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

The INQY call is valid only when using the AIB. An INQY call that is issued through the PCB interface is rejected with an AD status code.

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 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: 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 only valid PCB names that can be passed in AIBRSNM1 are IOPCBbbb or the name of an alternate PCB or DB PCB, as defined in the PSB. The PCB address is returned in the AIBRSA1 field of the AIB mask. When the INQY call is completed, the AIBRSA1 field contains call-specific information.

To retrieve the status for a database, you must pass the DB PCB for that database in the INQY FIND call. You must issue one call for each PCB required.

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 program to analyze the PCB status code to determine whether either an NA or NU status code is set in the PCB.

The following PL/I code sample shows how to retrieve the database status values.

II00_INITSTAT: PROC;                                                   
     DCL DUMMY_LENGTH CHAR(4) INIT(' '); /* TO PLEASE IMS */            
     AIB.PCBNAME     = 'IOPCB';                                         
     CALL AIBTDLI($3,INIT,AIB,STATUS_CALL2);                            
     IF AIB.RETURN = 0 THEN                                             
        PUT SKIP LIST('INIT ISSUED');                                   
     ELSE                                                               
       DO;                                                              
        PUT SKIP LIST ('AIB RETURN CODE   ',AIB.RETURN);                
        PUT SKIP LIST ('AIB REASON CODE   ',AIB.REASON);                
        PUT SKIP LIST ('IOPCB STATUS CODE ',IO_PCB.STATUS_CODE);        
        PUT SKIP LIST ('INIT  UNSUCCESSFULL');                          
       END;                                                             
     SELECT  (IO_PCB.STATUS_CODE);                                      
       WHEN ('  ')                                                      
         GROUPA_STATUS = '  ';                                          
       WHEN ('NA')                                                      
         GROUPA_STATUS = 'NA';                                          
       WHEN ('NU')                                                      
         GROUPA_STATUS = 'NU';                                          
       OTHERWISE                                                        
         DO;                                                            
           PUT SKIP LIST                                                
           ('INIT STATUS GROUPA FAILED ',IO_PCB.STATUS_CODE);           
         END;                                                           
     END;                                                               
     PUT SKIP LIST                                                      
       ('INIT STATUS GROUPA =  ',IO_PCB.STATUS_CODE);                   
 END II00_INITSTAT;                                                     
 JJ00_INQY: PROC;                                                       
     DCL DUMMY_LENGTH CHAR(4) INIT(' '); /* TO PLEASE IMS */            
     AIB.PCBNAME     = 'IOPCB';                                         
     AIB.SUB_FUNC    = 'DBQUERY   ';                                    
     AIB.OUT_LEN_TOT = 2000;                                            
     CALL AIBTDLI($3,INQY,AIB,IO_AREA);                                 
     PUT SKIP LIST('INQY ISSUED ON IOPCB BEFORE CHECK OF AIB RETURN');  
     IF AIB.RETURN = 0 THEN                                             
        PUT SKIP LIST('INQY ISSUED - 0 RC ON AIB.RETURN');              
     ELSE                                                               
       DO;                                                              
        PUT SKIP LIST ('AIB RETURN CODE   ',AIB.RETURN);                
        PUT SKIP LIST ('AIB REASON CODE   ',AIB.REASON);                
        PUT SKIP LIST ('IOPCB STATUS CODE ',IO_PCB.STATUS_CODE);        
        PUT SKIP LIST ('INQY IOPCB DBQUERY  UNSUCCESSFULL');            
       END;                                                             
     SELECT  (IO_PCB.STATUS_CODE);                                      
       WHEN ('  ')                                                      
         DO;                                                            
           PUT SKIP DATA (IO_AREA);                                     
           PUT SKIP DATA (IO_PCB.STATUS_CODE);                          
         END;                                                           
       WHEN ('NA')                                                      
         PUT SKIP LIST ('NA STATUS ON IO_PCB.STATUS_CODE');             
       WHEN ('NU')                                                      
         PUT SKIP LIST ('NU STATUS ON IO_PCB.STATUS_CODE');             
       OTHERWISE                                                        
         DO;                                                            
           PUT SKIP LIST                                                
           ('INQY  FAILED ',IO_PCB.STATUS_CODE);                        
         END;                                                           
     END;
     PUT SKIP LIST ('START B1CSTP FIND CALL');                          
     AIB.PCBNAME     = 'B1CSTP';                                        
     AIB.SUB_FUNC    = 'FIND     ';                                     
     AIB.OUT_LEN_TOT = 2000;                                            
     CALL AIBTDLI($3,INQY,AIB,IO_AREA);                                 
     PUT SKIP LIST('INQY B1CSTP FIND READY TO BE CALLED');              
     IF AIB.RETURN = 0 THEN                                             
        PUT SKIP LIST('INQY B1CSTP FIND CALLED  - 0 RC');               
     ELSE                                                               
       DO;                                                              
        PUT SKIP LIST ('AIB RETURN CODE   ',AIB.RETURN);                
        PUT SKIP LIST ('AIB REASON CODE   ',AIB.REASON);                
        PUT SKIP LIST ('CSTP_PCB STATUS CODE ',CSTP_PCB.STATUS_CODE);   
        PUT SKIP LIST ('INQY B1CSTP FIND  UNSUCCESSFULL');              
       END;                                                             
       PUT SKIP LIST ('CSTP  STATUS  ' ,CSTP_PCB.STATUS_CODE);          
       PUT SKIP LIST ('IO PCB        ', IO_PCB.STATUS_CODE);            
     SELECT  (CSTP_PCB.STATUS_CODE);                                    
       WHEN ('  ')                                                      
         DO;                                                            
           PUT SKIP DATA (CSTP_PCB.STATUS_CODE);                        
           PUT SKIP DATA (IO_AREA);                                     
         END;                                                           
       WHEN ('NA')                                                      
         PUT SKIP LIST ('NA STATUS ON  B1CSTP CSTPPCB.STATUS_CODE');    
       WHEN ('NU')                                                      
         PUT SKIP LIST ('NU STATUS ON  B1CSTP CSTPPCB.STATUS_CODE');    
       OTHERWISE                                                        
         DO;                                                            
           PUT SKIP LIST                                                
           ('INQY  FAILED ',IO_PCB.STATUS_CODE);                        
         END;                                                           
     END;                                                               
     PUT SKIP LIST ('START D1CSTP FIND CALL');                          
     AIB.PCBNAME     = 'D1CSTP';                                        
     AIB.SUB_FUNC    = 'FIND     ';                                     
     AIB.OUT_LEN_TOT = 2000;                                            
     CALL AIBTDLI($3,INQY,AIB,IO_AREA);                                 
     PUT SKIP LIST('INQY D1CSTP FIND READY TO BE CALLED');              
     IF AIB.RETURN = 0 THEN                                             
        PUT SKIP LIST('INQY D1CSTP FIND CALLED  - 0 RC');               
     ELSE                                                               
       DO;                                                              
        PUT SKIP LIST ('AIB RETURN CODE   ',AIB.RETURN);                
        PUT SKIP LIST ('AIB REASON CODE   ',AIB.REASON);                
        PUT SKIP LIST ('CSTP_PCB STATUS CODE ',CSTP_PCB.STATUS_CODE);   
        PUT SKIP LIST ('INQY D1CSTP FIND  UNSUCCESSFULL');              
       END;                                                             
       PUT SKIP LIST ('CSTP  STATUS  ' ,CSTP_PCB.STATUS_CODE);          
       PUT SKIP LIST ('IO PCB        ', IO_PCB.STATUS_CODE);            
     SELECT  (CSTP_PCB.STATUS_CODE);                                    
       WHEN ('  ')                                                      
         DO;                                                            
           PUT SKIP DATA (CSTP_PCB.STATUS_CODE);                        
           PUT SKIP DATA (IO_AREA);                                     
         END;                                                           
       WHEN ('NA')                                                      
         PUT SKIP LIST ('NA STATUS ON  D1CSTP CSTPPCB.STATUS_CODE');    
       WHEN ('NU')                                                      
         PUT SKIP LIST ('NU STATUS ON  D1CSTP CSTPPCB.STATUS_CODE');    
       OTHERWISE                                                        
         DO;                                                            
           PUT SKIP LIST                                                
           ('INQY  FAILED ',IO_PCB.STATUS_CODE);                        
         END;  
     END;                                                               
     PUT SKIP LIST ('START S1CSTP FIND CALL');                          
     AIB.PCBNAME     = 'XXCSTP';                                        
     AIB.SUB_FUNC    = 'FIND     ';                                     
     AIB.OUT_LEN_TOT = 2000;                                            
     CALL AIBTDLI($3,INQY,AIB,IO_AREA);                                 
     PUT SKIP LIST('INQY S1CSTP FIND READY TO BE CALLED');              
     IF AIB.RETURN = 0 THEN                                             
        PUT SKIP LIST('INQY S1CSTP FIND CALLED  - 0 RC');               
     ELSE                                                               
       DO;                                                              
        PUT SKIP LIST ('AIB RETURN CODE   ',AIB.RETURN);                
        PUT SKIP LIST ('AIB REASON CODE   ',AIB.REASON);                
        PUT SKIP LIST ('CSTP_PCB STATUS CODE ',CSTP_PCB.STATUS_CODE);   
        PUT SKIP LIST ('INQY S1CSTP FIND  UNSUCCESSFULL');              
       END;                                                             
       PUT SKIP LIST ('CSTP  STATUS  ' ,CSTP_PCB.STATUS_CODE);          
       PUT SKIP LIST ('IO PCB        ', IO_PCB.STATUS_CODE);            
     SELECT  (CSTP_PCB.STATUS_CODE);                                    
       WHEN ('  ')                                                      
         DO;                                                            
           PUT SKIP DATA (CSTP_PCB.STATUS_CODE);                        
           PUT SKIP DATA (IO_AREA);                                     
         END;                                                           
       WHEN ('NA')                                                      
         PUT SKIP LIST ('NA STATUS ON  S1CSTP CSTPPCB.STATUS_CODE');    
       WHEN ('NU')                                                      
         PUT SKIP LIST ('NU STATUS ON  S1CSTP CSTPPCB.STATUS_CODE');    
       OTHERWISE                                                        
         DO;                                                            
           PUT SKIP LIST                                                
           ('INQY  FAILED ',IO_PCB.STATUS_CODE);                        
         END;                                                           
     END; 

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.

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