HP OpenVMS Systems Documentation

HP COBOL
User Manual

You can specify object libraries on the COBOL command line by using certain flags or by providing the file name of the library. These object libraries are also searched by ld for unresolved external references.

When cobol specifies certain libraries to ld , it provides a standard list of COBOL library file names to ld . The ld linker tries to locate each of these library file names in a standard list of library directories. That is, ld attempts to locate each object library file name first in one directory, then in the second, and then in the third directory on its search list of directories.

To display a list of the compilers invoked, files processed, and libraries accessed during linking, specify the -v flag.

In addition to an object file created by the compiler, any linker flags and object files specified on the cobol command are also passed to the ld linker. The linker loads object files according to the order in which they are specified on the command line. Because of this, you must specify object libraries after all source and object files on the cobol command line.

To help identify undefined references to routines or other symbols in an object module, consider using the nm command. For instance, in the following example the nm command filtered by the grep command lists all undefined (U) symbols:

% cobol -c ex.cob
% nm -o ex.o | grep U

If the symbol is undefined, U appears in the column before the symbol name. Any symbols with a U in their names can also be displayed by this use of grep .

1.1.3.2 Specifying Additional Object Libraries

You can control the libraries as follows:

• To specify additional object library file names for ld to locate, use the -l string flag to define an additional object library for ld to search. Thus, each occurrence of the -l string flag specifies an additional file name that is added to the list of object libraries for ld to locate. The standard COBOL library file names searched (shown in the form of the appropriate -l string flag) are:

  -lcob
  -lcurses
  -lFutil
  -lots2
  -lots
  -lisam
  -lsort
  -lexc
  -lm

  
  For instance, the file name of -lcob is libcob .
  The following example specifies the additional library libX :

  % cobol simtest.cob -lX

• In addition to the standard directories in which ld tries to locate the library file names, you can use the -L dir flag to specify another directory. The -l string flag and -L dir flag respectively adds an object library file name ( -l string) or directory path ( -L dir) that ld uses to locate all specified library files. The standard ld directories are searched before directories specified by the -L dir flag.
  The following example specifies the additional object library path /usr/lib/mytest :

  % cobol simtest.cob -L/usr/lib/mytest

• You can indicate that ld should not search its list of standard directories at all by specifying the -L flag. When you do so, you must specify all libraries on the cobol command line in some form, including the directory for cobol standard libraries. To specify all libraries, you might use the -L flag in combination with the -L dir flag on the same cobol command line.
• You can specify the pathname and file name of an object library as you would specify any file. Specifying each object library that resides in special directories in this manner is an alternative to specifying the library using the -l string or -L dir flag. This method can reduce the amount of searching the linker must do to locate all the needed object files.
  In certain cases, you may need to specify the pathname and file name instead of using the -l string or -L dir flags for the linker to resolve global symbols with shared libraries.

When processing a C source file ( .c suffix) using the cobol command, you may need to specify the appropriate C libraries using the -l string flag.

1.1.3.3 Specifying Types of Object Libraries

Certain cobol flags influence whether ld searches for an archive ( .a ) or shared object ( .so ) library on the standard list of COBOL libraries and any additional libraries specified using the -l string or -L dir flags. These flags are the following:

• The -call_shared flag, the default, indicates that .so files are searched before .a files. As ld attempts to resolve external symbols, it looks at the shared library first before the corresponding archive library. References to symbols found in a .so library are dynamically loaded into memory at run time. References to symbols found in .a libraries are loaded into the executable image file at link time. For instance, /usr/shlib/libc.so is searched before /usr/lib/libc.a .
• The -non_shared flag indicates that only .a files are searched, so the object module created contains static references to external routines and are loaded into the executable image at link time, not at run time. Corresponding .so files are not searched.
  The following example requests that the standard cobol .a files be searched instead of the corresponding .so files:

  % cobol -non_shared mainprog.cob rest.o

External references found in an archive library result in that routine being included in the resulting executable program file at link time.

External references found in a shared object library result in a special link to that library being included in the resulting executable program file, instead of the actual routine itself. When you run the program, this link gets resolved by either using the shared library in memory (if it already exists) or loading it into memory from disk.

1.1.3.4 Creating Shared Object Libraries

To create a shared library, first create the .o file, such as octagon.o in the following example:

% cobol  -O3 -c octagon.cob

The file octagon.o is then used as input to the ld command to create the shared library, named octagon.so :

% ld -shared -no_archive octagon.o \
     -lcob -lcurses -lFutil -lots2 -lots -lisam -lsort -lexc -lmld -lm

A description of each ld flag follows:

• The -shared flag is required to create a shared library.
• The -no_archive flag indicates that ld should not search archive libraries to resolve external names (only shared libraries).
• The name of the object module is octagon.o . You can specify multiple .o files.
• The -lcob and subsequent flags are the standard list of libraries that the COBOL command would have otherwise passed to ld . When you create a shared library, all symbols must be resolved. For more information about the standard list of libraries used by HP COBOL, see Section 1.1.3.2.