Calling subprograms from COBOL

In a CICS® system, when control is transferred from the active program to an external program, but the transferring program remains active and control can be returned to it, the program to which control is transferred is called a subprogram.

There are three ways of transferring control to a subprogram:

EXEC CICS LINK

The calling program contains a command in one of these forms:

EXEC CICS LINK PROGRAM('subpgname')
EXEC CICS LINK PROGRAM(name)

In the first form, the called subprogram is specified as an alphanumeric literal. In the second form, name refers to the COBOL data area with length equal to that required for the name of the subprogram.

Static COBOL call

The calling program contains a COBOL statement of the form:

CALL 'subpgname'

The called subprogram is explicitly named as a literal string.

Dynamic COBOL call

The calling program contains a COBOL statement of the form:

CALL identifier

The identifier is the name of a COBOL data area that must contain the name of the called subprogram.

For information about the performance implications of using each of these methods to call a subprogram, see the Enterprise COBOL for z/OS®: Programming Guide, and the IBM® Enterprise COBOL Version 3 Release 1 Performance Tuning Paper. The White Paper is available on the Web at www.ibm.com/software/ad/cobol/library

COBOL programs can call any language programs statically or dynamically. LINK or XCTL are not required for inter-language communication, unless you wish to use CICS functions such as COMMAREA. See Language Environment Writing Inter Language Communication Applications for guidance on mixing languages under Language Environment® control.

Rules for calling subprograms gives the rules governing the use of the three ways to call a subprogram. This information refers to CICS application logical levels. Each LINK command creates a new logical level, the called program being at a level one lower than the level of the calling program (CICS is taken to be at level 0). Figure 3 shows logical levels and the effect of RETURN commands and CALL statements in linked and called programs.

The term run unit is used in Figure 3. A run unit is a running set of one or more programs that communicate with each other by COBOL static or dynamic CALL statements. In a CICS environment, a run unit is entered at the start of a CICS task, or invoked by a LINK or XCTL command. A run unit can be defined as the execution of a program defined by a PROGRAM resource definition, even though for dynamic CALL, the subsequent PROGRAM definition is needed for the called program. When control is passed by a XCTL command, the program receiving control cannot return control to the calling program by a RETURN command or a GOBACK statement, and is therefore not a subprogram.

The terms 'translator' and 'translation' in Rules for calling subprograms refer to the separate translator. This step is not required if a compiler with an integrated translator is used.

Rules for calling subprograms

The following rules describe the requirements and behavior of called or linked subprograms.

Translation

LINK: The linked subprogram must be translated if it, or any subprogram invoked from it, contains CICS function.
Static and Dynamic COBOL CALL: The called subprogram must be translated if it contains CICS commands or references to the EXEC interface block (DFHEIBLK) or to the CICS communication area (DFHCOMMAREA).

Compilation

You must always use the NODYNAM compiler option (the default) when you compile a COBOL program that is to run with CICS, even if the program issues dynamic calls.

Link-editing

LINK: The linked subprogram must be compiled and link-edited as a separate program.
Static COBOL CALL: The called subprogram must be link-edited with the calling program to form a single load module (but the programs can be compiled separately). This can produce large program modules, and it also stops two programs that call the same program from sharing a copy of that program.
Dynamic COBOL CALL: The called subprogram must be compiled and link-edited as a separate load module. It can reside in the link pack area or in a library that is shared with other CICS and non-CICS regions at the same time.

CICS CSD entries without program autoinstall

(If you use program autoinstall, you do not need an entry in the CSD.)

LINK: The linked subprogram must be defined using RDO. If the linked subprogram is unknown or unavailable, even though autoinstall is active, the LINK fails with the PGMIDERR condition.
Static COBOL CALL: The calling program must be defined in the CSD. If program A calls program B and then program B attempts to call program A, COBOL issues a message and an abend(1015). The subprogram is part of the calling program so no CSD entry is required.
Dynamic COBOL CALL: The calling program must be defined in the CSD. If program A calls program B and then program B attempts to call program A, COBOL issues a message and an abend(1015). The called subprogram must be defined in the CSD. If the called subprogram cannot be loaded or is unavailable even though autoinstall is active, COBOL issues a message and abends (1029).

Return from subprogram

LINK: The linked subprogram must return using either RETURN or a native language return command such as the COBOL statement GOBACK.
Static and Dynamic COBOL CALL: The called subprogram must return using a native language return statement such as the COBOL statement GOBACK or EXIT PROGRAM. The use of RETURN in the called subprogram terminates the calling program.

Language of subprogram

LINK, Static and Dynamic COBOL CALL: Any language supported by CICS.

Contents of subprogram

The contents of any called or linked subprogram can be any function supported by CICS for the language (including calls to external databases, for example, DB2® and DL/I) with the exception that an assembler language subprogram cannot CALL a lower level subprogram.

Passing parameters to subprogram

Data can be passed by any of the standard CICS methods (COMMAREA, TWA, TCTUA, TS queues) if the called or linked subprogram is processed by the CICS translator.

LINK: If the COMMAREA is used, its address must be passed in the LINK command. If the linked subprogram uses 24-bit addressing, and the COMMAREA is above the 16MB line, CICS copies it to below the 16MB line, and recopies it on return.
Static COBOL CALL: The CALL statement may pass DFHEIBLK and DFHCOMMAREA as the first two parameters, if the called program is to issue EXEC CICS requests, or the called program can issue EXEC CICS ADDRESS commands. The COMMAREA is optional but if other parameters are passed, a dummy COMMAREA must also be passed. The rules for nested programs can be different. See Nesting: what the application programmer must do
Dynamic COBOL CALL: The CALL statement may pass DFHEIBLK and DFHCOMMAREA as the first two parameters, if the called program is to issue EXEC CICS requests, or the called program can issue EXEC CICS ADDRESS commands. The COMMAREA is optional but if other parameters are passed, a dummy COMMAREA must also be passed. If the called subprogram uses 24-bit addressing and any parameter is above the 16MB line, COBOL issues a message and abends(1033) .

Storage

LINK: On each entry to the linked subprogram, a new initialized copy of its WORKING-STORAGE SECTION is provided, and the run unit is reinitialized (in some circumstances, this can cause a performance degradation).
Static and Dynamic COBOL CALL: On the first entry to the called subprogram within a CICS logical level, a new initialized copy of its WORKING-STORAGE SECTION is provided. On subsequent entries to the called subprogram at the same logical level, the same WORKING STORAGE is provided in its last-used state, that is, no storage is freed, acquired, or initialized. If performance is unsatisfactory with LINK commands, COBOL calls may give improved results.

CICS condition, AID and abend handling

LINK

On entry to the called subprogram, no abend or condition handling is active. Within the subprogram, the normal CICS rules apply. In order to establish an abend or condition handling environment, that exists for the duration of the subprogram, a new HANDLE command should be issued on entry to the subprogram. The environment so created remains in effect until either a further HANDLE command is issued, or the subprogram returns control to the caller.

Static and Dynamic COBOL CALL

If the dynamic COBOL CALL fails, CICS abend handling is not invoked, and you may get a COBOL abend code (1013).

If the dynamic COBOL CALL fails, with Language Environment and CBLPSHPOP ON:

On entry to the called subprogram, no abend or condition handling is active. Within the subprogram, the normal CICS rules apply. On entry to the called subprogram, COBOL issues a PUSH HANDLE to stack the calling program’s condition or abend handlers. In order to establish an abend or condition handling environment that exists for the duration of the subprogram, a new HANDLE command should be issued on entry to the subprogram. The environment that this creates remains in effect until either a further HANDLE command is issued or the subprogram returns control to the caller. When control is returned to the calling program from the subprogram, COBOL unstacks the condition and abend handlers using a POP HANDLE.

If the dynamic COBOL CALL fails, with CBLPSHPOP OFF:

The condition/AID and abend handling for the calling program remain in effect.

Location of subprogram

LINK: Can be remote.
Static and Dynamic COBOL CALL: Must be local.

Flow of control between programs and subprograms

Figure 3 shows the possible flows between COBOL main and subprograms (also known as run units).

A main, or level 1 program can use the COBOL GOBACK or STOP RUN statements, or the CICS RETURN command to terminate and return to CICS. It can use a COBOL CALL statement to call a subprogram at the same logical level (level 1), or a CICS LINK command to call a subprogram at a lower logical level. A called subprogram at level 1 can return to the caller using the COBOL GOBACK statement, or can terminate and return to CICS using EXEC CICS RETURN.

A subprogram executing at level 2 can use the COBOL GOBACK or STOP RUN statements, or the CICS RETURN command to terminate and return to the level 1 calling program. It can use a COBOL CALL statement or a CICS XCTL command to call a subprogram at the same level (level 2). A subprogram called using the COBOL CALL at level 2 can return to the caller (at level 2) using the COBOL GOBACK statement, or can return to the level 1 calling program using EXEC CICS RETURN. A subprogram called using XCTL at level 2 can only return to the level 1 calling program, using GOBACK, STOP RUN or EXEC CICS RETURN.

See Application program logical levels for more information about program logical levels.

Figure 3. Flow of control between COBOL programs, run units, and CICS

Flow of control between COBOL programs and subprograms, described in preceding text.

[[ Contents Previous Page | Next Page Index ]]