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

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

The scope of the SCOPY 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 queues.

To use the SCOPY function, DDname CSQP0000 must specify the data set with page set zero for the subsystem required. Note: The SCOPY function does not operate on shared queues.


Queue Management (SCOPY)

SCOPY 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.

    DDname CSQP00 nn must specify the data set with page set nn for the subsystem required, where nn is the number of the page set where the queue resides.

    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.

    DDname CSQP00 psid-number must specify the data set with the required page set for the subsystem required.

    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.

    This parameter is only valid if we specify PSID.

    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).

    Do not specify the same DDname on more than one SCOPY statement, unless its DD statement specifies a sequential data set with DISP=MOD.


Example

Figure 1. Sample JCL for the CSQUTIL SCOPY functions. The sample shows two instances of the SCOPY function; one SCOPY to the default DDNAME, CSQUOUT; the other to DDNAME OUTPUTA, which overrides CSQUOUT. 
//SCOPY   EXEC PGM=CSQUTIL,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)
//CSQP0000 DD DISP=OLD,DSN=pageset.dsname0
//CSQP0003 DD DISP=OLD,DSN=pageset.dsname3
//CSQP0006 DD DISP=OLD,DSN=pageset.dsname6
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
* COPY WHOLE PAGE SET TO 'CSQUOUT'
SCOPY PSID(03)
* COPY ONE QUEUE TO 'OUTPUT' - QUEUE IS ON PAGE SET 6
SCOPY QUEUE(ABC123A) DDNAME(OUTPUTA)
/*


Usage notes

  1. Do not use SCOPY for a queue manager that is running because results are unpredictable. We can avoid doing this accidentally by using DISP=OLD in the page set DD statement.
  2. When we use SCOPY, we do not need to specify a queue manager name.
  3. To operate on a range of page sets, repeat the SCOPY function for each page set.
  4. The function operates only on local queues and only for persistent messages.
  5. An SCOPY PSID function is considered successful only if it successfully copies all the queues on the page set. If an empty queue is processed, data indicating this is written to the sequential data set. If the page set has no queues, the SCOPY function fails, and no data is written to the data set.
  6. If you try to copy an empty queue explicitly by SCOPY QUEUE, 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, the SCOPY function fails, and no data is written to the data set.
  7. If the SCOPY function fails, no further CSQUTIL functions are attempted.
  8. To use the SCOPY 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.
  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