INQY call

Format

Parameters

aib

Specifies the address of the application interface block (DFSAIB) for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB:

AIBID

Eye catcher. This 8-byte field must contain DFSAIBbb.

AIBLEN

AIB lengths. This field must contain the actual length of the AIB that the application program obtained.

AIBSFUNC

Subfunction code. This field must contain one of the 8-byte subfunction codes as follows:

• bbbbbbbb (Null)
• DBQUERYb
• ENVIRONb
• ENVIRON2
• FINDbbbb
• LERUNOPT
• MSGINFOb
• PROGRAMb (Not supported with the ODBA interface)

AIBRSNM1

Resource name. This 8-byte, left-aligned field must contain the name of any named PCB in the PSB.

AIBOALEN

I/O area length. This field must contain the length of the I/O area specified in the call list. This field is not changed by IMS.

i/o area

Specifies the data output area to use with the call. This parameter is an output parameter. An I/O area is required for INQY subfunctions ENVIRONb, ENVIRON2, MSGINFOb and PROGRAMb. It is not required for subfunctions DBQUERYb, FINDbbbb, and LERUNOPT.

Restrictions

A CPI Communications driven application program cannot issue an INQY call with the null subfunction against an I/O PCB.

A batch program cannot issue an INQY call with a null subfunction.

Usage

The INQY call operates in both batch and online IMS environments. IMS application programs can use the INQY call to request information about the output destination, the session status, the current execution environment, the availability of databases, and the PCB address, which is based on the PCB name. You must use the AIB when issuing an INQY call. Before you can issue an INQY call, initialize the fields of the AIB.

When you use the INQY call, specify an 8-byte subfunction code, which is passed in the AIB. The INQY subfunction determines the information that the application program receives.

The INQY call returns information to the caller's I/O area. The length of the data that is returned from the INQY call is passed back to the application program in the AIB field, AIBOAUSE.

Specify the size of the I/O area in the AIB field, AIBOALEN. The INQY call returns only as much data as the area can hold in one call. If the area is not large enough for all the information, an AG status code is returned, and partial data is returned in the I/O area. In this case, the AIB field AIBOALEN contains the actual length of the data that is returned to the I/O area, and the AIBOAUSE field contains the output area length that would be required to receive all the data.

Querying information from the PCB: INQY null

When the INQY call is issued with the null subfunction, the application program obtains information related to the PCB, including output destination type and location, and session status. The INQY call can use the I/O PCB or the alternate PCB. The information you receive regarding destination location and session status is based on the destination type. The destination types are APPC, OTMA, TERMINAL, TRANSACT, and UNKNOWN.

Related reading: For more information about APPC and LU 6.2, see IMS Version 15.4 Communications and Connections.

The INQY null subfunction returns character string data in the I/O area. The output that is returned for the destination types APPC, OTMA, TERMINAL, and TRANSACT is left justified and padded with blanks. The UNKNOWN destination type does not return any information. The following tables list the output returned from the INQY null call. Refer to the notes associated with the table for further information about some of the entries.

The contents of the output fields vary depending on the type of PCB used for the INQY call. The following table shows how INQY output for APPC destinations varies depending on the PCB type. The PCB can be a TP PCB or an alternate PCB.

Related reading: For more information on APPC and LU 6.2, see IMS Version 15.4 Communications and Connections.

Querying data availability: INQY DBQUERY

When the INQY call is issued with the DBQUERY subfunction, the application program obtains information about the data for each PCB. The only valid PCB name that can be passed in AIBRSNM1 is IOPCBbbb. The INQY DBQUERY call is similar to the INITDBQUERY call. The INQY DBQUERY call does not return information in the I/O area, but like the INIT DBQUERY call, it updates status codes in the database PCBs.

The application program is not made aware of the status of each PCB until an INQY FIND call is issued. To retrieve the status for a database, you must pass the DB PCB for that database in the INQY FIND call.

In addition to the INIT DBQUERY status codes, the INQY DBQUERY call returns these status codes in the I/O PCB:

bb

The call is successful and all databases are available.

BJ

None of the databases in the PSB are available, or no PCBs exist in the PSB. All database PCBs (excluding GSAM) contain an NA status code as the result of processing the INQY DBQUERY call.

BK

At least one of the databases in the PSB is not available, or availability is limited. At least one database PCB contains an NA or NU status code as the result of processing the INQY DBQUERY call. When CATALOG PCBs show NA, the status code is bb.

The INQY call returns the following status codes in each DB PCB:

NA

At least one of the databases that can be accessed by using this PCB is not available. A call that is made using this PCB probably results in a BA or BB status code if the INIT STATUS GROUPA call has been issued, or in a DFS3303I message and 3303 pseudoabend if the call has not been issued. An exception is when the database is not available because dynamic allocation failed. In this case, a call results in an AI (unable to open) status code.

In a DCCTL environment, the status code is always NA.

NU

At least one of the databases that can be updated using this PCB is unavailable for update. An ISRT, DLET, or REPL call using this PCB might result in a BA status code if the INIT STATUS GROUPA call has been issued, or in a DFS3303I message and 3303 pseudoabend if it has not been issued. The database that caused the NU status code might be required only for delete processing. In that case, DLET calls fail, but ISRT and REPL calls succeed.

bb

The data that can be accessed with this PCB can be used for all functions the PCB allows. DEDBs and MSDBs always have the bb.

Querying the environment: INQY ENVIRON or ENVIRON2

When the INQY call is issued with the ENVIRON or ENVIRON2 subfunctions, the application program obtains information about the current execution environment. Both subfunctions cannot be used with the same INQY call, so use either ENVIRON or ENVIRON2. The ENVIRON subfunction provides compatibility for existing programs that require its specific use, whereas ENVIRON2 is newer and provides more information. The only valid PCB name that can be passed in AIBRSNM1 is IOPCBbbb. This includes the IMS identifier, release, region, and region type.

The INQY ENVIRON and ENVIRON2 calls return character-string data. The output is left-aligned and padded with blanks on the right.

The following table describes the INQY ENVIRON output.

The INQY ENVIRON2 subfunction returns all the information provided by the ENVIRON subfunction, plus the output described in the following table.

Querying the input message information: INQY MSGINFO

To obtain information regarding the current input message, use the INQY call with the MSGINFO subfunction. The only valid PCB name that can be passed in the AIBRSNM1 field is IOPCBbbb. The output returns the version number and the output fields for the message information. The INQY MSGINFO call returns the response in the I/O area.

The following table lists the output that is returned from the INQY MSGINFO call. Included with the information returned is the byte length, the actual value, and an explanation of the output.

The distributed network user ID, if used, has a variable length from 1 to 246 bytes and the distributed network session ID, if used, has a variable length from 1 to 254 bytes. Because the size of the distributed network security credentials can vary, the information is appended to the end of the response in the I/O area. If network security credentials are included in the message, define the I/O area, in the AIB field AIBOALEN, with the appropriate 2-byte length to account for the variable length of the network user ID and the network session ID.

To reference the field that contains the distributed network user ID or distributed network session ID, code your application programs to locate the field by using the address of the field that is returned in the data output of the INQY MSGINFO call. The address identifies a length field (LL) that contains the length of the ID followed by the distributed network user ID or network session ID. This is the only valid programming technique to reference the network user ID and network session ID.

The distributed network user ID or network session ID are optional and therefore are not always returned. If they are not returned, the value in the address field is zero.

Querying the PCB address: INQY FIND

When the INQY call is issued with the FIND subfunction, the application program is returned with the PCB address of the requested PCB name. The valid PCB names that can be passed in AIBRSNM1 are IOPCBbbb or the name of the alternate PCB (TP PCB) or database PCB as it is defined in the PSB.

On a FIND subfunction, the requested PCB remains unmodified, and no information is returned in an I/O area.

The FIND subfunction is used to get a PCB address following an INQY DBQUERY call. This process allows the application to analyze the PCB status code to determine if an NA or NU status code is set in the PCB.

Querying for LE overrides: INQY LERUNOPT

When the LERUNOPT call is issued with the LERUNOPT subfunction, IMS determines whether LE overrides are allowed based on the LEOPT system parameter. The LE override parameters are defined to IMS through the UPDATE LE command. IMS checks to see whether there are any overrides applicable to the caller based on the specific combinations of transaction name, lterm name, userid, or program name in the callers environment. IMS returns the address of the string to the caller if an override parameter is found. The LE overrides are used by the IMS supplied CEEBXITA exit, DFSBXITA, to allow dynamic overrides for LE runtime parameters.

The call string must contain the function code and the AIB address. The I/O area is not a required parameter and is ignored if specified. The only valid PCB name that can be passed in AIBRSNM1 is IOPCB. The AIBOALEN and AIBOAUSE fields are not used.

The rules for matching an entry that results in it being returned on a DL/I INQY LERUNOPT call are:

• An MPP or JMP region uses transaction name, lterm, userid, and program to match with each entry.
• An IFB, JBP, or non-message-driven BMP uses program name to match with each entry. If an entry has a defined filter for transaction name, lterm, or userid, it does not match. Message driven BMPs also use transaction name.
• The entries are scanned to find the entry with the most filter matches. The first entry in the list with the most exact filter matches is selected. The scan stops with an entry found with all of the filters matching the entry.
  Note: Searching table entries may cause user confusion because of the way entries are built and searched. For example, assume that there are two entries in the table that match on the filters specified on the DL/I INQY call. The first transaction matches on transaction name and lterm name. The second entry matches on transaction name and program name. IMS chooses the first entry because it was the first entry encountered with highest number of filter matches. If the second entry is now updated with a longer parameter string, which causes a new entry to be built, it is added to the head of the queue. The next search would result in the entry with transaction name and program name being selected. This could result in a set of runtime options being selected that were not expected by the user.

Environments: The LERUNOPT subfunction can be specified from DB/DC, DBCTL, and DCCTL environments. Overrides are based on a combination of transaction name, lterm name, user ID, and program name in MPP and JMP regions. IFP, BMP, and JBP regions will have overrides based on program name. Message driven BMP regions can also use transaction name.

Return and reason codes: AIB return and reason codes must be checked to determine if the call has been successfully completed. AIBRSA2 is used to return the address of the parameter string if override parameters are available for the caller.

Querying the program name: INQY PROGRAM

When you issue the INQY call with the PROGRAM subfunction, the application program name is returned in the first 8 bytes of the I/O area. The only valid PCB name that can be passed in AIBRSNM1 is IOPCBbbb.

INQY return codes and reason codes

When you issue the INQY call, return and reason codes are returned to the AIB. Status codes can be returned to the PCB. If return and reason codes other than those that apply to INQY are returned, your application should examine the PCB to see what status codes are found.

Map of INQY subfunction to PCB type