Modifying EGL build scripts for z/OS®

EGL uses build scripts to manage the preparation process for z/OS®. The build scripts perform the following tasks
  • Compile and link for a COBOL program, including the code generated from an EGL program, library, service, FormGroup,or DataTable part.
  • DB2® precompile and bind if a program, library or service performs SQL I/O.
  • CICS® translation if a program, library or service is generated for the z/OS® CICS® environment.

These build scripts are developed using pseudo-JCL, a form of JCL with some restrictions and a few extensions, as described in Pseudo-JCL syntax.

The build server reads the pseudo-JCL and processes it to invoke the build program against the data sets specified in the program. Because the build scripts reference data sets that contain the location of the DB2® preprocessor, the CICS® translator, the COBOL compiler, and the z/OS® linkage editor, you need to modify the shipped build scripts to at least specify the actual locations of these code-preparation components.

To modify EGL build scripts for z/OS®:
  1. Open the PROCLIB on the System 390 build server. (For information about installing the z/OS® build server, see the IBM® Rational® COBOL Runtime Guide for zSeries®.)
  2. Select the member (build script) that you want to edit.
  3. Edit the member. For information about the predefined symbolic parameters that are always passed as environment variables when you build output for z/OS® environments, see Predefined symbolic parameters that are set automatically. For a list of substitution variables defined within EGL build scripts, see Predefined symbolic parameters that can be set by the user.
  4. Save the member.

Examples of modifying EGL build scripts

The following examples show common modifications that you can make to EGL build scripts.

Modifying location of build components used by EGL build scripts

It is likely that the PDS naming conventions for the compiler, linkage editor, and database libraries are not the same as those used in the EGL build scripts. To change the default values, you must modify the VARS statement in the EGL build scripts. The following example shows the VARS statement for the default CICS® and COBOL compiler libraries:

//DEFAULTS VARS EZEPID=USER,
//              COBCICS=SYS1.SCEECICS,
//              COBCOMP=SYS1.IGY.SIGYCOMP,
//              COBLIB=SYS1.SCEELKED, 
...

To change the high level qualifier for these libraries to MYSYS, you would use the following syntax to change the VARS statement:

//DEFAULTS VARS EZEPID=USER,
//              COBCICS=MYSYS.SCEECICS,
//              COBCOMP=MYSYS.IGY.SIGYCOMP,
//              COBLIB=MYSYS.SCEELKED, 
...

Alternatively, you can leave the values of COBCICS, COBCOMP, and COBLIB set to the defaults in the build scripts and set the corresponding predefined symbolic parameters COBCICS, COBCOMP, and COBLIB in the EGL build descriptor parts to the values you need.

You can make similar updates for the EGL libraries (ELA substitution variable) and the database libraries (DSNEXIT and DSNLOAD substitution variables) either in the build scripts or by setting the corresponding predefined symbolic parameters in the EGL build descriptor parts.

Modifying EGL build scripts to save generated COBOL source

By default, the FDABCL, FDABPTCL, FDABTCL, FDACL, FDAPCL, FDAPTCL, and FDATCL build scripts do not save the generated source code on the build server. If you want to save the source code, you can uncomment statements in the UPLOAD step of these build scripts to cause the COBOL source to be saved in the user EZESRC data set. For example, consider the following statements in the FDACL build script :
//*UPLOAD EXEC PGM=IEFBR14 
//*EZESRC   DD  DSN=&EZEPID..&SYSTEM..EZESRC,DISP=SHR,CCUEXT=CBL
Uncomment the statements as follows:
//UPLOAD EXEC PGM=IEFBR14
//EZESRC   DD  DSN=&EZEPID..&SYSTEM..EZESRC,DISP=SHR,CCUEXT=CBL

Options required in EGL build scripts

In EGL build scripts, certain preparation options are required if you are using DB2® UDB, the CICS® translator, or the COBOL compiler for z/OS®.

Required options for DB2® precompiler

The following options are required for DB2® usage and are included in the FDAPCL and FDAPTCL build scripts:
  • HOST(COB2)
  • APOSTSQL
  • QUOTE

Required options for CICS® translator

The following options are required for CICS® usage and are included in the FDAPTCL and FDATCL build scripts:
  • COBOL2
  • NOSEQ
  • QUOTE
  • SP

The DBCS option is required for the CICS® translator when DBCHAR or MBCHAR variables or literals are used. The build scripts automatically include this option based on the setting of the predefined symbolic parameter EZEDBCS, which in turn is set based on the use of DBCHAR or MBCHAR

Required options for COBOL compiler for z/OS®

The following options are required for the z/OS® COBOL compiler and are included in the FDABCL, FDABPTCL, FDABTCL, FDACL, FDAPCL, FDAPTCL, and FDATCL build scripts:
  • LIB
  • NODYNAM (as further described later)
  • NUMPROC(NOPFD)
  • NOSEQ
  • QUOTE
  • RENT
  • TRUNC(BIN)

Also, the DBCS option is required for the COBOL compiler when DBCHAR or MBCHAR variables or literals are used. The build scripts automatically include this option based on the setting of the predefined symbolic parameter EZEDBCS, which in turn is set based on the use of DBCHAR or MBCHAR.

The NODYNAM compiler option enables static linking of the IBM® Rational® COBOL Runtime for zSeries® stub program with the generated COBOL program. Calls to other programs can be dynamic depending on whether the COBOL call is generated as a CALL IDENTIFIER or CALL LITERAL:
  • CALL IDENTIFIER is always a dynamic call. EGL generates this type of call for a call or transfer to program statement when you use the default linkage in a non-CICS environment. EGL also uses CALL IDENTIFIER for calls to DataTable programs and FormGroup print services programs. This usage lets you to generate Data Tables and FormGroups containing print forms independently of the programs that use them.
  • CALL LITERAL is either a dynamic or static call based on the compiler option. EGL generates this type of call for a call or transfer to program statement when you request static linkage. EGL also generates this type of call for calls to IBM® Rational® COBOL Runtime for zSeries® modules. The following IBM® Rational® COBOL Runtime for zSeries® modules are statically linked:
    • A few modules that are used frequently
    • A stub module that dynamically links to the major runtime functions

    EGL requires the NODYNAM compiler option so that all CALL LITERAL statements are treated as static calls.

Compiler options controlled by build descriptor options

The following COBOL compiler options are included in the build scripts. You can change their values by setting build descriptor options:
  • The ARITH compiler option specifies the size of numeric fields. You can control the setting for the ARITH compiler option by setting the maxNumericDigits build descriptor option to 31 for ARITH(EXTEND), or to 18 for ARITH (COMPAT). EXTEND increases the maximum number of digits for numeric items from 18 to 31 and also affects how intermediate results are computed. The default for the build descriptor option is 31.
  • The DATA compiler option specifies the whether data areas are acquired above or below the 16 MB boundary. You can control the setting for the DATA compiler option by setting the data build descriptor option to 24 for DATA(24), or to 31 for DATA(31). The default for the build descriptor option is 31.

Other COBOL compiler options in build scripts for z/OS®

The following compiler option is included in the build scripts, and you can remove the option:
  • The OPTIMIZE compiler option provides faster runtime performance, but can significantly increase the compile time. Consider using the NOOPTIMIZE option during testing and the OPTIMIZE option when moving the program to production.

COBOL compiler options not found in build scripts for z/OS®

The following compiler options are not included in the build scripts, but you might find them to be useful:
  • Listing Options. You can set the COBLISTPARMS predefined symbolic parameter to specify the combination of LIST, MAP, and OFFSET that you require. The build scripts default COBLISTPARMS to NOLIST.
    • LIST

      Produces an assembler language expansion of the COBOL source code.

    • MAP

      Produces a listing of information from the COBOL DATA DIVISION, including a DATA DIVISION map, global tables, literal pools, nested program structure map, and program attributes.

    • OFFSET

      Produces a cross-reference listing of the hexadecimal offsets in the module and the corresponding COBOL statement number. This is recommended to help you while you are debugging your program in the runtime environment.

  • SSRANGE

    Provides runtime subscript checking. NOSSRANGE eliminates runtime subscript checking. Because using NOSSRANGE can result in better performance, specify NOSSRANGE when you move the program to production.

  • TEST

    Produces object code that enables Debug Tool to perform batch and interactive debugging in your runtime environment.

For details on COBOL compiler options, refer to your compiler documentation.

COBOL compiler options that are not supported

The COBOL compiler option NAME is not supported.