Linking¶

Unlike, C, the COBOL CALL statement implies dynamic linking, because for

gcobol supports static linking where possible, unless defeated by -fno-static-call. If the parameter value is known at compile time, the compiler produces an external reference to be resolved by the linker. The referenced program is normally supplied via an object module, a static library, or a shared object. If it is not supplied, the linker will report an “unresolved symbol” error, either at build time or, if using a shared object, when the program is executed. This feature informs the programmer of the error at the earliest opportunity.

Programs that are expected to execute correctly in the presence of an unresolved symbol (perhaps because the program logic won't require that particular CALL) can use the -no-static-call option. That forces all CALL statements to be resolved dynamically, at runtime.

Implemented Exception Conditions¶

By default, per ISO, no EC is enabled. Implemented ECs may be enabled on the command line or via the TURN directive. Any attempt to enable an EC that is not implemented is treated as an error.

An enabled EC not handled by a DECLARATIVE is written to the system log and to standard error. (The authors intend to make that an option.) A fatal EC not handled with RESUME ends with a call to abort(3) and process termination.

Not all Exception Conditions are implemented. Any attempt to enable an EC that that is not implemented produces a warning message. The following are implemented:

As of this writing, no COBOL compiler documents a complete implementation of ISO/IEC 1989:2023 Exception Conditions. gcobol will give priority to those ECs that the user community deems most valuable.

Environment Variables¶

To read an environment variable:

where target is a data item defined in DATA DIVISION, and envar names an environment variable. envar may be a string literal or alphanumeric data item whose value is the name of an environment variable. The value of the named environment variable is moved to target. The rules are the same as for MOVE.

To write an environment variable:

where source is a data item defined in DATA DIVISION, and envar names an environment variable. envar again may be a string literal or alphanumeric data item whose value is the name of an environment variable. The value of the named environment variable is set to the value of source.

Command-line Arguments¶

To read command-line arguments, use the registers COMMAND-LINE and COMMAND-LINE-COUNT in an ACCEPT statement (only). Used without a subscript, COMMAND-LINE returns the whole command line as a single string. With a subscript, COMMAND-LINE is a table of command-line arguments. For example, if the program is invoked as

then

moves input into target. The program name is the first thing in the whole command line and is found in COMMAND-LINE(1) COMMAND-LINE table.

To discover how many arguments were provided on the command line, use

If ACCEPT refers to a nonexistent environment variable or command-line argument, the target is set to LOW-VALUES.

The system command line parameters can also be accessed through the LINKAGE SECTION in the program where execution starts. The data structure looks like this:

        linkage         section.
        01   argc       pic 999.
        01   argv.
         02  argv-table   occurs 1 to 100 times depending on argc.
          03 argv-element pointer.
        01   argv-string  pic x(100) .

        procedure division using by value argc by reference argv.
        set address of argv-string to argv-element(3)
        display argv-string

#line directive¶

The parser accepts lines in the form

SELECT ... ASSIGN TO¶

In the phrase

filename may appear in quotes or not. If quoted, it represents a filename as known to the operating system. If unquoted, it names either a data element or an environment variable containing the name of a file. If filename matches the name of a data element, that element is used. If not, resolution of filename is deferred until runtime, when the name must appear in the program's environment.

USAGE Data Types¶

gcobol supports the following USAGE IS clauses:

INDEX

for use as an index in a table.

POINTER

for variables whose value is the address of an external function, PROGRAM-ID, or data item. Assignment is via the SET statement.

BINARY, COMP, COMPUTATIONAL, COMP-4, COMPUTATIONAL-4

big-endian integer, 1 to 16 bytes, per PICTURE.

COMP-1, COMPUTATIONAL-1, FLOAT-BINARY-32

IEEE 754 single-precision (4-byte) floating point, as provided by the hardware.

COMP-2, COMPUTATIONAL-2, FLOAT-BINARY-64

IEEE 754 double-precision (8-byte) floating point, as provided by the hardware.

COMP-3, COMPUTATIONAL-3, PACKED-DECIMAL

currently unimplemented.

COMP-5, COMPUTATIONAL-5

little-endian integer, 1 to 16 bytes, per PICTURE.

FLOAT-BINARY-128, FLOAT-EXTENDED

implements 128-bit floating point, per IEEE 754.

gcobol supports ISO integer BINARY-<type> types, most of which alias COMP-5.

These define a size (in bytes) and cannot be used with a PICTURE clause. Per the ISO standard, SIGNED is the default for the BINARY-type aliases.

All computation — both integer and floating point — is done using 128-bit intermediate forms.

Environment Names¶

In gcobol

maps SYSOUT and STDOUT to standard output, and SYSPUNCH, SYSPCH and STDERR to standard error.

Exit Status¶

gcobol supports the ISO syntax for returning an exit status to the operating system,

In addition, gcobol also supports the IBM syntax for returning an exit status to the operating system. Use the RETURN-CODE register:

MOVE ZERO TO RETURN-CODE.
GOBACK.

The RETURN-CODE register is defined as a 4-byte binary integer.

CDF Text Manipulation¶

COPY copybook [OF|BY library] [REPLACING ...]

If copybook is a literal, it treated a literal filename, which either does or does not exist. If copybook is a COBOL word, gcobol looks first for an environment variable named copybook and, if found, uses the contents of that variable as the name of the copybook file. If that file does not exist, it continues looking for a file named one of:

• copybook (literally)
• copybook.cpy
• copybook.CPY
• copybook.cbl
• copybook.CBL
• copybook.cob
• copybook.COB

in that order. It looks first in the same directory as the source code file, and then in any copybook-path named with the -I option. copybook-path may (like the shell's PATH variable) be a colon-separated list. The -I option may occur multiple times on the command line. Each successive copybook-path is concatenated to previous ones. Relative paths (having no leading ‘/’) are searched relative to the compiler's current working directory.

For example,

-I /usr/local/include:include

searches first the directory where the COBOL program is found, next in /usr/local/include, and finally in an include subdirectory of the directory from which gcobol was invoked.

For the REPLACING phrase, both the modern pseudo-text and the COBOL/85 forms are recognized. (The older forms are used in the NIST CCVS/85 test suite.)

REPLACE ...

gcobol supports the full ISO REPLACE syntax.

CDF Directives¶

>>DEFINE name AS {expression | PARAMETER} [OVERRIDE]

Define name as a compilation variable to have the value expression. If name was previously defined, OVERRIDE is required, else the directive is invalid. AS PARAMETER is accepted, but has no effect in gcobol.

>>DEFINE name AS OFF

releases the definition name, making it subsequently invalid for use.

>>IF cce text [>>ELSE alt-text] >>END-IF

evaluates cce, a constant conditional expression, for conditional compilation. If a name, cce may be defined with the -D command-line parameter. If true, the COBOL text text is compiled. If false, else-text, if present, is compiled. [IS [NOT]] DEFINED is supported. Boolean literals are not supported.

>>EVALUATE

Not implemented.

>>CALL-CONVENTION convention

convention may be one of:

COBOL

Use standard COBOL case-insensitive symbol-name matching. For CALL “name”, name is rendered by the compiler in lowercase.

C

Use case-sensitive symbol-name matching. The CALL target is not changed in any way; it is used verbatim.

VERBATIM

An alias for >>CALL-CONVENTION C.

>>COBOL-WORDS EQUATE keyword WITH alias

makes alias a synonym for keyword.

>>COBOL-WORDS UNDEFINE keyword

keyword is removed from the COBOL grammar. Use of it in a program will provoke a syntax error from the compiler.

>>COBOL-WORDS SUBSTITUTE keyword BY new-word

keyword is deleted as a keyword from the grammar, replaced by new-word. keyword may thereafter be used as a user-defined word.

>>COBOL-WORDS RESERVE new-word

Treat new-word as a COBOL keyword. It cannot be used by the program, either as a keyword or as a user-defined word.

>>DISPLAY string ...

Write string to standard error as a warning message.

>>SOURCE format

format may be one of:

FIXED

Source conforms to COBOL fixed-form reference format with unlimited line length.

FREE

Source conforms to COBOL free-form reference format. ‘*’ at the beginning of a line is recognized as a comment.

>>FLAG-02

Not implemented.

>>FLAG-85

Not implemented.

>>FLAG-NATIVE-ARITHMETIC

Not implemented.

>>LEAP-SECOND

Not implemented.

>>LISTING

Not implemented.

>>PAGE

Not implemented.

>>PROPAGATE

Not implemented.

>>PUSH directive

 

>>POP directive

With PUSH, push CDF state onto a stack. With POP, return to the prior pushed state. directive may be one of

CALL-CONVENTION

 

COBOL-WORDS

 

DEFINE

 

SOURCE FORMAT

 

TURN

 

>>TURN [ec [file ...] ...] CHECKING {[ON] [[WITH] LOCATION] | OFF}

Enable (or, with OFF, disable) exception condition ec optionally associated with the file connectors file. If LOCATION is specified, gcobol reports at runtime the source filename and line number of the statement that triggered the exception condition.

Feature-set Variables¶

Some command-line options affect CDF feature-set variables that are special to gcobol. They can be set and tested using >>DEFINE and >>IF, and are distinguished by a leading ‘%’ in the name, which is otherwise invalid in a COBOL identifier:

%EBCDIC-MODE

is set by -finternal-ebcdic.

%64-BIT-POINTER

is implied by -dialect ibm.

To set a feature-set variable, use

To test a feature-set variable, use

Intrinsic functions¶

gcobol implements all intrinsic functions defined by ISO/IEC 1989:2023, plus a few others. They are listed alphabetically below.

• ABS ACOS ANNUITY ASIN ATAN
• BASECONVERT BIT-OF BIT-TO-CHAR BOOLEAN-OF-INTEGER BYTE-LENGTH
• CHAR CHAR-NATIONAL COMBINED-DATETIME CONCAT CONVERT COS CURRENT-DATE
• DATE-OF-INTEGER DATE-TO-YYYYMMDD DAY-OF-INTEGER DAY-TO-YYYYDDD DISPLAY-OF
• E EXCEPTION-FILE EXCEPTION-FILE-N EXCEPTION-LOCATION EXCEPTION-LOCATION-N EXCEPTION-STATEMENT EXCEPTION-STATUS EXP EXP10
• FACTORIAL FIND-STRING FORMATTED-CURRENT-DATE FORMATTED-DATE FORMATTED-DATETIME FORMATTED-TIME FRACTION-PART
• HEX-OF HEX-TO-CHAR HIGHEST-ALGEBRAIC
• INTEGER INTEGER-OF-BOOLEAN INTEGER-OF-DATE INTEGER-OF-DAY INTEGER-OF-FORMATTED-DATE INTEGER-PART
• LENGTH LOCALE-COMPARE LOCALE-DATE LOCALE-TIME LOCALE-TIME-FROM-SECONDS LOG LOG10 LOWER-CASE LOWEST-ALGEBRAIC
• MAX MEAN MEDIAN MIDRANGE MIN MOD MODULE-NAME
• NATIONAL-OF NUMVAL NUMVAL-C NUMVAL-F ORD
• ORD-MAX ORD-MIN
• PI PRESENT-VALUE
• RANDOM RANGE REM REVERSE
• SECONDS-FROM-FORMATTED-TIME SECONDS-PAST-MIDNIGHT SIGN SIN SMALLEST-ALGEBRAIC SQRT STANDARD-COMPARE STANDARD-DEVIATION SUBSTITUTE SUM
• TAN TEST-DATE-YYYYMMDD TEST-DAY-YYYYDDD TEST-FORMATTED-DATETIME TEST-NUMVAL TEST-NUMVAL-C TEST-NUMVAL-F TRIM
• ULENGTH UPOS UPPER-CASE USUBSTR USUPPLEMENTARY UUID4 UVALID UWIDTH
• VARIANCE
• WHEN-COMPILED
• YEAR-TO-YYYY

Binary floating point DISPLAY¶

How the DISPLAY presents binary floating point numbers depends on the value.

When a value has six or fewer decimal digits to the left of the decimal point, it is expressed as 123456.789....

When a value is less than 1 and has no more than three zeroes to the right of the decimal point, it is expressed as 0.0001234....

Otherwise, exponential notation is used: 1.23456E+7.

In all cases, trailing zeroes on the right of the number are removed from the displayed value.

COMP-1

displayed with 9 decimal digits.

COMP-2

displayed with 17 decimal digits.

FLOAT-EXTENDED

displayed with 36 decimal digits.

Those digit counts are consistent with the IEEE 754 requirements for information interchange. As one example, the description for COMP-2 binary64 values (per Wikipedia).

If an IEEE 754 double-precision number is converted to a decimal string with at least 17 significant digits, and then converted back to double-precision representation, the final result must match the original number.

17 digits was chosen so that the DISPLAY statement shows the contents of a COMP-2 variable without hiding any information.

Binary floating point MOVE¶

During a MOVE statement, a floating-point value may be truncated. It will not be unusual for Numeric Display values to be altered when moved through a floating-point value.

This program:

    01 PICV999 PIC 9999V999.
    01 COMP2 COMP-2.
   PROCEDURE DIVISION.
    MOVE 1.001 to PICV999
    MOVE PICV999 TO COMP2
    DISPLAY "The result of MOVE " PICV999 " TO COMP2 is   " COMP2
    MOVE COMP2 to PICV999
    DISPLAY "The result of MOVE COMP2    TO PICV999 is " PICV999

generates this result:

    The result of MOVE 0001.001 TO COMP2 is   1.00099999999999989
    The result of MOVE COMP2    TO PICV999 is 0001.000

However, the internal implementation can produce results that might be seem surprising:

    The result of MOVE 0055.110 TO COMP2 is   55.1099999999999994
    The result of MOVE COMP2    TO PICV999 is 0055.110

The source of this inconsistency is the way gcobol stores and converts numbers. Converting the floating-point value to the numeric display value 0055110 is done by multiplying 55.109999... by 1,000 and then truncating the result to an integer. And it turns out that even though 55.11 can't be represented in floating-point as an exact value, the product of the multiplication, 55110, is an exact value.

In cases where it is important for conversions to have predictable results, we need to be able to apply rounding, which can be done with an arithmetic statement:

    MOVE 1.001 to PICV999
    MOVE PICV999 TO COMP2
    DISPLAY "The result of MOVE " PICV999 " TO COMP2 is   " COMP2
    MOVE COMP2 to PICV999
    DISPLAY "The result of MOVE COMP2    TO PICV999 is " PICV999
    ADD COMP2 to ZERO GIVING PICV999 ROUNDED
    DISPLAY "The result of ADD COMP2 to ZERO GIVING PICV999 ROUNDED is " PICV999

    The result of MOVE 0001.001 TO COMP2 is   1.00099999999999989
    The result of MOVE COMP2    TO PICV999 is 0001.000
    The result of ADD COMP2 to ZERO GIVING PICV999 ROUNDED is 0001.001

Binary floating point computation¶

gcobol attempts to do internal computations using binary integers when possible. Thus, simple arithmetic between binary values and numeric display values conclude with binary intermediate results.

If a floating-point value gets included in the mix of variables specified for a calculation, then the intermediate result becomes a 128-bit floating-point value.

A warning about binary floating point comparison¶

The cardinal rule when doing comparisons involving floating-point values: Never, ever, test for equality. It's just not worth the hassle.

For example:

   WORKING-STORAGE SECTION.
    01 COMP1 COMP-1 VALUE 555.11.
    01 COMP2 COMP-2 VALUE 555.11.
   PROCEDURE DIVISION.
    DISPLAY "COMPARE " COMP1 " with " COMP2
    IF COMP1 EQUAL COMP2 DISPLAY "Equal" ELSE DISPLAY "Not equal" END-IF

    MOVE COMP1 to COMP2
    DISPLAY "COMPARE " COMP1 " with " COMP2
    IF COMP1 EQUAL COMP2 DISPLAY "Equal" ELSE DISPLAY "Not equal" END-IF

the results:

    COMPARE 555.1099854 with 555.110000000000014
    Not equal
    COMPARE 555.1099854 with 555.1099853515625
    Equal

Why? Again, it has to do with the internals of gcobol. When differently sized floating-point values need to be compared, they are first converted to 128-bit floats. And it turns out that when a COMP1 is moved to a COMP2, and they are both converted to FLOAT-EXTENDED, the two resulting values are (probably) equal.

Avoid testing for equality unless you really know what you are doing and you really test the code. And then avoid it anyway.

Finally, it is observably the case that the gcobol implementations of floating-point conversions and comparisons don't precisely match the behavior of other COBOL compilers.

You have been warned.

On-Disk Format¶

Any ability to use files produced by other COBOL compilers, or for those compilers to use files produced by gcobol, is the product of luck and intuition. Various compilers interpret the ISO standard differently, and the standard's text is not always definitive.

For ORGANIZATION IS LINE SEQUENTIAL files (explicitly or by default), gcobol, absent specific direction, produces an ordinary Linux text file: for each WRITE, the data are written, followed by an ASCII NL (hex 0A) character. On READ, the record is read up to the size of the specified record or NL, whichever comes first. The NL is not included in the data brought into the record buffer; it serves only as an on-disk record-termination marker. Consequently, SEQUENTIAL and LINE SEQUENTIAL files work the same way: the COBOL program never sees the record terminator.

When READ and WRITE are used with ADVANCING, however, the game changes. If ADVANCING is used with LINE SEQUENTIAL files, it is honored by gcobol.

Other compilers may not do likewise. According to ISO, in WRITE (14.9.47.3 General rules) ADVANCING is ignored for files for which “the physical file does not support vertical positioning”. It further states that, in the absence of ADVANCING, WRITE proceeds as if “as if the user has specified AFTER ADVANCING 1 LINE”. Some other implementations interpret that to mean that the first WRITE to a LINE SEQUENTIAL file results in a leading NL on the first line, and no trailing NL on the last line. Some furthermore prohibit the use of ADVANCING with LINE SEQUENTIAL files.

Status of NIST COBOL Compiler Verification Suite¶

NC 100%

Nucleus

SQ 100%

Sequential I/O

RL 100%

Relative I/O

IX 100%

Indexed I/O

IC 100%

Inter-Program Communication

ST 100%

Sort-Merge

SM 100%

Source Text Manipulation RW \n Report Writer

CM

Communication

DB to do?

Debug

SG

Segmentation

IF 100%

Intrinsic Function

Where gcobol passes 100% of the tests in a module, we exclude the (few) tests for obsolete features. The authors regard features that were obsolete in 1985 to be well and truly obsolete today, and did not implement them.

Notable deferred features¶

CCVS-85 modules not marked with above with any status (CM, and SG) are on the “hard maybe” list, meaning they await an interested party with real code using the feature.

gcobol does not implement Report Writer or Screen Section.

Beyond COBOL/85¶

gcobol increasingly implements ISO/IEC 1989:2023. For example, DECLARATIVES is not tested by CCVS-85, but are implemented by gcobol. Similarly, Exception Conditions were not defined in 1985, and gcobol contains a growing number of them.

The authors are well aware that a complete, pure COBOL-85 compiler won't compile most existing COBOL code. Every vendor offered (and offers) extensions, and most environments rely on a variety of preprocessors and ancillary systems defined outside the standard. The express goal of adding an ISO COBOL front-end to GCC is to establish a foundation on which any needed extensions can be built.