>>-+-/DEQUEUE-+-------------------------------------------------> '-/DEQ-----' >--+-AOITKN--aoitokenname--------------------------------+----->< +-LINE--line#--PTERM--pterm#--| A |-------------------+ +-LTERM--ltermname--+--------+------------------------+ | +-PURGE--+ | | '-PURGE1-' | +-LU--luname--TPNAME--tpname--+-PURGE--+--------------+ | '-PURGE1-' | +-MSNAME--msname--+-PURGE--+--------------------------+ | '-PURGE1-' | +-NODE--nodename--+----------------+--| A |-----------+ | '-USER--username-' | +-SUSPEND---------------------------------------------+ +-TMEM--tmembername--+------------------+--+-PURGE--+-+ | '-TPIPE--tpipename-' '-PURGE1-' | +-TRAN--tranname--+-PURGE--+--------------------------+ | '-PURGE1-' | '-USER--username--| A |-------------------------------' A: |--+------------------------------+-----------------------------| +-PURGE------------------------+ '-LTERM--ltermname--+--------+-' +-PURGE--+ '-PURGE1-'
Table 42 lists the environments (DB/DC, DBCTL, and DCCTL) from which the command and keywords can be issued.
Command / Keywords | DB/DC | DBCTL | DCCTL |
---|---|---|---|
/DEQUEUE | X | X | X |
AOITKN | X | X | X |
LINE | X | X | |
LTERM | X | X | |
LU | X | X | |
MSNAME | X | X | |
NODE | X | X | |
PTERM | X | X | |
PURGE | X | X | |
PURGE1 | X | X | |
SUSPEND | X | X | |
TMEM | X | X | |
TPIPE | X | X | |
TPNAME | X | X | |
TRAN | X | X | |
USER | X | X |
The /DEQUEUE command with any of the following keywords is used to cancel a message that is being processed: LINE, LTERM, LUNAME, MSNAME, NODE, TRANSACTION, or USER. Also, a /DEQUEUE command dequeues messages from either the local queues, or in a shared-queues environment, the shared queues. An output message displays the total count of all messages dequeued.
/DEQUEUE AOITOKEN is used to dequeue and discard messages associated with the specified AOI token name.
A /DEQUEUE command with any of the following keywords activates the Message Control Error exit routine, DFSCMUX0, before processing each message: LTERM, LUNAME TPNAME, NODE, or MSNAME. The user exit routine can request IMS to:
/DEQUEUE SUSPEND schedules transactions that have been suspended by IMS.
/DEQUEUE TMEMBER TPIPE dequeues messages associated with an IMS Open Transaction Manager Access (OTMA) transaction pipe.
The /DEQUEUE NODE command dequeues messages from the local or shared queues for statically defined terminals. If PURGE or PURGE1 is specified, the node must be stopped and idle. Without PURGE or PURGE1, the message actively being sent is dequeued.
The /DEQUEUE LTERM command dequeues messages from the local or shared queues. The user must be stopped (by a /STOP USER command), and not in conversation, in order to enter /DEQUEUE USER or /DEQUEUE LTERM with PURGE or PURGE1. In a shared queues and ETO environment where the user doesn't exist, /DEQUEUE LTERM with PURGE or PURGE1 creates a user structure in order to dequeue messages from the shared queues.
/DEQUEUE NODE nodename LTERM is not valid for nodes with users. The user that contains the LTERM must be allocated and the session must be active.
If the PURGE or PURGE1 keyword is specified and the LTERM is associated with a user with DEADQ status, the DEADQ status will be reset.
If the DEADQ status is on, the following command turns it off for the user associated with LTERM ltermname:
/DEQUEUE LTERM ltermname (PURGE/PURGE1)
The DEADQ status is removed by signing the user on or by issuing /DEQUEUE to dequeue one or more messages.
Either the PURGE or PURGE1 option must be specified, and the LU 6.2 destination must be stopped and not active; if both actions are not taken, error messages are issued.
The following command is not valid for nodes with users:
/DEQUEUE NODE nodename
/DEQUEUE NODE nodename LTERM ltermname
The following command cancels the output message currently being sent to the specified ISC session, and the user must be allocated to the node and the session must be active:
/DEQUEUE NODE nodename USER username
If PURGE or PURGE1 is specified, the node must be stopped and idle. Without PURGE and PURGE1, if an ETO node or an ISC static parallel session, the USER keyword is required.
If the PURGE keyword is specified, and the NODE is associated with a user with DEADQ status, the DEADQ status will be reset.
Messages cannot be canceled with PURGE if they are destined for the MTO or for terminals or users in response mode, Fast Path, or conversation mode. /DEQUEUE PURGE does not cancel messages destined for the master terminal operator because the master terminal cannot be stopped, disconnected, or idled. /EXIT should be used for a terminal in conversation mode.
If the terminal is a dynamic 3600/FINANCE, SLU P, or ISC terminal, the NODE keyword is only valid if the session is stopped and idle, and the LTERMs are still allocated to the terminal pending message resynchronization. For example,
/DEQUEUE NODE nodename USER username (LTERM ltermname) PURGE
is valid for the allocated user only if the specified ISC session is stopped and idled.
Messages queued to LTERMs associated with users that are not signed on can be purged by specifying the LTERM keyword without the NODE keyword. NODE with the USER keyword applies to ISC sessions and dynamic terminals and is only valid if the user is still allocated to the node. However, the line or node must be stopped and idled.
If USER is specified and the user had DEADQ status, the DEADQ status is removed. If LTERM or NODE is specified and the LTERM or node is associated with a user with DEADQ status, the DEADQ status is removed.
/DEQUEUE LTERM PURGE1 removes the first message from the queue. The order of search for messages to be removed is:
Using a synonym for PURGE1 avoids the potential danger of omitting the trailing digit on PURGE1 and canceling all the messages enqueued. Synonyms for PURGE1 are SINGLE, SNGL, and FIRST.
When PURGE1 is specified, the terminal must be stopped and idle and not in conversation mode. If the message is in the process of being actively sent, /DEQUEUE without PURGE1 cancels the message.
Another use for /DEQUEUE SUSPEND is to release those transactions queued because the installation specified the requeue region error option in the external subsystem PROCLIB member for a particular subsystem. Transactions will be queued if the subsystem connection terminates in an abnormal fashion (for example, dependent region abend, subsystem abnormal termination).
In a shared-queues environment, a /DEQUEUE SUSPEND command moves all transactions on the Transaction Suspend queue to the Transaction Ready queue and makes them eligible for rescheduling. The "suspend" status for the transactions is also reset locally (on the IMS subsystem that entered the command), but is not reset across the sysplex. To reset the "suspend" status across a sysplex, use the /START TRANSACTION command on each IMS subsystem.
You can also use the /START TRANSACTION command to reschedule a specific transaction that has been suspended.
/DISPLAY TRANSACTION and /DISPLAY STATUS can be used to determine whether a transaction has messages on its suspend queue.
Restriction: This keyword is valid only in a shared-queues environment.
Recommendation: Stop the transaction on all IMS subsystems in the shared queues group before issuing the /DEQUEUE TRANSACTION command. If you do not, the IMS subsystem that processes the /DEQUEUE could dequeue a message it does not own and that another IMS subsystem might need.
A /DEQUEUE TRANSACTION command does not dequeue messages enqueued for suspended transactions.
Entry ET:
/DEQUEUE AOITOKEN ABCDE
Response ET:
DFS058I DEQUEUE COMMAND COMPLETED
Explanation: The messages on AOITOKEN ABCDE are dequeued and discarded.
Entry ET:
/DEQUEUE LINE 5 PTERM 2
Response ET:
DFS058I DEQUEUE COMMAND COMPLETED
Explanation: The message is terminated on successful completion of the current transmission.
Entry ET:
/DEQUEUE LTERM ABCDE PURGE
Response ET:
DFS976I 2 MESSAGE(S) PURGED
Explanation: Two messages are dequeued for LTERM ABCDE (the line is stopped and idle as required).
Entry ET:
/DEQUEUE LTERM ABCDE PURGE1
Response ET:
DFS058I DEQUEUE COMMAND COMPLETED
Explanation: The message is dequeued for LTERM ABCDE.
Entry ET:
/DEQ LUNAME 'NETWORK1.LUNAME1' TPNAME TPNAME1 PURGE
Response ET:
DFS1952 10:51:35 DESTINATION NOT FOUND
Explanation: An invalid APPC destination was entered.
Entry ET:
/DEQ LUNAME 'CICSNET.SERVER1' TPNAME DFSASYNC PURGE1
Response ET:
DFS976I 14:10:25 1 MESSAGE(S) PURGED
Explanation: The message was dequeued from the APPC destination LUNAME CICSNET.SERVER, TPNAME DFSASYNC.