Document revision date: 19 July 1999

You can control in which cluster the linker places an input file by using either of the following linker options:

• CLUSTER= option
• COLLECT= option

The CLUSTER= option causes the linker to create a named cluster and to place in the cluster the object modules specified in the option. (The linker puts shareable images in their own clusters by default.)

For example, you can use the CLUSTER= option to fix the link operation illustrated in Section 2.2.4, where the link failed because a shareable image was processed selectively. To make the linker process the object module MY_MAIN.OBJ before it processes the shareable image MY_MAIN.EXE, put the object module in a named cluster. In the following example, the /EXECUTABLE qualifier is specified on the command line to specify the name of the resultant image, because MY_MAIN is not specified on the command line.

$ link/executable=my_main sys$input/opt CLUSTER=mymain_clus,,,my_main my_math/shareable/selective_search [Ctrl/Z]

The Object Module Synopsis section of the image map file verifies that the linker processed the object module MY_MAIN before it processed the shareable image MY_MATH, as in the following map file excerpt:

+------------------------+ ! Object Module Synopsis ! +------------------------+ Module Name Ident Bytes File ----------- ----- ----- ----- MY_MAIN V1.0 105 MY_MAIN.OBJ;1 MY_MATH V1.0 12 MY_MATH.EXE;1 . . .

2.3.2.2 Using the COLLECT= Option to Control Clustering

You can also create a named cluster by specifying the COLLECT= option. The COLLECT= option directs the linker to put specific program sections in a named cluster. The linker creates the cluster if it does not already exist. Note that the COLLECT= option manipulates program sections, not input files.

The linker sets the global (GBL) attribute of the program sections specified in a COLLECT= option to enable a global search for the definition of that program section.

2.4 Resolving Symbols Defined in the OpenVMS Executive

For VAX linking, you link against the OpenVMS executive by specifying the system symbol table (SYS$LIBRARY:SYS.STB) in the link operation. Because a symbol table file is an object module, the linker processes the symbol table file as it would any other object module.

For Alpha linking, you link against the OpenVMS executive by specifying the /SYSEXE qualifier. When this qualifier is specified, the linker selectively processes the system shareable image SYS$BASE_IMAGE.EXE located in the directory pointed to by the logical name ALPHA$LOADABLE_IMAGES. The linker does not process SYS$BASE_IMAGE.EXE by default.

Note that, because the linker is processing a shareable image, references to symbols in the OpenVMS executive are fixed up at image activation, not fully resolved at link time as they are for VAX linking. Also note that the linker looks for SYS$BASE_IMAGE.EXE in the directory pointed to by the logical name ALPHA$LOADABLE_IMAGES, not in the directory pointed to by the logical name SYS$LIBRARY as for VAX linking.

When the /SYSEXE qualifier is specified, the linker processes the file selectively. To disable selective processing, specify the /SYSEXE=NOSELECTIVE qualifier. For more information about using the /SYSEXE qualifier, see the description of the qualifier in Part 2.

Relation to Default Library Processing

When you specify the /SYSEXE qualifier, the linker processes the SYS$BASE_IMAGE.EXE file after processing the system shareable image library, IMAGELIB.OLB, and before processing the system object library, STARLET.OLB. (Note that the linker also processes the system service shareable image, SYS$PUBLIC_VECTORS.EXE, when it processes STARLET.OLB by default.)

The /SYSSHR and /SYSLIB qualifiers, which control processing of the default system libraries, do not affect SYS$BASE_IMAGE.EXE processing. When the /NOSYSSHR qualifier is specified with the /SYSEXE qualifier, the linker does not process IMAGELIB.OLB, but still processes SYS$BASE_IMAGE.EXE and then STARLET.OLB and SYS$PUBLIC_VECTORS.EXE. When /NOSYSLIB is specified, the linker does not process IMAGELIB.OLB, STARLET.OLB, or SYS$PUBLIC_VECTORS, but still processes SYS$BASE_IMAGE.EXE.

To process SYS$BASE_IMAGE.EXE before the shareable images in IMAGELIB.OLB, specify SYS$BASE_IMAGE.EXE in a linker options file as you would any other shareable image. If you specify SYS$BASE_IMAGE.EXE in your options file, do not use the /SYSEXE qualifier.

Figure 2-4 illustrates how the /SYSEXE qualifier, in combination with the /SYSSHR and /SYSLIB qualifiers, can affect linker processing. (The default syntax illustrated in the figure is rarely specified.)

Figure 2-4 Linker Processing of Default Libraries and SYS$BASE_IMAGE.EXE

In the dialects of MACRO, BLISS, and Pascal supported on both VAX and Alpha systems, you can define a global symbol as either strong or weak, and you can make either a strong or a weak reference to a global symbol.

In these languages, all definitions and references are strong by default. To make a weak definition or a weak reference, you must use the .WEAK assembler directive (in MACRO), the WEAK attribute (in BLISS), or the WEAK_GLOBAL or WEAK_EXTERNAL attribute (in Pascal).

The linker records each symbol definition and each symbol reference in its global symbol table, noting for each whether it is strong or weak. The linker processes weak references differently from strong references and weakly defined symbols differently from strongly defined symbols.

A strong reference can be made to a weakly defined symbol or to a strongly defined symbol.

For a strong reference, the linker checks all explicitly specified input modules and libraries and all default libraries for a definition of the symbol. In addition, if the linker cannot locate the definition needed to resolve the strong reference, it assigns the symbol a value of 0 and reports an error. By default, all references are strong.

A weak reference can be made to a weakly defined symbol or to a strongly defined symbol. In either case, the linker resolves the weak reference in the same way it does a strong reference, with the following exceptions:

• The linker will not search library modules that have been specified with the /LIBRARY qualifier or default libraries (user-defined or system) solely to resolve a weak reference. If, however, the linker resolves a strong reference to another symbol in such a module, it will also use that module to resolve any weak references.
• If the linker cannot locate the definition needed to resolve a weak reference, it assigns the symbol a value of 0, but does not report an error (as it does if the reference is strong). If, however, the linker reports any unresolved strong references, it will also report any unresolved weak references.

One purpose of making a weak reference arises from the need to write and test incomplete programs. The resolution of all symbolic references is crucial to a successful linking operation. Therefore, a problem arises when the definition of a referenced global symbol does not yet exist (as would be the case, for example, if the global symbol definition is an entry point to a module that is not yet written). The solution is to make the reference to the symbol weak, which informs the linker that the resolution of this particular global symbol is not crucial to the link operation.

By default, all global symbols in all VAX and Alpha languages have a strong definition.

A strongly defined symbol in a library module is included in the library symbol table; a weakly defined symbol in a library module is not. As a result, if the module containing the weak symbol definition is in a library but has not been specified for inclusion by means of the /INCLUDE qualifier, the linker will not be able to resolve references (strong or weak) to the symbol. If, however, the linker has selected that library module for inclusion (in order to resolve a strong reference), it will be able to resolve references (strong or weak) to the weakly defined symbol.

If the module containing the weak symbol definition is explicitly specified either as an input object file or for extraction from a library (by means of the /INCLUDE qualifier), the weak symbol definition is as available for symbol resolution as a strong symbol definition.

This chapter describes how the linker creates an image from the input files you specify in a link operation and how you can control image file creation by using linker qualifiers and options.

3.1 Overview

After the linker has resolved all symbolic references between the input files specified in the LINK command (described in Chapter 2), the linker knows all the object modules and shareable images that are required to create the image. For example, the linker has extracted from libraries specified in the LINK command those modules that contain the definitions of symbols required to resolve symbolic references in other modules. The linker must now combine all these modules into an image.

To create an image, the linker must perform the following processing:

• Determine the memory requirements of the image. The memory requirements of an image are the sum of the memory requirements of each object module included in the link operation. The language processors that create the object modules specify the memory requirements of an object module as program section definitions. A program section represents an area of memory that has a name, a length, and other characteristics, called attributes, which describe the intended or permitted usage of that portion of memory. Section 3.2 describes program sections.
  The linker processes the program section definitions in each object module, combining program sections with similar attributes into an image section. Each image section specifies the size and attributes of a portion of the virtual memory of an image. The image activator uses the image section attributes to determine the characteristics of the physical memory pages into which it loads the image, such as protection.
  Figure 3-1 illustrates how memory requirements are communicated from the language processor to the linker and from the linker to the image activator. Section 3.3 provides more information about this process.

  Figure 3-1 Communication of Image Memory Requirements

  ---

  
  Note that shareable images included in link operations have already been processed by the linker. These images are separate images with their own memory requirements, as specified by their own image sections. The linker does, however, create special global image section descriptors (GISDs) for each shareable image to which an image has been linked. The image activator activates these shareable images at run time.
• Initialize the image. When image sections are first created, they are empty. In this step of linker processing, the linker fills the image sections with the machine code and data, as specified by the Text Information and Relocation (TIR) commands in the object module. Section 3.4 provides more information about this process.
  For Alpha linking, the linker also attempts to optimize the performance of an image by replacing Jump to Subroutine (JSR) instruction sequences with the more efficient Branch to Subroutine (BSR) instruction sequences. See Section 1.4 for more information.

After creating image sections and filling them with binary code and data, the linker writes the image to an image file. Section 3.4.1 describes this process. To keep the size of image files manageable, the linker does not allocate space in the image file for image sections that have not been initialized with any data unless this function has been disabled (that is, the linker does not write pages of zeros to the image file). The linker can create demand-zero image sections, which the operating system initializes at run time when a reference to the image section requires the operating system to move the pages into memory. Section 3.4.3 describes how the linker creates demand-zero image sections.

3.2 Creating Program Sections

Language processors create program sections and define their attributes. The number of program sections created by a language processor and the attributes of these program sections are dependent upon language semantics. For example, some programming languages implement global variables as separate program sections with a particular set of attributes. Programmers working in high-level languages typically have little direct control over the program sections created by the language processor. Medium- and low-level languages provide programmers with more control over program section creation. For more information about the program section creation features of a particular programming language, see the language processor documentation.

In general, the linker does not create program sections. However, for Alpha linking, the linker creates a special program section for a shareable image, named $SYMVECT, which contains the symbol vector of the shareable image.

Program Section Attributes

The language processors define the attributes of the program sections they create and communicate these attributes to the linker in program section definition records in the global symbol directory (GSD) in an object module. (The GSD also contains global symbol definitions and references, as described in Chapter 2.)

Program section attributes control various characteristics of the area of memory described by the program section, such as the following:

• Access. Using program section attributes, compilers can prohibit some types of access, such as write access. Using other program section attributes, compilers can allow access to the program section by more than one process.
• Positioning. By specifying certain program section attributes, compilers can specify to the linker how it should position the program section in memory.

Program section attributes are Boolean values, that is, they are either on or off. Table 3-1 lists all program section attributes with the keyword you can use to set or clear the attribute, using the PSECT_ATTR= option. (For more information about using the PSECT_ATTR= option, see Section 3.3.6.)

For example, to specify that a program section should have write access, specify the writability attribute as WRT. To turn off an attribute, specify the negative keyword. Some attributes have separate keywords that express the negative of the attribute. For example, to turn off the global attribute (GBL), you must specify the local attribute (LCL). Note that the alignment of a program section is not strictly considered an attribute of the program section. However, because you can set it using the PSECT_ATTR= option, it is included in the table.

For Alpha linking, the EXE attribute is propagated to the image section descriptor where it is used by the Install utility when it is installing the image as a resident image. (For information about resident images, see the description of the /SECTION_BINDING qualifier in Part 2.)

Table 3-1 Program Section Attributes

Attribute	Keyword	Description
Alignment	--	Specifies the alignment of the program section as an integer that represents the power of 2 required to generate the desired alignment. For certain alignments, the linker supports keywords to express the alignment. The following table lists all the alignments supported by the linker with their keywords: Power of 2 Keyword Meaning 0 BYTE Alignment on byte boundaries. 1 WORD Alignment on word boundaries. 2 LONG Alignment on longword boundaries. 3 QUAD Alignment on quadword boundaries. 4 OCTA Alignment on octaword boundaries. 9 -- Alignment on 512-byte boundaries. 13 -- Alignment on 8 KB boundaries. 14 -- Alignment on 16 KB boundaries. 15 -- Alignment on 32 KB boundaries. 16 -- Alignment on 64 KB boundaries. -- PAGE Alignment on the default target page size, which is 64 KB for Alpha linking and 512 bytes for VAX linking. You can override this default by specifying the /BPAGE qualifier.
Position Independence	PIC/NOPIC	Specifies that the program section can run anywhere in virtual address space. Applicable in shareable images only. Note that this attribute is not meaningful for Alpha images, but it is still used to sort program sections.
Overlaid/Concatenated	OVR/CON	When set to OVR, specifies that the linker may combine (overlay) this program section with other program sections with the same name and attribute settings. Program sections that are overlaid are assigned the same base address. When set to CON, the linker concatenates the program sections.
Relocatable/Absolute	REL/ABS	When set to REL, specifies that the linker can place the program section anywhere in virtual memory, according to the memory allocation strategy for the type of image being produced. When set to ABS, this attribute specifies that the program section is an absolute program section that contains no binary data or code and appears to be based at virtual address 0. Absolute program sections are used by compilers primarily to define constants.
Global/Local	GBL/LCL	When set to GBL, specifies that the linker should gather contributions to the program section from all clusters and place them in the same image section. When set to LCL, the linker gathers program sections into the same image section only if they are in the same cluster. The memory for a global program section is allocated in the cluster that contains the first contributing module.
Shareability	SHR/NOSHR	Specifies that the program section can be shared between several processes. Only used to sort program sections in shareable images.
Executability	EXE/NOEXE	Specifies that the program section contains executable code. If an image transfer address is defined in a nonexecutable program section, the linker issues a diagnostic message.++
Writability	WRT/NOWRT	Specifies that the contents of a program section can be modified at run time.
Protected Vectors	VEC/NOVEC	Specifies that the program section contains privileged change-mode vectors or message vectors. In shareable images, image sections with the VEC attribute are automatically protected.
Solitary	SOLITARY	Specifies that the linker should place this program section in its own image section. Useful for programs that map data into specific locations in their virtual memory space. Note that compilers do not set this attribute. You can set this attribute using the PSECT_ATTR= option.
++Unmodified	NOMOD/MOD	When set, specifies that the program section has not been initialized (NOMOD). On Alpha systems, the linker uses this attribute to create demand zero sections; see Section 3.4.3. Only compilers can set this attribute. You can clear this attribute only by specifying the MOD keyword in the PSECT_ATTR= option.
++COM	--	Used by the DEC C compiler to implement the relaxed symbol reference/definition model for external variables. See the C documentation for more information. This attribute cannot be modified using the PSECT_ATTR= option.
Readability	RD	Reserved by Digital.
User/Library	USR/LIB	Reserved by Digital. To ensure future compatibility, this attribute should be clear.

To illustrate program section creation, consider the program sections created by the VAX C compiler when it processes the sample programs in the following examples.

Example 3-1 Sample Program MYTEST.C

extern int global_data; int myadd(); int mysub(); main() { int num1, num2, res1, res2; static int my_data; num1 = 5; num2 = 6; res1 = myadd( num1, num2 ); res2 = mysub( num1, num2 ); printf("res1 = %d, res2 =%d, globaldata=%d\n", res1,res2,global_data); }

Example 3-2 Sample Program MYADD.C

#include <stdio.h> myadd(value_1,value_2) int value_1; int value_2; { int result; static int add_data; printf("In MYADD.C\n"); result = value_1 + value_2; return( result ); }

Example 3-3 Sample Program MYSUB.C

int global_data = 5; mysub(value_1,value_2) int value_1; int value_2; { int result; static int sub_data; result = value_1 - value_2; return( result ); }

To see what program sections the VAX C compiler creates for these programs, use the ANALYZE/OBJECT utility to examine the global symbol directory (GSD) in each object module. (Note that the names the language processors assign to program sections are architecture specific.)

Example 3-4 presents an excerpt from the analysis of the object module MYTEST.OBJ. Only the program section definitions are included in the excerpt.

Example 3-4 Program Sections Generated by Example 3-1

4. GLOBAL SYMBOL DIRECTORY (OBJ$C_GSD), 138 bytes . . . 6) Program Section Definition (GSD$C_PSC) (1) alignment: 4-byte boundary <-- psect 0 (2) attribute flags: (0) GPS$V_PIC 1 (1) GPS$V_LIB 0 (2) GPS$V_OVR 0 (3) GPS$V_REL 1 (4) GPS$V_GBL 0 (5) GPS$V_SHR 1 (6) GPS$V_EXE 1 (7) GPS$V_RD 1 (8) GPS$V_WRT 0 (9) GPS$V_VEC 0 (3) allocation: 63 (%X'0000003F') (4) symbol: "$CODE" 7) Program Section Definition (GSD$C_PSC) alignment: 4-byte boundary <-- psect 1 attribute flags: (0) GPS$V_PIC 1 (1) GPS$V_LIB 0 (2) GPS$V_OVR 0 (3) GPS$V_REL 1 (4) GPS$V_GBL 0 (5) GPS$V_SHR 0 (6) GPS$V_EXE 0 (7) GPS$V_RD 1 (8) GPS$V_WRT 1 (9) GPS$V_VEC 0 allocation: 4 (%X'00000004') symbol: "DATA" 8) Program Section Definition (GSD$C_PSC) alignment: 4-byte boundary <-- psect 2 attribute flags: (0) GPS$V_PIC 1 (1) GPS$V_LIB 0 (2) GPS$V_OVR 1 (3) GPS$V_REL 1 (4) GPS$V_GBL 1 (5) GPS$V_SHR 1 (6) GPS$V_EXE 0 (7) GPS$V_RD 1 (8) GPS$V_WRT 1 (9) GPS$V_VEC 0 allocation: 4 (%X'00000004') symbol: "GLOBAL_DATA" 9) Program Section Definition (GSD$C_PSC) alignment: 4-byte boundary <-- psect 3 attribute flags: (0) GPS$V_PIC 1 (1) GPS$V_LIB 0 (2) GPS$V_OVR 0 (3) GPS$V_REL 1 (4) GPS$V_GBL 0 (5) GPS$V_SHR 0 (6) GPS$V_EXE 0 (7) GPS$V_RD 1 (8) GPS$V_WRT 1 (9) GPS$V_VEC 0 allocation: 36 (%X'00000024') symbol: "$CHAR_STRING_CONSTANTS" . . .

	privacy and legal statement
4548PRO_005.HTML