Interfacing With The OS
Compiling Programs
Program source files should have by convention, extensions of .cob or .cbl.
Program file names should match exactly the specification of PROGRAM-ID (including case).
Spaces cannot be included in primary entry-point names and therefore must not be included in program file names.
The GnuCOBOL compiler will translate your COBOL program into C source code, compile that C source code into executable binary form using the C compiler specified when GnuCOBOL was built and link that executable binary into:
- Directly executable form
-
This is an executable file directly-executable from the command-line. On Windows computers, this would be an
.exefile. On Unix systems, this will be a file with no specific extension, but with execute permissions. This file will include the main program as well as any static-linked subprograms. - Static-linkable form
-
This is a single subprogram compiled into object-code form, ready to be linked in with a main program to form a directly-executable program. On windows computers, these generally are
.o(object-code) files. - Dynamically-loadable executable form
-
These are dynamically-loadable object code files ready to be invoked from other programs at execution time. On Windows systems, these would be
.dllfiles, while on Unix systems they are typically.sofiles (OSX uses.dylib).
cobc - The GnuCOBOL Compiler
The GnuCOBOL compiler is named cobc (cobc.exe on a Windows system).
The following describes the syntax and option switches of the cobc command. This information may be displayed by entering the command cobc --help or cobc -h.
GnuCOBOL compiler for most COBOL dialects with lots of extensions
Sorted within groups
Usage: cobc [options]... file...
Options:
-h, --help display this help and exit
-du(mpversion) display compiler version and exit
-i, --info display compiler information (build/environment)
and exit
-q, --brief reduced displays, commands invoked not shown
-v, --verbose verbose mode, display additional information;
multiple -v options increase the verbosity,
the maximum is 3 as follows:
(1) display compiler version and the commands
invoked by the compiler,
(2) pass verbose option to assembler/compiler
(3) pass verbose option to linker
-V, --version display compiler version information and exit
-### like -v but commands not executed
-A <options> add <options> to the C compile phase
-b combine all input files into a single
dynamically loadable module
-c compile and assemble, but do not link
--conf=<file> user-defined dialect configuration; see -std
-C translation only; convert COBOL to C
-d, --debug enable all run-time error checking,
equal to -fstack-check -fec=EC-ALL
-D <define> define <define> for COBOL compilation
-ext <extension> add file extension for resolving COPY
-E preprocess only; do not compile or link
-F, --free use free source format (alias for -fformat=free)
--fixed use fixed source format (default; alias for
-fformat=fixed)
-fec=<exception-name> enable code generation for <exception-name>,
see --list-exceptions for the possible values,
sets -fsource-location
-fno-ec=<exception-name>
disable code generation for <exception-name>
-g enable C compiler debug and stack check
-I <directory> add <directory> to copy/include search path
-j [<args>], --job[=<args>]
run program after build, passing <args>
-K <entry> generate CALL to <entry> as static
-l <lib> link the library <lib>
-L <directory> add <directory> to library search path
--list-exceptions display exception names
--list-intrinsics display intrinsic functions
--list-mnemonics display mnemonic names
--list-reserved display reserved words and internal registers
--list-system display system routines
-m build a dynamically loadable module (default)
-o <file> place the output into <file>
-O, -O2, -O3, -Os enable optimization
-O0 disable optimization
-P[=<dir or file>] generate preprocessed program listing (.lst)
-Q <options> add <options> to the C link phase
-std=<dialect> warnings/features for a specific Cobol dialect
<dialect> can be one of:
default
acu ACUCOBOL-GT compatibility
acu-strict ACUCOBOL-GT compatibility - strict
bs2000 BS2000 COBOL compatibility (back again)
bs2000-strict BS2000 COBOL compatibility - strict
cobol85 COBOL (19) 85 Standard
cobol2002 COBOL 2002 Standard
cobol2014 COBOL 2014 Standard
gcos-strict GCOS COBOL compatibility - strict
gcos GCOS COBOL compatibility
ibm IBM COBOL compatibility
ibm-strict IBM COBOL compatibility - strict
mf Micro Focus COBOL compatibility
mf-strict Micro Focus COBOL compatibility - strict
mvs MVS/VM COBOL compatibility
mvs-strict MVS/VM COBOL compatibility - strict
rm RM-COBOL compatibility
rm-strict RM-COBOL compatibility - strict
xopen X/Open COBOL Standard
See configuration files in directory config and more detail
at -std= below.
-S compile only; output assembly file
--save-temps[=<dir>] save intermediate files
* default: current directory
-t <file> generate and place a program listing into <file>
--tlines=<lines> specify lines per page in listing, default = 55
-T <file> generate and place a wide program listing into <file>
-x build an executable program
-X, --Xref generate internal cross reference
Warning options:
-w disable all warnings
-Wall enable most warnings (all except as noted below)
-Wadditional additional warnings only raised with -Wall
-Warchaic warn if archaic features are used
-Warithmetic-osvs warn if arithmetic expression precision has changed
-Wcall-params warn about non 01/77 items for CALL parameters
* NOT set with -Wall
-Wcolumn-overflow warn about text after program-text area, FIXED format
* NOT set with -Wall
-Wconstant-expression warn about expressions that always resolve to true/false
-Wconstant-numlit-expression
warn about numeric expressions that always resolve to
true/false
-Wdangling-text warn about source text after program-area
* NOT set with -Wall
-Werror treat all warnings as errors
-Werror=<warning> treat specified <warning> as error
-Wextra like -Wall but enable some extra warning flags
-Wimplicit-define warn whenever data items are implicitly defined
* NOT set with -Wall
-Winitial-value warn if initial VALUE clause is ignored
-Wlarger-01-redefines warn about larger redefines allowed by COBOL standards
-Wlinkage warn about dangling LINKAGE items
* NOT set with -Wall
-Wobsolete warn if obsolete features are used
-Woverlap warn about overlapping MOVE of items
-Wno-corresponding do not warn about CORRESPONDING with no matching items
* ALWAYS active
-Wno-dialect do not warn about dialect specific issues
* ALWAYS active
-Wgoto-different-section
warn about GO TO a praragraph defined in a different section
-Wno-error don't treat warnings as errors
-Wno-error=<warning> don't treat specified <warning> as error
-Wno-goto-section do not warn about GO TO section-name
* ALWAYS active
-Wno-ignored-error do not warn about errors in code parts which are
unreachable and so normally ignored
* ALWAYS active
-Wno-missing-newline do not warn about missing newlines
* ALWAYS active
-Wno-others do not warn about different issues
* ALWAYS active
-Wno-pending do not warn if pending features are used
* ALWAYS active
-Wno-repository-checks
do not warn/check for program/function/external signature
mismatch
* ALWAYS active
-Wno-unfinished do not warn if unfinished features are used
* ALWAYS active
-Wno-unsupported do not warn if runtime does not support a feature used
-Wno-<warning> disable warning enabled by default, -Wall or -Wextra
-Wparentheses warn if parentheses are omitted around AND within OR
-Wpossible-overlap warn about MOVE of items that may overlap depending on
variables
* NOT set with -Wall
-Wpossible-truncate warn about possible field truncation
* NOT set with -Wall
-Wprototypes warn about missing FUNCTION prototypes/definitions
-Wredefinition warn about non-referenced ambiguous data items
-Wstrict-typing warn strictly about type mismatch
-Wsuspicious-perform-thru
warn if PERFORM THRU references procedures not in ascending
order or multiple sections
* ALWAYS active
-Wterminator warn about lack of scope terminator END-XXX
* NOT set with -Wall
-Wtruncate warn about field truncation from constant assignments
-Wunreachable warn about likely unreachable statements
* NOT set with -Wall
Compiler options:
-fsign=[ASCII|EBCDIC] define display sign representation
* default: machine native
-ffold-copy=[UPPER|LOWER]
fold COPY subject to value
* default: no transformation
-ffold-call=[UPPER|LOWER]
fold PROGRAM-ID, CALL, CANCEL subject to value
* default: no transformation
-fmax-errors=<number> maximum number of errors to report before
compilation is aborted
* default: 128
-fintrinsics=[ALL|intrinsic
function name(,name,...)]
intrinsics to be used without FUNCTION keyword
-fdump=<scope> dump data fields on abort, <scope> may be
a combination of: ALL, WS, LS, RD, FD, SC, LO
-fcallfh=<name> specifies <name> to be used for I/O
as external provided EXTFH interface module
-febcdic-table=[DEFAULT|RESTRICTED-GC|IBM|GCOS]
define EBCDIC translation table:
* default: translation to extended ASCII as per MF
* restricted-gc: translation from restricted ASCII only
* ibm: translation to restricted ASCII as per IBM
* gcos: translation to extended ASCII as per GCOS7
-fdefault-colseq=[ASCII|EBCDIC|NATIVE]
define default collating sequence
* default: NATIVE
-fstack-extended store origin of entrypoints and PERFORM
* turned on by -debug/-dump
-fno-remove-unreachable
disable remove of unreachable code
* turned off by -g
-ftrace generate trace code
* scope: executed SECTION/PARAGRAPH
-ftraceall generate trace code
* scope: executed SECTION/PARAGRAPH/STATEMENTS
-fsyntax-only syntax error checking only; don't emit any output
-fdebugging-line enable debugging lines
* 'D' in indicator column or floating >>D
-fsource-location generate source location code
* turned on by -debug/-ftraceall/-fec/-dump
-fimplicit-init automatic initialization of the COBOL runtime system
-fno-recursive-check disable check of recursive program call;
effectively compiling as RECURSIVE program
-fstack-check PERFORM stack checking
* turned on by -debug/-g
-fsection-exit-check check that code execution does not leave the scope of
SECTIONs
-fimplicit-goback-check
check that code execution does not end implicit at end of
PROCEDURE DIVISION
-fwrite-after use AFTER 1 for WRITE of LINE SEQUENTIAL
* default: BEFORE 1
-fmfcomment '*' in column 1 treated as comment with listing suppression
* FIXED/COBOL85/VARIABLE format only
-facucomment '$' in indicator area treated as '*',
'|' treated as floating comment
-fno-trunc allow numeric field overflow
* non-ANSI behaviour
-fsingle-quote use a single quote (apostrophe) for QUOTE
* default: double quote
-foptional-file treat all files as OPTIONAL
* unless NOT OPTIONAL specified
-fstatic-call output static function calls for the CALL statement
-fno-gen-c-decl-static-call
disable generation of C function declarations
for subroutines with static CALL
-fgen-c-line-directives
generate source location directives in C code;
* turned on by -g
-fgen-c-labels generate extra labels in C sources;
* turned on by -g
-fno-theaders suppress all headers and output of compilation
options from listing while keeping page breaks
-fno-tsource suppress source from listing
-fno-tmessages suppress warning and error summary from listing
-ftsymbols specify symbols in listing
-fno-diagnostics-show-option
suppress output of option that directly
controls the diagnostic
Compiler dialect configuration options:
-freserved-words=<value>
use of complete/fixed reserved words
-ftab-width=1..12 number of spaces that are assumed for tabs
-ftext-column=72..255 right margin column number for fixed-form reference format
-fpic-length=<number> maximum number of characters allowed in the PICTURE
character-string
-fword-length=1..63 maximum word-length for COBOL (= programmer defined) words
-fliteral-length=<number>
maximum literal size in general
-fnumeric-literal-length=1..38
maximum numeric literal size
-fdefaultbyte=<value> default initialization for fields without VALUE, may be
one of
* character in quotes
* decimal 0..255 representing a character
* "init" to initialize to PICTURE/USAGE
* "none" to do no explicit initialization
* default: "init"
-fformat=<value> default reference-format, may be one of: FIXED, FREE,
COBOL85, VARIABLE, XOPEN, XCARD, CRT, TERMINAL, COBOLX
-fbinary-size=<value> binary byte size - defines the allocated bytes according to
PIC, may be one of: 2-4-8, 1-2-4-8, 1--8
-fbinary-byteorder=<value>
binary byte order, may be one of: native, big-endian
-fassign-clause=<value>
how to interpret 'ASSIGN word': as 'ASSIGN EXTERNAL word' or
'ASSIGN DYNAMIC word', may be one of: dynamic, external,
ibm (= external), mf (= dynamic)
-fscreen-section-rules=<value>
which compiler's rules to apply to SCREEN SECTION item
clauses, may be one of: acu, gc, mf, rm, std, xopen
-fdpc-in-data=<value> whether DECIMAL-POINT IS COMMA has effect in XML/JSON
GENERATE, may be one of: none, xml, json, all
-ffilename-mapping resolve file names at run time using environment variables
-fpretty-display alternate formatting of numeric fields
-fbinary-truncate numeric truncation according to ANSI
-fcomplex-odo allow complex OCCURS DEPENDING ON
-fodoslide adjust items following OCCURS DEPENDING (implies complex-odo)
-findirect-redefines allow REDEFINES to other than last equal level number
-frelax-syntax-checks allow certain syntax variations (e.g. REDEFINES position)
-fref-mod-zero-length allow zero length reference-modification (only changed with
EC-BOUND-REF-MOD active)
-frelax-level-hierarchy
allow non-matching level numbers
-fselect-working require ASSIGN USING items to be in WORKING-STORAGE
-flocal-implies-recursive
LOCAL-STORAGE SECTION implies RECURSIVE attribute
-fsticky-linkage LINKAGE SECTION items remain allocated between invocations
-fmove-ibm MOVE operates as on IBM (left to right, byte by byte)
-fperform-osvs exit point of any currently executing perform is recognized
if reached
-farithmetic-osvs limit precision in intermediate results to precision of
final result (less accurate)
-fconstant-folding evaluate constant expressions at compile time
-fhostsign allow hexadecimal value 'F' for NUMERIC test of signed
PACKED DECIMAL field
-fprogram-name-redefinition
program names don't lead to a reserved identifier
-faccept-update set WITH UPDATE clause as default for ACCEPT dest-item,
instead of WITH NO UPDATE
-faccept-auto set WITH AUTO clause as default for ACCEPT dest-item,
instead of WITH TAB
-fconsole-is-crt assume CONSOLE IS CRT if not set otherwise
-fno-echo-means-secure NO-ECHO
hides input with asterisks like SECURE
-fline-col-zero-default
assume a field DISPLAY starts at LINE 0 COL 0 (i.e. at the
cursor), not LINE 1 COL 1
-fdisplay-special-fig-consts
special behaviour of DISPLAY SPACE/ALL X'01'/ALL X'02'/ALL
X'07'
-fbinary-comp-1 COMP-1 is a 16-bit signed integer
-fnumeric-pointer POINTER is a 64-bit unsigned integer
-fmove-non-numeric-lit-to-numeric-is-zero
imply zero in move of non-numeric literal to numeric items
-fimplicit-assign-dynamic-var
implicitly define a variable if an ASSIGN DYNAMIC does not
match any data item
-fdevice-mnemonics specifying device by mnemonic
-fxml-parse-xmlss XML PARSE XMLSS
-fareacheck check contents of Area A (when reference format supports
Area A enforcement),
enabled checks include:
* division, section, paragraph names, level indicators (FD,
SD, RD, and CD),
and toplevel numbers (01 and 77) must start in Area A;
* statements must not start in Area A; and
* separator periods must not be within Area A
-fcomment-paragraphs=<support>
comment paragraphs in IDENTIFICATION DIVISION (AUTHOR,
DATE-WRITTEN, ...)
-fcontrol-division=<support>
CONTROL DIVISION
-fpartial-replace-when-literal-src=<support>
apply partial replacing with literal source operand even
when it replaces with spaces only;
* "skip" prevents such replacements
-fmemory-size-clause=<support>
MEMORY-SIZE clause
-fmultiple-file-tape-clause=<support>
MULTIPLE-FILE-TAPE clause
-flabel-records-clause=<support>
LABEL-RECORDS clause
-fvalue-of-clause=<support>
VALUE-OF clause
-fdata-records-clause=<support>
DATA-RECORDS clause
-ftop-level-occurs-clause=<support>
OCCURS clause on top-level
-fsame-as-clause=<support>
SAME AS clause
-ftype-to-clause=<support>
TYPE TO clause
-fusage-type=<support> USAGE type-name
-fsynchronized-clause=<support>
SYNCHRONIZED clause
-fsync-left-right=<support>
LEFT/RIGHT phrases in SYNCHRONIZED clause
-fspecial-names-clause=<support>
SPECIAL-NAMES clause
-fgoto-statement-without-name=<support>
GOTO statement without name
-fstop-literal-statement=<support>
STOP-literal statement
-fstop-identifier-statement=<support>
STOP-identifier statement
-fstop-error-statement=<support>
STOP ERROR statement
-fdebugging-mode=<support>
DEBUGGING MODE and debugging indicator
-fuse-for-debugging=<support>
USE FOR DEBUGGING
-fpadding-character-clause=<support>
PADDING CHARACTER clause
-fnext-sentence-phrase=<support>
NEXT SENTENCE phrase
-flisting-statements=<support>
listing-directive statements EJECT, SKIP1, SKIP2, SKIP3
-ftitle-statement=<support>
listing-directive statement TITLE
-fentry-statement=<support>
ENTRY statement
-fmove-noninteger-to-alphanumeric=<support>
move noninteger to alphanumeric
-fmove-figurative-constant-to-numeric=<support>
move figurative constants to numeric
-fmove-figurative-space-to-numeric=<support>
move figurative constant SPACE to numeric
-fmove-figurative-quote-to-numeric=<support>
move figurative constant QUOTE to numeric
-fodo-without-to=<support>
OCCURS DEPENDING ON without to
-fsection-segments=<support>
section segments
-falter-statement=<support>
ALTER statement
-fcall-overflow=<support>
OVERFLOW clause for CALL
-fnumeric-boolean=<support>
boolean literals (B'1010')
-fhexadecimal-boolean=<support>
hexadecimal-boolean literals (BX'A')
-fnational-literals=<support>
national literals (N'UTF-16 string')
-fhexadecimal-national-literals=<support>
hexadecimal-national literals (NX'265E')
-fnational-character-literals=<support>
non-standard national literals (NC'UTF-16 string')
-fhp-octal-literals=<support>
HP COBOL octal literals (%377)
-facu-literals=<support>
ACUCOBOL-GT literals (#B #O #H #X)
-fword-continuation=<support>
continuation of COBOL words
-fnot-exception-before-exception=<support>
NOT ON EXCEPTION before ON EXCEPTION
-faccept-display-extensions=<support>
extensions to ACCEPT and DISPLAY
-frenames-uncommon-levels=<support>
RENAMES of 01-, 66- and 77-level items
-flarger-redefines=<support>
allow larger REDEFINES items
-fsymbolic-constant=<support>
constants defined in SPECIAL-NAMES
-fconstant-78=<support>
constant with level 78 item (note: has left to right
precedence in expressions)
-fconstant-01=<support>
constant with level 01 CONSTANT AS/FROM item
-fperform-varying-without-by=<support>
PERFORM VARYING without BY phrase (implies BY 1)
-freference-out-of-declaratives=<support>
references to sections not in DECLARATIVES from within
DECLARATIVES
-fprogram-prototypes=<support>
CALL/CANCEL with program-prototype-name
-fcall-convention-mnemonic=<support>
specifying call-convention by mnemonic
-fcall-convention-linkage=<support>
specifying call-convention by WITH ... LINKAGE
-fnumeric-value-for-edited-item=<support>
numeric literals in VALUE clause of numeric-edited items
-fincorrect-conf-sec-order=<support>
incorrect order of CONFIGURATION SECTION paragraphs
-fdefine-constant-directive=<support>
allow >> DEFINE CONSTANT var AS literal
-ffree-redefines-position=<support>
REDEFINES clause not following entry-name in definition
-frecords-mismatch-record-clause=<support>
record sizes does not match RECORD clause
-frecord-delimiter=<support>
RECORD DELIMITER clause
-fsequential-delimiters=<support>
BINARY-SEQUENTIAL and LINE-SEQUENTIAL phrases in
RECORD DELIMITER
-frecord-delim-with-fixed-recs=<support>
RECORD DELIMITER clause on file with fixed-length records
-fmissing-statement=<support>
missing statement (e.g. empty IF / PERFORM)
-fmissing-period=<support>
missing period in PROCEDURE DIVISION (when reference
format supports Area A enforcement)
-fzero-length-literals=<support>
zero-length literals, e.g. '' and ""
-fxml-generate-extra-phrases=<support>
XML GENERATE's phrases other than COUNT IN
-fcontinue-after=<support>
AFTER phrase in CONTINUE statement
-fgoto-entry=<support> ENTRY FOR GOTO and GOTO ENTRY statements
-fassign-variable=<support>
ASSIGN [TO] variable in SELECT
-fassign-using-variable=<support>
ASSIGN USING/VARYING variable in SELECT
-fassign-ext-dyn=<support>
ASSIGN EXTERNAL/DYNAMIC in SELECT
-fassign-disk-from=<support>
ASSIGN DISK FROM variable in SELECT
-fvsam-status=<support>
VSAM status in FILE STATUS
-fself-call-recursive=<support>
CALL to own PROGRAM-ID implies RECURSIVE attribute
-frecord-contains-depending-clause=<support>
DEPENDING clause in RECORD CONTAINS
-fpicture-l=<support> PICTURE string with 'L' character
where <support> is one of the following:
'ok', 'warning', 'archaic', 'obsolete', 'skip', 'ignore', 'error',
'unconformable'
-fnot-reserved=<word> word to be taken out of the reserved words list
-freserved=<word> word to be added to reserved words list
-freserved=<word>:<alias>
word to be added to reserved words list as alias
-fnot-register=<word> special register to disable
-fregister=<word> or <word>:<definition>
special register to enable
For -std= option and others, more details.
Note: 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 and GnuCOBOL specific extensions. COBOL sources compiled with these dialects therefore may work only with GnuCOBOL. COBOL sources may need a change because of rich feature-set and reserved words in GnuCOBOL, otherwise offending words may be removed by ‘-fno-reserved=word’. COBOL-85, X/Open COBOL, COBOL 2002 and COBOL 2014 are always "strict".
The intrinsic functions that are actually available as intrinsic functions depend on the -std used. Function names that aren’t marked as intrinsic functions by the current -std can be used freely as user defined words or even as user defined functions.
-fformat dialect option, and extended SOURCE FORMAT directives, with the following newly supported reference-formats (in addition to FIXED/FREE):
COBOL85 Fixed-form format with enforcement of Area A
COBOLX GCOS 7 extended format
CRT ICOBOL Free-form format
TERMINAL ACUCOBOL-GT Terminal format
VARIABLE Micro Focus Variable Fixed-form format
XCARD ICOBOL xCard (extended card) format
XOPEN X/Open Free-form format
These formats come with Area A enforcement (except for XOPEN), that checks whether division, section, and paragraph names start in Area A (i.e, before margin B), and so do level indicators FD, SD, RD, and CD, and level numbers 01, and 77. The underlying checks are enabled or disabled by default using dialect option ‘areacheck’, and then with ‘$SET AREACHECK’ and ‘$SET NOAREACHECK’ compiler directives.
As a result of reference format being a dialect option, Area A enforcement is available and enabled by default for dialects BS2000 COBOL, CA Realia II, COBOL85, GCOS COBOL, IBM COBOL, MVS/VM COBOL, RM-COBOL, and X/Open COBOL.
Area A enforcement additionally enables detection of missing periods before level numbers that lie in Area A in the DATA DIVISION, and before paragraph and section names in the PROCEDURE DIVISION. More generally, some, but not all, missing periods can be reported and recovered from. This is configurable with option ‘missing-period’.
and others, that discuss dialect options:
The most important part is: * if you use a -strict option, then the behaviour is according to that dialect and features are limited to what the dialect supports, that’s especially true for reserved words (which are not unlikely to create problems in case of same user-defined names [for example NOTHING]), intrinsic functions and registers; if a feature does not conflict at all with a dialect it may still be available; we definitely don’t drop any CBL routines, for example (you could create those in other compilers as well, after all) * non-strict are "identical behaviour" (for example initialization and soon possibly also runtime checks) but with all features (and reserved words) enabled that don’t directly conflict with that dialect
If you start a migration and/or need to "still compile and run" on the other compiler: use the strict one; if you then want to use GnuCOBOL’s features because that is already done, then use the non-strict one, possible unreserving single words that conflict with your code. If you want to be portable between compilers use xopen/cobol85 (because that’s widely supported) or the newer COBOL standards (but many features of that aren’t available in other compilers). If you start with a new COBOL project and want to stick to GnuCOBOL in the future: just use the default.
And in any case there’s the option to manually override any dialect option on the command line or write your own conf file that includes a dialect, then overrides what you want different and only reference that by –conf.
To learn more about the dialect options: check cobc –help (or directly cobc/config.def) and the config files itself. To see what reserved words / intrinsics / registers are active: use cobc’s –list options after using -std/-conf (and maybe -f[not-]reserved).
Each file specified on the cobc command constitutes a Compilation Unit. A compilation unit may be a single GnuCOBOL program — with or without nested subprograms(see Independent vs Contained vs Nested Subprograms) — or multiple GnuCOBOL programs, separated by END PROGRAM or END FUNCTION marker lines, as appropriate. See Independent vs Contained vs Nested Subprograms, for some examples of these marker lines.
A compilation unit may also be a C-language source program, recognized as such by having a file extension of .c or an assembly-language program, recognized by its file extension of .s. In such a case, COBOL compilation of that file will be bypassed by the cobc command; instead, the file will be passed directly to the C compiler or assembler (executed automatically by cobc).
A compilation unit may also be an object-code module (output from the C compiler), recognized as such by having a file extension of .o. In these situations, all compilation will be bypassed, and the object code will be “bound” into the generated executable by the linker (an ld command executed internally by the cobc command).
Pre-compiled object-code subprograms may be automatically located by the GnuCOBOL compiler and the loader by using the LD_LIBRARY_PATH compilation-time environment variable (see Compilation Time Environment Variables). If they are locatable through that environment variable, they need not be named on the cobc command.
The collection of compilation units supplied on a single cobc execution constitute a Compilation Group. All executable code produced from a single compilation group will be collected together into a single executable file, whose filename will be the same as that of the first compilation unit specified on the cobc command.
The simplest mode of compilation is to generate a single executable file from one or more GnuCOBOL source files:
cobc -x mainprog.cbl sub1.cbl sub2.cbl
The main program must be the first program found in the first compilation unit (mainprog.cbl). The remainder of that compilation unit as well as the rest of the files in the compilation group (sub1.cbl and sub2.cbl) must be independent and/or contained subprograms (see Independent vs Contained vs Nested Subprograms).
This command assumes that all source files are in the directory from which the cobc command was executed. You are, of course, free to include full pathnames with any filename, if necessary.
With the -x switch on the compiler command, a single directly-executable executable file (UNIX, Windows/Cygwin, OSX) or “exe” file (Windows, Windows/MinGW) will be generated. This executable file has the compiled code for all COBOL programs contained within the compilation group specified on the cobc command included in the file.
Any subroutines or user-defined functions that weren’t included in any of the source files comprising the compilation group will be treated as dynamically loadable subprograms (see Dynamic vs Static Subprograms).
Optionally, the -o switch may be used in addition to -x to specify the name of the generated executable file. If -o switch is not specified, the filename of the 1st compilation unit will be used as the name of the executable file. The appropriate extension for the generated file (.exe, on a Windows computer, for example) will be added to the filename that is explicitly specified or implicitly assumed for the output file.
Compilations may be performed to generate dynamically-loadable modules (or dynamically-loadable libraries, as they are frequently called). These compilations are performed by using the -m switch instead of -x switch:
cobc -m mainprog.cbl sub1.cbl sub2.cbl
When the -m switch is used, an operating-system-specific dynamically-loadable module is generated for each individual compilation unit, using the filename of each compilation unit as its module filename and either an extension of .so (UNIX, Windows/Cygwin), .dylib (OSX) or .dll (Windows, Windows/MinGW).
You may compile GnuCOBOL subprograms into assembler source code which can then be assembled and linked with a main program when that main program is compiled. To create such an assembler source file, compile the subprogram(s) as follows:
cobc -S sprog1.cbl
The above generates an assembler source file named sprog1.s. If you have multiple subprograms to compile this way, just string their file names out on the command. Each will be translated to its own assembler source file.
Later, when you wish to compile a calling program and combine any needed assembly language subroutines in (as static subroutines — see Dynamic vs Static Subprograms), use a command such as this:
cobc -x mainprog.cbl sprog1.s
cobc option -Xref an example
The following shows the output from using -Xref.
Using the internal -Xref as extra options -X -t prog.list :
GnuCOBOL 3.1.2.0 prog.cbl Thu Nov 25 15:31:52 2021 Page 0001
LINE PG/LN A...B............................................................
000001 000001 IDENTIFICATION DIVISION.
000002 000002 PROGRAM-ID. prog.
000003 000003 ENVIRONMENT DIVISION.
000004 000004 CONFIGURATION SECTION.
000005 000005 DATA DIVISION.
000006 000006 WORKING-STORAGE SECTION.
000007 000007 COPY 'values.cpy'.
000001C 000001 78 I VALUE 20.
000002C 000002 78 J VALUE 5000.
000003C 000003 78 M VALUE 5.
000008 000008 01 SETUP-REC.
000009 000009 05 FL1 PIC X(04).
000010 000010 05 FL2 PIC ZZZZZ.
000011 000011 05 FL3 PIC 9(04).
000012 000012 05 FL4 PIC 9(08) COMP.
000013 000013 05 FL5 PIC 9(04) COMP-4.
000014 000014 05 FL6 PIC Z,ZZZ.99.
000015 000015 05 FL7 PIC S9(05) SIGN LEADING SEPARATE.
000016 000016 05 FL8 PIC X(04).
000017 000017 05 FL9 REDEFINES FL8 PIC 9(04).
000018 000018 05 FLA.
000019 000019 10 FLB OCCURS I TIMES.
000020 000020 15 FLC PIC X(02).
000021 000021 10 FLD PIC X(20).
000022 000022 05 FLD1 PIC X(100).
000023 000025 05 FLD3 PIC X(3).
000024 000026 05 FLD4 PIC X(4).
000025 000023 05 FLD2 OCCURS M TO J TIMES DEPENDING ON FL5.
000026 000024 10 FILLER PIC X(01).
000027 000027 PROCEDURE DIVISION.
000028 000028 STOP RUN.
GnuCOBOL 3.1.2.0 prog.cbl Thu Nov 25 15:31:52 2021 Page 0002
NAME DEFINED REFERENCES
SETUP-REC 8 referenced by child
FL1 9 not referenced
FL2 10 not referenced
FL3 11 not referenced
FL4 12 not referenced
FL5 13 25 x1
FL6 14 not referenced
FL7 15 not referenced
FL8 16 not referenced
FL9 17 not referenced
FLA 18 not referenced
FLB 19 not referenced
FLC 20 not referenced
FLD 21 not referenced
FLD1 22 not referenced
FLD3 23 not referenced
FLD4 24 not referenced
FLD2 25 not referenced
GnuCOBOL 3.1.2.0 prog.cbl Thu Nov 25 15:31:52 2021 Page 0003
LABEL DEFINED REFERENCES
E prog 27
0 warnings in compilation group
0 errors in compilation group
Cross Reference listing using cobxref
This program is found in the contrib area or by itself in Sourceforge under its own name (cobxref).
The following shows the output from using cobxref with the same program example.
Note that cobxref also reports the COPY depth which can be up to 9 and includes the program being compiled as depth 1.
Using cobxref with command cobxref prog.cbl :
Cobol Xref v2.02.03 Dictionary File for PROG 25/11/2021 15:22:00:04 Page 1
1 000001 IDENTIFICATION DIVISION.
2 000002 PROGRAM-ID. prog.
3 000003 ENVIRONMENT DIVISION.
4 000004 CONFIGURATION SECTION.
5 000005 DATA DIVISION.
6 000006 WORKING-STORAGE SECTION.
7 000007*COPY 'values.cpy'.
8 000001 78 I VALUE 20.
9 000002 78 J VALUE 5000.
10 000003 78 M VALUE 5.
11 000008 01 SETUP-REC.
12 000009 05 FL1 PIC X(04).
13 000010 05 FL2 PIC ZZZZZ.
14 000011 05 FL3 PIC 9(04).
15 000012 05 FL4 PIC 9(08) COMP.
16 000013 05 FL5 PIC 9(04) COMP-4.
17 000014 05 FL6 PIC Z,ZZZ.99.
18 000015 05 FL7 PIC S9(05) SIGN LEADING SEPARATE.
19 000016 05 FL8 PIC X(04).
20 000017 05 FL9 REDEFINES FL8 PIC 9(04).
21 000018 05 FLA.
22 000019 10 FLB OCCURS I TIMES.
23 000020 15 FLC PIC X(02).
24 000021 10 FLD PIC X(20).
25 000022 05 FLD1 PIC X(100).
26 000025 05 FLD3 PIC X(3).
27 000026 05 FLD4 PIC X(4).
28 000023 05 FLD2 OCCURS M TO J TIMES DEPENDING ON FL5.
29 000024 10 FILLER PIC X(01).
30 000027 PROCEDURE DIVISION.
31 000028 STOP RUN.
32 *>>>Info: Total Copy Depth Used = 02
Cobol Xref v2.02.03 Dictionary File for PROG 25/11/2021 15:22:00:04 Page 2
Symbols of Module: PROG (PROG)
------------------------------
Data Section (WORKING-STORAGE) Defn Locations
-------------------------------+------------------------------------------
FL1 000012W
FL2 000013W
FL3 000014W
FL4 000015W
FL5 000016W 000028
FL6 000017W
FL7 000018W
FL8 000019W 000020
FL9 000020W
FLA 000021W
FLB 000022W
FLC 000023W
FLD 000024W
FLD1 000025W
FLD2 000028W
FLD3 000026W
FLD4 000027W
I 000008W 000022
J 000009W 000028
M 000010W 000028
SETUP-REC 000011W
Cobol Xref v2.02.03 Dictionary File for PROG 25/11/2021 15:22:00:04 Page 3
Symbols of Module: PROG (PROG)
------------------------------
Procedure Defn Locations
-------------------------------+---------------------------------------------
None
Compilation Time Environment Variables
The following are the various environment variables that can play a role in the compilation of GnuCOBOL programs.
COB_CC-
Set to the name of the C compiler you wish GnuCOBOL to use.
Use this feature at your own risk – you should always use the c compiler your gnucobol build was generated for.
COB_CFLAGS-
Set to any switches that you’d like to pass on to the C compiler from the
cobccompiler (in addition to any thatcobcwill specify). COB_CONFIG_DIR-
Set to the path to the folder where GnuCOBOL config files are kept.
COB_COPY_DIR-
If copybooks your program needs are not stored in the same directory as your program, set this environment variable to the folder in which the copybooks may be found (IBM mainframe programmers will recognize this as
SYSLIB). COB_LDADD-
Set to any additional linker switches (
ld) that can specify where standard libraries that must be linked with the program can be found. The default is "" (empty). COB_LDFLAGS-
Set to any linker (
ld) switches that you’d like to pass on to the C compiler from thecobccompiler (in addition to any that cobc will specify). COB_LIBS-
Set to any linker switches (
ld) that specify where standard libraries that must be linked with the program can be found. COBCPY-
This environment variable provides an additional means of specifying where copybooks may be found by the compiler (see also COB_COPY_DIR, above).
LD_LIBRARY_PATH-
If you are planning on using static-linked subroutine libraries, set this variable to the path of the directory containing your libraries.
TMPDIR;TMP-
Set to a directory/folder appropriate to create temporary files in. The intermediate working files created by the compiler will be created here (and deleted once they’re no longer needed).
The variable
TMPDIRis checked for a valid path first; if that isn’t set, thenTMPis checked.On a Windows system, the
TMPenvironment variable is normally set for you when you logon. If you wish to use a different temporary folder, you may setTMPDIRyourself and have no fear of disrupting other Windows software that relies on TMP.
Predefined Compilation Variables
GnuCOBOL defines compilation variables when certain conditions are true.
If the condition associated with a variable is false, the variable is not defined during compilations.
DEBUG-
The
-ddebug flag is specified. EXECUTABLE-
The module being compiled contains the main program.
GCCOMP-
The size of a
COMPitem is determined according to the GnuCOBOL scheme, where for aPICTUREof length:- 1-2
-
item has 1 byte
- 3-4
-
item has 2 bytes
- 5-9
-
item has 4 bytes
- 10-18
-
item has 8 bytes.
HOSTSIGNS-
A signed packed-decimal item’s value may be considered
NUMERICif the sign has valueX"F". IBMCOMP-
The size of a
COMPitem is determined according to the IBM scheme, where for aPICTUREof length:- 1-4
-
item has 2 bytes
- 5-9
-
item has 4 bytes
- 10-18
-
item has 8 bytes.
MODULE-
The module being compiled does not contain the main program.
NOHOSTSIGNS-
A signed packed-decimal item’s value may not be considered
NUMERIC-
if the sign has value
X"F". NOIBMCOMP-
The size of a
COMPitem is not determined according to the IBM scheme. NOSTICKYLINKAGE-
Sticky-linkage (linkage-section items remaining allocated between invocations) is not enabled.
NOTRUNC-
Numeric data items are truncated according to their internal representation.
P64-
Pointers are greater than 32 bits long
STICKY-LINKAGE-
Sticky-linkage (linkage-section items remaining allocated between invocations) is enabled.
TRUNC-
Numeric data items are truncated according to their
PICTUREclauses.While still supported, this may well be removed in the future and should not be used. See
GCCOMPandGNUCOBOLinstead: OCCOMP-
The size of a
COMP<item> is determined according to the GnuCOBOL scheme, where for aPICTUREof length:- 1 - 2
-
<item> = 1 byte
- 3 - 4
-
<item> = 2 bytes
- 5 - 9
-
<item> = 4 bytes
- 10 - 18
-
<item> = 8 bytes
Locating Copybooks
The GnuCOBOL compiler will attempt to locate copybooks by searching for them in the following folders. The search will occur in the sequence shown below, and will terminate once a copybook is found.
The folder named as the <library-name-1> on the
COPYstatement (see COPY).The folder in which the program being compiled resides.
The folder named on the
-Iswitch.Each of the folders named on the
COB_CPY_DIRcompilation-time environment variable (see Compilation Time Environment Variables) in order of presentation.Each of the folders named on the
COBCPYcompilation-time environment variable (see Compilation Time Environment Variables) in order of presentation.A single folder may be named or multiple folders may be specified, separated by a system-appropriate delimiter character. When multiple folders are specified, they will be searched in the order they are named on the environment variable.
If the GnuCOBOL compiler you are using was built to utilize a native Windows environment, use a semicolon (‘
;’) as the delimiter character.If, however, the GnuCOBOL compiler was built for a Unix, OSX or Linux environment, or was built for a Windows environment utilizing either the Cygwin or MinGW Unix emulators, use a colon character (‘
:’) as the delimiter.For v1.1 only, the single folder specified on the COB_COPY_DIR environment variable. (If not defined, for order see results of ‘cobc –info’).
The search order is as specified in the copy/include statement, then as specified via -ext, then the defaults that follows below.
As each of the above folders is searched for a copybook — COPY XXXXXXXX., for example — the GnuCOBOL compiler will attempt to locate the copybook file by any of the following names, in the sequence shown:
XXXXXXXX.CPYXXXXXXXX.CBLXXXXXXXX.COBXXXXXXXX.cpyXXXXXXXX.cblXXXXXXXX.cobXXXXXXXX
The COPY statement is case-sensitive on UNIX systems; COPY copybookname and COPY COPYBOOKNAME will both fail to locate the CopyBookName copybook on a UNIX system.
Windows implementations of GnuCOBOL may, or may not, be similarly case sensitive with regard to copybook names, depending upon the Windows version and GnuCOBOL build options — it is safest to simply treat the COPY command as case-sensitive in all environments.
It is possible, however, to automatically cause all COPY statements to “fold” the names of all copybooks to upper-case by specifying the -ffold-copy switch with the upper option (i.e. --fold-copy=upper) to the GnuCOBOL compiler. Similarly, names could be folded to lower-case by using the lower option (i.e. --fold-copy=lower. If copybook libraries are maintained entirely using upper- or lower-case file names and extensions, either of these options will allow copybooks to be found regardless of how the programmer entered their names on COPY statements.
Case-folding may also be turned on and off within the program source code using the CDF >>SET statement (see >>SET).
Compiler Configuration Files
GnuCOBOL uses compiler configuration files to define various options that will control the compilation process. These configuration files are specified using the -conf switch compilation switch and are found in the folder defined by the COB_CONFIG_DIR compilation-time environment variable (see Compilation Time Environment Variables).
If this is not defined under *nix it will default to /usr/local/share/gnucobol/config.
The following is a verbatim listing of the default configuration file (the one used if you don’t specify the -conf switch), just to show you the types of settings that may appear and taken from v3.1.2 :
# Value: any string
name: "GnuCOBOL"
# Value: enum
standard-define 0
# NOTE: see enum cb_std_def, defined in cobc/cobc.h.
# CB_STD_GC = 0,
# CB_STD_MF,
# CB_STD_IBM,
# CB_STD_MVS,
# CB_STD_BS2000,
# CB_STD_ACU,
# CB_STD_RM,
# CB_STD_85,
# CB_STD_2002,
# CB_STD_2014
# Default source reference-format; values: FIXED, FREE, COBOL85,
# VARIABLE, XOPEN, XCARD, CRT, TERMINAL, COBOLX
format: auto
# Value: int
tab-width: 8
text-column: 72
# Maximum word-length for COBOL words / Programmer defined words
# Be aware that GC checks the word length against COB_MAX_WORDLEN
# first (currently 63)
word-length: 63
# Maximum literal size in general
literal-length: 8191
# Maximum numeric literal size (absolute maximum: 38)
numeric-literal-length: 38
# Maximum number of characters allowed in the character-string (max. 255)
pic-length: 255
# Enable AREACHECK by default, for reference formats other than {fixed,free}
areacheck: no
# Default assign type
# Value: 'dynamic', 'external'
assign-clause: dynamic
# If yes, file names are resolved at run time using
# environment variables.
# For example, given ASSIGN TO "DATAFILE", the file name will be
# 1. the value of environment variable 'DD_DATAFILE' or
# 2. the value of environment variable 'dd_DATAFILE' or
# 3. the value of environment variable 'DATAFILE' or
# 4. the literal "DATAFILE"
# If no, the value of the assign clause is the file name.
#
filename-mapping: yes
# Alternate formatting of numeric fields
pretty-display: yes
# Allow complex OCCURS DEPENDING ON
complex-odo: no
# Adjust position of items following OCCURS DEPENDING
odoslide: no
# Do ISAM indexes with DUPLICATES get compressed
keycompress: 0
# Allow REDEFINES to other than last equal level number
indirect-redefines: no
# Binary byte size - defines the allocated bytes according to PIC
# Value: signed unsigned bytes
# ------ -------- -----
# '2-4-8' 1 - 4 same 2
# 5 - 9 same 4
# 10 - 18 same 8
#
# '1-2-4-8' 1 - 2 same 1
# 3 - 4 same 2
# 5 - 9 same 4
# 10 - 18 same 8
#
# '1--8' 1 - 2 1 - 2 1
# 3 - 4 3 - 4 2
# 5 - 6 5 - 7 3
# 7 - 9 8 - 9 4
# 10 - 11 10 - 12 5
# 12 - 14 13 - 14 6
# 15 - 16 15 - 16 7
# 17 - 18 17 - 18 8
#
binary-size: 1-2-4-8
# Numeric truncation according to ANSI
binary-truncate: yes
# Binary byte order
# Value: 'native', 'big-endian'
binary-byteorder: big-endian
# Allow larger REDEFINES items other than 01 non-external
larger-redefines: error
# Allow certain syntax variations (eg. REDEFINES position)
relax-syntax-checks: no
# Allow zero length reference-modification
# (only checked with active EC-BOUND-REF-MOD)
ref-mod-zero-length: yes
# Perform type OSVS - If yes, the exit point of any currently
# executing perform is recognized if reached.
perform-osvs: no
# Compute intermediate decimal results like IBM OSVS
arithmetic-osvs: no
# MOVE like IBM (mvc); left to right, byte by byte
move-ibm: no
# LOCAL-STORAGE SECTION implies RECURSIVE attribute
local-implies-recursive: no
# If yes, LINKAGE SECTION items remain allocated
# between invocations.
sticky-linkage: no
# If yes, allow non-matching level numbers
relax-level-hierarchy: no
# If yes, evaluate constant expressions at compile time
constant-folding: yes
# Allow Hex 'F' for NUMERIC test of signed PACKED DECIMAL field
hostsign: no
# If yes, set WITH UPDATE clause as default for ACCEPT dest-item,
# except if WITH NO UPDATE clause is used
accept-update: no
# If yes, set WITH AUTO clause as default for ACCEPT dest-item,
# except if WITH TAB clause is used
accept-auto: no
# If yes, DISPLAYs and ACCEPTs are, by default, done on the CRT (i.e., using
# curses).
console-is-crt: no
# If yes, allow redefinition of the current program's name. This prevents its
# use in a prototype-format CALL/CANCEL statement.
program-name-redefinition: yes
# If yes, NO ECHO/NO-ECHO/OFF is the same as SECURE (hiding input with
# asterisks, not spaces).
no-echo-means-secure: no
# If yes, the first item in a field screen ACCEPT/DISPLAY (e.g. DISPLAY x UPON
# CRT) is located after the previous ACCEPT/DISPLAY (as though LINE 0 COL 0 had
# been specified).
line-col-zero-default: yes
# If yes, then REPORT, COLUMN may have any of PLUS num, + num, or +num
# to define a relative column position
# If no, then COLUMN +num is not accepted due to signed numeric
report-column-plus: yes
# If yes, DISPLAY SPACES acts as ERASE EOS, DISPLAY X"01" acts as ERASE EOL,
# DISPLAY X"02" acts as BLANK SCREEEN and DISPLAY X"07" acts as BELL. Note
# DISPLAY LOW-VALUE is excluded from this; it will always just position the
# cursor.
display-special-fig-consts: no
# If yes, COMP-1 is a signed 16-bit integer and any PICTURE clause is ignored.
binary-comp-1: no
# If yes, POINTER is handled as BINARY-DOUBLE UNSIGNED instead of its own class
numeric-pointer: no
# auto-adjust to zero like MicroFocus does
move-non-numeric-lit-to-numeric-is-zero: no
# If yes, implicitly define a variable for an ASSIGN DYNAMIC which does not
# match an existing data item.
implicit-assign-dynamic-var: yes
# If yes, ACCEPT and DISPLAY statements accept device names using mnemonics
device-mnemonics: no
# full clauses in XML PARSE - and adjusted XML-EVENTs
xml-parse-xmlss: yes
# What rules to apply to SCREEN SECTION items clauses
screen-section-rules: gc
# Whether DECIMAL-POINT IS COMMA has effect in XML/JSON GENERATE
dpc-in-data: xml
# Functionality of JUSTIFY for INITIALIZE verb and initialization of storage
init-justify: no
# Dialect features
# Value: 'ok', 'warning', 'archaic', 'obsolete', 'skip', 'ignore', 'error',
# 'unconformable'
alter-statement: obsolete
comment-paragraphs: obsolete
control-division: unconformable
partial-replace-when-literal-src: obsolete
call-overflow: archaic
data-records-clause: obsolete
debugging-mode: ok
use-for-debugging: ok
listing-statements: skip # may be a user-defined word
title-statement: skip # may be a user-defined word
entry-statement: ok
goto-statement-without-name: obsolete
label-records-clause: obsolete
memory-size-clause: obsolete
move-noninteger-to-alphanumeric: error
move-figurative-constant-to-numeric: archaic
move-figurative-space-to-numeric: error
move-figurative-quote-to-numeric: obsolete
multiple-file-tape-clause: obsolete
next-sentence-phrase: archaic
odo-without-to: warning
odo-last-varlen: ok
padding-character-clause: obsolete
occurs-max-length-without-subscript: no
section-segments: ignore
stop-literal-statement: obsolete
stop-identifier-statement: obsolete
stop-error-statement: unconformable
same-as-clause: ok
type-to-clause: ok
usage-type: ok
synchronized-clause: ok
sync-left-right: ok
special-names-clause: ok
top-level-occurs-clause: ok
value-of-clause: obsolete
numeric-boolean: ok
hexadecimal-boolean: ok
national-literals: ok
hexadecimal-national-literals: ok
national-character-literals: warning
# TO-DO: Add separate config option for H"..." to be unsupported,numeric,non-numeric(acu)
acu-literals: unconformable
hp-octal-literals: unconformable
ebcdic-symbolic-characters: no
word-continuation: warning
length-in-data-division: yes
depending-on-not-fixed: warning
not-exception-before-exception: ok
accept-display-extensions: ok
renames-uncommon-levels: ok
symbolic-constant: ok
constant-78: ok
constant-01: ok
perform-varying-without-by: ok
reference-out-of-declaratives: warning
# Is reference modification required to be within the single field
reference-bounds-check: warning
program-prototypes: ok
call-convention-mnemonic: ok
call-convention-linkage: ok
numeric-value-for-edited-item: ok
incorrect-conf-sec-order: ok
define-constant-directive: archaic
free-redefines-position: warning
records-mismatch-record-clause: warning
record-delimiter: ok
sequential-delimiters: ok
record-delim-with-fixed-recs: ok
record-sequential-advancing: warning
missing-statement: warning
missing-period: warning # when format not in {fixed,free}
zero-length-literals: ok
xml-generate-extra-phrases: ok
continue-after: ok
goto-entry: warning
binary-sync-clause: ignore
nonnumeric-with-numeric-group-usage: ok
assign-variable: ok
assign-using-variable: ok
assign-ext-dyn: ok
assign-disk-from: ok
vsam-status: ignore
self-call-recursive: skip
record-contains-depending-clause: unconformable
align-record: 0
align-opt: no
defaultbyte: init # GC inits as INITIALIZE ALL TO VALUE THEN TO DEFAULT,
# with INDEXED BY variables initialized to 1
picture-l: ok
# use complete word list; synonyms and exceptions are specified below
reserved-words: default
# not-reserved:
# Value: Word to be taken out of the reserved words list
not-reserved: TERMINAL
#not-reserved: TRANSACTION
not-reserved: EXAMINE
# reserved:
# Entries of the form word-1=word-2 define word-1 as an alias for default
# reserved word word-2. No spaces are allowed around the equal sign.
reserved: AUTO-SKIP=AUTO
reserved: AUTOTERMINATE=AUTO
reserved: BACKGROUND-COLOUR=BACKGROUND-COLOR
reserved: BEEP=BELL
reserved: BINARY-INT=BINARY-LONG
reserved: BINARY-LONG-LONG=BINARY-DOUBLE
reserved: CELLS=CELL
reserved: COLOURS=COLORS
reserved: EMPTY-CHECK=REQUIRED
reserved: EQUALS=EQUAL
reserved: FOREGROUND-COLOUR=FOREGROUND-COLOR
reserved: HIGH-VALUES=HIGH-VALUE
reserved: INITIALISE=INITIALIZE
reserved: INITIALISED=INITIALIZED
reserved: LENGTH-CHECK=FULL
reserved: LOW-VALUES=LOW-VALUE
reserved: ORGANISATION=ORGANIZATION
reserved: PIXELS=PIXEL
reserved: SYNCHRONISED=SYNCHRONIZED
reserved: TIMEOUT=TIME-OUT
reserved: ZEROES=ZERO
reserved: ZEROS=ZERO
Running Programs
Once GnuCOBOL programs have been compiled into either directly-executable programs (created via the -x switch) or dynamically-loadable libraries (created via the -m switch), those programs may be executed from any shell environment. The exact manner in which the two are executed will differ, as described in the upcoming sections.
Direct Execution
GnuCOBOL programs compiled with the -x switch will be generated as directly-executable programs. For example, a native Windows or Windows/MinGW build of GnuCOBOL will generate an .exe file when the -x switch switch is specified to the compiler.
On Unix, OSX, or Windows/Cygwin builds, the -x switch switch will generate an executable binary file, usually with no particular extension unless one is explicitly requested of the compiler via the -o switch.
On a UNIX system this means the programs may be executed from a command shell such as bash, csh, ksh and so forth. When a GnuCOBOL program runs on a Windows system, it runs within a console window (i.e. cmd.exe). OSX versions of GnuCOBOL programs run within a terminal.app window.
Interactions between the program and the user will take place using the standard input, standard output and standard error streams. Any screen section I/O performed by the program will take place within the terminal window.
Direct program execution syntax is [path]program [arguments].
For example:
/usr/local/printaccount ACCT=6625378
or
C:\\Users\\Me\\Documents\\Programs\\printaccount.exe ACCT=6625378
Executing Dynamically-Loadable Libraries
As discussed previously, dynamically-loadable libraries are created via the compiler’s -m switch. Once so created, the program(s) in these libraries are executed from the command line (via the GnuCOBOL cobcrun utility), or as dynamically-loadable subprograms.
cobcrun - Command-line Execution
It is possible to generate executable modules for all GnuCOBOL programs, not just subprograms, by choosing to use the -m switch option to specify the loader output format, even for main programs.
Some may prefer to compile their GnuCOBOL main programs into these dynamically-loadable modules in the interests of using the same general compilation command for all programs without having to think “Is it a main program or a subprogram?”.
Main programs compiled in this manner should be executed as follows:
[path]cobcrun program [arguments]
Do not specify the .so or .dll extension on the program name. The program value must exactly match the primary entry-point name of the main program (including upper- and lower-case letters), unless you are planning on using Call Folding (see Dynamically Loaded Subprograms).
The general usage and syntax of cobcrun is as follows as issued by running cobcrun -h (or –help) :
GnuCOBOL module loader
Usage: cobcrun [options] PROGRAM [parameter ...]
or: cobcrun options
Options:
-h, -help display this help and exit
-V, -version display cobcrun and runtime version and exit
-i, -info display runtime information (build/environment)
-v, -verbose display extended output with --info
-c <file>, -config=<file> set runtime configuration from <file>
-r, -runtime-config display current runtime configuration
(value and origin for all settings)
-M <module>, -module=<module> set entry point module name and/or load path
where -M module prepends any directory to the
dynamic link loader library search path
and any basename to the module preload list
(COB_LIBRARY_PATH and/or COB_PRELOAD)
Here are two examples of using cobcrun. First, on a Unix, OSX or Windows/Cygwin system:
cd /usr/local
cobcrun printaccount acct=6625378
Or, on a Native Windows or Windows/MinGW system:
cd C:\Users\Me\Documents\Programs
cobcrun printaccount.exe acct=6625378
Note how the cobcrun command does not allow a path to be specified with the program name — the directory in which the programs dynamically loadable module exists must either be the current directory or must be defined in the current PATH.
Dynamically Loaded Subprograms
Dynamically-loaded subprograms are executed (from a COBOL syntax point of view) just like any other subprograms. What makes them unique, however, is that they are loaded into memory only when they are actually used the first time during the execution of a program.
When a dynamically-loadable module needs to be loaded (because it is not already in memory from a previous subprogram execution), the dynamically-loadable library will be sought by libcob in each directory named in the library specified by the COB_LIBRARY_PATH run-time environment variable will be searched and if not found then. Finally, if it still cannot be located, execution will be terminated with an error message (libcob: Cannot find module ‘xxxxxxxx’). For speed performance purposes all such should therefore be stored within the directories pointed to by the environment variable COB_LIBRARY_PATH run-time environment variable.
The process of locating dynamically-loadable modules is case sensitive on UNIX systems; CALL "dynsub" and CALL "DYNSUB" will both fail to locate the DynSub.so library on a UNIX system.
Windows implementations of GnuCOBOL may, or may not, be similarly case sensitive with regard to library names, depending upon the Windows version and GnuCOBOL build options — it is safest to simply treat library names as case sensitive in all environments.
It is possible, however, to automatically cause all library names to ‘fold’ to upper-case by specifying the -ffold-call switch with the “upper” option (i.e. --fold-call=upper) to the GnuCOBOL compiler. Similarly, library names could be folded to lower-case by using the “lower” option (i.e. --fold-call=lower. If libraries are maintained entirely using upper- or lower-case file names, either of these options will allow libraries to be found regardless of how the programmer entered their names on CALL statements.
See Sub-Programming, for a complete discussion of sub-programming.
Run Time Environment Variables
The following is a list of the various environment variables that can play a role in the execution of GnuCOBOL programs.
COB_DISPLAY_WARNINGS-
If set to a value of ‘
Y’, any run-time warnings (such as noting the implicit closing of open files when aGOBACKstatement (see GOBACK) orSTOPstatement (see STOP) with theRUNoption is executed) will be displayed. Any other value for this environment variable (including not setting the variable at all) will suppress such messages. COB_LIBRARY_PATH-
At runtime, GnuCOBOL will attempt to locate and load any application dynamically loadable libraries used this variable that points to the directories specified, if it wasn’t found there, using the
PATHenvironment variable. COB_LOAD_CASE-
If set to either
UPPERorLOWER, this environment variable will internally convert referenced entry point names to either upper- or lower-case before initiating searches for dynamically loadable modules. TheUPPERandLOWERvalues of the environment variable are actually case insensitive. COB_PHYSICAL_CANCEL-
If set to ‘
Y’, ‘y’ or ‘1’, aCANCELstatement (see CANCEL) will physically unload a subprogram dynamically loadable module. If set to anything else, aCANCELstatement (see CANCEL) logically unloads a module so that subsequent use will re-initialize the module as if it had actually been reloaded, but the overhead of actually reloading the module will be avoided. COB_PRE_LOAD-
If set to any non-null value, this variable will cause all dynamically loadable libraries to be loaded when the program begins execution (rather than searching for and loading the module upon first use).
COB_SET_DEBUG-
If a
USE FOR DEBUGGING(see DECLARATIVES) section exists, the code within it will be disabled unless this environment variable is set to a value of ‘Y’, ‘y’ or ‘1’. COB_SET_TRACE-
If the
-ftraceswitch (trace procedures) or-ftraceallswitch (trace procedures and statements) was used when the program was compiled, setting this environment variable to a value of ‘Y’ will activate the trace at the point the program begins execution. Setting this environment variable to any other value (or never setting it to ANY value) will disable tracing. Tracing, if configured by one of the two switches described above, can also be controlled via the theREADY TRACEstatement (see READY TRACE) andRESET TRACEstatement (see RESET TRACE). If COB_SET_TRACE is set to Y, then tracing will always occur regardless of the presence of READY TRACE or RESET TRACE so in effect they will have no action on program execution. COB_SCREEN_ESC-
If set to any non-blank value, this variable allows a
ACCEPT data-itemstatement (see ACCEPT data-item) to detect theEsckey. COB_SCREEN_EXCEPTIONS-
Setting this variable to any non-blank value will allow the
ACCEPT data-itemstatement (see ACCEPT data-item) to detect the pressing of theEsc,PgUpandPgDnkeys. COB_SORT_MEMORY-
The value of this variable (an integer) will be used to define how much memory will be allocated for use in sorting. If the value is 1048576 or greater, that value will be used “as is” as the amount of memory (in bytes) to allocate. If the value is less than 1048576, the value will specify how many MB of memory will be allocated. The default sort memory amount is 128 MB.
COB_SWITCH_n-
(n=0 to 15); These environment variables correspond to
SWITCH-0throughSWITCH-15, defined in theSPECIAL-NAMES(see SPECIAL-NAMES) paragraph. Setting them toONwill activate them; any other value turns them off. COB_SYNC-
If set to a value of upper- or lower-case ‘
p’, this variable will force a file commit every time a file is written to (ensuring that data is immediately written to the file rather than retained in memory until a future commit occurs). This will slow-down update access to files, but will provide for better integrity in the event of a program failure. COB_TRACE_FILE-
If set to any non-null value, this environment variable specifies the file to which all
-ftraceswitch and-ftraceallswitch output will be written. If this is NOT set to a value, all-ftraceswitch and-ftraceallswitch output will be written to STDERR, where it may be piped via a "2> filename" on the command that executes the program. DB_HOME-
If your GnuCOBOL build uses the Berkeley Database (BDB) package, use this environment variable to specify the folder in which the lock management files to be associated with all non-SORT files opened by the program will be stored.
ORGANIZATION INDEXED(see ORGANIZATION INDEXED) files will also have their data file allocated in the folder pointed to by this environment variable, if it exists.. Having this variable defined will activate record locking features on theREADstatement (see READ),REWRITEstatement (see REWRITE) andWRITEstatement (see WRITE). Even with DB_HOME, locking will not work withORGANIZATION SEQUENTIAL(see ORGANIZATION SEQUENTIAL),ORGANIZATION LINE SEQUENTIAL(see ORGANIZATION LINE SEQUENTIAL) or ORGANIZATION RELATIVE files with GnuCOBOL builds created for Windows/MinGW.ORGANIZATION INDEXEDlocks will work with Windows/MinGW + BDB and all locks will work for all file organizations with UNIX GnuCOBOL builds. OS-
Use this environment variable to retrieve the value of the Operating System in which the program is running.
The statement ACCEPT identifier-1 FROM ENVIRONMENT "OS" returns the value "Windows_NT" if the program is running in a WINDOWS 10 environment. PATH-
The GnuCOBOL "bin" directory should be defined in the PATH.
TMPDIR;TMP;TEMP-
One of these environment variables must be set to a directory/folder appropriate to create temporary files in. They will be checked in the order shown. This will be used by the
SORTstatement (see SORT) andMERGEstatement (see MERGE) to create temporary work files. You may also use this folder for any temporary files your application may require.
Also used during execution of programs is runtime.cfg also found in /usr/local/share/gnucobol/config for *nix and this file can also be changed to match your environment if needed. When viewing, note the Default settings.
General instructions
#
## General instructions
#
# The initial runtime.cfg file is found in the $COB_CONFIG_DIR ,
# which defaults to installdir/gnucobol/config (see cobcrun --info for the
# local path that is configured).
# The environment variable COB_RUNTIME_CONFIG may define a different runtime
# configuration file to read.
# If settings are included in the runtime environment file multiple times
# then the last setting value is used, no warning occurs.
# Settings via environment variables always take precedence over settings
# that are given in runtime configuration files. And the environment is
# checked after completing processing of the runtime configuration file(s)
# All values set to string variables or environment variables are checked
# for ${envvar} and replacement is done at the time of the setting.
# You can also specify a default value for the case that envvar is not set:
# ${envvar:default} (the format ${envvar:-default} is supported, too).
# Any environment variable may be set with the directive setenv .
# Example: setenv COB_LIBARAY_PATH ${LD_LIBRARY_PATH}
# Any environment variable may be unset with the directive unsetenv
# (one var per line).
# Example: unsetenv COB_LIBRARY_PATH
# Runtime configuration files can include other files with the
# directive include .
# Example: include my-runtime-configuration-file
# To include another configuration file only if it is present use the
# directive includeif .
# You can also use ${envvar} inside this.
# Example: includeif ${HOME}/mygc.cfg
# If you want to reset a parameter to its default value use
# reset parametername .
# Most runtime variables have boolean values, some are switches, some have
# string values, integer values (if not explicit noted: unsigned) and some
# are size values.
# The boolean values will be evaluated as following:
# to true: 1, Y, ON, YES, TRUE (no matter of case)
# to false: 0, N, OFF
# A 'size' value is an unsigned integer optionally followed by K, M, or G
# for kilo, mega or giga.
# Variables of type string can be of three different kinds:
# regular string, file name, and path list
# All those may contain the following escape sequences:
# $$ process id
# $f executable filename (full path)
# $b executable basename (anything after the last separator)
# $d date (yyyymmdd)
# $t time (hhmmss)
# For convenience a parameter in the runtime.cfg file may be defined by using
# either the environment variable name or the parameter name.
# In most cases the environment variable name is the parameter name (in upper
# case) with the prefix COB_ .
# For a complete list of the settings in use see cobcrun --runtime-config .
# Note:
# If you want to *slightly* speed up a program's startup time, remove all
# of the comments from the actual real configuration file that is processed.
General Environment
#
## General environment
#
# Environment name: COB_DISABLE_WARNINGS
# Parameter name: disable_warnings
# Purpose: turn off runtime warning messages
# Type: boolean
# Default: false
# Example: DISABLE_WARNINGS TRUE
# Environment name: COB_ENV_MANGLE
# Parameter name: env_mangle
# Purpose: names checked in the environment would get non alphanumeric
# change to '_'
# Type: boolean
# Default: false
# Example: ENV_MANGLE TRUE
# Environment name: COB_SET_DEBUG
# Parameter name: debugging_mode
# Purpose: to enable USE ON DEBUGGING procedures that were active
# during compile-time because of WITH DEBUGGING MODE,
# otherwise the code generated will be skipped
# Type: boolean
# Default: false
# Example: COB_SET_DEBUG 1
# Environment name: COB_SET_TRACE
# Parameter name: set_trace
# Purpose: to enable COBOL trace feature
# Type: boolean
# Default: false
# Example: SET_TRACE TRUE
# Environment name: COB_TRACE_FILE
# Parameter name: trace_file
# Purpose: to define where COBOL trace output should go
# Type: string (file) ; may use $-sequences
# Note: file is opened for append if name starts with "+"
# Default: stderr
# Example: TRACE_FILE ${HOME}/mytrace.$$
# Environment name: COB_TRACE_FORMAT
# Parameter name: trace_format
# Purpose: to define format of COBOL trace output
# Type: string
# Default: "%P %S Line: %L"
# %P is replaced by Program-Id/Function-Id minimal length 29
# with prefix
# %I is replaced by Program-Id/Function-Id variable length,
# without prefix
# %L is replaced by Line number, right justified, length 6
# %S is replaced by statement type and name
# %F is replaced by source file name
# Example: TRACE_FORMAT "Line: %L %S"
# Note: format of GC2.2 and older:
# "PROGRAM-ID: %I Line: %L %S"
# Environment name: COB_TRACE_IO
# Parameter name: trace_io
# Purpose: define if I/O details should be added to trace
# Type: boolean
# Default: false
# Example: TRACE_IO true
# Environment name: COB_CORE_ON_ERROR
# Parameter name: core_on_error
# Purpose: to enable operating system handling of signals and to
# raise an ABORT signal on runtime error instead of the
# default error handling, which will commonly kill the
# process after creating a coredump
# Type: 0 means catching all default signals and do full
# internal error handling as done in versions pre 3.2
# along with full internal handling of COBOL runtime
# errors
# 1 means to forward any signals; whatever happens
# by means of system signal handers will happen,
# which may include creating coredumps and killing
# the process before libcob does any cleanup; preserve
# full internal handling of COBOL runtime errors
# 2 is identical to 1, but on runtime errors explicit
# raises SIGABRT after displaying it along with the
# stacktrace and after doing minimal cleanup
# 3 similar to 2, but instead of raising SIGABRT execute
# "gcore -a -o NAME $$" (where $$ is the process id and
# NAME is specified by COB_CORE_FILENAME) as early as
# possible before doing the normal internal error
# handling; if the command does not work or if a signal
# handler was executed before a SIGABRT is raised
# Default: 0
# Example: core_on_error 3
# Note: If the operating system kills the process as part of the
# signal handling no COBOL centric dump will be created and
# no cleanup will be done either.
# When catching a signal (for example 11) it will be
# returned as exit code of the process, the generated
# coredumps store the reason for the error in the variable
# "runtime_err_str".
# Environment name: COB_CORE_FILENAME
# Parameter name: core_filename
# Purpose: to adjust the default name or specify a folder for a
# COB_CORE_ON_ERROR=3 generated coredump
# Type: string
# Default: ./core.libcob
# Example: core_filename /home/me/SomeApp.core
# Environment name: COB_STACKTRACE
# Parameter name: stracktrace
# Purpose: to disable stracktrace creation on abort
# Type: boolean
# Default: true
# Example: STRACKTRACE no
# Environment name: COB_DUMP_FILE
# Parameter name: dump_file
# Purpose: to define where COBOL dump output should go
# Note: the -fdump=all compile option prepares for dump;
# file is opened for append if name starts with "+";
# may be disabled by setting it to "NONE"
# Type: string (file) ; may use $-sequences
# Default: stderr
# Example: DUMP_FILE ${HOME}/mytrace.log
# Environment name: COB_DUMP_WIDTH
# Parameter name: dump_width
# Purpose: to define COBOL dump line length
# Type: integer
# Default: 100
# Example: dump_width 120
# Environment name: COB_STATS_RECORD
# Parameter name: stats_record
# Purpose: define if I/O statistics should be written
# Type: boolean
# Default: false
# Example: STATS_RECORD true
# Environment name: COB_STATS_FILE
# Parameter name: stats_file
# Purpose: to define where COBOL I/O statistics should be written
# The file is appended to
# Type: string
# Default: stderr
# Example: STATS_FILE ${HOME}/mystats.txt
# Environment name: COB_CURRENT_DATE
# Parameter name: current_date
# Purpose: specify an alternate Date/Time to be returned to ACCEPT
# statement; this is used for testing purposes or to tweak
# a missing offset, partial setting is allowed
# Type: numeric string in format YYYYDDMMHHMISS or date string
# or seconds since the epoch as @SSSSSSSS
# Default: the operating system date is used
# Example: COB_CURRENT_DATE "2026/03/16 16:40:52"
# current_date YYYYMMDDHHMMSS+01:00
# Environment name: COB_PROF_FILE
# Parameter name: prof_file
# Purpose: to define where COBOL profiling output should go
# Type: string (file) ; may use $-sequences
# Default: cob-prof-$b-$$-$d-$t.csv
# Example: PROF_FILE ${HOME}/$$-prof.csv
# Environment name: COB_PROF_ENABLE
# Parameter name: prof_enable
# Purpose: to enable profiling for modules compiled with profiling;
# note that this disables physical cancel
# Type: boolean
# Default: false
# Example: PROF_ENABLE yes
# Environment name: COB_PROF_MAX_DEPTH
# Parameter name: prof_max_depth
# Purpose: the number of sections and paragraphs that can be nested;
# if the nesting level is higher than this threshold,
# profiling is disabled automatically
# Type: integer
# Default: 8192
# Example: PROF_MAX_DEPTH 8192
# Environment name: COB_PROF_FORMAT
# Parameter name: prof_format
# Purpose: to define the format of the columns in the profiling CSV file.
# Type: string a comma separated list of fields, with %m for module,
# %s for section, %p for paragraph, %e for entry, %w for
# location, %k for kind (PROGRAM,SECTION,PARAGRAPH,ENTRY)
# %f for file, %i for PID, %t for time in nano-seconds,
# %h for human-readable time, %n for number of calls
# Default: %m,%s,%p,%e,%w,%k,%t,%h,%n
# Example: COB_PROF_FORMAT %m,%s,%p,%e,%w,%k,%t,%h,%n
Call Environment
#
## Call environment
#
# Environment name: COB_LIBRARY_PATH
# Parameter name: library_path
# Purpose: paths for dynamically-loadable modules
# Type: string (path list)
# Note: the default paths .:/installpath/extras are always
# added to the given paths
# Example: LIBRARY_PATH /opt/myapp/test:/opt/myapp/production
# Environment name: COB_PRE_LOAD
# Parameter name: pre_load
# Purpose: modules that are loaded during startup, can be used
# to CALL COBOL programs or C functions that are part
# of a module library
# Type: string
# Note: the modules listed should NOT include extensions, the
# runtime will use the right ones on the various platforms,
# COB_LIBRARY_PATH is used to locate the modules
# Example: PRE_LOAD COBOL_function_library:external_c_library
# Environment name: COB_LOAD_CASE
# Parameter name: load_case
# Purpose: resolve ALL called program names to UPPER or LOWER case
# Type: Only use UPPER or LOWER
# Default: if not set program names in CALL are case sensitive
# Example: LOAD_CASE UPPER
# Environment name: COB_PHYSICAL_CANCEL
# Parameter name: physical_cancel
# Purpose: physically unload a dynamically-loadable module on CANCEL,
# this frees some RAM and allows the change of modules during
# run-time but needs more time to resolve CALLs (both to
# active and not-active programs)
# Alias: default_cancel_mode, LOGICAL_CANCELS (0 = yes)
# Type: TRUE/YES/1 unload module on CANCEL
# FALSE/NO/0 unload module on STOP RUN only
# NEVER never unload module, only useful for profilers
# and tracing tools that do a post-mortem lookup
# of function address
# Default: false
# Example: PHYSICAL_CANCEL TRUE
File I/O
#
## File I/O
#
# Environment name: COB_VARSEQ_FORMAT
# Parameter name: varseq_format
# Purpose: declare format to be used for variable length sequential files
# Type: 0 means 2 byte record length (big-endian) plus 2 NULs precedes record
# 1 means 4 byte record length (big-endian) precedes record
# 2 means 4 byte record length (local machine int) precedes record
# 3 means 2 byte record length (local machine short) precedes record
# b32 means 'type 2' above but the 'int' is in Big-Endian format
# l32 means 'type 2' above but the 'int' is in Little-Endian format
# mf means create the file in Micro Focus compatible format
# Default: 0
# Example: VARSEQ_FORMAT 1
# Environment name: COB_VARREL_FORMAT
# Parameter name: varrel_format
# Purpose: declare format to be used for variable length relative files
# Type: gc means 'size_t' record length (local machine) precedes
# maximum length data record
# mf means file is in Micro Focus format
# b32 means Big-Endian 32-bit 'int' record length precedes data
# b64 means Big-Endian 64-bit 'int' record length precedes data
# l32 means Little-Endian 32-bit 'int' record length precedes data
# l64 means Little-Endian 64-bit 'int' record length precedes data
# Default: gc
# NOTE: 'gc' results in files which cannot be used if copied between
# machines of different hardware architecture
# Example: VARREL_FORMAT mf
# Environment name: COB_FIXREL_FORMAT
# Parameter name: fixrel_format
# Purpose: declare format to be used for fixed length relative
# files (different types and lengths preceding each record)
# Type: b32 means 4 byte record length (big-endian)
# l32 means 4 byte record length (little-endian)
# b64 means 8 byte record length (big-endian)
# l64 means 8 byte record length (little-endian)
# mf means Micro Focus default
# gc means 'size_t' with record length precedes data record
# Default: gc
# NOTE: 'gc' results in files which cannot be used if copied between
# machines of different hardware architecture
# Example: FIXREL_FORMAT B32
# Environment name: COB_FILE_PATH
# Parameter name: file_path
# Purpose: define default location(s) where data files are stored
# Type: file path directory list
# Default: . (current directory)
# Example: FILE_PATH ${HOME}/mydata
# Unix/Linux list: FILE_PATH ${HOME}/mydata:${PROJECT}/datafiles
# Windows list: FILE_PATH C:\proja\mydata;D:\projb\yourdata;.
# Environment name: COB_FILE_DICTIONARY
# Parameter name: file_dictionary
# Purpose: define when a file format description is written
# is written to 'asgname.dd'
# Type: false means never write
# no means never write
# true means write for BDB or LMDB only
# min means write for BDB or LMDB only
# always means write for all file types
# max means write for all file types
# Default: min
# Example: file_dictionary always
# Environment name: COB_FILE_DICTIONARY_PATH
# Parameter name: file_dictionary_path
# Purpose: define where the 'asgname.dd' is written
# Type: file path directory
# Default: . (current directory)
# Example: FILE_DICTIONARY_PATH ${HOME}/mystuff
# Environment name: COB_BDB_BYTEORDER
# Parameter name: bdb_byteorder
# Purpose: Defines the byte order to be used for BDB
# Type: native - use the system byte order
# big-endian - use big-endian order
# little-endian - use little-endian order
# Default: native
# Example: bdb_byteorder big-endian
# Environment name: COB_FILE_FORMAT
# Parameter name: file_format
# Purpose: Declares if all files in the program should be in
# Micro Focus compatible format or old GnuCOBOL 3 format.
# Type: mf means create files in Micro Focus compatible format
# gc means create files in old GnuCOBOL 3 format
# Default: GC (depends on compiler build --with-file-format= )
# Example: FILE_FORMAT = MF
# Environment name: COB_LS_FIXED
# Parameter name: ls_fixed
# Purpose: Defines if LINE SEQUENTIAL files should be fixed length
# (or variable, by removing trailing spaces)
# Alias: STRIP_TRAILING_SPACES (0 = yes)
# Type: boolean
# Default: false
# Note: This setting is most useful if you want to REWRITE those
# files.
# Example: LS_FIXED TRUE
# Environment name: COB_LS_VALIDATE
# Parameter name: ls_validate
# Purpose: Defines for LINE SEQUENTIAL files that the data should be
# validated as it is read (status 09) / written (status 71).
# Type: boolean
# Default: true (per COBOL 2022)
# Note: If active effectively disables COB_LS_NULLS.
# Example: LS_VALIDATE FALSE
# Environment name: COB_LS_NULLS
# Parameter name: ls_nulls
# Purpose: Defines for LINE SEQUENTIAL files what to do with data
# which is not DISPLAY type. This could happen if a LINE
# SEQUENTIAL record has BINARY/COMP data fields in it.
# This option is only for GnuCOBOL format files
# Type: boolean
# Default: true (for MF files) otherwise false
# Note: The TRUE setting will insert a null character x"00" before
# those values to escape them, and redo on read-in plus
# validating that they only occur after a null character.
# Decreases LINE SEQUENTIAL performance and prevents writing
# escape sequences or formatting within the data.
# Only checked if COB_LS_VALIDATE is disabled.
# Example: LS_NULLS = TRUE
# Environment name: COB_LS_SPLIT
# Parameter name: ls_split
# Purpose: Defines for LINE SEQUENTIAL files what to do when a record
# is longer than the program handles. If 'ls_split=true' then
# the data is returned as multiple records with io status 06,
# otherwise the record is truncated, io status set to 04 and
# the file skips to the next LF.
# Type: boolean
# Default: true (per COBOL 2022)
# Example: LS_SPLIT = FALSE
# Environment name: COB_LS_INSTAB
# Parameter name: ls_instab
# Purpose: Defines for LINE SEQUENTIAL files that multiple spaces
# should be replaced by a TAB character, assuming a 'tab set'
# value of 8. Each TAB means to skip to the next column that
# is a multiple of 8
# Similar to Micro Focus INSERTTAB=ON option
# Type: boolean
# Default: false
# Example: LS_INSTAB = TRUE
# Environment name: COB_SHARE_MODE
# Parameter name: share_mode
# Purpose: Defines what file sharing option should be used
# Type: -- choice of values ---
# none - nothing overrides application code
# read - files opened as SHARE READ ONLY
# all - files opened as SHARE ALL OTHERS
# no - files opened as SHARE NO OTHERS
# Default: none
# Example: share_mode = ALL
# Environment name: COB_RETRY_MODE
# Parameter name: retry_mode
# Purpose: Defines what I/O retry sharing option should be used
# Type: --- choice of values ---
# none - nothing overrides application code
# never - I/O is never retried
# forever - I/O will be retried until success
# Default: none
# Example: retry_mode = never
# Environment name: COB_RETRY_TIMES
# Parameter name: retry_times
# Purpose: Defines how many times I/O should be retried
# Type: integer
# Default: 0
# Example: retry_times = 10
# Environment name: COB_RETRY_SECONDS
# Parameter name: retry_seconds
# Purpose: Defines how many seconds I/O should be retried
# Type: integer
# Default: 0
# Example: retry_seconds = 6
# Environment name: COB_KEYCHECK
# Parameter name: keycheck
# Purpose: Must INDEXED file keys match COBOL SELECT exactly
# Type: boolean
# Default: true
# Example: keycheck = off
# Environment name: COB_DUPS_AHEAD
# Parameter name: dups_ahead
# Purpose: Should INDEXED file handler return status 02 for dups
# Type: -- choice of values ---
# default - yes, if the low level I/O routine handles it
# never - Even if 02 is return from xISAM, ignore it
# always - fisam/foci/fodbc should do extra work to compute
# Default: default
# Example: dups_ahead = never
# Environment name: COB_SYNC
# Parameter name: sync
# Purpose: Should the file be synced to disk after each write/update
# Type: boolean
# Default: false
# Example: SYNC: TRUE
# Environment name: COB_FILE_ROLLBACK
# Parameter name: rollback
# Purpose: Should file updates be recorded for later COMMIT/ROLLBACK
# Type: boolean
# Default: false
# Example: rollback=TRUE
# Environment name: COB_FILE_VBISAM
# Parameter name: file_vbisam
# Purpose: Should ISAM files be created in the old VB-ISAM format
# Type: boolean
# Default: false
# Example: file_vbisam=TRUE
# Environment name: COB_FILE_ISNODAT
# Parameter name: file_isnodat
# Purpose: Should ISAM 'data file' have the '.dat' extension or not
# (The ISAM 'index file' will always have a '.idx' extension)
# Type: boolean
# Default: false
# Example: file_isnodat=TRUE
# Environment name: COB_STOP_RUN_COMMIT
# Parameter name: stop_run_commit
# Purpose: On STOP RUN with updates pending should it COMMIT
# Type: boolean
# Default: false
# When 'false' a ROLLBACK of pending updates will be done
# Example: stop_run_commit=true
# Environment name: COB_HEAP_MEMORY
# Parameter name: heap_memory
# Purpose: Defines how much RAM to use when allocating segments
# of memory to be used by the VIRTAUL HEAP functions.
# Type: size but must be between 16K and 64M
# Default: 1M
# Example: HEAP_MEMORY 1M
# Environment name: COB_HEAP_MEMORY_64
# Parameter name: heap_memory_64
# Purpose: Defines how much RAM to use when allocating segments
# of memory to be used by the VIRTAUL HEAP functions
# when using the 64 bit READ / WRITE VFILE versions.
# Type: size but must be >= 256K
# Default: 64M
# Example: HEAP_MEMORY_64 128M
# Environment name: COB_SORT_MEMORY
# Parameter name: sort_memory
# Purpose: Defines how much RAM to assign for sorting data
# if this size is exceeded the SORT will be done
# on disk instead of memory
# Type: size but must be more than 1M
# Default: 128M
# Example: SORT_MEMORY 64M
# Environment name: COB_SORT_CHUNK
# Parameter name: sort_chunk
# Purpose: Defines how much RAM to assign for sorting data in chunks
# Type: size but must be within 128K and 16M
# Default: 256K
# Example: SORT_CHUNK 1M
# Environment name: COB_SEQ_CONCAT_NAME
# Parameter name: seq_concat_name
# Purpose: Does DD_asgname hold multiple input file names
# Type: boolean
# Default: false
# Example: seq_concat_name = true
# Environment name: COB_SEQ_CONCAT_SEP
# Parameter name: seq_concat_sep
# Purpose: Character separating file names
# Type: char
# Default: +
# Example: seq_concat_sep = '&'
#
## File I/O database specfic for OCI and ODBC
#
# Environment name: COB_SCHEMA_DSN
# Purpose: Defines the DSN name for connecting to the database.
# (DSN is commonly defined in /usr/local/etc/odbc.ini or
# /etc/odbc.ini)
# Type: string
# Example: COB_SCHEMA_DSN = testdb
# Environment name: COB_SCHEMA_CON
# Purpose: Defines the complete database connection string,
# normally DSN is enough.
# Type: string
# Example: COB_SCHEMA_CON = "what goes here"
# Environment name: COB_SCHEMA_SID
# Purpose: Defines the Oracle SID name for connecting to the database.
# Type: string
# Example: COB_SCHEMA_SID = mydb
# Environment name: COB_SCHEMA_UID
# Purpose: Defines the Oracle UID name for connecting to the database.
# Type: string
# Example: COB_SCHEMA_UID = myname
# Environment name: COB_SCHEMA_PWD
# Purpose: Defines the Oracle PWD value for connecting to the database.
# Type: string
# Example: COB_SCHEMA_PWD = mypassword
Screen I/O
#
## Screen I/O
#
# Environment name: COB_BELL
# Parameter name: bell
# Purpose: Defines how a request for the screen to beep is handled
# Type: FLASH, SPEAKER, FALSE, BEEP
# Default: BEEP
# Example: BELL SPEAKER
# Environment name: COB_REDIRECT_DISPLAY
# Parameter name: redirect_display
# Purpose: Defines if DISPLAY output should be sent to 'stderr'
# Type: boolean
# Default: false
# Example: redirect_display Yes
# Environment name: COB_SCREEN_ESC
# Parameter name: screen_esc
# Purpose: Enable handling of ESC key during ACCEPT
# Type: boolean
# Default: false
# Note: is only evaluated if COB_SCREEN_EXCEPTIONS is active
# Example: screen_esc Yes
# Environment name: COB_SCREEN_EXCEPTIONS
# Parameter name: screen_exceptions
# Purpose: enable exceptions for function keys during ACCEPT
# Type: boolean
# Default: false
# Example: screen_exceptions Yes
# Environment name: COB_TIMEOUT_SCALE
# Parameter name: timeout_scale
# Purpose: specify translation in milliseconds for ACCEPT clauses
# BEFORE TIME value / AFTER TIMEOUT
# Type: integer
# 0 means 1000 (Micro Focus COBOL compatible), 1 means 100
# (ACUCOBOL compatible), 2 means 10, 3 means 1
# Default: 0
# Note: the minimum and possible maximum value depend on the
# screenio library used
# Example: timeout_scale 3
# Environment name: COB_INSERT_MODE
# Parameter name: insert_mode
# Purpose: specify default insert mode for ACCEPT; 0=off, 1=on
# Type: boolean
# Default: false
# Note: also sets the cursor type (if available)
# Example: insert_mode Y
# Environment name: COB_HIDE_CURSOR
# Parameter name: hide_cursor
# Purpose: hide the cursor; 0=visible, 1=hidden
# Type: boolean
# Default: false
# Example: hide_cursor Y
# Environment name: COB_MOUSE_FLAGS
# Parameter name: mouse_flags
# Purpose: specify which mouse events will be sent as function key
# to the application during ACCEPT and how they will be
# handled
# Type: int (by bits)
# Default: 1
# Note: 0 disables the mouse cursor, any other value enables it,
# any value containing 1 will enable internal handling (click
# to position, double-click to enter).
# See copy/screenio.cpy for list of events and their values.
# Alias: MOUSE_FLAGS
# Example: 11 (enable internal handling => 1, left press => 2,
# double-click => 8; 1+2+8=11)
# Environment name: COB_MOUSE_INTERVAL
# Parameter name: mouse_interval
# Purpose: specifies the maximum time (in thousands of a second)
# that can elapse between press and release events for them
# to be recognized as a click.
# Type: int (0 - 166)
# Default: 100
# Note: 0 disables the click resolution (instead press + release
# are recognized), also disables positioning by mouse click
# Environment name: COB_DISPLAY_PRINT_PIPE
# Parameter name: display_print_pipe
# Purpose: Defines command line used for sending output of
# DISPLAY UPON PRINTER to (via pipe)
# This is very similar to Micro Focus COBPRINTER
# Note: Each executed DISPLAY UPON PRINTER statement causes a
# new invocation of command-line (= new process start).
# Each invocation receives the data referenced in
# the DISPLAY statement and is followed by an
# end-of-file condition.
# COB_DISPLAY_PRINT_FILE, if set, takes precedence
# over COB_DISPLAY_PRINT_PIPE.
# Alias: COBPRINTER
# Type: string
# Default: not set
# Example: print 'cat >>/tmp/myprt.log'
# Environment name: COB_DISPLAY_PRINT_FILE
# Parameter name: display_print_file
# Purpose: Defines file to be appended to by DISPLAY UPON PRINTER
# Note: Each DISPLAY UPON PRINTER opens, appends and closes the file.
# Type: string ; may use $-sequences
# Default: not set
# Example: display_printer '/tmp/myprt.log'
# Environment name: COB_DISPLAY_PUNCH_FILE
# Parameter name: display_punch_file
# Purpose: Defines file to be created on first
# DISPLAY UPON SYSPUNCH/SYSPCH
# Note: The file will be only be closed on runtime exit.
# Type: string ; may use $-sequences
# Default: not set
# Example: display_punch './punch_$$.out'
# Environment name: COB_LEGACY
# Parameter name: legacy
# Purpose: keep behavior of former runtime versions, currently only
# for setting screen attributes for non input fields and
# disabling blinking on some systems
# Type: boolean
# Default: not set
# Example: legacy true
# Environment name: COB_EXIT_WAIT
# Parameter name: exit_wait
# Purpose: to wait on main program exit if an extended screenio
# DISPLAY was issued without an ACCEPT following
# Type: boolean
# Default: true
# Example: COB_EXIT_WAIT off
# Environment name: COB_EXIT_MSG
# Parameter name: exit_msg
# Purpose: string to display if COB_EXIT_WAIT is processed, set to ''
# if no actual display but an ACCEPT should be done
# Type: string
# Default: 'end of program, please press a key to exit' (localized)
# Example: COB_EXIT_MSG ''
Report I/O
#
## Report I/O
#
# Environment name: COB_COL_JUST_LRC
# Parameter name: col_just_lrc
# Purpose: If true, then COLUMN defined as LEFT, RIGHT or CENTER
# will have the data justified within the field limits
# If false, then the data is just copied into the column as is
# Type: boolean
# Default: TRUE
# Example: col_just_lrc True
File I/O Environment Variables and/or dictionary file
#
## File I/O Environment Variables and/or dictionary file
#
# Before a file is opened a check is done for environment variables that
# may define various attributes of the file
# First a check is made for attributes for files of the same ORGANIZATION
# IX_OPTIONS for INDEXED, SQ_OPTIONS for SEQUENTIAL, RL_OPTIONS for RELATIVE
# LS_OPTIONS for LINE SEQUENTIAL, LA_OPTIONS for LINE ADVANCING SEQUENTIAL
# If none of these are present, it then checks for IO_OPTIONS
#
# Then an additional check is done for IO_asgnmame where 'asgname' was
# the ASSIGN EXTERNAL name used in the program
#
# The environment variable (or dictionary file) may contain any of the
# following keywords, separated by spaces and/or commas
#
# You can specify just the keyword and it is assumed to mean set to true,
# or no-keyword (or no_keyword or nokeyword) which means set to false,
# or keyword=true or keyword=false. The valid keywords are:
# Keyword Meaning
# ========= ======================================================
# type=xx Set file organization where 'xx' is one of
# IX = INDEXED, SQ = SEQUENTIAL, RL = RELATIVE
# LS = LINE SEQUENTIAL, LA = LINE ADVANCING
# mf Set file to Micro Focus compatible format
# gc Set to original GNU Cobol default format
# recsz The size for fixed size record file
# maxsz Maximum record size for variable length records
# minsz Minimum record size for variable length records
# ls_nulls Do NUL insertion before characters less than a SPACE,
# Default: false
# ls_validate Validate data for LINE Sequential Files, Default: true
# crlf Lines end with CR LF (Windows format for text files)
# lf Lines end with LF (Unix format for text files)
# sync Sync all writes to disk
# B32 Use 32-bit Big-Endian format 'int' as record length
# L32 Use 32-bit Little-Endian format 'int' as record length
# B64 Use 64-bit Big-Endian format 'int' or 'size_t' as record length
# L64 Use 64-bit Little-Endian format 'int' or 'size_t' as record length
# trace Enable I/O trace when program execution tracing is enabled
# stats Write I/O statistic information on file close
# retry_times Default number of times to retry I/O
# retry_seconds Number of seconds between I/O retry attempts
# retry_forever Retry I/O forever
# retry_never Never retry I/O operations
# ignore_lock Ignore record locks
# advancing_lock Advance to the next record if lock condition
# share_all Share file with ALL others
# share_read Share file for READ only
# share_no Share file with NO others
# ---- For INDEXED files -----
# format=ixhandler INDEXED file format: CISAM,DISAM,VBISAM,VBCISAM,OCI,ODBC,BDB,LMDB
# format=auto INDEXED file format is determined by inspecting the file
# dups_ahead= default,never,always
# rollback= yes, no
# (OCI & ODBC will 'autocommit' each update is not defined and not APPLY COMMIT)
# (fileio will handle COMMIT/ROLLBACK for all other files)
# nkeys=n number of indexes
# key1=(loc:len) loc (zero relative) of key, len of key
# key2=(loc:len,loc:len ...) define composite index
# dupn=Y index allows dups
# ---- For INDEXED BDB files -----
# big_endian Set internal 'int' byte order to BIG ENDIAN
# little_endian Set internal 'int' byte order to LITTLE ENDIAN
#
Program Arguments
Regardless of the manner in which a main program is executed (i.e. directly or via cobcrun), any arguments specified to the program may be retrieved via any of the following:
ACCEPT FROM COMMAND-LINE(see ACCEPT FROM COMMAND-LINE)PROCEDURE DIVISION CHAINING(see PROCEDURE DIVISION CHAINING)
Binary Truncation
By default, the GnuCOBOL compiler will truncate binary data items to the precision indicated by their PICTURE (see PICTURE) clause, if they have one. This applies to COMP, BINARY and COMP-4 items Only. The fact is, however, that binary truncation has a significant effect on the performance of GnuCOBOL programs. When binary truncation is in effect, arithmetic operations performed against all types of numeric data items (even USAGE DISPLAY) are slowed down.
Before continuing, it’s worth making the point that we’re not talking about astronomical performance degradations here. Today’s computers are fast, and a user sitting at the keyboard, running a GnuCOBOL program is unlikely to notice. But, if you have a GnuCOBOL program that has to process large amounts of data, performing some significant “number crunching” against that data as it goes, the impact of truncation could become noticeable.
The following program compares the performance of performing arithmetic operations (in a totally non-scientific, non-rigorous way) against data items with a USAGE (see USAGE) of DISPLAY, COMP and BINARY-LONG. It was actually my intent when I first wrote the program to merely demonstrate the relative performance differences between different types of numeric data storage, and it certainly met that objective.
IDENTIFICATION DIVISION.
PROGRAM-ID. DEMOMATH.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 Begin-Time.
05 BT-HH PIC 9(2).
05 BT-MM PIC 9(2).
05 BT-SS PIC 9(2).
05 BT-HU PIC 9(2).
01 Binary-Item BINARY-LONG SIGNED VALUE 0.
01 Comp-Item COMP PIC S9(9) VALUE 0.
01 Display-Item DISPLAY PIC S9(9) VALUE 0.
01 End-Time.
05 ET-HH PIC 9(2).
05 ET-MM PIC 9(2).
05 ET-SS PIC 9(2).
05 ET-HU PIC 9(2).
78 Repeat-Count VALUE 10000000.
01 Time-Diff PIC ZZ9.99.
PROCEDURE DIVISION.
010-Test-Usage-DISPLAY.
ACCEPT Begin-Time FROM TIME
PERFORM Repeat-Count TIMES
ADD 7 TO Display-Item
END-PERFORM
PERFORM 100-Determine-Time-Diff
DISPLAY 'USAGE DISPLAY: ' Time-Diff ' SECONDS'.
020-Test-Usage-COMP.
ACCEPT Begin-Time FROM TIME
PERFORM Repeat-Count TIMES
ADD 7 TO Comp-Item
END-PERFORM
PERFORM 100-Determine-Time-Diff
DISPLAY 'USAGE COMP: ' Time-Diff ' SECONDS'.
040-Test-Usage-BINARY.
ACCEPT Begin-Time FROM TIME
PERFORM Repeat-Count TIMES
ADD 7 TO Binary-Item
END-PERFORM
PERFORM 100-Determine-Time-Diff
DISPLAY 'USAGE BINARY: ' Time-Diff ' SECONDS'.
099-Done.
STOP RUN.
100-Determine-Time-Diff.
ACCEPT End-Time FROM TIME
COMPUTE Time-Diff =
( (ET-HH * 360000 + ET-MM * 6000 + ET-SS * 100 + ET-HU)
- (BT-HH * 360000 + BT-MM * 6000 + BT-SS * 100 + BT-HU) )
/ 100.
Each data item has 7 added to it ten million times.
The time (to one-one-hundredth of a second) will be retrieved before and after each test and the difference between the two is displayed. This is why the computations were done so many times — it was to make sure the timing was measurable with only a 1/100 second “stopwatch”.
I also ran the tests multiple times, just to make sure I had consistent results (I did). Like I mentioned earlier, this is not a rigorous, scientific benchmark of numeric performance; it’s just a quick-and-dirty comparison.
Here are the results:
Test 1:
USAGE DISPLAY: 1.72 SECONDS
USAGE COMP: 0.62 SECONDS
USAGE BINARY: 0.02 SECONDS
Test 2:
USAGE DISPLAY: 1.69 SECONDS
USAGE COMP: 0.61 SECONDS
USAGE BINARY: 0.02 SECONDS
Test 3:
USAGE DISPLAY: 1.69 SECONDS
USAGE COMP: 0.65 SECONDS
USAGE BINARY: 0.02 SECONDS
The results I saw here were consistent with those that would have been obtained from most of the COBOL implementations I have ever worked with — USAGE COMP has a significant performance advantage over USAGE DISPLAY and USAGE BINARY-LONG (and presumably the other BINARY-xxx usages as well) perform identically, within the measurement tolerances of the test.
Imagine my surprise, however, when I discovered that the use of -fno-trunc switch also made a difference:
Test 4:
USAGE DISPLAY: 1.72 SECONDS
USAGE COMP: 0.07 SECONDS
USAGE BINARY: 0.02 SECONDS
Test 5:
USAGE DISPLAY: 1.72 SECONDS
USAGE COMP: 0.07 SECONDS
USAGE BINARY: 0.02 SECONDS
Test 6:
USAGE DISPLAY: 1.73 SECONDS
USAGE COMP: 0.06 SECONDS
USAGE BINARY: 0.02 SECONDS
As you can see, there was a huge drop in USAGE COMP timings by turning off truncation. As a result, I see absolutely no reason whatsoever why the -fno-trunc switch option shouldn’t be used on all GnuCOBOL compilations.
If you want to squeeze every last bit of performance out of your GnuCOBOL programs, don’t forget to investigate the -O switch, -O2 switch and the -Os switch, all of which influence the optimization of compiled code. Actually run programs using various optimization switches (or not) and compare execution times against those of unoptimized compiled versions of your programs. Don’t just compare the generated C code because sometimes the differences can’t be seen at the C source-code level.
Test 7:
cobc -x demomath.cbl -O2;demomath
USAGE DISPLAY: 1.68 SECONDS
USAGE COMP: 0.60 SECONDS
USAGE BINARY: 0.00 SECONDS
Test 8:
cobc -x demomath.cbl -fnotrunc -O2;demomath
USAGE DISPLAY: 1.67 SECONDS
USAGE COMP: 0.01 SECONDS
USAGE BINARY: 0.00 SECONDS
All tests above carried out under Linux with a AMD FX8350 under very low loading prior to the test.