The parameters of this option control which listings the compiler is to generate, their layout, and where they are to be output. Only one options listing is generated per compilation group. The other listings are created individually for each compilation unit.
Format
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
LISTING = *NONE
The compiler is to generate no listings.
LISTING = *STD
The default values of the following PARAMETERS structure are to be used.
LISTING = *PARAMETERS(...)
The following parameters determine which listings are to be generated, their layout, and the output destination to which they are to be directed.
OPTIONS = *NO / *YES
By default, the compiler generates a listing specifying the control statements that apply during compilation, the environment of the compilation process and some information for maintenance and diagnostic purposes.
SOURCE = *YES(...)
The compiler generates a source listing and a library listing.
COPY-EXPANSION = *NO
The COPY elements copied into the compilation unit will not be printed in the source listing. This setting is recommended for frequently occurring COPY elements, in order to save paper.
COPY-EXPANSION = *VISIBLE-COPIES
Only COPY elements containing no SUPPRESS entry will be printed in the source listing for the compilation unit. Each line of a COPY element is identified by a “C” in column 1.
COPY-EXPANSION = *ALL-COPIES
All COPY elements will be printed in the source listing for the compilation unit, including those that contain a SUPPRESS entry. Each line of a COPY element is identified by a “C” in column 1.
SUBSCHEMA-EXPANSION = *NO / *YES
If YES is specified, the SUB-SCHEMA SECTION will be listed and each line will be identified by a “D” in column 1.
This operand is not available in COBOL-BC.
INSERT-ERROR-MSG = *NO / *YES
If YES is specified, any (error) messages that occur during compilation are “merged” with the source listing for the compilation unit. The message line always appears immediately after the source line in which the construct responsible for triggering the message begins. Messages that cannot be allocated to a particular source line by the compiler are output after the last source line.
The operand also works if no error listing has been requested.
For merging to function correctly, the source listing for the compilation unit should not contain more than 65535 source lines (see for the for the compilation unit source listing in the section "Source listing for a compilation unit").
CROSS-REFERENCE = *YES(...)
If YES is specified, the address and length of the definitions contained in the line follow in the source listing on the right next to the source lines. In the case of definitions, there are cross-references to the users, including the usage type, and in the case of the users, references back to the definition.
The operand has no effect if the compilation unit comprises more than 65535 lines.
When using this operand, it is advisable to increase the line length (see the LAYOUT operand) and then to use a corresponding character set or wider paper to print out the listing (see 3-5).
In the case of lines that are not listed in the source listing, the additional specifications generated by the operand (see COPY-EXPANSION, SUBSCHEMA-EXPANSION and LISTING directive) are not included. References from listed lines to suppressed lines are retained.
STMT-ADDRESS = *NO / *FIRST
If FIRST is specified, for the first statement in a line the source listing contains, on the right next to the source lines from the Procedure Division, the address of the first machine instruction generated for this.
DIAGNOSTICS = *YES(...)
The compiler is to generate a diagnostic listing.
MINIMAL-WEIGHT = *NOTE / *WARNING / *ERROR / *SEVERE-ERROR / *FATAL-ERROR
The diagnostic listing will contain no messages with a weighting less than the specified value. The default value NOTE causes all (error) messages that occurred during the compilation to be listed.
IMPLICIT-SCOPE-END = *STD / *REPORTED
If REPORTED is specified, a remark message is added to the diagnostic listing each time a structured statement is ended by a period.
MARK-NEW-KEYWORDS = *NO / *YES
If YES is specified, keywords from the future standard will be marked in the diagnostic listing with a message with severity code I. A value of YES is only meaningful if *COBOL85 has been specified for ENABLE-KEYWORDS.
REPORT-2-DIGIT-YEAR = *ACCEPT-STMT / *NO
If *ACCEPT-STMT is specified, the compiler indicates that the year numbers are processed without century digits for every ACCEPT statement and for every variable accessed in the statement. MINIMAL-WEIGHT should be set to NOTE. If *NO is specified, these indications are suppressed.
NAME-INFORMATION = *NO / *YES(...)
If YES is specified, the compiler will generate a locator map or a locator map and cross-reference listing. The listing contains data, section and paragraph names.
SORTING-ORDER = *ALPHABETIC
The symbolic names are to be listed in ascending alphabetical order.
SORTING-ORDER = *BY-DEFINITION
The symbolic names are to be listed in the order in which they are defined in the compilation unit.
CROSS-REFERENCE = *NONE
No cross-reference listing will be generated.
CROSS-REFERENCE = *REFERENCED
Only the data and procedure names that are actually addressed in the program will be listed in the cross-reference listing.
CROSS-REFERENCE = *ALL
A cross-reference listing containing all data and procedure names will be generated.
SUPPRESS-GENERATION = *NO / *AT-SEVERE-ERROR
AT-SEVERE-ERROR can be specified to suppress the generation of the module if an error with a severity code >= 2 occurs during compilation.
LAYOUT = *STD
The layout of the generated listings is to correspond to the default settings of the PARAMETERS structure.
LAYOUT = *PARAMETERS(...)
The following parameters can be used to modify the layout of the generated listings.
LINES-PER-PAGE = 64 / <integer 20..128>
This parameter can be used to define the maximum number of lines to be printed per page. A page throw will be performed when this line number is reached.
LINE-SIZE = 132 / <integer 119..172>
This parameter defines the maximum number of characters to be printed per line.
OUTPUT = *SYSLST
This causes the generated listings to be written into the temporary system file SYSLST, from where they will automatically be output on the printer at end of task (i.e. after LOGOFF). The first requested listing is preceded by a title page (COMOPT listing) with details concerning the system environment and a list of all the COMOPT operands in effect at compilation.
OUTPUT = *STD-FILES
This setting causes each requested listing to be placed in a separate cataloged file. The cataloged files created in this way have the default names given in the right-hand column of the following table. program-name is derived from the PROGRAM-ID name and may, if necessary, be abbreviated to 16 characters.
Listing | File name |
control statement listing | OPTLST.COBOL.program-name |
source listing or library listing | SRCLST.COBOL.program-name |
diagnostic listing | ERRFIL.COBOL.program-name |
locator map listing / cross-reference listing | LOCLST.COBOL.program-name |
File names and file characteristics for these cataloged files are preset by default. However, the user can divert the output to other cataloged files. In order to do this, the desired characteristics must be defined in an ADD-FILE-LINK command before the compiler is called so that they can be linked with the respective file link name used by the compiler:
Listing | Link name |
control statement listing | OPTLINK |
source listing/library listing | SRCLINK |
address listing/cross-reference listing | LOCLINK |
diagnostic listing | ERRLINK |
To store the generated listings in the POSIX file system, you must assign them to the POSIX file system using S variables. The default names of these variables are:
Listing | Name of S variable |
control statement listing | SYSIOL-OPTLINK |
source listing/library listing | SYSIOL-SRCLINK |
locator map/cross-reference listing | SYSIOL-LOCLINK |
diagnostic listing | SYSIOL-ERRLINK |
OUTPUT = LIBRARY-ELEMENT(LIBRARY = <filename 1..54>)
The requested listings are output to the PLAM library specified by <filename>. Each listing occupies its own type R library element, which has the highest possible version number. The following standard names are assigned to these elements:
Listing | Element name |
control statement list | OPTLST.COBOL.program-name |
source listing/library listing | SRCLST.COBOL.program-name |
address listing/cross-reference listing | LOCLST.COBOL.program-name |
diagnostic listing | ERRLST.COBOL.program-name |
program-name is derived from the PROGRAM-ID name and truncated to 16 characters is required. If the truncation causes the program name to end in a ’-’ character, the ’-’ is replaced by a ’#’ character. After the compilation, there is a TFT entry for the link name LIBLINK, which is linked with the <filename> of the PLAM library.
Example 3-2
Writing listings to cataloged files
The compiler is to generate only a diagnostic (error) listing and save this in the cataloged file ERRORS.
/ADD-FILE-LINK ERRLINK,ERRORS ———————————————————————————————————— (1) /START-COBOL2000-COMPILER? ——————————————————————————————————————— (2) Entry in operand form: LISTING=PAR(OPTIONS=NO,SOURCE=NO) ———————————————————————————————— (3)
(1) | The ADD-FILE-LINK command assigns the cataloged file ERRORS to the default link name ERRLINK. |
(2) | The compiler is called in menu mode. |
(3) | The default setting (generation of options, source and diagnostic listings) is changed; the compiler is to generate only a diagnostic listing and output it by default to the cataloged file ERRORS. |
Example 3-3
Writing listings to a PLAM library
The compiler is to generate all listings and save them as elements in the PLAM library LISTLIB.
/START-COBOL2000-COMPILER? ————————————————————————————————————————(1) Entry in operand form: LISTING=PAR(NAME-INFORMATION=YES(CROSS-REFERENCE=ALL),- OUTPUT=*LIBRARY-ELEMENT(LIBRARY=LISTLIB)) —————————————————————————(2)
(1) (2) | The compiler is called in menu mode. The default setting (generation of options, source and diagnostic listings) is changed; the compiler is also to generate a locator map and cross-reference listing and save all listings in a PLAM library named LISTLIB. |
Example 3-4
Writing listings to the POSIX file system
The compiler is to generate a source listing and a diagnostic listing and store them in the POSIX file system.
/DECL-VAR SYSIOL-SRCLINK,INIT='*P(xpl.srclst)',SCOPE=*TASK————————— (1) /DECL-VAR SYSIOL-ERRLINK,INIT='*P(xpl.errlst)',SCOPE=*TASK————————— (1) /START-COBOL2000-COMPILER? ———————————————————————————————————————— (2)
(1) | The DECL-VARIABLE command assigns the desired name to the variable. Since the file name does not include a path specification, the file will be stored in the home directory. |
(2) | The compiler is called in SDF menu mode. |
Example 3-5
Writing a compressed listing for utilizing print pages
A compressed listing is to be generated to utilize the print pages as far as possible.
LISTING=*PAR(SOURCE=*YES(CROSS-REFERENCE=YES),- —————————————————— (1) LAYOUT=*PAR(LINES-PER-PAGE=60,LINE-SIZE=172)) *) ————— (1) /PRINT-FILE srclst.cobol.programmname,LOOP=98,CHAR-SET=R01 ———————— (2)
*) These specifications have been optimized for a page width of 32 cm and a page length of 22 cm.
(1) | Options used |
(2) | Command for printing out the listing file |