Translator options

(COBOL only)

APOST indicates that literals are delineated by the apostrophe or a quotation mark. QUOTE is the alternative option, which indicates double quotation marks.

This translator option determines the appropriate value for all delimiters in COBOL source code, including those in copybooks, CICS® statements and COBOL literals in the source. Although COBOL allows delimiters in COBOL source code to be apostrophes, quotation marks, or a mix of both in the same program, if the CICS stand-alone translator is used, then all beginning and ending delimiters in the COBOL program must match the CICS option specified. Literals continued across multiple lines must also start and end with the specified delimiter.

Note that the CICS-supplied COBOL copybooks have a single quotation mark. If you are using any CICS-supplied copybooks in your application to interface to a CICS component, ensure that you use the APOST option, not the QUOTE option, and code the delimiters in your program accordingly.

(COBOL only) Abbreviation: CBL

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

The COBOL compiler LIB option is not required for COBOL Version 5 and later. The compiler options that result from the CBLCARD translator option do not include the LIB option. When translating source to be processed by COBOL compilers earlier than Version 5, you must specify the LIB option without relying on CBLCARD.

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)

(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: 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 you specify both COBOL2 and COBOL3 , the translator issues a warning message.

(COBOL only) Abbreviation: CO3

COBOL3 specifies that the translator is to translate programs that are Language Environment-conforming. COBOL3 and COBOL2 options are mutually exclusive. For information about which Language Environment-conforming compilers are available, see Programming languages and Language Environment.

(C++ only)

CPP specifies that the translator is to translate C++ programs for compilation by a supported C++ compiler.

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

(COBOL only)

DBCS specifies that the source program might contain double-byte characters. The DBCS option 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.

(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 specifies that the translator is to process EXEC DLI commands. You must specify it with the XOPTS option, that is, XOPTS(DLI).

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

(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, use RETURN and specify NOEPILOG.

EPILOG is the default; the alternative NOEPILOG prevents the translator from inserting the macro DFHEIRET. (See DFHECALL macro for programming information about the DFHEIRET macro.)

EXCI specifies that the translator is to process EXEC API commands for the External CICS Interface (EXCI). EXCI API 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.

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

FEPI allows access to the FEPI API commands of the CICS Front End Programming Interface (FEPI). The alternative is NOFEPI . For more information about FEPI, see Developing with the FEPI API.

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

FLAG specifies the minimum severity of error in the translation that 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.

(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 CICS API commands.

(PL/I only)

GRAPHIC specifies that the source program might contain double-byte characters. The GRAPHIC option 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. Prevent unintended shift-out and shift-in codes 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.

(Assembler language 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 subroutines in a CICS environment. The LEASM option 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 are in 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 with LEASM.

(COBOL, assembler language 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.

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.

(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 inserts a USING DFHEIBLK DFHCOMMAREA statement in the PROCEDURE DIVISION, if one does not exist, and ensures that the LINKAGE SECTION (creating one if necessary) contains definitions for DFHEIBLK and DFHCOMMAREA.

LINKAGE is the default; the alternative is NOLINKAGE.

(C only)

MAIN specifies the program contains a main procedure and so the translator will include structures and declarations for the CICS API. This is the default.

(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 MARGINS 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 as follows:

m

Column number of left margin.

n

Column number of right 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 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 one line before printing.
0: Skip two lines before printing.
-: Skip three 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 specifies which language is to be used for the translator message output:

CS: Simplified Chinese.
EN: (Default) English.
KA: Kanji.

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

(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. Ensure that RENT and NODYNAM are specified.

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

(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 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.

(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, use EXEC CICS RETURN and specify NOEPILOG. NOEPILOG prevents the translator inserting the macro DFHEIRET. The alternative is EPILOG , which is the default.

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

(COBOL, assembler language 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.

(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.

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

LINKAGE is the default.

(C only)

NOMAIN specifies the program does not contain a main procedure and so the translator will not include structures for the CICS API. The DFHEIPTR pointer is declared as external. This allows multiple C programs to be link-edited together.

(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.

(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.

Abbreviation: NOP

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

(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.

(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.

(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 instructs the translator not to include a listing of the translated source program in the translator listing.

NOSPIE prevents the translator from trapping unrecoverable errors; instead, a dump is produced. Use NOSPIE only when requested to do so by the IBM® support center.

(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.

(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.

(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 margins 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 might be necessary to change the input margins for the compiler being used. If the OPMARGINS value is allowed to default, it is not necessary to change the input margins for the compiler being used.

(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.

Abbreviation: OP

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

(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.

(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. Although COBOL allows delimiters in COBOL source code to be apostrophes, quotation marks, or a mix of both in the same program, if the CICS stand-alone translator is used, then all beginning and ending delimiters in the COBOL program must match the CICS option specified. Literals continued across multiple lines must also start and end with the specified delimiter.

Note that the CICS-supplied COBOL copybooks have a single quotation mark. If you are using any CICS-supplied copybooks in your application to interface to a CICS component, ensure that you use the APOST option, not the QUOTE option, and code the delimiters in your program accordingly.

(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.

(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).

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 must be specified for application programs that contain special (SP) CICS commands or they are rejected at translate time. These commands are ACQUIRE, COLLECT, CREATE, DISABLE, DISCARD, ENABLE, EXTRACT, INQUIRE, PERFORM, RESYNC, and SET. Theses commands are used by system programmers. For programming information about these commands, see System commands.

(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 specifies that the translator is to trap unrecoverable errors. SPIE is the default; the alternative is NOSPIE.

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. Use this option only in special situations because it imposes restrictions on the programs using it. A program translated with the SYSEIB option must:

Execute in AMODE(31), because the system EIB is assumed to be located in TASKDATALOC(ANY) storage.
Obtain the address of the system EIB using the ADDRESS EIB command (if the program is translated with the SYSEIB option, this command automatically returns the address of the system EIB).
The use of the SYSEIB option implies the use of the NOHANDLE option on all CICS commands issued by the program. Commands can use the RESP option as required.

(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.)