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

You can call an IMS™ program remotely, from EGL-generated Java™ code or the EGL debugger. The called program can be generated from EGL or VisualAge® Generator or can be written in another language.

You can also invoke an IMS™ transaction remotely, as described in Calling a remote IMS™ transaction from EGL-generated Java™ code or the debugger.

When you call a program on IMS™ rather than a transaction, the program accessed is not the called program itself, but is a catcher program provided by Rational® COBOL Runtime for zSeries®. As shown later, the system programmer must re-link that catcher program. The effect of that task is to assign an alias for each runtime PSB associated with any transactions that are invoked remotely by EGL-generated Java™ code.

The runtime process is as follows:
  1. EGL runtime takes the name of the IMS™ transaction code from the linkage options part used at generation time of the calling program.
  2. EGL uses the connectors of IMS™ Connect to submit this transaction code, as well as the called program name and parameters, to the IMS™ message queue.
  3. The catcher program reads the called program name and parameters from the message queue and uses a z/OS® call to invoke the requested program. The name of the catcher program depends on the version of EGL you use. For version 7.0 and later of EGL, the catcher program is ELAISVN7. For earlier versions of EGL, the catcher program is ELAISVN.
  4. On regaining control, the catcher program submits the returned data to the IMS™ queue.
  5. IMS™ Connect reads the data from the queue and returns the data to the calling program.
Here is an example:
  1. On IMS™, the systems programmer carries out the following tasks:
    1. Creates a system definition that associates a transaction (for example, TRAN1) with a PSB (for example, PSB1).
    2. Links the catcher program (ELAISVN7 for EGL version 7 or later, or ELAISVN for an earlier version) to assign it the alias PSB1. The linkage can include up to 64 aliases of this kind, and you can give the module any name you choose. If you want to add an alias after 64, create a second load module.
  2. You place a statement in your Java™ program to call PGMX and to supply parameters for that program.
  3. In the build descriptor used to generate the program, you set the linkage build descriptor option to a linkage options part called pgmLinkage.
  4. In that linkage options part for program PGMX, you set the callLink element, serverID property to the appropriate transaction code (in this case, to TRAN1). Set the remoteComType to IMSTCP or IMSJ2C to indicate that the program is in the IMS™ environment.
  5. At run time, IMS™ Connect sends the transaction code (TRAN1), program name (PGMX), and parameters to the IMS™ message queue.
  6. Because TRAN1 has been invoked, IMS™ schedules PSB1, which starts the catcher program.
  7. The catcher program reads the message queue for the program name (PGMX) and parameters, then calls PGMX.
  8. When PGMX finishes, control returns to the catcher program, which places the returned data on the IMS™ message queue.
  9. IMS™ Connect returns the data to your Java™ code.
The transaction TRAN1 must be defined to IMS™ as a message processing program. Use the following IMS™ system definition as a model: 
APPLCTN PGMTYPE=TP,PSB=PSB1
TRANSACT CODE=TRAN1,MODE=SNGL,EDIT=ULC

Data will be folded to uppercase characters if the statement EDIT=ULC is omitted from the transaction definition.

Here is an example of the JCL the system programmer might use to re-link the catcher program ELAISVN7, in this case to assign the aliases PSB1 and PSB2. If you are using a version of EGL earlier than version 7, the catcher program is named ELAISVN: 
//L    EXEC ELARLINK 
//L.SYSLMOD DD DISP=SHR,DSN=loadLibraryName 
//L.SYSIN DD * 
INCLUDE SELALMD(ELAISVN7) 
ENTRY ELAISVN7 
ALIAS PSB1
ALIAS PSB2
NAME loadModuleName(R) 
/*
loadLibraryName
Name of the load library
loadModuleName
Name of the load module; usually ELAISVN7 (or ELAISVN for versions of EGL earlier than version 7).
IMS™ requires that the name of a runtime PSB be identical to the name (or, in this case, the alias) of the first program in a transaction. If you want your called program to be called, not only from remote code, but in another transaction on IMS™, you must do as follows:
  1. Create a second PSB that is named for the first program in that transaction.
  2. Structure that PSB like the PSB scheduled for the remote invocation.