WRITE_FILE

The WRITE_FILE activity writes text to a file.  It can be used, for example, to:

• Write status or diagnostic information to a file
• As a simple, low-volume alternative to Transformation Maps, in some cases, to create simple transaction output files (for example comma-separated files).

 

Unless you specify otherwise, the activity will keep the target file open for the duration of the containing Processing Sequence, permitting repeated writes without the performance overhead of repeatedly opening and closing the file.  When the containing Processing Sequence ends, any remaining opened files are automatically closed.

You can have more than one file opened at a time, if you need to write to multiple files – you simply need to ensure that you specify the appropriate path and files name in the WRITEFILEPATH parameter of each WRITE_FILE activity instance.  (However, the operating environment may constrain the number of files you may have open at once.)

Variables substitution may be used in the text strings, permitting you to easily mix text with Processing Sequence variables values – or to create a line of comma-separated values to write.

You can refer to the EXAMPLE_WRITEFILE01 Processing Sequence for an example of using the WRITE_FILE activity.

INPUT Parameters:

WRITEFILEPATH: Required

This parameter specifies the path and file name of the file to be written.

If you write to the file more than once in the course of a Processing Sequence run, you must ensure that you pass the path and file name of the file in exactly the same form to ensure that an open file handle for the file is re-used for continued writes to the file.

WRITETEXT: Optional

When the value of the WRITEACTION parameter is *WRITE, this parameter specifies the text to be written to the file.

If the text is not provided, then the WRITE_FILE activity with a WRITEACTION parameter value of *WRITE will simply write a line terminator as specified by the WRITEOPTION parameter.

If provided, the text may contain embedded references to processing sequence variables (eg: &myvar) and/or built-in variables (eg: *tradingpartner) that will be replaced by the current variable values.  Support for indexed variable references (eg: &myvar(2) OR &myvar(&myindex) ) is provided.

For example, if you specify the string "&MYCOUNT files processed from &MYFOLDER(&MYINDEX) at *now_local", the variable and built-in variable references &MYCOUNT, &MYFOLDER(&MYINDEX) and *now_local will be replaced by the values of the variables that they represent.

In most cases, a reference to a processing sequence variable or built-in variable must be followed by a space (or certain special characters or the end of the string) in order for the reference to be correctly identified and substituted.

If two ampersands (&&) or two asterisks (**) appear together in the string, they are reduced to a single ampersand or asterisk and not considered for substitution.

WRITEACTION: Optional

This parameter specifies the type of WRITE_FILE action to perform.

The default value of *WRITE causes (a) the text specified by the WRITETEXT parameter, if any, to be written, and / or (b) the line terminator specified by the WRITEOPTION parameter to be written to the specified file.  The file is automatically opened in 'append' mode when necessary.  (This offers the most appropriate behavior should a failed Processing Sequence be restarted.)

An alternate value, *OPEN, allows you to control how and when the file is opened for writing.  You only need to specify *OPEN if you wish to specify *OVERWRITE in the WRITEOPTION parameter – when it is not used, the file is opened automatically, when required, in 'append' mode.  When you specify *OPEN for the WRITEACTION parameter, the file is opened, but no data is written (the value of the WRITETEXT parameter is not used).

A third value, *CLOSE, allows you to control when the file is closed.  You may need to use this after writing the file contents, if you wish to use the file in other Activities or Transformation Maps in the same Processing Sequence run.  When the containing Processing Sequence ends, any remaining opened files are automatically closed, so you only need to explicitly close a file if you need to use it for another purpose.  The values of the WRITETEXT, WRITEOPTION and WRITECCSID parameters are not used when you specify *CLOSE for the WRITEACTION parameter.

WRITEOPTION: Optional

This parameter specifies the option to be used when either *WRITE or *OPEN is specified for the WRITEACTION parameter.

For *WRITE, one of the following values controls whether a line terminator is written:

*CRLF: a carriage return/line feed pair is written after writing the text specified by the WRITETEXT parameter, if any.

*LFCR: a line feed/carriage return pair is written after writing the text specified by the WRITETEXT parameter, if any.

*CR: a carriage return is written after writing the text specified by the WRITETEXT parameter, if any.

*LF: a line feed is written after writing the text specified by the WRITETEXT parameter, if any.

*NL: a new line character is written after writing the text specified by the WRITETEXT parameter, if any.

*NOLINETERMINATOR (or blank): no line terminator is written.

NOTE: On Windows server platforms, all the line terminator options (*CRLF, *LFCR, *CR, *LF, *NL) result in a carriage return/line feed pair.  The distinct line terminator options are not supported.  You may still use *NOLINETERMINATOR to avoid any line terminator being written.

For *OPEN, one of the following values controls how the file is opened:

*APPEND: the file is opened in 'append' mode.  If the file does not exist it will be created.  If the files does exist it will be opened for write at the end of the existing file.  This is the default if this parameter is not specified on the WRITE_FILE activity that specifies *OPEN for the WRITEACTION parameter.  It is also the default if the file is not explicitly opened by means of a WRITE_FILE activity that specifies *OPEN for the WRITEACTION parameter.

*OVERWRITE: the file will be opened for write.  If the file does not exist it will be created.  If the files does exist the existing contents will be overwritten.

WRITECCSID: Optional

This parameter applies only on IBM i servers.  It allows you to specify the IBM i CCSID with which the output text file is created.

If the parameter value is blank or not specified, a default value of *DEFAULT causes the activity to use the default CCSID for the job in which the activity is executing.

Otherwise, you should specify the numeric CCSID value required.  For example, a value of 1208 means UTF-8.  Refer to IBM i documentation for a complete list and description of the available CCSIDs.

NOTE:  the assumed or explicit CCSID is applied only when the file is opened in the course of the WRITE_FILE activity and the specified output file does NOT already exist.  If the specified output file already exists and is being replaced or appended to by this activity, then its CCSID will not be changed.

OUTPUT Parameters:

There are no output parameters.