vsys_build_image.com (for OpenVMS)

VMS This section addresses using and creating shareable images on OpenVMS with the vsys_build_image.com command file.

Shareable Images

Using the command file vsys_build_image.com to make a shareable image out of a user-specified object library is a simple procedure compared to performing this task by hand; however, an understanding of shareable images and the OpenVMS linker is an important aid in avoiding problems. Most common problems involve improperly specifying the linking options for the library or generating ident mismatches with the images.

A shareable image is a special type of image that allows multiple processes to share the same piece of code. There are several advantages to this approach. Programs linked against shareable images rather than object libraries tend to be smaller. Also, if the shareable image has been installed, multiple programs linked against the shareable image (for instance VDB_ACCSHR.EXE) all access the same copy, thus memory usage for the system is lower. In general, computers running Vsystem have multiple images accessing Vaccess routines, so installing the Vsystem shareable images helps with performance. Also, installed images can be activated into the process context more quickly.

The OpenVMS library routine LIB$FIND_IMAGE_SYMBOL examines the symbol table at the top of the shareable image to find the address of the routine that has been requested. The shareable image is then mapped into the address space of the program, and Vsystem can execute the user-written routine. Removing the address resolution step until run time provides a measure of flexibility necessary for a complex system such as Vsystem, especially with the tight integration between the various components of a control system.

Additionally, you can expand the system while it is running without having to relink the images. You can add new hardware support to a system without stopping those parts that don't use the new hardware. Also, the automatic features of Vsystem can be supported because the programs shipped with Vsystem don't have to be relinked to add support for user features.

The Command Procedure

The vsys_build_image command procedure automates building a shareable image, but it is not a complete solution. There are complex libraries that cannot be built into shareable images with this procedure. A brief description of vsys_build_image.com operations should help explain how to use the command procedure.

As mentioned previously, most of the common problems encountered with vsys_build_image.com involve improper linking. It helps to have some understanding of the linking process. You can find a complete discussion of the linker in the OpenVMS linker manual. One common problem is improperly setting up the user link libraries to link the shareable image.

To create shareable images on OpenVMS

Enter the following at the system prompt:

$@VSYS_COM:VSYS_BUILD_IMAGE.COM lib_file sharable_image -[exclude_file] [options_file] [link_options]

Parameters

This section describes the parameters you can use with vsys_build_image.com.

exclude_file

The exclude_file parameter is the file specification for a file containing a list (one per line) of global names to exclude from the list of routines included in the shareable image. The primary use of this feature is to prevent global names that are not routines from being included in the transfer vector. For example, a C variable declared "globaldef" shows up as a global name, and this command file tries to include it in the transfer vector for the shareable image, which leads to unresolved references at link time. However, putting the name in the exclusion file prevents this from being a problem and provides a mechanism for hiding some of the routines in a library from the shareable image.

lib_file

The lib_file parameter is the file specification for the object library from which to build the shareable image. This is a required parameter.

link_options

The link_options parameter enables you to specify linking options for the final link command for the shareable image to be built. Since it is a single parameter, there should be no spaces between the options. In order to link the shareable image for debug and to generate a map, this parameter is set to the string

/debug/map/full

options_file

The options_file parameter is the file specification for additional linker options for linking the shareable image. vsys_build_image.com creates an option file containing the image identification string, the match criteria for the image, the cluster declaration for the transfer vectors, and any necessary PSECT attribute commands. If any other linker options are desired, they can be entered into this file; they are appended to the option file created by vsys_build_image.com.

sharable_image

The sharable_image parameter is the file specification for the shareable image to be built. This is a required parameter.

Examples

Examples of the full command line are:

$@vsys_com:vsys_build_image USERLIB.OLB USERSHR.EXE "" "" /DEBUG

$@vsys_com:vsys_build_image USERLIB.OLB USERSHR.EXE EXCLUDE.DAT OPTIONS.OPT /MAP

$@vsys_com:vsys_build_image USERLIB.OLB USERSHR.EXE "" OPTIONS.OPT /MAP/FULL