Request body attributes for transfers with HTTP POST
When you create the request body for creating a transfer request with the administrative REST API for MFT, we can specify attributes for the transfer within named JSON objects. A number of objects and attributes are available.
The following objects are available:
job
The job object can contain the following attributes that relate to the transfer job:
- name
- String.
- Specifies a user-defined job name for the transfer.
sourceAgent
The sourceAgent object can contain the following attributes that relate to the source agent:
- name
- String.
- Specifies the name of the agent on the source system.
- This attribute is required.
- qmgrName
- String.
- Specifies the name of the queue manager on the source system.
- This attribute is required.
destinationAgent
The destinationAgent object can contain the following attributes that relate to the destination agent:
- name
- String.
- Specifies the name of the agent on the destination system.
- This attribute is required.
- qmgrName
- String.
- Specifies the name of the queue manager on the destination system.
- This attribute is required.
scheduleTransfer
The scheduleTransfer object can contain the following attributes that relate to a scheduled transfer:
- startTime
- String.
- Specifies the start time and date for the scheduled transfer in the format yyyy-MM-ddThh:mm or hh:mm. Specify the time by using the 24-hour clock.
- timeBase
- String.
- Specifies the time base for the start and end time of the scheduled file transfer.
- The value must be one of the following values:
- admin
- The start and end time for the scheduled transfer are based on the time and date of the system where the mqweb server is running.
- source
- The start and end time for the scheduled transfer are based on the time and date of the system where the source agent is located.
- utc
- The start and end time for the scheduled transfer are based on Coordinated Universal Time.
- occurrenceInterval
- String.
- Specifies the interval that the scheduled transfer occurs at.
- Use this attribute in conjunction with the startTime and occurrenceFrequency attributes.
- The value must be one of the following values:
- minutes
- hours
- days
- weeks
- months
- years
- occurrenceFrequency
- Integer.
- Specifies the frequency of a repeating scheduled transfer. Use this attribute in conjunction with the startTime and occurrenceInterval attributes.
- occurrenceCount
- Integer.
- Specifies the number of times that the scheduled transfer will occur.
- Use this attribute in conjunction with the startTime and occurrenceInterval attributes.
- This attribute can not be specified with the endTime attribute.
- endTime
- String.
- Specifies the time and date when a repeating scheduled transfer ends in format yyyy-MM-ddThh:mm or hh:mm. Specify the time by using the 24-hour clock.
- Use this attribute in conjunction with the startTime and occurrenceInterval attributes.
- This attribute can not be specified with the occurrenceCount attribute.
transferSet
The transferSet object can contain the following attributes that relate to the transfer:
- priority
- Integer.
- Specifies the priority assigned to the transfer request. The default value is zero.
- userProperties
- JSON object.
- Specifies user-defined metadata that is passed to exits run by the agents involved in the transfer.
- item
- JSON array.
- An array of JSON objects that describe the source and destination item configurations to transfer.
-
- source
- JSON object.
- A JSON object that contains attributes that relate to the source item to transfer.
- name
- String.
- Specifies the absolute path of the file, directory, data set, partitioned data set, or queue at the source end.
- This attribute is required.
- type
- String.
- Specifies the type of source.
- The value must be one of the following values:
- queue
- The source is an IBM MQ .
- file
- The source is a file.
- recursive
- Boolean.
- Specifies whether files are transferred recursively in subdirectories when the source element is a directory, or contains wildcard characters.
- disposition
- String.
- Specifies the action that is taken on the source element when a source has successfully been transferred to its destination.
- The value must be one of the following values:
- leave
- The source files are left unchanged.
- delete
- The source files are deleted from the source system when they have been successfully transferred.
- encoding
- String
- Specifies which character encoding to use, to read the source file when performing character conversion. This option is only applicable to text files.
- The values can be any valid code page number.
- datasetExtended
- JSON object.
- A JSON object that contains additional source attributes, if the source is a z/OS sequential or partitioned data set.
- keepTrailingSpaces
- Boolean.
- Specifies whether trailing spaces are kept in the source records that are read from a fixed-length format record oriented file (for example, a z/OS data set) as part of a text mode transfer.
- If we do not specify this parameter, trailing spaces are stripped from source records.
- hexDelimiters
- String.
- For source files that are record oriented (for example, z/OS data sets), specifies one or more byte values to insert as the delimiter when appending records into a binary file.
- We must specify each value as two hexadecimal digits in the range 00-FF, prefixed by x. Separate multiple bytes with commas.
- delimiterPosition
- String
- Specifies the position to insert source record delimiters. This attribute is used in conjunction with the hexDelimiters attribute.
- The value must be one of the following values:
- prefix
- The delimiters are inserted at the start of each record.
- postfix
- The delimiters are inserted at the end of each record; this is the default option.
- queueExtended
- JSON object.
- A JSON object that contains additional source attributes, if the source is an IBM MQ queue.
- messageGroup
- Boolean.
- Specifies whether messages are grouped by IBM MQ group ID. The first complete group is written to the destination file.
- If this parameter is not specified, all messages on the source queue are written to the destination file.
- groupID
- String.
- Specifies the group ID to be used when getting messages from a queue.
- textDelimiters
- String.
- Specifies a sequence of text to insert as the delimiter, when appending multiple messages to a text file.
- hexDelimiters
- String.
- Specifies one or more byte values to use, when appending multiple messages to a file.
- We must specify each value as two hexadecimal digits in the range 00-FF, prefixed by x. Separate multiple bytes with commas. For example x12 or x03,x7F.
- delimiterPosition
- String.
- Specifies where the delimiters are positioned in the message being put to the source queue.
- The value must be one of the following values:
- prefix
- The delimiters are inserted at the start of each message.
- postfix
- The delimiters are inserted at the end of each message; this is the default option.
- messageArrivalWaitTime
- Integer.
- Specifies the time in seconds to wait for the arrival of messages on the source queue.
- destination
- JSON object.
- A JSON object that contains attributes that relate to the destination item.
- name
- String.
- Specifies the absolute path of the file, directory, data set, partitioned data set, or queue at the destination.
- This attribute is required.
- type
- String.
- Specifies the type of destination.
- This attribute is required.
- The value must be one of the following values:
- queue
- The destination is an IBM MQ queue.
- file
- The destination is a file.
- directory
- The destination is a directory.
- sequentialDataset
- The destination is a z/OS sequential data set.
- partitionedDataset
- The destination is a z/OS partitioned data set.
- actionIfExists
- String.
- Specifies the action that is taken if a destination file, directory, or data set exists on the destination system.
- The value must be one of the following values:
- error
- An error is reported and the file is not transferred; this is the default value.
- overwrite
- The existing destination file is overwritten.
- encoding
- String.
- Specifies which character encoding to use to write the file at the destination. This option is only applicable to text files.
- The value can be any valid code page number.
- endOfLine
- String.
- Specifies the end-of-line characters that are used when the file is written at the destination. This option is applicable to text files only.
- The value must be one of the following values:
- LF
- Line feed.
- CRLF
- Carriage return followed by line feed.
- datasetExtended
- JSON object.
- A JSON object that contains additional destination attributes, if the destination is a z/OS data set.
- truncateRecords
- Boolean.
- Specifies whether destination records longer than the data set LRECL attribute are truncated. If this parameter is not specified, the records are wrapped.
- This parameter is valid only for text mode transfers where the destination is a data set.
- queueExtended
- JSON object.
- A JSON object that contains additional destination attributes, if the destination is an IBM MQ queue.
- messagePersistence
- String.
- Specifies the persistence of the message put to the destination queue.
- The value must be one of the following values:
- persistent
- Messages are persistent.
- notPersistent
- Messages are not persistent.
- asQueue
- The message persistence is as set in the queue definition. This is the default value.
- delimiterType
- String.
- Specifies the type of delimiter to use when splitting a file into multiple messages.
- The value must be one of the following values:
- size
- Split based on a specified size.
- binary
- Split based on specified delimiters.
- hexDelimiters
- String.
- Specifies the hexadecimal delimiter to use when splitting a binary file into multiple messages.
- We must specify each value as two hexadecimal digits in the range 00-FF, prefixed by x. We can specify a sequence of hexadecimal bytes as a delimiter by specifying a comma-separated list of hexadecimal bytes. For example x12 or x03,x7F.
- textDelimiters
- String.
- Specifies the Java regular expression to use, when splitting a text file into multiple messages.
- includeDelimitersInMessage
- Boolean.
- Specifies whether delimiters are inserted in the message put to the destination queue.
- delimiterPosition
- String
- Specifies where the delimiters are positioned in the message put to the destination queue.
- The value must be one of the following values:
- prefix
- The delimiters are inserted at the beginning of the message body.
- postfix
- The delimiters are inserted at the end of the message body.
- setMQProperties
- Boolean.
- Specifies whether message properties are set on the first message that is created by the transfer.
- messageSize
- Integer.
- Specifies whether to split the file into multiple fixed-length messages of this size in bytes.
- checksum
- String.
- Specifies the checksum method for verifying data integrity.
- The value must be one of the following values:
- md5
- The MD5 algorithm is used for integrity validation.
- none
- No checksum validation.
- mode
- String.
- Specifies the transfer mode.
- The value must be one of the following values:
- text
- Data is transferred as text.
- binary
- Data is transferred in binary.
- This is the default value.
- recoveryTimeout
- Integer.
- Specifies the length of time during which a source agent attempts to recover a stalled file transfer.
- The value must be one of the following values:
- -1
- The agent continues to attempt to recover the stalled transfer until the transfer is complete.
- This is the default value.
- 0
- The agent stops the file transfer as soon as it enters recovery.
- n
- The agent continues to attempt to recover the stalled transfer for the specified amount of time in seconds.
- The value must be in the range 1 - 999,999,999.
- preSourceCall
- JSON object.
- A JSON object that contains attributes that are related to the program to invoke at the source
agent, before a transfer begins.
- type
- String.
- Specifies the type of the program to be invoked.
- The value must be one of the following values:
- executable
- A platform-specific executable is invoked. This is the default value.
- antScript
- An Apache Ant script is invoked.
- jcl
- A z/OS JCL job is submitted.
- executable
- JSON object.
- A JSON object that can contain attributes related to a platform-specific executable program to
be invoked. This object can only be specified when the value of the type attribute
is executable.
- name
- String.
- Specifies the name of the program to run.
- This attribute is required if the executable JSON object is specified.
- arguments
- String.
- Specifies arguments to be passed to the program that is invoked.
- antScript
- JSON object.
- A JSON object that can contain attributes related to an Apache Ant script to be invoked. This
object can only be specified when the value of the type attribute is
antScript.
- name
- String.
- Specifies the name of the Ant script to run.
- This attribute is required if the antScript JSON object is specified.
- target
- Specifies the target to invoke in the specified Ant script.
- If this attribute is not specified, the target named default is invoked.
- arguments
- String.
- Specifies a list of user-defined custom data in space separated key=value pairs.
- jcl
- JSON object.
- A JSON object that can contain attributes related to a z/OS JCL job to submit. This object can only be specified when
the value of the type attribute is jcl.
- name
- String.
- Specifies the name of the JCL to submit.
- retryCount
- Integer.
- Specifies the number of attempts to run the command before ceasing.
- retryWait
- Integer.
- Specifies the amount of time to wait, in seconds, between retry attempts.
- successReturnCode
- String.
- Specifies the condition, based on the return code from the transfer, that must be true in order for the specified program, script, or JCL to be run.
- The condition is specified as an operator, followed by a value. Valid characters for the operator are >, <, ! and =. It is valid to have a combination of more than one operator. For example, ">= 40".
- The default value is zero.
- postSourceCall
- JSON object.
- A JSON object that contains attributes that are related to the program to invoke at the source agent, after a transfer completes.
- The attributes that can be specified are the same as for the preSourceCall object.
- preDestinationCall
- JSON object.
- A JSON object that contains attributes that are related to the program to invoke at the destination agent, before a transfer begins.
- The attributes that can be specified are the same as for the preSourceCall object.
- postDestinationCall
- JSON object.
- A JSON object that contains attributes that are related to the program to invoke at the destination agent, after a transfer completes.
- The attributes that can be specified are the same as for the preSourceCall object.
Parent topic: POST
Related information