Response body attributes for transfers
When you use the HTTP GET method with the transfer object to request information about transfers, the following attributes are returned within named JSON objects.
The following objects are available:
destinationAgent
- name
- String.
- Specifies the name of the agent on the destination system.
- This attribute is always returned.
- qmgrName
- String.
- Specifies the name of the queue manager on the destination system.
originator
- host
- String.
- Specifies the host name of the system where the source file is located.
- This attribute is always returned.
- mqmdUserId
- String.
- Specifies the IBM® MQ user ID that was supplied in the message descriptor (MQMD).
- userID
- String.
- Specifies the user ID that originated the file transfer.
- This attribute is always returned.
sourceAgent
- name
- String.
- Specifies the name of the agent on the source system.
- This attribute is always returned.
- qmgrName
- String.
- Specifies the name of the queue manager on the source system.
statistics
- endTime
- String.
- Specifies the time when the transfer completed. This field is updated only when the transfer is complete. If the transfer is in any other state, then endTime is an empty string.
- This attribute is always returned.
- numberOfFileFailures
- Integer.
- Specifies the number of files that failed to transfer successfully.
- This attribute is always returned.
- numberOfFileSuccesses
- Integer.
- Specifies the number of files that successfully transferred.
- This attribute is always returned.
- numberOfFileWarnings
- Integer.
- Specifies the number of files that generated warnings, but otherwise transferred successfully.
- This attribute is always returned.
- numberOfFiles
- Integer.
- Specifies the total number of files included in the transfer request. This number includes all the files considered for the transfer operation.
- This attribute is always returned.
- retryCount
- Integer.
- Specifies the number of times that the transfer went into the recovery state and was retried by the agent.
- A transfer can go into a recovery state because the source and destination agents lose communication, either because of an IBM MQ network error, or because the agents are not receiving data or acknowledgment messages for a period. This period is determined by the agent properties: transferAckTimeout and transferAckTimeoutRetries.
- startTime
- String.
- Specifies the time when the transfer was submitted in UTC format.
- This attribute is always returned.
status
- description
- String.
- Specifies detailed information about the status upon completion, such as whether it was partially successful, successful, or failed.
- lastStatusUpdate
- String.
- Specifies the most recent time when the transfer status was captured, in UTC format.
- state
- String.
- Specifies the state of the transfer. The value can be one of the following values:
- started
- inProgress
- successful
- failed
- partiallySuccessful
- cancelled
- malformed
- notAuthorized
- deleted
- inProgressWithFailures
- inProgressWithWarnings
- This attribute is always returned.
transferSet
- bytesSent
- Integer.
- Specifies the total bytes sent.
- item
- JSON object.
- Contains elements that specify the source and destination file names and locations:
- destination
- JSON object.
- actionIfExists
- String.
- Specifies the action that is taken if a destination file exists on the destination system. The
valid options are as follows:
- error
- Reports an error and the file is not transferred.
- overwrite
- Overwrites the existing destination file.
- checksum
- JSON object.
- This object does not appear if a checksum was not performed.
- Specifies the type of hash algorithm that generated the message digest to create the digital signature. Managed File Transfer supports Message Digest algorithm 5 (md5) only. The checksum provides a way for you to confirm the integrity of transferred files is intact.
- The JSON object includes the following elements:
- method
- String.
- Specifies the method that is used for generating the checksum.
- value
- String.
- Specifies the checksum value generated.
- dataset
- JSON object.
- This object is not returned if the
fileorqueueobject is returned. - Specifies a z/OS® dataset with the following elements:
- attributes
- String.
- Specifies attributes related to the dataset.
- name
- String.
- Specifies the name of the dataset.
- size
- Integer.
- Specifies the file size.
- file
- JSON object.
- This object is not returned if the
queueordatasetobject is returned. - Specifies information about the file that was transferred in the following elements:
- encoding
- String.
- Specifies the encoding for a text file transfer.
- endOfLine
- Specifies the end of line marker. This value can be either of the following values:
- LF - line feed character only.
- CRLF - carriage return and line feed character sequence.
- lastModified
- String.
- Specifies the last modified date and time for the file, in UTC format.
- path
- String.
- Specifies the path location of the file.
- size
- Integer.
- Specifies the file size.
- queue
- JSON object.
- This object is not returned if the
fileordatasetobject is returned. - Specifies information about the queue that messages were transferred to, in the following elements:
- delimiter
- String.
- Specifies the delimiter used.
- If delimiterType is set to size, this element specifies the delimiter size. If delimiterType is set to binary, the value is the number of delimiter bytes.
- If delimiter is an empty string, the field is not set while initiating the transfer.
- delimiterPosition
- String.
- This element is valid only when delimiterType is binary.
The value is one of the following values:
- "prefix"
- Before each message.
- "postfix"
- After each message.
- If delimiterPosition is an empty string, the field is not set while initiating the transfer.
- delimiterType
- String.
- Specifies the type of delimiter that is used to split the messages. The value can be one of the
following values:
- binary
- Split by delimiter bytes.
- size
- Split by size.
- If delimiterType is an empty string, the field is not set while initiating the transfer.
- includeDelimiterInMessage
- Boolean.
- This element is valid only when delimiterType is binary.
- Specifies whether the delimiter is included in the message.
- messageCount
- Integer.
- Specifies the number of messages that were written to the queue.
- messageLength
- Integer.
- Specifies the length of the message written to the queue.
- messageOrGroupId
- String.
- If the transfer request did not specify that the file is split into multiple messages, the value of this attribute is the IBM MQ message ID of the message written to the queue.
- If the transfer request specified that the file is split into multiple messages, the value of this attribute is the IBM MQ group ID of the messages written to the queue.
- name
- String.
- Specifies the name of the queue and the queue manager, in the following format:
queueName@queueManagerName
- type
- String.
- Specifies the type of destination. The destination is one of the following destinations:
- queue
- Specifies an IBM MQ queue as the destination.
- file
- Specifies a file as the destination.
- dataset
- Specifies a z/OS dataset as the destination.
- mode
- String.
- Specifies the transfer mode as either binary or text.
- source
- JSON object.
-
- checksum
- JSON object.
- This object does not appear if a checksum was not performed.
- Specifies the type of hash algorithm that generated the message digest to create the digital signature. Managed File Transfer supports Message Digest algorithm 5 (md5) only. The checksum provides a way for you to confirm the integrity of transferred files is intact.
- The JSON object includes the following elements:
- method
- String.
- Specifies the method that is used to generate the checksum.
- value
- String.
- Specifies the checksum value that is generated.
- disposition
- String.
- Specifies the action that is taken on the source element when source has successfully been
transferred to its destination. This string is one of the following options:
- leave
- Specifies that the source files are left unchanged
- delete
- Specifies that the source files are deleted from the source system after the source file is successfully transferred
- dataset
- JSON object.
- This object is not returned if the
fileorqueueobject is returned. - Specifies a z/OS dataset with the following elements:
- attributes
- String.
- Specifies attributes related to the dataset.
- name
- String.
- Specifies the name of the dataset.
- size
- Integer.
- Specifies the file size.
- file
- JSON object.
- This object is not returned if the
queueordatasetobject is returned. - This object contains the following elements:
- encoding
- String.
- Specifies the encoding for a text file transfer.
- endOfLine
- Specifies the end of line marker. This value can be either of the following values:
- LF - line feed character only.
- CRLF - carriage return and line feed character sequence.
- lastModified
- String.
- Specifies the last modified date and time for the file, in UTC format.
- path
- String.
- Specifies the path location for the file.
- size
- Integer.
- Specifies the size of the file.
- queue
- JSON object.
- This object is not returned if the
fileordatasetobject is returned. - Specifies information about the queue that transferred messages were retrieved from, in the
following elements:
- messageCount
- Integer.
- Specifies the number of messages that were read from the queue.
- name
- String.
- Specifies the name of the queue and the queue manager, in the following format:
queueName@queueManagerName - setMqProperties
- Boolean.
- Specifies 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.
- type
- String.
- Specifies the type of source. The source is one of the following sources:
- queue
- Specifies an IBM MQ queue as the source.
- file
- Specifies a file as the source, if the source is a file or directory.
- dataset
- Specifies a z/OS dataset as the source.
- status
- JSON object.
- Specifies the status of a single item in the transfer set. The status object contains the
following elements:
- description
- String.
- Specifies detailed information about the status completion, such as whether it was partially successful, successful, or failed.
- state
- String.
- Specifies the state of the transfer. The value can be one of the following values:
- started
- inProgress
- successful
- failed
- partiallySuccessful
- cancelled
- malformed
- notAuthorized
- deleted
- inProgressWithFailures
- inProgressWithWarnings