Transferring control in IMS™ BMP and z/OS® batch environments

Transfers in the IMS™ BMP and z/OS® batch environments are implemented in the following ways:
  • An EGL program initiates the transfer with either of the following statements:
    • transfer to program, implemented as either a static or dynamic call when transferring to another EGL program, or as an OS XCTL macro when transferring to a non-EGL program.
    • transfer to transaction, implemented as an OS XCTL macro.
  • A non-EGL program initiates a transfer to an EGL program with the OS XCTL command.

The next table outlines the different ways of implementing the transfers.

EGL Statement From Program To Program How Implemented
transfer to program EGL EGL COBOL CALL
Non-EGL OS XCTL
Non-EGL EGL
transfer to transaction EGL EGL
Non-EGL
Non-EGL EGL

The EGL build server statically links an EGL COBOL runtime stub program with each generated main program. This EGL COBOL runtime stub activates the EGL runtime environment and starts the first program in the run unit. The stub also fulfills the transfer request in response to a transfer statement issued by any program in the run unit.

Transfer from an EGL program to an EGL program using transfer to program

When an EGL program uses a transfer to program statement to transfer control to another EGL program, the transferring EGL program ends and returns control to the EGL COBOL runtime stub linked with the EGL program. The stub issues a static or dynamic call in accordance with the linkage options part specified at generation time, for the EGL transfer-from program. The EGL COBOL runtime stub program remains in control, and the EGL runtime environment remains active.

If the EGL transfer-to program in turn uses a transfer to program statement, control again returns to the EGL COBOL runtime stub program, which handles the requested transfer.

In each case, the EGL transfer-to program starts at its main function.

Transfer from an EGL program to an EGL program using transfer to transaction

When an EGL program uses a transfer to transaction statement to transfer control to another EGL program, the transferring EGL program ends and returns to an EGL COBOL runtime stub program linked with the EGL program. The stub issues an OS XCTL macro to transfer to the target program. Both COBOL and Rational® COBOL Runtime for zSeries® clean up and reestablish the runtime environment each time an OS XCTL macro is used. Both COBOL and Rational® COBOL Runtime for zSeries® use termination and initialization logic for the OS XCTL. You can set the synchOnTrxTransfer build descriptor option to YES to control commit points.

Transfer to a non-EGL program using either transfer to program or transfer to transaction

When an EGL program uses a transfer to program or transfer to transaction statement to transfer control to a non-EGL program, the transferring EGL program ends and returns to the EGL COBOL runtime stub program linked with the EGL program. The stub issues an OS XCTL macro to transfer to the non-EGL program. Both COBOL and Rational® COBOL Runtime for zSeries® clean up the runtime environment each time an OS XCTL macro is used. Both COBOL and Rational® COBOL Runtime for zSeries® use termination logic for the OS XCTL. The non-EGL program establishes it own runtime environment and does any initialization logic required by the OS XCTL. You can set the build descriptor option synchOnTrxTransfer to YES to control commit points.

If the EGL program was started with a PSB, both the record specified on the transfer and the dliLib.psbData structure are passed as OS XCTL parameters. Otherwise, only the record specified on the transfer is passed. Register 1 is 0 if no parameters are passed. See Standard linkage conventions.

Special considerations apply if you pass dliLib.psbData. For more information, see Format of the dliLib.psbData structure.

The target program can issue a FREEMAIN for the parameters passed from the EGL program. The FREEMAIN address is the address in register 1. The FREEMAIN length is the value in the length field plus 100.

When a transfer to program or transfer to transaction statement is used, you must indicate that you are transferring to a non-EGL program, in one of the following ways:

  • Set the property isExternal to yes on the transfer statement.
  • Specify the externallyDefined option in the linkage options part, in the linkage information for the transferToProgram or transferToTransaction element.

Transfer from a non-EGL program to an EGL program using OS XCTL

Transfers from a non-EGL program to an EGL program in the IMS™ BMP and z/OS® batch environments can be implemented by using an OS XCTL to the EGL program. Different ways of passing parameters with the OS XCTL command are described in the following sections.

Standard linkage conventions

One or two parameters are passed to the receiving program on the OS XCTL. The first parameter is the working storage buffer consisting of a 2-byte binary length field containing the buffer length (working storage data length plus 10), an 8-byte filler field, and the working storage data. The second parameter, used only if the EGL program is a DL/I program, is the dliLib.psbData structure. The following diagram shows the format of the parameter list that the transferring program should pass.

Figure 1. Passing parameters on OS XCTL: Example 1

Passing parameters on OS XCTL

For the format of the dliLib.psbData structure, see Format of the dliLib.psbData structure. Register 1 can be set to 0 if there is nothing to pass.

Standard linkage conventions that support FREEMAIN in the EGL program

If you want Rational® COBOL Runtime for zSeries® to issue a FREEMAIN for the areas passed to the EGL program, obtain a single area for all passed data with a length equal to the length of the working storage data you want to pass plus 110 bytes (see the figure below). Set up the parameter list pointers at the top of the area, put the length and filler fields starting at offset 100 in the area, and move the working storage data to be passed into the area at offset 110. Issue the OS XCTL macro with register 1 pointing to the start of the area.

Figure 2. Passing parameters on OS XCTL: Example 2

Passing parameters on OS XCTL
Note: The high-order bit must be turned on for one of the following pointers:
  • The pointer to working storage if dliLib.psbData is not passed
  • The pointer to dliLib.psbData if dliLib.psbData is passed.

PCB list linkage

If the EGL program is a DL/I program, the non-EGL program can also transfer to the EGL program, passing a list of PCBs as parameters on the OS XCTL. The EGL program receives control in this way if it is started as a DL/I z/OS® batch job. The PCBs must map to the PSB definition expected by the EGL program.

The input record for the EGL program is initialized according to data type if the EGL program is started with this interface.