Copy queues into a data set while the queue manager is running (COPY) on z/OS

We can use the COPY function of CSQUTIL to copy queued messages to a sequential data set while the queue manager is running, without destroying any messages in the original queues.

The scope of the COPY function is determined by the keyword that you specify in the first parameter. We can either copy all the messages from a named queue, or all the messages from all the queues on a named page set.

Use the complementary function, LOAD, to restore the messages to their appropriate queues. Note:
  1. To copy the object definitions from the named page set, use COPYPAGE.
  2. To copy messages to a data set when the queue manager is stopped, use SCOPY.
  3. For information about how to avoid problems with duplicate messages if this function fails, see Syncpoints in IBM MQ for z/OS applications.


Queue management (COPY)

COPY Object SelectionObject SelectionQUEUE(q-name)PSID(psid-number)DEFTYPE(ALL)DEFTYPE(PREDEFINED)DDname SelectionDDname SelectionDDNAME(ddname)


Keywords and parameters

    QUEUE(q-name)
    Specifies that messages in the named queue are to be copied. The keyword QUEUE can be abbreviated to Q.

    q-name specifies the name of the queue to be copied. This name is case-sensitive.

    PSID(psid-number)
    Specifies that all the messages in all the queues in the specified page set are to be copied.

    psid-number is the page set identifier, which specifies the page set to be used. This identifier is a two-digit integer (whole number) representing a single page set.

    DEFTYPE
    Specifies whether to copy dynamic queues:

      ALL
      Copy all queues; this is the default.

      PREDEFINED
      Do not include dynamic queues; this is the same set of queues that are selected by the COMMAND and SDEFS functions with the MAKEDEF parameter.

    DDNAME(ddname)
    Specifies that the messages are to be copied to a named data set. If this keyword is omitted, the default DDname, CSQUOUT, is used. The keyword DDname can be abbreviated to DD.

    ddname specifies the DDname of the destination data set, which is used to store the messages. The record format of this data set must be variable block spanned (VBS).


Example

Figure 1. Sample JCL for the CSQUTIL COPY functions. The sample shows two instances of the COPY function-one COPY to the default DDNAME, CSQUOUT; the other to DDNAME OUTPUTA, which overrides CSQUOUT. 
//COPY   EXEC PGM=CSQUTIL,PARM='CSQ1',REGION=0M
//STEPLIB  DD   DISP=SHR,DSN=thlqual.SCSQANLE
//         DD   DISP=SHR,DSN=thlqual.SCSQAUTH
//OUTPUTA  DD DSN=SAMPLE.UTILITY.COPYA,DISP=(NEW,CATLG),
//            SPACE=(CYL,(5,1),RLSE),UNIT=SYSDA,
//            DCB=(RECFM=VBS,BLKSIZE=23200)
//CSQUOUT  DD DSN=SAMPLE.UTILITY.COPY3,DISP=(NEW,CATLG),
//            SPACE=(CYL,(5,1),RLSE),UNIT=SYSDA,
//            DCB=(RECFM=VBS,BLKSIZE=23200)
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
* COPY WHOLE PAGE SET TO 'CSQUOUT'
COPY PSID(03)
* COPY ONE QUEUE TO 'OUTPUT'
COPY QUEUE(ABC123A) DDNAME(OUTPUTA)
/*


Usage notes

  1. The queues involved must not be in use when the function is started.
  2. To operate on a range of page sets, repeat the COPY function for each page set.
  3. The function operates only on local queues.
  4. A COPY PSID function is considered successful only if it successfully copies all the queues on the page set.
  5. If you try to copy an empty queue (either explicitly by COPY QUEUE or because there are one or more empty queues on a page set that we are copying), data indicating this is written to the sequential data set, and the copy is considered to be a success. However, if you attempt to copy a nonexistent queue, or a page set containing no queues, the COPY function fails, and no data is written to the data set.
  6. If COPY fails, no further CSQUTIL functions are attempted.
  7. To use the COPY function more than once in the job, specify different DDnames and data sets for each invocation of the function, or specify a sequential data set and DISP=MOD in the DD statements.
  8. You need the necessary authority to use the command server queues (SYSTEM.COMMAND.INPUT, SYSTEM.COMMAND.REPLY.MODEL, and SYSTEM.CSQUTIL.*), to use the DISPLAY QUEUE and DISPLAY STGCLASS MQSC commands, and to open the queues that we want to copy with the MQOO_INPUT_EXCLUSIVE and MQOO_BROWSE options.
  9. For the REGION parameter, 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. We must ideally look to limit the REGION size and specify an absolute maximum value that the job is allowed to acquire.

Parent topic: IBM MQ utility program (CSQUTIL) on z/OS