/DEQUEUE command

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.

Subsections:

• Environment
• Syntax
• Keywords
• Usage notes
• Examples

Environment

The following table lists the environments (DB/DC, DBCTL, and DCCTL) in which you can use the command and keywords.

Syntax

A

Keywords

The following keywords are valid for the /DEQUEUE command:

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 the /DEQUEUE command to dequeue one or more messages.

Important: Both the USER and the LTERM blocks must exist in either the IMS system or the Resource Manager (RM) resource structure. Otherwise, a DFS189 error message might occur when the /DEQUEUE LTERM ltermname (PURGE/PURGE1) command is issued for a dynamic LTERM in a shared-queue environment with STM=YES specified. To solve this problem, see the instructions in DFS189.

When the /DEQUEUE LTERM ltermname (PURGE/PURGE1) command is successfully completed, issue a /START USER command to reset the user status so that the user structure can be deleted at the next checkpoint.

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.

Note: A fully qualified LU name must be specified in single quotation marks.

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.

In a shared-queues environment, only messages that are owned by the command processing IMS are dequeued. Inflight synchronous output messages are not dequeued. Any stranded synchronous output messages with affinity to the command processing IMS are dequeued.

If you used a side information entry name to place messages on the queues, to dequeue those messages, specify the side information entry name for the LU name and the character string DFSSIDE for the TP name.

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

Restrictions for using NODE and USER parameters together:

• Commands with the NODE USER keyword pair are valid only if:
  • The USER is signed on to the NODE
  • In an ISC environment, the USER is allocated to the NODE
  • The nodes and users already exist
• /DEQUEUE NODE USER LTERM commands are valid for ISC and non-ISC nodes and users.
• /DEQUEUE NODE USER PURGE commands and /DEQUEUE NODE USER LTERM PURGE1 commands are valid for ISC, LUP, and 3600 nodes only.

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, TMEM, TPIPE, or USER. The PURGE keyword 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 or conversation mode. The /DEQUEUE PURGE command does not cancel messages destined for the master terminal operator because the master terminal cannot be stopped, disconnected, or idled. The /EXIT command 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 valid only if the session is stopped and idle, and the LTERMs are still allocated to the terminal pending message resynchronization. For example, the following command is valid for the allocated user only if the specified ISC session is stopped and idled.

/DEQUEUE NODE nodename USER username (LTERM ltermname) PURGE

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 valid only 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.

The /DEQUEUE LTERM PURGE1 command 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, The /DEQUEUE command 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). The /DEQUEUE SUSPEND command causes all message-driven transactions that have been suspended to be rescheduled. When a failed IMS system is restarted, the /DEQUEUE SUSPEND command 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, the /DEQUEUE SUSPEND command is used to reschedule these message-driven transactions in the other subsystems. This can occur when:

• The still-running IMS has transactions on its SUSPEND queue and the failed IMS has been restarted using the /ERESTART COLDSYS command.
• The still-running IMS terminates before the failed IMS is restarted. Thus, when the failed system is restarted, the other system, which has now terminated, is unable to receive the message to reschedule the transactions on its SUSPEND queue. The operator must issue the /DEQUEUE SUSPEND command to reschedule them.

Another use for the /DEQUEUE SUSPEND command 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 TRAN command on each IMS subsystem.

You can also use the /START TRAN command to reschedule a specific transaction that has been suspended.

The /DISPLAY TRAN and /DISPLAY STATUS commands can be used to determine whether a transaction has messages on its suspend queue.

TMEM TPIPE

Dequeues messages from the specified IMS Open Transaction Manager Access (OTMA) member and transaction pipe. Using the /DEQ command can make OTMA message resynchronization impossible. If resynchronization is in progress for the specified transaction pipe, IMS rejects the command and issues message DFS2392I.

In a shared-queues environment, only messages that are owned by the command processing IMS are dequeued. Inflight synchronous output messages are not dequeued. Any stranded synchronous output messages with affinity to the command processing IMS are dequeued.

TRAN

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 TRAN 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 TRAN command does not dequeue messages enqueued for suspended transactions.

In a shared-queues environment, a /DEQUEUE TRAN command can dequeue transaction messages queued to the transaction from APPC or OTMA Clients. The command only dequeues the transaction messages. The APPC or OTMA transaction instance blocks (TIB) created at the IMS system are not deleted and the storage may remain allocated until the next IMS restart. For APPC, the TIB is not released and the APPC conversation (the client) hangs if there is no timeout value specified. The APPCIOT=(x,Y) timeout value for APPC would deallocate the APPC conversation and release the TIB after the timeout limit has been reached.

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. The /DEQUEUE USER command with PURGE1 or the /DEQUEUE USER LTERM command without PURGE or PURGE1 requires the LTERM keyword. If a user is signed on, the /DEQUEUE USER LTERM command 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.

Usage notes

The DEQUEUE command dequeues messages from an OTMA transaction pipe. CM0 output messages can be placed on the OTMA tpipe using multiple output queue names. A different queue name is used to queue I/O PCB output messages than is used to queue hold queue messages. In the non-super member environment, a CM0 output message could be on the I/O PCB output queue or the member's tpipe hold queue. In the super member environment, a CM0 output message could be on I/O PCB output queue or the super member hold queue.

If the member specified is a regular member, CM0 output messages are dequeued from the member's tpipe hold queue and the member's I/O PCB output queue. If the member specified is a super member, CM0 output messages are dequeued from the super member's output hold queue. The number of messages dequeued depends on whether PURGE or PURGE1 is specified. In the non-shared-queues environment, if the member specified is a regular member, messages are dequeued from the regular member's hold queue first, then from the regular member's I/O PCB output queue. In the shared-queues environment the order in which messages for the same destination are dequeued is not guaranteed. Hold queue messages may be dequeued before I/O PCB output messages one time and I/O PCB output messages may be dequeued before hold queue messages the next.

If IMS cold starts and messages are queued to the same tpipe destination following the cold start, a new set of queue names is used to queue I/O PCB output messages and hold queue messages. In the shared-queues environment with super member enabled, all messages queued to a super member, are placed on the shared queues using the same queue name, even after a cold start of IMS. Messages on the super member's output queue do not have affinity to any IMS. They can be dequeued from any IMS in the IMSplex.

This command can be issued to an IMSplex using the Batch SPOC utility.

The /DEQUEUE NODE command dequeues messages from the local or shared queues for statically defined terminals. 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 does not exist, /DEQUEUE LTERM with PURGE or PURGE1 creates a user structure in order to dequeue messages from the shared queues.