QUEUE TRAN command

The QUEUE TRAN command is defined to OM as ROUTE=ALL. When this command is issued, OM routes the command to all IMS systems that have registered for the command. Depending on the environment, either only the command master IMS processes the command or all IMS process the command. If only the command master processes the command, all other IMS systems that receive the command return with a return and reason code indicating that they are not the IMS command master.

Subsections:

• Environment
• Syntax
• Keywords
• Usage notes
• Output fields
• Return, reason, and completion codes
• Examples

Environment

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

Syntax

Keywords

The following keywords are valid for the QUEUE TRAN command:

NAME(tranname)

Specifies the 1- to 8-character name of the transaction.

DATA(messagedata)

Specifies the message data to enqueue to the transaction. The data is variable in length. This parameter is only valid for OPTION(ENQ). If the COMM macro is defined with OPTION=NOBLANK, DATA is an optional parameter. If the COMM macro is defined with OPTION=BLKREQD (the default), at least one character, even if it is a blank, must be specified in the message data area.

The data can be specified in mixed case. If the transaction is defined as EDIT=ULC, the data is enqueued as it was specified on the command, without any uppercase translation. If the transaction is defined as EDIT=UC, the data is translated to uppercase before the message is enqueued. No EDIT routine is called before the data is enqueued.

The data is enqueued as a single segment message. The maximum length of data that can be enqueued is 32 763.

OPTION()

Specifies the option parameters:

ENQ

This is the default. Indicates that a message is to be enqueued to the specified transaction. The ENQ function is processed only by the command master IMS in both the local queues and shared-queues environment. Any output generated by the transaction is sent as an unsolicited output message to the OM that originated the command. Any MFS formatting associated with the output message is not returned.

The transaction specified for the ENQ cannot be full-function response mode or a Fast Path transaction. The initiated transaction can be conversational, but it cannot be in conversational mode with OM.

DEQALL

Indicates that all messages currently enqueued to the transaction should be dequeued and discarded. The transaction must be stopped before messages can be dequeued.

DEQALL is valid in both local queues environment and the shared-queues environment. If IMS is in the local queues environment, all IMS systems that receive the command process the QUEUE TRAN OPTION(DEQALL) command. If IMS is in the shared-queues environment, only the command master IMS processes the QUEUE TRAN OPTION(DEQALL) command.

A QUEUE TRAN OPTION(DEQALL) command can dequeue transaction messages queued to a 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.

DEQ1

Indicates that the first (oldest) message on the queue for the transaction should be dequeued and discarded. The transaction must be stopped before the message can be dequeued.

A QUEUE TRAN OPTION(DEQ1) command can dequeue transaction messages queued to a 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.

Usage notes

This command is processed if the transaction is defined locally at the IMS system. If the transaction is not defined at the IMS system, the Destination Creation exit routine, DFSINSX0, is called. If the exit routine successfully creates a transaction, the command is processed. If the exit does not create a transaction, a response line is returned with an error completion code indicating that the transaction is not found.

The effect of this command differs depending on whether the IMS processing it uses RM's resource structure. If it does use the resource structure, a message can be enqueued even if the transaction is stopped locally if the transaction does not have a global status of STOQ. To dequeue one or all messages, however, the transaction must be stopped globally and locally for scheduling (STOSCHD). If the IMS does not use the resource structure, no messages can be enqueued if the transaction is stopped for queuing (STOQ). To dequeue one or all messages, the transaction must be stopped for scheduling (STOSCHD).

The QUEUE TRAN OPTION(ENQ) command is not supported for conversational, response mode, Fast Path, and remote transactions. This form of the command performs security checking on the transaction name and on the user ID that issued the command. For OPTION(ENQ), workload management (WLM) CLASSIFY calls are issued using information passed to the OM from the command. The information passed includes LUNAME=DFSOMAPI and the user ID. Also for OPTION(ENQ), if the transaction name specified is a remote transaction, the message is placed on the shared queues (on the transaction ready queue) using the remote transaction name. The command is not processed if the MSNAME associated with the remote transaction is stopped. The TM and MSC Message Routing and Control user exit routine, DFSMSCE0, is not called for a QUEUE TRAN command.

The maximum length of the data that can be enqueued is 32 763 bytes. The data is enqueued to the transaction as a single segment.

8 byte transactionname + 8 byte IMSID + output message

Output fields

Return, reason, and completion codes

Commands that are issued through the OM API, including QUEUE TRAN, produce a standard set of OM return and reason codes, which are defined in CSLORR.

The following table includes the return and reason codes and a brief explanation of the codes. The return or reason code returned for the command might also indicate an error from a CSL request.

The following table contains completion codes that can be returned on a QUEUE TRAN command.