Metadata for MFT user exits

There are three different types of metadata that can be supplied to user exit routines for Managed File Transfer: environment, transfer, and file metadata. This metadata is presented as maps of Java key-value pairs.

Environment metadata

Environment metadata is passed to all user exit routines and describes the agent runtime environment that the user exit routine is being called from. This metadata is read-only and cannot be updated by any user exit routine.

Table 1. Environment metadata
Key	Description
AGENT_CONFIGURATION_DIRECTORY_KEY	The name of the directory that contains the agent's configuration information.
AGENT_PRODUCT_DIRECTORY_KEY	The name of the directory that the agent code has been installed in.
AGENT_VERSION_KEY	Version number for the agent runtime that calls the exit routine.

The key names and value names given in Table 1 are constants that are defined in the EnvironmentMetaDataConstants interface.

Transfer metadata

Transfer metadata is passed to all user exit routines. The metadata consists of system-supplied values and user-supplied values. If you change any system-supplied values, these changes are ignored. The initial user-supplied values for the source transfer start user exit are based on those values you supply when you define the transfer. The source agent can change user-supplied values as part of the processing of the source transfer start user exit. This user exit is called before the entire file transfer starts. These changes are used in subsequent calls to other exit routines that relate to that transfer. Transfer metadata is applied to an entire transfer.

Although all user exits can read values from the transfer metadata, only the source transfer start user exit can change transfer metadata

We cannot use transfer metadata to propagate information between different file transfers.

The system-supplied transfer metadata is detailed in Table 2:

Table 2. Transfer metadata
Key	Description
DESTINATION_AGENT_KEY	The name of the agent that is the destination for the transfer.
JOB_NAME_KEY	The job name associated with the transfer request
MQMD_USER_KEY	The MQMD user field from the message used to submit the transfer request
ORIGINATING_HOST_KEY	The host name specified as the originating host name in the transfer request
ORIGINATING_USER_KEY	The user name specified as the originating user ID in the transfer request
SOURCE_AGENT_KEY	The name of the agent that is the source of the transfer
TRANSFER_ID_KEY	The identifier of the transfer

The key names and value names given in Table 2 are constants that are defined in the TransferMetaDataConstants interface.

File metadata

The file metadata is passed to the source transfer start exit as part of the file specification. There is separate file metadata for the source and destination files.

You cannot use file metadata to propagate information between different file transfers.

Table 3. File metadata
Key	Permitted values	Description
CONVERT_LINE_SEPARATORS		Key value used for text transfers to indicate whether CRLF (carriage return-line feed) or LF (line feed) line separator sequences in source data are converted to the line separator sequence at the destination.
DELIMITER_KEY		Key value used to define a delimiter to separate record data when transferring record-oriented data to normal files. Also used for message-to-file and file-to-message transfers.
DELIMITER_POSITION_KEY	DELIMITER_POSITION_PREFIX_VALUE DELIMITER_POSITION_POSTFIX_VALUE	Use with the DELIMITER_KEY to define the position of the delimiter; either prefix or postfix.
DELIMITER_TYPE_KEY	DELIMITER_TYPE_BINARY_VALUE DELIMITER_TYPE_TEXT_VALUE DELIMITER_TYPE_SIZE_VALUE	Use with the DELIMITER_KEY to define the type of delimiter.
DESTINATION_EXIST_KEY	DESTINATION_EXIST_KEY_ERROR_VALUE DESTINATION_EXIST_KEY_OVERWRITE_VALUE	Determines the file transfer behavior if the destination file exists.
FILE_ALIAS_KEY		Key value used to define an alias for the file being transferred.
FILE_CHECKSUM_METHOD_KEY	FILE_CHECKSUM_METHOD_NONE_VALUE FILE_CHECKSUM_METHOD_MD5_VALUE	Determines the checksum method to use when transferring the file.
FILE_CONVERSION_KEY	FILE_CONVERSION_TEXT_VALUE FILE_CONVERSION_BINARY_VALUE	Determines the type of conversion applied to the file contents.
FILE_ENCODING_KEY		Determines the encoding used for a text file.
FILE_END_OF_LINE_KEY	FILE_END_OF_LINE_LF_VALUE FILE_END_OF_LINE_CRLF_VALUE	Determines the character sequence that denotes the end of a line: <LF> or <CR><LF>.
FILE_SPACE_ALIAS		Determines the alias of a file in the file space. Note: This metadata can be used only if the FILE_TYPE_KEY is FILE_TYPE_FILE_SPACE_VALUE
FILE_SPACE_NAME		Determines the name of the file space. Note: This metadata can be used only if the FILE_TYPE_KEY is FILE_TYPE_FILE_SPACE_VALUE
FILE_TYPE_KEY	FILE_TYPE_FILE_VALUE FILE_TYPE_DIRECTORY_VALUE FILE_TYPE_DATASET_VALUE FILE_TYPE_PDS_VALUE FILE_TYPE_QUEUE_VALUE FILE_TYPE_FILE_SPACE_VALUE	Determines the destination file, queue, or file space specification.
GROUP_ID_KEY		Key value used for message-to-file transfers to determine the group of messages to read from the source queue. This attribute is valid only when the value of USE_GROUPS_KEY is USE_GROUPS_TRUE_VALUE.
INCLUDE_DELIMITER_IN_MESSAGE_KEY	INCLUDE_DELIMITER_IN_MESSAGE_TRUE_VALUE INCLUDE_DELIMITER_IN_MESSAGE_FALSE_VALUE	Key value used for file-to-message transfers to determine whether to include the delimiters that were used to split the file into multiple messages at the end of the messages. This attribute is valid only when the value of DELIMITER_TYPE_KEY is DELIMITER_TYPE_BINARY_VALUE DELIMITER_TYPE_TEXT_VALUE.
INSERT_RECORD_LINE_SEPARATOR_KEY		Key value used for text transfers from record-oriented files to specify whether line separators are inserted into the data after each record.
KEEP_TRAILING_SPACES_KEY	KEEP_TRAILING_SPACES_TRUE_VALUE KEEP_TRAILING_SPACES_FALSE_VALUE	Key value used to determine whether trailing spaces are removed from records read from fixed-length-format data sets.
NEW_RECORD_ON_LINE_SEPARATOR_KEY		Key value used for text transfers to record- oriented files to specify whether line separators in the data are included with the record data or cause a new record (and are not written).
PERSISTENT_KEY	PERSISTENT_TRUE_VALUE PERSISTENT_FALSE_VALUE PERSISTENT_QDEF_VALUE	Key value used for file-to-message transfers to determine whether the messages are persistent.
SET_MQ_PROPS_KEY	SET_MQ_PROPS_TRUE_VALUE SET_MQ_PROPS_FALSE_VALUE	Key value used for file-to-message transfers to determine whether IBM MQ message properties are set on the first message in a file, and any messages written to the queue when an error occurs.
UNRECOGNISED_CODE_PAGE_KEY	UNRECOGNISED_CODE_PAGE_FAIL_VALUE UNRECOGNISED_CODE_PAGE_BINARY_VALUE	Key value used for file-to-message transfers to determine whether a text mode transfer fails or conversion is performed, if the code page of the data is not recognized by the destination queue manager.
USE_GROUPS_KEY	USE_GROUPS_TRUE_VALUE USE_GROUPS_FALSE_VALUE	Key value used for message-to-file transfers to determine whether to transfer only a complete group of messages from the source queue.
WAIT_TIME_KEY		Key value used for message-to-file transfers to determine the time, in seconds, for the source agent to wait for one of the following cases: A message to appear on the source queue, if the queue is empty or has become empty, if the value of USE_GROUPS_KEY is FALSE. A complete group to appear on the source queue, if the value of USE_GROUPS_KEY is TRUE.

The key names and value names given in Table 3 are constants that are defined in the FileMetaDataConstants interface.