Highlighting Compiler and Runtime Options

Source Format

COBOL-IT supports both fixed and free source format. The default format is the fixed format.

Example: Compile a free-format program.

>cobc –free hello.cbl

Example: Compile a fixed-format program

>cobc hello.cbl or
>cobc –fixed hello.cbl

Source Code	Behavior
`-free`	Free format. In Free Format source code, the indicator area is in column 1. Area A starts in column 1, or immediately after an indicator. Area B starts in column 5. The beginning of the Identification Area is marked with a “
`-fixed`	Fixed format. In Fixed Format source code, the indicator area is in column 7. Area A is in columns 8-11. Area B is in columns 12-72. The Identification Area is in columns 73-80. The line ends after 80 characters.

Shared Object or Native Executable

COBOL-IT allows you to compile to a shared object format or to a native executable format. The default format is to compile to a shared object format. Running shared objects requires the COBOL-IT runtime cobcrun, whereas native executables can be run stand-alone.

Example: Compile to a native executable format, and run the executable.

       >cobc -x hello.cbl
       >hello

Example: Compile to a shared object format and run the executable.

       >cobc -m hello.cbl
       >cobcrun hello

Source Code	Behavior
`-m`	Build a dynamically loadable module (default). `-m` compiles, assembles, and builds a dynamically loadable module/shared library. The output is saved in a `.DLL` file on Windows platforms, and in a `.so` file on Linux/Unix platforms.
`-x`	Build an executable program. `-x` builds a native executable. The output is saved in an `.EXE` file on Windows platforms, and in a file with no extension on Linux/Unix platforms.

Locating copy files

The COBOL-IT compiler can be directed to search for copy files in directories named by either the COBCPY, or COB_COPY_DIR environment variable, or with the use of the –I compiler flag. Copy file name resolution is refined with the use of the –ext compiler flag.

By default, the COBOL-IT compiler will search the current directory, and $COBOLITDIR\copy for named copy files, and if the copy files have no explicit file name extensions, the COBOL-IT compiler will search for default copy file extensions.

Default copy file extensions are:
– .CPY
– .COB
– .CBL
– .cpy
– .cob
– .cbl
– no extension

The COBOL-IT compiler will then check the environment variables COBCPY and COB_COPY_DIR for pathes to add to the default search pathes.

At the command line, you may add more directories to search with the –I <directory> compiler flag, and you may add more extensions to the default file extensions searched with the –ext <extension> compiler flag.

Source Code	Behavior
`-ext <extension>`	Add file extension to list of default extensions.
`-I <directory>`	Add `<directory>` to copy/include search path.
`COB_COPY_DIR`	Path where standard copy books are stored by default: `$COBOLITDIR/share/COBOL-it/copy` in Unix/Linux, or `$COBOLITDIR\copy` in Windows.
`COBCPY`	List of directories to search for copy files. Directories are separated by colon “`:`” on Unix machines, by a semi-colon “`;`” on Windows machines.

Example: Consider a case where a program, myprog.cbl has a copy file declared as follows:

COPY “customer.cpy”.

And where customer.cpy is contained in a subdirectory called copy.

       >set COBCPY=.\copy
       >cobc myprog.cbl

Example: Consider a case where a program, myprog.cbl has a copyfile declared as follows:

COPY “customer”.

And where customer.fd is contained in a subdirectory called copy. .fd is not a default extension, so both the directory and the extension need to be given to the compiler, to find the file.

>set COBCPY=.\copy
>cobc –ext=fd myprog.cbl or

>cobc –I .\copy –ext=fd myprog.cbl

Redirecting Output to another Directory

When you compile your source code, you probably will want to create the compiled objects in a separate directory, and run them from this separate directory. To create compiled objects in a separate directory, use the –o compiler flag.

>cobc –o .\object hello.cbl

To run shared objects from a separate directory, set the COB_LIBRARY_PATH environment variable.

In Linux/Unix:

> export COB_LIBRARY_PATH=./object

In Windows:

> set COB_LIBRARY_ PATH=.\object

Execute your program:

>cobcrun hello

To run native executables from a separate directory, set the PATH environment variable.

In Linux/Unix:

       > export PATH=./object:$PATH
       >hello

In Windows:

       >set PATH=.\object;%PATH%
       >hello

Source Code	Behavior
`-o <dir>\|<file>`	Compiler flag. Place the output into `<dir>` or `<file>`.
`COB_LIBRARY_PATH`	Runtime environment variable. Directory where the shared objects that will be executed with `cobcrun` are located.
`COBITOPT`	Compiler environment variable. Compiler flags to be used when running `cobc`, in addition to compiler flags named on the command line. Note that compiler options can be stored in an environment variable called `COBITOPT`. The following are equivalent: `>cobc –o .\object hello.cbl` and `>set COBITOPT=-o .\object` `>cobc hello.cbl`

Calling subprograms

When a COBOL program executes the statement CALL myprog, the COBOL-IT runtime performs the following step to resolve the symbol myprog:

Search pre-loaded modules for the exact symbol. Modules will be pre-loaded by the runtime if they have been named by COB_PRE_LOAD runtime environment variable, and located by the runtime at startup.
Search the running executable for that exact symbol. This search is successful if the call is to a C function that is statically linked to the runtime.
Search the current directory for the shared library myprog.cit. If found, the symbol is further searched for inside the share library. Note that when looking for a shared library, the name of the file searched for can be translated into upper, or lower case using the COB_LOAD_CASE runtime environment variable.
Search the current directory for the shared library myprog.so in Linux/Unix, or myprog.dll in Windows. If found, the symbol is further searched for inside the share library. Note that when looking for a shared library, the name of the file searched for can be translated into upper, or lower case using the COB_LOAD_CASE runtime environment variable.
Search the directory named by COB_LIBRARY_PATH for the shared library myprog.cit. As with the previously described search in the current directory, COB_LOAD_CASE may be used to translate into upper, or lower case.
Search the directory named by COB_LIBRARY_PATH for the shared library myprog.so in Linux/Unix, or myprog.dll in Windows. As with the previously described search in the current directory, COB_LOAD_CASE may be used to translate into upper, or lower case.
If a fully qualified shared library name is given, for example CALL “/mypath/MyFunc.so”, then the runtime searches for the requested file. If found, the runtime then looks for the following symbols:
- base name without extension (MyFunc) .
- base name without extension, upper case (MYFUNC) .
- base name without extension, lower case (myfunc) .

Source Code	Behavior
`COB_PRE_LOAD`	List of external modules pre-loaded at startup. Modules are separated by a colon “:” on Unix machines, by a semi-colon “;” on Windows machines.
`COB_LOAD_CASE`	Runtime environment variable. When set to `LOWER`, the file name is converted to lower case. When set to `UPPER`, the file name is converted to upper case.
`COB_LIBRARY_PATH`	Runtime environment variable. Directory where the shared objects that will be executed with `cobcrun` are located.

Using data files

COBOL-IT supports filename mapping, which allows a rich set of alternatives for aliasing file names in your COBOL programs. In the case where your program contains a statement such as:

ASSIGN TO DATAFILE

You may locate the file in any of the following ways:

Set the environment variable DD_DATAFILE to [ filename ].
Set the environment variable dd_DATAFILE to [ filename ].
Set the environment variable DATAFILE to [ filename ].
Provide a [ filename ] of DATAFILE.
Locate [ filename ] in a directory named by the COB_FILE_PATH environment variable.

Source Code	Behavior
`Filename-mapping:yes`	Compiler Configuration file flag. Enables full set of file aliasing for resolving data file names.
`DD_[filename]`	Runtime environment variable. `[filename]` is named in the `ASSIGN` TO `[filename]` clause. Set to the name of the file that the runtime will search for.
`dd_[filename]`	Runtime environment variable. `[filename]` is named in the `ASSIGN` TO `[filename]` clause. Set to the name of the file that the runtime will search for.
`[filename]`	Runtime environment variable. `[filename]` is named in the `ASSIGN` TO `[filename]` clause. Set to the name of the file that the runtime will search for.
`COB_FILE_PATH`	Path to data files used by the application. `COB_FILE_PATH` is prepended to datafile names by the runtime as it works to resolve filenames and locations.
`COB_FILE_TRACE`	When set to `Y`/`YES`, file tracing information is output to the file named by `COB_ERROR_FILE`, which includes information on how the runtime resolves file names on `OPEN`, and also status codes returned from unsuccessful file `i-o` operations.
`COB_ERROR_FILE`	Specify the filename used to receive all runtime error messages that would otherwise be sent to `stderr`. When writing an error message, the runtime will create the specified filename if it does not exist, and will append to it if it does exist.

Options with multiple source files

COBOL-IT allows you to compile multiple source files into multiple shared objects, multiple source files into a single shared object, multiple source files into a single executable and to use a compiled native executable together with compiled shared objects. This wide range of capabilities gives you a full range of options for the deployment of your application in production.

Multiple source files to multiple shared objects

Example: Compile all programs with the -m option.

In Linux/Unix:

> cobc -m -o ./object main.cbl subr.cbl

This creates shared object files main.so and subr.so' in the ./object folder.

In Windows:

>cobc -m -o .\object main.cbl subr.cbl

This creates dynamic load libraries (DLL’s) main.dll and subr.dll in the .\object folder.

Set the environment variable COB_LIBRARY_PATH to your library directory, and run the main program:

In Linux/Unix:

> export COB_LIBRARY_PATH=./object

In Windows:

> set COB_LIBRARY_PATH=.\object

Execute your program:

>cobcrun main

This causes the shared object main(.so/.dll) to begin executing. When subr(.so/.dll) is called as a subprogram from within main(.so/.dll), it will be located, as it is in the COB_LIBRARY_PATH, and it will be loaded and run.

Multiple source files to a single shared object

Example: Compile all programs with the –b option:

In Linux/Unix:

> cobc -b -o ./object main.cbl subr.cbl

This creates a single shared object file main.so in the ./object folder.

In Windows:

>cobc -b -o . \object main.cbl subr.cbl

This creates a single shared object file main.dll in the .\object folder.

Multiple COBOL source files to a single executable

Example: Compile all COBOL source files with the –x option

In Linux/Unix:

> cobc -x -o ./object main.cbl subr.cbl

This creates a single executable file main in the ./object folder.

In Windows:

>cobc -x -o . \object main.cbl subr.cbl

This creates a single executable file main.exe in the .\object folder.

Using compiled executables with compiled shared objects

You may wish to create a main program as an executable, and have all CALL’ed subroutines be created as shared objects. You would not be required to store the native executable main program in the same directory as the shared objects.

Note

The main native executable would be located by the PATH environment variable and the CALL’ed shared objects would be located by the COB_LIBRARY_PATH environment variable in this situation.

Example: Compile main program as an executable, subprograms as shared objects

In Linux/Unix:

       > cobc -x main.cbl  
       > cobc -m -o ./object subr.cbl

This creates a single executable file main in current working directory, and a single shared object, subr.so in the ./object folder.

In Windows:

       > cobc -x main.cbl
       > cobc -m -o ./object subr.cbl

This creates a single executable file main.exe in the current working directory, and a single shared object, subr.dll in the ./object folder.

Set the environment variable COB_LIBRARY_PATH to your library directory, and run the main program:

In Linux/Unix:

> export COB_LIBRARY_PATH=./object

In Windows:

> set COB_LIBRARY_PATH=.\object

Execute your program:

> . \main

This causes the executable module main (or main.exe in Windows) to begin executing. When subr.so/subr.dll is called as a subprogram from within main, it will be located, as it is in the COB_LIBRARY_PATH, and it will be loaded and run. Note if main is not located in the current directory, then the directory where it is located must be referenced in the PATH environment variable.

COBOL source files and C source files to a single executable

Example: Compile a COBOL source files and a C source file with the –x option

In Linux/Unix:

> cobc -x -o ./object main.cbl subr.c

This creates a single executable file main in the ./object folder.

In Windows:

>cobc -x -o .\object main.cbl subr.c

This creates a single executable file main.exe in the .\object folder.

Separating the compile and link steps

COBOL-IT allows you to separate the compile and link steps. This is done using the –ccompiler flag, which is equivalent to the C compiler –c flag. The program must be linked with the –x option. Note that this could be a useful thing to do, if you need to link a pre-compiled object with your COBOL.

Separate compile and link steps for multiple COBOL source files

Example: Separate the compile and link steps of several COBOL source files

In Linux/Unix:
> cobc -c subr1.cob (produces subr1.o as output)
> cobc -c subr2.cob (produces subr2.o as output)
> cobc -c main.cob (produces main.o as output)
> cobc -x -o ./object main.o subr1.o subr2.o

This creates a single executable file main in the ./object folder.

In Windows:
> cobc -c subr1.cob (produces subr1.obj as output)
> cobc -c subr2.cob (produces subr2.obj as output)
> cobc -c main.cob (produces main.obj as output)
> cobc -x -o ./object main.obj subr1.obj subr2.obj

This creates a single executable file main.exe in the ./object folder.

Linking C and COBOL objects

Example: Using objects created from C and COBOL together

In Linux/Unix:
> cc -c subrs.c (produces subrs.o as output)
> cobc -c main.cob (produces main.o as output)
> cobc -x -o prog main.o subrs.o

This creates a single executable file main in the ./object folder.

In Windows:
> cl -c subrs.c (produces subrs.obj as output)
> cobc -c main.cob (produces main.obj as output)
> cobc -x -o prog main.obj subrs.obj

This creates a single executable file main.exe in the ./object folder.

Building a shared library from COBOL and C routines

Example: Building a shared library combining COBOL and C routines

In Linux/Unix:

       > cobc -c subr1.cob
       > cobc -c subr2.cob
       > cobc -c subr3.c
       > cobc -b -o libsubrs.so subr1.o subr2.o subr3.o

In Windows:

       > cobc -c subr1.cob
       > cobc -c subr2.cob
       > cobc -c subr3.c
       > cobc -b -o subrs.dll subr1.obj subr2.obj subr3.obj

Linking a shared library with your main program

Example: Using a shared library by linking it with your main program

In Linux/Unix:
Before linking the library, install it in your system library directory:

> cp libsubrs.so /usr/lib

or install it somewhere else and set LD_LIBRARY_PATH:

       > cp libsubrs.so /your/COBOL/lib
       > export LD_LIBRARY_PATH=/your/COBOL/lib

Then, compile the main program, linking the library as follows:

> cobc -x main.cob -L/your/COBOL/lib -lsubrs

In Windows:
In Windows, you need to place the shared library (.dll) in your PATH, and then use the link command to locate the .lib file that contains the stub for linking.
Link the library, as follows:

> cobc -x main.cob -LC:\your\COBOL\lib -lsubrs.lib