Assembler Calling COBOL: Language Environment Setup

NON-LE ASSEMBLER DRIVER
    INITIALIZE LANGUAGE ENVIRONMENT ONCE
    CALL COBOL ROUTINE FOR EACH REQUEST
    TERMINATE LANGUAGE ENVIRONMENT ONCE

Assembler calling COBOL repeatedly can pay a runtime startup cost on every invocation when the first program is not Language Environment-conforming. The useful fix is architectural: establish one valid LE environment, run the COBOL work inside it, and end that environment only when the driver is finished.

Initialize Language Environment once, invoke COBOL repeatedly, and terminate the environment when the driver finishes.

Why the first program changes COBOL call cost

Language Environment supplies the common runtime for Enterprise COBOL and other conforming high-level languages on z/OS. If an LE-conforming main routine starts the application, the environment it establishes is available to routines called later. If a nonconforming Assembler main repeatedly invokes COBOL main programs without a reusable or preinitialized environment, LE initialization and termination can recur for each call.

The difference matters most when the called COBOL routine performs a small amount of work. A routine that only validates a short record can spend proportionally more time entering and leaving the runtime than a routine that processes thousands of records. Measure the full transaction or batch path; do not apply a runtime change from a microbenchmark alone.

Choose the environment pattern before changing code

Pattern	Best fit	Main caution
CEEENTRY and CEETERM	The Assembler driver can be changed to follow LE conventions.	Use the complete LE macro pattern and required register, save-area, PPA, CAA, and DSA conventions.
COBOL stub main	A small COBOL front end can establish LE before calling the existing Assembler driver.	The driver must return normally to the stub; document parameter ownership and final termination.
CEEPIPI	A non-LE driver must explicitly initialize, call routines many times, and terminate.	Select main-routine versus subroutine services deliberately and preserve the returned token.
RTEREUS	A carefully reviewed COBOL-only application meets every documented restriction.	It changes termination, storage, mixed-language, and nested-enclave behavior.

Practical order: IBM lists an LE-conforming first program first, followed by a COBOL stub and CEEPIPI subroutine preinitialization. Choose from the current application design, support requirements, and measured behavior rather than copying a legacy option list.

Make the Assembler main routine LE-conforming

CEEENTRY generates an LE-conforming prolog, while CEETERM generates the matching epilog and terminates the Assembler routine. They are not isolated drop-in statements. IBM requires CEEENTRY to be used with CEETERM, CEECAA, CEEDSA, and CEEPPA.

* Architectural sketch only; use IBM macro syntax and site standards
LEDRIVER CEEENTRY PPA=DRVPPA,MAIN=YES,AUTO=DRVAUTO
         ... validate the incoming OS linkage parameter list ...
         ... invoke COBOL routines under the established LE enclave ...
         CEETERM RC=0
         ... required CEEPPA, CEEDSA, and CEECAA definitions ...

A migration review must cover register usage, save-area chaining, addressing mode, parameter access, condition handling, and any code that inspects old COBOL control blocks. The IBM CEEENTRY reference defines the macro contract; the site's Assembler framework should supply the tested implementation pattern.

Use a COBOL stub when the driver cannot become LE-conforming

A small COBOL main program can start LE and call the original Assembler driver as a subroutine. The Assembler driver then invokes COBOL subprograms while the same environment remains active. This can be simpler than restructuring a large legacy driver.

       IDENTIFICATION DIVISION.
       PROGRAM-ID. LESTUB.

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  WS-DRIVER-RC       PIC S9(9) COMP VALUE ZERO.

       PROCEDURE DIVISION.
           CALL 'ASMDRVR' USING WS-DRIVER-RC
           IF WS-DRIVER-RC NOT = ZERO
               DISPLAY 'ASMDRVR RC=' WS-DRIVER-RC
           END-IF
           GOBACK.

The stub is intentionally small. Keep the cross-language parameter contract explicit, and make every routine return through the expected linkage. The COBOL called-subprogram guide covers LINKAGE SECTION, PROCEDURE DIVISION USING, and positional parameter matching.

Use CEEPIPI for explicit preinitialization

CEEPIPI lets a non-LE-conforming driver initialize an environment once, execute conforming high-level-language programs inside it, and terminate the environment explicitly. All CEEPIPI service requests must come from a non-LE environment. The first fullword in the OS-standard parameter list identifies the requested service.

Service	Function code	Purpose
init_sub	3	Create an environment for repeated subroutine execution and return its token.
call_sub	4	Invoke a named subroutine inside the already initialized environment.
term	5	Terminate the environment explicitly after the final request.

CEEPIPI init_sub  -> save environment token
repeat for each request:
    CEEPIPI call_sub -> target COBOL routine
    inspect service return, reason, and feedback information
CEEPIPI term      -> release the environment

This is a control-flow outline, not an Assembler parameter-list replacement. Use IBM's complete sample for field layouts, PreInit table entries, return information, and cleanup. The IBM CEEPIPI invocation example shows an Assembler driver calling COBOL through init_sub, call_sub, and term.

Choose main or subroutine preinitialization deliberately

CEEPIPI provides separate environments for repeated main-routine execution and repeated subroutine execution. A main-routine environment performs more reinitialization per invocation and starts each execution with a cleaner state. A subroutine environment does less reinitialization and retains more state between calls.

State check: faster repeated subroutine calls also mean the application can observe storage left by an earlier call. Review WORKING-STORAGE, files, acquired storage, condition handling, and application-level reset logic before moving a routine into a retained environment.

The IBM preinitialization interface table lists the supported function codes. Do not interchange call_main and call_sub merely because the program name is the same.

Treat RTEREUS as an application-specific choice

RTEREUS(ON) makes the COBOL runtime environment reusable, but IBM warns against using it as a system-level or region-level default. It is ignored under CICS, is not recommended under IMS, cannot be used with XPLINK or in a z/OS UNIX process, and does not support Enterprise COBOL programs compiled with THREAD.

It can also affect nested enclaves and mixed-language execution. Storage acquired for COBOL programs remains until the task or environment ends, and STOP RUN terminates the reusable environment. If the next invocation recreates that environment, the intended saving is lost.

Approval boundary: do not enable RTEREUS until the application inventory, termination paths, C and PL/I participation, nested-enclave use, storage growth, and platform restrictions have been reviewed. The IBM RTEREUS reference is the governing checklist.

Measure initialization rather than guessing

Run the unchanged driver and the candidate design with the same request count and comparable input. Capture elapsed time and CPU for the whole unit of work, then separate the first-call cost from steady-state repeated calls. Include cleanup and termination in the test; leaving the environment active at measurement end gives a false comparison.

Use RPTOPTS(ON) in a controlled run when you need confirmation of the effective LE runtime options. IBM notes that the report goes to SYSOUT on MVS by default, subject to MSGFILE. Link to the broader COBOL runtime-options guide for TEST, TRAP, VCTRSAVE, and RPTOPTS, and to the COBOL performance-tuning guide for compiler-level checks.

Diagnose common mixed-language failures

Symptom	Likely cause	Check
Every short call remains expensive	LE is still created and ended per invocation	Trace the first program, enclave lifetime, and the actual preinitialization sequence.
COBOL receives damaged parameters	Assembler parameter list and COBOL LINKAGE definitions disagree	Compare order, address, length, sign, PICTURE, and USAGE on both sides.
Later calls see old values	Subroutine environment retains state	Reset application state explicitly and test repeated calls with different inputs.
CEEPIPI call fails	Wrong function code, token, PreInit entry, or parameter list	Record the service return, reason, and feedback values before changing the target.
IGZ0168S after enabling RTEREUS	A nested enclave conflicts with default reusable-environment behavior	Remove the broad option change and review the documented nested-enclave restrictions.
Storage grows across requests	Loaded programs or LE-managed storage remain retained	Measure region growth and verify the explicit termination path.

The COBOL CALL performance guide handles static, dynamic, and nested-call cost. The COBOL RENT guide covers reentrant program requirements; neither replaces the LE-environment decision described here.

Implementation checklist

• Identify the true first program and confirm whether it follows Language Environment conventions.
• Count repeated COBOL invocations and measure first-call versus steady-state work.
• Select one ownership pattern: LE-conforming Assembler main, COBOL stub, CEEPIPI, or an approved specialized alternative.
• Validate register, save-area, addressing-mode, and parameter-list conventions.
• Keep COBOL and Assembler field definitions compatible at every parameter position.
• Check service return, reason, and feedback information on each CEEPIPI request.
• Test repeated-call state, error exits, normal termination, and storage growth.
• Confirm effective runtime options with a controlled RPTOPTS report when needed.
• Obtain system-programming review before changing LE defaults or placing routines in LPA or ELPA.

Official IBM references

• IBM: First program not LE-conforming
• IBM: Language Environment macros
• IBM: Using preinitialization services
• IBM: Checking effective runtime options
• IBM: RTEREUS usage notes and restrictions

Assembler calling COBOL FAQ

Why can repeated calls from Assembler to COBOL be slow?

When a non-Language Environment-conforming first program repeatedly invokes COBOL main programs, Language Environment can be initialized and terminated for each invocation. The startup work can dominate when each COBOL call does little processing.

Should an Assembler main program use CEEENTRY and CEETERM?

For a new or maintainable driver, making the Assembler main routine Language Environment-conforming is IBM's first listed choice. CEEENTRY and CEETERM are part of a required macro set, so use the full IBM pattern and local Assembler standards.

When is CEEPIPI useful for an Assembler driver?

CEEPIPI is useful when a non-Language Environment driver must create one preinitialized environment, invoke one or more conforming high-level-language routines repeatedly, and terminate the environment explicitly at the end.

Is RTEREUS a general replacement for CEEPIPI?

No. RTEREUS changes COBOL application behavior and has restrictions involving XPLINK, z/OS UNIX, THREAD, nested enclaves, mixed C or PL/I main programs, storage retention, and IMS. IBM says not to make RTEREUS(ON) a system-level or region-level default.

Make the runtime owner explicit: initialize LE once, prove that every repeated call uses that environment, and execute the matching termination path before accepting the change.