Language Environment interface

Design overview

Communication between CICS and Language Environment is made by calling a special Language Environment interface module (CEECCICS) and passing to it a parameter list (addressed by register 1), which consists of an indication of the function to be performed and a set of address pointers to data values or areas.

Module CEECCICS is distributed in the Language Environment library, but must be copied to an authorized library defined in the STEPLIB concatenation of the CICS startup job stream.

All calls to Language Environment are made directly from the CICS language interface module DFHAPLI. This module is called by several components of CICS to perform specific functions. Table 1 lists those functions, and shows the name of the CICS module initiating each function call and the Language Environment call made by DFHAPLI to support the function. The format of each call parameter list is given in Language Environment interface parameter lists.

The logical relationship between the different calls is shown in Figure 1.

All calls to DFHAPLI use either the DFHAPLIM macro (for calls from outside the CICS application domain), or the DFHLILIM macro (for calls made from within the application domain).

How does CICS establish the connection with Language Environment

The procedure for establishing the initial connection with Language Environment is as follows:

1. Load CEECCICS. At CICS startup, DFHSIJ1 invokes DFHAPLI to “initialize languages”. DFHAPLI issues a BLDL for CEECCICS, followed by an MVS LOAD macro.
2. Initialize contact with Language Environment. Contact is first made with Language Environment by having CICS drive the partition initialization function. DFHAPLI attempts partition initialization only if the earlier load of CEECCICS was successful; otherwise, the logic is bypassed.

   If the Language Environment partition initialization is successful, and Language Environment indicates that it can support the running of programs in languages supported by CICS, a flag is set and no further processing takes place.

   If the partition initialization function fails, CICS issues error message DFHAP1200.

Application program contact with Language Environment. Whenever a program written in a supported language is run, the application’s attempt to make contact with Language Environment fails if the Language Environment initialization bits flag is not set. CICS then tries to run the program itself using the basic support for the language. If this fails, CICS then abends the transaction and sets the associated installed resource definition as disabled.

How is storage provided for the transaction

A set of work areas is required during the lifetime of any task that includes one or more programs supported by Language Environment. This set is known as the language interface work area. Also, a thread work area is required if Language Environment is involved in the running of the task. Further areas known as run-unit work areas (RUWAs) are required at run time if the transaction includes one or more programs that use Language Environment. For details, see How it works: Storage for the transaction.

How does the transaction manager acquire storage for tasks

During task initialization, the transaction manager acquires an area of storage, the language interface work area, which is large enough to hold all required data for calls to Language Environment. This area is contiguous with the EXEC interface storage (EIS), and its address is saved in TCACEEPT in the TCA.

The thread work area is usually contiguous with the language interface work area. Its address is always held in CEE_TWA in the language interface work area.

For every link level entered during the execution of the application, a run-unit work area must be acquired by CICS and its address passed to Language Environment during run-unit initialization. Its address is placed in EISRUSTG in the EXEC interface storage (EIS).

Control blocks

The main control block is the language interface work area. It is addressed by TCACEEPT in the TCA. For programs supported by Language Environment, the work area is mapped by the Language_Interface_Workarea DSECT.

Modules

Exits

No global user exit points are provided for this interface.

Trace

Trace entries are made on entry to and exit from DFHAPLI. Point IDs AP 1940 to AP 1945, with a trace level of PCA 1, correspond to these trace entries.

The function information is always interpreted.

For entry trace records, the program name and link level are also interpreted where applicable.

For exit trace records, the returned reason code is interpreted.

Also, all calls into and out of the language environments are traced at level 1. The point IDs are AP1948 to AP 1952.

The ERTLI function named in the DFHAPLI entry trace is the function requested on the call, while that named in the DFHAPLI exit trace is the ERTLI function most recently processed. There are some situations in which a trace record made on entry to DFHAPLI is not matched by a corresponding exit trace for the same ERTLI function. In particular, after making a call to Language Environment for thread initialization, DFHAPLI does not return to the caller, but proceeds with run-unit initialization and run-unit begin invocation before finally returning. Another example is the successful execution of a perform GOTO function, which results in DFHAPLI not returning to the caller.

External interfaces

Language Environment interface module CEECCICS

See Table 1 for an overview of functions and Language Environment interface parameter lists for the layout and contents of the parameter lists for the functions.

Work areas

These are the work areas required during the lifetime of any task that includes one or more programs that use the Language Environment interface. See Work areas reference for details.

• IOINFO
• PGMINFO1
• PGMINFO2
• Program termination block

Reference