HP OpenVMS Systems Documentation

HP COBOL
User Manual

This search sequence occurs for each reference that remains unresolved.

System-Supplied Object Module Libraries

All HP COBOL programs reference system-supplied object module libraries when they are linked. These libraries contain routines that provide I/O and other system functions. Additionally, you can use your own libraries to provide application-specific object modules.

To use the contents of an object module library, you must do the following:

• Refer to a symbol in the object module by name in your program in a CALL statement or VALUE EXTERNAL reference.
• Make sure that the linker can locate the library that contains the object module by ensuring that required software is correctly installed.
• Make sure that your default directory (or LINK/EXE directory) is valid and that you have write privileges to it.

To specify that a linker input file is a library file, use the /LIBRARY qualifier. This qualifier causes the linker to search for a file with the name you specify and the default file type .OLB. If you specify a file that the linker cannot locate, a fatal error occurs and linking terminates.

The sections that follow describe the order in which the linker searches libraries that you specify explicitly, default user libraries, and system libraries.

For more information about object module libraries, refer to the OpenVMS Linker Utility Manual.

Defining the Search Order for Libraries

When you specify libraries as input for the linker, you can specify as many as you want; there is no practical limit. More than one library can contain a definition for the same module name. The linker uses the following conventions to search libraries specified in the command string:

• A library is searched only for definitions that are unresolved in the previously specified input files.
• If you specified more than one object module library, the libraries are searched in the order in which they are specified.

For example:

$ LINK METRIC,DEFLIB/LIBRARY,APPLIC

The library DEFLIB will be searched only for unresolved references in the object module METRIC. It is not searched to resolve references in the object module APPLIC. However, this command can also be entered as follows:

$ LINK METRIC,APPLIC,DEFLIB/LIBRARY

In this case, DEFLIB.OLB is searched for all references that are not resolved between METRIC and APPLIC. After the linker has searched all libraries specified in the command, it searches default user libraries, if any, and then the default system libraries.

1.2.3.5 Creating Shareable Images

You can create HP COBOL subprograms as shareable images by using the LINK qualifier /SHARE. A shareable image is a single copy of a subprogram that can be shared by many users or applications. Using shareable images provides the following benefits:

• Saves system resources, since one physical copy of a set of procedures can be shared by more than one application or user
• Facilitates the linking of very large applications by allowing you to break down the whole application into manageable segments
• Allows you to modify one or more sections of a large application without having to relink the entire program

The following steps describe one way to create an HP COBOL subprogram as a shareable image:

1. Create the main program used to call the subprogram.
2. Create the subprogram.
3. Link the subprogram as a shareable image by using the /SHARE qualifier and including the options file containing the symbol vector in the LINK command as an input file. (See the sections Using Symbol Vectors with Shareable Images (Alpha, I64) and Using Transfer Vectors (VAX) for information about vectors.)
4. Define a logical name to point to your shareable image.
5. Install the shareable image subprogram, using the OpenVMS Install utility (INSTALL).
6. Link the main program with the shareable image.

Once you have completed these steps, you can run the main program to access the subprogram installed as a shareable image.

Refer to the OpenVMS Linker Utility Manual and the Guide to Creating OpenVMS Modular Procedures for more information about shareable images.

The following sample programs and command procedures provide an example of how to create and link a subprogram as a shareable image, as described in the preceding steps.

Example 1-2 shows the main program CALLER.COB and the two subprograms (SUBSHR1.COB and SUBSHR2.COB). Only the subprograms are shareable images.

* CALLER.COB
IDENTIFICATION DIVISION.
PROGRAM-ID. CALLER.
******************************************************************
* This program calls a subprogram installed as a shareable image.*
******************************************************************
PROCEDURE DIVISION.
0.
     CALL "SUBSHR1"
         ON EXCEPTION
             DISPLAY "First CALL failed. Program aborted."
     END-CALL.
     STOP RUN.
END PROGRAM CALLER.

* SUBSHR1.COB
IDENTIFICATION DIVISION.
PROGRAM-ID. SUBSHR1.

******************************************************************
* This subprogram is linked as a shareable image. When it is called,*
* it calls another subprogram installed as a shareable image.       *
******************************************************************
PROCEDURE DIVISION.
0.
     DISPLAY "Call to SUBSHR1 successful. Calling SUBSHR2.".
     CALL "SUBSHR2"
         ON EXCEPTION
             DISPLAY "Second call failed. Control returned to CALLER."
     END-CALL.
END PROGRAM SUBSHR1.


* SUBSHR2.COB
IDENTIFICATION DIVISION.
PROGRAM-ID. SUBSHR2.
****************************************************************
* This subprogram is linked as a shareable image and is called by *
* another shareable image.                                     *
****************************************************************
PROCEDURE DIVISION.
0.
     DISPLAY "Call to SUBSHR2 successful!".
END PROGRAM SUBSHR2.

Example 1-3 shows a command procedure that compiles and links the sample program and subprograms in Example 1-2 on an OpenVMS Alpha system. (Example 1-4 shows an equivalent command procedure for OpenVMS VAX.)

$! Create the main program and subprograms.
$! In this example CALLER.COB is the main program.
$! SUBSHR1.COB and SUBSHR2.COB are the subprograms to be installed
$! as shareable images.
$!
$! Compile the main program and subprograms.
$!
$  COBOL CALLER.COB
$  COBOL SUBSHR1.COB
$  COBOL SUBSHR2.COB
$!
$! Create an options file containing all the universal symbols
$! (entry points and other data symbols) for the subprograms.
$!
$  COPY SYS$INPUT OPTIONS1.OPT
$  DECK
   SYMBOL_VECTOR=(SUBSHR1=PROCEDURE,SUBSHR2=PROCEDURE)
$  EOD
$!
$! Link the subprograms using the /SHARE qualifier to the
$! shareable library and the options file.  For more information
$! on options files, refer to the OpenVMS Linker Utility Manual.
$!
$  LINK/SHARE=MYSHRLIB SUBSHR1,SUBSHR2,OPTIONS1/OPT
$!
$! Assign a logical name for the shareable images.
$!
$  ASSIGN DEVICE:[DIRECTORY]MYSHRLIB.EXE MYSHRLIB
$!
$! Create a second options file to map the main program to the
$! shareable image library.
$!
$  COPY SYS$INPUT OPTIONS2.OPT
$  DECK
   MYSHRLIB/SHAREABLE
$  EOD
$!
$! Link the main program with the shareable image subprograms
$! through the options file.
$!
$  LINK CALLER,OPTIONS2/OPT
$!
$! Now you can run the main program.

Using Symbol Vectors with Shareable Images (Alpha, I64)

To make symbols in the shareable image available for other modules to link against, you must declare the symbols as universal. You declare universal symbols by creating a symbol vector. You create a symbol vector by specifying the SYMBOL_VECTOR=option clause in a linker options file. List all of the symbols you want to be universal in the order in which you want them to appear in the symbol vector.

If you use symbol vectors, you can modify the contents of shareable images and avoid relinking user programs bound to the shareable image when you modify the image. Once you have created the symbol vector, you can install the subprograms using the OpenVMS Install utility (INSTALL) and link the main program to the shareable library. Symbol vectors, if used according to the coding conventions, can also provide upward compatibility.

For more information about symbol vectors, refer to the OpenVMS Linker Utility Manual. <>

Linking a Subprogram as a Shareable Image (VAX)

Example 1-4 shows a command procedure that compiles, links, and installs the sample programs in Example 1-2 on OpenVMS VAX systems.

$! Create the main program and subprograms to be installed as shareable
$! images. In this example CALLER.COB is the main program. SUBSHR1.COB
$! and SUBSHR2.COB are the subprograms to be installed as
$! shareable images.
$!
$! Compile the main program and subprograms.
$!
$  COBOL CALLER.COB
$  COBOL SUBSHR1.COB
$  COBOL SUBSHR2.COB
$!
$! Create an options file to map the entry points of the subprograms.
$!
$  COPY SYS$INPUT OPTIONS1.OPT
$  DECK
   UNIVERSAL=SUBSHR1,SUBSHR2
$  EOD
$!
$! Link the subprograms using the /SHARE qualifier to the shareable library
$! and the options file. For more information on options files, refer to
$! the documentation on the OpenVMS Linker.
$!
$  LINK/SHARE=MYSHRLIB SUBSHR1,SUBSHR2,OPTIONS1/OPT
$!
$! Copy the shareable images to SYS$LIBRARY. To perform this
$! you must have [SYSLIB] access privileges. Alternatively,
$! you can perform the same function by doing a local assignment.
$!
$! COPY MYSHRLIB.EXE SYS$LIBRARY:*
$!      or
$  ASSIGN DEVICE:[DIRECTORY]MYSHRLIB.EXE MYSHRLIB
$!
$! Install the shareable images in a shareable library.
$! This will allow multiple users to use a single copy of the
$! shareable image.
$!
$! If you do not install the shareable library,
$! multiple users will each link to their own run-time copy of
$! the image.
$!
$! Note that to install an image in a shareable library, you must have
$! PRMGBL, SYSGBL, or CMKRNL privileges.
$!
$! Prior to installing the shareable image, check to see if there is
$! enough global symbol space.
$! MCR INSTALL
$! /GLOBAL
$! ^Z
$!
$! Also check to see if there are available global sectors and pages.
$! MCR SYSGEN
$! /GBLSE
$! /GBLPA
$! ^Z
$!
$! The /WRITE qualifier is required if you want to install writable PSECTS.
$  MCR INSTALL
   device:[directory]MYSHRLIB/SHARE/WRITE
$!
$! Create a second options file to map the main program to the shareable
$! image library.
$  COPY SYS$INPUT OPTIONS2.OPT
$  DECK
   MYSHRLIB/SHAREABLE
$  EOD
$!
$! Link the main program with the shareable image subprograms through the
$! options file.
$  LINK CALLER,OPTIONS2/OPT
$!
$! Now you can run the main program.