Coding the EXEC CICS LINK Statement

The COBOL program calls the CICS program using the External CICS Interface (EXCI). To use this interface, you need to code an EXEC CICS LINK call every time the COBOL program wants to invoke a CICS program.

CAUTION:

An EXCI call can only be executed in a service that is Container Managed. An EXCI call executed in an Application Managed generates an abend: EXIA.

This is similar to the EXEC CICS LINK call used in a CICS program to perform distributed program linking. However, there are some significant differences.

The format of the call is as follows:

EXEC CICS LINK
    PROGRAM(program-name)
    RETCODE(data-area-1)
    COMMAREA(data-area-2)
    .
    .
    .
    END-EXEC

where the options are as follows:

PROGRAM(`program-name`)	The name of the CICS program to be invoked
RETCODE(`data-area-1`)	An area in which the CICS program places a return code indicating sucess or failure
COMMAREA(`data-area-2`)	An area that the service program and the CICS program use for communications

The call must be immediately followed by an EXEC-END statement.

For example:

exec cics link
               program     (ws-program)
               commarea    (ws-commarea)
               retcode     (exci-exec-return-code)
end-exec

We supply a copy book, dfhxcplo.cpy, which provides data descriptions for RETCODE and COMMAREA. You can find this copybook in $COBDIR/cpylib. The copybook has data descriptions for the parameter passed in the RETCODE field, exci-exec-return-code:

01 exci-exec-return-code.
   03 exec-resp                pic 9(8) comp.
   03 exec-resp2               pic s9(8) comp.
   03 exec-abcode              pic x(4).
   03 exec-msg-len             pic 9(8) comp.
   03 exec-msg-ptr             pointer.