INQUIRE—Obtain logical unit information or application program status

Usage

Several types of INQUIRE exist. The setting of the RPL's option code determines which one is used.

The following descriptions indicate the purpose and use of these options; see the operand descriptions for details regarding how each is specified. For restrictions on the use of the operands, see Table 1. Also, for large networks, see description of INQUIRE OPTCD=APPSTAT in this topic. .

Table 1. Permissible option codes in the INQUIRE macroinstruction
OPTCD= keyword	Same-domain request	Cross-domain request	Issued by primary	Issued by secondary
APPSTAT (Note 3)	YES	YES	YES	YES
CIDXLATE	YES	YES	YES	YES
COUNTS	YES	YES	YES	YES
DEVCHAR	YES	YES (Note 1)	YES	YES
LOGONMSG (Note 1)	YES	YES	YES	NO (Note 2)
NQN (Note 3)	YES	YES	YES	YES
PERSESS	YES	YES	YES	YES
SESSKEY (Note 4)	YES	YES	YES	YES
SESSNAME	YES	YES	YES	YES
SESSPARM (Note 1)	YES	YES	YES	NO
STATUS	YES	YES	YES	YES
TERMS	YES	YES	YES	YES
TOPLOGON (Note 1)	YES	YES	YES	NO (Note 2)
USERVAR	YES	NO	YES	YES

The following notes refer to the preceeding table.

Notes:

Application program can issue only after the CINIT is queued and before the OPNDST or CLSDST macroinstruction is issued to accept or reject the pending active session.
Application program can issue, but VTAM® can return (RTNCD,FDB2)=(X'00',X'07') indicating that the requested information is not available.
These operands are the only options that could cause an external RU to flow into the network.
Application program can issue only after the session is established. If the session is not established, VTAM can return (RTNCD,FDB2)=(X'00',X'07') indicating that the requested information is not available.

Before issuing the INQUIRE macroinstruction, the application program must set register 13 to the address of an 18-word save area. Refer to Summary of register usage, for information pertaining to the register contents upon return of control.

VTAM receives control from the INQUIRE macroinstruction in the addressing mode of the application program that issued the macroinstruction and returns control to the application program in that same mode.

Note: The INQUIRE macroinstruction for OPTCD=NQN differs from other VTAM macroinstructions in that whether a network-qualified name is presented or not is not always dependent on the value specified for PARMS=(NQNAMES=YES) on the ACB macroinstruction. Therefore, an application program can use this type of INQUIRE to translate names without having to change the entire application program to use network-qualified names. Translation is performed on this type of INQUIRE macroinstruction by examining the NIBNET field in the NIB. If NIBNET is not zeros, blanks, or “RECORD ”, the network identifier of the NIB is used in the INQUIRE macroinstruction (real-to-symbolic translation).

APPSTAT: INQUIRE checks a specified application program and determines its capability to establish sessions. In addition, if AREA and AREALEN are included, the network-qualified name of the specified application program is returned. This option can be used to determine the name of the VTAM application currently associated with a USERVAR.
CIDXLATE: Given a session CID, INQUIRE provides the symbolic name of the logical unit that has this session with the application program. Conversely, given the symbolic name of a logical unit with which this application program has one or more sessions, INQUIRE provides the CID of a session with that logical unit.
COUNTS: For the ACB specified, INQUIRE provides the number of active sessions and the number of queued CINIT requests for the application program.
DEVCHAR: INQUIRE obtains certain predefined device characteristics of a logical unit. In general, however, session parameter information (obtained, for example, by INQUIRE OPTCD=SESSPARM) should be used to determine the way to operate a session with the logical unit.
LOGONMSG: INQUIRE obtains the user data (logon message) portion of a queued CINIT that resulted from an initiation of a session between a logical unit and this application program. The user data was part of the original session-initiation request (such as a logon).
NQN: Provides name translation for either a symbolic-to-real or real-to-symbolic request.
PERSESS: INQUIRE enables VTAM to create an NIB for each session pending recovery. The NIB provides the information needed to restore the individual session.
SESSKEY: This provides the session cryptography key and the initial chaining value of a session.
SESSNAME: Allows you to determine the network qualified name of the real instance that a specified LU is currently in session with.
SESSPARM: INQUIRE obtains either a set of session parameters from the logon mode table associated with the specified logical unit, or obtains the session parameter from a CINIT queued for the application program.
STATUS: INQUIRE returns the status of an LU or an application program; it checks the LU or application and determines its capability to establish sessions. In addition, if AREA and AREALEN are included, it returns the network-qualified name of the LU or application program.
TERMS: For a given resource known to VTAM, INQUIRE builds an NIB or list of NIBs for associated logical units. Examples of resources that can be specified are: logical units, physical units, lines, local terminals, application programs, resources in other domains, NCPs, non-SNA major nodes, channel-attached major nodes, switched major nodes, and CDRSC major nodes. Refer to the z/OS Communications Server: SNA Resource Definition Reference for more information on these resources. During VTAM definition, the user can define a resource (such as a PU) that has one or more logical units subordinate to it. These definitions create entries for the resource and the dependent LUs that are subordinate to the resource that is defined to VTAM. If the application program builds one NIB that indicates such an entry in its NAME field, it can then issue INQUIRE to generate NIBs for all of the logical units associated with the entry. Thus, the application program need not be aware of the identities or the number of these logical units before establishing sessions with them. This allows the user, through the VTAM operator or VTAM definition procedures, to change the set of logical units after the application program has been assembled. For additional information, refer to Using INQUIRE OPTCD=TERMS to generate NIBs.
TOPLOGON: Returns the name of the session partner and the CID for the pending active session represented by the oldest queued CINIT received by the application program.
USERVAR: Although USERVAR is allowed to be issued , the actual macroinstruction invocation always returns a successful RTNCD,FDB2 and returns the translated name as the same name passed as input. OPTCD=NQN is the suggested option to be used for name translation requests.

Syntax


>>-+------+--INQUIRE--RPL--=--rpl_address----------------------->
   '-name-'                                 

>--+----------------------------+------------------------------->
   |                        (1) |   
   '-,--ACB--=--acb_address-----'   

>--+-----------------------------------+------------------------>
   |                               (1) |   
   '-,--AREA--=--data_area_address-----'   

>--+-------------------------------------+---------------------->
   |                                 (1) |   
   '-,--AREALEN--=--data_area_length-----'   

>--+-------------------------------+---------------------------->
   |                           (1) |   
   +-,--ARG--=--(--register--)-----+   
   |                        (1)    |   
   '-,--NIB--=--nib_address--------'   

>--+---------------------------+-------------------------------->
   |                       (1) |   
   '-,--BRANCH--=--+-NO--+-----'   
                   '-YES-'         

>--+--------------------------------------+--------------------->
   |                     (1)              |   
   +-,--ECB--=--INTERNAL------------------+   
   +-,--ECB--=--ecb_address---------------+   
   |                                  (1) |   
   '-,--EXIT--=--exit_routine_address-----'   

>--+-----------------------------------------------+-----------><
   |                  (2)                      (1) |   
   '-,--OPTCD--=--(--------+-+-ASY-+------+--)-----'   
                           | '-SYN-'      |            
                           '-+-APPSTAT--+-'            
                             +-CIDXLATE-+              
                             +-COUNTS---+              
                             +-DEVCHAR--+              
                             +-LOGONMSG-+              
                             +-NQN------+              
                             +-PERSESS--+              
                             +-SESSKEY--+              
                             +-SESSNAME-+              
                             +-SESSPARM-+              
                             +-STATUS---+              
                             +-TERMS----+              
                             +-TOPLOGON-+              
                             '-USERVAR--'

Notes:

Operand value can be placed in its RPL field either by specification on an RPL macroinstruction operand or by explicitly setting the field using the IFGRPL DSECT.
You can code more than one suboperand on OPTCD, but code no more than one from each group.

Input parameters

RPL=rpl_address

Indicates the RPL that specifies which kind of processing INQUIRE is to perform.

The following RPL operands apply to the INQUIRE macroinstruction:

ACB=acb_address

Indicates the ACB that identifies the application program issuing INQUIRE.

AREA=data_area_address

Indicates where the information produced by INQUIRE is to be placed.

The AREA operand must be coded with each INQUIRE macroinstruction and must contain a valid storage pointer regardless of OPTCD except for OPTCD=APPSTAT.

AREALEN=data_area_length

Indicates the maximum number of bytes of data that the data area can hold; if the data to be placed there exceeds this value, a special condition results, (RTNCD,FDB2)=(X'00',X'05'), and the RECLEN field indicates the required length (except when OPTCD=APPSTAT). INQUIRE can be reissued using the correct length.

With OPTCD=APPSTAT, AREALEN must be defined to be at least 16 bytes to hold the network-qualified name.

ARG=(register)

Indicates the register containing the CID of the session. Register notation must be used if the CID is to be placed in the ARG field with this INQUIRE macroinstruction. This operand applies to the DEVCHAR, CIDXLATE, SESSPARM, LOGONMSG, and SESSKEY forms of INQUIRE.

Note:

The NIB and the ARG operands occupy the same physical field (RPLARG) in the RPL. If the last macroinstruction operand used to set or modify this field was ARG=(register), or if the field has been left unchanged since VTAM inserted a CID into it, VTAM recognizes that this field contains a CID. If the last operand used to set or modify this field was NIB=address, VTAM recognizes that the field contains an NIB address.
If your application uses the RPL DSECT, IFGRPL, you must clear the RPLNIB bit if a CID is being inserted into the RPLARG field.

BRANCH

For application programs running in supervisor state under a TCB, BRANCH indicates whether authorized path processing is to be used. See Authorized path.

BRANCH=YES: When the macroinstruction is issued, VTAM processes the macroinstruction using authorized path. For programs running under an SRB rather than under a TCB, the macroinstruction is processed in this manner automatically, regardless of the actual setting of the BRANCH field.
BRANCH=NO: When the macroinstruction is issued, VTAM does not process the macroinstruction using authorized path.

ECB

Indicates that an ECB is posted when an asynchronous (OPTCD=ASY) INQUIRE operation is posted as being complete. You cannot specify both ECB and EXIT on a single macroinstruction.

ECB=event_control_block_address: Specifies that VTAM is to post an event control block (ECB). Event_control_block_address is the location of the ECB to be posted. The ECB can be any fullword of storage aligned on a fullword boundary.
ECB=INTERNAL: Specifies that VTAM is to post an internal ECB.

EXIT=exit_routine_address

Indicates the address of an RPL exit routine that is scheduled when an asynchronous (OPTCD=ASY) INQUIRE operation is posted as being complete. You cannot specify both ECB and EXIT on a single macroinstruction. For details about the EXIT operand, refer to the RPL macroinstruction description in this chapter.

NIB=nib_address

Indicates the NIB whose NAME field identifies the session or logical unit. This operand applies to the LOGONMSG, DEVCHAR, TERMS, APPSTAT, SESSPARM, SESSKEY, and CIDXLATE forms of INQUIRE. See the OPTCD descriptions of these forms of INQUIRE for information about whether the NAME (NIBSYM) or CID fields in the NIB can be used. For DEVCHAR, LOGONMSG, SESSPARM, SESSKEY, and CIDXLATE, NIB=address and ARG=(register) are mutually exclusive methods of identifying the logical unit, or specific session.

Note: If your application uses the RPL DSECT, IFGRPL, you must set the RPLNIB if an NIB address is being inserted into the RPLARG field.

OPTCD

See Table 1 for possible restrictions on the use of the OPTCD operand. The following describes each of the possible parameters to OPTCD. Only one of the following options can be specified.

OPTCD=APPSTAT

INQUIRE checks the status of a given application program and returns a value in the RPL's FDBK field which gives information about that application program's capability to establish sessions. INQUIRE can also return information about the application program's capability to establish cross-network sessions. Refer to the SETLOGON macroinstruction for further information.

The following are the RPL FDBK flag values indicating the status of the specified application program.

RPLFDB3 value: Explanation
X'00': The application program is active. The application program has opened its ACB with MACRF=LOGON and has issued SETLOGON OPTCD=START. It has not subsequently issued SETLOGON OPCTD=QUIESCE or SETLOGON OPCTD=STOP. Therefore, the application program can act as the PLU in a session.
X'04': The application program is inactive. If this is a same-domain request, the application program's ACB is not open. If this is a cross-domain request, the application program's ACB is not open, or an inactive CDRSC, representing the application, was found in the host of the program that issued the INQUIRE request. No sessions can be established with the application program.
X'08': The application program has opened its ACB with MACRF=NLOGON. Therefore, it does not accept sessions that it did not itself initiate by OPNDST OPTCD=ACQUIRE, and it cannot act as the SLU in a session.
X'0C': The application program has opened its ACB with MACRF=LOGON and has not yet issued SETLOGON OPTCD=START or has issued a subsequent SETLOGON OPCTD=STOP. If SETLOGON OPCTD=START has not yet been issued, the application program is not yet enabled for sessions in which it acts as the SLU and attempts to initiate such sessions are rejected.
If SETLOGON OPCTD=STOP is issued, the program requests to temporarily stop establishing sessions. This indicator is by convention only; that is, the SSCP does not take any action to prevent the initiation of sessions with this application program just because this indicator is set. The effect of SETLOGON OPTCD=STOP can be reversed by issuing SETLOGON OPTCD=START.
X'10': VTAM returns this code in two cases. The application either issued SETLOGON OPTCD=QUIESCE, or the application is pending recovery. In either case, no new sessions can be established. To reverse SETLOGON OPTCD=QUIESCE, the application program closes and reopens the ACB.
To leave the recovery pending state, the application program issues OPEN ACB.

RPLRTNCD/ RPLFDB2: Explanation
X'000A': Application program not connectable
X'144C': Search argument for INQUIRE or INTRPRET not valid
X'1453': Logical unit not found

Note: For more information on RPL fields, see Return codes and sense fields for RPL-based macroinstructions, or Control block formats and DSECTs.

The RPL's ACB field must contain the address of an opened ACB. This is the ACB of the application program issuing the INQUIRE.

The RPL's NIB field must point to a NIB whose NAME field contains the symbolic name of the application program whose status is desired.

If PARMS=(NQNAMES=YES), and if the NIB is specified and it contains a network identifier in the NIBNET field, the network identifier is used along with the LU name in NIBSYM to find the application.

If AREA and AREALEN are specified with OPTCD=APPSTAT, VTAM will attempt to give the network-qualified name (network identifier and real name) for the specified application program. If a USERVAR or ALIAS is given as input, the name of the application associated with the USERVAR will be returned. The network-qualified name will be placed in RPLAREA. RPLRLEN will contain the number of bytes placed in RPLAREA.

Note: The preferred function for symbolic-to-real name translation is INQUIRE OPTCD=NQN.

When VTAM is able to process the request successfully, RPLAREA will contain the network identifier followed by the real name of the application. The netid will be in the first 8 bytes, followed by the real name in the second 8 bytes. Blanks (X'40') are appended to the right of the network identifier or name, if needed, to guarantee the 8-byte length of each field. AREA/AREALEN should be defined to hold at least 16 bytes of data.

The network-qualified name is not returned when AREA and AREALEN are included with INQUIRE OPTCD=APPSTAT in the following cases:

The work area designated by AREA is not large enough (AREALEN must be at least 16 bytes to hold the network identifier and real name)
An error was encountered while processing INQUIRE (RPLRTNCD=X'00')
The named resource is an inactive CDRSC and the real network identifier or name is not available
The named resource was found but is not an application.

In these cases, RPLAREA will not contain the network-qualified name. In addition, RTNCD/FBD2 will not report any new or additional error codes. If RPLRTNCD=X'00', the RPL will still contain information about the application's status. The INQUIRE will complete as if AREA had never been specified as part of the invocation.

OPTCD=ASY

Control is returned to the application program as soon as VTAM has accepted the INQUIRE operation request. Once the INQUIRE operation has been completed, the ECB is posted or the RPL exit routine is scheduled, depending on the setting of the ECB-EXIT field. Refer to the RPL macroinstruction description in this topic for details about OPTCD=ASY.

OPTCD=CIDXLATE

To determine the name of the logical unit associated with a CID, the RPLARG field must contain the CID when the INQUIRE macroinstruction is executed.

If PARMS=(NQNAMES=NO) on the ACB macroinstruction and AREALEN is greater than or equal to 8, the 8-byte name is stored in AREA.
If PARMS=(NQNAMES=YES) on the ACB macroinstruction and AREALEN is greater than or equal to 16, the network-qualified name is stored in AREA.

The format of the returned data is the 8-byte network identifier (padded with blanks, if necessary) followed by the resource name (padded with blanks, if necessary).

To use INQUIRE to determine the CID of a session with a logical unit, the RPL's NIB field must contain the address of an NIB. The NAME field of that NIB must in turn contain the symbolic name to be converted. The CID is placed in the data area indicated by the RPL's AREA field. The AREALEN field must be set to 4. If the logical unit is not currently in session, a CID is not returned, and an error code is set (RTNCD,FDB2)=(X'00',X'07').

If the INQUIRE macroinstruction specifies the name of a logical unit with which the application program has established parallel sessions, the CID returned identifies one of the current parallel sessions. The exact session whose CID is returned is unpredictable.

If PARMS=(NQNAMES=YES), then the following logic is used in finding the CID:

If NIBNET is zeros, blanks, or “RECORD ”, the LU name in the NIB field NIBSYM is used to find the CID.
If NIBNET is not zeros, blanks, or “RECORD”, the LU name in the NIB field NIBSYM and the network identifier in the NIB field NIBNET are used to find the CID.

OPTCD=COUNTS

For the ACB specified in the RPL, INQUIRE provides the number of active sessions and the number of queued CINIT requests for the application program.

The RPL's ACB field must contain the address of the ACB. The AREA and AREALEN fields must indicate a 4-byte area where the information is to be placed. VTAM places the number of active sessions in the first 2 bytes and the number of queued CINITs in the second 2 bytes.

OPTCD=DEVCHAR

The logical unit (which can be a non-SNA device) for which the device characteristics are to be retrieved is specified either by placing the CID of an active or pending active session into the RPL's ARG field or by specifying an NIB in the RPL. For application programs not capable of parallel sessions (PARSESS=NO on the APPL definition statement), if a NIB is specified, the NIBSYM field must specify the name of the logical unit. For application programs capable of parallel sessions, if an NIB is specified, the operation of the DEVCHAR option depends on the setting of the NIBCID field. If the NIBCID field contains 0, the NIBs NAME (NIBSYM) field must specify the name of the logical unit. If the NIBCID field is not 0, the logical unit is the one associated with the specified session.

The device characteristics are placed in an 8-byte program storage area whose location is set in the AREA field. The AREALEN field must be set to 8. See the description of the ISTDVCHR DSECT in Control block formats and DSECTs, for a complete description of the DEVCHAR information.

OPTCD=LOGONMSG

The RPL's ACB field must indicate the ACB to which the CINIT is directed. The AREA and AREALEN fields must indicate the location and length of the storage area where the user data field (the logon message) from the Initiate that led to the CINIT is to be placed. The particular user data field to be retrieved is specified either by placing the CID of the associated pending active session into the RPLARG field or by specifying an NIB in the RPL.

For application programs not capable of parallel sessions (PARSESS=NO on the APPL definition statement), if an NIB is specified, the NIBSYM field must specify the name of the logical unit associated with the pending active session (and thus uniquely identifies the queued CINIT containing the user data).

For application programs capable of parallel sessions (PARSESS=YES on the APPL definition statement), if an NIB is specified, the operation of the LOGONMSG option depends upon the setting of the NIBCID field. If the NIBCID field contains a value of 0, INQUIRE obtains the data associated with the oldest queued CINIT for a session with the named logical unit; if the NIBCID field contains a value other than 0, INQUIRE obtains the data from the specific queued CINIT represented by the CID.

If PARMS=(NQNAMES=YES), then the following logic is used in finding the CINIT:

If NIB is specified and if it contains a network identifier in the NIBNET field, the network identifier is used along with the LU name in NIBSYM to find the CINIT.
If NIBNET is zeros, blanks, or “RECORD ”, then only NIBSYM is used to find the CINIT.

Note: The information necessary to be supplied for the ACB, NAME, CID, and AREALEN fields can be obtained from the LOGON exit routine's parameter list. Refer to LOGON exit routine for further information.

VTAM indicates the actual length of the user data in the RPL's RECLEN field. If the length of data is AREALEN, RECLEN is posted with the required length; conditional completion is indicated, (RTNCD,FDB2)=(X'00',X'05'); and no data is supplied to the application program. INQUIRE OPTCD=LOGONMSG can then be reissued specifying a larger AREALEN.

Note: The user data portion of a CINIT cannot be obtained after an OPNDST or CLSDST has been issued for the pending active session with which CINIT is associated.

OPTCD=NQN

If a symbolic-to-real translation request is made, the application program supplies a non-network-qualified symbolic name and asks VTAM to translate the symbolic name into a real network identifier and a resource name. If a real-to-symbolic translation request is made, the application program supplies a network-qualified name (a network identifier and a resource name) and asks VTAM to translate the real name into a non-network-qualified symbolic name if one is defined to that VTAM.

VTAM performs a symbolic-to-real translation if NIBNET is filled in with “RECORD ”, blanks, or null. In other words, VTAM translates the symbolic name into a network-qualified name. The AREALEN field must be greater than or equal to 16.

VTAM performs a real-to-symbolic translation if NIBNET is filled in with a network identifier. In other words, VTAM translates the network-qualified name into a symbolic name. The AREALEN field must be greater than or equal to 8.

OPTCD=PERSESS

This option causes VTAM to create an NIB for each record application program interface session that is pending recovery in the area provided by the user (RPLAREA). The NIB provides the application with information that is used to restore the session. This information includes:

The network ID of the LU
The VTAM CID
Note: The CID of a session restored for persistent sessions is different from the CID of the original session.
The value of the previous NIB USERFLD
An indication of whether the application is the PLU or the SLU
An indication of whether this is the last NIB in the list
The setting of the session's continue-any mode and continue-specific mode for the three data types: DFSYN, DFASY, and RESP
A pointer to the restore parameter list.
The restore parameter list indicates where to locate:
- BIND information and user data structure subfields if BINUSEL is non-zero (for LU 6.1 and LU 6.2)
- Session qualifier pair (for LU 6.1)
- MODENAME (for LU 6.2)
- Session instance identifier (for LU 6.2).

When INQUIRE OPTCD=PERSESS is issued, AREA indicates where the information produced by the macroinstruction is placed. See Restoring sessions pending recovery for more information.

If the data to be provided exceeds the AREALEN value, one of two special conditions results, (RTNCD,FDB2)=(X'00',X'05') or (RTNCD,FDB2)=(X'00',X'0D'). VTAM sets the return code to (RTNCD,FDB2)=(X'00',X'05') if AREALEN is insufficient to hold the information for at least one session pending recovery (in this case, RPLAREA will not contain any data). VTAM sets the return code to (RTNCD,FDB2)=(X'00',X'0D') if AREALEN is insufficient to hold the information for all sessions pending recovery. See Restoring sessions for more information. The RECLEN field indicates the length that was used (in this case, RPLAREA will contain the NIBs for as many sessions as the RPLAREA is capable of holding). If AREALEN is large enough to hold the data, a different condition results, (RTNCD,FDB2)=(X'00',X'00'). If INQUIRE OPTCD=PERSESS is issued and no sessions are pending recovery, another condition results, (RTNCD,FDB2)=(X'00',X'07').

VTAM builds NIBs and returns them to the issuer of the macroinstruction.

If PARMS=(NQNAMES=YES) on the ACB macroinstruction, the field NIBSYM contains the LU name and the field NIBNET contains the network identifier.
If PARMS=(NQNAMES=NO) on the ACB macroinstruction, the field NIBSYM contains the LU name and the field NIBNET contains zeros.

OPTCD=SESSKEY

For a particular session, INQUIRE returns cryptographic session information which consists of a 16-byte field containing the session cryptography key (the first 8 bytes) and the initial chaining value (ICV) (the second 8 bytes). The AREA field indicates the location of this 16-byte field. The AREALEN field must be set to 16. The session is specified by either the CID in the RPLARG field or by a CID or NAME field in the NIB.

For application programs not capable of parallel sessions (PARSESS=NO on the APPL definition statement), if an NIB is specified, the NIB's NAME (NIBSYM) field must specify the name of the logical unit. For application programs capable of parallel sessions, if an NIB is specified, the operation of the SESSKEY option depends on the setting of the NIBCID field. If the NIBCID field contains 0, the NIB's NAME (NIBSYM) field must specify the name of the logical unit, and the session cryptography information is retrieved for a session with the named logical unit; if multiple sessions exist with the logical unit, the session for which the information is retrieved is unpredictable. If the NIBCID field is not 0, the session cryptography information is retrieved for the session identified by the CID.

If PARMS=(NQNAMES=YES), then the following logic is used in finding the session:

In the NIBNET field, the network identifier is used along with the LU name in NIBSYM to find the session.
If NIBNET is zeros, blanks, or “RECORD ”, only NIBSYM is used to find the session.

OPTCD=SESSNAME

Allows you to determine the network-qualified name of the generic resource application that is associated, using the generic name, with a specific LU.

The NIBSYM field contains the name of the LU; NIBNET is the network identifier of the LU. NIBGENN provides the generic resource name used to establish the session.

VTAM determines which application is associated with the specified LU and generic resource name and returns the name and netid of the application in the AREA field. The AREALEN field must be set to 16.

If the logical unit initiates its sessions using the application network names, rather than the generic resource name, error code (RTNCD,FDB2)=(X'14',X'88') is set indicating that no LU-to-application associations match the given criteria.

If the application program does not support network-qualified names and NETID is not specified, VTAM will use the first occurrence of the partner name.

OPTCD=SESSPARM

To determine the session parameters associated with a specified logon mode name, the NIB field of the RPL must point to an NIB whose LOGMODE operand identifies the logon mode name used. The logon mode name that is specified in the NIB is used to search the logon mode table defined for the logical unit named in the NIB. If a match is found, the session parameters associated with the logon mode name are returned in the AREA field of the RPL. The AREALEN field must be set to at least 36 (decimal).

To determine the session parameters associated with a queued CINIT, either the RPLARG field can specify the CID of the pending active session or the RPL's NIB field can specify an NIB that in turn specifies the pending active session. In either case, the session parameters (including the user data field from Initiate) from the queued CINIT are returned in the AREA field. AREALEN must be large enough to contain the session parameters from the queued CINIT. If the NIB technique is used, the LOGMODE field must be set to 0 (indicating that the session parameters of a queued CINIT are requested). For application programs not capable of parallel sessions (PARSESS=NO on the APPL definition statement), if an NIB is specified, the NIB's NAME (NIBSYM) field must specify the name of the logical unit. For application programs capable of parallel sessions, if a NIB is specified, the operation of the SESSPARM option depends on the setting of the NIBCID field. If the NIBCID field contains 0, the NIBSYM field must specify the name of the logical unit, and the session parameters are retrieved from the CINIT for the oldest pending active session with that logical unit. If the NIBCID field is not 0, the session parameters are retrieved from the CINIT identified by the CID.

See the description of the LOGMODE operand of the NIB macroinstruction for more information. For more information on session parameters, refer to Specifying a session parameter.

OPTCD=STATUS

INQUIRE checks the status of an application or LU and returns a value in the RPL's FDBK field. Specify this option code to receive the status of an LU. If the requested resource is an application, or if an error is detected, the result is the same as though an INQUIRE OPTCD=APPSTAT was issued. If the resource is an LU, one of the following RPL FDBK values is returned:

RPLFDB3 value: Explanation
X'80': The resource is active. For an independent LU, the PU is either active or connectable.
X'84': The resource is not active. The resource currently has a status other than active.

OPTCD=SYN

Control is returned to the application program when the INQUIRE operation has been completed. Once the INQUIRE operation has been completed, the ECB is posted or the RPL exit routine is scheduled, depending on the setting of the ECB-EXIT field. Refer to the RPL macroinstruction description in this topic for details about OPTCD=SYN.

Because it might take VTAM a relatively long time to complete the INQUIRE operation, you should not use the SYN option if suspending the INQUIRE issuing task or SRB for this time is undesirable. Use the ASY option code, instead.

OPTCD=TERMS

The RPL's NIB field must point to a NIB whose NAME field contains the name of a resource known to VTAM at the time INQUIRE is executed. If the name in the NIB is an LU, an NIB is built for that LU. If the name is for a resource other than an LU, an NIB is built for that resource and all dependent LUs that are subordinate to that resource.

The AREA and AREALEN fields designate the location and length of the work area where the NIBs are built. The work area must be set to binary zeros by the application program before INQUIRE is issued.

VTAM indicates the total length of the NIBs in the RPL's RECLEN field.

If the application program wants the NIBs to be built in dynamically allocated storage (obtained by the application program), INQUIRE should be issued twice. For the first INQUIRE, set AREALEN to 0. This INQUIRE is completed with (RTNCD,FDB2)=(X'00',X'05') (insufficient length), and RECLEN indicates the required length. Obtain the storage and reissue INQUIRE with AREALEN set to the proper length.

Each NIB contains the symbolic name of a logical unit, with flags for the LISTEND field set in such a way as to group the NIBs together into an NIB list. In addition, except for a cross-domain LU, the same device characteristics are placed in each NIB as would be obtained for each logical unit by issuing INQUIRE OPTCD=DEVCHAR for that logical unit. The device characteristics field in the NIB might not always be set for a cross-domain LU.

After you have set the NIB fields to their desired values, the NIBs are ready to be used for session establishment.

If PARMS=(NQNAMES=YES), then the following logic is used in finding the LU:

If the NIB is specified and if it contains a network identifier in the NIBNET field, the network identifier is used along with the LU name in NIBSYM to find the LU.
If NIBNET is zeros, blanks, or “RECORD ”, only NIBSYM is used to find the LU.

OPTCD=TOPLOGON

The ACB field of the INQUIRE's RPL must indicate the ACB whose CINIT queue is to be examined. The symbolic name of the logical unit associated with the oldest queued CINIT is returned in the data area indicated by you in the RPL's AREA field. The AREALEN field must be set to 8. The CID of this pending active session is returned in the RPLARG field.

If no CINITs are queued, INQUIRE is posted complete with (RTNCD,FDB2)=(X'00',X'07').

If PARMS=(NQNAMES=NO) and AREA is greater than or equal to 8, the non-network-qualified name is returned. The format of the returned data in RPLAREA is an 8-byte name, (padded with blanks if necessary).
If PARMS=(NQNAMES=YES) and AREA is greater than or equal to 16, the network-qualified name is returned. The format of the returned data in RPLAREA is an 8-byte network identifier, (padded with blanks if necessary), followed by the resource name, (padded with blanks if necessary).

OPTCD=USERVAR

Use OPTCD=NQN in place of OPTCD=USERVAR. Although OPTCD=USERVAR can be issued, the actual macroinstruction invocation always returns a successful RTNCD,FDB2 and returns the translated name as the same name passed as input. NQN is the suggested option to be used for name translation requests.

RPLAREA points to an 8-byte field that is the name of the USERVAR. Set RPL AREALEN to 8 for a USERVAR name.

Examples

INQ1     INQUIRE RPL=RPL1,OPTCD=APPSTAT,NIB=NIB1
         .
         .
         .
TST1     TESTCB RPL=RPL1,FDBK=0
         BE    ACTIVE
         .
         .
         .
NIB1     NIB   NAME=PGM1

INQ1 determines whether PGM1 is active and accepting session-establishment requests. The answer is returned in RPL1's FDBK field. TST1 and the branch instruction cause a branch to ACTIVE if the application program is active and accepting session-establishment requests.

INQ2     INQUIRE RPL=RPL2,OPTCD=LOGONMSG,                              C
               ACB=ACB1,NIB=NIB2,                                      C
               AREA=LGNMSG,AREALEN=100
         .
         .
         .
NIB2     NIB   NAME=LU2
LGNMSG   DS    CL100

INQ2 obtains the user data portion of the Initiate that was sent from or on behalf of the logical unit whose symbolic name is contained in NIB2 and that requested a session with the application program represented by ACB1. This data is placed in the area designated as LGNMSG.

Completion information

The INQUIRE operation is successfully completed when the information has been placed into the application program's storage area.

When the INQUIRE operation completes, the following RPL fields are set:

The value 26 (decimal) is set in the REQ field indicating an INQUIRE request.
If INQUIRE OPTCD=APPSTAT completes normally, as indicated in register 15, VTAM sets the FDBK field to one of the values listed under APPSTAT, discussed earlier in this macroinstruction description.
If INQUIRE (all versions except OPTCD=APPSTAT) has been completed normally, the RECLEN field indicates the number of bytes of data that are placed in the work area designated by the AREA field. If INQUIRE completed successfully, but the FDB2 field indicates that the work area is too small, (RTNCD,FDB2)=(X'00',X'05'), RECLEN indicates the required length.
If INQUIRE OPTCD=TOPLOGON completes normally, as indicated in register 15, VTAM sets the ARG field with the CID of the oldest queued CINIT.
If the macroinstruction returns an error code, the SSENSEI, SSENSMI, and USENSEI fields might be set indicating system-sense information, system-sense modifier, and user-sense information. See Return codes and sense fields for RPL-based macroinstructions for more information about these fields.
The RTNCD and FDB2 fields are set as indicated in Return codes and sense fields for RPL-based macroinstructions. VTAM also sets registers 0 and 15 as indicated in Handling errors and special conditions.