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 (see CICS System Definition Guide).

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 10 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 External interfaces.

Table 10. Language Environment interface calls
Function Module Language Environment call
Terminate Languages DFHSTP Partition Termination
Establish Language
DFHPGLK
DFHPGLU
DFHPGPG
Establish Ownership Type
Start Program
DFHPGLK
DFHPGLU
Thread Initialization
Run Unit Initialization
Run Unit Begin Invocation
Run Unit End Invocation
Run Unit Termination
Thread Termination
Goto DFHEIP Perform Goto
Find Program Attributes DFHEDFX Determine Working Storage
Initialize Languages DFHSIJ1 Partition Initialization

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

Figure 67. Language Environment interface components
 This is a technical drawing showing the function calls from CICS to Language Environment and their logical relationship.
Note:
The actual passing of control to CEECCICS is made from the CICS language interface program (DFHAPLI), which provides a single point of contact between CICS and Language Environment. Other modules call DFHAPLI to initiate the desired function.

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).

Establishing the connection

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.

Storage 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".

The language interface work area contains storage for the following:

Also, a thread work area is required if Language Environment is involved in the running of the task. The length of a thread work area is a constant value that is notified to CICS by Language Environment during the partition initialization processing. This additional work area is built contiguous with the language interface work area if the transaction is known to contain one or more programs that use Language Environment. When such a program is first encountered, DFHAPLI:

  1. Gets from the transaction manager the address of the transaction-related instance data.
  2. Flags the data to tell the transaction manager that the transaction runs Language Environment application programs.
  3. Adds the length of the language interface work area to the total user storage length for that transaction.

This forces the transaction manager to acquire extra storage, during task initialization, as an extension to the language interface work area. For the first occurrence only, DFHAPLI acquires the thread work area.

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. The length of an RUWA varies for each program. The lengths required for work areas above and below the 16MB line by Language Environment are notified to CICS during the processing to establish ownership type for that program; thereafter they can be found in the program’s installed resource definition. CICS adds to the length for the RUWA above the 16MB line a fixed amount for its own purposes before acquiring the storage.

Storage acquisition

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 EIORUSTG in the EXEC interface storage (EIS).

[[ Contents Previous Page | Next Page Index ]]