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 8.0, the qload utility, that previously shipped in IBM MQ Supportpac MO03, has been integrated into IBM MQ as the dmpmqmsg utility.

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

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

[z/OS] 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 Using the dmpmqmsg utility.

Syntax

Mode options

Context options

Display options

Delay options

Get options

Message range options

Optional 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 (non-destructive get), whereas using -I deletes messages from the queue (destructive get).

-f or -F Filename

Specifies either the source or target file name.

Note:

Using -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 you do not select this flag, the utility runs in local mode, which is the default.

[z/OS] 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.; On EBCDIC platforms, data is instead written in EBCDIC.
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 you 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 Using message age for information on selection using message age.

Attention: The age is based on the PutDate and PutTime fields in the Message Descriptor (MQMD), compared to UTC for the system where the utility is running.

-s or -e

Allows message selection based on message content.

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

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

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

-u

If you use the -u parameter to supply a user ID, you 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 you 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.

For examples on using the utility, see Examples of using the dmpmqmsg utility. If you store the output of the command in a file, see Meaning of three letter codes in dmpmqmsg output file for the meaning of the codes in the second column of the information in that file.