You can call a CICS® program
remotely, from EGL-generated Java™ code
or from the EGL debugger. The called program can be generated from
EGL or VisualAge® Generator
or can be written in another language.
At debug or generation time, the properties in the linkage options
part,
calllink element vary by characteristics
of the called program. Specifically:
- If the called program is generated from EGL or VisualAge Generator, the value of the property remotePgmType is
EGL.
Note: An EGL-generated called program must be generated with
one of the following values for the property parmForm: CHANNEL,
COMMDATA, or COMMPTR. For details, see “parmForm in callLink element."
- If the called program is not generated from EGL or VisualAge Generator, the value of the property remotePgmType is
EXTERNALLYDEFINED .
Here is the behavior at run time:
- The EGL runtime code uses the linkage options part that was used
to generate the caller, taking from that part both the name of the
called program and the related CICS transaction
code.
- The EGL runtime code converts the data to EBCDIC based on the conversionTable property
specified in the callLink element and based
on the data types of the fields passed to the called program.
- The EGL runtime code uses the connectors of CICS Transaction Gateway to start the transaction
and to identify and pass the called program name and parameters to
the specific CICS region. The
exact path depends on the value of remoteComType,
whether CICSECI, CICSEXCI, CICSJ2C, or CICSSSL.
- The following events depend on property values in the calllink element:
- If the value of remotePgmType is EXTERNALLYDEFINED
or EGL and if the value of parmForm is COMMDATA,
the CICS mirror program invokes
the called program directly, and runtime code uses the COMMAREA to
exchange values with the called program. (COMMDATA is available only
if every argument being passed is a value variable or literal, not
a reference variable.)
- If the value of remotePgmType is EXTERNALLYDEFINED
or EGL and if the value of parmForm is COMMPTR,
the CICS mirror program invokes
an EGL catcher program.
The name of the catcher program depends
on the version of the client runtime code that makes the call. For
EGL version 7.0 and later, the catcher program is ELACSV7. For earlier
versions of EGL (or for VisualAge Generator),
the catcher program is ELACSV.
- If the value of remotePgmType is EXTERNALLYDEFINED
or EGL and the value of parmForm is CHANNEL,
the CICS mirror program invokes
an EGL catcher program; but in this case, the name of the catcher
program is ELACSV7C.
- If a catcher program is in use, the following statements apply:
- If the value of parmForm is COMMPTR,
the program transforms the calling parameters into pointers. In this
case, the catcher program calls the called program in one of two ways: by
a dynamic COBOL call (if the value of remotePgmType is
EGL) or by using a CICS LINK
(if the value of remotePgmType is EXTERNALLYDEFINED).
- If the value of parmForm is CHANNEL,
each parameter is passed in a separate container whose content includes
no pointers. In this case, the catcher program always calls the called
program by using a CICS LINK.
The catcher program calls the called program in one of two
ways: by a dynamic COBOL call (if the value of remotePgmType is
EGL) or by using a CICS LINK
(if the value of remotePgmType is EXTERNALLYDEFINED).
- The called program runs and returns the data back through the
same path used to start it; either directly or by way of the EGL catcher.
- The EGL runtime code converts the data back to the code page of
the caller according to the locale of the client machine and the data
types of the fields passed to the called program.
Here is an example:
- The CICS system programmer
creates a transaction named TRNX and associates it with the CICS mirror program DFHMIRS.
The transaction name must match the name specified in the calllink property serverID.
The characteristics of that transaction are as described in the following
topic: “serverID in callLink element.”
- On CICS, an existing non-EGL
program named PGMX expects arguments in the form of pointers in the
COMMAREA.
- Your Java program includes
a statement to call PGMX.
- In the build descriptor used to generate the caller, the linkage build
descriptor option references a linkage options part named pgmLinkage.
- In that linkage options part, do as follows:
- Set the callLink element, property serverID property
to the appropriate transaction code (in this case, to TRNX)
- Set the property remoteComType to CICSECI,
CICSJ2C, or CICSSSL to indicate that the program is in the CICS environment
- At run time, the EGL runtime code converts the data and then sends
the transaction code (TRNX); program name (ELACSV7, because this call
requires the use of the EGL catcher program); and the parameters (including
the name of the target called program) to the CICS Transaction Gateway.
- The CICS Transaction Gateway
invokes TRNX on the CICS server.
This transaction is associated with the CICS Mirror program named DFHMIRS.
- The CICS Mirror Program
calls the EGL Catcher program named ELACSV7 (assuming that the EGL Java runtime code is version 7.0
or later.
- The EGL catcher program receives the parameters as values, converts
the values passed over the network into one pointer per parameter,
and calls PGMX.
- When PGMX finishes, control returns to the catcher program, which
receives pointers to the returned data and builds a buffer of data
values to return to the caller.
- The catcher program returns to the mirror program, which sends
the data back through the CICS Transaction
Gateway to the EGL Java runtime
code.
- The EGL Java runtime receives
these values, converts them to the appropriate locale, and resumes
execution of the caller.