FileInput node

Use the FileInput node to process messages that are read from files.

The FileInput node is available in the following operation modes:

Developer
Application Integration Suite
Standard
Advanced
Express
Scale
Adapter

For more information, see Operation modes.

This topic contains the following sections:

Purpose

One or more messages can be read from a single file, and each message is propagated as a separate flow transaction. The part of a file that generates one message flow transaction is called a record. A file can be a single record, or a series of records. Properties on the node specify how the FileInput node determines the records in a file.

The FileInput node is contained in the File drawer of the palette, and is represented in the IBM® Integration Toolkit by the following icon:

FileInput node icon

Message structure

The FileInput node handles messages in the following message domains:

DFDL
XMLNSC
DataObject
JSON
BLOB
MIME
MRM
JMSMap
JMSStream
XMLNS

When the FileInput node propagates a message, it stores information about it in the LocalEnvironment.File message tree. If the input file is empty, an empty message is propagated (assuming that it is valid). The following table lists the LocalEnvironment.File message tree structure. The elements contain data about the current record.

Element Name	Element Data Type	Description
Directory	CHARACTER	Absolute directory path of the input directory in the form used by the file system of the integration node. For example, on Windows systems, this starts with the drive letter prefix (such as C:).
Name	CHARACTER	File name and extension.
LastModified	TIMESTAMP	Date and time the file was last modified.
TimeStamp	CHARACTER	Date and time, in the Coordinated Universal Time (UTC) zone, the input node started processing the file as a character string. This data is the string used to create archive and backout file names if a timestamp is included.
The following elements contain data about the current record:
Offset	INTEGER	The start of the record within the file. The first record starts at offset 0. When Offset is part of the End of Data message tree, this value is the length of the input file.
Record	INTEGER	The number of the record within the file. The first record is record number 1. When Record is part of the End of Data message tree, this value is the number of records.
Delimiter	CHARACTER	The characters used to separate this record from the preceding record, if Delimited is specified in Record detection. The first record has a null delimiter. When Delimiter is part of the End of Data message tree, this value is the delimiter that follows the last record, if any.
IsEmpty	BOOLEAN	Whether the record that is propagated by the message flow is empty. IsEmpty is set to TRUE if the current record is empty. When IsEmpty is part of the End of Data message tree, this property is always set to TRUE.

Using this node in a message flow

The FileInput node can be used in any message flow that must accept messages in files.

If you configure a File node to use FTP, your network might need it to connect to an FTP proxy server, instead of directly to the remote FTP server. How you configure the File nodes to use an FTP proxy depends on how that proxy handles requests. For some FTP proxies, you must encode the target FTP server information in the logon credentials that you create with the mqsisetdbparms command. For example, some FTP proxies support the following values:

Username: FtpTargetHostUsername@ProxyUserName@TargetFtpHostname 
Password: TargetFtpUserPassword@ProxyUserPassword

Other proxies might require a different encoding, or might require external configuration, or you might not be able to use them with the File nodes.

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

Terminals and properties

The FileInput node terminals are described in the following table.

Terminal	Description
Failure	The output terminal to which a message is routed if an error occurs before a message is propagated to the Out terminal. Messages propagated to this terminal are not validated, even if you have specified, using the Validate property, that validation is to take place.
Out	The output terminal to which a message is routed if it has been successfully extracted from the input file. If no errors occur within the input node, a message received from an external resource is always sent to the Out terminal first.
End of Data	The output terminal to which the End of Data message is routed after all the messages in a file have been processed. The End of Data message flow transaction is initiated only if this terminal is attached.
Catch	The output terminal to which the message is routed if an exception is thrown downstream and caught by this node. Exceptions are caught only if this terminal is attached.

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).

Description properties:

Property	M	C	Default	Description
Node name	No	No	FileInput	The name of the node.
Short description	No	No	None	A brief description of the node.
Long description	No	No	None	Text that describes the purpose of the node in the message flow.

Basic properties:

Property	M	C	Default	Description	mqsiapplybaroverride command property
Input directory	Yes	Yes	None	The path of the directory from which input files are processed. The directory must be in a file system to which the integration node has access. If the input directory does not exist, no files are processed. The FileInput node checks that the input directory exists at intervals that are defined by the Scan delay property. The input directory must exist, even if you are processing files over FTP, FTPS, or SFTP. Specify the directory as either an absolute or a relative directory path. If the directory path is relative, it is based on the directory specified in the environment variable MQSI_FILENODES_ROOT_DIRECTORY. An example on Windows systems is C:\fileinput. An example on UNIX systems is /var/fileinput. On Windows, if you are specifying a shared directory that is mapped to your local computer, specify the share name instead of the letter that represents the drive; for example \\myshare\mydirectory. The FileInput node creates an mqsitransitin subdirectory in the specified input directory. The mqsitransitin subdirectory holds and locks input files while they are being processed. If an integration server that processes files in this input directory is removed, check the mqsitransitin subdirectory for partially processed or unprocessed files. Move any such files back into the input directory (and remove the integration server UUID prefix from the file names) so that they can be processed by a different integration server.	inputDirectory
Include local subdirectories	Yes	Yes	False	Determines whether all subdirectories under the specified input directory must also be searched for files to process. If you select this property and the Remote Transfer property, only the top-level directory that you have specified on the remote system is searched for files.	recursiveDirectories
File name or pattern	Yes	Yes	*	A file name or string containing optional wildcard characters (* or ?) or a regular expression that identifies the file or files to process from the input directory. If you specify a regular expression, you must enclose it in parentheses.	filenamePattern
File exclusion pattern	No	Yes	None	A simple string containing optional wildcard characters (* and ?) that identifies files to exclude from processing.	excludePattern
Action on successful processing	Yes	No	Delete	The action the node takes on the file after successfully processing the contents. Valid options are: Move to Archive Subdirectory Add Time Stamp and Move to Archive Subdirectory Delete
Replace duplicate archive files	Yes	No	Cleared	This property controls whether the node replaces existing archive files with the same name as the input file. It applies only when Action on successful processing is not Delete.

The FileInput node Input Message Parsing properties are described in the following table:

Property	M	C	Default	Description
Message domain	No	No	BLOB	The domain that is used to parse the message. If the field is blank then the default is BLOB.
Message model	No	No	Cleared	The name or location of the message model schema file in which the message is defined. When you click Browse, you see a list of available message model schema files for the selected Message domain.
Message	No	No	Cleared	The name or location of a global element that models an entire document of data, and is contained in your message model schema file. This list is populated with all available messages that are defined in the Message model that you have selected.
Physical format	No	No	Cleared	The name of the physical format of the message. If you are using the MRM or IDOC parser, select the physical format of the incoming message from the list. This list includes all the physical formats that you have defined for the selected message model. If you set the Message domain property to DataObject, you can set this property to XML or SAP ALE IDoc. Set this property to SAP ALE IDoc when you have to parse a bit stream from an external source and generate a message tree.
Message coded character set ID	Yes	No	Broker System Default	The ID of the coded character set used to interpret bytes of the file being read. mqsiapplybaroverride command property is messageCodedCharSetIdProperty.
Message encoding	Yes	No	Integration node System Determined	The encoding scheme for numbers and large characters used to interpret bytes of the file being read. Valid values are Integration node System Determined or a numeric encoding value. For more information about encoding, see Data conversion. mqsiapplybaroverride command property is messageEncodingProperty.

Parser Options properties:

Property	M	C	Default	Description
Parse timing	No	No	On Demand	This property controls when an input message is parsed. Valid values are: On Demand Immediate Complete For a full description of this property, see Parsing on demand.
Build tree using XML schema data types	No	No	Cleared	This property controls whether the syntax elements in the message tree have data types taken from the XML schema.
Use XMLNSC compact parser for XMLNS domain	No	No	Cleared	Specifies whether the XMLNSC Compact Parser is used for messages in the XMLNS Domain. If you set this property, the message data is displayed under XMLNSC in nodes that are connected to the output terminal when either of the following items is XMLNS: The input MQRFH2 header. The Input Message Parsing property, Message Domain.
Retain mixed content	No	No	Cleared	This property controls whether the XMLNSC parser creates elements in the message tree for mixed text in an input message. If you select the check box, elements are created for mixed text. If you clear the check box, mixed text is ignored and no elements are created.
Retain comments	No	No	Cleared	Specifies whether the XMLNSC parser creates elements in the message tree for comments in an input message. If you select the check box, elements are created for comments. If you clear the check box, comments are ignored and no elements are created.
Retain processing instructions	No	No	Cleared	This property controls whether the XMLNSC parser creates elements in the message tree for processing instructions in an input message. If you select the check box, elements are created for processing instructions. If you clear the check box, processing instructions are ignored and no elements are created.
Opaque elements	No	No	Blank	This property is used to specify a list of elements in the input message that are to be opaquely parsed by the XMLNSC parser. Opaque parsing is performed only if validation is not enabled (that is, if Validate is None); entries that are specified in Opaque Elements are ignored if validation is enabled.

Polling property:

Property	M	C	Default	Description	mqsiapplybaroverride command property
Polling interval (seconds)	Yes	Yes	5	The polling interval in seconds.	waitInterval

Retry properties:

Property	M	C	Default	Description	mqsiapplybaroverride command property
Retry mechanism	Yes	No	Failure	How the node handles a flow failure. Valid options are: Failure Short retry Short and long retry
Retry threshold	Yes	Yes	0	The number of times to try the flow transaction again when the Retry mechanism property value is Short retry.	retryThreshold
Short retry interval	No	Yes	0	The interval, in seconds, between each retry if Retry threshold property is not zero.	shortRetryInterval
Long retry interval	No	Yes	300	The interval between retries, if the Retry mechanism property is Short and long retry and the retry threshold has been exhausted.	longRetryInterval
Action on failing file	Yes	Yes	Move to Backout Subdirectory	The action that the node takes with the input file if all attempts to process the contents of the input file fail. Valid options are: Move to Backout Subdirectory Delete Add Time Stamp and Move to Backout Subdirectory

Records and Elements properties:

Property	M	C	Default	Description
Record detection	Yes	No	Whole File	The mechanism used to identify records in the input file. Valid options are: Whole File When you set this property to Whole File, files larger than 2 Gb are not supported. Fixed Length Delimited Parsed Record Sequence
Length	Yes	No	80	The length of each record, in bytes, when Fixed Length record detection is selected.
Delimiter	Yes	No	DOS or UNIX Line End	The type of delimiter bytes that separate, or end, each record when Delimited record detection is selected. Valid options are: DOS or UNIX Line End Custom Delimiter
Custom delimiter	No	No		The delimiter bytes, expressed in hexadecimal, when Delimited record detection and Custom Delimiter are selected. This property is mandatory only if the Delimiter property is set to Custom Delimiter.
Delimiter type	Yes	No	Postfix	The position of the delimiter when Delimited record detection is selected. Valid options are: Postfix Infix This property is ignored unless the Delimiter property is set to Custom Delimiter.
Skip first record	Yes	No	FALSE	Skip the first record in the file. The FileInput node will read the first record in the file but not propagate the record to the Out terminal. Records will be propagated as normal, from the second record onwards. Use this option when the first record is a header that does not need to be processed. It is not valid to use this option when using the whole file.

Validation properties:

For a full description of these properties, see Validation properties.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Validate	No	Yes	None	This property controls whether validation takes place. Valid values are: None Content and Value Content	validateMaster
Failure action	No	No	Exception	This property controls what happens if validation fails. Valid values are: User Trace Local Error Log Exception Exception List

FTP properties:

Property	M	C	Default	Description	mqsiapplybaroverride command property
Remote Transfer	No	Yes	Cleared	This property defines whether the node uses the remote file transfer properties listed on the FTP tab and reads files from either an FTP, FTPS, or SFTP server. If you select this property and the Include local subdirectories property, only the top-level directory that you have specified on the remote system is searched for files.	fileFtp
Transfer protocol	No	Yes	FTP	This property specifies the protocol to be used for remote transfer. Valid values are: FTP SFTP FTPS	remoteTransferType
Remote server and port	No	Yes	None	This property can have either of the following values: The IP address or name (and, optionally, the port number) of a remote FTP, FTPS, or SFTP server; for example `ftp.server.com:21` or `sftp.server.com:22` The name of a configurable service of type FtpServer If a configurable service name is specified, any of the other remote transfer properties on the FTP tab can be overridden by the configurable service.	fileFtpServer
Security identity	No	Yes		The name of the user identification used to access the FTP, FTPS, or SFTP server. This property is overridden by the securityIdentity property, if set, in the FtpServer configurable service.	fileFtpUser
Server directory	No	Yes	"."	The directory on the FTP, FTPS, or SFTP server from which to transfer files. If you specify this property as a relative path, it is relative to the home directory after logon. This property is overridden by the remoteDirectory property, if set, in the FtpServer configurable service. If the directory specified in this field does not exist on the remote server, the node attempts to create it.	fileFtpDirectory
Transfer mode	No	No	Binary	The FTP transfer mode for transfer of file data. This property is valid only when FTP is selected as the protocol for remote transfer. Valid values are: Binary ASCII This property is overridden by the transferMode property, if set, in the FtpServer configurable service. If you have specified FTPS or SFTP as the protocol for remote transfer, the Transfer mode property is ignored, and binary encoding is used.
Scan delay	No	Yes	60	The delay, in seconds, between remote directory scans. This property overrides the value set for Polling interval when the Remote Transfer property is selected. This property is overridden by the scanDelay property, if set, in the FtpServer configurable service.

Transactions properties:

Property	M	C	Default	Description
Transaction mode	No	Yes	No	The transaction mode on this input node determines whether the rest of the nodes in the flow are run under sync point. Valid options are: Yes No

Instances properties. For a full description of these properties, see Configurable properties in a BAR file.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Additional instances pool	No	Yes	Use Pool Associated with Message Flow	The pool from which additional instances are obtained. If you select Use Pool Associated with Message Flow, additional instances are obtained from the message flow pool. If you select Use Pool Associated with Node, additional instances are allocated from the additional instances of the node based on the number specified in the Additional instances property.	componentLevel
Additional instances	No	Yes	0	The number of additional instances that the node can start if the Additional instances pool property is set to Use Pool Associated with Node.	additionalInstances

The Monitoring properties of the node are described in the following table.

Property	M	C	Default	Description
Events	No	No	None	Events that you have defined for the node are displayed on this tab. By default, no monitoring events are defined on any node in a message flow. Use Add, Edit, and Delete to create, change or delete monitoring events for the node; see Configuring monitoring event sources by using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box.