CIUSPAPP Stored Procedure

With the help of this CICS® IA External Interface, you can access saved dependency data directly from your application.

What is the CIUSPAPP Stored Procedure?

CIUSPAPP is a DB2® Stored Procedure that acts as dependency data query interface. It can be called from a user application with the SQL CALL statement to get the collected dependency data from CICS IA interdependency database.

Syntax

You can call the CIUSPAPP procedure with the following SQL CALL statement:
EXEC SQL 
CALL CIUSPAPP (calltype, appcode, restype, error-message, return-code); 

Procedure parameters

There are several input parameters that assist you to manage CIUSPAPP processing and several output parameters that inform about the process completion and errors, if any.

The following table lists all the CIUSPAPP parameters.
Table 1. CIUSPAPP parameters
Parameter name input/output Type Description
calltype INPUT CHAR(4) Type of call
appcode INPUT CHAR(8) Application code
restype INPUT CHAR(8) Resource type
error-message OUTPUT CHAR(300) Error message text
return-code OUTPUT INTEGER Return code

CIUSPAPP INPUT parameters (calltype, appcode, restype)

The calltype parameter specifies queries that can be called by the application. The following table lists all available queries and their description.
Table 2. calltype values
calltype value Description
LIST Calls for a list of the applications that are defined in CICS IA. Fetches information from the CIU_APPLS_DESC table (APPLIC_CODE and APPLIC_NAME).
CICS Calls for a list of CICS resources. Fetches information from the CIU_CICS_DATA table (TYPE and OBJECT).
DB2 Calls for a list of DB2 resources. Fetches information from the CIU_DB2_DATA table (restypeand resname).
MQ Calls for a list of MQ resources. Fetches information from the CIU_MQ_DATA table (TYPE and OBJECT).
IMS™ Calls for a list of IMS resources. Fetches information from the CIU_IMS_DATA table (TYPE and OBJECT).
DEFN Calls for a list of all transactions/programs. Fetches information from the CIU_APPLS_RESOURCE table (APPLIC_CODE, APPLIC_TYPE, and APPLIC_RESNAME).
RES Calls for a list of CICS, DB2, IMS, and MQ resources for the defined appcode and restype parameters.

The appcode parameter specifies the Application Code. Required for calltype values CICS, DB2, MQ, IMS, DEFN, RES.

The restype parameter specifies the resource type. Required for the calltype value DEFN and has itself three values: PROGRAM, TRANSID, or null.

CIUSPAPP OUTPUT parameters (error-message, return-code)

The return-code parameter contains value of the CIUSPAPP return code. Possible return-code values are listed in the following table.
Table 3. return-code values
Return code Description
0 CIUSPAPP procedure that completed successfully.
4 One of the following conditions exists: either the calltype value is invalid, or an SQL exception/warning occurred during the CIUSPAPP run time.
5 The appcode value is not specified.
The error-message parameter contains message text that describes the error or warning:
  • For return-code = 4, it provides either the relevant SQL warning, or the "Invalid call type" message, depending on the error cause.
  • For return-code = 5, it provides the following message: "Application Code must be specified".

Returned result sets

The CIUSPAPP stored procedure returns a number of result sets depending on the input parameters values. A result set is a set of rows, effectively a table, which is associated with a cursor opened in the stored procedure and returned to the caller program. You can access the data that is returned in a result set when you run the SQL ASSOCIATE LOCATORS, followed by the SQL ALLOCATE cursor, and then the SQL FETCH loop as shown in the COBOL example for CIUSPAPP stored procedure.
List applications that are defined to CICS IA
To retrieve a list of user applications that are defined to CICS IA, you must set the input parameters as follows:
calltype = 'LIST'
The other input parameters are ignored and can be set to null values.

This call returns one result set with APPLIC_CODE and APPLIC_NAME columns from CIU_APPLS_DESC table.

List CICS resources that are used by an application
To retrieve a list of CICS resources that are used by one particular application, you must set the input parameters as follows;
calltype = 'CICS'
appcode  = application code
The restype input parameter is ignored and can be set to null value.

This call returns one result set with TYPE and OBJECT columns from the CIU_CICS_DATA table.

List DB2 resources that are used by an application
To retrieve a list of DB2 resources that are used by one particular application, you must set the input parameters as follows;
calltype = 'DB2'
appcode  = application code
The restype input parameter is ignored and can be set to null value.

This call returns one result set with restype and resname columns from the CIU_DB2_DATA table.

List MQ resources that are used by an application
To retrieve a list of MQ resources that are used by one particular application, you must set the input parameters as follows:
calltype = 'MQ'
appcode  = application code
The restype input parameter is ignored and can be set to null value.

This call returns one result set with TYPE and OBJECT columns from the CIU_MQ_DATA table.

List IMS resources that are used by an application
To retrieve a list of IMS resources that are used by one particular application, you must set the input parameters as follows:
calltype = 'IMS'
appcode  = application code
The restype input parameter is ignored and can be set to null value.

This call returns one result set with TYPE and OBJECT columns from the CIU_IMS_DATA table

List all transactions and programs that are used by an application
To retrieve a list of transactions and programs that are used by one particular application, you must set the input parameters as follows:
calltype = 'DEFN'
appcode  = application code
restype  = resource type
The restype input parameter must be set to either PROGRAM to list all application programs or to TRANSID to list all application transactions. To list both application programs and transactions, it must be set to null value.

This call returns one result set with APPLIC_CODE, APPLIC_TYPE and APPLIC_RESNAME columns from the CIU_APPLS_RESOURCE table.

List all CICS, DB2, MQ, and IMS resources that are used by an application.
To retrieve a list of all CICS, DB2, MQ, and IMS resources that are used by one particular application, you must set the input parameters as follows:
calltype = 'RES'
appcode  = application code
The restype input parameter is ignored and can be set to null value.

This call returns four result sets which returned separately for CICS, DB2, MQ, and IMS call types.

CIUSPAPP invocation

An example of a COBOL program, which calls the CIUSPAPP stored procedure and receives the contents of table CIU_APPLS_DESC:
       IDENTIFICATION DIVISION.                              
       PROGRAM-ID.  CALLSPM.                                 
       ENVIRONMENT DIVISION.                                 
       CONFIGURATION SECTION.                                
       INPUT-OUTPUT SECTION.                                 
       FILE-CONTROL.                                         
       DATA DIVISION.                                        
       FILE SECTION.                                         
       WORKING-STORAGE SECTION.                              
                                                             
      *****************************************************  
      *    WORKAREAS                                      *  
      *****************************************************  
       01  WV-APPLIC-NAME               PIC X(50).           
       01  WV-APPLIC-CODE               PIC X(08).           
       01  WW-CALLTYPE                  PIC X(4).            
       01  WW-APPLIC-CODE               PIC X(08).           
       01  WW-APPLIC-TYPE               PIC X(08).           
       01  WW-ERRMSG            PIC X(300).                  
       01  WW-RC                PIC S9(8) BINARY.            
                                                                        
      ****************************************************************  
      *    A RESULT SET LOCATOR FOR THE RESULT SET THAT IS RETURNED. *  
      ****************************************************************  
       01 LOC-DTLSC USAGE SQL TYPE IS                                   
          RESULT-SET-LOCATOR VARYING.                                   
                                                                        
       PROCEDURE DIVISION.                                              
      *------------------                                               
                                                                        
       MAINLINE.                                                        
           MOVE 'LIST'      TO WW-CALLTYPE.          
           MOVE '       '   TO WW-APPLIC-CODE.  
           MOVE '       '   TO WW-APPLIC-TYPE. 

           EXEC SQL                                             
            CALL CIUSPAPP(:WW-CALLTYPE,                         
                          :WW-APPLIC-CODE, :WW-APPLIC-TYPE,     
                          :WW-ERRMSG, :WW-RC)                   
           END-EXEC.                                            
                                                                
           EXEC SQL ASSOCIATE LOCATORS (:LOC-DTLSC)      
               WITH PROCEDURE CIUSPAPP                   
           END-EXEC.                                     
                                                              
           EXEC SQL ALLOCATE C1 CURSOR FOR RESULT SET   :LOC-DTLSC
           END-EXEC.                                     
                                                              
           EXEC SQL FETCH C1                             
                INTO  :WV-APPLIC-CODE, :WV-APPLIC-NAME   
           END-EXEC.                                     
                                                              
           DISPLAY 'CODE= '  WV-APPLIC-CODE  
                   'NAME= '  WV-APPLIC-NAME                   
           GOBACK.   

Concept Concept

Feedback


Timestamp icon Last updated: Friday, 22 November 2013


http://pic.dhe.ibm.com/infocenter/cicsts/v5r1/topic///ciuugsp03.html