The FileWrite plug-in icon
The File Write plug-in node
receives data messages on the "in" terminal and writes them as records on
an output file (QSAM dataset in z/OS). Status messages are propagated to the
"status" terminal when an output file is opened or closed.
If an error condition is detected, an exception message is propagated to
the "failure" terminal (if the "failure" terminal is not wired then a user
exception is thrown to terminate the processing). After an exception is
detected the output file is closed (An exception message is propagated
instead of a "closed output file" status message).
Copies of the action and status messages are maintained in the
Environment tree of the message flow.
The File Write plug-in
node has two modes of operation: The first one is called "Action Message
Controlled Mode" and the second one is called "Automated Mode".
The File Write plug-in node opens and closes the output file when it receives a valid (OPEN, CLOSE and EXCEPTIONCLOSE) action message on the "action" terminal.
The File Write plug-in node properties control the file name, the attributes and when to close the output file. A new file is opened when a data message arrives on the "in" terminal and there is not an output file opened.
The File Write plug-in node has the following algorithm to generate non-duplicate output file names:
The "Filename" node property specifies a file name stem used to prefix any generated file name. Each time a new output file is required a unique suffix is appended to the file name stem. This suffix is formed by the year and Julian day (Dyyddd) followed by the time of day (Thhmmss) and a sequence number (Snnnn). For example, if the node property "Filename" = MY.FILE then the generated file name is MY.FILE.Dyyddd.Thhmmss.Snnnn.
The sequence number is initialised in zeros (0000) when a new file name is generated. This number is increased if a duplicate file name is found and the open is retried within the same date and time. If a sequence of 9999 is exceeded then a new name is generated again getting a different date and time.
The output file is closed when one of the following conditions is met:
When
the File Write plug-in node is operating in "Automated Mode" and an action
message is received on the "action" terminal an error exception is thrown.
Action messages are not allowed. The Exception Close action message is
allowed to close the output file and then throw an exception to
terminate the processing.
action |
Input terminal that receives action control messages to open and close the file. |
in |
Input terminal that receives data messages to be written as records in the output file. |
failure |
Output terminal to which an exception message is propagated in case that the node detects an error exception. |
status |
Output terminal that status messages are propagated when the file is opened or closed. |
When this node is in "controlled message" mode, it opens the output file when an open action message is received on the "action" terminal. When the node property Mulithreaded File = FALSE is specified, the node will accept one open file message per active thread. When the node property Multithreaded File = TRUE is specified, the node will accept only one open file message (this message can be originated by any thread). The following are the formats of this action message:
[M]<FileAdapter>
[M]
<Filename>string
[M]
<Action>OPEN</Action>
[M]
<Type>OUTPUT</Type>
[M]
<Attributes>
[M]
<Disposition>
[M]
<Status>string</Status>
[O]
<Normal>string</Normal>
[O]
<Conditional>string</Conditional>
[M]
</Disposition>
[O*]
<RecordFormat>string</RecordFormat>
[O*]
<RecordLength>integer</RecordLength>
[O*]
<BlockSize>integer</BlockSize>
[M]
<Space>
[O*]
<AllocationUnit>string</AllocationUnit>
[O*]
<Primary>integer</Primary>
[O*]
<Secondary>integer</Secondary>
[M]
</Space>
[O*]
<DataClass>string</DataClass>
[O]
<ManagementClass>string</ManagementClass>
[O]
<StorageClass>string</StorageClass>
[O]
<Unit>string</Unit>
[M]
</Attributes>
[M]
</Filename>
[M] </FileAdapter>
Note:
[M] is a mandatory element, [O] is an optional element and [O*] is that at least some of these properties must be specified.
Note: [M] is a mandatory element and [O] is an optional element.
Note: [M] is a mandatory element and [O] is an optional element.
If the open file is successful an status message is propagated to the "status" terminal. The following is the format of the status message:
<FileAdapter>If the close file is successful an status message is propagated to the status terminal. The following is the format of the status message:
<FileAdapter>An exception message is propagated to the failure terminal when an error exception is detected by the File Write plug-in node. The following is the format of the exception messages:
The following properties are on the Default tab
Property |
Default |
Description |
Generate debug data |
None |
This property can have the values of "None", "Performance" or "Full". The "Performance" option generates data to monitor the duration of key activities during the File Write process. The "Full" option generates debugging and trace information. |
Trace Filename |
Path and name of the trace file. If no trace file is specified then the debugging information is sent to the broker's stdout. |
|
Automated Mode |
Unchecked |
To indicate if the node is in "action message controlled mode" or "automated mode". |
Multithreaded File |
Unchecked |
To indicate if the node is opening a single output file that is shared by all the threads (Multithread = Checked) or it opens an output file per thread (Multithreaded File = Unchecked). When the node is operating in automated mode, the Multithreaded File = Unchecked is not supported. |
The following properties are on the AutomatedMode tab
Property |
Default |
Description |
Timer Expiration (seconds) |
0 |
Time interval used to check the closing conditions of the output file. |
Maximum Number of Records |
0 |
The maximum number of records to be written to the output file. |
Maximum Open Time (minutes) |
0 |
Maximum number of minutes that an output file is kept open. |
GMT Time of Day to Close File (hhss) |
Time of day (24 hour clock) to close the output file. |
|
Filename |
Output file name prefix (stem) to be used when generating unique files. The format of the generated file names is STEM.Dyyddd.Thhmmss.S0000 |
|
Disposition Status |
NEW |
Initial status of the file (NEW or MOD). |
Disposition Normal |
CATLG |
Disposition of the file after normal termination (KEEP, CATLG, or DELETE) |
Disposition Conditional |
CATLG |
Disposition of the file after an abnormal termination (KEEP, CATLG, DELETE or UNCATLG) |
Record Format |
none |
none, F = fixed, V = variable, FB = fixed blocked, and VB = variable blocked |
Record Length (bytes) |
Maximum record size to be written to the file. |
|
Block Size (bytes) |
Maximum block size in bytes. |
|
Space Allocation Unit |
none |
Indicate if space is allocated in TRK (tracks) or CYL (cylinders). |
Space Primary Allocation |
Number of TRKs or CYLs to be initially allocated to the file. |
|
Space Secondary Allocation |
Number of TRKs or CYLs to be allocated once the previous space allocation is exhausted. The secondary space allocation is used up to 15 times before generating a file full exception. |
|
Unit |
The name of the type of storage device used for the file (Disk or Tape). |
|
SMS Data Class |
The name data class to be used to create the file. |
|
SMS Data Class |
The name data class used to create the file. |
|
SMS Management Class |
The name management class used to create the file. |
|
SMS Storage Class |
The name storage class to be used to create the file. |