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:
- EGL runtime takes the name of the IMS transaction
code from the linkage options part used at generation time of the
calling program.
- 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.
- 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.
- On regaining control, the catcher program submits the returned
data to the IMS queue.
- IMS Connect reads the data
from the queue and returns the data to the calling program.
Here is an example:
- On IMS, the systems programmer
carries out the following tasks:
- Creates a system definition that associates a transaction (for
example, TRAN1) with a PSB (for example, PSB1).
- 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.
- You place a statement in your Java program
to call PGMX and to supply parameters for that program.
- In the build descriptor used to generate the program, you set
the linkage build descriptor option to a
linkage options part called pgmLinkage.
- 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.
- At run time, IMS Connect
sends the transaction code (TRAN1), program name (PGMX), and parameters
to the IMS message queue.
- Because TRAN1 has been invoked, IMS schedules
PSB1, which starts the catcher program.
- The catcher program reads the message queue for the program name
(PGMX) and parameters, then calls PGMX.
- When PGMX finishes, control returns to the catcher program, which
places the returned data on the IMS message
queue.
- 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:
- Create a second PSB that is named for the first program in that
transaction.
- Structure that PSB like the PSB scheduled for the remote invocation.