Adding Enterprise COBOL 5 or 6 programs to existing COBOL applications

When you add an Enterprise COBOL 5 or 6 program to an existing application, you are either recompiling an existing program with Enterprise COBOL 5 or 6 or including a newly written Enterprise COBOL 5 or 6 program.

Note: You should use this Migration Guide only if you have completed the runtime migration to Language Environment®. This means that the following steps have been completed:

Add Language Environment to the LNKLST/LPALST. This moves Language Environment into production, and all COBOL applications will run under Language Environment by default.
- The only COBOL runtime library present should be SCEERUN. Remove any instances of COBLIB, VSCLLIB, or COB2LIB in JCL STEPLIB or JOBLIB statements or in CICS startup JCL.
- Note: Only use one library for a given language in LNKLST/LPALST. For example, if you install Language Environment with the COBOL component in LNKLST/LPALST, do not have the OS/VS COBOL library or the VS COBOL II library installed in LNKLST/LPALST.
Optional: Add Language Environment to the STEPLIB JCL. This is a more gradual approach where Language Environment is phased in one region (CICS or IMS) or user (TSO) at a time.
Note: Programs run slower and use more virtual storage with this approach than using LNKLST/LPALST to access Language Environment.
For programs compiled with NORES, use REPLACE linkage-editor control statements to replace the existing runtime library routines compiled with Language Environment versions.
Ensure that SCEERUN is the only COBOL runtime library available in LNKLST/LPALST. Remove any other COBOL runtime libraries present, such as COBLIB, VSCLLIB, or COB2LIB.
For VS COBOL II programs IGZEBST bootstrap models compiled with RES, do one of the following tasks:
- Link to a runtime version of IGZEBST with APAR PN74000 applied
- REPLACE with IGZEBST from Language Environment

If these steps have not been completed, please first complete all runtime migration activities in Chapter 3. Planning the move to Language Environment of the Enterprise COBOL 4.2 Compiler and Runtime Migration Guide prior to following the steps here.

When you add Enterprise COBOL 5 or 6 programs to your existing applications, you have the ability to:

Upgrade your existing programs incrementally, as your shop's needs dictate
Use Language Environment condition handling

If you have a program object that includes a COBOL program linked with C, C++, or Enterprise PL/I programs, the program object has slightly different behavior when the COBOL program is changed to Enterprise COBOL 5 or 6. This occurs when such program objects are fetched (that is, using either C fetch or PL/I fetch) more than once. In the subsequent fetches, external and static variables in these other LE languages may retain their last used state, following COBOL rules, instead of getting their initial values. With prior versions of COBOL linked in, the C, C++ and PL/I programs would retain C/C++ or PL/I behavior.

Using Language Environment with Enterprise COBOL 5 or 6 and VS COBOL II programs

When running a mixture of VS COBOL II NORES programs and Enterprise COBOL 5 or 6 programs:

A current version of IGZEBST is required:
- For statically CALLed programs in CICS®, you will need to replace IGZEBST in applications with VS COBOL II programs with the IGZEBST from LE with the PTFs for APAR PI33330 installed.
  Note: IGZEBST from LE with the PTFs for APAR PI33330 installed can also be used with any COBOL programs VS COBOL II and later without COBOL 5 or 6 programs.
- For dynamically CALLed CICS programs, you just need to install the PTFs for APAR PI25079 on SCEERUN.
  Note: For statically CALLed programs in non-CICS, performance will be better if you replace IGZEBST in applications with VS COBOL II programs with the IGZEBST from LE with the PTFs for APAR PI33330 installed. It is not required. There is no issue with IGZEBST for dynamically called programs in non-CICS for calling VS COBOL II programs from COBOL 5 or 6 programs.
A current version of CEEBETBL, the Language Environment externals table, is required. If you are including object code bound some time ago with your COBOL 5 or 6 object code, you might be indirectly including an old version of CEEBETBL.
If the length of CEEBETBL you bind is less than x'28' (or the length of the CEEBETBL in the current SCEELKED library), it is old and needs to be replaced, or you will encounter runtime abends or a terminating runtime message.

If you rebind older object code with COBOL 5 or 6 as part of your migration, it is recommended that you specifically INCLUDE a current copy of CEEBETBL prior to INCLUDEs of the older object code, taking care that you do not inadvertently make CEEBETBL the entry point.

AMODE restrictions with Enterprise COBOL 5 or 6 programs

AMODE 24 execution of Enterprise COBOL 5.2 or 6 programs is supported in all the same cases as in earlier Enterprise COBOL compilers.

Note: To run COBOL 5 or 6 programs with AMODE 24, you must compile all COBOL programs with Enterprise COBOL V5.1.1 or later versions; or Enterprise COBOL V4.2 or earlier versions. If any component of a program object is compiled with Enterprise COBOL V5.1.0, the program object must run in AMODE 31. COBOL programs that run with AMODE 24 must be linked with the binder option RMODE(24).

Run time differences with Enterprise COBOL 5 or 6 programs

You cannot mix Enterprise COBOL 5 or 6 programs with:

OS/VS COBOL programs. You must migrate to Enterprise COBOL. To find any OS/VS COBOL programs, you can:
- Use COBOL Upgrade Advisor for z/OS® to run an inventory scan to discover what compiler versions are used in your load libraries or applications.
- Enable Language Environment to put out a message whenever an OS/VS COBOL program is run. To enable this warning message, set up IGZEOPT.
  The following is an example of the embedded HLASM code inside the JCL:
```
IGZUOPT CSECT
IGZUOPT AMODE 31
IGZUOPT RMODE ANY
*
  IGZXOPT SUPP_OSV=ON * ON: Suppress warning
       * ONCE: Only issue 1 warning
       * OFF: issue warning 
END
```
VS COBOL II NORES programs. You must migrate to Enterprise COBOL.

The ILBOABN0 interface for requesting an ABEND in a COBOL environment can be called dynamically with Enterprise COBOL 5 and later versions. When called by a program compiled with the Enterprise COBOL compiler, it will have the same result as calling CEE3ABD using ACTION code 1.

Your are strongly recommended to migrate and use the CEE3ABD interface, because the CEE3ABD interface provides additional flexibility to control the level of details provided in the CEEDUMP produced.

When your application is called by Enterprise COBOL programs, it might ABEND in an unexpected way if it has an older version of ILBOABN0 (before LE's SCEELKED) statically linked. To fix the unexpected ABEND, you can follow one of the advises in the following list:

Migrate to CEE3ABD.
Relink your application with REPLACE ILBOABN and resolve the reference against the LE SCEELKED library. (ILBOABN0 is an alias of ILBOABN.)
Change the COBOL program to use dynamic call for ILBOABN0.

RMODE restrictions with Enterprise COBOL 5 or 6 programs

Reentrant programs may be RMODE 24 or RMODE ANY
Non-reentrant programs must be RMODE 24.