Monday, January 24, 2011

COBOL Compiler Options

Cobol Compiler Options

  COBOL COMPILATION


The VS COBOL II compiler prepares a VS COBOL II source program for execution by producing a machine-language object module. This object module contains the actual machine language which implements or carries out the instructions specified in the COBOL source program. (The object module produced by the compiler must be processed by the linkage editor before the program is actually ready for execution.)


A single invocation of the compiler can compile an individual COBOL source program or a sequence of two or more separate source programs. The object programs which result from compiling more than one source program at a time may be link-edited into a single load module or into two or more separate load modules.


The VS COBOL II compiler provides several additional services while compiling a program.
These include:


• producing a source listing
• tayloring the content of the source listing (i.e., to include a sorted cross-reference of data-names, a map of the DATA DIVISION, a listing of the machine-language instructions that were generated, etc.).
• setting literal delimiters
• selecting a reserved word list
• processing COPY, BASIS, and REPLACE statements
• offering options to control object code generation, object code execution, and the compilers use of virtual storage
• producing debugging information at run time
• providing user-exits


Compiler Options:
   • ADV:


This is a COBOL compiler option.
Format: ADV NOADV
Abbreviations: None
IBM-default: ADV
ADV, which conforms to the ANSI standard, requests that the compiler add 1 byte to the record length to account for the printer control character when WRITE with the ADVANCING option is used.


NOADV implies that the record length has already been adjusted to account for the printer control character.


• QUOTE/APOST:


This is a COBOL compiler option.
 Format: QUOTE APOST
Abbreviations: Q
IBM-default: QUOTE


QUOTE, which conforms to the ANSI standard, specifies that the double quotation mark (“) is to be the delimiter character for non-numeric literals.


APOST specifies that the single quote mark or apostrophe (‘) is to be the delimiter character for non-numeric literals.


• AWO:


This is a COBOL compiler option.
Format: AWO NOAWO
Abbreviations: NOAWO
IBM-default: None


AWO specifies that, for any file in the program which is physical sequential with blocked V-mode records, the APPLY WRITE-ONLY clause be in effect (even if this clause is not specified in the program).


• BUFSIZE:
This is a COBOL compiler option.
Format: BUFSIZE(nnnn)


(nnnK)
where nnnn is a decimal number no less than 256
nnnK is a decimal number in 1K (1024) increments


Abbreviations: BUF
IBM-default: 4096
BUFSIZE specifies the amount of main storage to be allocated to each compiler work file buffer.


Generally, a large buffer size will improve compiler performance; however, BUFSIZE cannot exceed the track capacity for the device being used nor can it exceed the maximum allowed by data management services.
If the SIZE option is specified along with BUFSIZE, the amount of storage allocated to buffers is included in the amount of storage available for compilation as specified by the SIZE option.


• CMPR2:


This is a COBOL compiler option.


Format: CMPR2 NOCMPR2
Abbreviations: None
IBM-default: NOCMPR2


CMPR2 requests that generated object code be compatible with code generated by VS COBOL II Release 2.


NOCMPR2 requests that generated object code conform to the ANSI ‘85 standard (i.e., as implemented by VS COBOL II Release 3, which, in some instances, is incompatible with Release 2).


CMPR2 (which forces on the FLAGMIG option) can be used to assist in the migration of programs written under Release 2 to the ‘85 standard (i.e., to the Release 3 level).


See “Release 2 Compatibility And Migration” in the VS COBOL II Release 3 APPLICATION PROGRAMMING GUIDE for more information (including a list of elements that are CMPR2 sensitive and a description of their behavior under CMPR2 and NOCMPR2).


• COMPILE:


This is a COBOL compiler option.


Format: COMPILE NOCOMPILE NOCOMPILE(W)
(E)
(S)
Abbreviations: C NOC IBM-default: NOCOMPILE(S)


COMPILE forces a full compilation even when serious errors are detected. All diagnostics and object code will be generated (even though the object code should not be executed if serious errors are detected).


NOCOMPILE requests a syntax check only. Diagnostic messages (but no object code) are produced. When NOCOMPILE is specified, the following options have no effect (even though listed among the options in effect) because no object code is generated:


DECK FDUMP LIST
OBJECT OFFSET OPTIMIZE
SSRANGE TEST
NOCOMPILE(W), NOCOMPILE(E), and NOCOMPILE(S) -for level W
(warning), level E (error), and level S (severe error) diagnostics, respectively- request a conditional full compilation (i.e., diagnostics and object code), with object code generation (but not diagnostics) to stop when an error of the level specified (or higher) is encountered.


*** Compiler Options ***
There are 4 ways in which options may be passed to the compiler, listed below in order of precedence:
• Installation defaults that are fixed for your installation
• PROCESS (or CBL) statements in the source code
• JCL parameter
• Installation defaults that are not fixed

Fixed installation defaults may not be overridden. Installation defaults that are not fixed may be overridden by either PROCESS/CBL statements and/or by JCL parameters. If conflicting or mutually exclusive options are specified on both PROCESS/CBL statements and via a JCL parm, then the PROCESS/CBL statement takes precedence.
For a list of the default options in effect for your installation, run a compile without specifying any options and look at the list of compiler options in effect produced as part of the normal compiler printout. (For a list of the fixed defaults, see your manager or technical support staff.)


Note: The default value shown in the individual option descriptions is the IBM-supplied default shipped with the product (which may have been changed by your installation).


PROCESS statements must appear before the IDENTIFICATION DIVISION header and are formatted as shown below:


PROCESS option1,option2,....


IDENTIFICATION DIVISION.


CBL may be used as a synonym for PROCESS. PROCESS can start in columns 1 through 66 (or 8 through 66 if a sequence field is placed in columns 1 through 6). CBL can start in 1 through 70 (or 8 through 70 if a sequence field is used). One or more blanks must separate PROCESS/CBL from the first option; options must not contain embedded blanks and must be separated be a comma or a blank. Options may not be continued; however, multiple PROCESS/CBL statements may be used.


PROCESS/CBL statements may be inhibited by your installation. In this case, PROCESS/CBL statements in the source code will be flagged with a COBOL error message.


If conflicting versions of the same option (i.e., DECK and NODECK, NAME and NONAME, etc.) are specified at the same level of precedence (say, for example, via a JCL parameter), then the last one specified takes precedence. For example, specifying:


PARM=(DECK,NAME,NODECK) would result in NODECK being used as the active option.


The table below shows how mutually exclusive options (i.e., LIST and OFFSET, RENT and NORES, etc.). are handled when specified at the same level of precedence.


OPTION OPTION OPTION
SPECIFIED IGNORED FORCED ON*
---------------- --------------- -----------------
TEST FDUMP NOFDUMP
NOOBJECT OBJECT
NORES RES
OPTIMIZE NOOPTIMIZE
RENT NORES RES
DYNAM NORES RES
OFFSET LIST NOLIST
CMPR2 FLAGSTD NOFLAGSTD
FLAGSAA NOFLAGSAA
DBCS NODBCS
NOCMPR2 FLAGMIG NOFLAGMIG
WORD FLAGSTD NOFLAGSTD
FLAGSTD FLAGSAA NOFLAGSAA
FLAGMIG NOFLAGMIG
DBCS NODBCS
FLAGSAA FLAGMIG NOFLAGMIG
DBCS FLAGMIG NOFLAGMIG

*Unless in conflict with a fixed installation default option.
As an example, suppose FLAGSTD is set up as a non-fixed system default and that WORD is specified as an option via a JCL parm. Then the options in effect would be WORD and NOFLAGSTD (because WORD, at a higher level of precedence than the non-fixed default FLAGSTD, would force NOFLAGSTD on).


Shown below are the option settings required to conform to the 1985 ANSI COBOL Standards:


ADV
NOCMPR2
NODBCS
DYNAM
NOFASTSRT
NOFLAGMIG
NOFLAGSAA
FLAGSTD
LIB
NAME(ALIAS) or NAME(NOALIAS)
NONUMBER
NUMPROC(NOPFD) or NUMPROC(MIG) QUOTE RESIDENT NOSEQUENCE TRUNC(STD)
NOWORD
ZWB


The chart below shows what you can do with compiler options by grouping them into various activities and, within each activity, listing the specific task associated with each option.


Compiler Activity/Task Option
------------------------------------------------------ ---------
Control source listing and diagnostics:
• Produce system dump at compile time.............. DUMP
• Set severity level of diagnostics................ FLAG
• Identify Release 2/Release 3 incompatibilities... FLAGMIG
• Flag non-SAA compatible elements................. FLAGSAA
• Flag specified non-standard elements............. FLAGSTD
• Select output language........................... LANGUAGE
• Set number lines per page for compiler output.... LINECOUNT
• Produce list of generated code................... LIST
• Produce DATA DIVISION map........................ MAP
• Select line number processing.................... NUMBER
• Produce condensed PROCEDURE DIVISION listing..... OFFSET
• Specify sequence number processing............... SEQUENCE
• Produce source listing........................... SOURCE
• Select spacing within source listing............. SPACE
• Send diagnostics to SYSTERM dd statement......... TERMINAL
• Produce verb cross-reference..................... VBREF
• Produce sorted cross-reference................... XREF

Provide debugging information at run time:
• Produce formatted dump for abends................ FDUMP
• Setup for batch/interactive debugging............ TEST

Set literal delimiters:
• Set apostrophe as non-numeric delimiter.......... APOST
• Set quote mark as non-numeric delimiter.......... QUOTE
• Recognize shift codes for DBCS................... DBCS


Control object code output:
• Set diagnostic severity to stop compilation...... COMPILE
• Produce object code as 80-column card images..... DECK
• Generate link-edit NAME for each object module... NAME
• Output object code to SYSLIN dd statement........ OBJECT


Optimize object code:
• Specify APPLY WRITE-ONLY clause.................. AWO
• Allow sort product to perform I/O................ FASTSRT
• Request optimized object code.................... OPTIMIZE


Control object code generation and execution:
• Provide byte for printer control character....... ADV
• Generate Release 2 compatible code............... CMPR2
• Restrict dynamic storage to 16-meg line.......... DATA
• Specify dynamic CALL............................. DYNAM
• Set DISPLAY output ddname........................ OUTDD
• Specify invalid sign processing.................. NUMPROC
• Request reentrant object code.................... RENT
• Request Library Management Feature............... RESIDENT
• Check subscripts/indexes/ref. mod. expressions... SSRANGE
• Set binary field truncation...................... TRUNC
• Remove sign from DISPLAY fields for comparisons.. ZWB

Control compilers use of virtual storage:
• Set buffer size.................................. BUFSIZE
• Set amount of storage available for compilation.. SIZE

Miscellaneous:
• Select reserved word list........................ WORD
• Process COPY, BASIS, and REPLACE statements...... LIB
• Provide User-exits............................... EXIT

Some compiler options are specified with sub-parameters. These sub- parameters are specified in parentheses (with multiple sub-parameters, when applicable, generally separated by a comma) immediately following the option to which they apply (with no intervening or embedded blanks).
As examples:
DATA(24) SIZE(MAX) FLAG(W,E)
DATA:
This is a COBOL compiler option.
Format: DATA(24)
(31)
Abbreviations: None IBM-default: DATA(31)


For a program compiled with the RENT option which is to be executed under XA, the DATA option specifies whether dynamic storage (for data areas such as WORKING STORAGE, file buffers, etc.) is to be acquired from below the 16-meg line or from unrestricted storage.


DATA(24) specifies that dynamic storage areas are to be allocated from storage below the 16-meg line.


DATA(31) specifies that dynamic storage areas are to be allocated from unrestricted storage (i.e., either above or below the 16-meg line).


DATA(24) should be used for programs running under XA in 31-bit addressing mode that are passing data parameters to programs in 24-bit addressing mode. Otherwise, the called program may not be able to address the data being passed.




DBCS:


This is a COBOL compiler option.
Format: DBCS NODBCS
Abbreviations: None
IBM-default: NODBCS


DBCS instructs the compiler to recognize X’0E’ and X’0F’ as shift codes for the double byte portion of a non-numeric literal. (The double byte portion is syntax checked; the literal remains in the alphanumeric category.)


If either CMPR2 or FLAGSTD is specified, DBCS is ignored.
NODBCS conforms to the ANSI standard.

DECK:


This is a COBOL compiler option.
Format: DECK NODECK
Abbreviations: D NOD
IBM-default: NODECK


DECK requests that object code be produced in the form of 80- column card images and output to the SYSPUNCH dd statement.

DUMP:


This is a COBOL compiler option.
Format: DUMP NODUMP
Abbreviations: DU NODU
IBM-default: NODUMP


DUMP requests that a dump be produced whenever the compiler abnormally terminates. This option is normally used by IBM personnel in order to diagnose bugs in the compiler itself. When DUMP is specified, a SYSABEND, SYSUDUMP, or SYSMDUMP dd statement should be included in the compile JCL.


NODUMP provides a limited set of diagnostic information when the compiler abnormally terminates. This includes a description of the error, the compiler execution phase at the time of the abend, the line number of the COBOL statement being processed when the error occured, and the contents of the general purpose registers.

DYNAM:


This is a COBOL compiler option.
Format: DYNAM NODYNAM
Abbreviations: DYN NODYN
IBM-default: NODYNAM


DYNAM specifies that separately compiled programs invoked through the CAll literal statement (i.e., a CALL statement where the program to be called is specifed in the form of a literal) are to be loaded dynamically at run time.


NODYNAM implies that programs invoked through the CALL literal statement will be statically linked into the run-unit prior to execution.


EXIT:


This is a COBOL compiler option.
Format: EXIT(xparm) NOEXIT
Abbreviations: EX NOEX
IBM-default: NOEXIT
EXIT, depending upon the sub-parameters specified, instructs the compiler to:


• accept source input from a user-supplied exit module (rather than from the file defined with the SYSIN dd statement)
• accept copy input from a user-supplied exit module (rather than from the file defined with the SYSLIB dd statement)
• pass printer output to a user-supplied exit module (rather than to the file defined with the SYSPRINT dd statement)


The xparm sub-parameters (separated by a comma) must be specified by choosing one option from each of the 3 pairs of options shown below:


INEXIT(‘instring’,inmod) or NOINEXIT
LIBEXIT(‘libstring’,libmod) or NOLIBEXIT
PRTEXIT(‘prtstring’,prtmod) or NOPRTEXIT


where inmod, libmod, and prtmod are, respectively, the names of the user-supplied load modules to be used in place of SYSIN, SYSLIB, and SYSPRINT and ‘instring’, ‘libstring’, and ‘prtmod’ are optional
character strings of up to 64 characters (enclosed in apostrophes) that are to be passsed to the Corresponding user-supplied load module INEXIT, LIBEXIT, and PRTEXIT may be abbreviated as INEX, LIBEX, and PRTX, respectively.
EXIT may only be specified via a JCL parm or as an installation default (i.e., it may not be specified in a PROCESS/CBL statement).




FASTSRT:


This is a COBOL compiler option.


Format: FASTSRT NOFASTSRT
Abbreviations: FSRT NOFSRT
IBM-default: NOFASTSRT


FASTSRT specifies that, during an internal sort operation, IBM DFSORT (or an equivalent sort product) is to perform the I/O operations on sort input and output files (i.e., SORT USING and GIVING). This option may improve internal sort performance.


NOFASTSRT, which is the ANSI standard, specifies that COBOL is to perform the I/O operations on these files.

FDUMP:
This is a COBOL compiler option.


Format: FDUMP NOFDUMP
Abbreviations: FDU NOFDU
IBM-default: NOFDUMP


FDUMP requests that a formatted dump be produced at run time when execution ends in an abnormal termination.
When FDUMP is specified:
• the run time execution JCL should include a SYSDBOUT dd statement for FDUMP output
• if NUMBER is also specified, the sequence fields in columns 1 through 6 must be numeric
• the size of the object module is increased (because statement number and data description tables are included as part of the object code)


No formatted dump will be produced if the NOSTAE run time option is used or if any other program in the run-unit was compiled with TEST.


FLAG:


This is a COBOL compiler option.
Format: FLAG(a) NOFLAG


(a,b) where a and b are specified as I, W, E, S, or U Abbreviations: F NOF IBM-default: FLAG(I)
FLAG(a) directs the compiler to produce diagnostic messages for errors of severity level a or above at the end of the source listing.
FLAG(a,b) directs the compiler to produce diagnostic messages for errors of severity level a or above at the end of the source listing and to also place diagnostic messages for errors of severity level b and above directly in the source lising (i.e., directly after the statement in error). FLAG(a,b) has no meaning unless the SOURCE option is also specified.


NOFLAG directs the compiler to suppress error flagging.


The levels of severity for diagnostic messages are shown below:
I Informational (Return Code=0)
W Warning (Return Code=4)
E Error (Return Code=8)
S Severe (Return Code=12)
U Unrecoverable (Return Code=16)


FLAGMIG:


This is a COBOL compiler option.
Format: FLAGMIG NOFLAGMIG
Abbreviations: None
IBM-default: NOFLAGMIG


FLAGMIG requests that the compiler identify language elements that may be implemented differently in Release 2 than in Release 3 (which conforms to the ‘85 ANSI standard).


NOFLAGMIG conforms to the ANSI standard.


FLAGMIG is intended to be used, in conjunction with CMPR2 (which forces on FLAGMIG), to aid in the migration of programs written under VS COBOL II Release 2 to the Release 3 level (i.e., to the ‘85 standard). See CMPR2 for more information.


FLAGSAA:


This is a COBOL compiler option.
Format: FLAGSAA NOFLAGSAA
Abbreviations: None
IBM-default: NOFLAGSAA


FLAGSAA requests that the compiler identify (by flagging with a warning message) language elements that are not Systems Application Architecture (SAA) compatible. This will identify program elements that may restrict program portability across IBM systems.


NOFLAGSAA conforms to the ANSI standard.


The NOCMPR2 compiler option must be in effect in order to use FLAGSAA and the FLAGSTD option can not be used. If FLAGSTD and FLAGSAA are both specified along with NOCMPR2, FLAGSAA is ignored.


FLAGSTD:


This is a COBOL compiler option.
Format: FLAGSTD(s) NOFLAGSTD
(smm)
(smm,o)
(s,o)


where s is specified as M, I, or H in order to set the level or subset of Standard COBOL that is to be
considered as conforming mm is specified (as a single character or a combination of any two) as D, N, or S to set the optional modules to be included in the subset o is specified as O to indicate that obsolete language elements are to be flagged


Abbreviations: None
IBM-default: NOFLAGSTD


FLAGSTD is designed to provide information (via flagging) about the type of COBOL elements included in the source program. Based on the way in which the subparameters are coded, this can include flagging for non-conforming, non-standard, and/or obsolete language elements.


NOCMPR2 and the standard set of reserved words must be in effect in order to use FLAGSTD.


The sub-parameters are further described below:


For s: M specifies that language elements not from the minimum subset are to be flagged (i.e., as non-conforming standard)
I specifies that language elements not from the minimum or intermediate subset are to be flagged (i.e., as non-conforming standard)
H specifies that language elements offered as IBM extension are to be flagged (i.e., as non-conforming non-standard)


------------
For mm: D specifies that elements from Debug module level 1 are not flagged (i.e., as non- conforming standard)


N specifies that elements from Segmentation module level 1 are not flagged (i.e., as non-conforming standard)
S specifies that elements from Segmentation module level 2 are not flagged (i.e., as non-conforming standard) (Note: N is a subset of S.)
For o: O specifies that obsolete language elements are to be flagged (i.e., as obsolete)


Specified elements are flagged with an informational message that:


• Identifies the clause, statement, or header that contains the element as well as the source program line number and column.
• Identifies the subset or optional module to which the element belongs.
• Identifies the element as non-conforming standard, non- conforming non-standard, or obsolete. (A language element that is both obsolete and non-conforming is flagged as obsolete only.)


Flagging is suppressed whenever an error (diagnostic level E or higher) is detected.


*** JCL ***
Sample JCL required to invoke the compiler appears below, followed by a description of each dd statement required. This is followed by several examples (showing required JCL and selected options).


Sample compiler JCL:


//JS10 EXEC PGM=IGYCRCTL, Compiler Program Name
// PARM=(options) Optional Parms
//STEPLIB DD DSN=SYS1.COB2COMP,DISP=SHR PDS Containing Compiler
//SYSLIB DD DSN=cpylib,DISP=SHR Copy Member Library
//SYSPRINT DD SYSOUT=* Printed Output
//SYSTERM DD SYSOUT=* Diagnostic Messages
//SYSUT1 DD UNIT=SYSDA,SPACE=(subparms) Work File
//SYSUT2 DD UNIT=SYSDA,SPACE=(subparms) Work File
//SYSUT3 DD UNIT=SYSDA,SPACE=(subparms) Work File
//SYSUT4 DD UNIT=SYSDA,SPACE=(subparms) Work File
//SYSUT5 DD UNIT=SYSDA,SPACE=(subparms) Work File
//SYSUT6 DD UNIT=SYSDA,SPACE=(subparms) Work File
//SYSUT7 DD UNIT=SYSDA,SPACE=(subparms) Work File
//SYSLIN DD DSN=&&OBJMOD,DISP=(MOD,PASS), Object Module Output
// UNIT=SYSDA,SPACE=(subparms)
//SYSIN DD * Source Program Input
source program...
/*


Explanation of Compiler JCL:


PARM: JCL parameter used to pass options to the compiler. (See descriptions below.)


STEPLIB DD:
Partitioned data set containing the executable form of the compiler. (This may be installation dependent.)


SYSLIB DD:
Partitioned data set containing copy members. Required if programs to be compiled contain any COPY or BASIS statements.


SYSPRINT DD:
Provides a definition of the data set that receives printed output from the compiler. This includes the source listing, diagnostic messages, etc. Must have RECFM=F or FB. BLKSIZE can be any permissable value for the output device (up to 32760) that is a multiple of 133.


SYSTERM DD:
Provides definition of a second data set on which diagnostic messages are to be output. Only required when the TERMINAL compiler option is specified. Must have RECFM=F or FB. BLKSIZE can be any permissable value for the output device (up to 32670) that is a multiple of 81.


SYSUT1-SYSUT7:
Provides definitions of various compiler work files. These files must be on direct-access storage devices and must have RECFM=F or FB. BLKSIZE can be any permissable value for the output device (up to 32760) that is a multiple of 80.


SYSLIN DD:
Provides a definition of the output data set that is used for the object module. Must have RECFM=F or FB. BLKSIZE can be any permissable value for the output device (up to 32760) that is a multiple of 80.


SYSIN DD:
Provides a definition of the input data set that contains the source program(s) to be compiled. Must have RECFM=F or FB. BLKSIZE can be any permissable value for the input device (up to 32670) that is a multiple of 80.


Rather than specifying all of the required JCL shown above, you may prefer to invoke the VS COBOL II compiler by executing one of the IBM-supplied cataloged procedures for this purpose (i.e., COB2UC, COB2UCL, COB2CLG, etc.) or some other cataloged procedure provided by your systems programming or technical support staff. (Check with your manager or technical support staff for direction on which cataloged procedure to use.)


Examples of the JCL required to invoke the compiler (and selected options) are shown and described below:


//JS10 EXEC PGM=IGYCRCTL, Compiler Program Name
// PARM=(LIST,MAP,XREF) Optional Parms
//STEPLIB DD DSN=SYS1.COB2COMP,DISP=SHR PDS Containing Compiler
//SYSLIB DD DSN=cpylib,DISP=SHR Copy Member Library
//SYSPRINT DD SYSOUT=* Printed Output
//SYSTERM DD SYSOUT=* Diagnostic Messages
//SYSUT1 DD UNIT=SYSDA,SPACE=(subparms) Work File
//SYSUT2 DD UNIT=SYSDA,SPACE=(subparms) Work File
//SYSUT3 DD UNIT=SYSDA,SPACE=(subparms) Work File
//SYSUT4 DD UNIT=SYSDA,SPACE=(subparms) Work File
//SYSUT5 DD UNIT=SYSDA,SPACE=(subparms) Work File
//SYSUT6 DD UNIT=SYSDA,SPACE=(subparms) Work File
//SYSUT7 DD UNIT=SYSDA,SPACE=(subparms) Work File
//SYSLIN DD DSN=&&OBJMOD,DISP=(MOD,PASS), Object Module Output
// UNIT=SYSDA,SPACE=(subparms)
//SYSIN DD * Source Program Input
source program...
/*


The example above shows sample JCL required to execute the compiler with the following options:


LIST: to request an assembler-language listing of the generated object code
MAP: to request a DATA DIVISION map
XREF: to request a sorted cross-reference listing

//JS10 EXEC PROC=COB2UC, IBM-supplied proc
// PARM.COB=(OFFSET,OUTDD(DSPOUT)) Optional Parms
//COB.SYSIN DD * Source Program Input
source program...
/*
The example above shows sample JCL required to execute the compiler via the COB2UC JCL procedure supplied by IBM. In this case, the following options are specified:


OFFSET: to request a condensed PROCEDURE DIVISION listing
OUTDD: to request that execution time DISPLAY output use a ddname of DSPOUT


LANGUAGE:


This is a COBOL compiler option.
Format: LANGUAGE(xxxxxx)
Abbreviations: LANG(xx)
IBM-default: LANGUAGE(ENGLISH)


LANGUAGE specifies the language that will be used for compiler messages (i.e., for diagnostic messages, message summary headers, the compilation summary, and various headers and notations resulting from the use of compiler options like MAP, XREF, etc.).


The language sub-parameters that may be specified are shown below:


Sub-parameter Abbreviation Description
------------- ------------ ------------------------


ENGLISH EN Mixed case ENGLISH
JAPANESE JA,JP Japanese (using Japanese character set)
UENGLISH UE Upper-case English


Note: To use Japanese, the Japanese National Language Feature must be installed.


If the LANGUAGE option is changed using CBL or PROCESS statements, some initial text will be printed in the language that was in effect when compiler execution began.


LIB:


This is a COBOL compiler option.
Format: LIB NOLIB
Abbreviations: None
IBM-default: NOLIB


LIB, which conforms to the ANSI standard, instructs the compiler that it is to honor and process COPY, BASIS, and REPLACE statements.


If COPY or BASIS statements are to be processed, the compile JCL must include a dd statement for the library or libraries from which the compiler can extract the copied code (i.e., SYSLIB) as well as the SYSUT5 work file.


LINECOUNT:


This is a COBOL compiler option.


Format: LINECOUNT(nn) Abbreviations: LC IBM-default: LINECOUNT(60)
LINECOUNT specifies the number of lines to be printed on each page of the compilation listing.


The nn sub-parameter must be an integer between 10 and 255. This includes 3 lines which are used for titles. If LINECOUNT is specified as LINECOUNT(50), 47 lines of source code are printed on each page of the output listing.


LINECOUNT may also be specified as LINECOUNT(0) in order to suppress pagination (i.e., no page ejects are generated within the compilation listing).


LIST:


This is a COBOL compiler option.
Format: LIST NOLIST
Abbreviations: None
IBM-default: NOLIST


LIST requests that the compiler produce a listing of the generated machine language object code (which is produced by printing out the corresponding assembler-language source code).


LIST also provides information in the output listing about:


• Global tables
• Literal pools
• WORKING-STORAGE


If compiled with the NORENT option, the WORKING-STORAGE information includes the size of WORKING-STORAGE and its location within the object code.


LIST and OFFSET are mutually exclusive; if both are used, LIST is ignored.


The assembler-language source listing can be limited (i.e., turned on or off as required) through the use of *CONTROL LIST and *CONTROL NOLIST statements placed in the PROCEDURE DIVISION.


MAP:


This is a COBOL compiler option.
Format: MAP NOMAP
Abbreviations: None
IBM-default: NOMAP


MAP requests that the compiler produce a listing of the items defined in the DATA DIVISION (i.e., a DATA DIVISION “map”).


Other MAP output includes:


• Global tables
• Literal pools
• Nested program structure (and attributes)


If compiled with the NORENT option, MAP information includes the size of WORKING-STORAGE and its location within the object code.


MAP output can be limited (i.e., turned on or off as required) through the use of *CONTROL MAP and *CONTROL NOMAP statements placed in the DATA DIVISION.




NAME:


This is a COBOL compiler option.
Format: NAME NAME(ALIAS) NONAME
(NOALIAS)
Abbreviations: None
IBM-default: NONAME


NAME and NAME(NOALIAS) request that a link-edit NAME card be generated for each object module. NAME(ALIAS) requests that, in addition to a NAME card, a link-edit ALIAS card be generated for each ENTRY statement contained in the source program.




NUMBER:


This is a COBOL compiler option.
Format: NUMBER NONUMBER
Abbreviations: NUM NONUM
IBM-default: NONUMBER


NUMBER instructs the compiler to honor the line numbers embedded in columns 1 through 6 of each source statement. The compiler will check these columns to ensure that they contain numeric data and will sequence check them according to numeric collating sequence (as opposed to SEQUENCE, which checks them according to EBCDIC collating sequence). When a line number is found to be out of sequence, a number one greater than the number in the previous line will be assigned and sequence checking then continues with the newly assigned line number. These line numbers will also be referenced in error messages and in MAP, LIST, and XREF listings.


If NUMBER is specified and COPY statements are used, the line numbers in the source program should be coordinated with those in each referenced COPY member.


NONUMBER, which conforms to the ANSI standard, specifies that line numbers appearing in columns 1 through 6 (if any) are to be ignored. In this case, the compiler generates a line number for each line in the source program and uses these generated line numbers as references in error messages and in MAP, LIST, and XREF listings.




NUMPROC:


This is a COBOL compiler option.
Format: NUMPROC(PFD)
(NOPFD)
(MIG)
Abbreviations: None IBM-default: NUMPROC(NOPFD)


NUMPROC(NOPFD), which conforms to the ANSI standard, specifies that the generated code is to perform invalid sign processing during run time. This will result in increased run time and a larger object module.


NUMPROC(PFD) is a performance option which specifies that invalid sign processing is not to be done. It should be used only if the data to be processed agrees exactly with the following IBM system standards:


DATA FORMAT STANDARD SIGN FORMAT
----------------- ------------------------------------------
External decimal, High-order 4 bits of the sign byte contain unsigned X’F’
External decimal, High-order 4 bits of the sign byte contain signed overpunch X’C’ if the number is positive or 0; X’D’ if the number is negative
External decimal, Separate sign byte contains character ‘+’ separate sign if the number is positive or 0; ‘-‘ if the number is negative
Internal decimal, Low-order 4 bits of the low-order byte unsigned contain X’F’
Internal decimal, Low-order 4 bits of the low-order byte signed contain X’C’ if the number is positive or
0; X’D’ is the number is negative


NUMPROC(MIG), which conforms to the ANSI standard, is designed to aid in migrating from OS/VS COBOL to VS COBOL II. It results in the following sign processing:


• preferred signs are created only for the receiving field in a MOVE statement or an arithmetic operation
• no explicit sign correction is done during input operations
• some implicit sign correction may be done during data format conversion operations
• numeric comparisons are performed as a decimal (rather than a logical) comparison operation


OBJECT:


This is a COBOL compiler option.
Format: OBJECT NOOBJECT
Abbreviations: OBJ NOOBJ
IBM-default: OBJECT


OBJECT requests that the generated object code be routed to the SYSLIN dd statement.
NOOBJECT and TEST are mutually exclusive; NOOBJECT is ignored if TEST is specified.

OFFSET:


This is a COBOL compiler option.
Format: OFFSET NOOFFSET
Abbreviations: OFF NOOFF
IBM-default: NOOFFSET


OFFSET requests that the compiler produce a condensed PROCEDURE DIVISION listing. This condensed listing will contain line numbers, statement references, and the location (i.e., offset within the object code) of the first instruction generated for each statement. Other OFFSET output includes:


• Global tables
• Literal pools


If compiled with the NORENT option, OFFSET information includes the size of WORKING-STORAGE and its location within the object code.


OFFSET and LIST are mutually exclusive; if both are used, LIST is ignored.




OPTIMIZE:


This is a COBOL compiler option.
Format: OPTIMIZE NOOPTIMIZE
Abbreviations: OPT NOOPT
IBM-default: NOOPTIMIZE


OPTIMIZE specifies that the object code be generated for maximum efficiency. This should result in reduced run time and may also reduce the size of the object module. However, use of OPTIMIZE increases compile time.


OPTIMIZE is turned off whenever a severe error is detected.


OPTIMIZE and TEST are mutually exclusive; if TEST is specified, OPTIMIZE is ignored. Given these facts (and the additional compile time consumed by the OPTIMIZE option), it might be best to use NOOPTIMIZE while in initial program development or debugging mode.


Use of OPTIMIZE along with NUMPROC(PFD), AWO, and FASTSRT (when applicable) may result in significant run time savings.




OUTDD:


This is a COBOL compiler option.
Format: OUTDD(ddname) Abbreviations: OUT IBM-default: OUTDD(SYSOUT)
OUTDD may be used to specify a ddname other than SYSOUT for run time output produced by the DISPLAY verb.


RENT:


This is a COBOL compiler option.
Format: RENT NORENT
Abbreviations: None
IBM-default: NORENT


RENT specifies that the generated object code is to be reentrant.


NORENT specifies that the program be generated as a nonreentrant object module. (This option should not be used for CICS programs.)


Reentrant object code can be executed only in run units where all programs have been generated with the RESIDENT option. (RENT automatically forces on RESIDENT).


RENT must be specified if the program will be executed under XA in virtual storage addresses above the 16-meg line. In this case, the DATA option can be used to control whether dynamic data areas are allocated in unrestricted storage or from below the 16-meg line.


RENT automatically forces on RESIDENT and is not valid with NORESIDENT. DYNAM automatically forces on RESIDENT and is not valid with NORESIDENT.


Outlined below are the 5 valid combinations of DYNAM, RESIDENT, and RENT:


NORENT/NORES/NODYNAM
Nonreentrant code, COBOL library subroutines are statically called, CALL literal is a static call.


NORENT/RES/NODYNAM
Nonreentrant code, COBOL library subroutines are dynamically called, CALL literal is a static call.


NORENT/RES/DYNAM
Nonreentrant code, COBOL library subroutines and application subprograms are all dynamically called.


RENT/RES/NODYNAM
Reentrant code, COBOL library subroutines are dynamically called, CALL literal is a static call.

RENT/RES/DYNAM
Nonreentrant code, COBOL library subroutines and application subprograms are all dynamically called.




RESIDENT:


This is a COBOL compiler option.
Format: RESIDENT NORESIDENT
Abbreviations: RES NORES
IBM-default: NORESIDENT


RESIDENT, which conforms to the ANSI standard, specifies that the COBOL Library Management Feature be invoked. This causes most COBOL library subroutines to be loaded dynamically at run time rather than being statically link-edited into the run unit. (This allows for application programs to automatically pick up any fixes applied to the library subroutines without having to be link-edited again.) This option requires that the VS COBOL II subroutine library be included in the JOBLIB/STEPLIB concatenation at run time.


NORESIDENT, if used when compiling each COBOL program in the run unit, specifies that the load module contain all required VS COBOL II library subroutines needed for execution. In this case, the VS COBOL II subroutine library need not be included in the JOBLIB/STEPLIB concatenation.


The RESIDENT option is automatically in effect when the DYNAM option is specified or when the source program uses CALL identifier (i.e., a CALL statement where the program to be called is specified in the form of an identifier rather a literal).


Use of the VS COBOL II Library in conjunction with an OS/VS COBOL program compiled with the RESIDENT option may result in significant performance degradation at run time.


For more information on the interaction of RESIDENT and other compiler options, see the RENT option.

SEQUENCE:


This is a COBOL compiler option.
Format: SEQUECNE NOSEQUENCE
Abbreviations: SEQ NOSEQ
IBM-default: SEQUENCE


SEQUENCE instructs the compiler to ensure that the source program lines are in ascending EBCDIC collating sequence based on the information coded in columns 1 through 6. (Source program lines containing spaces in columns 1 through 6 are not checked.)


If NUMBER is also specified, the sequence checking is based on the numeric (rather than the EBCDIC) collating sequence.


If SEQUENCE is specified and COPY statements are used, the source program line numbers should be coordinated with the line numbers in each referenced COPY member.


NOSEQUENCE, which conforms to the ANSI standard, suppresses this sequence checking.

SIZE:


This is a COBOL compiler option.
Format: SIZE(nnnn)
(nnnK)
(MAX)


where nnnn is a decimal number no less than 655360,nnnK is a decimal number in 1K (1024) increments
with a minimum value of 640K
MAX requests the largest block of storage available in the user region Abbreviations: SZ IBM-default: SIZE(MAX)
SIZE specifies the amount of main storage to be made available for the compile process.


In an XA environment, SIZE(MAX) will cause the compiler to use all the storage in the user region above the 16-meg line. (Storage below the 16-meg line will be used for compiler modules that must be loaded below the line and for work file buffers.)


SIZE(MAX) should not be used if there is a need for the compiler to leave a specific amount of unused storage in the user region.

SOURCE:


This is a COBOL compiler option.
Format: SOURCE NOSOURCE
Abbreviations: S NOS
IBM-default: SOURCE


SOURCE requests that the compiler produce a listing of the input source program (including statements brought in by COPY or PROCESS statements).


SOURCE must be specified in order to get embedded diagnostics.


SOURCE output can be limited (i.e., turned on or off as required) through the use of *CONTROL SOURCE and *CONTROL NOSOURCE statements placed in the source program.


SPACE:


This is a COBOL compiler option.
Format: SPACE(1)
(2)
(3)


Abbreviations: None IBM-default: SPACE(1)


SPACE, which is meaningful only when SOURCE is specified, sets the (single, double, or triple) spacing to be used between the printed lines in the source code listing.


SSRANGE:


This is a COBOL compiler option.
Format: SSRANGE NOSSRANGE
Abbreviations: SSR NOSSR
IBM-default: NOSSRANGE


SSRANGE specifies that the generated code is to check to ensure that:


• the effective address generated for an index or subscript does not reference an area outside the region of the associated table
• the current effective length for a variable-length item (i.e., OCCURS DEPENDING ON) is no greater than its maximum defined length
• for reference modification expressions:
• the reference modification starting position is no less than 1 and no greater than the current length of the subject item
• the reference modification length value (if specified) is no less than 1
• the reference modification starting position and length value (if specified) do not reference an area that extends beyond the end of the subject item

If an “out of range” condition is detected, an error message will be written to write-to-programmer route code 11 (i.e., usually the SYSPRINT dd statement) and the program will be terminated. When running under CICS, these messages are written to a temporary storage queue.

The SSRANGE option can result in some performance degradation.


The NOSSRANGE run time option can be specified at run time in order to inhibit the range checking code generated by specifying SSRANGE as as a compile time option. In this way, the “dormant” range checking code can be activated at run time (i.e., to assist in resolving any unexpected errors) without having to recompile.


TERMINAL:


This is a COBOL compiler option.
Format: TERMINAL NOTERMINAL
Abbreviations: TERM NOTERM
IBM-default: NOTERMINAL


TERMINAL requests that a copy of each diagnostic message be sent to the SYSTERM data set.


NOTERMINAL suppresses this duplicate output.

TEST:


This is a COBOL compiler option.
Format: TEST NOTEST
Abbreviations: TES NOTES
IBM-default: NOTERMINAL


TEST requests that the compiler produce object code that can be executed with VS COBOL II batch or interactive debug.


The following options are forced on when TEST is specified:
NOFDUMP, NOOPTIMIZE, OBJECT, and RES.


If NUMBER is also specified, the sequence fields in columns 1 through 6 must be numeric.


If both the WITH DEBUGGING MODE clause and the USE FOR DEBUGGING statement are specified, then TEST is deactivated. (TEST will appear in the options list; however, a diagnostic message will be issued to indicate that, because of the conflict, TEST is not in effect.)


Using TEST can result in significant performance degradation at run time.

TRUNC:


This is a COBOL compiler option.


Format: TRUNC(STD)
(OPT)
(BIN)
Abbreviations: None IBM-default: TRUNC(STD)


TRUNC(STD), which conforms to the ANSI standard, specifies that, for USAGE BINARY receiving fields, the final result of an arithemetic expression or MOVE statement is truncated to the number of digits in the PICTURE clause of the BINARY receiving field.


TRUNC(OPT), which is provided as an IBM extension, is a performance option which causes the compiler to assume that data being moved to a USAGE BINARY receiving field conforms to the associated PICTURE clause. For this reason, the data will be truncated in what appears to the compiler to be the most optimal way at the time the code is being generated. This means that the truncation may be based on the number of digits in the PICTURE clause or it might be based on the actual physical size of the binary field in storage (i.e., as a halfword, fullword, or doubleword). If the data being moved has a value with a larger precision than that defined in the PICTURE clause, an unpredictable truncation of high order digits may occur.


Since the type of truncation generated for TRUNC(OPT) is unpredictable, TRUNC(OPT) should be used only if the data being moved to binary items is guaranteed not to have a value with a larger precision than that defined by the PICTURE clause for those binary items.


TRUNC(BIN), which is provided as an IBM extension, specifies that all binary items (no matter how many digits are shown in their PICTURE clause) are to be treated as a halfword, fullword, or doubleword. (The number of digits in the PICTURE clause is used only to determine the minimal binary field -i.e., halfword, fullword, doubleword- requried to store the item.) This means, once the physical size of the field is determined, that it is treated as a halfword, fullword, or doubleword both when processed as a sending field and when processed as a receiving field. In this case then, the only way to lose significant digits is to move a larger binary field to a smaller binary field (i.e., fullword to halfword, etc.).


TRUNC(BIN) should be used when there is a possibility of having more than 9 digits in a fullword or more than 4 digits in a halfword. (Specifying a PICTURE clause for a binary item with more than 4 digits forces it into a fullword. However, a halfword can contain some numbers of up to 5 decimal digits and a fullword can contain some numbers of up to 10 decimal digits.) TRUNC(BIN) should also be used when interfacing with other languages or products that have S/370 format binary data (i.e., PL/1, FORTRAN, S/370 assembler, CICS, DB2, etc.).


For the MOVE statement shown below:


MOVE 32700 TO BINFIELD1.


where BINFIELD1 is defined as:


BINFIELD1 PIC 9(4) COMP.


The result of compiling with the various binary truncation options is shown below:


Decimal Hex
------- ----
Sending Value 32700 7FBC
Received Value TRUNC(STD) 2700 0A8C
Received Value TRUNC(BIN) 32700 7FBC
Received Value TRUNC(OPT)* 32700 7FBC
or 2700 0A8C


*Depends upon how the compiler generates the truncation logic in this particular case.

VBREF:


This is a COBOL compiler option.
Format: VBREF NOVBREF
Abbreviations: None
IBM-default: NOVBREF


VBREF requests that the compiler produce a cross-reference showing all verb types used in the source program and the line numbers of the lines in which they appear. A summary showing how many times each verb is used is also produced.


WORD:


This is a COBOL compiler option.
Format: WORD(wwww) NOWORD
Abbreviations: WD NOWD
IBM-default: NOWORD

WORD instructs the compiler to use an alternative reserved word table for the current compilation.
The wwww sub-parameter specifies the (up to 4) characters that are to be appended to ‘IGYC’ to form the name of the reserved word table to be used. These 4 characters may not include the dollar sign ($) nor any of the character strings listed below:


ASM1 ASM2 DIAG DMAP DOPT FGEN INIT LIBO LIBR
LSTR LVL0 LVL1 LVL2 LVL3 LVL8 OPTM OSCN PGEN
RCTL RDPR RDSC RWT SAW SCAN SIMD XREF

NOWORD, which conforms to the ANSI standard, is a fixed default (i.e., cannot be changed by an application programmer via a JCL parm or PROCESS/CBL statement).


XREF:

This is a COBOL compiler option.
Format: XREF NOXREF
Abbreviations: X NOX
IBM-default: NOXREF


XREF requests that the compiler produce a sorted cross-reference showing EBCDIC data-names and EBCDIC procedure names (in alphanumeric order) and the line numbers of the source lines in which they are referenced. It also includes a listing of DBCS data-names and DBCS procedure names in the same order as they appear in the source program (unless the DBCSXREF installation option is selected) as well as a section listing all the program names that are referenced in the source program and the line number in which they are defined (with external program names identified as such).


In the data-name portion of the XREF listing, line numbers preceded by the letter ‘M’ indicate the data item is modified by a statement on that line. Elementary names within a group item referenced in a MOVE CORRESPONDING statement will also be included in the XREF listing.


If both XREF and SOURCE are specified, cross-reference information will also be embedded in the source listing itself (i.e., at the right hand end of the line to which it applies).


This information includes line number references as well as an indication that a name is undefined (UND), duplicately defined (DUP), implicitly defined (IMP), or, if a program name, externally defined (EXT).


XREF and NOSOURCE produce only the sorted cross-reference listing.


ZWB:

This is a COBOL compiler option.

Format: ZWB NOZWB
Abbreviations: None

IBM-default: ZWB

ZWB, which conforms to the ANSI standard, specifies that the compiler generate code to remove the sign from a signed external decimal field when comparing such a field to an alphanumeric field.

For the two fields defined below (with their hex values shown to the right):
Hex Value
---------


FIELDA PIC S9(3) VALUE +123. F1F2C3
FIELDB PIC X(3) VALUE ‘123’. F1F2F3


Compiling with ZWB would result in the two fields above being considered equal in value when compared; NOZWB would result in an unequal comparison.


No comments: