#include <stdio.h>
#pragma extern_model save
#pragma extern_model common_block
extern int my_data;
#pragma extern_model restore
extern int my_symbol;
extern int mysub( int, int );
main()
{
int num1, num2, result;
num1 = 7;
num2 = 4;
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 4-2 Shareable Image: my_math.c |
|---|
#pragma extern_model save
#pragma extern_model common_block
int my_data = 5;
#pragma extern_model restore
int my_symbol = 10;
int add_data = -1;
int sub_data = -1;
int mul_data = -1;
int div_data = -1;
int myadd( int value_1, int value_2 )
{
add_data = value_1 + value_2;
return add_data;
}
int mysub( int value_1, int value_2 )
{
sub_data = value_1 - value_2;
return sub_data;
}
int mymul( int value_1, int value_2 )
{
mul_data = value_1 * value_2;
return mul_data;
}
int mydiv( int value_1, int value_2 )
{
div_data = value_1 / value_2;
return div_data;
}
|
You must use the extern common model to make the HP C for OpenVMS I64 compiler implement the symbol my_data as an overlaid section. The default model on HP C is relaxed/refdef. (For more information on the extern models and how they are enabled with pragmas or command qualifiers, see the HP C User's Guide for OpenVMS Systems.)
For I64 linking, you declare universal symbols by listing them in a SYMBOL_VECTOR= option. For each symbol listed in the SYMBOL_VECTOR= option, the linker creates an entry in the shareable image's symbol vector and creates an entry for the symbol in the shareable image's GST. When the shareable image is included in a subsequent link operation, the linker processes the symbols listed in its GST.
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 4.
To implement Example 4-2 as an I64 shareable image, you must declare the universal symbols in the image by using the following LINK command:
$ LINK/SHAREABLE MY_MATH, SYS$INPUT/OPT
GSMATCH=LEQUAL,1,1000
SYMBOL_VECTOR=(MYADD=PROCEDURE,-
MYSUB=PROCEDURE,-
MYMUL=PROCEDURE,-
MYDIV=PROCEDURE,-
MY_SYMBOL=DATA,-
MY_DATA=PSECT)
[Ctrl/Z]
|
You must identify the type of symbol vector entry you want to create by specifying a keyword. The linker allows you to create symbol vector entries for procedures, data (relocatable or constant), and for global data implemented as an overlaid section.
A symbol vector entry is a quadword that contains information about the symbol that can be used in subsequent fixups of images that are linked against the shareable image. The contents of the quadword depends on what the symbol represents. If the symbol represents a procedure (=PROCEDURE), the symbol vector entry contains the address of the function descriptor (FD). If the symbol represents a data (=DATA), the symbol vector entry contains the address of the data location. If the symbol represents a data constant (=DATA), the symbol vector entry contains the actual value of the constant. If the symbol represents a section (=PSECT) the symbol vector entry contains the address of the location of the section.
The linker fills in the symbol vector with values and addresses. The address calculations are based on the assumption that the shareable image will be mapped at the default start address of 10000 (hexadecimal). This is done despite the fact that the linker can not know where the image will be in memory, at run time. The linker also adds relocation information for the image activator to adjust the address values based on the actual start address of the shareable image, at activation time. This way, at run time, the symbol vector contains the actual code or data addresses.
When you create the shareable image (by linking it specifying the /SHAREABLE qualifier), the value of a universal symbol listed in the GST is the zero-based index in the quadword array, representing its entry in the symbol vector (expressed as the index z in Figure 4-1).
When you include this shareable image in a subsequent link operation, the linker leaves the address of the data, the address function descriptor of the external routine, or the address of the section empty in the linker-created short data. The linker creates a fixup for the executable image that references the symbol from the shareable image. The fixup includes the symbol's index in the symbol vector of the shareable image.
The following example illustrates how to link the object module MY_MAIN.OBJ with the shareable image MY_MATH.EXE.
$ LINK MY_MAIN, SYS$INPUT/OPT MY_MATH/SHAREABLE [Ctrl/Z] |
At run time, when the image activator maps the shareable image into memory, it calculates the actual locations of the routines and relocatable data within the image and stores these values in its symbol vector. The image activator then fixes up the references to these symbols in the executable image. For a symbol representing constant data, the constant from the symbol vector is copied into the executable image. For a symbol representing relocatable data, the address of the data from the symbol vector is copied into the executable image. For a symbol representing a procedure the contents of the FD pointed to by the address in the symbol vector, the code address and the global pointer, is copied into the executable image. When the executable image makes a call to the procedure, shown as the branch (br.few) instruction sequence in Figure 4-1, control is transferred directly to the location of the procedure within the shareable image.
Figure 4-1 Accessing Universal Symbols Specified Using the SYMBOL_VECTOR = Option
Note that the images are being activated by the image activator with all relocations applied, pointing out a single fixup. That is, m and n are the virtual addresses after the image relocations are applied and gp is the relocated global pointer value.
Note also that, unlike VAX linking, global symbols implemented as
overlaid sections are not universal by default. Instead, you control
which of these symbols is a universal symbol by including it in the
SYMBOL_VECTOR= option, specifying the PSECT keyword. The example
declares the section
my_data
as a universal symbol.
4.2.1 Symbol Definitions Point to Shareable Image Sections
On I64 systems, the linker cannot overlay sections that are referenced by symbol definitions with shareable image sections of the same name.
For example, the HP C compiler generates symbol definitions when the relaxed ref/def extern model is used (the default).
For hard symbol definitions, the compiler creates an overlaid section defining the memory requirements for that symbol. For tentative symbol definitions, there is no virtual memory allocated by the compiler. At link time, if there is no virtual memory for a symbol found, the linker creates an overlaid section defining the memory.
If an overlaid section was created for a symbol definition, such a section cannot be overlaid with shareable image sections that are created when you link a shareable image and use the PSECT keyword in your SYMBOL_VECTOR option. (For more information on the extern models, see HP C User's Guide for OpenVMS Systems.)
If the linker detects this condition, it issues the following error:
%LINK-E-SHRSYMFND, shareable image psect <name> was pointed to by a symbol definition %LINK-E-NOIMGFIL, image file not created |
The link continues, but no image is created. To work around this restriction, change the symbol vector keyword to DATA, or recompile your C program with the qualifier /EXTERN=COMMON.
For more information, see the HP C User's Guide for OpenVMS Systems.
If the section specified in a SYMBOL_VECTOR= option does not exist, the linker issues a warning, places zeros in the symbol vector entry and does not create an entry for the section in the image's GST.
The linker maintains separate name spaces for global symbol names and section names. As described in Chapter 2, the section names are not used to resolve an undefined symbol. Because of the different name spaces, it is possible to specify an identical name in a symbol vector option when exporting a global symbol and a section. This depends on the main module's extern model and which entry in the symbol vector resolves or overlays a reference from the main module.
Although this is correct linker behavior, using identical names in this manner can create confusion. As such, HP discourages the use this feature. |
4.2.2 Creating Upwardly Compatible Shareable Images
The SYMBOL_VECTOR= option allows you to create upwardly compatible shareable images. 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 ensure upward compatibility when using a SYMBOL_VECTOR= option, you must preserve the order and placement of the entries in the symbol vector with each relinking. Do not delete existing entries and only add new entries at the end of the list. If you use multiple SYMBOL_VECTOR= option statements in a single options file to declare the universal symbols, you must also maintain the order of the SYMBOL_VECTOR= option statements in the options file. If you specify SYMBOL_VECTOR= options in separate options files, make sure the linker always processes the options files in the same order. (The linker creates only one symbol vector for an image.)
Use the GSMATCH mechanism to record any changes you make. GSMATCH handles the changes as follows:
- Major changes or incompatible changes, different orders of existing symbol vector entries, or deletion of entries most likely will result in a mismatch of the major ID number.
- Minor changes or compatible changes, or addition of new entries should result in a match of the major ID number but in a mismatch of the minor ID number.
By using the major and minor IDs in this manner, along with the LEQUAL keyword, you can create upwardly compatible shareable images. For example, a main image linked against minor ID 2 of a shareable image is not allowed to run against the shareable image with a minor ID less than 2, if the shareable image was linked with the keyword LEQUAL. For more information, see the description of the GSMATCH= option in Part 4.
| Previous | Next | Contents | Index |