DSNACICS stored procedure

Environment

DSNACICS runs in a WLM-established stored procedure address space and uses the Resource Recovery Services attachment facility to connect to DB2.

If you use CICS Transaction Server for OS/390® Version 1 Release 3 or later, you can register your CICS system as a resource manager with recoverable resource management services (RRMS). When you do that, changes to DB2 databases that are made by the program that calls DSNACICS and the CICS server program that DSNACICS invokes are in the same two-phase commit scope. This means that when the calling program performs an SQL COMMIT or ROLLBACK, DB2 and RRS inform CICS about the COMMIT or ROLLBACK.

If the CICS server program that DSNACICS invokes accesses DB2 resources, the server program runs under a separate unit of work from the original unit of work that calls the stored procedure. This means that the CICS server program might deadlock with locks that the client program acquires.

Authorization

To execute the CALL statement, the owner of the package or plan that contains the CALL statement must have one or more of the following privileges:

• The EXECUTE privilege on stored procedure DSNACICS
• Ownership of the stored procedure
• SYSADM authority

The CICS server program that DSNACICS calls runs under the same user ID as DSNACICS. That user ID depends on the SECURITY parameter that you specify when you define DSNACICS.

The DSNACICS caller also needs authorization from an external security system, such as RACF®, to use CICS resources.

Syntax

The following syntax diagram shows the SQL CALL statement for invoking this stored procedure.

Because the linkage convention for DSNACICS is GENERAL WITH NULLS, if you pass parameters in host variables, you need to include a null indicator with every host variable. Null indicators for input host variables must be initialized before you execute the CALL statement.

>>-CALL--DSNACICS--(--+-parm-level-+-,--+-pgm-name-+-,---------->
                      '-NULL-------'    '-NULL-----'     

>--+-CICS-applid-+-,--+-CICS-level-+-,--+-connect-type-+-,------>
   '-NULL--------'    '-NULL-------'    '-NULL---------'     

>--+-netname-+-,--+-mirror-trans-+-,--+-COMMAREA-+-,------------>
   '-NULL----'    '-NULL---------'    '-NULL-----'     

>--+-COMMAREA-total-len-+-,--+-sync-opts-+-,--return-code,------>
   '-NULL---------------'    '-NULL------'                   

>--msg-area--)-------------------------------------------------><

Option descriptions

parm-level

Specifies the level of the parameter list that is supplied to the stored procedure. This is an input parameter of type INTEGER. The value must be 1.

pgm-name

Specifies the name of the CICS program that DSNACICS invokes. This is the name of the program that the CICS mirror transaction calls, not the CICS transaction name.

This is an input parameter of type CHAR(8).

CICS-applid

Specifies the applid of the CICS system to which DSNACICS connects.

This is an input parameter of type CHAR(8).

CICS-level

Specifies the level of the target CICS subsystem:

1

The CICS subsystem is CICS for MVS/ESA Version 4 Release 1, CICS Transaction Server for OS/390 Version 1 Release 1, or CICS Transaction Server for OS/390 Version 1 Release 2.

2

The CICS subsystem is CICS Transaction Server for OS/390 Version 1 Release 3 or later.

This is an input parameter of type INTEGER.

connect-type

Specifies whether the CICS connection is generic or specific. Possible values are GENERIC or SPECIFIC.

This is an input parameter of type CHAR(8).

netname

If the value of connection-type is SPECIFIC, specifies the name of the specific connection that is to be used. This value is ignored if the value of connection-type is GENERIC.

This is an input parameter of type CHAR(8).

mirror-trans

Specifies the name of the CICS mirror transaction to invoke. This mirror transaction calls the CICS server program that is specified in the pgm-name parameter. mirror-trans must be defined to the CICS server region, and the CICS resource definition for mirror-trans must specify DFHMIRS as the program that is associated with the transaction.

If this parameter contains blanks, DSNACICS passes a mirror transaction parameter value of null to the CICS EXCI interface. This allows an installation to override the transaction name in various CICS user-replaceable modules. If a CICS user exit routine does not specify a value for the mirror transaction name, CICS invokes CICS-supplied default mirror transaction CSMI.

This is an input parameter of type CHAR(4).

COMMAREA

Specifies the communication area (COMMAREA) that is used to pass data between the DSNACICS caller and the CICS server program that DSNACICS calls.

This is an input/output parameter of type VARCHAR(32704). In the length field of this parameter, specify the number of bytes that DSNACICS sends to the CICS server program.

commarea-total-len

Specifies the total length of the COMMAREA that the server program needs.

This is an input parameter of type INTEGER. This length must be greater than or equal to the value that you specify in the length field of the COMMAREA parameter and less than or equal to 32704. When the CICS server program completes, DSNACICS passes the server program's entire COMMAREA, which is commarea-total-len bytes in length, to the stored procedure caller.

sync-opts

Specifies whether the calling program controls resource recovery, using two-phase commit protocols that are supported by RRS. Possible values are:

1

The client program controls commit processing. The CICS server region does not perform a syncpoint when the server program returns control to CICS. Also, the server program cannot take any explicit syncpoints. Doing so causes the server program to abnormally terminate.

2

The target CICS server region takes a syncpoint on successful completion of the server program. If this value is specified, the server program can take explicit syncpoints.

When CICS has been set up to be an RRS resource manager, the client application can control commit processing using SQL COMMIT requests. DB2 for z/OS ensures that CICS is notified to commit any resources that the CICS server program modifies during two-phase commit processing.

When CICS has not been set up to be an RRS resource manager, CICS forces syncpoint processing of all CICS resources at completion of the CICS server program. This commit processing is not coordinated with the commit processing of the client program.

This option is ignored when CICS-level is 1. This is an input parameter of type INTEGER.

return-code

Return code from the stored procedure. Possible values are:

0

The call completed successfully.

12

The request to run the CICS server program failed. The msg-area parameter contains messages that describe the error.

This is an output parameter of type INTEGER.

msg-area

Contains messages if an error occurs during stored procedure execution. The first messages in this area are generated by the stored procedure. Messages that are generated by CICS or the DSNACICX user exit routine might follow the first messages. The messages appear as a series of concatenated, viewable text strings.

This is an output parameter of type VARCHAR(500).

User exit routine

DSNACICS always calls user exit routine DSNACICX. You can use DSNACICX to change the values of DSNACICS input parameters before you pass those parameters to CICS. If you do not supply your own version of DSNACICX, DSNACICS calls the default DSNACICX, which modifies no values and does an immediate return to DSNACICS. The source code for the default version of DSNACICX is in member DSNASCIX in data set prefix.SDSNSAMP. The source code for a sample version of DSNACICX that is written in COBOL is in member DSNASCIO in data set prefix.SDSNSAMP.

Example

The following PL/I example shows the variable declarations and SQL CALL statement for invoking the CICS transaction that is associated with program CICSPGM1.

/***********************/ 
/* DSNACICS PARAMETERS */ 
/***********************/
DECLARE  PARM_LEVEL  BIN FIXED(31); 
DECLARE  PGM_NAME    CHAR(8); 
DECLARE  CICS_APPLID CHAR(8); 
DECLARE  CICS_LEVEL  BIN FIXED(31); 
DECLARE  CONNECT_TYPE CHAR(8); 
DECLARE  NETNAME     CHAR(8); 
DECLARE  MIRROR_TRANS CHAR(4); 
DECLARE  COMMAREA_TOTAL_LEN BIN FIXED(31); 
DECLARE  SYNC_OPTS   BIN FIXED(31); 
DECLARE  RET_CODE    BIN FIXED(31); 
DECLARE  MSG_AREA    CHAR(500) VARYING;
  
DECLARE1 COMMAREA  BASED(P1),
         3 COMMAREA_LEN BIN FIXED(15),
         3COMMAREA_INPUT   CHAR(30),
         3 COMMAREA_OUTPUT  CHAR(100);
  
/***********************************************/
/* INDICATOR VARIABLES FOR DSNACICS PARAMETERS */ 
/***********************************************/
DECLARE 1 IND_VARS,
          3 IND_PARM_LEVEL   BIN FIXED(15),
          3 IND_PGM_NAME     BIN FIXED(15),
          3 IND_CICS_APPLID  BIN FIXED(15),
          3 IND_CICS_LEVEL   BIN FIXED(15),
          3 IND_CONNECT_TYPE BINFIXED(15),
          3 IND_NETNAME      BIN FIXED(15),
          3 IND_MIRROR_TRANSBIN FIXED(15),
          3 IND_COMMAREA     BIN FIXED(15),
          3 IND_COMMAREA_TOTAL_LEN BIN FIXED(15),
          3 IND_SYNC_OPTS    BIN FIXED(15),
          3 IND_RETCODE     BIN FIXED(15),
          3 IND_MSG_AREA     BIN FIXED(15);
  
/**************************/
/* LOCAL COPY OF COMMAREA */ 
/**************************/ 
DECLARE P1 POINTER;
DECLARE COMMAREA_STG CHAR(130) VARYING;

/**************************************************************/ 
/* ASSIGN VALUES TO INPUT PARAMETERS PARM_LEVEL, PGM_NAME,    */ 
/* MIRROR_TRANS, COMMAREA, COMMAREA_TOTAL_LEN, AND SYNC_OPTS. */ 
/* SET THE OTHER INPUT PARAMETERS TO NULL. THE DSNACICX       */ 
/* USER EXIT MUST ASSIGN VALUES FOR THOSE PARAMETERS.        */ 
/**************************************************************/
PARM_LEVEL = 1; 
IND_PARM_LEVEL = 0; 
 
PGM_NAME = 'CICSPGM1'; 
IND_PGM_NAME = 0 ; 
 
MIRROR_TRANS = 'MIRT'; 
IND_MIRROR_TRANS = 0; 
 
P1 = ADDR(COMMAREA_STG);
COMMAREA_INPUT = 'THIS IS THE INPUT FOR CICSPGM1'; 
COMMAREA_OUTPUT = ' ';
COMMAREA_LEN = LENGTH(COMMAREA_INPUT); 
IND_COMMAREA = 0; 
 
COMMAREA_TOTAL_LEN = COMMAREA_LEN + LENGTH(COMMAREA_OUTPUT); 
IND_COMMAREA_TOTAL_LEN = 0; 
 
SYNC_OPTS= 1; 
IND_SYNC_OPTS = 0; 
 
IND_CICS_APPLID= -1; 
IND_CICS_LEVEL = -1; 
IND_CONNECT_TYPE = -1; 
IND_NETNAME = -1; 
/*****************************************/ 
/* INITIALIZE
OUTPUT PARAMETERS TO NULL. */ 
/*****************************************/
IND_RETCODE = -1; 
IND_MSG_AREA= -1; 
/*****************************************/
/* CALL DSNACICS TO INVOKE CICSPGM1.     */ 
/*****************************************/
EXEC SQL 
 CALL SYSPROC.DSNACICS(:PARM_LEVEL         :IND_PARM_LEVEL,
                       :PGM_NAME           :IND_PGM_NAME,
                       :CICS_APPLID        :IND_CICS_APPLID,
                       :CICS_LEVEL         :IND_CICS_LEVEL,
                       :CONNECT_TYPE       :IND_CONNECT_TYPE,
                       :NETNAME            :IND_NETNAME,
                       :MIRROR_TRANS       :IND_MIRROR_TRANS,
                       :COMMAREA_STG       :IND_COMMAREA,
                       :COMMAREA_TOTAL_LEN :IND_COMMAREA_TOTAL_LEN,
                       :SYNC_OPTS          :IND_SYNC_OPTS,
                       :RET_CODE           :IND_RETCODE,
                       :MSG_AREA           :IND_MSG_AREA);

Output

DSNACICS places the return code from DSNACICS execution in the return-code parameter. If the value of the return code is non-zero, DSNACICS puts its own error messages and any error messages that are generated by CICS and the DSNACICX user exit routine in the msg-area parameter.

The COMMAREA parameter contains the COMMAREA for the CICS server program that DSNACICS calls. The COMMAREA parameter has a VARCHAR type. Therefore, if the server program puts data other than character data in the COMMAREA, that data can become corrupted by code page translation as it is passed to the caller. To avoid code page translation, you can change the COMMAREA parameter in the CREATE PROCEDURE statement for DSNACICS to VARCHAR(32704) FOR BIT DATA. However, if you do so, the client program might need to do code page translation on any character data in the COMMAREA to make it readable.

Restrictions

Because DSNACICS uses the distributed program link (DPL) function to invoke CICS server programs, server programs that you invoke through DSNACICS can contain only the CICS API commands that the DPL function supports.

Debugging

If you receive errors when you call DSNACICS, ask your system administrator to add a DSNDUMP DD statement in the startup procedure for the address space in which DSNACICS runs. The DSNDUMP DD statement causes DB2 to generate an SVC dump whenever DSNACICS issues an error message.