Metadata for user exit routines

There are three different types of metadata that can be supplied to user exit routines for IBM® MQ 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

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