Linking to System Executables

Descriptions of cob Flags

Chapter 10: COBOL System Interface (Cob)

This chapter describes how to use the Cob utility. This utility provides the interface to the Compiler and system linker. This interface enables you to handle all the phases involved in the production of an executable program.

10.1 Introduction

The Cob utility enables you to handle all the phases involved in the production of an executable program by providing the interface between your COBOL source program and the following COBOL system components:

• The Compiler - to syntax check and compile your COBOL source files into .int files, and to generate the .int files into .gnt files or object code .o files
  
  
• The system linker - to link object code into a callable shared object, shared library or system executable file.

It also provides an interface to the C++ compiler, cc (the C compiler) and as (the Assembler).

10.2 Using Cob

You start and control the Cob utility using the cob command. cob causes the files named on its command line to be processed with the aim of producing modules that can be linked or run.

There are five basic types of executable COBOL program; the cob command provides a straightforward means of creating a mixture of any of these types of program. The executable files types are:

• Callable shared object files
  
  
• Intermediate code files
  
  
• Generated code files
  
  
• Shared library files
  
  
• System executable files

Callable shared object files, intermediate code files (.int files) and generated code files (.gnt files) are dynamically loadable, and do not have to be linked into a system executable to be executed.

Shared libraries are system linkable files that can be linked into executable files. They cannot be directly executed themselves.

System executable files are files in an operating system format that are directly executable. They are loaded by the operating system, which creates a new process in which to run them.

For detailed information on the types of executable file, see the chapter Packaging Applications.

The type of file output by cob depends on the type of file you input to it and the options you specify to the cob command. The file types recognized by cob are identified by their extensions as follows:

Cob assumes that any unrecognized options are either input files or valid linker options to be saved and used at link time. In this way, any archive files you supply to the cob command are passed to the linker, which pulls out only the referenced files from the archive.

You can use COBOL source files with extensions other than those listed above. To do so, you must specify the -k cob flag to identify them to cob (see the chapter Descriptions of cob Flags for details).

10.2.1 Invoking the Cob Utility

To invoke the Cob utility, enter the following at the UNIX system prompt:

cob [options|filename] ...

where the parameters are:

10.2.2 Specifying cob Options

A cob option takes the form:

flag-intro flag-letter [parameter]

A group of cob options is equivalent to a separate option for each flag-letter with all options having the same intro. The parameter, if present, only apply to the last option. It takes the form:

flag-intro flag-letter[flag-letter]... [parameter]

where the parameters are:

There must be no spaces between flag-intro and flag-letter or between two adjacent flag-letters but there can be one space between the last flag-letter and the parameter if it is present. (For example -xve "" in which "" represents a null parameter). The flag-intro must always be preceded by a space character.

10.2.2.1 Option Configuration

You can specify cob options in a number of ways, and the method used determines the order in which cob processes them. The cob command processes options from left to right for each method of specifying them. In general, if an option appears more than once, cob uses the setting that it processed last for that option. Some options, such as -C and -N that take Compiler directives, are cumulative.

At start-up, the cob command searches for options in the following sequence of locations:

1. System default options in the file $COBDIR/etc/cobopt
   
   
2. User default options in the environment variable COBOPT
   
   
3. Execution-time options on the cob command line

You might need to set options as a system or user default and then to unset them again in specific instances. By specifying a hyphen after the flag letter with no intervening space, you can unset the following options: -c, -P and -U.

Options specified on the cob command line pass through the UNIX shell that carries out special processing on certain characters such as space, asterisk (*), parentheses (), single (') and double (") quotation marks before passing them to cob. If you need to pass these characters unchanged as part of an option, you must escape the shell processing. Under the UNIX shell this can be done by preceding the character with a backslash (\) or enclosing it in a pair of single or double quotation marks (see your UNIX system documentation for details of shell processing).

However, for your convenience cob enables you to use the syntax mode=setting in place of either "mode(setting)" or mode\(setting\) so enabling you to avoid these characters. The cob command converts any syntax using the equals sign (=) into the form "mode(setting)". To pass an actual equals sign (=) to the COBOL components, you must use two equals signs together (==).

Note: The cob command treats the special characters single and double quotation marks in exactly the same way when used in an option, regardless of whether the option was specified on the command line or in one of the other locations. A parameter enclosed in a pair of quotation marks must not exceed 128 characters.

Example:

Assuming the following line in $COBDIR/etc/cobopt:

-U -P -C "ans85 noalter warning=1"

specifying the cob command line:

cob -xU -C alter -C warning=2 prog.cbl

or the exact equivalent:

cob -xU -C "alter warning=2" prog.cbl

passes the COBOL source file prog.cbl to the Compiler with the final directive settings of ANS85 ALTER LIST"prog.lst" WARNING"2". An executable program prog is built, with any unresolved symbols being dynamically loaded at run time and flagged as missing at link time.

10.2.2.1.1 The $COBDIR/etc/cobopt File

System-wide default options are defined in the file $COBDIR/etc/cobopt. This is the file the cob command reads when first invoked. Each line of this text file should correspond to one of the following formats:

[set environment-variable=value]
[options] ...
[cobextn: .ext [.ext] ... ]

where the parameters are:

If a line does not begin with one of the identifiers set or cobextn:, it is taken as an options line.

Note: The contents of the file $COBDIR/etc/cobopt affect the operation of COBOL for all users using the same $COBDIR; you should alter the file only after careful consideration of the implications.

Example

Assuming the following two lines in $COBDIR/etc/cobopt:

cobextn: .AD  .FD 
-N "nobound" -C ans85

specifying the cob command line:

cob -u a.FD b.AD

passes the COBOL source files a.FD and b.AD to the syntax-check phase of the Compiler to be translated, under the ANS85 directive, into intermediate code. The intermediate code is then passed in turn to the Compiler's generate phase to be translated, under the NOBOUND directive, into generated code.

10.2.2.1.2 The COBOPT Environment Variable

User default options are defined using the COBOPT environment variable. COBOPT can either contain options that supplement or override the system default options defined in $COBDIR/etc/cobopt, or it can specify the path of a file that contains such options. The options can extend over more than one line and each line must have the same format as described for the file $COBDIR/etc/cobopt (see the section The $COBDIR/etc/cobopt File).

The COBOPT environment variable can be set to a value that includes several lines by enclosing the entire value in single (') or double (") quotation marks that tells the UNIX shell to process each line as part of the one value. Under the Bourne shell, the Enter key can be typed to indicate the line-break. However, other types of shell might need a different way of showing the line-break. If you want to include a double quotation mark in the value, then remember to escape shell processing, for example by preceding it with a backslash (\) character.

See your UNIX system documentation for details of setting environment variables and shell processing.

You can include any valid cob command line in the COBOPT environment variable. If the line includes the -v cob flag, the whole line is echoed to the screen when it is passed to cob (see the chapter Descriptions of cob Flags for details on -v).

Examples:

Specifying COBOPT as follows:

COBOPT="set COBCPY=/usr/lib/cblcpy:$COBDIR/cpylib:$HOME/mylib::
-N nobound -C \"ans85 noalter list\"
cobextn: .AD .FD"
export COBOPT

causes cob to set the environment variable COBCPY for the duration of the cob command, it passes the directives ANS85 NOALTER LIST to the Compiler's syntax-check phase and passes the directive NOBOUND to the Compiler's generate phase. Note that $COBDIR and $HOME get expanded by the shell if the double quotation marks are used but not if single quotation marks are used.

Specifying COBOPT as follows:

COBOPT='-C "copyext=CPY,cpy nooptional-file" -N "nobound"'

causes cob to pass the directives COPYEXT"CPY,cpy" and NOOPTIONAL-FILE to the Compiler's syntax-check phase and the NOBOUND directive to the Compiler's generate phase.

10.2.2.1.3 The cob Command Line

Execution-time options (that is when cob executes, not when the application runs) are specified on the cob command line as described in the section Invoking the cob Command. Options given on the cob command line supplement or override any already specified in the $COBDIR/etc/cobopt file or COBOPT environment variable.

You can specify on the command line any cob options listed in the section cob Flags later in this chapter and described in more detail in the chapter Descriptions of cob Flags.

Example

Assuming neither $COBDIR/etc/cobopt nor $COBOPT exist, specifying the following on the cob command line:

cob -xve "" -o my_rts -C xopen prog.cbl prog2.c

passes the XOPEN directive to the Compiler and instructs cob to compile the COBOL source file prog.cbl and the C source file prog2.c and to link the result into a system executable file named my_rts that, when run, expects the name of the program to run to be given on its own command line. The cob utility also gives verbose notification of its progress.

See the section Command Line Examples later in this chapter for further examples.

10.2.3 cob File Processing

While creating an executable module, the cob command passes each input program through a series of steps, each of which transforms the program from one file type into another file type. Thus, an output file from one step can serve as an input file for a subsequent step. These types are characterized by the file extensions as follows:

By default, cob processing ends when all COBOL source files have been compiled for animation; that is, a dynamically loadable intermediate code file (with extension .int) and an Animator file (with extension .idy) have been created. Other end points can be specified by using cob options (see the section cob Flags later in this chapter).

If any of the input files are beyond the desired end point, cob links them with the dynamic loader. This produces a system executable run-time system, that can be used to load and run any dynamically loadable files.

Any temporary files produced at any of the intermediate stages of processing are removed once used, with the exception of any .int and .o files, that are left in the same directory as their input file.

A linked or dynamically loadable COBOL program, can access (using the COBOL CALL verb) any other linked or dynamically loadable module in the application. For details on creating these types of modules, see the chapter Linking to System Executables.

Note: On file systems that support long filenames, you are recommended to keep the length of program source filenames below the entry point name limit. See the chapter Linking to System Executables for further details.

10.2.4 Accessing the COBOL System Components

To access COBOL system components, the cob command must know where they are located. They must all be located in a directory in which a COBOL system has been installed and the directory is represented in this chapter as $COBDIR. The cob command assumes a default $COBDIR directory of /usr/lpp/cobol on AIX, or /opt/lib/cobol otherwise. If your COBOL system has been installed here then you do not need to specify the COBDIR environment variable. If you put the Micro Focus COBOL system software elsewhere, then you must set the COBDIR environment variable to tell cob in which directory to search for the system components. You can choose to install different versions of the COBOL system on your machine, in which case you select which one to use by simply setting its location in COBDIR. For example:

COBDIR=/home/products/cobse10
export COBDIR

specifies that the system components are located in the directory /home/products/cobse10. If the cob command is not on the UNIX search path then you must change the value of PATH. For example:

PATH=$COBDIR/bin:$PATH
export PATH

You should ensure that LIBPATH (on AIX), SHLIB_PATH (on HP/UX systems) or LD_LIBRARY_PATH (otherwise), is set to $COBDIR/lib.

By default, files output by the cob command are put in the current directory. By default, any temporary files created are put in the system temporary directory; however, you can put them elsewhere by setting the TMPDIR environment variable and specifying a valid pathname. See the appendix Micro Focus Environment Variables for details on using TMPDIR.

10.2.5 cob Flags

The following flags can be used with the cob command to specify any action the system components should take while creating an executable module and to determine the type of file output. For full details on the effect of these flags, see the chapter Descriptions of cob Flags.

Any options that are not recognized are passed to the system linker (ld). However, we recommend you use the -Q flag to explicitly pass options to the linker. Any linker flags that take parameters must be passed using the -Q flag.

cob flags -c, -P and -U are binary global options (that is, they select features that can potentially affect several of the input files). Any of these options can be turned off once selected by appending a hyphen (-) to the option letter. This enables any global binary options selected in the system $COBDIR/etc/cobopt file to be overridden.

10.2.5.1 Command Line Examples

These examples show several uses of the cob command to compile, code generate and link programs.

• To compile the program in pi.cbl into a file called pi.int suitable for animation, specify:

  cob pi.cbl

  As this is the default case, the -a flag does not need to be specified.

• To syntax-check, generate and then link the COBOL source file pi.cbl to the run-time support libraries to form a system executable file named pi, enter:

  cob -x pi.cbl

• To compile the COBOL source file pi.cbl for the unlinked environment to produce an intermediate code file, pi.int, enter:

  cob -i pi.cbl

  This differs from the default case, shown in the first example, because an end point has been specified. In this case pi.int is not suitable for animation.

• To syntax-check and generate the program in pi.cbl into a dynamically loadable .gnt file, enter:

  cob -u pi.cbl 

• To syntax-check and generate the program in pi.cbl into a dynamically loadable callable shared object file, enter:

  cob -z pi.cbl 

• To build an executable run-time system that contains C routines enter:

  cob -xo newrts routines.c

• To syntax-check, generate and link a callable shared object file that contains C routines, enter:

  cob -z myprog routines.c 

For details on how to execute the files produced using the cob command, see the chapter Running. See also the chapters Creating Programs, Callable Shared Objects and Linking to System Executables for additional details.

10.2.6 Interface to Compiler

The cob command is used to interface to the COBOL compilation system. Compiler directives can be specified in a variety of ways, including via cob and via the program source files. The following sections describe all the ways that Compiler directives can be specified.

10.2.6.1 Program Source Conventions

The Server Express COBOL Compiler accepts source from a standard UNIX text file (as created by a UNIX editor such as vi). The format of this is the same as for standard COBOL, described in your Language Reference.

Each line of your COBOL source programs, including the last line, must be terminated by a new line character.

Your COBOL source programs must not contain any control characters (characters with hexadecimal values x"00" to x"1F" inclusive, or x"7F") except the tab character, unless they are embedded in literal strings. Tab is expanded with spaces to the next character position that is a multiple of eight.

10.2.6.2 Specifying Compiler Directives

You can specify Compiler directives in a number of ways, and the method used determines the order in which the Compiler processes them. The Compiler processes directives from left to right for each method of specifying them. If a directive appears more than once, the Compiler uses the setting that it processed last for that directive. The Compiler searches for directives in the following sequence of locations:

1. COBOL system default directives in the file cobol.dir
   
   
2. System default directives contained in cob options in the file $COBDIR/etc/cobopt
   
   
3. User default directives contained in cob options in the environment variable COBOPT
   
   
4. Compile-time directives contained in cob options on the cob command line
   
   
5. Program-specific directives in the initial $SET statements in the source code file of each program

These methods are listed in the order in which the Compiler processes directives for each COBOL source file. This order of precedence means that a directive set on the command line would override another setting for that directive set in cobol.dir. For example, specifying the NOANS85 Compiler directive on the command line overrides ANS85 in cobol.dir.

You can further customize the Compiler's behavior by creating your own directives file; that is, an ASCII text file in which is defined an entire set of directives to be passed to the Compiler at one time. You can use either the DIRECTIVES or USE directive to pass this user directives file to the Compiler. You can determine the precedence for processing your directives file by specifying the DIRECTIVES or USE directive by any of the methods described above. See the section The DIRECTIVES and USE Directives later in the chapter.

Parameters to directives given in a $SET statement are converted to upper case; parameters to directives given on the cob command line or in a directives file retain their case.

The methods of specifying cob options and of specifying Compiler directives in cob options are given earlier in the section Invoking the cob Command. The additional methods of specifying Compiler directives are described in the following sections.

10.2.6.2.1 The cobol.dir Directives File

cobol.dir is a directives file that is processed automatically by the Compiler, as if the directive:

directives"cobol.dir"

were encountered by the Compiler as the very first directive after start-up. Consequently, Compiler directives contained in cobol.dir override the defaults built into the Compiler but can be overridden in turn by directives specified in the ways listed above. Generate phase directives cannot be specified in the cobol.dir directives file.

The Compiler looks for a cobol.dir file first in the current directory. If it finds one there, it uses it. Otherwise, it looks in the COBOL system directory $COBDIR.

If the Compiler rejects a directive contained in the cobol.dir file, compilation continues. However, if the Compiler rejects directives from either the command line or a directives file specified on the command line, compilation terminates. Therefore, if you create or change a cobol.dir file, you should do a trial compilation and watch for "rejected" messages at the beginning when the directives are being processed. If any occur, correct the cobol.dir file and retry until no errors are reported.

10.2.6.2.2 The $SET Statement

Many Compiler directives can be specified in the program source code in $SET statements. Compiler directives specified in this way supplement or override options specified in $COBDIR/etc/cobopt or in COBOPT. Generate phase directives cannot be specified using $SET statements.

You specify the $SET statement in the following format with the $ character in column 7:

$SET directive["parameter"] ... 

where the parameters are:

The $ character must be in column 7; if it is not, the Compiler does not recognize it and can produce spurious errors. The same is true for any character at the start of a source file that the Compiler does not recognize. Additionally, the $SET statement must not be terminated with a period (.).

If more than one directive is specified they must be separated by spaces. A $SET statement cannot be continued onto a new line, but it can be followed by additional $SET statements.

You can specify any number of $SET statements in your source code, and these can appear anywhere in the code. If you want to specify a dialect-controlling Compiler option, for example ANS85, this must be on an initial $SET statement; that is, one that is not preceded in the source file by any source statements except other $SET statements. Once you have set a dialect-controlling option at the beginning of your source code, you cannot unset it later in the program. When a directive is specified on a $SET other than an initial $SET, it affects compilation from the point the $SET is encountered onwards.

The chapter Directives for Compiler indicates which Compiler directives are allowed on $SET statements, distinguishing those only allowed on initial $SET statements.

Examples:

Both of the following examples have the same effect: they cause the Compiler to assume all file assignments to data names are resolved externally and to flag features in your program that are not in the ANSI'85 dialect of the COBOL language:

$SET assign(external) flag(ans85)

$SET assign "external" flag"ans85"

10.2.6.2.3 The DIRECTIVES and USE Directives

The DIRECTIVES and USE Compiler directives enable you to pass to the Compiler a user file containing a predefined set of directives. You can specify the DIRECTIVES or USE directive on the command line, in a $SET statement, in the cobol.dir file or in the $COBDIR/etc/cobopt file. Generate phase directives cannot be specified using DIRECTIVES or USE directives. The format for these directives is:

directives "filename"

or:

use "filename"

where filename is the name of the user file containing the set of directives you want to pass to the Compiler. It can be any valid filename except cobol.dir or $COBDIR/etc/cobopt.

A directives file is a standard ASCII text file containing any number of lines. Each line can contain one or more directives or comments. Directives in the directives file must be separated by a space and cannot be broken across two lines. Comment lines are indicated by an ampersand character (&) in column 1.

The Compiler reads the directives from the file until the end of file (EOF) is reached or another DIRECTIVES or USE Compiler directive is encountered.

If you specify the DIRECTIVES directive in another directives file, the Compiler switches to the new directives file for processing and then returns to the original directives file. When the Compiler completes processing the directives file, it then processes subsequent directives on the command line or in $SET statements.

Directives in a directives file are processed as if they were coded in place of the DIRECTIVES directive. Consequently, restrictions applying to any directive at that time also apply to all the directives in a directives file read at that time. See also the chapter Directives for Compiler.

Linking to System Executables

Descriptions of cob Flags