Using the COBOL2 and COBOL3 translator options

For general information about translating your program and preparing it for execution, see Translation and compilation.

Start of changeThe following CICS translator options for COBOL are available in CICS® Transaction Server for z/OS®, Version 3 Release 1:

End of change

The ANSI85 translator option ceased to be available in CICS Transaction Server for z/OS, Version 2 Release 2.

Modules compiled in earlier CICS releases with the OOCOBOL translator option cannot execute in CICS Transaction Server for z/OS, Version 3 Release 1. The OOCOBOL translator option was used for the older SOM-based (System Object Manager-based) OO COBOL, and runtime support for this form of OO COBOL was withdrawn in z/OS V1.2. The newer Java-based OO COBOL, which is used in Enterprise COBOL, is not supported by the CICS translator.

The COBOL2 option is the default. It does not have the same effect on the translator as it did in CICS Transaction Server for z/OS, Version 2 Release 1 and earlier releases. COBOL2 instructs the translator to translate as COBOL3, but in addition to include declarations of temporary variables for use in EXEC CICS and EXEC DLI requests.

Choose the COBOL2 option if you are re-translating old programs which were written in such a way that they require the use of temporary variables. In particular, note that the use of temporary variables might circumvent errors that would normally occur when an argument value in a program is incorrectly defined. The COBOL2 option in CICS Transaction Server for z/OS, Version 2 Release 1 and earlier releases provided declarations of temporary variables. Because of this feature, incorrect definitions of argument values might be present, but not noticeable at runtime, in programs that were originally translated with the COBOL2 option in earlier releases of CICS Transaction Server. Translating these programs with the COBOL3 option can reveal these errors for the first time. To assist with migration to the newer releases of CICS, you may use the new COBOL2 option to continue to circumvent the errors in the programs, rather than correcting them.

If you are confident that your program do not need the translator's temporary variables, you may use COBOL3, which results in smaller working storage. The COBOL3 option includes all features of the older COBOL2 and ANSI85 translator options, except for declarations of temporary variables.

Start of changeThe CICS translator support in CICS Transaction Server for z/OS, Version 2 Release 2 and later versions and releases does not support the use of the CMPR2 compiler option previously available with old COBOL compilers. For information on upgrading these COBOL programs to the NOCMPR2 feature, see the Enterprise COBOL for z/OS: Compiler and Run-Time Migration Guide.End of change

Note:
Start of change
COBOL2 and COBOL3 are mutually exclusive. If you specify both options by different methods, the COBOL3 option is always used, regardless of where the two options have been specified. If this happens, the translator issues a warning message.
End of change

The following topics describe specific translator action that is taken when the COBOL3 option is used. Processing with the COBOL2 option is the same in all respects, except for declarations of temporary variables.

Literals intervening in blank lines

Start of changeBlank lines can appear anywhere in a COBOL source program. A blank line contains nothing but spaces between columns 7 and 72 inclusive.End of change

If blank lines occur within literals in a COBOL source program, the translator eliminates them from the translated output but includes them in the translated listing.

Lower case characters

Lower case characters can occur anywhere in any COBOL word, including user-defined names, system names, and reserved words.

The translator listing and output preserve the case of COBOL text as entered.

In addition, the translator accepts mixed case in:

The translator does not translate lower case text into upper case. Some names in COBOL text, for example file names and transaction IDs, must match with externally defined names. Such names must always be entered in the same case as the external definition.

If you specify the LINKAGE translator option, or allow it to default, a mixed-case version of the EIB structure (DFHEIBLC) is inserted into the LINKAGE SECTION.

Sequence numbers containing any character

In a COBOL source program, the sequence number field can contain any character in the computer’s character set. The sequence number fields need not be in any order and need not be unique.

REPLACE statement

COBOL programs can include the REPLACE statement, which allows the replacement of identified text by defined substitution text. The text to be replaced and inserted can be pseudo-text, an identifier, a literal, or a COBOL word. REPLACE statements are processed after COPY statements.

If you process your COBOL source statements with the CICS-supplied translator, the translator accepts REPLACE statements but does not translate text between pseudo-text delimiters, with the exception of CICS built-in functions (DFHRESP and DFHVALUE), which are translated wherever they occur. CICS commands should not be placed between pseudo-text delimiters.

If you use the integrated translator, the translator accepts REPLACE statements and does translate text between pseudo-text delimiters. CICS commands can be placed between pseudo-text delimiters.

Batch compilation

Separate COBOL programs can be compiled together as one input file. An END PROGRAM header statement terminates each program and is optional for the last program in the batch.

The translator accepts separate COBOL programs in a single input file, and interprets END PROGRAM header statements.

Translator options specified as parameters when invoking the translator are in effect for the whole batch, but can be overridden for a unit of compilation by options specified in the CBL or PROCESS card that initiates the unit.

The options for a unit of compilation are determined according to the following order of priority:

  1. Start of changeOptions fixed as installation non-user-modifiable options.End of change
  2. Options specified in the CBL or PROCESS card that initiates the unit.
  3. Options specified when the translator is invoked.
  4. Default options.

For more information about compilation, see Installing application programs.

If you are using batch compilation, you must take some additional action to ensure that compilation and linkage editing are successful, as follows:

For batch compilation you must vary the procedure described in the Installing application programs. The following is a suggested method:

  1. Split the supplied cataloged procedure DFHYITVL into two procedures; PROC1 containing the translate and compilation steps (TRN and COB), and PROC2 containing the linkage editor steps COPYLINK and LKED.
  2. In PROC1, add the NAME option to the parameters in the EXEC statement for the compiler, which then looks like this:
    //COB    EXEC PGM=IGYCRCTL,REGION=..,
    //       PARM='....,NAME,....',
  3. In PROC1, change the name and disposition of the compiler output data set &&LOADSET. At least remove the initial && from the data set name and change the disposition to CATLG. The SYSLIN statement should then read:
    //SYSLIN DD DSN=LOADSET,DISP=(NEW,CATLG),
    //          UNIT=&WORK,SPACE=(80,(250,100))
  4. Run PROC1.
    Figure 4. Compiler output before editing
               .................
               ....program a....
               .................
    NAME PROGA(R)
               .................
               .................
               ....program b....
               .................
               .................
    NAME PROGB(R)
               .................
               ....program c....
               .................
    NAME PROGC(R)
  5. Edit the compiler output in the data set LOADSET to add the INCLUDE and ORDER statements as shown in Figure 5. If you use large numbers of programs in batches, you should write a simple program or REXX EXEC to insert the ORDER and INCLUDE statements.
  6. In PROC2, add a DD statement for the library that includes the CICS stub. The standard name of this library is CICSTS31.CICS.SDFHLOAD. The INCLUDE statement for the stub refers to this library by the DD name. In Figure 5, it is assumed you have used the DD name SYSLIB ( or concatenated this library to SYSLIB). The suggested statement is:
    //SYSLIB DD DSN=CICSTS31.CICS.SDFHLOAD,
    //       DISP=SHR
  7. In PROC2, replace the SYSLIN concatenation with the single statement:
    //SYSLIN DD DSN=LOADSET,
    //       DISP=(OLD,DELETE)

    In this statement it is assumed that you have renamed the compiler output data set LOADSET.

  8. Run PROC2.
Figure 5. Linkage editor input
           ....program a....
           .................
INCLUDE SYSLIB(DFHELII)
ORDER DFHELII
NAME PROGA(R)
           .................
           .................
           ....program b....
           .................
           .................
INCLUDE SYSLIB(DFHELII)
ORDER DFHELII
NAME PROGB(R)
           .................
           ....program c....
           .................
INCLUDE SYSLIB(DFHELII)
ORDER DFHELII
NAME PROGC(R)
Note:
You are recommended to use the DFHELII stub, but DFHECI is still supplied, and can be used.

Nested programs

For an explanation of valid calls to nested programs and of the COMMON attribute of a nested program, see the Enterprise COBOL for z/OS Customization Guide.

Integrated CICS translator

When using the integrated CICS translator no action is necessary for nested programs that contain EXEC CICS commands. The compiler, in effect, declares DFHEIBLK and DFHCOMMAREA as global in the top-level program. This means that explicit coding of EIB and COMMAREA on the USING phrases on CALL and on the PROCEDURE DIVISION are not required, as described in Translator action on nested programs, for the separate translator.

Existing or modified programs will require appropriate modification for use with the CICS integrated translator. If modification is difficult the user should continue to use separate translation and compilation.

Translator action

The CICS translator treats top-level and nested programs differently.

The translator translates a top-level program (a program that is not contained by any other program) in the normal way, with one addition. The translator assigns the GLOBAL attribute for all translator-generated variables in the WORKING-STORAGE SECTION.

The translator translates nested or contained programs in a special way as follows:

The translator interprets that the input source starts with a top-level program if the first non-comment record is any of the following:

If the first record is none of these, the translator treats the input as part of the PROCEDURE DIVISION of a nested program. The first CBL or PROCESS card indicates the start of a top-level program and of a new unit of compilation. Any IDENTIFICATION DIVISION statements that are found before the first top-level program indicate the start of a new nested program.

The practical effect of these rules is that nested programs cannot be held in separate files and translated separately. A top-level program and all its directly and indirectly contained programs constitute a single unit of compilation and should be submitted together to the translator.

Comments in translator input

The translator treats comments that follow an END PROGRAM statement as belonging to the next program in the input source. Comments that precede an IDENTIFICATION DIVISION statement appear in the listing after the IDENTIFICATION DIVISION statement.

To avoid confusion always place comments:

and

Nesting: what the application programmer must do

  1. Submit a top-level containing program and all its directly and indirectly contained programs as a single unit of compilation.
  2. In each nested program that contains EXEC CICS commands, CICS built-in functions, or references to the EIB or COMMAREA, code DFHEIBLK and DFHCOMMAREA as the first two parameters of the PROCEDURE DIVISION header as follows:
    PROCEDURE DIVISION USING DFHEIBLK
            DFHCOMMAREA PARM1 PARM2 ...
  3. In every call to a nested program that contains EXEC CICS commands, CICS built-in functions, or references to the EIB or COMMAREA, code DFHEIBLK and DFHCOMMAREA as the first two parameters of the CALL statement as follows:
    CALL 'PROGA' USING DFHEIBLK
            DFHCOMMAREA PARM1 PARM2 ...
  4. For every call that forms part of the control hierarchy between the top-level program and a nested program that contains EXEC CICS commands, CICS built-in functions, or references to the EIB or COMMAREA, code DFHEIBLK and DFHCOMMAREA as the first two parameters of the CALL statement. In the PROCEDURE DIVISION in the called programs code DFHEIBLK and DFHCOMMAREA. This is necessary to allow addressability to the EIB and COMMAREA to be passed to programs not directly contained by the top-level program.
  5. If it is not necessary to insert DFHEIBLK and DFHCOMMAREA in the PROCEDURE DIVISION of a nested program for any of the reasons given above (2, 3, and 4), calls to that program should not include DFHEIBLK and COMMAREA in the parameter list of the CALL statement.

An example of a nested program

A unit of compilation (see Figure 6) consists of a top-level program W and three nested programs, X, Y, and Z, all directly contained by W.

Program W
During initialization and termination, calls Y and Z to do initial CICS processing and non-CICS file access. Calls X to do main processing.
Program X
Calls Z for non-CICS file access and Y for CICS processing.
Program Y
Issues CICS commands. Calls Z for non-CICS file access.
Program Z
Accesses files in batch mode.

Figure 6. Nested program example--nesting structure
 A top-level program W and three nested programs, X, Y, and Z, all directly contained by W, as described in the text.

Applying the rules:

Figure 7 illustrates the points in Nesting: what the application programmer must do.

Figure 7. Nested program example: coding
IDENTIFICATION DIVISION.
PROGRAM-ID. W.
.
.
PROCEDURE DIVISION.
.
.
    CALL Z.
.
.
    CALL Y USING DFHEIBLK COMMAREA.
.
.
    CALL X USING DFHEIBLK COMMAREA.
.
.
  IDENTIFICATION DIVISION.
  PROGRAM-ID. X.
.
.
  PROCEDURE DIVISION USING DFHEIBLK DFHCOMMAREA
.
.
    CALL Z.
.
.
    CALL Y USING DFHEIBLK COMMAREA.
.
.
  END PROGRAM X.
  IDENTIFICATION DIVISION.
  PROGRAM-ID. Y IS COMMON.
.
.
  PROCEDURE DIVISION USING DFHEIBLK DFHCOMMAREA.
.
.
    CALL Z.
.
.
    EXEC CICS...
.
.
  END PROGRAM Y.
  IDENTIFICATION DIVISION.
  PROGRAM-ID. Z IS COMMON.
.
.
  PROCEDURE DIVISION.
.
.
  END PROGRAM Z.
END PROGRAM W.  

Reference modification

Reference modification supports a method of referencing a substring of a character data item by specifying the starting (leftmost) position of the substring in the data item and, optionally, the length of the substring. The acceptable formats are:

data-name (leftmost-character-position:)
data-name (leftmost-character-position: length)

Data-name can be subscripted or qualified or both. Both leftmost-character-position and length can be arithmetic expressions. For more information about reference modification, qualification and subscripting, see the Enterprise COBOL for z/OS Language Reference, SC27-1408.

The translator accepts reference modification wherever the name of a character variable is permitted in a COBOL program or in an EXEC CICS command.

Note:
If a CICS command uses reference modification in defining a data value, it should include a LENGTH option to specify the data length, unless the NOLENGTH translator option is used. Otherwise the translator generates a COBOL call with a LENGTH register reference in the form:
LENGTH OF (reference modification)

This is rejected by the compiler.

Global variables

The GLOBAL variable storage class is supported. A variable defined with the GLOBAL variable storage class in a top-level program (see Translator action on nested programs) can be referred to in any of its nested programs, whether directly or indirectly contained.

The translator accepts the GLOBAL keyword.

Comma and semicolon as delimiters

A separator comma is a comma followed by a space. A separator semicolon is a semicolon followed by a space. A separator comma or a separator semicolon can be used as a separator wherever a space alone can be used.

The translator accepts the use in COBOL statements of a separator comma or a separator semicolon wherever a space can be used. For example, the translator accepts the statement:

IDENTIFICATION; DIVISION

The translator does not support the use of the separator comma and separator semicolon as delimiters in EXEC CICS commands. The only acceptable word delimiter in an EXEC CICS command continues to be a space.

Symbolic character definition

Symbolic characters can be defined in the SPECIAL-NAMES paragraph after the ALPHABET clause. A symbolic character is a program-defined word that represents a 1-character figurative constant.

The translator accepts the use of symbolic characters as specified in the standard.

Note:
In general, the compiler does not accept the use of figurative constants and symbolic characters as arguments in CALL statements. For this reason, do not use figurative constants or symbolic constants in EXEC CICS commands, which are converted into CALL statements by the translator. There is one exception to this restriction: a figurative constant is acceptable in an EXEC CICS command as an argument to pass a value if it is of the correct data type. For example, a numeric figurative constant can be used in the LENGTH option.
[[ Contents Previous Page | Next Page Index ]]