FileRead node



The FileRead plug-in icon


This page contains information on:

  • FileRead node terminals
  • Using the FileRead node
  • FileRead node properties



  • The File Read plug-in reads records from an input sequential file (QSAM dataset in z/OS) and propagates each record as a BLOB message to the "out" terminal. The input file process is triggered when an "open input file" action message arrives on the "action" terminal.

    The File Read plug-in validates the action message, opens the required input file (an "opened input file" status message is propagated to the "status" terminal), reads records from the file and for each record it propagates a data message to the "out" terminal. When the end of file is detected, the file is closed and the process is terminated (a "closed input file" status message is propagated to the "status" terminal).

    If an error condition is detected, an exception message is propagated to the "failure" terminal (if the "failure" terminal is not wired then an user exception is thrown to terminate the processing). After an exception is detected the input file is closed (An exception message is propagated instead of a "closed input file" status message).


    Copies of action and status messages are maintained in the Environment tree of the message flow.

    FileRead node terminals

    action

    Input terminal receives the action control messages to open and to close the file.

    failure

    Output terminal to which an exception message is propagated in case that the node detects an error exception.

    out

    Output terminal that data messages are propagated with the contents of the records read from the input file.

    status

    Output terminal that status messages are propagated when the file is opened or closed.

    Using the FileRead node

    When this node receives the open file action message on the "action" terminal, the file is opened and records are read until the end of file is detected then the file is closed.

    Open file action message

    The following is the format of this action message:

    [M]<FileAdapter>
    [M]      <Filename>'string'
    [M]           <Action>OPEN</Action>
    [M]           <Type>INPUT</Type>
    [M]           <Attributes>
    [M]                <Disposition>
    [M]                     <Status>string</Status>
    [O]                     <Normal>string</Normal>
    [O]                     <Conditional>string</Conditional>
    [M]                </Disposition>
    [M]           </Attributes>
    [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>INPUT</Type>
                   <Attributes>
                        <Disposition>
                             <Status>string</Status>
                             <Normal>string</Normal>
                             <Conditional>string</Conditional>
                        </Disposition>
                        <RecordFormat>string</RecordFormat>
                        <RecordLength>integer</RecordLength>
                        <BlockSize>integer</BlockSize>
                   </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>INPUT</Type>
                   <Attributes>
                        <Disposition>
                             <Status>string</Status>
                             <Normal>string</Normal>
                             <Conditional>string</Conditional>
                        </Disposition>
                        <RecordFormat>string</RecordFormat>
                        <RecordLength>integer</RecordLength>
                        <BlockSize>integer</BlockSize>
                   </Attributes>
                   <TimeFileOpened>timestamp</TimeFileOpened>
                   <TimeFileClosed>timestamp</TimeFileClosed>
                   <RecordsProcessed>integer</RecordsProcessed>
            </Filename>
    </FileAdapter>

    Exception messages

    An exception message is propagated to the "failure" terminal when an error exception is detected by the File Read plug-in node. The following is the format of the exception messages:

    Exception when the action message is invalid

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

    Exception when the dynalloc function returns an error

    <FileAdapter>
             <Filename>'string'
                   <Exception>FileRead</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>FileRead</Exception>
                   <Function>string</Function>
                   <ErrorNumber>integer</ErrorNumber>
                   <ErrorText>string</ErrorText>
                   <TimeException>timestamp</TimeException>
              </Filename>
    </FileAdapter>

    FileRead node properties

    All 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 Read 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.

    Input data encoding 785 This value represents the encoding of the numeric fields in the input file. This is a numeric value that describes the encoding of integers, decimal and floating point fields. Refer to the WebSphere MQ documentation for more information.
    Input data CCSID 500 This is the coded character set identifier (CCSID) for the text data in the input file.
    Add MQMD to data message Unchecked This property indicates if the data messages with the records from the input file require an MQMD header or not. When a message flow is reading messages from an input file and writing them onto an output file, it is STRONGLY recommended to "uncheck" this property to make the process more efficient in the use of memory.