Transferring to and from IMSADF II programs

Generated EGL programs can transfer to or from IMSADF programs. Immediate program-to-program message switches can be performed between IMSADF II conversational programs and EGL segmented conversational programs generated with the spaADF build descriptor option set to YES. In addition, IMSADF II secondary transactions can be processed by EGL batch programs.

Please note the following, however:

IMSADF II conversational processing

EGL cannot be used to initiate IMSADF II, but can be used to receive control from and return control to the IMSADF II transaction driver. This is supported only when the IMSADF II program system uses the IMSADF II 28-byte SPA with a work database.

The code example below shows an EGL DLISegment record definition for the IMSADF II, Version 2, Release 2, work database. The fields in this definition are limited to those you must modify if an EGL program is transferring directly to the IMSADF II conversational transaction driver.
//*** RECORD=ADFWKDB ****
// The sample segment layout of the ADFWORK database default
// segment size is 6000 bytes.  Use this DLISegment definition
// to retrieve data from and store data into the ADF work database.
// Refer to the IMSADF Application Development Guide
// Appendix E for details on which fields to update.
// ***********************
Record ADFWKDB type DLISegment  {
  keyItem = "LTERMNME"
  }
  3 LTERMNME char(8) ; 
  3 SPALEGTH smallint ; 
  3 * char(4) ; 
  3 SPATRANS char(8) ; 
  3 * char(397) ; 
  3 SPABITS hex(2) ; 
  3 * char(6) ; 
  3 SPAFIRST smallint ; 
  3 SPARTNCD int ; 
  3 SPASECTX smallint ; 
  3 * char(4) ; 
  3 SPAPGOPT smallint ; 
  3 SPASWITH char(2) ; 
    4 RDFSWITH smallint ; 
  3 SPATRX char(3) ; 
  3 SPACGTRX char(3) ; 
  3 * char(66) ; 
  3 SPASHOTR char(8) ; 
  3 * char(31) ; 
  3 SPAKEYID char(255) ; 
  3 SPAFLDSG char(5192) ; 
end   // end ADFWKDB

Rational® COBOL Runtime for zSeries does not share its work database with IMSADF II; the two databases have different formats. Changes to the IMSADF II work database do not affect the Rational COBOL Runtime work database. Similarly, changes made by an EGL program to the Rational COBOL Runtime work database do not affect the IMSADF II work database.

Starting from the IMSADF II side, define the EGL program to IMSADF II in the same way that you define a transaction that is written entirely in COBOL. Refer to the IMSADF II documentation for your system for additional information. The EGL generated program name (and therefore, the load module name) must obey the following IMSADF II naming convention:
ssssTcc
ssss
The IMSADF II program system ID.
T
A constant.
cc
The cluster code (SOMTX) operand used to generate the transaction that causes the switch to the EGL program.

From IMSADF II transaction driver to EGL program

When the program user enters the IMSADF II transaction ID that corresponds to the EGL program, IMSADF II does an immediate program-to-program message switch to the requested transaction. IMSADF II writes its own 28-byte SPA to the IMS™ message queue to perform the switch.

The EGL program must be generated with the spaADF build descriptor option set to YES and spaSize set to 28 to match the IMSADF II SPA size. When IMS schedules the new transaction, the EGL program control logic reads the IMSADF II SPA from the I/O PCB. Because of these build descriptor options, the EGL program control logic does not modify the SPA in any way. Therefore, the EGL program can eventually do an immediate program-to-program message switch back to the IMSADF II conversational transaction driver. Switching directly to the IMSADF II sign-on transaction is not supported.

If multiple EGL programs run before transferring back to the IMSADF II conversational transaction driver, all the EGL programs must be generated with these same build descriptor options. The program control logic uses the Rational COBOL Runtime work database or a second message segment following the SPA to pass records between the EGL programs, thereby preserving the IMSADF II-formatted SPA. Both deferred and immediate program-to-program message switches can be used between the EGL programs.

You can also specify the spaStatusBytePosition=p build descriptor option, where p specifies an available byte in the IMSADF II SPA that can be used for EGL's segmentation status byte. All EGL programs involved in a series of message switches that started from the IMSADF II transaction driver must have the same spaSize, spaADF, and spaStatusBytePosition build descriptor options. Refer to your IMSADF II documentation for information on the positions in the SPA that are available.

As in a COBOL program, the EGL program can access the IMSADF II work database to use information or to modify information in the IMSADF II communication area. If you access the IMSADF II work database, the EGL program processes the IMSADF II work database the way it would any other program database. Use the record definition above to access the IMSADF II work database. If you use a DL/I IMSADF II work database, be sure to include a database PCB in the EGL program's PSB definition.

From EGL program to IMSADF II transaction driver

To switch back to the IMSADF II transaction driver, your EGL program should set flags in the IMSADF II work database that tell the transaction driver what to do when it receives control. Refer to the IMSADF II documentation for your system for additional information. The EGL program transfers control using a transfer to transaction statement that specifies no record. Set sysVar.transferName to the name of the new transaction to be started; this variable must contain the same value that was placed in the IMSADF II variable SPATRANS. The EGL program control logic inserts the SPA to cause an immediate program-to-program message switch back to IMSADF II.

Transferring with conversational programs in ADF mode

The techniques described in this section are used only when there is a transfer from IMSADF II to a series of EGL programs and non-EGL programs prior to transferring back to IMSADF II. If only a single EGL program runs and then transfers back to IMSADF II, the program control logic automatically preserves the IMSADF II SPA. For transfers when IMSADF II is not involved, see “Transferring control in the IMS/VS environment.”

The following table shows the conventions used for transferring between EGL programs when the spaADF build descriptor option is set to YES. These conventions differ from the techniques used when IMSADF II is not involved in that special techniques are used to pass a record so the SPA can remain intact. ADF mode does not support transfers between segmented nonconversational programs.

Table 1. Transfers between EGL conversational programs
Action Immediate switch (optional input form) Deferred switch (with input form)
Coding and generating Define both programs as segmented = YES. Generate both programs as conversational with the spaSize build descriptor set to 28 and the spaADF build descriptor option set to YES. Define both programs as segmented = YES. Generate both programs as conversational with the spaSize build descriptor set to 28 and the spaADF build descriptor option set to YES.
Performing the transfer The originating program cannot send a form. If it is an EGL program, it does this using a transfer to transaction statement with a record. The originating program must write the form to a message queue associated with the terminal after first writing the SPA. If it is an EGL program, it does this using a show statement with a form and an optional record.
Using an input form The target program can optionally have an input form. The target program must have an input form.
Passing a record The record is transferred in a message segment following the SPA. The record, if any, is transferred through the work database.
Specifying segmentation status byte If spaStatusBytePosition was specified, the target program always ignores the value of the segmentation status byte that is located in the SPA at the offset specified. If spaStatusBytePosition was specified, the target program uses the value of the segmentation status byte at the offset specified when there is an input form integrity problem caused by the program user pressing PA1 or PA2.
The segmentation status byte specified by spaStatusBytePosition is used only for program to program transfers for conversational programs. The byte is present for transfers between conversational programs and other programs. However, a transferring non-EGL program should always set the byte to blank. A target non-EGL program can ignore the value of the segmentation status byte.

Conversational immediate program-to-program message switch

Conversational immediate program-to-program message switches are supported as follows:
  • Between two EGL programs.
  • From a non-EGL program to an EGL program.
  • From an EGL program to a non-EGL program.

Immediate switch between two EGL programs

With this technique two segmented conversational EGL programs can change both the transaction name and the PSB name without presenting a form to the program user. The two programs can use different FormGroups. For a skeleton definition of the two programs, see “Immediate switch between two EGL programs” in “Transferring control in the IMS/VS environment”; remember that you must set the spaADF build descriptor option to YES when IMSADF II programs are involved.

The EGL program control logic automatically preserves the SPA and manages the record that is passed as a message segment following the SPA for both programs A and B. Specify the same spaSize build descriptor option (28 bytes) for both programs A and B.

Immediate switch from non-EGL program to EGL program

The non-EGL program must be an IMS conversational program. The EGL program must be defined similarly to program B in "Immediate switch between two EGL programs" in “Transferring control in the IMS/VS environment”; remember that you must set the spaADF build descriptor option to YES when IMSADF II programs are involved.

The non-EGL program must do the following:
  1. Preserve the IMSADF II SPA format.
  2. Insert the SPA to an alternate PCB, with the destination set to the transaction name for the EGL program. If you specified a spaStatusBytePosition build descriptor option, the segmentation status byte is in the SPA at the offset specified. Initialize the segmentation status byte to blank before inserting the SPA.
  3. Insert the record you want to pass as a message segment after the SPA into the same alternate PCB. For the required layout of the message, see “Format of EGL input message for IMS nonconversational message switch.”

Immediate switch from EGL program to non-EGL program

The non-EGL program must be an IMS conversational program. The EGL program must be defined similarly to program A in "Immediate switch between two EGL programs" in “Transferring control in the IMS/VS environment”; remember that you must set the spaADF build descriptor option to YES when IMSADF II programs are involved.

The non-EGL program must do the following:
  1. Issue a get unique to the I/O PCB to read the SPA. This SPA is in the original IMSADF II format, unchanged by the EGL program. If you specified a spaStatusBytePosition build descriptor option, the segmentation status byte is in the SPA at the offset specified. The non-EGL program should ignore the value of the segmentation status byte.
  2. Issue a get next to the I/O PCB to read the message that contains the record that was passed by the EGL program. For the required layout of the message, see “Format of EGL input message for IMS nonconversational message switch."
  3. Preserve the IMSADF II SPA format.

Conversational deferred program-to-program message switch

Conversational deferred program-to-program message switches are supported as follows:
  • Between two EGL programs.
  • From a non-EGL program to an EGL program.
  • From an EGL program to a non-EGL program.

Deferred switch between two EGL programs

With this technique two segmented conversational EGL programs can change both the transaction name and the PSB name when a form is presented to the program user. The two programs must use the same FormGroup. You do not have to transfer a record, but a form is required. For a skeleton definition of the two programs, see “Deferred switch between two EGL programs” in “Transferring control in the IMS/VS environment”; remember that you must set the spaADF build descriptor option to YES when IMSADF II programs are involved.

Deferred switch from non-EGL program to EGL program

The non-EGL program must be an IMS conversational program. Define the EGL program similarly to program B in "Deferred switch between two EGL programs" in “Transferring control in the IMS/VS environment”; remember that you must set the spaADF build descriptor option to YES when IMSADF II programs are involved.

The non-EGL program must do the following:
  1. Preserve the IMSADF II SPA format. If you specified a spaStatusBytePosition build descriptor option, the segmentation status byte is in the SPA at the offset specified. Initialize the segmentation status byte to blank before inserting the SPA.
  2. Call ELATSPUT to save the record that you want to pass to the EGL program via the work database. For details see “Using the EGL COBOL runtime work database for IMS/VS.”
  3. Insert the SPA to the I/O PCB.
  4. Insert the form to the I/O PCB using the message output descriptor that corresponds to the message input descriptor in the EGL program. The non-EGL program must set the modified data tag (MDT) attribute for all variable data fields on the form to be passed to the EGL program on the deferred switch. All other attributes should be left at their default values. For the required layout of the form, see “Format of the IMS MFS message input descriptor (MID).” EGL creates a COBOL copybook for the MID/MOD record layout that the non-EGL program should use to ensure that the record formats match.

Deferred switch from EGL program to non-EGL program

The non-EGL program must be an IMS conversational program. Define the EGL program similarly to program A in "Deferred switch between two EGL programs" in “Transferring control in the IMS/VS environment”; remember that you must set the spaADF build descriptor option to YES when IMSADF II programs are involved. The EGL program must set the modified property to YES for all variable data fields on the form that the non-EGL program needs as input.

The non-EGL program must do the following:
  1. Issue a get unique to the I/O PCB to read the SPA. This SPA is in the original IMSADF II format, unchanged by the EGL program.
  2. Issue a get next to the I/O PCB to retrieve the message input descriptor that corresponds to the message output descriptor used by the EGL program. For the required layout of the map, see “Format of the IMS MFS message input descriptor (MID).” EGL creates a COBOL copybook for the MID/MOD record layout that the non-EGL program should use to ensure that the record formats match.
  3. Use the value of the MID form field EZEMAP-SSM-STATUS to determine whether a record was passed in the work database.
    • If either EZEMAP-SSM-WSR-SAVED or EZEMAP-SSM-WSR-MAP-SAVED is true, then there is a record in the work database. Retrieve it as described in step 4 below.
    • If EZEMAP-SSM-FILL-CHAR is true and this is not an initial SPA, then an input form integrity problem has occurred, probably because the program user has pressed PA1 or PA2. Take whatever action is appropriate for the program to recover the data that was lost from the input form. This might involve issuing an error message to the program user and restarting the transaction or other recovery actions depending on the program design. In this situation, if you specified a spaStatusBytePosition build descriptor option, the program can use the segmentation status byte to determine if a record was saved in the work database prior to the transfer. If the segmentation status byte has the value C, c, D, or d, then a record was saved in the work database and you can retrieve it as described in step 4 below.
  4. Call ELATSGET to retrieve the record saved by the EGL program in the work database. For details see “Using the EGL COBOL runtime work database for IMS/VS.”
  5. Preserve the IMSADF II SPA format.

Feedback