Response body attributes for transfers

When we 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 file or queue object 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 queue or dataset object 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 file or dataset object 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 file or queue object 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 queue or dataset object 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 file or dataset object 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

Parent topic: GET


Related reference


Related information