| 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.”
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.
The following sections provide a more detailed description of the parameter formats used for call statement in the CICS environment.
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.

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

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

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

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:
| 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) |
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.”
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.
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.
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.
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
.
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
.
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.
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.