Skip to content

Standard Flags

Standard compiler flags are applied to COBOL-IT's basic build process, which consists of separate preprocess, translate, compile, assemble, and link steps. These are used to direct the compiler in basic functions such as locating copy files, placing object files, creating listing files, adding error-checks, and adding information required for running with the COBOL-IT debugger.

-b

Links all input files into a single dynamically loadable module.

-c

Compile and assemble, but do not link.

This is equivalent to cc -c (Linux/Unix) or cl -c (Windows).

On Linux/Unix systems, the output is saved in a *.o' file. On Windows systems, the output is saved in a *.obj' file.

-codepage <codepage-id>

Defines the encoding of PIC X in memory.

If -source-codepage is specified, the compiler converts from the codepage-id used in the -source-codepage compiler flag to the codepage-id used in the -codepage compiler flag.

The debugger makes use of the -codepage <codepage-id> compiler flag setting, and converts alphanumeric (PIC X) data to/from UTF-8 when sending data to/from GUI interface.

The conversion of data described with USAGE NATIONAL to PIC X also uses the -codepage <codepage-id> compiler flag setting. The -codepage <codepage-id> compiler flag sets the default code page for National literals (N'xxx') and for conversion DISPLAY-OF and NATIONAL-OF when used without code page indication.

If -codepage <codepage-id> is not specified then if -source-codepage <codepage-id> is specified, the setting of -source-codepage is used for the conversion of data described with USAGE NATIONAL to PIC X.

-conf=[+]<file>

Causes a user-defined compiler configuration file to be referenced either as the default configuration file, or, if the "+" operand is used, as an addition to the base compiler configuration file. For rules on how the base compiler configuration file is set, see the -std=` compiler flag.

-constant "key=value"

Provides a way to define constants that can be tested for purposes of conditional compilation. After using the -constant "key=value" compiler flag, the conditional compilation below will test true.

       $if key=value
       $else 
       $end

-debug

Enables all run-time error checking. See Guidelines for Enforcing Bounds-Checking for more details.

-debugdb [=<DebugDB-name>]

The -debugdb compiler flag causes the compiler to store debugging meta information in an SQLite3 database.

When compiling with -g, the COBOL-IT compiler stores all debugging meta information in the program binaries. This could make programs compiled for debug very huge. In some situations, it could prevent the program from loading into memory.

When used without a filename, and when used with -g, stores all debugging information into a file name <modulenam>.dbd. Copy this file to the same location as the the object file .so or .dll. This will permit the runtime debugger to load the debugging information dynamically when needed.

If you have multiple programs in your project for which debugging information must be stored, you must use -debugdb=<DebugDB-name>, where DebugDB-name is the name of an SQLite3 database that stores metadata for all of the programs in the project.

During a debug session, the runtime debugger will check for the existence of the COB_DEBUGDB environment variable containing the full path to the DebugDB file. If the environment variable is not set, the runtime will attempt to retrieve the location of the COB_DEBUGDB data file from the location of the compiled object.

Currently only 1 database may be used at a time. This means that the Customer must use the same one for all of his programs. Several programs may write metadata to the same database.

-dump-config

Dumps all of the compiler config file settings being used in the compilation session to stdout. The -dump-config compiler flag can be used with or without a COBOL source file.

To dump default compiler configuration file setting to a file: >cobc-dump-config > [dumpfile].

To dump compiler configuration file settings for the current compilation: >cobc [compiler flags] -dump-config hello.cbl >[dumpfile].

-err <file>

Causes errors and warnings to be written to <file> instead of stderr.

-ext<extension>

Adds <extension> to list of default copy file extensions. For example, to direct the compiler to search for copy files with a .fd extension, use the compiler flag -ext fd. Multiple iterations of -ext are used to express multiple non-default copy file extensions. For example, -ext fd -ext sl.

-fixed

Instructs the compiler that source code is in the fixed source format. The -fixed compiler flag is assumed, by default.

-free

Instructs the compiler that source code is in the free, or terminal source format.

-g

Produce debugging information in the output.

-initcall=<program-name>

The initcall compiler flag names modules to be called immediately before the first statement of a program is executed.

-l <lib>

Causes the library <mylib> to be used by the linker.

Note

The linker will look for mylib in the path indicated by the -L compiler flag.

-linkage-desc=[program.xsd]

Generates an XSD file from the Source file. This process parses the program, and records the names of the entry points, and for each entry point, the linkage section items. This information is stored in an XML format in a file with a .xsd extension. The -linkage-desc compiler flag is invoked in the Developer Studio Web Services Perspective, when generating an XSD.

Command-line usage: > cobc -linkage-desc=[programname].xsd [programname].cbl

-m

Builds a dynamically loadable module. The -m compiler flag is implied by default.

-makesyn "oldvalue=newvalue"

Provides a way to make a reserved word a synonym for another reserved word. The first word, represented by "oldvalue" becomes a synonym of the second word, represented by "newvalue". A common usage is to make COMP a synonym of COMP-5. To do this:

>cobc -makesyn comp=comp-5 hello.cbl

The -makesyn "oldvalue=newvalue" compiler flag provides compatibility with the MAKESYN directive.

A COBOL verb or field-name may be used as "old-value". The COBOL-IT compiler will replace all instances of this "old-value" with the "new-value" when compiling.

Warning

While this provides an equivalent capability to the implementation of the MAKESYN directive in other COBOLs, the order of the parameters is reversed. COBOL-IT requires that the "old-value" be listed first, and followed by the "new-value".

-o <file> | <dir>

Causes a compiled object to be output into <file> or <directory>. When using a directory name, standard naming conventions are used, and the output is written to the named directory.

-preprocess=<CMD> [input file]

Causes <CMD> to be run after the COBOL pre-processing step. <CMD> is a script of batch file in which an external pre-processor is run.

Consider an example, related to the use of Pro*COBOL. A simple Pro*COBOL script would be:

procob iname=%1 oname=%2

Where INAME would be the input file, which needed to be preprocessed, and ONAME would be the resulting output file. To cause the COBOL-IT precompiler to run its precompilation prior to calling this script, run the script in a .BAT file (in Windows), and invoke as follows:

cobc -preprocess=myprocob.bat mysource.cbl

For more detail, see Guidelines for use of -preprocess=cmd for more details. The -preprocess compiler flag is only available in the Enterprise Edition of the Compiler Suite.

-save-temps (=<dir>)

Causes all intermediate files to be preserved.

Note

"intermediate files" are the C source and header files that are created during the compilation process. These files will be located in a subdirectory named "c", when using the -save-temps compiler flag.

-source-codepage <codepage-id>

Defines the code page to be used when editing the source and the code page used for string literals in the COBOL source code.

When used with -codepage <codepage-id>
If -source-codepage is specified, the compiler converts from the codepage-id used in the -source-codepage compiler flag to the codepage-id used in the -codepage compiler flag.

When used without -codepage <codepage-id>
If -codepage <codepage-id> is not specified then if -source-codepage <codepage-id> is specified, the setting of -source-codepage is used for the conversion of data described with USAGE NATIONAL to PIC X.

-std=<dialect>

Causes one of the dialect-oriented compiler configuration files to be used instead of the default compiler configuration file. COBOL-IT provides several dialect-oriented compiler configuration files, which can be located in $COBOLITDIR/share/COBOL-it/config/*.conf on Unix/Linux-based systems and in %COBOLITDIR%\config\*.conf on Windows-based systems.

For a specific dialect:

   COBOL2002   COBOL 2002
   ----------- ---------------------------
   COBOL85     COBOL 85
   ibm         IBM Compatible
   mvs         MVS Compatible
   bs2000      BS2000 Compatible
   mf          Micro Focus Compatible

For example: >cobc -std=ibm hello.cbl causes the compiler to select the file ibm.conf as the standard compiler configuration file, instead of default.conf.

-sysin=<input file>

Allows redirection of ACCEPT statements at compilation time. <input file> is the file used by ACCEPT instead of the console. It must be a line sequential file.

For example:

cobc -sysin=sysin.txt testit.cbl

-sysout=<output file> [,S/L [,Min [,Max]]]

Allows redirection of DISPLAY statements at compilation time. <output file> is the file used by DISPLAY instead of the console. By default, <output file> is created as a line sequential file.

The -sysout compiler flag provides compatibility with the OUTDD compiler directive supported by some other COBOL compilers.

For example:

-sysout=sysout.txt testit.cbl

  • When <output file> exists, output is appended to the existing file.

  • When <ouput file> does not exist, it is created in the current working directory. When dot '.' is used as a file name, sysout is sent to stdout.
    As an example:
    -sysout=.,SEQ,100 produces output on stdout as a sequential record of 100 bytes.

Use the S flag, in conjunction with the Min/Max flags to cause <output file> to be created as a binary sequential file, with minimum and maximum record lengths.

Use the L flag optionally. You may use the Min/Max flags with the L flag. For the case where an output string exceeds a maximum record length, a line feed (Linux/Unix) or CR/LF (Windows) is inserted after a maximum length has been reached, and the output string is then continued.

For example: -sysout=sysout.txt testit.cbl The -sysout compiler flag supports a file name of dot '.' . When dot '.' is used as a file name, sysout is sent to stdout.

As an example: -sysout=.,SEQ,100 produces output on stdout as a sequential record of 100 bytes.

General Format: -sysout=filename [,S/L [,Min [,Max]]]

Syntax:

  1. "," may be replace by ":"
  2. No spaces are allowed in the compiler command
  3. S = Sequential (Binary Sequential)
  4. L = Line Sequential
  5. If a Max value is not given for Sequential files, then Max = Min.
  6. If a Max value is not given for Line Sequential files, then Max = Min, and Min = 0.

General Rules:

  1. The runtime will write as many records as needed.
  2. If the data written is smaller than the Min value, then the runtime will pad the output with SPACES up to min-length in the line-sequential output file, and the runtime will pad the output with LOW-VALUES up to min-length in the sequential (binary sequential) output file.

-t <file> | <dir>

Causes a program listing to be output into <file> or <directory>. When using a directory name, standard naming conventions are used, and the output is written to the named directory with a .lst extension.

The listing file produced by the -t compiler flag includes memory mapping information. At the end of the listing, in lines that are commented, the list file reports the size and offsets of the data fields in the Working-Storage Section.

The listing file produced by the -t compiler flag preserves comments, and can be compiled by the COBOL-IT compiler.

When a compilation string designates no configuration file, and when not using the -E compiler flag, the settings of the default.conf file are printed to the listing file that is named, or implied when using the -t compiler flag.

When a compilation string designates a configuration file, using the conf=xxx.conf compiler flag, then the settings of the named compiler configuration flag are printed in the listing file that is named or implied when using the -t compiler flag.

When using the -b compiler flag to combine several programs into a single library, and using the -t [ filename ] compiler flag, a single listing is created that includes all of the programs in the library.

-use-extfh <name>

Names an EXTFH File handler to be used, enabling the use of an external file system.

-use-extsm <name>

Runtime module to be used, enabling the use of an external sort handler.

-v

Produces verbose output. The output of the -v compiler flag displays, all of the steps, and intermediate programs created by the compilation.

-x

Builds an executable program.

The executable produced with the -x compiler flag includes the main function in the output. This option takes effect at the translation stage. If you compile with -x -C, you will see the main function at the end of the generated C file.

Warning

When using -x, the first source module or object (.o on UNIX or .obj on windows) given on the command line MUST be the main module of the program. All other modules, libraries or object files may follow in any order.
For example: cobc -x mymain.cob other1.cob ...

-xdd-prefix=<dir>

Causes the XDD file created with the -fgen-xdd compiler flag to be stored in the directory named in <dir>. The folder name described in <dir> must be followed by a slash "/" in Unix/Linux, or a back-slash "\" in Windows.

As an example: >cobc -fgen-xdd -xdd-prefix=/my/doc/xdd/ hello.cbl causes all xdds generated in the compilation to be stored in the /my/doc/xdd/ folder.

-C

Interrupts the compilation after converting COBOL to C. The output is saved in files with different extensions:

  • .c Files with extension .c hold the main code.
  • .c.h Files with extension .c.h hold the COBOL field storage.
  • .c.d.h Files with extension .c.d.h hold debug information.
  • .c.l.h Files with extension .c.l.h hold temporary fields.

-D <define>

Passes <define> to the "C" Compiler.

-E

Interrupts the compilation after the preprocessing of the COBOL code, without doing any translation to "C", compilation, assembly, or linking. The preprocessed code is output to stdout by default, and reproduces the preprocessed COBOL source code.

Output from the -E compiler flag retains the format (free or fixed) of the original source code.

Note

Using the -E compiler flag, the references to expanded copy files includes path information on the commented-out reference to the copy file. As an example, in the sample below, the program was compiled with -I .\copy -ext sl. Note that the path to the SELECT statement is preserved:

      *"./copy/reswords.sl"
      *
       SELECT reswords ASSIGN TO "reswords"
       ORGANIZATION IS INDEXED
       ACCESS IS DYNAMIC
       RECORD KEY IS reserved-word
       FILE STATUS IS reswords-stat.

-G

Produces debugging information in the output, allowing "C"-level debugging.

To perform "C" level debugging, use the COBOL-IT Developer Studio.

COBOL-IT translates COBOL to "C" and uses the host "C" compiler to compile the translated source. As preparation, compile your COBOL programs with the -G compiler flag. "C" modules should be compiled for debugging as well.

The -G COBOL compiler flag allows the COBOL program to be include information for the "C" debugger. This corresponds to the gcc -g compiler flag.

Using the Debug Attach functionality of the Developer Studio to Attach the COBOL Debugger to an Application, you can enter the COBOL Debugger, then start the "C" debugger, and proceed your debugging with both the "C" and COBOL debuggers running.

The Eclipse IDE for C/C++ Developers, and "C" compiler are required for this exercise.

-I <path>[,ext1,ext2,.,extn][@<LibName>] |<command-file>

Where: Description
<path> is the path that the compiler will search for the COPY file.
ext1,ext2,…extn are file extensions to be included when performing the search for the COPY file.
@ represents the “@” character, which is placed before <LibName>
<LibName> is the Library named in a COPY statement that contains a reference to a Library.
For example:
COPY <filename> IN/OF LibName.
<command-file> is the name of an existing file. When –I is followed by the name of an existing file, that file is read, and each line is treated as a parameter of the –I compiler flag.

For more details, and rules governing the treatment of file extensions, and rules applying to the COPY IN/OF LIBNAME syntax, see Guidelines for Searching and Locating COPY files.

-L <directory>

Adds <directory> to the library search path.

-MF <file>

Writes dependency list into <file>.

-MT <target>

Names the target file used for the dependency list.

-O, -Os, -O2

Enables optimization.

Note

-O, -Os and -O2 are passed to the "C" compiler as is and used for "C"-level optimization. For more details on the usage of the optimization compiler flags, see the Guidelines for use of the Lib Optimizer below.LINK

The -O and -O2 compiler flags now automatically enable the following compiler flags by default:

  • -fbin-opt
  • -fcmp-opt
  • -fcmp-inline
  • -ffp-opt
  • -foptimize-move
  • -foptimzize-move-call
  • -ffast-op
  • -findex-optimize
  • -fdecimal-optimize

For more details about each of these optimizing compiler flags, see below.

-R <directory>

Adds <directory> to runtime library search path (if supported).

-S

Interrupts the compilation after output of the assembly file. Translated C files are compiled By cc. The output is saved in a file with a .s extension. The -S compiler flag is only available when using the gcc C compiler.

-Wc CC_opt

Passes CC_opt directly to the C Compiler.

CC_opt is a compiler flag, or string, that can be processed by the C compiler. As an example, the command: >cobc -Wc -O2 hello.cbl affects the manner in which the C compiler command-line is built, adding -O2 to the compile string.

To view the C compiler command-line that is built by the COBOL-IT compiler, add the -v compiler flag to the compile string.

   >cobc -v hello.cbl
   …
   cobc:0: cl /c /I "C:\Cobol\CobolIT\include" /DCOB_HAS_THREAD 
   /W0 /nologo /GF /MD /Fo"hello.obj" "C:\Users\ROBERT~1\AppData
   \Local\Temp\cob652217784_5.c" cob652217784_5.c
   …

-Wl LD_opt

Passes LD_opt directly to the Linker.

LD_opt is an option, or string that can be processed by the Linker.

To view the link command-line that is built by the COBOL-IT compiler, add the -v compiler flag to the compile string.

   >cobc -v hello.cbl
   …
   cobc:0: link /DLL /MANIFEST /out:"hello.dll" /nologo "hello.obj" 
   "C:\Cobol\CobolIT\lib\libcobit_dll.lib" /DEFAULTLIB:MSVCRT.LIB
Back to top