NAME

gcobol-migration — feature and option comparison with GnuCOBOL and other COBOL compilers

DESCRIPTION

The GCC COBOL compiler, gcobol, is a gcc front-end, meaning it parses ISO COBOL source code and produces executable code using the gcc back-end. Because it's a gcc compiler, gcobol accepts all gcc options that control code generation and linking. There is a small set of options and environment variables unique to gcobol itself.

Being part of gcc means gcobol works like gcc, and not necessarily how other COBOL compilers work. This guide describes features of GnuCOBOL and gcobol, showing how they are similar and different:

identical

The feature has the same effect in both compilers.

mappable

The feature in one compiler has a similar/matching feature in the other.

unique

The feature has no comparable feature in the other compiler. Sometimes the same or similar effect can be obtained by other means.

COMMAND-LINE OPTIONS

Help options

Identical

--help --version --verbose -v

Mappable

GNU	GCC
-h	--help

GnuCOBOL Only

--info --list-reserved --list-intrinsics --list-system --list-mnemonics

Build target

Identical

-c

compile each COBOL file to object code. Do not link.

-D name=value

Define CDF user-defined word name as representing the string or number value.

-E

gcobol continues with compilation. To prevent compilation, use

because nonzero status from any preprocessor prevents compilation. gcobol also writes to standard output, not to a .i file.

-I pathname

Add pathname to the search path for copybooks. If pathname does not begin with ‘/’, it is interpreted as relative to the current working directory for the gcobol process.

-L pathname

Library search path

-l libname

Link with library Ar libname .

-o filename

Write the compiled output to filename.

-S

Stop after the stage of compilation proper; do not assemble. Output is assembler code file for each non-assembler input file.

Mappable

GNU	GCC
-m, -b	-shared

gcobol Only

-main filename, -nomain

controls whether a main() function is generated for filename.

GnuCOBOL Only

-C

gcobol does not translate to C.

-x

Inapplicable because, like gcc, by default gcobol produces an executable binary.

-j -job

gcobol has no job control

Source format

Identical

None identified.

Mappable

GNU	GCC
-free, -F	-ffree-form
-fixed	-ffixed-form    gcobol truncates lines at column 72, i.e. strict Reference Format. For Extended Reference Format, use -indicator-column 7 which places the indicator area in its standard position, and imposes no line length limit.

GnuCOBOL Only

None identified.

Warning options

Identical

-fsyntax-only -fmax-errors=N

The following warning option are not yet implemented, but will be during gcc integration: -w -Werror -Werror=WARNING

GnuCOBOL Only

-Wfatal-errors -Wall -Wextra, -W -WWARNING -Wno-WARNING -Warchaic -Wcall-params -Wcolumn-overflow -Wconstant -Wimplicit-define -Wlinkage -Wobsolete -Wparentheses -Wredefinition -Wstrict-typing -Wterminator -Wtruncate -Wconstant-expression -Wconstant-numlit-expression -Wunreachable -Wadditional

Configuration options

Identical

 

Mappable

GNU	GCC
-std=mvs	-dialect ibm
-std=mf	-dialect mf

gcobol is an ISO-standard compiler with relatively little support for nonstandard syntax. Some common syntax extensions are supported using the -dialect option. For details see gcobol(1).

GnuCOBOL Only

-std=DIALECT -std=default -std=cobol85 -std=xopen -std=cobol2002, -std=cobol2014 -std=ibm-strict, -std=ibm -std=mvs-strict, -std=mvs -std=mf-strict -std=bs2000-strict, -std=bs2000 -std=acu-strict, -std=acu -std=rm-strict, -std=rm -std=realia-strict, -std=realia -std=gcos-strict, -std=gcos -freserved-words=DIALECT -conf=<file> -febcdic-table=CCONV-TABLE/FILE

GnuCOBOL has numerous specific options controlling acceptable syntax. gcobol has no such options.

Listing options

gcobol produces no listing file.

Debug switches

Identical

-g

gcobol supports all forms of the gcc -g option, including -ggdb, which can be very useful.

Mappable

-O, -O2, -Os

It's not clear how exactly to map these GnuCOBOL optimization options. gcobol supports the gcc -O options, from -O0 to -O3, with -O2 being perhaps the most commonly used. For debugging, -O0 (no optimization) probably yields the best experience.

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

In addition to the CDF >>TURN directive, gcobol supports -fcobol-exceptions mask, where mask is hexadecimal number, as described in gcobol(1).

--debug

maps to -d.

-fstack-check

may correspond to the gcc option of the same name.

gcobol Only

-preprocess filter-name

Between gathering the COBOL source file and copybooks, and sending them to the compiler, this options passes the normalized input through filter-name. More than one -preprocess option can be used; they are applied in order.

-fflex-debug, -fyacc-debug

produce messages useful for compiler development.

GnuCOBOL Only

-fmemory-check=scope -fsource-location -ftrace -ftraceall -fdebugging-line -fnotrunc

gcobol has no trace functionality. Any runtime bounds checking is enabled via Exception Conditions. gcobol's support for debugging lines has not been thoroughly tested. The feature is deprecated in ISO, but is still supported by IBM's compiler. If the user needs support for such code, the gcobol developers will enable the NIST DB module for testing.

Miscellaneous

Mappable

The GnuCOBOL option -save-temps[=dir] can be emulated in gcobol using the GCOBOL_TEMPDIR environment variable, as described in gcobol(1).

GnuCOBOL Only

-ext extension -fintrinsics=[ALL|name [,name,...]] -ffold-copy=LOWER -ffold-copy=UPPER -fimplicit-init

Multiple Sources

gcobol treats multiple sources in the way any gcc compiler does. Multiple source code files, object files, and libraries may appear on the command line. By default they are combined to produce one executable. If -shared is used, the product is a shared object with a .so extension. If -c is used, each source file produces a corresponding object file with a .o extension.

Linkage

As a gcc compiler, gcobol by default links with any libraries at build time. This differs from the GnuCOBOL default, which always defers CALL for dynamic, runtime resolution. See -static-call in gcobol(1) for details. gcobol also differs in how/where the produced executable searches for libraries. The conventional (gcc) approach is to link any libraries that will be needed. This applies even with -no-static-call. For the linked library to be found at runtime by the dynamic linker, ld.so(8), the library must either be

1. in the linker's default search path, or
2. in the executable's RPATH -Wl,path.

The library search path can be further extended with the environment variables COBPATH, which is specific to gcobol-produced executables, and LD_LIBRARY_PATH, which is a feature of the dynamic linker.

C interface

This section has two parts:

1. how COBOL symbols in programs compiled with gcobol appear in the object code
2. from a COBOL compiled with gcobol

gcobol symbols

gcobol binaries use ordinary C linkage. Each top-level PROGRAM-ID creates a symbol in the object code by the same name. A COBOL Program can be called from C as a function, and returns a value to a C caller just as a C function does.

An EXTERNAL data item is manifested in the object code as a name with external linkage, accessible to the linker. A C program may reference it using the ‘extern’ keyword.

Contained programs and data items not using the EXTERNAL phrase do not have external linkage. gcobol has no support for the ENTRY statement.

Name mangling

To facilitate case-insensitive name matches as mandated by the ISO standard, all COBOL symbol names appear in the object file in lower case. This differs from the GnuCOBOL practice of using upper case symbol names.

The x64 ABI used by Linux does not allow for hyphens in a symbol name, which is restricted to letters, digits, and underscores, (regex [[:alnum:]_]). For this reason, names that include hyphens are “mangled”. The exact algorithm is too tedious to describe here. If you wish to access such names from C, though, it is possible. Contact the developers for details.

Parameters

In gcobol, program's parameters and return value are always 64-bit entities. If a program returns a numeric value, it is returned as a 64-bit integer or floating point value, (C int64_t or double). Strings are always represented by pointers. An OPTIONAL parameter is represented by a NULL pointer. There is no way for a C program to indicate a missing parameter for which USING BY VALUE is specified.

gcobol provides no functions for C programs to manipulate COBOL variables. Intrinsic functions are likewise inaccessible from C because their parameters do not follow the above scheme. Because they are designed to be called from COBOL, they are designed to accept and return COBOL data.

Calling C functions from gcobol

By default, gcobol assumes the target of a CALL statement is a COBOL program compiled by gcobol. It therefore converts the name of the CALL target to lower case (and applies the name-mangling algorithm). Also by default, if the target is a compile-time constant, static linking is used. That is, the name is manifested in the object code as an external reference for the linker to resolve. Both these defaults can be changed.

To prevent a name from being converted to lowercase form, use the CDF

>>CALL-CONVENTION VERBATIM

directive. With that in force, the name provided will be the name used, without change. It remains in force until

>>CALL-CONVENTION COBOL

is encountered.

To prevent static linking, use the command-line option

-fno-static-call

With that option, no CALL target is ever manifested as an external reference in the object code. All references are resolved at runtime using dlopen(3) and dlsym(3).

These features are independent. One can have static linking or not with either call-convention.

How links the linker

The term “static linking” used here can be misleading, and should not be confused with static libraries. It means only that a name known at compile time is resolved by “the linker”, not the gcobol runtime library. At build time, the static linker, ld(1), verifies that each external reference is supplied by a library named on the command line. That library might be a static library, in which case the function (say) is incorporated into the produced binary. More commonly the library is a shared object, in which case the linker adds the library's name to the set required by the produced binary. When the program runs, the runtime linker, ld.so(8), actually resolves the external symbols from those named libraries.

For the runtime linker to do its work, it must be able to find those libraries. That is where the ELF RPATH comes in. If the library does not reside in the default search path for ld.so(8), it will inspect directories in the RPATH, a property of the executable. In gcc, the RPATH is conventionally set with

-Wl,-rpath=pathname

The search can be further extended using LD_LIBRARY_PATH at time of execution. See ld.so(8) for more information.

Extending runtime linking with COBPATH

When searching for a CALL target, unlike GnuCOBOL, gcobol assumes no relationship between the name of the target the name of the library that might house it. Normally, the names of all required libraries are defined at build time. Those libraries must be found by the runtime linker, and no other libraries are consulted. There is an escape hatch, though: the COBPATH environment variable.

As described in gcobol(1), the value of COBPATH is a colon-separated list of directory names. If present, the gcobol runtime library, libgcobol.so, will attempt to resolve a CALL target by searching all libraries in each named directory. For example,

COBPATH=.

makes all shared objects in the process's current working directory eligible to supply symbols to the program.

ENVIRONMENT

Compile-time variables

gcobol recognizes environment variables for copybooks. Given

COPY copybook library

gcobol will examine the environment for variables named ‘copybook’, ‘COPYBOOK’, ‘library’, and ‘LIBRARY’. If found, the values of those variables are used instead of the literal.

Consistent with gcc practice, gcobol uses no environment variables to control the compiler itself, other than a few easter eggs used by the developers to display details of the compilation process.

Run-time variables

The environment is consulted at runtime to resolve file names. See FILES below.

FILES

gcobol uses no files for configuration.

Programs compiled by gcobol consult the environment to resolve file names. For

SELECT name ASSIGN filename

filename may be a COBOL word or an alphanumeric literal. If it is a literal, it is interpreted literally; relative paths are interpreted as relative to the current working directory of the executing process. If filename is a COBOL word, the gcobol runtime support queries the environment for an uppercase form of the filename. If found, the value of the variable is used as the filename, with relative paths being interpreted just as literal names are. If no environment variable is found, filename is treated as a literal.

The process of interpreting filename is performed for each OPEN operation. Although the functionality has never been tested, in theory it should be possible to OPEN filename, operate on it, CLOSE it, change the value of filename in the environment, and then OPEN a different file.

No transformation done on the text of filename. No prefix is implied and no path is searched.

Compatibility

The on-disk format of files written by programs compiled with gcobol is unique to gcobol. They are incompatible with the on-disk format of any file system supported by GnuCOBOL. Their sole claim is to support the file semantics defined in the ISO standard.

It is an aspiration of the gcobol developers to provide support for I/O plug-in modules in the form of shared objects that implement a defined interface.

SEE ALSO

ld(1)

ld.so(8)

gcobol(1)

GnuCOBOL Programmer’s Guide