dmpmqmsg (queue load and unload)

Use the dmpmqmsg utility to copy or move the contents of a queue, or its messages, to a file. Formerly the IBM MQ qload utility.


Purpose

From IBM MQ Version 8.0, the qload utility, that previously shipped in IBM MQ Supportpac MO03, has been integrated into IBM MQ as the dmpmqmsg utility.

On UNIX and Linux platforms the utility is available in <installdir>./bin

On Windows platforms the utility is available in <installdir>./bin64 as part of the server fileset.

On z/OS, the utility is available as an executable module, CSQUDMSG in the SCSQLOAD library, with an alias of QLOAD for compatibility. Sample JCL is also provided as member CSQ4QLOD in SCSQPROC.

For more information, see Use the dmpmqmsg utility.


Syntax

dmpmqmsg  -m Queue manager name  -i or -I Input queue name  -f or -F Filename  -o Output queue name Mode options -c  -P CodepageContext optionsDisplay optionsDelay optionsGet options -h Strip headers -pPurge -qQuiet modeMessage range -tTransaction message limit -TMessage age selection -s or -eMessage content selection -uUserID -wWait intervalMode options -a ab Context options -C -AIaidn Display options -d aAcCHipsMNtTw Delay options -D positive valuenegative valuer (value) Get options -g c (value)m (value)g (value)xc (value)xm (value)xg (value) Message range options -r xx..yx#y#x


Required parameters

    -m QueueManagerName
    The name of the queue manager on which the queue, or queues, exist.

    -i or -I Input queue name
    The name of the input queue. Note: Using -i browses the queue, whereas using -I gets messages from the queue.


Optional parameters

    -f or -F Filename
    Specifies either the source or target file name. Note:

    • Use -F on a target file forces output to a file if it already exists. The program does not ask you if the file should be overwritten.
    • Take care to ensure that appropriate access controls are set on the output file, as users who are not permitted to access messages on the queue might have access to read the output file.

      On UNIX and Linux, permissions for new files are set according to the current umask when the utility is run.

      On Windows, permissions for new files are inherited from the parent directory ACL.

    -o Output queue name
    Specifies the name of the output queue.

    -a
    Controls whether the file is opened in append or binary mode, by adding one of the following values to the keyword:

      a
      Append mode

      b
      Binary mode

    -c
    Connect in client mode.

    If we do not select this flag, the utility runs in local mode, which is the default.

    This option is not available on z/OS.

    -P
    Controls whether messages taken from a queue are converted. Use the command 
    -P CCSID [ : X 'Encoding' ]
    For example -P850:111

    -C
    Controls the context option, by adding one of the following values to the keyword:

      A
      Set all context. This is the default value.

      I
      Set identity context.

      a
      Pass all context.

      p
      Pass identity context.

      Use of the pass options is not applicable if the source messages are browsed on a queue.

      d
      Default context.

      n
      No context.

    -d
    Controls the display option or options, by adding one or more of the following values to the keyword. For example -dsCM:

      a
      Add ASCII columns to the hexadecimal output in the file to aid readability.

      A
      Write ASCII lines of data wherever possible.

      c
      Output ApplicationOriginData and ApplicationIdentityData as characters

      C
      Display the Correlation Identifier in the queue summary.

      H
      Do not write the file header.

      Files created with this option are not loadable by the program as the program does not recognize the file format. However, if necessary we can use an editor to add an appropriate header manually, to make the file loadable.

      i
      Include the message index in the output.

      p
      Printable character output format.

      This format is not code page safe. Loading a file written in this format, while running in a new code page does not guarantee to produce the same message.

      s
      Write a simple summary of the messages found on input.

      M
      Display the Message Identifier in the queue summary.

      N
      Do not write out the message descriptor content, only the message payload.

      t
      Text line output format.

      This format is not code page safe. Loading a file written in this format, while running in a new code page does not guarantee to produce the same message.

      T
      Display the time the message has been on the queue.

      w Length
      Set the data width for the output.

    -D
    Add a delay, expressed in milliseconds, before writing a message to the output destination, by adding one of the following values to the keyword. For example:

      -Dpositive_value
      Add a fixed delay before putting a message. For example, -D500 puts each message half a second apart.

      -Dnegative_value
      Add a random delay, up to the specified value before putting a message. For example, -D-10000 adds a random delay of up to 10 seconds before putting a message.

      rvalue
      Replays the messages at a percentage of their original put speed. For example:

        r
        Replays messages at their original speed.

        r50
        Replays messages at half their original speed.

        r200
        Replays messages at twice their original speed.

    -g
    Filter by Message identifier, Correlation identifier, or Group identifier, by adding one of the following values to the keyword.

      cvalue
      Get by character Correlation identifier.

      mvalue
      Get by character Message identifier.

      gvalue
      Get by character Group identifier.

      xcvalue
      Get by hexadecimal Correlation identifier.

      xmvalue
      Get by hexadecimal Message identifier.

      xgvalue
      Get by hexadecimal Group identifier.

    -h
    Strip headers.

    Any Dead Letter Queue header (MQDLH) or Transmission Queue header (MQXQH) is removed from the message before the message is written.

    -o
    Output queue name.

    -p
    Causes the source queue to be purged of messages as they are copied to the target destination.

    -q
    Sets quiet mode. When set, the program does not output its usual summary of activity.

    -r
    Note: If the dmpmqmsg command runs with the -r option set to 0, the command copies all messages to the destination, whether that destination is a file or queue.

    Sets the applicable message range by adding one of the following values to the keyword.

      x
      Only message x, for example, -r10. If r is 0, copies all messages to the destination.

      x..y
      From message x to message y. For example, -r 10..20. -r0..9 copies one to nine messages to the destination.

      x#y
      Output y messages starting at message x. For example, -r 100#10.,-r0#4 copies one to four messages to the destination.

      #x
      Output the first x messages, for example, -r #100. -r \#0 copies all messages to the destination.

    -t
    Set the transaction message limit. If the optional n flag is not set, all the messages are done in a single transaction.

      n
      The message operations are split into groups of n messages. For example -t1000 deals with 1000 messages in a single transaction.

    -T
    Allows message selection based on message age.

    See Use message age for information on selection using message age.

    -s or -e
    Allows message selection based on message content.

    On ASCII platforms (UNIX, Linux, and Windows) use the -s option to search for a natively encoded string.

    On EBCDIC platforms (z/OS) use the -e option to search for a natively encoded string.

    See Use message content for information on selection using message content.

    -u
    If we use the -u parameter to supply a user ID, we are prompted for a matching password.

    If you have configured the CONNAUTH AUTHINFO record with CHCKLOCL(REQUIRED) or CHCKLOCL(REQDADM), you must use the -u parameter otherwise we will not be able to copy or move the contents of a queue.

    If you specify this parameter and redirect stdin, a prompt will not be displayed and the first line of redirected input should contain the password.

    -w
    Wait interval, in seconds, for consuming messages. If specified the program waits for messages to arrive, for the specified period, before ending.

See Examples of using the dmpmqmsg utility for examples on using the utility.

  • Message selection
    Message selection can be based on message age or message content.

Parent topic: IBM MQ control commands reference