Emptying a queue of all messages (EMPTY) on z/OS

We can use the EMPTY function of CSQUTIL to delete all messages from a named queue or all the queues on a page set.

The queue manager must be running. The scope of the function is determined by the keyword that you specify in the first parameter.

Use this function with care. Only delete messages of which copies have already been made. Note: See Syncpoints for information about how to avoid problems with duplicate messages if this function fails.


Queue management (EMPTY)

EMPTY Object SelectionObject SelectionQUEUE(q-name)PSID(psid-number)


Keywords and parameters

We must specify the scope of the EMPTY function. Choose one of these:

    QUEUE(q-name)
    Specifies that messages are to be deleted from a named queue. This keyword can be abbreviated to Q.

    q-name specifies the name of the queue from which messages are to be deleted. This name is case sensitive.

    PSID(psid-number)
    Specifies that all the messages are to be deleted from all queues in the named page set.

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


Example

Figure 1. Sample JCL for the CSQUTIL EMPTY function
//EMPTY  EXEC PGM=CSQUTIL,PARM=('CSQ1')
//STEPLIB  DD   DISP=SHR,DSN=thlqual.SCSQANLE
//         DD   DISP=SHR,DSN=thlqual.SCSQAUTH
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
EMPTY QUEUE(SPARE)
EMPTY PSID(66)
/*


Usage notes

  1. The queues involved must not be in use when the function is invoked.
  2. This function operates only on local queues.
  3. To operate on a range of page sets, repeat the EMPTY function for each page set.
  4. We cannot empty the system-command input queue (SYSTEM.COMMAND.INPUT).
  5. An EMPTY PSID function is considered successful only if it successfully empties all the queues on the page set.
  6. If you empty a queue that is already empty (either explicitly by EMPTY QUEUE or because there are one or more empty queues on a page set that we are emptying), the EMPTY function is considered to be a success. However, if you attempt to empty a nonexistent queue, or a page set containing no queues, the EMPTY function fails.
  7. If EMPTY fails or is forced to take a syncpoint, no further CSQUTIL functions are attempted.
  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 use the IBM MQ API to get messages from the queues that we want to empty.

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


Related concepts