This topic describes the FileOutput node.
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:
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:
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.
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:
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. |
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. |
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).
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 | ?? | ?? | ?? | ??? |