Calling programs in CICS environments

Use the linkage options part to specify how you want EGL to generate the call statement. In the CICS® environments, you can specify one of the following values for the type property for a callLink element in the linkage options part:
localCall
A call that is to be made in the same CICS region.
remoteCall
A call that is to be made from one CICS region to another or from a generated Java™ program to a generated COBOL program that runs in CICS.
For a localCall, you can also specify the linkType property that determines the actual call statement as follows:
DYNAMIC
Standard dynamic COBOL call.
STATIC
Standard static COBOL call. The called program must be link edited with the calling program.
CICSLINK
CICS LINK command (default for CICS programs). CICSLINK is only supported in the following situations:
  • The callLink element for the called program specifies a remoteCall.
  • The callLink element for the called program specifies parmForm = CHANNEL.
  • The call statement specifies isExternal = YES or the callLink element for the called program specifies pgmType = EXTERNALLYDEFINED.
In all other cases, including where CICSLINK is the default, EGL does not generate a CICS LINK command for linkType = CICSLINK. Instead EGL generates a standard dynamic COBOL call, the same call as if you specified linkType = DYNAMIC for the callLink element for the called program.
You must create a CICS RDO PROGRAM entry for any called program that is called with the following linkage options:
You can also specify how the parameters on the call statement are to be passed to the called program:
COMMPTR
Pointers to the parameters are passed in the COMMAREA (default for CICS programs if the property type is localCall).
COMMDATA
Parameter data is passed in the COMMAREA (default for CICS programs if the property type is remoteCall).
OSLINK
Parameters are passed using a standard COBOL parameter list. The called program cannot contain any CICS statements or be an EGL program.
CICSOSLINK
A standard COBOL parameter list is used. The first two parameters are the EXEC interface block (EIB) and COMMAREA followed by the call statement parameters.
CHANNEL
Parameters are passed in containers in a channel. The containers are named EGL-PARM-1 through EGL-PARM-n, where the maximum value of n is 30. No COMMAREA is passed in the CHANNEL parameter format.
Table 1. Valid parameter format and linkage combinations for CICS
  COMMPTR COMMDATA OSLINK CICSOSLINK CHANNEL
DYNAMIC Valid Valid Valid Valid No
STATIC Valid Valid Valid Valid No
CICSLINK Valid Valid No No Valid
REMOTE Valid if calling from an EGL-generated Java program; Not valid if calling from a CICS program. Valid No No Valid

For more information, see “Linkage options part.”

All calls described here are local calls between programs running on the same CICS system. Called programs can also run on a different system than the calling program as follows:

If either the calling or called program is a PL/I program, you must set the linkType property to CICSLINK. In addition, if the called program is a PL/I program, you must either specify isExternal = YES on the call statement or specify pgmType = EXTERNALLYDEFINED in the callLink element for the called program. If the calling program is a PL/I program, you must specify linkType = CICSLINK in the callLink element for the called EGL program.

The following sections give the specifics for using parameters with the call statement.

Format of call statement parameters for CICS

The following sections provide a more detailed description of the parameter formats used for call statement in the CICS environment.

Note: Special considerations apply if you pass dliLib.psbData or a PCB record as a parameter. For more information, see “Reference information for special parameters on a call or transfer statement.”

COMMAREA pointer (COMMPTR) parameter format

For the COMMPTR parameter format, pointers are passed in the CICS COMMAREA. The COMMAREA is generated in the calling program's COBOL working storage area. The high-order bit is set on for the last parameter address in the COMMAREA for the parameter format COMMPTR.

The figure below illustrates the COMMPTR parameter format. Register 1 points to a list of pointers. The first is the address of the EXEC interface block (EIB), followed by the address of the COMMAREA. Pointers to the parameters are passed in the COMMAREA.

COMMPTR parameter format

When you set the endCommarea build descriptor option to YES for the calling program, the calling program adds the x'FFFFFFFF' fullword at the end of the parameter list. You should set endCommarea to YES only when the called program requires this terminal fullword, as in a program that was previously called from a CSP/AE (Cross System Product/Application Execution) program. The length of the COMMAREA does not include the 4 bytes for this fullword unless endCommarea is set to YES. Under certain conditions, CICS passes a copy of the COMMAREA to the called program.

COMMAREA data (COMMDATA) parameter format

For the COMMDATA parameter format, the actual data is passed in a single buffer in the CICS COMMAREA. The COMMAREA is generated in the calling program's working storage area. Each parameter value is moved to the COMMAREA, where the values adjoin one another without regard for boundary alignment. If variable length records are passed, space is reserved for the maximum length record as defined to EGL. If a variable length record is passed that has the lengthItem property set, the required space must be defined within the fixed portion of the record. The called program must return the parameter values in the COMMAREA in the same order. The calling program moves the returned parameter values in the COMMAREA back to the original parameters.

The figure below illustrates the COMMDATA parameter format. Register 1 points to a list of pointers. The first is the address of the EIB, followed by the address of the COMMAREA. Actual parameter data is passed in the COMMAREA.

COMMDATA parameter format

OSLINK parameter format

For the OSLINK parameter format, the EIB and COMMAREA are not passed. Only the parameters specified on the call statement are passed. The high-order bit is set for the last address in the parameter list for parameter format OSLINK. OSLINK is valid only for DYNAMIC and STATIC linkage types. The called program must be one of the following:
  • A non-EGL program that does not contain any EXEC CICS commands
  • An EGL program that is generated for the ZOSBATCH environment. In this case, the called EGL program must not do any I/O. In addition, you must specify linkType = DYNAMIC in the callLink entry for the called EGL program.

The figure below illustrates the OSLINK parameter format. Register 1 points to a list of pointers that are the addresses of buffers of parameter data (one for each parameter).

OSLINK parameter format

CICSOSLINK parameter format

For the CICSOSLINK parameter format, the EIB and COMMAREA are always passed as the first two parameters followed by the parameters specified on the call statement. CICSOSLINK is valid only for STATIC and DYNAMIC linkage types.

The figure below illustrates the CICSOSLINK parameter format. Register 1 points to a list of pointers. The first is the address of the EIB, followed by the address of the COMMAREA, followed by the addresses of buffers of parameter data (one for each parameter).

CICSOSLINK parameter format

CHANNEL parameter format

For the CHANNEL parameter format, containers are passed in a channel. A channel is a set of containers that function like parameters for passing data between CICS programs. No COMMAREA is passed in the CHANNEL parameter format.

When an EGL generated program passes a channel to a called program, the channel has the same name as the called program. However, when an EGL called program receives a channel, the program uses a CICS API call to retrieve the name of the channel that was passed.

The containers are named EGL-PARM-1 through EGL-PARM-n, where the maximum value of n is 30.

For example, if you pass three parameters of type INT, Record (33,000 bytes), and EGL STRING, the channel will include three containers, as shown in the following table:

Table 2. Example containers and parameters
Container name Value in container
EGL-PARM-1 4 bytes representing the INT
EGL-PARM-2 33,000 bytes representing the record
EGL-PARM-3 4 bytes representing the pointer to the STRING (the called program must be EGL)

Calls from an EGL program to an EGL program

The called program runs and returns control to the calling program when the program ends or an exit program statement is encountered. Up to 30 parameters can be passed on the call statement. No CICS SYNCPOINT occurs as a result of a call statement. The type, linkType, and parmForm properties for a called program must be identical when generating both the calling and called program. If the linkage type or parameter format is changed, the called program and all programs that call it must be generated again. For a description of the parameter formats used for calls, see "Format of call statement parameters" above.

You can generate a called program for z/OS® batch and also use the program on CICS. To make the call work on CICS, do the mainframe setup described in IBM® Rational® COBOL Runtime Guide for zSeries, Chapter 11, section “CICS Setup for Calling z/OS Batch Programs in CICS.”

Calls from an EGL program to a non-EGL program

The call statement that calls a non-EGL program is implemented in the same way as when calling an EGL program. If the non-EGL program is written in assembler or COBOL, you can set the linkType option in the callLink entry for the called program to DYNAMIC, STATIC, or CICSLINK. However, if the non-EGL program is written in a language other than assembler or COBOL, or if it is called using EXEC CICS LINK, you must also specify one of the following options:
  • Set the isExternal property to YES on the EGL call statement.
  • Specify pgmType = EXTERNALLYDEFINED on the callLink entry for the called program.
If the non-EGL program uses a linkage convention other than the default (linkType = CICSLINK and parmForm = COMMPTR), you must include a callLink entry for the non-EGL program in the linkage option part with the correct values for the type, linkType, and parmForm properties. For a description of the parameter formats used for calls, see Format of call statement parameters for CICS.

The user program name must be defined to CICS and the program must exist in the operating system load library, or a NOT FOUND condition results. The program must also be link-edited according to CICS command level programming rules. Refer to the CICS application programmer's reference for more details.

Handling abends on calls from EGL programs to non-EGL programs

In CICS there are abend handling considerations when an EGL program uses a COBOL CALL instead of a CICS LINK to call a non-EGL COBOL program. In this situation, the COBOL runtime environment disables the CICS abend handling requested by the calling program on entry to the called program. The called program should reinstate the abend handler for the EGL program by issuing a CICS POP HANDLE statement on entry to the called program and a CICS PUSH HANDLE statement on exit from the called program.

If the abend handler is not reinstated and an abnormal termination occurs in the called program, normal error cleanup for the EGL program is not performed. The shared table use count is not updated when the program ends unsuccessfully. This might lead to an unnecessary copy of a shared table remaining in storage. No Rational COBOL Runtime for zSeries error messages are issued by the abend handler.

Refer to the application programming guide for your CICS environment for more information on using COBOL calls in a CICS environment.

Examples of COMMPTR definitions in programs

When an EGL program uses CICSLINK and COMMPTR to pass parameters to a non-EGL program, pointers to the parameters are passed in the CICS COMMAREA. The following sections show examples of how non-EGL programs can receive parameters passed using CICSLINK and COMMPTR.

Assembler language receiving parameters from CICSLINK with COMMPTR

         L     PARMPTR,DFHEICAP   Address parameter list
         USING PARMAREA,PARMPTR
         L     PARM1PTR,PARM1A    Address parameter 1
         USING PARM1,PARM1PTR
         L     PARM2PTR,PARM2A    Address parameter 2
         USING PARM2,PARM2PTR
         L     PARM3PTR,PARM3A    Address parameter 3
         USING PARM3,PARM3PTR
         .
         .                        And so on
         .
PARMAREA DSECT                    Define storage layout of parmlist
PARM1A   DS    F                  Passed pointer to parameter 1
PARM2A   DS    F                  Passed pointer to parameter 2
PARM3A   DS    F                  Passed pointer to parameter 3
PARM1    DSECT                    Define storage layout of passed parm
RECORD   EQU   *                  Parameter is a record
FLD1     DS    L10                Fields in record structure
FLD2     DS    L20                " "
FLD3     DS    L200               " "
         .
         .                        And so on
         .
PARM2    DSECT                    Define storage layout of passed parm
L7701    DS    L5                 Parameter is single data item level-77
PARM3    DSECT                    Define storage layout of passed parm
WORKSTOR EQU   *                  Parameter is working storage
FLD5     DS    L5                 Fields in working storage
FLD6     DS    L5                 " "
         .
         .                        And so on
         .

COBOL receiving parameters from CICSLINK with COMMPTR

LINKAGE SECTION.
01 DFHCOMMAREA.
  02 PARM1A                    USAGE IS POINTER.
  02 PARM2A                    USAGE IS POINTER.
  02 PARM3A                    USAGE IS POINTER.
01 PARM1.
  02 RECORD.
    03 FLD1                    PIC X(10).
    03 FLD2                    PIC X(20).
    03 FLD3                    PIC X(200).
      .
      .                               And so on
      .
01 PARM2.
  02 L7701                     PIC X(5).
01 PARM3.
  02 WORKSTOR.
    03 FLD5                    PIC X(5).
    03 FLD6                    PIC X(5).
      .
      .                               And so on
      .
PROCEDURE DIVISION.
  SET ADDRESS OF PARM1 TO PARM1A
  SET ADDRESS OF PARM2 TO PARM2A
  SET ADDRESS OF PARM3 TO PARM3A
      .
      .                               And so on
      .

Calls from a non-EGL program to an EGL program

The EGL program must be defined as a called program. The calling non-EGL program is responsible for setting the parameters as specified in the linkage option part for the called program when it was generated. For diagrams of the linkage generated for different parameter formats, see Format of call statement parameters for CICS.

The format of variables in the parameter list must match the definition specified for the parameters received by the called program. If they are not the same the results are not predictable.

The following example shows the format of CICS LINK for a program call to a program generated with the COMMPTR parameter format:
  EXEC CICS LINK
  PROGRAM('MYAPPL') COMMAREA(record of pointers) 
                   LENGTH(length of COMMAREA)
If the linkType is DYNAMIC or STATIC, at exit the called EGL program sets the COBOL special register RETURN-CODE to the value of the EGL variable sysVar.returnCode. This return code, which is stored in register 15, can be tested by the calling non-EGL programs.

Feedback