Defining translator options

You can specify the translator options that apply to all languages except where stated otherwise. Table 3 lists all the translator options, the program languages that apply, and any valid abbreviations.

If your installation uses the CICS-provided procedures in the distributed form, the default options are used. These are explicitly noted in the following option descriptions. You can tell which options get used by default at your installation by looking at the SYSPRINT translator listing output from the translate step (see The CICS-supplied translators). If you want an option that is not the default, you must specify it, as described in Using a CICS translator.

Translator options

APOST

(COBOL only)

APOST indicates that literals are delineated by the apostrophe or single quote (’). QUOTE is the alternative, which indicates double quotes. The same value must be specified for the translator step and the following compile step.

Start of changeThe CICS-supplied COBOL copybooks are generated with a single quote (APOST). If you are using any CICS-supplied copybooks in your application to interface to a CICS component, ensure the APOST option is in effect, not the QUOTE option.End of change

CBLCARD

(COBOL only) Abbreviation: CBL

CBLCARD specifies that the translator is to generate a CBL statement. This is the default--the alternative is NOCBLCARD.

CICS

CICS® specifies that the translator is to process EXEC CICS commands. It is the default specification in the translator. CICS is also an old name for the XOPTS keyword for specifying translator options, which means that you can specify the CICS option explicitly either by including it in your XOPTS list or by using it in place of XOPTS to name the list. The only way to indicate that there are no CICS commands is to use the XOPTS keyword without the option CICS. You must do this in a batch DL/I program using EXEC DLI commands. For example, to translate a batch DL/I program written in assembler language, specify:

*ASM XOPTS(DLI)

To translate a batch program written in COBOL, containing EXEC API commands, specify:

CBL XOPTS(EXCI)
Start of change

COBOL2

(COBOL only) Abbreviation: CO2

COBOL2 specifies that the translator is to generate temporary variables for use in the translated EXEC statements. In all other respects, the program is translated in the same manner as with the COBOL3 option. COBOL2 and COBOL3 are mutually exclusive. COBOL2 is the default for COBOL.

Note:
Start of change
If you specify COBOL2 and COBOL3 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
End of change

COBOL3

(COBOL only) Abbreviation: CO3

COBOL3 specifies that the translator is to translate programs that are Language Environment-conforming. COBOL3 and COBOL2 are mutually exclusive. Using the COBOL2 and COBOL3 translator options explains how the translator treats specific coding situations. Language Environment explains what Language Environment-conforming compilers are available.

CPP

(C++ only)CPP specifies that the translator is to translate C++ programs for compilation by a supported C++ compiler, such as IBM® C/C++ for MVS™.

CPSM

CPSM specifies that the translator is to process EXEC CPSM commands. The alternative is NOCPSM, which is the default.

DBCS

(COBOL only)

DBCS specifies that the source program may contain double-byte characters. It causes the translator to treat hexadecimal codes X'0E' and X'0F' as shift-out (SO) and shift-in (SI) codes, respectively, wherever they appear in the program.

For more detailed information about how to program in COBOL using DBCS, see the section on DBCS character strings in Enterprise COBOL for z/OS®: Language Reference.

DEBUG

(COBOL, C, C++, and PL/I only)

DEBUG instructs the translator to produce code that passes the line number through to CICS for use by the execution diagnostic facility (EDF). DEBUG is the default--NODEBUG is the alternative.

DLI

DLI specifies that the translator is to process EXEC DLI commands. You must specify it with the XOPTS option, that is, XOPTS(DLI).

EDF

EDF specifies that the execution diagnostic facility is to apply to the program. EDF is the default--the alternative is NOEDF.

EPILOG

(Assembler language only)

EPILOG specifies that the translator is to insert the macro DFHEIRET at the end of the program being translated. DFHEIRET returns control from the issuing program to the program which invoked it. If you want to use any of the options of the RETURN command, you should use RETURN and specify NOEPILOG.

EPILOG is the default--the alternative, NOEPILOG, prevents the translator inserting the macro DFHEIRET. (See the CICS Application Programming Reference manual for programming information about the DFHEIRET macro.)

EXCI

EXCI specifies that the translator is to process EXEC API commands for the External CICS Interface (EXCI). These commands must be used only in batch programs, and so the EXCI translator option is mutually exclusive to the CICS translator option, or any translator option that implies the CICS option. An error message is produced if both CICS and EXCI are specified, or EXCI and a translator option that implies CICS are specified.

The EXCI option is also mutually exclusive to the DLI option. EXEC API commands for the External CICS Interface cannot be coded in batch programs using EXEC DLI commands. An error message is produced if both EXCI and DLI translator commands are specified.

Start of changeEXCI cannot be used for COBOL programs compiled with the integrated translator, but can be used with a separate translator step.End of change

The EXCI translator option is specified by XOPTS, that is, XOPTS(EXCI).

FEPI

FEPI allows access to the FEPI API commands of the CICS Front End Programming Interface (FEPI). FEPI is only available if you have installed the CICS Front End Programming Interface. The alternative is NOFEPI. FEPI commands and design are described in the CICS Front End Programming Interface User’s Guide.

FLAG (I, W, E, or S)

(COBOL, C, C++, and PL/I only) Abbreviation: F

FLAG specifies the minimum severity of error in the translation which requires a message to be listed.

I
All messages.
W
(Default) All except information messages.
E
All except warning and information messages.
S
Only severe and unrecoverable error messages.

GDS

(C, C++, and assembler language only)

GDS specifies that the translator is to process CICS GDS (generalized data stream) commands. For programming information about these commands, see the CICS Application Programming Reference manual.

GRAPHIC

(PL/I only)

GRAPHIC specifies that the source program may contain double-byte characters. It causes the translator to treat hexadecimal codes X'0E' and X'0F' as shift-out (SO) and shift-in (SI) codes, respectively, wherever they appear in the program.

It also prevents the translator from generating parameter lists that contain the shift-out and shift-in values in hexadecimal form. Wherever these values would ordinarily appear, the translator expresses them in binary form, so that there are no unintended DBCS delimiters in the data stream that the compiler receives.

If the compiler you are using supports DBCS, you need to prevent unintended shift-out and shift-in codes, even if you are not using double-byte characters. You can do this by specifying the GRAPHIC option for the translator, so that it does not create them, or by specifying NOGRAPHIC on the compile step, so that the compiler does not interpret them as DBCS delimiters.

For more detailed information about how to program in PL/I using DBCS, see the relevant language reference manual.

Start of change

LEASM

(Assembler only)

LEASM instructs the translator to generate code for a Language Environment-conforming assembler MAIN program.

If the LEASM option is specified, the DFHEISTG, DFHEIENT, DFHEIRET and DFHEIEND macros expand differently to create a Language Environment-conforming assembler MAIN program, instead of the form of macro expansion used for assembler sub-routines in a CICS environment. This allows customer programs that have used NOPROLOG and NOEPILOG and coded their own DFHEIENT and other macros to take advantage of Language Environment® support without changing their program source. For example, all programs that require more than one code base register fall into this category because the translator does not support multiple code base registers.

For an example of an assembler program translated using the LEASM option see EXAMPLE Assembler language PROGRAM using LEASM.

End of change

LENGTH

(COBOL, Assembler and PL/I only)

LENGTH instructs the translator to generate a default length if the LENGTH option is omitted from a CICS command in the application program. The alternative is NOLENGTH.

LINECOUNT(n)

Abbreviation: LC

LINECOUNT specifies the number of lines to be included in each page of translator listing, including heading and blank lines. The value of "n" must be an integer in the range 1 through 255; if "n" is less than 5, only the heading and one line of listing are included on each page. The default is 60.

LINKAGE

(COBOL only) Abbreviation: LIN

LINKAGE requests the translator to modify the LINKAGE SECTION and PROCEDURE DIVISION statements in top-level programs according to the existing rules.

This means that the translator will insert a USING DFHEIBLK DFHCOMMAREA statement in the PROCEDURE DIVISION, if one does not already exist, and will ensure that the LINKAGE SECTION (creating one if necessary) contains definitions for DFHEIBLK and DFHCOMMAREA.

LINKAGE is the default--the alternative is NOLINKAGE.

The LINKAGE option has no effect on the translation of classes and methods.

MARGINS(m,n[,c])

(C, C++, and PL/I only) Abbreviation: MAR

MARGINS specifies the columns of each line or record of input that contain language or CICS statements. The translator does not process data that is outside these limits, though it does include it in the source listings.

The option can also specify the position of an American National Standard printer control character to format the listing produced when the SOURCE option is specified; otherwise, the input records are listed without any intervening blank lines. The margin parameters are:

m
Column number of left-hand margin.
n
Column number of right-hand margin. It must be greater than m.
Note:
When used as a C or C++ compiler option, the asterisk (*) is allowable for the second argument on the MARGIN option. For the translator, however, a numeric value between 1 and 100 inclusive must be specified. When the input data set has fixed-length records, the maximum value allowable for the right hand margin is 80. When the input data set has variable-length records, the maximum value allowable is 100.
c
Column number of the American National Standard printer control character. It must be outside the values specified for m and n. A zero value for c means no printer control character. If c is nonzero, only the following printer control characters can appear in the source:
(blank)
Skip 1 line before printing.
0
Skip 2 lines before printing.
-
Skip 3 lines before printing.
+
No skip before printing.
1
New page.

The default for C and C++ is MARGINS(1,72,0) for fixed-length records, and for variable-length records it is the same as the record length (1,record length,0). The default for PL/I is MARGINS(2,72,0) for fixed-length records, and MARGINS(10,100,0) for variable-length records.

NATLANG(EN or KA)

NATLANG specifies what language is to be used for the translator message output:

EN
(Default) English.
KA
Kanji.

(Take care not to confuse this option with the NATLANG API option.)

NOCBLCARD

(COBOL only)

NOCBLCARD specifies that the translator is not to generate a CBL statement. The compiler options that CICS requires are specified by the DFHYITVL procedure. You should ensure that RENT, NODYNAM, and LIB are specified..

NOCPSM

NOCPSM specifies that the translator is not to process EXEC CPSM commands. This is the default--the alternative is CPSM.

NODEBUG

(COBOL, C, C++, and PL/I only)

NODEBUG instructs the translator not to produce code that passes the line number through to CICS for use by the execution diagnostic facility (EDF).

NOEDF

NOEDF specifies that the execution diagnostic facility is not to apply to the program. There is no performance advantage in specifying NOEDF, but the option can be useful to prevent commands in well-debugged subprograms appearing on EDF displays.

NOEPILOG

(Assembler language only)

NOEPILOG instructs the translator not to insert the macro DFHEIRET at the end of the program being translated. DFHEIRET returns control from the issuing program to the program which invoked it. If you want to use any of the options of the EXEC CICS RETURN command, you should use EXEC CICS RETURN and specify NOEPILOG. NOEPILOG prevents the translator inserting the macro DFHEIRET. The alternative is EPILOG, which is the default. (See the CICS Application Programming Reference manual for programming information about the DFHEIRET macro.)

NOFEPI

NOFEPI disallows access to the FEPI API commands of the CICS Front End Programming Interface (FEPI). NOFEPI is the default--the alternative is FEPI.

NOLENGTH

(COBOL, Assembler and PL/I only)

NOLENGTH instructs the translator not to generate a default length if the LENGTH option is omitted from a CICS command in the application program. The default is LENGTH.

NOLINKAGE

(COBOL only)

NOLINKAGE requests the translator not to modify the LINKAGE SECTION and PROCEDURE DIVISION statements to supply missing DFHEIBLK and DFHCOMMAREA statements, or insert a definition of the EIB structure in the LINKAGE section..

This means that you can provide COBOL copybooks to define a COMMAREA and use the EXEC CICS ADDRESS command.

LINKAGE is the default.

NONUM

(COBOL only)

NONUM instructs the translator not to use the line numbers appearing in columns one through six of each line of the program as the line number in its diagnostic messages and cross-reference listing, but to generate its own line numbers. NONUM is the default--the alternative is NUM.

NOOPSEQUENCE

(C, C++, and PL/I only) Abbreviation: NOS

NOOPSEQUENCE specifies the position of the sequence field in the translator output records. The default for C and C++ is OPSEQUENCE(73,80) for fixed-length records and NOOPSEQUENCE for variable-length records. For PL/I, the default is OPSEQUENCE(73,80) for both types of records.

NOOPTIONS

Abbreviation: NOP

NOOPTIONS instructs the translator not to include a list of the options used during this translation in its output listing.

NOPROLOG

(Assembler language only)

NOPROLOG instructs the translator not to insert the macros DFHEISTG, DFHEIEND, and DFHEIENT into the program being assembled. These macros define local program storage and execute at program entry. (See the CICS Application Programming Reference manual for programming information about these "prolog" macros.)

NOSEQ

(COBOL only)

NOSEQ instructs the translator not to check the sequence field of the source statements, in columns 1-6. The alternative, SEQ, is the default. If SEQ is specified and a statement is not in sequence, it is flagged.

NOSEQUENCE

(C, C++, and PL/I only) Abbreviation: NSEQ

NOSEQUENCE specifies that statements in the translator input are not sequence numbered and that the translator must assign its own line numbers.

The default for fixed-length records is SEQUENCE(73,80). For variable-length records in C and C++, the default is NOSEQUENCE and for variable-length records in PL/I the default is SEQUENCE(1,8).

NOSOURCE

NOSOURCE instructs the translator not to include a listing of the translated source program in the translator listing.

NOSPIE

NOSPIE prevents the translator from trapping irrecoverable errors; instead, a dump is produced. You should use NOSPIE only when requested to do so by the IBM support center.

NOVBREF

(COBOL, C, C++ and PL/I only)

NOVBREF instructs the translator not to include a cross-reference of commands with line numbers in the translator listing. (NOVBREF used to be called NOXREF; for compatibility, NOXREF is still accepted.) NOVBREF is the default--the alternative is VBREF.

NUM

(COBOL only)

NUM instructs the translator to use the line numbers appearing in columns one through six of each line of the program as the line number in its diagnostic messages and cross-reference listing. The alternative is NONUM, which is the default.

OPMARGINS(m,n[,c])

(C, C++ and PL/I only) Abbreviation: OM

OPMARGINS specifies the translator output margins, that is, the margins of the input to the following compiler. Normally these are the same as the input margins for the translator. For a definition of input margins and the meaning of "m", "n", and "c", see MARGINS. The default for C and C++ is OPMARGINS(1,72,0) and for PL/I, the default is OPMARGINS(2,72,0).

The maximum "n" value allowable for the OPMARGINS option is 80. The output from the translator is always of a fixed-length record format.

If the OPMARGINS option is used to set the output from the translator to a certain format, it may be necessary to change the input margins for the compiler being used. If the OPMARGINS value is allowed to default this is not necessary.

OPSEQUENCE(m,n)

(C, C++, and PL/I only) Abbreviation: OS

OPSEQUENCE specifies the position of the sequence field in the translator output records. For the meaning of "m" and "n", see SEQUENCE. The default for C and C++ is OPSEQUENCE(73,80) for fixed-length records and NOOPSEQUENCE for variable-length records. For PL/I, the default is OPSEQUENCE(73,80) for both types of records.

OPTIONS

Abbreviation: OP

OPTIONS instructs the translator to include a list of the options used during this translation in its output listing.

PROLOG

(Assembler language only)

PROLOG instructs the translator to insert the macros DFHEISTG, DFHEIEND, and DFHEIENT into the program being assembled. These macros define local program storage and execute at program entry. (See the CICS Application Programming Reference manual for programming information about these "prolog" macros.) PROLOG is the default--the alternative is NOPROLOG.

QUOTE

(COBOL only) Abbreviation: Q

QUOTE indicates that literals are delineated by the double quotation mark ("). The same value must be specified for the translator step and the following compiler step.

Start of changeThe CICS-supplied COBOL copybooks are generated with a single quote (APOST). If you are using any CICS-supplied copybooks in your application to interface to a CICS component, ensure the APOST option is in effect, not the QUOTE option.End of change

SEQ

(COBOL only)

SEQ instructs the translator to check the sequence field of the source statements, in columns 1-6. SEQ is the default--the alternative is NOSEQ. If a statement is not in sequence, it is flagged.

SEQUENCE(m,n)

(C, C++, and PL/I only) Abbreviation: SEQ

SEQUENCE specifies that statements in the translator input are sequence numbered and the columns in each line or record that contain the sequence field. The translator uses this number as the line number in error messages and cross-reference listings. No attempt is made to sort the input lines or records into sequence. If no sequence field is specified, the translator assigns its own line numbers. The SEQUENCE parameters are:

m
Leftmost sequence number column.
n
Rightmost sequence number column.

The sequence number field must not exceed eight characters and must not overlap the source program (as specified in the MARGINS option).

The default for fixed-length records is SEQUENCE(73,80). For variable-length records in C and C++ the default is NOSEQUENCE and for variable-length records in PL/I the default is SEQUENCE(1,8).

SOURCE

Abbreviation: S

SOURCE instructs the translator to include a listing of the translated source program in the translator listing. SOURCE is the default--the alternative is NOSOURCE.

SP

SP must be specified for application programs that contain special (SP) CICS commands or they will be rejected at translate time. These commands are ACQUIRE, COLLECT, CREATE, DISABLE, DISCARD, ENABLE, EXTRACT, INQUIRE, PERFORM, RESYNC, and SET. They are generally used by system programmers. For programming information about these commands, see the CICS System Programming Reference manual .

SPACE(1 or 2 or 3)

(COBOL only)

SPACE indicates the type of spacing to be used in the output listing: SPACE(1) specifies single spacing, SPACE(2) double spacing, and SPACE(3) triple spacing. SPACE(3) is the default.

SPIE

SPIE specifies that the translator is to trap irrecoverable errors. SPIE is the default--the alternative is NOSPIE.

SYSEIB

SYSEIB indicates that the program is to use the system EIB instead of the application EIB. The SYSEIB option allows programs to execute CICS commands without updating the application EIB, making that aspect of execution transparent to the application. However, this option imposes restrictions on programs using it, and should be used only in special situations. A program translated with the SYSEIB option must:

VBREF

(COBOL, C, C++, and PL/I only)

VBREF specifies whether the translator is to include a cross-reference of commands with line numbers in the translator listing. (VBREF used to be called XREF, and is still accepted.)

Translator options table

Table 3. Translator options applicable to programming language
Translator option
COBOL
C
C++
PL/I
Assembler
APOST or QUOTE
X
CBLCARD or NOCBLCARD
X
CICS
X
X
X
X
X
Start of changeCOBOL2End of change Start of change
X
End of change
Start of changeEnd of change Start of changeEnd of change Start of changeEnd of change Start of changeEnd of change
COBOL3
X
CPP
X
CPSM or NOCPSM
X
X
X
X
X
DBCS
X
DEBUG or NODEBUG
X
X
X
X
DLI
X
X
X
X
X
EDF or NOEDF
X
X
X
X
X
EPILOG or NOEPILOG
X
EXCI
X
X
X
X
X
FEPI or NOFEPI
X
X
X
X
X
FLAG(I or W or E or S)
X
X
X
X
GDS
X
X
X
GRAPHIC
X
Start of changeLEASMEnd of change Start of changeEnd of change Start of changeEnd of change Start of changeEnd of change Start of changeEnd of change Start of change
X
End of change
LENGTH or NOLENGTH
X
X
X
LINECOUNT(n)
X
X
X
X
X
LINKAGE or NOLINKAGE
X
MARGINS(m,n)
X
X
X
NATLANG
X
X
X
X
X
NUM or NONUM
X
OPMARGINS(m,n[,c ])
X
X
X
OPSEQUENCE(m,n) or NOOPSEQUENCE
X
X
X
OPTIONS or NOOPTIONS
X
X
X
X
X
PROLOG or NOPROLOG
X
QUOTE or APOST
X
SEQ or NOSEQ
X
SEQUENCE(m,n) or NOSEQUENCE
X
X
X
SOURCE or NOSOURCE
X
X
X
SP
X
X
X
X
X
SPACE(1 or 2 or 3)
X
SPIE or NOSPIE
X
X
X
X
X
SYSEIB
X
X
X
X
X
VBREF or NOVBREF
X
X
X
X
[[ Contents Previous Page | Next Page Index ]]