Write local file

Creates a file on the Clarive server from text you type into the op. The text goes through stash expansion before anything is written, so the file can carry values the job worked out earlier, such as a generated SQL statement or a properties file for the environment being deployed.

For a file on a target node, use Write remote file, which performs this same write into a temporary location and then transfers it. To change a file that already exists instead of creating one, use Replace Strings.

Fields

Path

Full path of the file to create, including the file name. Missing parent directories are created for you, as deep as needed.

The value expands ${var} placeholders, which is how most rules build it: ${job_dir}/${project}/deploy.sql. Write the path as an absolute one or anchor it on ${job_dir}. A bare relative path is resolved against whatever directory the job process happens to be sitting in, and that is not something to depend on.

A placeholder that does not resolve is left in the text exactly as you typed it rather than becoming empty, so a misspelled variable creates a directory literally named ${projct} and the job reports success.

Leaving this blank does not stop you saving the rule. The op fails at run time with Could not open file for writing (No such file or directory) and an empty path in the message.

An existing file is truncated and replaced. There is no append mode and no backup copy.

File Encoding

Character encoding used when the bytes hit the disk. Defaults to utf-8. Common alternatives are latin1 and cp1252, or cp037 for mainframe targets.

Clearing the field writes the text through with no encoding layer at all, which is what you want when the contents are already in the exact bytes you need. Clear Content Encoding at the same time: a blank File Encoding with a value still sitting in Content Encoding makes the op fail with Unknown encoding '' before it opens anything.

Content Encoding

Describes the text you typed, so the op knows what it is converting from. Defaults to utf-8.

Conversion happens only when this holds a value and that value differs from File Encoding, and it happens before templating, so anything a template produces is not converted. Setting the two fields to different values converts the text once up front and then the output layer converts again on write, so accented characters can come out twice-converted. Leave both at utf-8 unless the consumer of the file demands something else, and open the result to check.

Line Endings

Choice	Effect
original	write the text exactly as it is
LF (Unix)	every CRLF pair becomes a single LF
CRLF (Windows)	every LF not already preceded by CR becomes CRLF

CRLF is safe to apply to mixed content: lines that already end in CRLF are left alone. A lone CR with no LF after it is never touched by either choice.

The rule editor stores what you type with Unix line endings. A Windows batch file or a mainframe JCL member that ends up with bare LF fails in confusing ways on the target, so set CRLF (Windows) for those.

Log Body

Choice	Effect
Don't print body to log	the log records the path only
Print body in log	the full contents are attached to the log entry, viewable in the monitor

Default is not to print. Turn it on while you are building the rule, then turn it back off: the contents are stored with the job log, so passwords or connection strings typed into Contents end up readable by anyone who can open that job.

Template Use

Choice	Effect
No Template	the contents are written as they stand
Template Toolkit	the contents are run through the template engine first

Independent of this setting, ${var} placeholders are always expanded. Template Toolkit adds the [% %] directive syntax on top, for loops and conditionals that plain substitution cannot do. A template error stops the job and the message names what failed.

Template Var

Appears only once Template Use is set to Template Toolkit.

Names a single stash variable holding a hash; its keys become the template variables, so [% hostname %] reads the hostname key inside it. Leave it blank and the whole stash is exposed, which is the usual choice.

The name has to be a top-level stash key. Dots are not followed here, so topic.data looks for a key literally called topic.data and finds nothing. A name that is not in the stash gives a template with no variables at all, and every [% %] reference renders as empty.

Contents

The body of the file. On most browsers this is a code editor with syntax highlighting; on Internet Explorer it falls back to a plain text area.

Both ${var} and ${nested.path} are replaced here. To write a literal ${something} into the file, double the first character: $${something}.

What the job log shows

One line per run, reading File content written: followed by the path in single quotes. With Log Body set to Print body in log, the final contents are attached to that entry, after substitution, after encoding conversion, after templating and after the line-ending rewrite, which makes it the fastest way to see what the expansion actually produced.

Failure and rollback

Anything that stops the write stops the job: a path that cannot be created, a read-only directory, a full disk, a template error. The op has no error handling of its own, so use the op's error handling properties, or wrap it in TRY statement, when you want the job to carry on.

The op takes no backup and has no rollback behaviour. On a rollback pass it runs again and writes the same file, unless you clear Run Rollback in the op properties.

Set a Return Key on the op's options (see Rule Palette) and the path that was written lands in the stash under that name, ready for the op that consumes the file. Without one, the path is discarded.

Combining with other ops

Write the script, then run it with Run command or local script. Point the command at the same ${job_dir} path you wrote to.

To get the file onto a node, either follow with Ship File Remotely, or skip this op and use Write remote file, which does both in one step.

To keep a copy of the file with the job for auditing, follow with Publish local file to log. To clear it away afterwards, use Delete Local File.

When the contents differ per environment, wrap the op in IF var condition THEN, or build the differences into the stash with SET VAR beforehand.

Examples

A SQL file assembled from job variables, written into the job directory so a later op can feed it to a client.

Path             ${job_dir}/deploy.sql
File Encoding    utf-8
Content Encoding utf-8
Line Endings     LF (Unix)
Log Body         Print body in log
Template Use     No Template
Contents         select count(*) from ${schema_name}.foo_table;

A Windows batch file. The line endings matter more than anything else here.

Path             ${job_dir}/bar/cleanup.bat
Line Endings     CRLF (Windows)
Template Use     No Template
Contents         @ECHO OFF
                 del /q "${deploy_path}\*.log"

A properties file built with a loop over a list in the stash.

Path             ${job_dir}/myapp/app.properties
Template Use     Template Toolkit
Template Var     (blank)
Contents         app.env=${env}
                 [% FOREACH node IN cluster_nodes %]
                 node.[% loop.index %]=[% node %]
                 [% END %]