Developing EGL programs for the IMS™ environment

EGL allows you to develop programs that run on IMS™. Depending on program and build-part characteristics, you can generate programs to run in any of the following regions:
  • a message processing program (MPP) region
  • an IMS™ FastPath (IFP) region
  • a batch message processing (BMP) region
Factors for each of these regions are discussed separately below.

In addition, the effect of build descriptors is also discussed in detail.

For more information on how to interact with IMS™ control blocks, see EGL support for runtime PSBs and PCBs.

Generating for the MPP region

You can generate two types of programs for the MPP region:
  • Text UI programs, which accept or display a text form.
  • Basic programs, which neither accept nor display text forms.
The following considerations apply to both Text UI and basic programs:
  • You can send output to another message queue; and for that purpose, you code an add statement to write a serial record that is associated (at generation time) with an alternate PCB or with an express alternate PCB. For output to a message queue, the file type associated with the serial record may be SMSGQ or MMSGQ. For details, see Using serial and print files in IMS.
  • You can send output to a printer; and for that purpose, you code a print statement to display a print form. You associate the printer (at generation time) with an alternate PCB or an express alternate PCB, specify the file type as SMSGQ, and also specify the IMS™ logical terminal name for the printer. Alternatively, at run time you can use converseVar.printerAssociation to change the IMS™ logical terminal name.
  • You can start an asynchronous transaction using vgLib.startTransaction().
  • You cannot access indexed or relative files.

The next two sections provide information particular to each of the two program types.

Text UI programs

If you code a main program that accepts or displays a text form, EGL handles the details of I/O PCB access. You must set the segmented program property to YES.

You can interact with the terminal by using the converse statement, which presents a text form and responds to the user's input by processing the statement that follows the converse statement. For an overview of the runtime behavior, refer to the EGL Language Reference.

Although use of a converse statement is relatively simple, you get better performance by using a show statement. You can use the show statement to return to the beginning of the same program or to another program. The show statement must specify the same form that the receiving program specifies as its inputForm. Use of the show statement limits the data that is saved to just the information in the form and record that are specified on the show statement. However, you must be sure to code your program so the form and record provide all the necessary information to continue the interaction with the program user.

Your program can run as an IMS™ conversational or nonconversational program, can transfer to or call another program, and can issue a show statement with a returning clause. For restrictions that apply to a particular type of statement, see the topic that describes the statement syntax.

On IMS™, a called Text UI program is not supported. A main Text UI program can transfer to or from a non-EGL IMS™ or IMSADF II program on the same IMS™ system. For more information, see one of the following topics:.

Basic programs

If you code a main program that neither accepts nor displays a text form, input is available from the IMS™ message queue. To retrieve that input, you code a loop that reads one message after another into a serial record that is associated with the I/O PCB. For input from a message queue, the file type associated with the serial record may be SMSGQ or MMSGQ. For details, see Using serial and print files in IMS.

In most environments, when a main basic program is started, the program's input record is initialized from the record that was passed by the transferring program. This is not true of a main basic program that is generated for the IMS™ BMP environment. Instead the target program must read the transferred record from the message queue.

An EGL-generated called basic program can be called from EGL-generated Java™ code on another platform.

Your program can run as an IMS™ nonconversational program and can transfer to a program or call another program in the same IMS/VS system. For restrictions that apply to a particular type of statement, see the topic that describes the statement syntax.

On IMS™, an EGL-generated called program cannot read from a message queue. A basic program cannot use the transfer to transaction statement.

Generating for the MPP IMS™ FastPath region

You can generate both Text UI and basic programs to run in an IMS™ FastPath (IFP) region, in which case the situation is the same as described for an MPP region, except that (in keeping with IMS™ requirements) the program must be nonconversational. In addition, use of multi-segment input message queues (including the use of converse statements) is not recommended for IMS™ fast path programs for performance reasons.

IMS™ imposes restrictions on fast path programs. These restrictions result in the following limitations on the use of EGL functions with fast path programs:
  • A transfer to transaction statement is supported only to a non-fast path program. In this case, the transferred-to program is responsible for responding to the terminal. A show statement is permitted.
  • dliLib.AIBTDLI(), dliLib.EGLTDLI(), and vgLib.VGTDLI() must use only the call types supported for fast path transactions.
  • Multiple-segment input message queues are not supported.
  • Only one of the following actions can be done for each get unique to the I/O PCB:
    • transfer to transaction or show statement
    • add statement for serial file associated with an alternate response PCB
    • dliLib.AIBTDLI(), dliLib.EGLTDLI(), and vgLib.VGTDLI() function calls using the I/O PCB or an alternate response PCB
To indicate that you want a nonconversational program to run as an IMS™ fast path program, set the imsFastPath build descriptor option to YES. This option causes the generated program to limit its use of IMS™ functions to that permitted by IMS™ fast path support. Use of fast path restricts the amount and type of diagnostic data that is provided when an error occurs in the generated program.
When a batch program runs in the IMS™ BMP environment and updates IMS™ fast path databases, the program must cause either a SYNC or CHKP call to commit the updates. You can cause a CHKP call by:
  • Using the sysLib.commit() service routine before the end of a batch-oriented BMP
  • Making sure that the get next statement for a serial file associated with an IMS™ message queue receives an endOfFile (QC status code) before the end of a transaction-oriented BMP.

Generating for the IMS™ BMP region

You can generate a basic program that runs in an IMS™ BMP region.

To create a transaction-oriented IMS™ BMP program, you must retrieve input from the IMS™ message queue by coding a loop that reads one message after another into a serial record that is associated with the I/O PCB. The use of single-segment and multi-segment message queues is as described earlier for IMS™ MPP programs. To create a batch-oriented IMS™ BMP program, do not read input from the IMS™ message queue. For details, see Using serial and print files in IMS.

An IMS™ BMP program can also send output to another message queue or printer as described for IMS™ MPP programs. An IMS™ BMP program can use any of the EGL statements that a program generated for z/OS® batch can use. In particular, you can do the following in an IMS™ BMP or z/OS® batch program:
  • Receive input or send output to a GSAM file. For that purpose, you code an add statement to write a serial record that is associated (at generation time) with a GSAM PCB. You also specify the file type as GSAM and specify the name of the GSAM data set. Alternatively, at run time you can use recordName.resourceAssociation to change the name of the data set.
  • Send print output to a GSAM data set; and for that purpose you code a print statement. You associate the printer (at generation time) with a GSAM PCB, specify the file type as GSAM and specify the name of the GSAM data set. Alternatively, at run time you can use converseVar.printerAssociation to change the name of the output GSAM data set.

Your code can transfer to or call another IMS™ BMP program. A called program cannot read from a message queue.

Effect of build descriptor options

You enforce some decisions outside of your code, by setting options in the build descriptor that is used at generation time.

To generate a program for an MPP or IFP region, set system to IMS/VS. The following options also apply:
  • To mandate the size of a SPA (as needed for a conversational program), set the build descriptor option spaSize. To ensure that a program is nonconversational, set that value to zero (as is the default).
  • To indicate that a conversational program transfers to or from an IMSADF II program, set the build descriptor option spaADF to YES.
  • To generate a FastPath program (which runs in an IFP region), set the build descriptor option imsFastPath to YES.
To generate a program for the IMS™ BMP region, set system to IMSBMP.
Additional build descriptor options apply only to the IMS/VS or IMS™ BMP environments:
  • imsLogID
  • mfsExtendedAttr
  • mfsIgnore
  • mfsUseTestLibrary
  • formServicePgmType
  • spaStatusBytePosition
The mfsDevice must also be set before you generate your formGroup.