Considerations for IBM Language Environment

Considerations for IBM Language Environment

This section applies only to runtime support for COBOL programs that run in an online DC/UCF region. It does not apply to batch or CICS programs that access CA IDMS. It also does not apply to online COBOL programs compiled with the "old" VS COBOL compiler, prior to VS COBOL II. Online VS COBOL programs must comply with the compile and linkage restrictions described in Compiling and Executing CA IDMS Programs. If these restrictions are observed, the LE runtime environment will not be accessed by VS COBOL programs. This section does apply to programs compiled under VS COBOL II when run in online LE runtime environment.

What is IBM Language Environment (LE)?

LE is a runtime environment that replaces the language-specific runtime environments that existed previously. For example, VS COBOL had its own runtime environment; VS COBOL II had another. CA IDMS can execute programs that are designed to use the LE runtime environment. It can also execute programs compiled with pre-LE compilers that use the LE runtime environment subject to IBM's documented restrictions.

Language Environment has had several names for different operating systems and release levels. The term "LE" will be used in this document to refer to the IBM runtime Language Environment for any of the following operating systems:

• z/VSE
• z/OS
• z/VM

Note: This section applies only to runtime supportin CA IDMS/DC. It does not apply to batch or CICS programs that access CA IDMS.

How Can You Use LE with CA IDMS/DC?

To execute online programs using the LE runtime libraries, follow these steps to bring up your CA IDMS environment:

1. Ensure that the CA IDMS system has been generated with a 24-bit reentrant pool (or program pool, if no reentrant pool is generated) that is large enough to contain the IBM-supplied LE application program interface module CEEPIPI. The size of this module is approximately 100K.
2. Ensure that the CA IDMS system has been generated with an XA reentrant pool that is large enough to maintain residence for several IBM-supplied LE support modules. Allow 5 megabytes for these programs.

Include the LE runtime load libraries in the CDMSLIB loadlib concatenation before any other IBM language loadlibs you are using. For example, before COBOL II.

This section contains the following topics:

Considerations About LE Runtime

Running LE-Compliant Compiler Programs Under CA IDMS/DC

Supported LE Functions

Unsupported LE Functions

Performance Improvements with RHDCLEFE

Multiple-Program Enclave

Considerations About LE Runtime

Running Pre-LE Programs

There are restrictions that apply when you run pre-LE programs in an LE runtime environment within CA IDMS/DC. Pre-LE programs are programs that were compiled with a non-LE compliant compiler, such as COBOL II.

Some of these restrictions are already documented in Compiling and Executing CA IDMS Programs and Appendix H:. Additional restrictions for LE are:

• VS COBOL II programs have to run without storage protection unless RHDCLEFE (see "Performance Improvements with RHDCLEFE" below) is in use.
• VS COBOL II programs must be linked with an IGZEOPT module that specifies STAE=NO (see "Execution Time Options" in Appendix H:, for more information on the use of IGZEOPT). If this restriction is not observed, a program check in a COBOL program will result in immediate termination of the program with no indication of an error. Certain other abnormal abend conditions may also go unreported. This restriction does not apply if one of the following conditions is true:
  • RHDCLEFE is in use. See "Performance Improvements with RHDCLEFE" later in this appendix for more information.
  • A special CEEDOPT or CEEROPT is in use as described later in this appendix under Runtime Options, and either or both of the following options is specified:

    ABTERMENC=((ABEND,...

    TRAP=((OFF,...

• The IBM LE support module CEEPIPI must be loaded once before any VS COBOL II program is run. This is most easily done by defining CEEPIPI as RESIDENT in the CA IDMS/DC sysgen using the following syntax.

  ADD PROGRAM CEEPIPI CONCURRENT ENABLED LANGUAGE ASSEMBLER
  NONOVERLAYABLE PROGRAM PROTECT REENTRANT RESIDENT REUSABLE .
  

• Restrictions mentioned in the IBM documentation (for example, the IBM COBOL/370 Migration Guide) apply.

  Note: Running pre-LE programs with LE runtime can degradeperformance in some circumstances. If you notice poor performance, you should consider recompiling the programs with the newer compiler or running with RHDCLEFE (see "Performance Improvements with RHDCLEFE" below). The use of RHDCLEFE also removes the necessity of forcing the load of CEEPIPI before running any VS COBOL II programs.

Running LE Programs

LE programs are programs that were compiled with an LE-compliant compiler. CA IDMS/DC supports all LE-compliant compilers supported by IBM including:

• IBM COBOL for VM
• IBM Enterprise COBOL for z/OS
• COBOL for z/VSE

For convenience, programs compiled with an LE-compliant compiler are referred to as "LE COBOL" programs below.

Running LE-Compliant Compiler Programs Under CA IDMS/DC

This section discusses Language Environment runtime options relevant to the online CA IDMS/DC environment.

Note: Also see Compiling and Executing CA IDMS Programs and Appendix H:. The restrictions on VS COBOL and VS COBOL II compile and runtime options also apply to programs compiled with an LE-compliant COBOL compiler unless specifically noted below.

See Appendix A: for sample compile and link JCL for both batch and online programs which use CA IDMS DML statements.

Runtime Options

The IBM Language Environment provides numerous options that control how programs operate at runtime. The default values are designed to be suitable in a batch environment. Therefore, it is necessary to modify some values for applications that are to run in a DC/UCF online system.

Note: As stated in the introduction to this appendix, this appendix does not apply to programs that run in a CICS or other region, even if they access CA IDMS using DML or SQL commands. It does apply to programs that run a DC/UCF online system, which are invoked from another front-end using CA IDMS UCF (such as an ADS/O application that is accessed using UCFCICS from a CICS front-end).

The IBM Language Environment provides a number of ways to specify runtime options. Four methods are supported for CA IDMS/DC online programs:

1. Modify, assemble, and link the IBM-supplied CEEUOPT module. Link the resulting module with each application program. Product Documentation Change LI18624 contains a sample version of the CEEUOPT with values that are appropriate for most online CA IDMS applications. Also consult the section "Creating an Application-Specific Runtime Options Module" in IBM's LE Installation and Customization Manual.
2. Assemble and link a CEEUOPT module as described above. Link the resulting module with RHDCLEFE. Make sure that RHDCLEFE is defined in the DC/UCF Sysgen (as described under "Performance Improvements Using RHDCLEFE" below). This option affects only COBOL programs. This is the recommended option for all online COBOL applications.
3. Assemble and link a specialized CEEDOPT module.

   Note: This method is not available for z/OS Version 1.10 and higher. Use method 1 or method 4 for non-COBOL applications on z/OS Versin 1.10 and higher.

   If this method is chosen, special copies of the IBM modules CEEBINIT and CEEPIPI must be maintained for use with online DC/UCF systems only. Due to maintenance considerations, this method is not recommended for COBOL applications. It is needed for PL/I programs compiled with a non-LE-compliant compiler. For more information on using this method, see Product Documentation Change LI23664.

4. Assemble and link a specialized CEEROPT module.

   Note: This method is not available for z/OS Version 1.9 and lower or for VSE. Use method 1 or 3 for those operating systems.

   If this method is chosen, a CEEROPT load module can be created to override desired options. Like CEEUOPT, and unlike CEEDOPT, you only need to specify those options which are to be different from the installation default LE run-time operations. The resultant load module must be included in a load library in the CDMSLIB concatenation ahead of the default SCEERUN load library.

   Note: The CEEROPT will be loaded in a CA IDMS region only if your CEEPRMxx member specified CEEROPT(ALL). For more information on using this module, refer to IBM documentation.

Except as discussed below, the IBM-supplied default runtime options can be used with any site-specific desired modifications. Note that the MSGFILE parameter is ignored and messages are sent to the CA IDMS log file.

Recommended settings for certain parameters are as shown below. For more details on these parameters see the IBM Language Environment Customization manual.

• ABTERMENC=(RETCODE) or ABTERMENC=(ABEND): This parameter affects the action taken when an LE enclave ends with an unhandled condition of severity 2 or higher. If RETCODE code is specified, the DC task will abend with message DC128004. If ABEND is specified, the DC task will abend with a Uxxx where xxx corresponds to the hexadecimal value of the user abend code set by LE. For example, an LE user abend 4093 would result in a DC task abend with code UFFD.
• ALL31=(ON): This parameter will minimize the amount of below-the-line storage that will be allocated by LE. This parameter requires that all COBOL programs are linked with AMODE(31). It is strongly recommended that any non-conforming programs be relinked so that ALL31=(ON) can be specified.
• DEBUG=(OFF): The DEBUG runtime option cannot be used in a DC environment.
• INTERRUPT=(OFF): Attention interrupts are handled by the CA IDMS/DC system and not by LE runtime support. Application COBOL programs can test for attention interrupts using the DC-ATTN-INT condition name under LE just as with earlier COBOL runtime environments.
• POSIX=(OFF): POSIX is not supported under DC/UCF.
• RPTSTG=(OFF) or RPTSTG=(ON): Normally OFF should be specified. OFF must be specified for systems prior to release 14.1.

  The purpose of RPTSTG is to determine the storage utilization for a particular application. The report is produced at the end of a COBOL task thread and is written to the CA IDMS log file. For efficiency reasons, the termination phase of COBOL processing is normally not executed in an online DC environment. If it is necessary to obtain storage information for a particular application, optional bit 196 can be set (See "COBOL II and LE COBOL Task Management" in Optional Online COBOL Functionality). Note that this option adversely affects performance. Storage reports are therefore normally produced only in a test or development system.

• TERMTHDACT=(QUIET) or TERMTHDACT=(TRACE): This option controls the extent of LE runtime information that will be supplied when an application terminates. All messages will be written to the DC log file.
• TRAP=(ON) or TRAP=(OFF): If ON is specified, program checks in an LE application will result in IBM LE error-handling being put into effect. COBOL-specific and LE messages will be written to the log. After these messages are written and the COBOL thread ends abnormally, the DC task will abend with message DC128004 and a task snap will be taken.

  If OFF is specified, program checks in an LE application will result in an immediate task snap. This is similar to the result in a VS COBOL or VS COBOL II runtime environment. No LE messages related to the program check will be written. Furthermore, if any PL/I applications are included in the online system, any ON ERROR clauses will not be handled properly.

In addition to the parameters above, we strongly recommend that you use smaller values than the default ones for the various heap (ANYHEAP, BELOWHEAP, and HEAP) parameters and stack (LIBSTACK and STACK) parameters because these are allocated on a task thread basis. Storage allocation is most efficient if relatively large values are specified as sixteen bytes less than a multiple of 4096. Smaller values than 4096 should be set for some parameters to avoid wasting storage. The values shown below have been found to be suitable for most DC/UCF systems.

Even when the smallest possible storage values are chosen, the IBM Language Environment requests a substantial amount of below-the-line storage for each program invoked in an online task--particularly with older releases of LE. This storage is used for functions which are not supported in an online DC/UCF system. For this reason, DC/UCF provides optional functionality which forces all LE storage to be allocated above the 16M line for tasks which are defined as LOCATION ANY. You can enable this functionality by specifying #DEFOPT OPT00227 when compiling module RHDCOPTF.

ANYHEAP=(2032,4080,ANYWHERE,FREE)
BELOWHEAP=(496,496,FREE)
HEAP=(2032,4080,ANYWHERE,KEEP,2032,2032)
LIBSTACK=(496,496,FREE)
STACK=(2032,8176,ANY,KEEP)
STORAGE=(NONE,NONE,NONE,0)
THREADHEAP=(0100,0100,ANYWHERE,KEEP)

Supported LE Functions

CA IDMS/DC supports these LE functions:

• Math services
• National language support services
• Date and time services
• XML parsing

CA IDMS/DC also supports storage management services, but for performance reasons, they are not recommended. The storage management services are:

• CEECRHP: Create heap segment
• CEECZST: Re-allocate (change size of) heap storage
• CEEDSHP: Discard heap segment
• CEEFRST: Free heap storage
• CEEGTST: Get heap storage

Unsupported LE Functions

CA IDMS/DC does not support the following LE functions:

• CEE3PRM: Get exec parms
• CEETDLI: Call IMS
• CEETEST: Invoke debugging environment

Performance Improvements with RHDCLEFE

Beginning with Release 14.1, CA IDMS supports a more efficient method of running online VS COBOL II and LE COBOL programs under LE runtime. In order to realize this performance improvement, link RHDCLEFE and define it in the CA IDMS sysgen with the following values:

ADD PROGRAM RHDCLEFE
 CONCURRENT
 DYNAMIC
 ENABLED
 LANGUAGE IS ASSEMBLER
 NEW COPY IS ENABLED
 NONOVERLAYABLE
 PROGRAM
 NOPROTECT
 REENTRANT
 RESIDENT
 REUSABLE.

The advantages of using defining RHDCLEFE in an LE runtime environment are as follows.

• COBOL II programs can run with Storage Protect.
• If RHDCLEFE is in use, it is not necessary to link CEEUOPT with each application program.
• If a VS COBOL II or an LE COBOL program is invoked multiple times in the same task using an CA IDMS DML call (#LINK from Assembler, DC TRANSFER from COBOL or PL/I, or LINK from ADS/O), then only one LE enclave and one LE environment will be established.

  The use of RHDCLEFE can reduce the CPU usage for TRANSFER CONTROL to another COBOL program, particularly a VS COBOL II program. Without RHDCLEFE, each such invocation of a VS COBOL II program will result in the establishment and termination of both the environment and the enclave. Each such invocation of a LE COBOL program will result in the establishment and termination of the enclave.

  Note: RHDCLEFE is linked with a CEEUOPT with ALL31=(ON). As a consequence, all LE COBOL and VS COBOL II programs must be linked with AMODE(31) or AMODE(any).

Multiple-Program Enclave

This feature became available on release 15.0 service pack 3.

You can improve the performance of certain online applications that use COBOL programs under the IBM Language Environment (LE) by enabling a new optional feature which allows the use of a single LE enclave for multiple programs. The following explains the conditions under which performance can be improved and some restrictions on the programs that can utilize this new feature:

• Because of restrictions on the applications that can use the new functionality, this feature is not in effect unless MULTIPLE ENCLAVE IS ON is specified on the SYSTEM statement in the DC System Generation. In addition, module RHDCLEFE must be in use as described in "Performance Improvements with RHDCLEFE." In release 15.0, this feature is available only for z/OS operating systems.
• When MULTIPLE ENCLAVE IS OFF, each new LE program invoked within a DC online task causes the initialization of a new LE process and enclave, provided the program was invoked as a result of one of the following:
  • The DC task definition specified INVOKES PROGRAM...
  • The program was invoked using a TRANSFER CONTROL.
  • After an LE program is invoked in a given task, the same process and enclave can be reused if one of the following occurs:
  • The same program is invoked subsequently in the same task.
  • A different program is invoked from an LE COBOL program using a static CALL (CALL 'literal') or a dynamic CALL (CALL IDENTIFIER).
• When MULTIPLE ENCLAVE IS ON, a new LE process and enclave are created the first time an LE COBOL program is invoked in a task. Subsequent invocations of any COBOL program in the same task utilizes the same process and enclave even if it was invoked using TRANSFER CONTROL LINK or TRANSFER CONTROL RETURN.
• Starting an LE process and/or enclave involves considerable overhead of both storage and CPU utilization. Therefore, MULTIPLE ENCLAVE IS ON can provide significant improvement for tasks that invoke many programs using TRANSFER CONTROL RETURN or TRANSFER CONTROL LINK.

Restrictions on Using Multiple-Program Enclaves

The following restrictions apply to COBOL programs that participate in a multiple-program enclave:

• Enabled programs cannot perform a DC RETURN DML call and then be reentered using a subsequent TRANSFER. This restriction does not apply to programs that contain a DC RETURN with no subparameters because the DML compiler generates a GOBACK for this type of statement. This restriction does apply if the DC RETURN statement does have subparameters. For example, you cannot execute a "DC RETURN NEXT TASKCODE ..." statement and then reenter the same program in the same task.
• Enabled programs cannot issue a TRANSFER CONTROL NORETURN or a TRANSFER CONTROL XCTL.
• Optional bit 196 is ignored for programs that participate in a multiple-program enclave. Therefore, if MULTIPLE ENCLAVE IS ON at the system level, any program that depends on bit 196 must be exempted as described in "Exempting Programs from Multiple-Program Enclave."

Exempting Programs from Multiple-Program Enclave

You can enable multiple-program enclaves at the system level even if some programs are not eligible. An ineligible program can be exempted in one of two ways:

• Use the MULTIPLE ENCLAVE IS OFF clause of the PROGRAM statement in the DC System Generation.
• Use the MULTIPLE ENCLAVE OFF clause on the DCMT VARY PROGRAM statement or the DCMT VARY DYNAMIC PROGRAM statement.

Exempted programs can participate in the same task with eligible programs. All eligible programs share one process/enclave. Each exempted program uses its own process/enclave.