Calling an IMS program from EGL-generated Java code

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

The program accessed on IMS is not the called program itself, but is a catcher program provided by Enterprise Developer Server for z/OS®. 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
  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 ELAISVN to assign it the alias PSB1. The linkage can include up to 64 aliases of this kind, and the name of the module name can be any you choose. If you wish 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, you set the callLink element, serverID property to the appropriate transaction code (in this case, to TRAN1).
  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=UL
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 ELAISVN, in this case to assign the aliases PSB1 and PSB2:
//L    EXEC ELARLINK 
//L.SYSLMOD DD DISP=SHR,DSN=load-library-name 
//L.SYSIN DD * 
INCLUDE SELALMD(ELAISVN) 
ENTRY ELAISVN 
ALIAS PSB1
ALIAS PSB2
NAME load-module-name(R) 
/* 
load-library-name
Name of the load library
load-module-name
Name of the load module; usually ELAISVN
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 wish your called program to be called, not only from remote code, but by a program on IMS, you must do as follows:
  1. Create a second PSB that is named for the first program in the additional run unit
  2. Structure that PSB like the PSB scheduled for the remote invocation

Related concepts
EGL support for runtime PSBs and PCBs
IMS runtime support
Linkage options part

Related reference
callLink element

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.