Metadata for user exit routines

There are three different types of metadata that can be supplied to user exit routines for WebSphere® MQ File Transfer Edition: 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.
Key Description
AGENT_VERSION_KEY Version number for the agent runtime that calls the exit routine.
AGENT_PRODUCT_DIRECTORY_KEY The name of the directory that the agent code has been installed in.
AGENT_CONFIGURATION_DIRECTORY_KEY The name of the directory that contains the agent's configuration information.

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.
Key Description
TRANSFER_ID_KEY The identifier of the transfer
MQMD_USER_KEY The MQMD user field from the message used to submit the transfer request
JOB_NAME_KEY The job name associated with the transfer request
ORIGINATING_USER_KEY The user name specified as the originating user ID in the transfer request
ORIGINATING_HOST_KEY The host name specified as the originating host name in the transfer request
SOURCE_AGENT_KEY The name of the agent that is the source of the transfer
DESTINATION_AGENT_KEY The name of the agent that is the destination for 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.
Key Permitted values Description
FILE_CONVERSION_KEY FILE_CONVERSION_TEXT_VALUE FILE_CONVERSION_BINARY_VALUE Determines the type of conversion applied to the file contents.
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.
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_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_CHECKSUM_METHOD_KEY FILE_CHECKSUM_METHOD_NONE_VALUE FILE_CHECKSUM_METHOD_MD5_VALUE Determines the checksum method to use when transferring the file.
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>.
DESTINATION_EXIST_KEY DESTINATION_EXIST_KEY_ERROR_VALUE DESTINATION_EXIST_KEY_OVERWRITE_VALUE Determines the file transfer behavior if the destination file exists.
SOURCE_DISPOSITION_KEY SOURCE_DISPOSITION_LEAVE_VALUE SOURCE_DISPOSITION_DELETE_VALUE Determines the disposition of a source file after the transfer has completed. That is, the action that is taken on a source file when that source file has successfully been transferred to its destination.

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


Concept Concept

Feedback

Timestamp icon Last updated: Tuesday, 30 January 2018
http://www.ibm.com/support/knowledgecenter/SSEP7X_7.0.4/com.ibm.wmqfte.doc/metadata.htm