Question

The compiler cobc accepts the options described in this section. The compiler arguments follow the general syntax cobc options file [file …]. A complete list of options can be displayed by using the option --help.

2.1.1 Help options

The following switches display information about the compiler:

--help, -h

Display help screen (see Compiler cobc options). No further actions will be taken.

--version, -V

Display compiler version, author package date and executable build date. No further actions will be taken.

-dumpversion

Display internal compiler version (plain string of numbers). No further actions will be taken.

--info

Display build information along with the default and current compiler configurations. No further actions will be taken except for further display options.

--verbose, -v

Verbosely display the programs invoked during compilation and additional diagnostics. Use multiple times to increase the verbosity.

--list-reserved

Display reserved words (see Reserved Words). A Yes/No output shows if the word is supported ¹, context sensitive and its aliases. The given options for reserved words specified for example by option -std=dialect will be taken into account. No further actions will be taken except for further display options.

--list-intrinsics

Display intrinsic functions (see Intrinsic Functions). A Y/N field shows if the function is implemented. No further actions will be taken except for further display options.

--list-system

Display system routines (see System routines). No further actions will be taken except for further display options.

--list-mnemonics

Display mnemonic names (see System names). No further actions will be taken except for further display options.

--list-exceptions

Display exception names (see Exception names). No further actions will be taken except for further display options.

2.1.2 Build target

The compiler cobc treats files like *.cob, *.cbl as COBOL source code, *.c as C source code, *.o as object code, *.i as preprocessed code and *.so as dynamic modules and knows how to handle such files in the generation, compilation, and linking steps.

The special input name - takes input from stdin which is assumed to be COBOL source, and uses a default output name of a.out (or a.so/c/o/i, selected as appropriate) for the build type.

By default, the compiler builds a dynamically loadable module.

The following options specify the target type produced by the compiler:

-E

Preprocess only: compiler directives are executed, comment lines are removed and COPY statements are expanded. The output is saved in file *.i.

-C

Translation only. COBOL source files are translated into C files. The output is saved in file *.c.

-S

Compile only. Translated C files are compiled by the C compiler to assembler code. The output is saved in file *.s.

-c

Compile and assemble. This is equivalent to cc -c. The output is saved in file *.o.

-m

Compile, assemble, and build a dynamically loadable module (i.e., a shared library). The output is saved in file *.so. ² This is the default behaviour.

-b

Compile, assemble, and combine all input files into a single dynamically loadable module. Unless -o is also used, the output is saved using the first filename as *.so.

-x

Include the main function in the output, creating an executable image. The main entry point being the first program in the file.

This option takes effect at the translation stage. If you give this option with -C, you will see the main function at the end of the generated C file.

-j, -job, -j=args, -job=args

Run job after compilation. Either from executable with -x, or with cobcrun when compiling a module. Optional arguments args, if given, are passed to the program or module command line.

-I directory

Add directory to copy/include search path.

-L directory

Add directory to library search path.

-l lib

Link the library lib.

-D define

Pass define to the COBOL compiler.

-o file

Place the output into file.

2.1.3 Source format

GnuCOBOL supports fixed, free, Micro Focus’ Variable, X/Open Free-form, ICOBOL xCard and Free-form, ACUCOBOL-GT Terminal, and COBOLX source formats. The default format is the fixed format. This can be overridden either by the >>SOURCE [FORMAT] [IS] {FIXED|FREE|COBOL85|VARIABLE|XOPEN|XCARD|CRT|TERMINAL|COBOLX} directive, or by one of the following options:

-free, -F, -fformat=free

Free format. The program-text area starts in column 1 and continues till the end of line (effectively 255 characters in GnuCOBOL).

-fixed, -fformat=fixed

Fixed format. Source code is divided into: columns 1-6, the sequence number area; column 7, the indicator area; columns 8-72, the program-text area; and columns 72-80 as the reference area.³

-fformat=cobol85

Fixed format with enforcements on the use of Area A.

-fformat=variable

Micro Focus’ Variable format. Identical to the fixed format above except for the program-text area which extends up to column 250 instead of 72.

-fformat=xopen

X/Open Free-form format. The program-text area may start in column 1 unless an indicator is present, and lines may contain up to 80 characters. Indicator for debugging lines is D instead of D or d.

-fformat=xcard

ICOBOL xCard format. Variable format with right margin set at column 255 instead of 250.

-fformat=crt

ICOBOL Free-form format (CRT). Similar to the X/Open format above, with lines containing up to 320 characters and single-character debugging line indicators (D or d).

-fformat=terminal

ACUCOBOL-GT Terminal format. Similar to the CRT format above, with indicator for debugging lines being \D instead of D or d. This format is mostly compatible with VAX COBOL terminal source format.

-fformat=cobolx

COBOLX format. This format is similar to the CRT format above, except that the indicator area is always present in column 1; the program-text area starts in column 2 and extends up to the end of the record. Lines may contain up to 255 characters.

Note that with source formats XOPEN, CRT, TERMINAL, and COBOLX, missing spaces are not inserted within continued alphanumeric literals that are truncated before the right margin.

Area A denotes the source code that spans between margin A and margin B, and Area B spans from the latter to the end of the record. Area A enforcement checks the contents of Area A, and reports any item that does not belong to the correct Area: this feature helps in developping COBOL programs that are portable to actual mainframe environments.

In general, division, section, and paragraph names must start in Area A. In the DATA DIVISION, level numbers 01 and 77, must also start in Area A. In the PROCEDURE DIVISIONs, statements and separator periods must fit within Area B. Every source format listed above may be subject to Area A enforcement, except FIXED and FREE.

Note that Area A enforcement enables recovery from missing periods between paragraphs and sections.

2.1.4 Warning options

Warnings are diagnostic messages that report constructions that are not inherently erroneous but that are risky or suggest there may have been an error.

The following options do not enable specific warnings but control the kinds of diagnostics produced by cobc.

-fsyntax-only

Check Check the code for syntax errors, but don’t do anything beyond that.

-fmax-errors=n

Limits the maximum number of error messages to n, at which point cobc bails out rather than attempting to continue processing the source code. If n is 0, there is no limit on the number of error messages produced. If -Wfatal-errors is also specified, then -Wfatal-errors takes precedence over this option.

-w

Inhibit all warning messages.

-Werror

Make all warnings into errors.

-Werror=warning

Make the specified warning into an error. The specifier for a warning is appended; for example -Werror=obsolete turns the warnings controlled by -Wobsolete into errors. This switch takes a negative form, to be used to negate -Werror for specific warnings; for example -Wno-error=obsolete makes -Wobsolete warnings not be errors, even when -Werror is in effect.

The warning message for each controllable warning includes the option that controls the warning. That option can then be used with -Werror= and -Wno-error= as described above. (Printing of the option in the warning message can be disabled using the -fno-diagnostics-show-option flag.)

Note that specifying -Werror=foo automatically implies -Wfoo. However, -Wno-error=foo does not imply anything.

-Wfatal-errors

This option causes the compiler to abort compilation on the first error occurred rather than trying to keep going and printing further error messages.

You can request many specific warnings with options beginning with ’-W’, for example -Wimplicit-define to request warnings on implicit declarations. Each of these specific warning options also has a negative form beginning ’-Wno’ to turn off warnings; for example, -Wno-implicit-define. This manual lists only one of the two forms, whichever is not the default.

Some options, such as -Wall and -Wextra, turn on other options, such as -Wtruncate. The combined effect of positive and negative forms is that more specific options have priority over less specific ones, independently of their position in the command-line. For options of the same specificity, the last one takes effect.

-Wall

Enable all the warnings about constructions that some users consider questionable, and that are easy to avoid (or modify to prevent the warning).
The list of warning flags turned on by this option is shown in --help.

-Wextra, -W

Enable every possible warning that is not dialect specific. This includes more information than -Wall would normally provide.
(This option used to be called -W. The older name is still supported, but the newer name is more descriptive.)

-Wwarning

Enable single warning warning.

-Wno-warning

Disable single warning warning.

-Warchaic

Warn if archaic features are used, such as continuation lines or the NEXT SENTENCE statement.

-Wcall-params

Warn if non-01/77-level items are used as arguments in a CALL statement. This is not set with -Wall.

-Wcolumn-overflow

Warn if text after column 72 in FIXED format. This is not set with -Wall.

-Wconstant

Warn inconsistent constant

-Wimplicit-define

Warn if implicitly defined data items are used.

-Wlinkage

Warn dangling LINKAGE items. This is not set with -Wall.

-Wobsolete

Warn if obsolete features are used.

-Wparentheses

Warn about any lack of parentheses around AND within OR.

-Wredefinition

Warn about incompatible redefinitions of data items.

-Wstrict-typing

Warn about type mismatch strictly.

-Wterminator

Warn about the lack of scope terminator END-XXX. This is not set with -Wall.

-Wtruncate

Warn on possible field truncation. This is not set with -Wall.

-Wunreachable

Warn if statements are unreachable. This is not set with -Wall.

-Wadditional

Enable warnings that don’t have an own warning flag.

2.1.5 Configuration options

The compiler uses many dialect specific options. These may be set via a defined dialect by -std=, a configuration file by -conf= or by using the single dialect flags directly.

See Compiler Configuration, and config/*.conf.

Note concerning the defined dialects: The GnuCOBOL compiler tries to limit both the feature-set and reserved words to the specified compiler when the "strict" dialects are used. COBOL sources compiled with these dialects are therefore likely to compile with the specified compiler and vice versa: sources that were compiled on the specified compiler should compile without any issues with GnuCOBOL.
With the "non-strict" dialects GnuCOBOL will activate the complete feature-set where it doesn’t directly conflict with the specified dialect, including reserved words. COBOL sources compiled with these dialects therefore may work only with GnuCOBOL. COBOL sources may need a change because of reserved words in GnuCOBOL, otherwise offending words word-1 and word-2 may be removed by -fno-reserved=word-1,word-1.

The dialects COBOL-85, X/Open COBOL, COBOL 2002 and COBOL 2014 are always "strict".

-std=dialect

Compiler uses the given dialect to determine certain compiler features and warnings.

-std=default

GnuCOBOL dialect, supporting many of the COBOL 2002 and COBOL 2014 features, many extensions found in other dialects and its own feature-set

-std=cobol85

COBOL-85 without any extensions other than the amendment Intrinsic Function Module (1989), source compiled with this dialect is likely to compile with most COBOL compilers

-std=xopen

X/Open COBOL (based on COBOL-85) without any vendor extensions, source compiled with this dialect is likely to compile with most COBOL compilers; will warn items that "should not be used in a conforming X/Open COBOL source program"

-std=cobol2002, -std=cobol2014

COBOL 2002 / COBOL 2014 without any vendor extensions, use -Warchaic and -Wobsolete if archaic/obsolete features should be flagged

-std=ibm-strict, -std=ibm

IBM compatible

-std=mvs-strict, -std=mvs

MVS compatible

-std=mf-strict, -std=mf

Micro Focus compatible

-std=bs2000-strict, -std=bs2000

BS2000 compatible

-std=acu-strict, -std=acu

ACUCOBOL-GT compatible

-std=rm-strict, -std=rm

RM/COBOL compatible

-std=realia-strict, -std=realia

CA Realia II compatible

-std=gcos-strict, -std=gcos

GCOS compatible

-freserved-words=dialect

Compiler uses the given dialect to determine the reserved words.

-conf=<file>

User-defined dialect configuration.

You can override each single configuration entry by using compiler configuration options on the command line.

Examples:

-frelax-syntax-checks

-frenames-uncommon-levels=warning

-fnot-reserved=CHAIN,SCREEN

-ftab-width=4

See Compiler cobc options.

2.1.6 Listing options

-t=file

Generate and place the standard print listing into file.

-T=file

Generate and place a wide print listing into *file.

--tlines=lines

Specify lines per page in print listing, default = 55. Set to zero for no additional page breaks.

-ftsymbols

Generate symbol table in listing.

-fno-theader

Suppress all headers from listing while keeping page breaks.

-fno-tmessages

Suppress warning and error summary from listing.

-fno-tsource

Suppress actual source from listing (for example to only produce the cross-reference).

-P, -Pdirectory, -P=file

Generate and place a preprocessed listing (old format) into filename.lst, directory/filename.lst, file.

-Xref

-X

Generate cross reference in the listing.

Here is an example program listing with the options -t -ftsymbols:

GnuCOBOL 3.0.0   test.cbl                   Mon May 14 10:23:45 2018  Page 0001

LINE    PG/LN  A...B...........................................................

000001         IDENTIFICATION   DIVISION.
000002         PROGRAM-ID.      prog.
000003         ENVIRONMENT DIVISION.
000004         CONFIGURATION SECTION.
000005         DATA             DIVISION.
000006         WORKING-STORAGE  SECTION.
000007         COPY 'values.cpy'.
000001C        78  I   VALUE 20.
000002C        78  J   VALUE 5000.
000003C        78  M   VALUE 5.
000008         01  SETUP-REC.
000009             05  FL1       PIC X(04).
000010             05  FL2       PIC ZZZZZ.
000011             05  FL3       PIC 9(04).
000012             05  FL4       PIC 9(08) COMP.
000013             05  FL5       PIC 9(04) COMP-4.
000014             05  FL6       PIC Z,ZZZ.99.
000015             05  FL7       PIC S9(05) SIGN LEADING SEPARATE.
000016             05  FL8       PIC X(04).
000017             05  FL9 REDEFINES FL8 PIC 9(04).
000018             05  FLA.
000019                 10  FLB OCCURS I TIMES.
000020                     15  FLC PIC X(02).
000021                 10  FLD   PIC X(20).
000022             05  FLD1      PIC X(100).
000023             05  FLD2 OCCURS M TO J TIMES DEPENDING ON FL5.
000024                 10  FILLER PIC X(01).
000025             05  FLD3      PIC X(3).
000026             05  FLD4      PIC X(4).
000027         PROCEDURE        DIVISION.
000028             STOP RUN.

The first part of the listing lists the program text. If the program text is a COPY the line number reflects the COPY line number and is appended with a ’C’.

When the wide list option -T is specified, the SEQUENCE columns (for fixed-form reference-format) are included in the listing.

The second part of the listing file is the listing of the Symbol Table:

GnuCOBOL 3.0.0   test.cbl                   Mon May 14 10:23:45 2018  Page 0002

SIZE TYPE           LVL  NAME                           PICTURE

5204 GROUP          01   SETUP-REC
0004 ALPHANUMERIC   05     FL1                          X(04)
0005 ALPHANUMERIC   05     FL2                          ZZZZZ
0004 ALPHANUMERIC   05     FL3                          9(04)
0004 NUMERIC        05     FL4                          9(08) COMP
0002 NUMERIC        05     FL5                          9(04) COMP
0008 ALPHANUMERIC   05     FL6                          Z,ZZZ.99
0006 ALPHANUMERIC   05     FL7                          S9(05)
0004 ALPHANUMERIC   05     FL8                          X(04)
0004 ALPHANUMERIC-R 05     FL9                          9(04)
0060 ALPHANUMERIC   05     FLA
0040 ALPHANUMERIC   10       FLB                        OCCURS 20
0002 ALPHANUMERIC   15         FLC                      X(02)
0020 ALPHANUMERIC   10       FLD                        X(20)
0100 ALPHANUMERIC   05     FLD1                         X(100)
5000 ALPHANUMERIC   05     FLD2                         OCCURS 5 TO 5000
0001 ALPHANUMERIC   10       FILLER                     X(01)
0003 ALPHANUMERIC   05     FLD3                         X(3)
0004 ALPHANUMERIC   05     FLD4                         X(4)

If the symbol redefines another variable the TYPE is marked with ’R’. If the symbol is an array the OCCURS phrase is in the PICTURE field.

The last part of the listing file is the summary of warnings an error in the compilation group:

0 warnings in compilation group
2 errors in compilation group

2.1.7 Debug switches

-g

Produce C debugging information in the output.

--debug, -d

Enable all run-time error checks.

-fec=exception-name, -fno=ec=exception-name

Enable/disable specified exception checks, see Exception Names.

-fsource-location

Generate source location code (implied by --debug, -g and -fec); --debug implies -fec=ALL.

-fstack-check

Enable PERFORM stack checking (implied by --debug or -g).

-ftrace

Generate trace code (log executed procedures, if tracing is enabled).

-ftraceall

Generate trace code (log executed procedures and statements, if tracing is enabled).

-fdebugging-line

Enable debugging lines (D in indicator column; >>D directive).

-O

Enable optimization of code size and execution speed. See your C compiler documentation, for example man gcc for details.

-O2

Optimize even more.

-Os

Optimize for size. Optimizer will favour code size over execution speed.

-fnotrunc

Do not truncate binary fields according to PICTURE.

2.1.8 Miscellaneous

-ext <extension>

Add default file extension.

-fmfcomment

Treat lines with * or / in column 1 as comment (fixed-form reference-format only).

-acucomment

Treat | as an inline comment marker.

-fsign=ASCII

Numeric display sign ASCII (default on ASCII machines).

-fsign=EBCDIC

Numeric display sign EBCDIC (default on EBCDIC machines).

-fintrinsics=[ALL|intrinsic function name(,name,...)]

Allow use of all or specific intrinsic functions without FUNCTION keyword.

Note: defining this within your source with CONFIGURATION SECTION. REPOSITORY. is preferred.

-ffold-copy=LOWER

Fold COPY subject to lower case (default no transformation).

-ffold-copy=UPPER

Fold COPY subject to upper case (default no transformation).

-save-temps(=<dir>)

Save intermediate files (by default, in current directory).

-fimplicit-init

Do automatic initialization of the COBOL runtime system.