IMS Version 9

/DEQUEUE

Format

Read syntax diagramSkip visual syntax diagram>>-+-/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-'

Environments and Keywords

Table 42 lists the environments (DB/DC, DBCTL, and DCCTL) from which the command and keywords can be issued.

Table 42. Valid Environments for the /DEQUEUE Command and Keywords
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

Usage

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.

AOITOKEN
Dequeues and discards all messages associated with the specified AOI token name.
LINE PTERM
Cancels the output message currently being sent to the specified physical terminal on the specified communication line.
LTERM
Cancels the output message currently being sent to the specified logical terminal.

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

LUNAME TPNAME
Specifies the LU name and TP name of the LU 6.2 destination from which messages are discarded. A normal (non-qualified) or fully network qualified LUNAME is required for the LUNAME keyword.

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.

MSNAME
Cancels the output message currently being sent to the specified MSC link. Either PURGE or PURGE1 is required for this link. The MSC link must be stopped by the /PSTOP LINK command before issuing the /DEQUEUE MSNAME command.
NODE
Cancels the output message currently being sent to the specified VTAM node.

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.

PURGE
Cancels all output messages enqueued to the specified LINE, LTERM, LUNAME, MSNAME, NODE, TMEMBER, TPIPE, or USER. PURGE allows cancellation of all output messages enqueued to an LTERM, or to a PTERM without regard to the LTERM. A /DEQUEUE command without PURGE cancels an in-progress output message on the specified terminal and, optionally, LTERM. If the NODE and LTERM keywords have both been supplied, the LTERM must be a valid LTERM of the user currently associated with the node.

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.

PURGE1
Cancels the first message queued to the specified LTERM. The PURGE1 and PURGE keywords are mutually exclusive.

/DEQUEUE LTERM PURGE1 removes the first message from the queue. The order of search for messages to be removed is:

  1. Fast Path
  2. Response mode
  3. Exclusive mode messages
  4. System messages
  5. All other messages

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.

SUSPEND
Reschedules transactions that have been suspended by IMS. SUSPEND applies to IMS systems sharing data at the block level and to connected external subsystems (not CCTL subsystems). /DEQUEUE SUSPEND causes all message-driven transactions that have been suspended to be rescheduled. When a failed IMS system is restarted, /DEQUEUE SUSPEND informs the currently running IMS system to reschedule any message-driven transactions on its SUSPEND queue. However, when the failed subsystem has global locks retained and cannot communicate the release of those locks to the other subsystems, /DEQUEUE SUSPEND is used to reschedule these message-driven transactions in the other subsystems. This can occur when:

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.

TMEMBER
Dequeues messages from the OTMA transaction pipe structure specified as tpipename. Using the /DEQ command can make OTMA message resynchronization impossible. And if resynchronization is in progress for the specified transaction pipe, IMS rejects the command and issues message DFS2392I.
TPIPE
Is used with the /DEQUEUE command to dequeue messages associated with an OTMA transaction pipe.
TRANSACTION
Dequeues one or more messages from the transaction specified. The transaction name is a 1- to 8-byte name. The transaction must be stopped for messages to be dequeued.

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.

USER (LTERM)
Dequeues all messages associated with all LTERMs (or a specific) LTERM assigned to that USER. The user must be stopped and not in conversation in order to enter /DEQUEUE USER with PURGE and PURGE1. /DEQUEUE USER with PURGE1 or /DEQUEUE USER LTERM without PURGE or PURGE1 requires the LTERM keyword. If a user is signed on, /DEQUEUE USER LTERM can be used to cancel an output message that is currently being processed. When the purge options are used, messages destined for the MTO and users in response mode, Fast Path, and conversation cannot be canceled. If the USER and LTERM keywords have both been supplied, the LTERM must be a valid LTERM of the specified USER.

If the user has DEADQ status, the DEADQ status is removed.

Examples

Example 1 for /DEQUEUE Command

Entry ET:

  /DEQUEUE AOITOKEN ABCDE

Response ET:

  DFS058I DEQUEUE COMMAND COMPLETED

Explanation: The messages on AOITOKEN ABCDE are dequeued and discarded.

Example 2 for /DEQUEUE Command

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.

Example 3 for /DEQUEUE Command

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

Example 4 for /DEQUEUE Command

Entry ET:

  /DEQUEUE LTERM ABCDE PURGE1

Response ET:

  DFS058I  DEQUEUE COMMAND COMPLETED

Explanation: The message is dequeued for LTERM ABCDE.

Example 5 for /DEQUEUE Command

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.

Example 6 for /DEQUEUE Command

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.

Go to the previous page Go to the next page

IBM Confidential

Downloads | Library | Support | Support Policy | Terms of use | Feedback
Copyright: IBM Corporation 1974, 2004 Copyright IBM Corporation 1974, 2004  timestamp Last updated: March, 2004