QUERY NODE command

For ISC TCP/IP nodes, the command also displays the IMS Connect instance that provides the TCP/IP support.

This command can be specified only through the OM API and is valid on an XRF alternate.

Subsections:

• Environment
• Syntax
• Keywords
• Usage notes
• Equivalent IMS type-1 commands
• Output fields
• QUERY NODE status
• 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.

Keywords

The following keywords are valid for the QUERY NODE command:

NAME()

Specifies the names of one or more VTAM nodes (terminals) or non-VTAM devices that are to be displayed. Valid names are 1-8 characters, and wildcards can be specified. To display all nodes and devices, specify NAME(*). NAME(*) is the default.

Any static or dynamic VTAM terminal name can be specified. Supported terminal types are LU0, LU1, LU2, and LU6.1 (ISC only).

Any non-VTAM device can be specified. Non-VTAM devices are assigned a LINE and PTERM number during the system definition process. Supported device types are CONSOLE, SYSOUT (DISK, PUNCH, PRINTER, READER, TAPE), SPOOL, and TCO:

CONSOLE

This is the system console. IMS automatically assigns LINE 1 PTERM 1 to this device.

DISK

Defined by the LINEGRP macro, UNITYPE=DISK.

PUNCH

Defined by the LINEGRP macro, UNITYPE=PUNCH.

PRINTER

Defined by the LINEGRP macro, UNITYPE=PRINTER.

READER

Defined by the LINEGRP macro, UNITYPE=READER.

SPOOL

Defined by the LINEGRP macro, UNITYPE=SPOOL.

TAPE

Defined by the LINEGRP macro, UNITYPE=TAPE.

TCO

This is the device assigned as the Time Control Option. The system definition process automatically assigns the last LINE number to this device.

To specify a non-VTAM device, specify a name of DFSLNxxx, where xxx is the LINE number of the device. For example, to display the system console (LINE 1), specify NAME(DFSLN001).

SHOW()

Specifies the node output fields to be returned.

The node name is always returned along with the name of the IMS that created the output and the completion code. If SHOW is not specified, only the node names are returned, provided that the STATUS filter is not specified. This provides a method for a system management application to obtain a list of all node names that are currently known in the IMSplex.

Two parameters, GLOBAL and LOCAL, are used to specify the location (global resources or local resources) where IMS should obtain the information that is to be displayed. The default is both GLOBAL and LOCAL.

The rest of the parameters are used to specify what information is displayed.

The parameters supported with the SHOW keyword, which can be specified in any order, are:

ALL

Returns all of the output fields, except for those fields displayed when the LTERM and CONV parameters are specified. To display LTERM and conversation information with all other output, specify SHOW(ALL,LTERM,CONV).

AFFIN

IMS APPLID to which the node has VTAM generic resource affinity, if applicable. VTAM generic resource affinity is valid only when the GLOBAL parameter is specified on the SHOW keyword. If GLOBAL is not specified, then the AFFIN parameter is ignored.

CICSAPPL

For ISC TCP/IP nodes, displays the APPLID of the remote CICS® subsystem.

CICSNETID

For ISC TCP/IP nodes, displays the NETWORK ID of the remote CICS.

CID

VTAM connection identifier.

CONV

The conversation ID, transaction, and conversation status associated with the node. Each conversation is returned on a separate command response display line. Conversation status is not included when SHOW(ALL) is specified. To display conversation information with all other output, specify SHOW(ALL,CONV).

COUNT

Displays the number of messages sent to and received from the specified node.

EMHQ

Displays the node message queue count in the Expedited Message Handler (EMH) queues. The queue count is the sum of the queue counts for each logical terminal associated with the specified node.

EMHQ is valid only when the GLOBAL parameter is specified on the SHOW keyword. If GLOBAL is not specified, then the EMHQ parameter is ignored.

EMHQ is processed by the command master only. It is ignored by all other IMS systems.

EMHQ is valid only if shared EMH is used in a shared queues environment. Otherwise, this parameter is ignored.

If the node resource exists in the resource structure, then the logical terminals associated with the global node resource are used to obtain the queue counts from the EMH queues. Otherwise, the logical terminals associated with the local node resource are used, but if the node does not exist locally on the command master, then the queue count is 0.

GLOBAL

If GLOBAL is specified, the command master displays global information, depending on the other SHOW parameters specified. This includes information from the resource structure.

The GLOBAL parameter is processed by the command master only. All other IMS systems ignore this parameter. If LOCAL is not also specified, then all IMS systems other than the command master ignore the command.

GLOBAL is applicable only when the command master is using shared queues, VTAM generic resources, sysplex terminal management, or any combination of these. GLOBAL is not applicable when the command master is not using shared queues, VTAM generic resources, or sysplex terminal management. In this environment, if LOCAL is also specified, then GLOBAL is ignored. Otherwise, the command master rejects the command.

If shared queues are enabled, and global queue counts are requested, then the command master will make requests to CQS to determine the appropriate queue counts. This includes both MSGQ and EMHQ.

If VTAM generic resources (VGR) is enabled, and VGR affinity information is requested, then the command master will make requests to VTAM to determine any VGR affinity.

If sysplex terminal management is enabled, then the command master will make requests to RM to determine the appropriate global status.

If both GLOBAL and LOCAL are specified (which is the default), then the command master builds global and local information separately. Global information is displayed as one output line (or set of output lines), and local information is displayed as another output line (or set of output lines).

ID

Displays the other half-session qualifier name of the ISC node.

IMSCON

For ISC TCP/IP nodes, shows the IMSplex member name of the IMS Connect instance that provides TCP/IP support for the node.

LOCAL

If LOCAL is specified, then all IMS systems including the command master display local information, depending on the other SHOW parameters specified. This includes information local to the IMS processing the command.

The LOCAL parameter is processed by all IMS systems, including the command master. LOCAL is applicable in any environment, regardless of whether shared queues or sysplex terminal management are used.

If both GLOBAL and LOCAL are specified (which is the default), then the command master builds global and local information separately. Global information is displayed as one output line (or set of output lines), and local information is displayed as another output line (or set of output lines).

LOGOND

For ISC TCP/IP nodes, displays the name of the ETO logon descriptor that was used to establish the session in use by the node.

LTERM

Displays the logical terminal (LTERM) names, if any, associated with the node. A node may have zero or more logical terminals associated with it.

Each logical terminal associated with the node is returned on a separate command response line.

The LTERM status is not included when SHOW(ALL) is specified. To display logical terminal information with all other output, specify SHOW(ALL,LTERM).

MODETBL

Displays the mode table names that are associated with the specified nodes. The output includes both the default mode table name and the actual mode table name. The default mode table name is the default name that is set by system definition. This name can be modified by the LOGON exit. The actual mode table name is the actual name used to initiate the session. This name is displayed only while the session is active, and is blank at all other times.

OWNER

Displays the owner of the node resource in the resource structure. This applies only when sysplex terminal management is enabled, and is only processed by the command master. All other IMS systems ignore this parameter.

The owner is the IMSID (or RSENAME for XRF systems) of the IMS system that owns the node. An IMS system owns a node resource if the resource is active (the node is logged on), or an IMS system is maintaining significant status for that resource.

PRESET

Displays the preset destination name for a node. A node is in preset destination mode set by the /SET command. The preset destination name is either a transaction name, or a logical terminal (LTERM) name. All messages entered from this node are sent to the preset destination transaction or LTERM.

QCNT

Displays the node message queue count. The queue count is the sum of the queue counts for each logical terminal associated with the specified node.

The local queue counts value returned on this command represents the messages being processed by the IMS system where this command is issued. In a shared-queues environment, do not use the local queue counts for queue evaluation purposes. The global queue counts, which are returned on this command, represent the current message queue counts on the shared queues structure.

If the LOCAL parameter is also specified on the SHOW keyword, then all IMS systems that process the command, including the command master, display the local queue count. This is valid whether or not shared message queues are enabled.

If the GLOBAL parameter is also specified on the SHOW keyword, and shared message queues are enabled, then the command master displays the global queue count on the shared message queues (MSGQ). If the node resource exists in the resource structure, then the logical terminals associated with the global node resource are used to obtain the queue counts from shared queues. Otherwise, the logical terminals associated with the local node resource are used, but if the node does not exist locally on the command master, then the queue count is 0.

The local and global queue counts are displayed as separate output fields.

RECOVERY

Displays the status recovery mode (SRM) and level of recovery for the node. End-user significant status can be conversation, Fast Path, full-function response mode, or STSN (set-and-test-sequence-number) status.

SRM determines where end-user significant status, if any exists, is recovered following a session or IMS termination. The output displays the SRM for the node as either GLOBAL (sysplex terminal management recovers it in the resource structure), LOCAL (IMS recovers it locally, which indicates an affinity to a particular IMS), or NONE (status is discarded).

Level of recovery determines what end-user significant status, if any exists, is recovered (if SRM is GLOBAL or LOCAL). The output displays whether conversation status is recovered (RCVYCONV), Fast Path status is recovered (RCVYFP), full-function response mode is recovered (RCVYRESP), and STSN status is recovered (RCVYSTSN).

STATUS

Returns local or global status of the node. See QUERY NODE status for a list and meaning of possible status that might be returned.

TYPE

VTAM node type. The possible node types are AVM, FIN, LUT6, NTO, SLUP, SLU1, SLU2, 3277, 3286, 3790, CONSOLE, RDR/PTR (for SYSOUT and SPOOL), and TCO.

USER

Displays the dynamic or ISC user associated with the node. For ISC parallel-session nodes, this is the user structure representing the half-session qualifier. For static ISC, this is defined with the SUBPOOL macro. For non-ISC dynamic nodes, this is the user structure allocated to the node during signon of a user ID to the node. The user name might or might not be the same as the user ID, depending on installation-specific user exits or descriptors used. Static non-ISC nodes (and single-session ISC nodes) do not have users (even if a user ID is signed on).

USERID

Displays the user ID (for security, usually RACF®), signed on to the node. This is applicable to any device type, static or dynamic, and is distinct from the user name.

VERSION

Displays the version number assigned to RM resources, which is assigned by MVS™, and maintained by RM, when the resources are created or updated in the resource structure.

Static single-session nodes (not parallel-session ISC) are represented in RM by two resources: the node resource, and the static-node-user resource. The VERSION parameter displays the version number for each of these resources. Static parallel-session ISC nodes and all dynamic nodes are represented in RM by one resource: the node resource. The VERSION parameter displays the version number of the node resource.

VERSION applies only when sysplex terminal management is enabled. VERSION is ignored when sysplex terminal management is not enabled.

STATUS()

Selects nodes for display that possess at least one of the specified node statuses. The status might exist locally or globally if sysplex terminal management (STM) is enabled.

The STATUS filter is valid in both a sysplex terminal management environment and in a non-sysplex terminal management environment. In a sysplex terminal management environment, the status selected might exist locally, globally, or both. If sysplex terminal management is not enabled, then the status only exists locally.

If SHOW(LOCAL) is specified, then IMS will select only those nodes with the appropriate status in the local system. The command is processed by all IMS systems, including the command master.

If SHOW(GLOBAL) is specified, and sysplex terminal management is enabled, then IMS will select only those nodes with the appropriate status in the resource structure. The command is processed only by the command master.

If SHOW(GLOBAL) is specified, but sysplex terminal management is not enabled, then the command is rejected.

If SHOW(GLOBAL,LOCAL) is specified (the default), then IMS will select those nodes with the appropriate status either locally or in the resource structure (if sysplex terminal management is enabled). The command is processed by all IMS systems. The command master processes both global and local information.

The output returned when the status filter is specified includes the status of the node, even if SHOW(STATUS) is not specified.

See QUERY NODE status to determine which filters can be used to select nodes with corresponding status.

USER()

For a specific ISC node, specifies the names of one or more ISC user names allocated to the node. Valid names are 1-8 characters, and wildcards can be specified. To display all users allocated to the node, specify USER(*), or omit the USER keyword.

The output returned includes the user name even if SHOW(USER) is not specified.

Usage notes

QUERY NODE can be specified only through the OM API.

QUERY NODE can be issued on an XRF alternate system, but SHOW(GLOBAL) is not supported. Only local information can be displayed.

The processing of the QUERY NODE command is different depending on whether IMS sysplex terminal management is enabled.

• If IMS sysplex terminal management is not enabled, processing is local for each system. The results of type-1 and type-2 commands are similar.
• If IMS sysplex terminal management is enabled, type-1 and type-2 command processing is similar when displaying local information. However, they differ in how global information is displayed.
• For type-1 /DISPLAY commands with IMS sysplex terminal management enabled, the command master displays information from either the resource structure or the local system, but not both. If the resource being displayed is not owned by any system or is owned by the command master, the command master displays the global resource. However, if the resource is owned by a system other than the command master, the command master displays only the local resource, and the owning system is responsible for displaying the global resource.
• For type-2 QUERY commands with IMS sysplex terminal management enabled, the command master is the only system that displays global resource information, regardless of whether the resource is owned. In addition, the command master displays local resource information. All other IMS systems that process the command display local resource information only. This approach allows more flexibility in displaying all information in an IMSplex.

The SHOW keyword determines which IMS systems process the command and what information is displayed.

• If SHOW(GLOBAL) is specified, then the command master displays global information, which includes the global queue count if shared queues are enabled, generic resource affinity information if VTAM generic resource (VGR) is enabled, and status from the resource structure if sysplex terminal management is enabled (STM=YES defined in DFSDCxxx PROCLIB member). This is true whether or not the node is active on any particular IMS system. All other IMS systems to which OM routes the command ignore the GLOBAL parameter with return code X'00000004' and reason code X'00001000'.
• If SHOW(LOCAL) is specified, then each IMS system to which OM routes the command (including the command master) processes the command, and displays information that is local to each system.
• If both GLOBAL and LOCAL are specified (which is the default), then the command master displays both global and local information, and all other IMS systems to which OM routes the command displays local information.

Equivalent IMS type-1 commands

The following table shows variations of the QUERY NODE command and the type-1 IMS commands that perform similar functions.

Output fields

QUERY NODE status

The following table shows the possible node status that can be displayed. The columns in the table are:

Status

The node status that is displayed.

STATUS parameter

The STATUS() filter that will select nodes with the specified status.

Scope

The scope of the status. GBL indicates that the status can be global (it exists in the resource structure when STM is enabled), and is returned with the STT short label. LCL indicates that the status can be local, and is returned with the LSTT short label.

Meaning

Provides a brief description of the status.

Return, reason, and completion codes

An IMS return and reason code is returned to OM by the QUERY NODE command. The OM return and reason codes that may be returned as a result of the QUERY NODE command are standard for all commands entered through the OM API.

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 includes an explanation of the completion codes. Errors unique to the processing of this command are returned as completion codes. A completion code is returned for each action against an individual resource.