Restoring messages from a data set to a queue (LOAD) on z/OS®

The LOAD function of CSQUTIL is complementary to the COPY or SCOPY function. LOAD restores messages from the destination data set of an earlier COPY or SCOPY operation. The queue manager must be running.

The data set can contain messages from one queue only if it was created by COPY or SCOPY QUEUE, or from a number of queues if it was created by COPY PSID or several successive COPY or SCOPY QUEUE operations. Messages are restored to queues with the same name as those from which they were copied. You can specify that the first or only queue is loaded to a queue with a different name. (This would normally be used with a data set created with a single COPY queue operation to restore the messages to a queue with a different name.)

Notes:

See Syncpoints for information about how to avoid problems with duplicate messages if this function fails.
An alternative approach to the LOAD function is to use the dmpmqmsg (queue load and unload) utility which is more flexible in many cases.

Messages are restored to queues with the same name as those from which they were copied. You can specify that the first or only queue is loaded to a queue with a different name using the QUEUE parameter. (This would normally be used with a data set created with a single COPY queue operation to restore the messages to a queue with a different name.) For a data set containing multiple queues, the first queue to be processed can be specified using the FROMQUEUE parameter. Messages are restored to this queue and all subsequent queues in the data set.

Queue management (LOAD)

Object Selection

DDname Selection

Record Selection

Keywords and parameters

QUEUE(q-name)

This parameter specifies that the messages from the first or only queue on the destination data set of a prior COPY or SCOPY operation are loaded to a named queue. Messages from any subsequent queues are loaded to queues with the same names as those they came from. The keyword QUEUE can be abbreviated to Q.

q-name specifies the name of the queue to which the messages are to be loaded. This name is case sensitive. It must not be a model queue.

FROMQUEUE(q_name)

Specifies the name of the first queue to process on the destination data set of a prior COPY or SCOPY operation. Messages from this queue and any subsequent queues on the data set are loaded to queues with the same names as those that they came from. If this parameter is removed, the LOAD function starts with the first queue on the data set and processes all queues. The keyword FROMQUEUE can be abbreviated to FROMQ.

DDNAME(ddname)

Specifies that messages are loaded from a named data set. This keyword can be abbreviated to DD.

ddname specifies the DDNAME that identifies the destination data set of a prior COPY or SCOPY operation, from which the messages are to be loaded. This name is not case sensitive, and can be up to 8 characters long.

If you omit DDNAME (ddname) the default DDNAME, CSQUINP, is used.

SKIPMSGS( n )

Specifies that the first n messages in the sequential data set are to be skipped before commencing the load of the queue.

If you omit SKIPMSGS( n ) no messages are skipped; the load starts at the first message.

MSGCOUNT( m )

Specifies that only m messages are read from the data set and loaded to the queue.

If you omit MSGCOUNT( m ) the number of messages read is unlimited.

Example

Figure 1. Sample JCL for the CSQUTIL LOAD function


//LOAD EXEC PGM=CSQUTIL,PARM=('CSQ1'),REGION=0M
//STEPLIB DD DISP=SHR,DSN=thlqual.SCSQANLE
// DD DISP=SHR,DSN=thlqual.SCSQAUTH
//OUTPUTA DD DSN=MY.UTILITY.OUTPUTA,DISP=SHR
//CSQUINP DD DSN=MY.UTILITY.COPYA,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
LOAD QUEUE(ABC123) DDNAME(OUTPUTA)
LOAD QUEUE(TOQ) FROMQUEUE(QUEUEA) SKIPMSGS(55)
/*

Note:

REGION - A value of 0M means that the job is allowed to have the amount of storage it needs. However, if a job tries to acquire too much storage, it might impact other jobs in the system. You must ideally look to limit the REGION size and specify an absolute maximum value that the job is allowed to acquire.

LOAD QUEUE(ABC123) DDNAME(OUTPUTA) - Reloads all queues from the input data set MY.UTILITY.OUTPUTA. The names of the queues loaded are the same as the queue names from which the data was copied, apart from the first queue on the data set which is reloaded to queue ABC123.

LOAD QUEUE(TOQ) FROMQUEUE(QUEUEA) SKIPMSGS(55) - Reloads all queues from the input data set MY.UTILITY.COPYA, starting from queue QUEUEA. The names of the queues loaded are the same as the queue names from which the data was copied, apart from the first queue QUEUEA, which is reloaded to queue TOQ. In processing the messages in QUEUEA, the first 55 messages are ignored, and loading starts from the 56th message.

Usage notes

To use the LOAD function, the queues or page sets involved must not be in use when the function is invoked.
If the data set contains multiple queues, the LOAD function is considered successful only if it successfully loads all the queues on the data set. (or all those following the starting queue specified with FROMQUEUE, if this is set).
If LOAD fails, or is forced to take a syncpoint, no further CSQUTIL functions are attempted.
CSQUTIL uses MQPMO_SET_ALL_CONTEXT to ensure that the message descriptor fields remain the same as the original copy. It therefore needs an access of CONTROL in the CONTEXT profile of the queue. For full details, see Profiles for context security.