Example: creating a sample shared library

The following example shows three COBOL programs, one of which (alpha) calls the other two (beta and gamma). The procedure after the programs shows how to create a shared library that contains the two called programs, create an archive library that contains that shared library, and compile and link the calling program into a module that accesses the called programs in the archive library.

Example 1: alpha.cbl

 IDENTIFICATION DIVISION.
 PROGRAM-ID. alpha.
*
 ENVIRONMENT DIVISION.
 CONFIGURATION SECTION.
*
 DATA DIVISION.
 WORKING-STORAGE SECTION.
 01 hello1   pic x(30)  value is "message from alpha to beta".
 01 hello2   pic x(30)  value is "message from alpha to gamma".
*
 PROCEDURE DIVISION.
     display "alpha begins"
     call "beta" using hello1
     display "alpha after beta"
     call "gamma" using hello2
     display "alpha after gamma"
     goback.

Example 2: beta.cbl

 IDENTIFICATION DIVISION.
 PROGRAM-ID. beta.
*
 ENVIRONMENT DIVISION.
*
 DATA DIVISION.
 WORKING-STORAGE SECTION.
*
 Linkage section.
 01 msg   pic x(30).
*
 PROCEDURE DIVISION using msg.
     DISPLAY "beta gets msg=" msg.
     goback.

Example 3: gamma.cbl

 IDENTIFICATION DIVISION.
 PROGRAM-ID. gamma.
*
 ENVIRONMENT DIVISION.
 CONFIGURATION SECTION.
*
 DATA DIVISION.
 WORKING-STORAGE SECTION.
*
 Linkage section.
 01 msg            pic x(30).
*
PROCEDURE DIVISION using msg.
    DISPLAY "gamma gets msg=" msg.
    goback.

Procedure

The simplest way to combine the three programs is to compile and link them into a single executable module by using the following command:

cob2 -o m_abg alpha.cbl beta.cbl gamma.cbl

You can then run the programs by issuing the command m_abg, which results in the following output:

alpha begins
beta gets msg=message from alpha to beta
alpha after beta
gamma gets msg=message from alpha to gamma
alpha after gamma

Instead of linking the programs into a single executable module, you can instead put beta and gamma in a shared library (called sh_bg in the following procedure), and compile and link alpha into an executable module that accesses beta and gamma in the shared library. To do so, do these steps:

  1. Create an export file that specifies the symbols that the shared library must export:
    #!
    * symbols exported by shared library sh_bg:
    BETA
    GAMMA

    The symbol names in export file bg.exp shown above are uppercase because the COBOL default is to use uppercase names for external symbols. If you need mixed-case names, use the PGMNAME(MIXED) compiler option.

    If you name the export file bg.exp, you must use option -bE:bg.exp when you create the shared library (as shown in the next step).

  2. Use the following command to combine beta and gamma into a shared library object called sh_bg:
    cob2 -o sh_bg beta.cbl gamma.cbl -bE:bg.exp -bM:SRE -bnoentry

    This command provides the following information to the compiler and linker:

    • -o sh_bg beta.cbl gamma.cbl compiles and links beta.cbl and gamma.cbl, and names the resulting output module sh_bg.
    • -bE:bg.exp tells the linker to export the symbols that are named in export file bg.exp.
    • -bM:SRE tells the linker to make the output module a shared reentrant object.
    • -bnoentry tells the linker that the output module will not have a main entry point. (sh_bg will have entry points BETA and GAMMA.)
  3. You can now use shared library sh_bg.

    If you have several shared objects, however, you might want to put them in an archive library for convenience. To put sh_bg in an archive library called libbg.a, use the following command:

    ar -rv libbg.a sh_bg
  4. Issue one of the following two commands to recompile alpha.cbl and produce executable m_alpha that has external references resolved within archive library libbg.a:
    cob2 -o m_alpha alpha.cbl -L. -lbg
    cob2 -o m_alpha alpha.cbl -L. libbg.a

    where:

    • -lxx is a standard AIX abbreviation for libxx.a.
    • -L. tells the linker to search for the specified archive library in the current directory (.).

    You might instead want to specify the full path of the target archive library. For example:

    cob2 -o m_alpha alpha.cbl -L/usr/jane/libraries -lbg

You can then run the program by issuing the command m_alpha, which produces the same output as that shown before the steps above.

As an alternative to issuing the commands in the last three steps, you can create a makefile that includes the commands.

Example: creating a makefile for the sample shared library