Appendix K: Compiler Options Reference
Overview
COBOL compiler options control how source code is interpreted, compiled, optimized, and linked. The two compilers used in this textbook -- IBM Enterprise COBOL for z/OS and GnuCOBOL -- have different option sets, though many serve equivalent purposes. This appendix provides a reference for the most commonly used options in both compilers, organized by functional category.
Part 1: IBM Enterprise COBOL for z/OS
IBM Enterprise COBOL options are specified in the JCL EXEC statement PARM field, in CBL/PROCESS statements at the top of the source program, or in installation-wide defaults set by the systems programmer. Options specified in the source override JCL options, which override installation defaults.
Specifying Options
In JCL:
//COBOL EXEC PGM=IGYCRCTL,
// PARM='MAP,LIST,SSRANGE,TEST(SEP)'
In source code:
CBL MAP,LIST,SSRANGE
IDENTIFICATION DIVISION.
Language Options
| Option | Default | Values | Description |
|---|---|---|---|
| ARITH(COMPAT/EXTEND) | COMPAT | COMPAT, EXTEND | Controls arithmetic precision. COMPAT limits intermediate results to 18 digits. EXTEND allows up to 31 digits. Use EXTEND for high-precision financial calculations. |
| CICS | NOCICS | CICS, NOCICS | Enables integrated CICS translator. When specified, EXEC CICS statements are processed during compilation without a separate translator step. Required for CICS programs. |
| CODEPAGE(ccsid) | 1140 | Any valid CCSID | Specifies the EBCDIC code page for the source program and alphanumeric literals. CCSID 1140 is US English with Euro sign. CCSID 037 is US English without Euro sign. |
| CURRENCY(symbol) | $ | Any single character | Specifies the currency symbol used in PICTURE clauses. Allows different currency symbols for international programs (e.g., CURRENCY('£')). |
| DBCS | NODBCS | DBCS, NODBCS | Enables Double-Byte Character Set support for languages that require two bytes per character (Japanese, Chinese, Korean). |
| INTDATE(ANSI/LILIAN) | ANSI | ANSI, LILIAN | Controls the behavior of date intrinsic functions. ANSI returns dates in YYYYMMDD format; LILIAN returns the number of days since October 15, 1582. |
| LIB | LIB | LIB, NOLIB | Enables processing of COPY and BASIS statements. LIB is almost always required; NOLIB prevents copybook inclusion. |
| NSYMBOL(NATIONAL/DBCS) | NATIONAL | NATIONAL, DBCS | Controls interpretation of the N literal prefix. NATIONAL treats N"..." as national (Unicode); DBCS treats it as double-byte. |
| NUMBER | NONUMBER | NUMBER, NONUMBER | Controls whether columns 1-6 contain line numbers verified by the compiler. NONUMBER (the usual setting) ignores columns 1-6. |
| QUOTE/APOST | QUOTE | QUOTE, APOST | Specifies whether string delimiters are quotation marks (") or apostrophes ('). QUOTE is the IBM default; APOST matches the ANSI standard. |
| RENT | RENT | RENT, NORENT | Produces reentrant (read-only) object code. RENT is required for CICS programs and recommended for all programs. Reentrant code can be shared in memory by multiple users simultaneously. |
| SQL | NOSQL | SQL, NOSQL | Enables integrated DB2 coprocessor. Processes EXEC SQL statements during compilation. Required for programs with embedded SQL. |
| SQLCCSID | NOSQLCCSID | SQLCCSID, NOSQLCCSID | Controls whether the DB2 coprocessor applies CCSID conversion to host variables. SQLCCSID ensures proper encoding conversion between COBOL data items and DB2 columns. |
| WORD(name) | -- | Library member name | Specifies a reserved word table that modifies the default reserved word list. Used to unreserve words that conflict with data names in legacy programs. |
Output and Listing Options
| Option | Default | Values | Description |
|---|---|---|---|
| LIST | NOLIST | LIST, NOLIST | Produces an assembler language listing of the generated code. Essential for ABEND debugging -- allows mapping PSW addresses to COBOL statements. |
| MAP | NOMAP | MAP, NOMAP | Produces a Data Division Map showing each data item's offset, length, and attributes. Critical for debugging storage-related issues and understanding record layouts. |
| OFFSET | NOOFFSET | OFFSET, NOOFFSET | Produces a condensed procedure listing showing the assembler offset for each COBOL verb. Smaller than LIST; sufficient for most debugging. Cannot be specified with LIST. |
| SOURCE | SOURCE | SOURCE, NOSOURCE | Includes the COBOL source listing in the compiler output. NOSOURCE suppresses the source listing to reduce output volume. |
| VBREF | NOVBREF | VBREF, NOVBREF | Produces a verb cross-reference listing showing every COBOL verb used and where it appears. Useful for code analysis. |
| XREF | NOXREF | XREF, NOXREF, XREF(FULL), XREF(SHORT) | Produces a cross-reference listing of data names and procedure names with line numbers where each is defined and referenced. XREF(FULL) includes unreferenced items. Essential for code analysis and maintenance. |
| TERMINAL | NOTERMINAL | TERMINAL, NOTERMINAL | Sends progress and diagnostic messages to SYSTERM (the terminal) in addition to the listing. Useful for TSO foreground compilations. |
Optimization Options
| Option | Default | Values | Description |
|---|---|---|---|
| OPTIMIZE(0/1/2) | OPTIMIZE(0) | 0, 1, 2 | Controls optimization level. 0 = no optimization (fastest compile, easiest debug). 1 = moderate optimization (recommended for most production). 2 = aggressive optimization (best performance, longer compile, harder debug). |
| HGPR(PRESERVE/NOPRESERVE) | PRESERVE | PRESERVE, NOPRESERVE | Controls whether high halves of 64-bit general purpose registers are saved on entry. NOPRESERVE generates slightly faster code but requires that the calling environment does not use the high halves. |
| ARCH(n) | ARCH(10) | 7 through 14 | Specifies the minimum z/Architecture level for generated code. Higher values enable newer hardware instructions. ARCH(13) enables z15 instructions; ARCH(14) enables z16 instructions. Match to your target hardware. |
Data Handling Options
| Option | Default | Values | Description |
|---|---|---|---|
| AWO | NOAWO | AWO, NOAWO | Automatic Write Overflow. Controls whether WRITE ADVANCING automatically handles page overflow for print files. |
| BLOCK0 | NOBLOCK0 | BLOCK0, NOBLOCK0 | Controls blocking behavior when no BLOCK CONTAINS clause is specified. BLOCK0 lets the system determine optimal block size. Recommended for new programs. |
| FASTSRT | NOFASTSRT | FASTSRT, NOFASTSRT | Allows the sort utility (DFSORT) to manage input and output files directly, bypassing COBOL I/O. Significantly improves SORT performance when INPUT/OUTPUT PROCEDUREs are not needed. |
| TRUNC(STD/OPT/BIN) | STD | STD, OPT, BIN | Controls truncation behavior for COMP/BINARY items. STD truncates to PIC size. OPT allows the compiler to choose the most efficient truncation. BIN truncates to the binary field's full capacity. BIN is safest for interface fields. |
Debugging Options
| Option | Default | Values | Description |
|---|---|---|---|
| SSRANGE | NOSSRANGE | SSRANGE, NOSSRANGE | Enables runtime checking of subscript and index ranges, and reference modification bounds. When a violation occurs, the program ABENDs with a diagnostic message identifying the offending statement. Essential during development; adds runtime overhead in production. |
| TEST(NOSEP/SEP/EJPD) | NOTEST | Various | Controls generation of debugging information. TEST(SEPARATE) generates a separate debug side file. TEST with no options generates inline debugging information. Required for IBM Debug Tool (z/OS Debugger). |
| CHECK(ON/OFF) | NOCHECK | CHECK, NOCHECK | Enables runtime checks for numeric data validity and pointer reference errors. Similar to SSRANGE but broader in scope. Adds overhead; use during development. |
| DIAGTRUNC | NODIAGTRUNC | DIAGTRUNC, NODIAGTRUNC | Generates compile-time diagnostic messages for MOVE statements where the receiving field is shorter than the sending field, potentially causing truncation. Helpful for detecting data loss. |
Commonly Used Option Sets
Development and debugging:
MAP,LIST,SSRANGE,TEST(SEP),XREF(FULL),SOURCE
Production:
MAP,OFFSET,OPTIMIZE(1),RENT,XREF(SHORT),SOURCE
CICS development:
MAP,LIST,SSRANGE,TEST(SEP),XREF(FULL),CICS,RENT,SOURCE
DB2 development:
MAP,LIST,SSRANGE,TEST(SEP),XREF(FULL),SQL,SQLCCSID,SOURCE
CICS + DB2 production:
MAP,OFFSET,OPTIMIZE(1),CICS,SQL,SQLCCSID,RENT,XREF(SHORT)
Part 2: GnuCOBOL
GnuCOBOL options are specified on the command line when invoking the cobc compiler. GnuCOBOL translates COBOL source to C code, then compiles the C code with GCC (or another C compiler). Some options control the COBOL-to-C translation; others are passed to the underlying C compiler.
Basic Compilation Commands
# Compile and link to executable
cobc -x program.cob
# Compile to dynamically loadable module (for CALL)
cobc -m subprogram.cob
# Compile only (produce object file)
cobc -c program.cob
# Compile and link multiple source files
cobc -x main.cob sub1.cob sub2.cob
# Compile with a specific standard
cobc -x -std=cobol85 program.cob
Compilation Mode Options
| Option | Description |
|---|---|
| -x | Compile and link to produce a standalone executable. This is the most common option for main programs. |
| -m | Compile and link to produce a dynamically loadable module (.so on Linux, .dll on Windows). Used for subprograms that are called dynamically. |
| -c | Compile only -- produce an object file (.o) without linking. Used when linking is performed separately. |
| -b | Compile and link to produce a dynamically loadable module (same as -m, alternative name). |
| -E | Preprocess only -- expand COPY statements and REPLACE directives, output the preprocessed source. Useful for debugging copybook inclusions. |
Language Standard Options
| Option | Description |
|---|---|
| -std=cobol85 | Enforce the COBOL-85 standard. Rejects features not in the 1985 standard. Most restrictive; ensures compatibility with oldest production code. |
| -std=cobol2002 | Enforce the COBOL 2002 standard. Allows OO features, free-format, and other 2002 additions. |
| -std=cobol2014 | Enforce the COBOL 2014 standard. Allows JSON/XML processing and other 2014 features. |
| -std=default | Use GnuCOBOL's default standard, which is a pragmatic combination of features from multiple standards. This is the recommended setting for learning. |
| -std=ibm | Enable IBM Enterprise COBOL compatibility mode. Accepts many IBM-specific extensions (COMP-5, SERVICE RELOAD, etc.). Useful when compiling code originally written for IBM mainframes. |
| -std=mf | Enable Micro Focus COBOL compatibility mode. Accepts Micro Focus extensions. |
Source Format Options
| Option | Description |
|---|---|
| -free | Compile in free-format mode. Source code is not constrained by column positions. |
| -fixed | Compile in fixed-format mode (the default). Columns 1-6 are sequence numbers, column 7 is the indicator, columns 8-72 are the program area. |
| -tab n | Set the tab stop width for fixed-format source. Default is 8. |
Debugging and Diagnostic Options
| Option | Description |
|---|---|
| -debug | Enable all runtime checks: subscript bounds, numeric data validity, pointer references, and PERFORM range checks. Equivalent to IBM's SSRANGE plus CHECK. Adds significant runtime overhead; use only during development. |
| -Wall | Enable all compiler warnings. Highly recommended during development. Reports potential issues such as unused variables, unreachable code, and implicit type conversions. |
| -Werror | Treat all warnings as errors. The compilation fails if any warning is produced. Useful for enforcing strict coding standards. |
| -Wpossible-truncation | Warn when a MOVE may truncate data because the receiving field is shorter than the sending field. |
| -Wother | Enable additional warnings not covered by -Wall. |
| -fsyntax-only | Check syntax without generating code. Useful for quick validation during editing. |
| -g | Generate debugging information for use with GDB (GNU Debugger). Allows source-level debugging of the generated C code and, with the appropriate mappings, COBOL source-level debugging. |
| -ftrace | Generate trace output showing each section and paragraph entry during execution. Produces verbose output but is invaluable for understanding program flow. |
| -ftraceall | Generate trace output for every COBOL statement, not just section/paragraph entries. Extremely verbose; use only on small test programs. |
| -fsource-location | Include source file and line number information in runtime error messages. Recommended for development builds. |
File and Include Path Options
| Option | Description |
|---|---|
| -I directory | Add a directory to the copybook search path. Copybooks referenced in COPY statements are searched in the specified directories. Multiple -I options can be specified; directories are searched in order. |
| -ext extension | Specify file extensions to search for copybooks. Default is .cpy, .cob, .cbl, and others. |
| -conf file | Specify a custom configuration file that defines the compiler's behavior (reserved words, feature flags, etc.). |
| -o outputname | Specify the output file name. Without this option, the output name is derived from the input file name. |
Runtime Environment Variables
GnuCOBOL's runtime behavior can be controlled through environment variables. These are not compiler options but are set before running the compiled program.
| Variable | Description |
|---|---|
| COB_LIBRARY_PATH | Directories searched for dynamically loaded modules (subprograms called with CALL). Separate multiple directories with the platform's path separator (colon on Linux/macOS, semicolon on Windows). |
| COB_PRE_LOAD | Modules to preload before program execution. Comma-separated list of module names. |
| COB_SET_TRACE | Set to Y to enable runtime tracing (equivalent to -ftrace at compile time but controlled at runtime). |
| COB_SET_DEBUG | Set to Y to enable runtime debugging checks (equivalent to -debug at compile time). |
| COB_FILE_PATH | Directories searched for data files referenced in ASSIGN clauses. |
| COB_SCREEN_ESC | Set to Y to enable the ESC key in ACCEPT statements for screen section input. |
| COB_SCREEN_EXCEPTIONS | Set to Y to enable exception handling for screen I/O operations. |
| DD_ddname | Assigns an external file to a DD name. For example, DD_INFILE=mydata.txt maps the COBOL file assigned to "INFILE" to the physical file mydata.txt. This emulates JCL DD statements in a distributed environment. |
Commonly Used GnuCOBOL Command Lines
Development (with all checks and warnings):
cobc -x -debug -Wall -fsource-location -I ./shared-copybooks program.cob
Compile subprogram as loadable module:
cobc -m -debug -Wall -I ./shared-copybooks subprogram.cob
Production-style (optimized, no debug overhead):
cobc -x -O2 -I ./shared-copybooks program.cob
IBM compatibility mode:
cobc -x -std=ibm -debug -Wall -I ./shared-copybooks program.cob
Syntax check only (fast validation):
cobc -fsyntax-only -Wall -std=cobol85 -I ./shared-copybooks program.cob
Free-format source:
cobc -x -free -debug -Wall program.cob
Compile with trace output:
cobc -x -ftrace -fsource-location program.cob
Part 3: Mapping Between IBM and GnuCOBOL Options
The following table maps common IBM Enterprise COBOL options to their GnuCOBOL equivalents.
| Purpose | IBM Option | GnuCOBOL Equivalent |
|---|---|---|
| Subscript range checking | SSRANGE | -debug (includes range checks) |
| Source listing | SOURCE | (always produced to stderr with -v) |
| Cross-reference | XREF | (not available; use external tools) |
| Data map | MAP | (not available; use -g and GDB) |
| Assembler listing | LIST | (use -save-temps to see generated C) |
| Optimization | OPTIMIZE(0/1/2) | -O0, -O1, -O2, -O3 |
| CICS support | CICS | (not available in GnuCOBOL) |
| DB2 support | SQL | (not available; use ODBC or native SQL) |
| Reentrant code | RENT | (all GnuCOBOL modules are reentrant) |
| Fixed format | (default) | -fixed (default) |
| Free format | (CBL directive) | -free |
| Reserved words | WORD(name) | -std= or -conf file |
| String delimiter | QUOTE/APOST | (configurable via -conf) |
| Arithmetic precision | ARITH(EXTEND) | (31-digit precision is default) |
| Truncation behavior | TRUNC(STD/OPT/BIN) | -fbinary-truncate / -fno-binary-truncate |
Part 4: Recommended Options for This Textbook
For the exercises in this textbook, the following GnuCOBOL options are recommended:
Standard Exercise Compilation
cobc -x -debug -Wall -fsource-location -I ../shared-copybooks exercise.cob
This enables all runtime checks (-debug), all compiler warnings (-Wall), source location in error messages (-fsource-location), and includes the shared copybook directory (-I).
Compiling Subprograms
cobc -m -debug -Wall -I ../shared-copybooks subprogram.cob
Running Programs with Dynamic Calls
export COB_LIBRARY_PATH=./modules:../shared-modules
./mainprogram
On Windows (Command Prompt):
set COB_LIBRARY_PATH=.\modules;..\shared-modules
mainprogram.exe
Removing Debug Overhead for Performance Testing
cobc -x -O2 -I ../shared-copybooks exercise.cob
The -O2 option enables GCC optimization (since GnuCOBOL generates C code compiled by GCC), and the absence of -debug removes runtime checking overhead. Use this only for performance comparison; always use -debug during development.