IMS V13 - Appl. programming APIs

Format


>>-INQY--aib--i/o area-----------------------------------------><

Call Name	DB/DC	DBCTL	DCCTL	DB Batch	TM Batch
INQY	X	X	X	X	X

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
FINDbbbb
LERUNOPT
MSGINFOb
PROGRAMb (Not supported with the ODBA interface)

AIBRSNM1

Resource name. This 8-byte, left-justified 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, MSGINFOb and PROGRAMb. It is not required for subfunctions DBQUERYb, FINDbbbb, and LERUNOPT. End of change

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 regarding 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.

You 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 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 13 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.

Table 1. INQY null data output for terminal-type destinations
Information returned	Length in bytes	Actual value	Explanation
Destination Type	8	Terminal	The destination of the I/O PCB or alternate PCB is a terminal.
Terminal Location	8	Local	The terminal is defined as local.
Terminal Location	8	Remote	The terminal is defined as remote.
Queue Status	8	Started	The queue is started and can accept work.
Queue Status	8	Stopped	The queue is stopped and cannot accept work.
Session Status	8	b	The status is not available.
		ACTIVE	The session is active.
		INACTIVE	The session is inactive.

Table 2. INQY null data output for transaction-type destinations
Information returned	Length in bytes	Actual value	Explanation
Destination Type	8	TRANSACT	The destination of the alternate PCB is a program.
Transaction Location	8	Local	The transaction is defined as local.
		Remote	The transaction is defined as remote.
		DYNAMIC	The transaction is defined as dynamic.¹
Transaction Status	8	STARTED	The transaction can be scheduled.²
Transaction Status	8	STOPPED	The transaction cannot be scheduled.²
Destination PSB Name	8		This field gives the name of the destination PSB.
Destination PSB Name	8	b	The Program Routing exit routine has defined the destination as a transaction not on this system or the transaction is dynamic. The transaction destination is not available.
Destination Program or Session Status	8	b	The status is not available.
		ACTIVE	The MSC link session is active (remote transaction or a transaction that was rerouted to a remote IMS by the TM and Message Routing and Control user exit routine (DFSMSCE0)).
		INACTIVE	The MSC link session is inactive (remote transaction or a transaction that was rerouted to a remote IMS by the TM and Message Routing and Control user exit routine (DFSMSCE0)).
		STARTED	The program can be scheduled (local transaction).
		STOPPED	The program cannot be scheduled (local transaction).
Notes: A dynamic transaction is only possible in a shared-queues environment. A transaction is dynamic when it is not defined to the IMS system that is sending the message, but rather to another IMS system that is sharing the queues. The dynamic transaction is created when the Destination Creation exit routine (DFSINSX0) indicates a transaction whose destination is unknown to IMS. The output fields for the destination PSB name and destination program are set to blanks. If the transaction was rerouted to a remote IMS by the TM and Message Routing and Control user exit routine (DFSMSCE0, the status returned is the MSNAME status.

Table 3. INQY null data output for APPC-Type destinations
Information returned	Length in bytes	Actual value	Explanation
Destination Type	8	APPC	The destination is an LU 6.2 device.
APPC/MVS Side Information Entry Name¹	8		This field provides the Side Name.
APPC/MVS Side Information Entry Name¹	8	b	The Side Name is not available.
Partner Logical Unit Name²	8		This field provides the partner LU name for the conversation.
Partner Logical Unit Name²	8	b	The partner LU name is not available.
Partner Mode Table Entry Name³	8		This field provides the Mode Name for the conversation.
Partner Mode Table Entry Name³	8	b	The Mode Name is not available.
User Identifier	8		This field provides the user ID.
User Identifier	8	b	The user ID is not available.
Group Name	8		This field provides the Group Name.
Group Name	8	b	The Group Name is not available.
Synchronization Level⁴	1	C	The synchronization level is defined as CONFIRM.
Synchronization Level⁴	1	N	The synchronization level is defined as NONE.
Conversation Type⁵	1	B	The conversation is defined as BASIC.
Conversation Type⁵	1	M	The conversation is defined as MAPPED.
Userid Indicator	1		The value of the Userid Indicator field indicates the contents of the user ID field. The Userid Indicator field has four possible values.
		U	The U value indicates the user's identification from the source terminal during signon.
		L	The L value indicates the LTERM name of the source terminal if signon is not active.
		P	The P value indicates the PSBNAME of the source BMP or transaction.
		O	The O value indicates some other name.
Address of TPN⁶	4		This is the address of the LL field of the Transaction Program Name.⁷
Address of TPN⁶	4	0	The address of the Transaction Program Name is not available.
Notes: If the call is issued against a TP PCB, the Side Name cannot be used and b is returned. If the call is issued against an alternate modifiable PCB, the Side Name must be supplied in a `CHNG` call that is issued before `INQY`. If the call is issued against a TP PCB, the LU name must be coded. If the call is issued against a modifiable alternate PCB, the LU name must be supplied in a `CHNG` call that is issued before `INQY`. If the call is issued against a TP PCB, the Mode Name cannot be used and b is returned. If the call is issued against an alternate modifiable PCB, the Mode Name must be supplied in a `CHNG` call that is issued before `INQY`. When the synchronization level is not available, IMS uses the default value of CONFIRM. When the conversation type is not available, IMS uses the default value of MAPPED. The pointer identifies a length field (LL), which contains the length of the TPN in binary, including the 2 bytes required for LL. The TPN can be up to 64 bytes long.

Table 4. INQY null data output for OTMA-Type destinations
Information Returned	Length in Bytes	Actual Value	Explanation
Destination Type	8	OTMA	The destination is an OTMA client.
tpipe Name	8		This field provides the OTMA transaction pipe name.
tpipe Name	8	b	The tpipe Name is not available.
Member Name	16		This field provides the z/OS® cross-system coupling facility (XCF) member name of the OTMA client.
Member Name	16	b	The Member Name is not available.
User Identifier	8		This field provides the User ID.
User Identifier	8	b	The User ID is not available.
Group Name	8		This field provides the group name.
Group Name	8	b	The Group Name is not available.
Synchronization Level	1	S	The OTMA transaction pipe is synchronized.
Synchronization Level	1	b	The OTMA transaction pipe is not synchronized.
Message Synchronization Level¹	1	C	The synchronization level is defined as CONFIRM.
Message Synchronization Level¹	1	N	The synchronization level is defined as NONE.
Userid Indicator	1		The value of the Userid Indicator field indicates the contents of the user ID field. The Userid Indicator field has four possible values.
		U	The U value indicates the user's identification from the source terminal during signon.
		L	The L value indicates the LTERM name of the source terminal if signon is not active.
		P	The P value indicates the PSBNAME of the source BMP or transaction.
		O	The O value indicates some other name.
Reserved for IMS	1		This field is reserved.
Notes: When the synchronization level is not available, IMS uses the default value of CONFIRM.

Table 5. INQY null data output for unknown-type destinations
Information returned	Length in bytes	Actual value	Explanation
Destination Type	8	UNKNOWN	Unable to find destination.

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.

Table 6. INQY output and PCB type
Output field	TP PCB	Alternate PCB (Non-modifiable)	Alternate PCB (Modifiable)
Destination Type	APPC	APPC	APPC
Side Name	blanks	Side Name if available or blanks	Side Name if supplied on previous CHNG call or blanks
LU Name	Input LU Name	LU Name if available or blanks	LU Name if supplied on previous CHNG call or blanks
Mode Name	blanks	Mode Name if available or blanks	Mode Name if supplied on previous CHNG call or blanks
User Identifier	USERID if available or blanks	USERID if available or blanks	USERID if available or blanks
Group Name	Group Name if available or blanks	Group Name if available or blanks	Group Name if available or blanks
Sync Level	C or N	C or N	C or N
Conversation Type	B or M	B or M	B or M
Userid Indicator	U or L or P or O	U or L or P or O	U or L or P or O
TPN Address	Address of the TPN character string	Address of the TPN character string or zero	Address of the TPN character string or zero
TPN character string Note: If your TPN name is DFSASYNC, the destination represents an asynchronous conversation.	Inbound name of IMS Transaction that is executing.	Partner TPN, if available. If not available, address field is zero.	TP Name if it is supplied on the previous CHNG call. If not supplied, the address field is zero.

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

Querying data availability: INQY DBQUERY

When the INQY call is issued with the DBQUERY subfunction, the application program obtains information regarding 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.

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

NA: At least one of the databases that can be accessed 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

When the INQY call is issued with the ENVIRON subfunction, the application program obtains information regarding the current execution environment. 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 call returns character-string data. The output is left justified and padded with blanks on the right.

Recommendations: To account for expansion in the length of the reply data, specify an I/O area length of 512 bytes.

To reference the field that contains the recovery token or the application parameter string, 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 ENVIRON call. This is the only valid programming technique to reference the recovery token field and the application parameter string field. No other programming technique should be used to reference these fields.

The recovery token or the application parameter string are optional and therefore are not always returned. If they are not returned, the value in the address field is zero.

For more information about the recovery token and application parameter fields, see note 2 after the following table.

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

Table 7. INQY ENVIRON data output
Information returned	Length in bytes	Actual value	Explanation
IMS Identifier	8		Provides the identifier from the execution parameters.
IMS Release Level	4		Provides the release level for IMS. For example, X'00000410'.
IMS Control Region Type	8	BATCH	Indicates that an IMS batch region is active.
		DB	Indicates that only the IMS Database Manager is active. (DBCTL system)
		TM	Indicates that only the IMS Transaction Manager is active. (DCCTL system)
		DB/DC	Indicates that both the IMS Database and Transaction managers are active. (DB/DC system)
IMS Application Region Type	8	BATCH	Indicates that the IMS Batch region is active.
		BMP	Indicates that the Batch Message Processing region is active.
		DRA	Indicates that the Database Resource Adapter Thread region is active.
		IFP	Indicates that the IMS Fast Path region is active.
		JBP	Indicates that the Java™ batch processing region is active.
		JMP	Indicates that the Java message processing region is active.
		MPP	Indicates that the Message Processing region is active.
Region Identifier	4		Provides the region identifier. For example, X'00000001'.
Application Program Name	8		Provides the name of the application program being run.
PSB Name (currently allocated)	8		Provides the name of the PSB currently allocated.
Transaction Name	8		Provides the name of the transaction.
Transaction Name	8	b	Indicates that no associated transaction exists.
User Identifier¹	8		Provides the user ID.
User Identifier¹	8	b	Indicates that the user ID is unavailable.
Group Name	8		Provides the group name.
Group Name	8	b	Indicates that the group name is unavailable.
Status Group Indicator	4	A	Indicates an INIT STATUS GROUPA call is issued.
		B	Indicates an INIT STATUS GROUPB call is issued.
		b	Indicates that a status group is not initialized.
Address of Recovery Token²	4		Provides the address of the LL field, followed by the recovery token.
Address of Recovery Token²	4	0	Indicates that the recovery token is not available.
Address of the Application Parameter String²	4		Provides the address of the LL field, followed by the application program parameter string.
Address of the Application Parameter String²	4	0	Indicates that the APARM= parameter is not coded in the execution parameters of the dependent region JCL.
Shared Queues Indicator	4		Indicates IMS is not using Shared Queues.
Shared Queues Indicator	4	SHRQ	Indicates IMS is using Shared Queues.
User ID of Address Space	8		User ID of dependent address space.
User ID Indicator	1		Contains one of the following possible values to indicate the contents of the userid field: U Indicates the user’s identification from the source terminal during sign-on. L Indicates the LTERM name of the source terminal in sign-on is not active. P Indicates the PSBNAME of the source BMP or transaction. O Indicates some other name.
z/OS Resource Recovery Services (RRS) Indicator	3	b	Indicates that IMS has not expressed interest in the UR with RRS. Therefore, the application should refrain from performing any work that causes RRS to become the syncpoint manager for the UR because IMS will not be involved in the commit scope. For example, the application should not issue any outbound protected conversations.
z/OS Resource Recovery Services (RRS) Indicator	3	RRS	Indicates IMS has expressed interest in the UR with RRS. Therefore, IMS will be involved in the commit scope if RRS is the syncpoint manager for the UR.
IMS catalog enablement indicator	7	b	Indicates that the IMS catalog is not enabled in the DFSDFxxx PROCLIB member. For information about setting up and enabling an IMS catalog, see IMS catalog definition and tailoring. For information about enabling the IMS catalog in the DFSDFxxx PROCLIB member, see DFSDFxxx member of the IMS PROCLIB data set.
IMS catalog enablement indicator	7	CATALOG	Indicates that the IMS catalog is enabled. Database and application metadata is available in IMS.
Notes: The user ID is derived from the PSTUSID field of the PST that represents the region making the INQY ENVIRON call. The PSTUSID field is one of the following: For message-driven BMP regions that have not completed successful GU calls to the IMS message queue and for non-message-driven BMP regions, the PSTUSID field is derived from the name of the PSB that is currently scheduled into the BMP region. For message-driven BMP regions that have completed a successful GU call and for any MPP region, the PSTUSID field is derived which is usually the input terminal's RACF® ID. If the terminal has not signed on to RACF, the ID is the input terminal's LTERM. The pointer is an address that identifies a length field (LL) which contains the length of the recovery token or application program parameter string in binary, including the two bytes required for LL. Use this pointer to set up addressability of the AIB between releases in a batch program.

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.

Table 8. INQY MSGINFO data output
Information returned	Length in bytes	Actual value	Explanation
Version number	4	1	Output response version 1.
Origin IMSID	8		The IMS identifier from which the input message originated.
Reserved for IMS	68		This field is reserved for future output expansion.

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 if 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 if 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 will return 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 will be 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 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 will be 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

Table 9. Subfunction, PCB, and I/O area combinations for the INQY call
Subfunction	I/O PCB	Alternate PCB	DB PCB	I/O Area Required
FIND	OK	OK	OK	NO
ENVIRON	OK	NO	NO	YES
DBQUERY	OK	NO	NO	NO
LERUNOPT	OK	NO	NO	NO
PROGRAM	OK	NO	NO	YES
MSGINFO	OK	NO	NO	YES