#include <stdio.h>
extern int my_data;
globalref int my_symbol;
int mysub();
main()
{
int num1, num2, result;
num1 = 5;
num2 = 6;
result = mysub( num1, num2 );
printf("Result= %d\n", result);
printf("Data implemented as overlaid psect= %d\n", my_data);
printf("Global reference data is= %d\n", my_symbol);
}
|
| Example 8-2 Shareable Image: my_math.c |
|---|
int my_data = 5;
globaldef int my_symbol = 10;
myadd(value_1, value_2)
int value_1;
int value_2;
{
int result;
result = value_1 + value_2;
return( result );
}
mysub(value_1,value_2)
int value_1;
int value_2;
{
int result;
result = value_1 - value_2;
return( result );
}
mydiv( value_1, value_2 )
int value_1;
int value_2;
{
int result;
result = value_1 / value_2;
return( result );
}
mymul( value_1, value_2 )
int value_1;
int value_2;
{
int result;
result = value_1 * value_2;
return( result );
}
|
To implement Example 8-2 as a shareable image, you must declare the universal symbols in the image by using the following LINK command:
$ LINK/SHAREABLE MY_MATH, SYS$INPUT/OPT PSECT_ATTR=my_data,NOSHR UNIVERSAL=myadd UNIVERSAL=mysub UNIVERSAL=mymul UNIVERSAL=mydiv UNIVERSAL=my_symbol [Ctrl/Z] |
Note that the symbol my_data in Example 8-2 does not have to be declared universal because of the way in which VAX C implements it. Several Compaq programming languages, including VAX C and Compaq Fortran for OpenVMS VAX, implement certain external variables as program sections with the overlaid (OVR), global (GBL), and relocatable (REL) attributes. When the linker processes these object modules, it overlays the program sections so that the various object modules that reference the variable access the same virtual memory. Symbols implemented in this way are declared universal (appear in the GST of the image) by default.
In the sample link operation, the SHR attribute of the program section that implements the data symbol my_data is reset to NOSHR. If you do not reset the shareable attribute for program sections that are writable, you must install the shareable image to run the program. (The shareable attribute [SHR] determines whether multiple processes have shared access to the memory.)
The following example illustrates how to link the object module MY_MAIN.OBJ with the shareable image MY_MATH.EXE. Note that the LINK command sets the shareability attribute of the program section my_data to NOSHR, as in the link operation in which the shareable was created.
$ LINK MY_MAIN, SYS$INPUT/OPT MY_MATH/SHAREABLE PSECT_ATTR=my_data,NOSHR [Ctrl/Z] |
8.2.1 Creating Upwardly Compatible Shareable Images (VAX Linking Only)
For VAX linking, you can create a shareable image that can be modified, recompiled, and relinked without causing the images that were linked against previous versions of the image to be relinked. To provide this upward compatibility, you must ensure that the values of relocatable universal symbols within the image remain constant with each relinking.
Universal Symbols that Represent Procedures
To fix the locations of universal symbols that represent procedures in a shareable image, create a transfer vector for the shareable image. In a transfer vector, you create small routines in VAX MACRO that define an entry point in the image and then transfer control to another location in memory. You declare the entry points defined in the transfer vector as the universal symbols and have each routine transfer control to the actual location of the procedures within the shareable image. As long as you ensure that the location of the transfer vector remains the same with each relinking, images that linked with previous versions of the shareable image will access the procedures at the locations they expect.
Figure 8-1 illustrates the flow of control at run time between a main image and a shareable image in which the actual routines are declared as universal symbols (as shown in Section 8.2) and between a main image and a shareable image in which the transfer vector entry points are declared as universal symbols (as shown in Section 8.2.1.1).
Figure 8-1 Comparison of UNIVERSAL = Option and Transfer Vectors
Universal Symbols that Represent Data
To provide upwardly compatible symbols that represent data locations,
you must also fix these locations within memory. You can accomplish
this by allocating the data symbols at the end of the transfer vector
file. In this way, when you fix the location of the transfer vector
within an image, the data locations also remain the same. (This is
described in the next section.)
8.2.1.1 Creating a Transfer Vector (VAX Linking Only)
You create a transfer vector using VAX MACRO. Specify the .TRANSFER directive because it declares the symbol that you specify as its argument as a universal symbol by default. Compaq recommends the following coding conventions for creating a transfer vector:
(1) .transfer FOO ;Begin transfer vector to FOO (2) .mask FOO ;Store register save mask (3) jmp L^FOO+2 ;Jump to routine |
- The .TRANSFER directive causes the symbol, named FOO in the example, to be added to the shareable image's global symbol table. (You do not need to also specify the symbol in a UNIVERSAL= statement in a linker options file.)
- The .MASK directive causes the assembler to allocate 2 bytes of memory, find the register save mask accompanying the entry point ( FOO in the example), and store the register save mask of the procedure. (According to the OpenVMS calling standard, procedure calls using the CALLS or CALLG instructions include a word, called the register save mask, whose bits represent which registers must be preserved by the routine.)
- The JMP instruction transfers control to the
address specified as its argument. In the example, this address is two
bytes past the routine entry point FOO (the first two bytes of the
routine are the register save mask).
HP recommends that you use a jump instruction (for example, JMP L^) in the transfer vector. Transfering control with a BSBW or JSB instruction results in saving the address of the next instruction from the transfer vector on the stack. In addition, the displacement used by the BSBW instruction must be expressible in 16 bits, which may not be sufficient to reach the target routine. Also, to avoid making the image position dependent, do not use an absolute mode instruction.
Note that the preceding convention assumes that the routine is called using the procedure call format, the default for most high-level language compilers. If a routine is called as a subroutine, using the JSB instruction, you do not need to include the .MASK directive. When creating a transfer vector for a subroutine call, Compaq recommends adding bytes of padding to the transfer vectors. This padding makes a subroutine transfer vector the same size as a transfer vector for a procedure call. If you need to replace a subroutine transfer vector with a procedure call transfer vector, you can make the replacement without disturbing the addresses of all the succeeding transfer vectors.
The following example illustrates a subroutine transfer vector that uses the .BLKB directive to allocate the padding:
.TRANSFER FOO ;Begin transfer vector to FOO JMP L^FOO ;Jump to routine .BLKB 2 ;Pad vector to 8 bytes |
To ensure upward compatibility, follow these guidelines when creating a transfer vector:
- Preserve the order and placement of entries in a transfer vector.
Once you establish the order in which entries appear in a transfer
vector, do not change it. Images that were linked against the shareable
image depend on the location of the symbol in the transfer vector.
You can reserve space within a transfer vector for future growth by specifying dummy transfer vector entries at various positions in a transfer vector. - Add new entries to the end of a transfer vector. When including universal data in a transfer vector file, use padding to leave adequate room for future growth between the end of the transfer vector and the beginning of the list of universal data declarations.
A transfer vector for the program in Example 8-2 is illustrated in Example 8-3.
| Example 8-3 Transfer Vector for the Shareable Image MY_MATH.EXE |
|---|
.transfer myadd .mask myadd jmp l^myadd+2 .transfer mysub .mask mysub jmp l^mysub+2 .transfer mymul .mask mymul jmp l^mymul+2 .transfer mydiv .mask mydiv jmp l^mydiv+2 .end |
Assemble the transfer vector file to create an object module that can be included in a link operation:
$ MACRO MY_MATH_TRANS_VEC.MAR |
8.2.1.2 Fixing the Location of the Transfer Vector in Your Image (VAX Linking Only)
For VAX linking, you include a transfer vector in a link operation as you would any other object module. However, to ensure upward compatibility, you must make sure that the transfer vector always appears in the same location in the image. The best way to accomplish this is to make the transfer vector always appear at the beginning of the image by forcing the linker to process it first. If you put the transfer vector file in a named cluster, using the CLUSTER= option, and specify it as the first option in an options file that can generate a cluster, the transfer vector will appear at the beginning of the file. (For more information about controlling cluster creation, see Section 6.3.)
The following example illustrates how to include the transfer vector in the link operation, using the CLUSTER= option, so that the linker processes it first:
$ LINK/SHAREABLE MY_MATH, SYS$INPUT/OPT (1) GSMATCH=lequal,1,1000 (2) CLUSTER=trans_vec_clus,,,MY_MATH_TRANS_VEC.OBJ [Ctrl/Z] |
- To enable images that linked against a shareable image to run with various versions of the shareable image, you must specify the identification numbers of the image. By default, the linker assigns a unique identification number to each version of a shareable image. At run time, if the ID of the shareable image as it is listed in the executable image does not match the ID of the shareable image the image activator finds to activate, the activation will abort. For information about using the GSMATCH= option to specify ID numbers, see the description of the GSMATCH= option in Part 2.
- This CLUSTER= option causes the linker to create the named cluster TRANS_VEC_CLUS and to put the transfer vector file in this cluster.
8.2.2 Creating Based Shareable Images (VAX Linking Only)
For VAX linking, you can create a based shareable image by specifying the BASE= option in a linker options file. In a based image, you specify the starting address at which you want the linker to begin allocating memory for the image. For more information about the BASE= option, see Part 2.
HP does not recommend using based shareable images.
Based shareable Alpha images are not supported.
| Previous | Next | Contents | Index |