Start of change
WebSphere Message Brokers
File: ac55160_.dita
Writer: Kate Hostler

Reference topic

This build: July 31, 2007 21:21:05

FileOutput node

This topic describes the FileOutput node.

Purpose

Use the FileOutput node to write messages to a file in the broker's file system. It can create a new file from a single message or replace an existing file's contents with a message. It can also append records to an existing file. The records can be created directly from messages, can be padded to a fixed length, or spearated from other records by a delimiter character.

The FileOutput node can be used for:

  • Simple file transfer with name controlled routing
  • Simple file transfer with content controlled routing and enrichment
  • File aggregation, for example, as input to another process
  • Multiple messages in a file

The FileOutput node writes messages to a file in the broker's file system. It can create a new file from a single message or replace an existing file's contents with a message.

The FileOutput node can be configured to replace an existing file, and move it to an archive subdirectory. If the specified directory does not exist, the broker creates it when it moves the first file. If the broker cannot create the directory, it throws an exception.

If you have several FileOutput node instances in your message flow, they may try to access the same file at the same time. Only one of the instances is permitted to access a file at any on time, so the other nodes wait until the first has finished. The order in which the FileOutput node instances access the file is undefined. If you need records to be appended to a file in a particular order, ensure that only one instance can access the file.

The FileOutput node's properties specify the path to the directory containing the resulting file and the file's name. The file name can contain only one wild card character, the asterisk (*). If the wildcard character is present, the FileOutput node will replace the wild card character with the current value of the Properties.WildcardMatch element. You can override either of these properties with values specified in the LocalEnvironment of the message you send to the FileOutput node. The FileOutput node does not replace wild cards in the file name specified in the LocalEnvironment. For example, if you specify LocalEnvironment.Destination.File.Name="*.txt", the output file will be named "*.txt", if your file system supports it. If the file system does not support your chosen file name, the FileOutput node throws a FileNotFound exception.

The FileOutput node is represented in the workbench by the following icon:

FileOutput node icon

Using this node in a message flow

The FileOutput node can be used in any message flow that needs to output messages in files. Look at the following sample to see how to use this node:
  • FileOutput sample
<<LINK TO FileOutput SAMPLE>>

Alt.txt if one sample: Look at the nnnnnnnnnnnnnnnnnn sample to see how to use this node.

You can view samples only when you use the information center that is integrated with the Message Brokers Toolkit.

Configuring the FileOutput node

When you have put an instance of the FileOutput node into a message flow, you can configure it. The properties of the node are displayed in the Properties view. All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.

To configure the FileOutput node:

  1. Optional: On the Description tab, enter a short description, a long description, or both. You can also rename the node on this tab.
  2. On the Basic tab, enter the details of the files created or modified by the FileOutput node.
    1. In Directory, specify the directory in which the FileOutput node will place its files. You can override this value in the message your flow sends to the FileOutput node's In terminal. Specify the directory as an absolute path, for example, on Windows® C:\fileoutput, or on UNIX® var/fileoutput. Any trailing path separator, for example, "/" or "\" is ignored.
    2. In File name, specify the name of the file which the FileOutput node will create or replace. The file name should be valid on the system which hosts the broker to which the message flow is deployed. You can override this value in the message your flow sends to the FileOutput node's In terminal. If you deploy the flow to a Windows server, the file name is treated as identifying a file irrespective of case, whereas if you deploy the flow to a UNIX server, two file names that differ only in case are treated as identifying two different files. If the file name contains a wild card character (*), the FileOutput node replaces it with the current value of Properties.WildcardMatch, or nothing if Properties.WildcardMatch is null or missing. If you leave the File name property empty, you must set the Name element in the request structure (by default LocalEnvironment.Destination.File) that your flow passes to the FileOutput node's In terminal.
  3. On the Request tab, specify the location of the data to be written, and any control information overriding the Basic panel's Directory and File name properties.
    1. In Request directory property location, specify the request structure's location as an Xpath or ESQL expression. If you do not specify a request location, the node uses the default value defined in its properties in LocalEnvironment.Destination.File. If you specify a location, any values in the structure override the corresponding node property. If the structure is empty or missing, the node uses the values defined in its properties. The FileOutput node supports exactly one destination; it does not support destination lists with several elements. The table below describes the elements that can appear in the request structure. Note that Windows file systems treat files with the same name except for differences of upper and lower case as the same file. UNIX, Linux, HFS, and zFS file systems treat such files as different files.
      Element name Element data type Element attributes
      Directory Character Absolute directory path. Use the path separator character ('/' or '\') according to the operating system on which the flow is executing. Trailing path separator characters are ignored. On Windows, start with the drive letter prefix , for example, C:.
      Name Character File name and extension.
    2. In Request file name property location, specify the file name property location as an Xpath or ESQL expression. If you do not specify a request location, the node uses the default value defined in its properties in LocalEnvironment.Destination.File. If you specify a location, any values in the structure override the corresponding node property. If the structure is empty or missing, the node uses the values defined in its properties. The FileOutput node supports exactly one destination; it does not support destination lists with several elements. The table below describes the elements that can appear in the request structure.
      Element name Element data type Element attributes
      Directory Character Absolute directory path. Use the path separator character ('/' or '\') according to the operating system on which the flow is executing. Trailing path separator characters are ignored. On Windows, start with the drive letter prefix , for example, C:.
      Name Character File name and extension.
    3. In Data location, specify the input data location. This is an Xpath or ESQL expression which locates the message element whose contents will form the record written to the output file. The default value is the entire message body specified by InputRoot.Body.
    4. In Request isFirst property location, specify the path to the flag which indicates whether the current record should be the first in the file. The default is $LocalEnvironment/Destination/File/IsFirst.
    5. In Request isLast property location, specify the path to the flag which indicates whether the current record should be the last in the file. The default is $LocalEnvironment/Destination/File/IsLast.
  4. Use the Records and Elements tab to specify how the FileOutput node handles the message by specifying the properties below:
    • In Output file action, select the action which the node is to take with the output record or file:
      • Select Replace Existing File (or Create if File does not Exist) if you want to replace a file that has the specified name in the output directory.
      • Select Create File (Fail if File Exists) if you want to create a new file with the specified name in the output directory. The node generates an exception if the output directory already contains a file of the specified name.
      • Select Archive and Replace Existing File (or Create if File does not Exist) if you want to move a file of the specified name in the output directory to the archive subdirectory, and then create a new file in the output directory. The archive subdirectory must be named 'mqsiarchive', be writeable by the broker, and be part of the same file system as the output directory.
      • Select Time Stamp, Archive and Replace Existing File (or Create if File does not Exist) if you want to add a time stamp to the file that is to be moved to the archive subdirectory. The timestamp is a string of decimal digits in the form yyyyMMdd_hhmmss_mmmmmm_ where:
        • yyyy is the year
        • MM is the month
        • dd is the day
        • hh is the hour in 24-hour form
        • mm is the minutes
        • ss is the seconds
        • mmmmmm is the microseconds
        and the separators are underscores. The timestamp shows the time at which the node started processing the file or record in Greenwich Mean Time; it is not the time at which the older file being moved to the archive subdirectory is processed. The use of a timestamp ensures that files in the mqsiarchive subdirectory have unique names.
      • Select Append Record to File (or Create if File does not Exist) to add the record to the end of the file with the specified name.
    • In Record definition, choose from:
      • Whole File and the file will be created or replaced by the message bit stream.
      • As Is and the message bit stream will be appended to the file.
      • Fixed Length and, if the message is shorter than the value specified in Length, the node creates the record by padding it to the right with a selected character, and append the resulting record to the file. If the record is longer than the value specified in Length, the node generates an exception.
      • Delimited and the node separates each record with a delimiter which is specified in the Delimiter property.
    • Select Replace duplicate archive files if you want to overwrite existing archive files with the same name as the successfully processed input file. If you do not set this option, the node will throw an exception when it tries to move a successfully processed file with the same name into the archive subdirectory.
    • If you specified Fixed Length in Record definition, use Length to specify the required length of the output record. This must be a value between 1 and 100 MB. The default is 80.
    • If you specified Fixed Length in Record definition, use Padding byte to specify the character that is to be used as the padding character. Specify this as 2 hexadecimal digits. Records that are shorter than the value specified in Fixed Length are padded to the right with this character. The default value is X'20'.
    • If you specified Delimited in Record definition, use Delimiter to specify the delimiter to be used. It is either the value that you specify in Custom delimiter or the default value. On UNIX systems, the default is a line feed character (<LF>, X'0A'). On Windows systems, the default is a carriage return character followed by a line feed character (<CR><LF>, X'0D0A').
    • In Custom delimiter, specify the delimiter character or characters to be used when the default value is not to be used. Specify this as an even-numbered string of hexadecimal digits. The default is X'0A' and the maximum length of the string is 16 bytes.
    • If you specified Delimited in Record definition, use Delimiter type to specify the type of delimiter. Permitted values are:
      • Postfix, which is the default. This means that the record is written directly to the file and followed directly by your chosen delimiter. In this way, each record in the file, including the final one, is followed by a delimiter.
      • Infix. If you select this, your chosen delimiter is written to the file and followed directly by the record. In this way, each record in the file, except the final one, is followed by a delimiter.
  5. The broker provides validation based on the message dictionaries for predefined messages. For more information about validation, see Validating messages. For information on how to fill in this tab, see Validation tab properties.
  6. On the FTP tab, select the FTP check box if you want the node to transfer files to an FTP server using the File Transfer Protocol properties:
    • In Server identification, specify the name of the configurable service in which the FTP server connection is configured, or the IP address of remote FTP server if no such resource.
    • In Client user identification, specify the name of the user identification used to access the FTP server. If left blank, the system uses the identification defined in the server identification configurable service.
    • Specify a Client user password. If left blank, the system uses the password associated with the client user identification.
    • In Server directory, specify the directory in the FTP server.
    • Specify the Transfer mode. Select Binary or Text.
    • Select the Retain after transfer check box if you want to retain this file after the file transfer process has completed.

Terminals and properties

The FileOutput node terminals are described in the following table.

Terminal Description
In The input terminal that accepts a message for processing by the node.
Failure The output terminal to which the message is routed if a failure is detected when the message is propagated
Out The output terminal to which the message is routed if it has been successfully propagated. The message is sent to this terminal unchanged but with status information added.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the bar file to deploy it).

The FileOutput node Description properties are described in the following table:
Property M C Default Description
Node name No No The node type The name of the node.
Short Description No No   A brief description of the node.
Long Description No No   Text that describes the purpose of the node in the message flow.

The FileOutput node Basic properties are described in the following table:

Property M C Default Description
Directory No Yes None The directory where the node will place its files.
File name No Yes None A string containing the name of the output file, containing at most one wild card character (*).

The FileOutput node Request properties are described in the following table:

Property M C Default Description
Request directory property location Yes Yes LocalEnvironment.Destination.File The request structure's location as an Xpath or ESQL expression
Request file name property location Yes Yes LocalEnvironment.Destination.File The file name property location as an Xpath or ESQL expression
Data location Yes No $Body The Xpath or ESQL expression that locates the message element whose contents will form the record written to the output file.
Request IsFirst property location Yes No $LocalEnvironment/Destination/File/IsFirst The path to the flag which indicates whether the current record should be the first in the file.
Request IsLast property location Yes No $LocalEnvironment/Destination/File/IsLast The path to the flag which indicates whether the current record should be the first in the file.

The FileOutput node Records and Elements properties are described in the following table:

Property M C Default Description
Record definition Yes No Whole File This property controls how the message is to be used to create a record.
Replace duplicate archive file Yes No ?? This property controls whether existing archive files with the same name as the successfully processed input file are overwritten.
Length Yes No 80 The required length of the output record.
Padding byte Yes No X'20' The hexadecimal byte to be used to pad short messages when Fixed Length is specified in Record definition.
Delimiter Yes No <LF>, X'0A' (UNIX systems), <CR><LF>, X'0D0A' (Windows systems) The delimiter value to be used when Delimited is specified in Record definition.
Custom delimiter No No X'0A' The delimiter value to be used when Delimited is specified in Record definition.
Delimiter type Yes No Postfix The delimiter type to be used when Delimited is specified in Record definition.

The FileOutput node Validation properties are described in the following table:

Property M C Default Description
Validate Yes Yes None This property controls whether validation takes place. Valid values are None, Content and Value, or Content.
Failure action Yes No Exception This property controls what happens if validation fails. You can set this property only if you set Validate to Content or Content and Value. Valid values are User Trace, Local Error Log, Exception, and Exception List.

The FileOutput node FTP properties are described in the following table:

Property M C Default Description
FTP No No Cleared??? This property defines whether the node uses the File Transfer Protocol (FTP) properties listed below and transfers files to an FTP server.
Server identification Yes Yes None The name of the configurable service in which the FTP server connection is configured, or the IP address of remote FTP server if no such resource.
Client user identification No Yes None The name of the user identification used to access the FTP server. If left blank, the system uses the identification defined in the server identification configurable service.
Client user password No Yes None Password for the client user identification. If left blank, the system uses the password associated with the client user identification.
Server directory No Yes "." The directory in the FTP server.
Transfer mode No Yes Binary The mode for transfer of files. Select Binary or Text.
Retain after transfer ?? ?? ?? ???
Related reference
FileInput node
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:21:06

ac55160_.dita This topic's URL is:
End of change