FileWrite node



The FileWrite plug-in icon


This page contains information on:

  • FileWrite node terminals
  • Using the FileWrite node
  • FileWrite node properties


  • 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".

    Action Message Controlled 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.

    Automated Mode

    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:

    1. The number of records written to file has exceed the "Maximum Number of Records" = integer (node property)
    2. The number of minutes that output file has been opened has exceed the "Maximum Open Time" = minutes (node property)
    3. The time of day is now "GMT Time of Day to Close File"= hhmm (node property)

    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.

    FileWrite node terminals

    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.


    Using the FileWrite node

    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:

    Open Output File 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.

    Close Output File action message

    [M]<FileAdapter>
    [M]      <Filename>'string'
    [M]           <Action>CLOSE</Action>
    [M]           <Type>OUTPUT</Type>
    [M]      </Filename>
    [M] </FileAdapter>

    Note: [M] is a mandatory element and [O] is an optional element.

    Exception Close Output File action message

    [M]<FileAdapter>
    [M]      <Filename>'*'
    [M]           <Action>EXCEPTIONCLOSE</Action>
    [M]           <Type>OUTPUT</Type>
    [M]      </Filename>
    [M] </FileAdapter>

    Note: [M] is a mandatory element and [O] is an optional element.

    Status messages

    Opened

    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>
             <Filename>string
                   <Status>OPENED</Status>
                   <Type>OUTPUT</Type>
                   <Attributes>
                        <Disposition>
                             <Status>string</Status>
                             <Normal>string</Normal>
                             <Conditional>string</Conditional>
                        </Disposition>
                        <RecordFormat>string</RecordFormat>
                        <RecordLength>integer</RecordLength>
                        <BlockSize>integer</BlockSize>
                        <Space>
                             <AllocationUnit>string</AllocationUnit>
                             <Primary>integer</Primary>
                             <Secondary>integer</Secondary>
                        </Space>
                        <Unit>string</Unit>
                        <DataClass>string</DataClass>
                        <ManagementClass>string</ManagementClass>
                        <StorageClass>string</StorageClass>
                   </Attributes>
                   <TimeFileOpened>timestamp</TimeFileOpened>
            </Filename>
    </FileAdapter>

    Closed

    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>
             <Filename>string
                   <Status>CLOSED</Status>
                   <Type>OUTPUT</Type>
                   <Attributes>
                        <Disposition>
                             <Status>string</Status>
                             <Normal>string</Normal>
                             <Conditional>string</Conditional>
                        </Disposition>
                        <RecordFormat>string</RecordFormat>
                        <RecordLength>integer</RecordLength>
                        <BlockSize>integer</BlockSize>
                        <Space>
                             <AllocationUnit>string</AllocationUnit>
                             <Primary>integer</Primary>
                             <Secondary>integer</Secondary>
                        </Space>
                        <Unit>string</Unit>
                        <DataClass>string</DataClass>
                        <ManagementClass>string</ManagementClass>
                        <StorageClass>string</StorageClass>
                   </Attributes>
                   <TimeFileOpened>timestamp</TimeFileOpened>
                   <TimeFileClosed>timestamp</TimeFileClosed>
                   <RecordsProcessed>integer</RecordsProcessed>
                   <RecordsTruncated>integer</RecordsTruncated>
            </Filename>
    </FileAdapter>

    Exception Messages

    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:

    Exception when the action message is invalid

    <FileAdapter>
                   <Exception>FileWrite</Exception>
                   <ErrorText>string</ErrorText>
                   <TimeException>timestamp</TimeException>
    </FileAdapter>

    Exception when the dynalloc function returns an error

    <FileAdapter>
             <Filename>'string'
                   <Exception>FileWrite</Exception>
                   <Function>dynalloc</Function>
                   <ErrorCode>integer</ErrorCode>
                   <InformationCode>string</InformationCode>
                   <TimeException>timestamp</TimeException>
              </Filename>
    </FileAdapter>

    Exception when system functions return errors

    <FileAdapter>
             <Filename>'string'
                   <Exception>FileWrite</Exception>
                   <Function>string</Function>
                   <ErrorNumber>integer</ErrorNumber>
                   <ErrorText>string</ErrorText>
                   <TimeException>timestamp</TimeException>
              </Filename>
    </FileAdapter>

    ExceptionClose

    <FileAdapter>
                   <Exception>FileWrite</Exception>
                   <ErrorText>
                   Closing all files on 'EXCEPTIONCLOSE' File Adapter XML control message
                   </ErrorText>
                   <TimeException>timestamp</TimeException>
    </FileAdapter>

    FileWrite node properties

    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.