Calling a remote CICS program from EGL-generated Java code or the debugger

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:
Here is the behavior at run time:
  1. 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.
  2. 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.
  3. 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.
  4. The following events depend on property values in the calllink element:
    1. 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.)
    2. 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.

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

  6. 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.
  7. 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:
  1. 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.”
  2. On CICS, an existing non-EGL program named PGMX expects arguments in the form of pointers in the COMMAREA.
  3. Your Java program includes a statement to call PGMX.
  4. In the build descriptor used to generate the caller, the linkage build descriptor option references a linkage options part named pgmLinkage.
  5. In that linkage options part, do as follows:
    1. Set the callLink element, property serverID property to the appropriate transaction code (in this case, to TRNX)
    2. Set the property remoteComType to CICSECI, CICSJ2C, or CICSSSL to indicate that the program is in the CICS environment
  6. 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.
  7. The CICS Transaction Gateway invokes TRNX on the CICS server. This transaction is associated with the CICS Mirror program named DFHMIRS.
  8. The CICS Mirror Program calls the EGL Catcher program named ELACSV7 (assuming that the EGL Java runtime code is version 7.0 or later.
  9. The EGL catcher program receives the parameters as values, converts the values passed over the network into one pointer per parameter, and calls PGMX.
  10. 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.
  11. The catcher program returns to the mirror program, which sends the data back through the CICS Transaction Gateway to the EGL Java runtime code.
  12. The EGL Java runtime receives these values, converts them to the appropriate locale, and resumes execution of the caller.

Feedback