Request body attributes for transfers with HTTP POST

job

The job object can contain the following attributes that relate to the transfer job:

sourceAgent

The sourceAgent object can contain the following attributes that relate to the source agent:

destinationAgent

The destinationAgent object can contain the following attributes that relate to the destination agent:

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

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

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

You must specify each value as two hexadecimal digits in the range 00-FF, prefixed by x. You 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.