Creating and using libraries

This topic is for Windows and UNIX only. For information on creating and using libraries on OpenVMS, see Building shared images.

About object and executable libraries

Your compiled Synergy DBL routines can be stored in one of the following:

• Object libraries (OLBs)
• Executable libraries (ELBs)

Object libraries (OLBs)

An object library is a collection of object modules stored in a single file with an .olb extension. Any routines that are included in the object library will be extracted from the library at link time. Thus, instead of distributing hundreds of .dbo files, you can distribute a single .olb file that contains all of the compiled source code routines. You use the Synergy librarian with the -c option to create an object library. (See Invoking the librarian (dblibr) for details.)

Object libraries are linked into a Synergy DBL executable file with the Synergy linker. If any routine calls are unresolved, the linker looks for them in the libraries listed in the link command line. When the linker builds the executable file, it puts a copy of the referenced OLB routines in the executable file.

In the diagram below, util2 is unreferenced; therefore, it is not included in the executable.

1. Object library.

Executable libraries (ELBs)

An executable library is a collection of executable modules. You use the Synergy linker with the -l option to create executable libraries. (See Linking object modules for details.) Each executable library is a single file with an .elb extension.

Executable libraries are linked against a Synergy DBL executable file by the Synergy linker. If any routine calls are unresolved, the linker looks for them in the libraries listed in the link command line. Only the executable library reference for the routines is put in the Synergy DBL executable file, not the code itself. During program execution (at runtime), the executable library is opened and the routines are accessed directly from the library file.

In the diagram below, the arrows show references between routines.

2. Executable library.

An executable library can also include references to executable modules in other executable libraries. When linking a Synergy DBL executable file, if any routines are unresolved, the linker looks for them in the libraries listed in the link command line and in the libraries linked against those libraries. The diagram below assumes ELB1 is linked against ELB2. During program execution (at runtime), both ELB1 and ELB2 are opened and routines are accessed from them.

3. Executable library with references to other executable libraries.

OLBs vs. ELBs

When you use executable libraries, you generate smaller executables than when you use object libraries because there’s only one copy of the subroutines in the ELB instead of a copy of each subroutine in every .dbr file. This difference can be significant in applications comprised of many programs.

An ELB subroutine is independent of the executable files that access it. You can change ELB subroutines without modifying the executable file and without relinking any programs that access the subroutines in the ELB. If you change a subroutine in an object library, you must relink all programs that use the object library to ensure they have the most recent code.

We recommend that you create ELBs when you have the choice.

Creating executable libraries

To create an executable library (ELB), use the Synergy linker, dblink, with the -l option. You can link either object files (.dbo files), object libraries (.olb files), or other executable libraries (.elb files) to create your ELB.

See the -l option in Linking object modules if you want to create an ELB from object files. Also see Creating an ELB from an OLB if you want to create an ELB from an OLB.

You cannot rebuild an ELB if it is in use by another program. Also, be careful when changing the size of a global data section: If an ELB subroutine increases the defined size of a global data section that’s owned externally, and no programs are relinked against the ELB, executing those programs could cause memory access violations. If you change the size of a global data section, all programs that use it must be relinked.

Creating object libraries

On Windows and UNIX, the dblibr command starts the librarian. The librarian creates and maintains object libraries (OLBs). If you want to create an executable library, see Creating executable libraries. The various methods you can use in a Windows environment to invoke the dblibr command are explained in Methods for invoking commands on Windows.

On OpenVMS, use the LIBRARIAN commands to create and maintain object libraries. See your OpenVMS documentation set for more information.

Invoking the librarian (dblibr)

The librarian command (dblibr) uses the following format:

dblibr [options] [--] library [object_1 ... object_n]

Options

options

(optional) One or more of the following librarian options. You can either precede a group of options with a minus sign (-) or precede each option with a minus sign. (For example, -acdr and -a -cdr are both valid.)

On Windows, if system option #34 is set, you must use a forward slash (/) instead of a minus sign (-) before each librarian option or group of options.

--

(optional) Included for consistency with other Synergy DBL command lines but serves no function here.

library

The name of the object library. The default extension is .olb.

object_1
object_n

(optional) One or more object files or object modules, depending on whether you’re adding to, deleting from, replacing in, or extracting from the object library. The default extension is .dbo. You can specify a maximum of 8192 files.

Discussion

Libraries contain object modules, not object files. The object module name is the name of the routine loaded in the object library. (This is the name defined with the SUBROUTINE or FUNCTION statements.) When you’re using the add or replace librarian option (-a or -r), specify the object file. When you’re using the extract or delete librarian option (-x or -d), specify the object module.

You must specify the -a, -d, -r, or -x options on the command line unless the only other options that you specify are -tv. The -c option will default to -a if neither -a nor -r is specified.

When using the -tv option combination, each line of output will look something like this:

SXC_GLOBAL_DATA  218723  Thu Sep 06 09:06:38 2007  

The number following the routine name (218723 in this example) is the size of the routine. (Note that this number cannot be used to approximate the runtime memory size due to data compression and other factors.)

The librarian detects and prevents duplicate routines from being added from another object library and issues a warning. It also detects methods being added to an object library and removes all existing methods from the object library that are from the same class.

Examples

The example below creates an object library file named screens.olb. It contains the object code for all subroutines in the files scr1.dbo, scr2.dbo, and scr3.dbo.

dblibr -ca screens scr1 scr2 scr3

The following example displays a detailed table of contents of the file screens.olb to the screen.

dblibr -tv screens

The following example adds the object modules in scr4.dbo to the object library file, screens.olb, and displays the modules added. Any duplicate modules will be replaced without a warning message.

dblibr -awv screens scr4

The example below extracts the subroutine named clear from the object library screens.olb. The Synergy librarian creates the file clear.dbo, which contains the extracted object module.

dblibr -x screens clear

The following example deletes the routine clear from the object library named screens.olb.

dblibr -d screens clear 

Redirecting librarian commands from a file

To redirect librarian commands from a file, use the following format:

dblibr [-T] <file

Options

-T

(optional) Specifies that the command line(s) should be traced, or displayed, as they are executed. If you don’t specify -T, the command lines will not be displayed.

file

The ASCII file that contains one or more command lines to be input to the librarian. It cannot contain more than 2000 characters.

Discussion

If system option #34 is set, you must use a forward slash (/) instead of a minus sign (–) before the trace flag option.

The Synergy librarian on Windows supports continuation lines in the input command file, which can make this file easier to read. If you need to continue a line to a new physical line, place the appropriate continuation character at the end of the line to be continued. The standard continuation line character on Windows and UNIX is the backslash (\). On Windows, if you set system option #34, use a minus sign (–) as the continuation character.

Examples

-ca screens scr1 scr2 scr3 util1 util2 util3 \
sutil1 sutil2

On Windows, if system option #34 is set, you would use the minus sign (–) as the continuation character and the forward slash (/) as the switch character. The file would look like this:

/ca screens scr1 scr2 scr3 util1 util2 util3 -
sutil1 sutil2

To input the required information into the Synergy librarian from libr with tracing set, type

dblibr -T <libr