Document revision date: 30 March 2001

## OpenVMS Linker Utility Manual

Previous | Contents | Index

### A.3.1 Program Section Definition Subrecord (GSD$C_PSC)

The linker assigns program sections an identifying index number as it encounters their respective GSD subrecords, that is, the GSD$C_PSC records. The linker assigns these numbers in sequential order, assigning 0 to the first program section it encounters, 1 to the second, and so on, up to the maximum allowable limit of 65,535 (216 --1) within any single object module.

Program sections are referred to by other object language records by means of this program section index. For example, the global symbol specification subrecord (GSD$C_SYM) contains a field that specifies the program section index. This field is used to locate the program section containing a symbol definition. Also, TIR commands use the program section index.

Of course, care is required to ensure that program sections are defined to the linker (and thus assigned an index) in proper order so that other object language records that reference a program section by means of the index are in fact referencing the correct program section.

The following presents the name, symbolic representation, and length of each field in the program section definition subrecord. The listing includes a symbolic value or an explanation of the contents of the field, where appropriate. Note that the names of fields in this subrecord begin with GPS rather than PSC.

GSD TYPE | Name: GPS$B_GSDTYP
| Length: 1 byte

The GSD type is GSD$C_PSC.

ALIGNMENT | Name: GPS$B_ALIGN
| Length: 1 byte

This field specifies the virtual address boundary at which the program section is placed. Each module contributing to a particular program section may specify its own alignment unless the program section is overlaid, in which case each module must specify the same alignment. An overlaid program section is one in which the value of flag bit 2 (GPS$V_OVR) is not equal to 0.

The contents of the alignment field is a number from 0 to 9, which is interpreted as a power of 2; the value of this expression is the alignment in bytes. The value 9 in the alignment field indicates alignment on page boundaries, which is the limit for program section alignment. Table A-2 illustrates some common alignment field values.

Table A-2 Alignment Field Values
Value | Alignment
--- | ---
0 | 1 (BYTE)
1 | 2 (WORD)
2 | 4 (LONGWORD)
3 | 8 (QUADWORD)
9 | PAGE

FLAGS | Name: GPS$W_FLAGS
| Length: 2 bytes

This field is a word-length bit field, each bit indicating (when set) that the program section has the corresponding attribute. (See Section 3.2 for a description of program section attributes.) The following table lists the numbers, names, and corresponding meanings of each bit in the field:

Bit | Name | Meaning if Set
--- | --- | ---
0 | GPS$V_PIC | Program section is position independent.
1 | GPS$V_LIB | Program section is defined in the symbol table of a shareable image, to which this image is bound. This bit is used by the linker and should not be set in user-defined program sections.
2 | GPS$V_OVR | Contributions to this program section by more than one module are overlaid.
3 | GPS$V_REL | Program section is relocatable. If this bit is not set, the program section is absolute and therefore contains only symbol definitions. Note that memory is not allocated for absolute program sections.
4 | GPS$V_GBL | Program section is global.
5 | GPS$V_SHR | Program section is shareable between two or more active processes.
6 | GPS$V_EXE | Program section is executable.
7 | GPS$V_RD | Program section is readable.
8 | GPS$V_WRT | Program section is writable.
9 | GPS$V_VEC | Program section contains change mode dispatch vectors or message vectors.
10--15 |  | Reserved.

ALLOCATION | Name: GPS$L_ALLOC
| Length: 4 bytes

This field contains the length in bytes of this module's contribution to the program section. If the program section is absolute, the value of the allocation field must be zero.

PSECT NAME LENGTH | Name: GPS$B_NAMLNG
| Length: 1 byte

This field contains the length in characters of the program section name.

PSECT NAME | Name: GPS$T_NAME
| Length: variable, 1 to 31 bytes

This field contains the name of the program section in ASCII format.

### A.3.2 Global Symbol Specification Subrecord (GSD$C_SYM)

The global symbol specification subrecord is used to describe the nature of a symbol (global or universal, relocatable or absolute) and how it is being used (definition or reference, weak or strong). This information is specified in the FLAGS field of the subrecord.

There are two formats for a global symbol specification subrecord, one for a symbol definition and one for a symbol reference. A symbol definition is indicated when bit 1 (GSY$V_DEF) in the FLAGS field is set, that is, when GSY$V_DEF = 1. A symbol reference is indicated when GSY$V_DEF = 0.

Section A.3.2.1 describes the format of the global symbol specification subrecord for symbol definitions; Section A.3.2.2 does the same for symbol references. Note that the PSECT INDEX and VALUE fields are present only for symbol definitions, not for symbol references.

#### A.3.2.1 GSD Subrecord for a Symbol Definition

The following presents the name, symbolic representation, and length of each field in the global symbol specification subrecord for a symbol definition. The listing includes a symbolic value or an explanation of the contents of the field, where appropriate.

GSD TYPE | Name: SDF$B_GSDTYP
| Length: 1 byte

The GSD type is GSD$C_SYM.

DATA TYPE | Name: SDF$B_DATYP
| Length: 1 byte

This field describes the data type of the global symbol. The linker currently ignores this field.

FLAGS | Name: SDF$W_FLAGS
| Length: 2 bytes

This field is a 2-byte bit field, whose bits describe the strong global symbol. Only bits 0 through 3 are used. The following table lists the numbers, names, and meanings of each bit in the field:

Bit | Name | Meaning
--- | --- | ---
0 | GSY$V_WEAK | When this bit is set, a weak symbol definition is indicated; when clear, a strong symbol definition.
1 | GSY$V_DEF | This bit is set for a symbol definition.
2 | GSY$V_UNI | When this bit is set, a universal symbol definition is indicated; when clear, a global symbol definition. Note that when this bit is set, the value of GSY$V_WEAK is ignored.
3 | GSY$V_REL | When this bit is set, the symbol is defined as relocatable; when clear, as absolute. When it is relocated, the value of a relocatable symbol is augmented by the base address of the module's contribution to the program section.
4--15 |  | Reserved.

PSECT INDEX | Name: SDF$B_PSINDX
| Length: 1 byte

This field contains the program section index, described in Section A.3.1. This field identifies the program section that contains the symbol definition. It may contain a number from 0 through 255 (28 --1).

VALUE | Name: SDF$L_VALUE
| Length: 4 bytes

This field contains the value assigned to the symbol by the language processor.

NAME LENGTH | Name: SDF$B_NAMLNG
| Length: 1 byte

This field contains the length in characters of the symbol name.

SYMBOL NAME | Name: SDF$T_NAME
| Length: variable, 1 to 31 bytes

This field contains the symbol name in ASCII format.

#### A.3.2.2 GSD Subrecord for a Symbol Reference

The following presents the name, symbolic representation, and length of each field in the global symbol specification subrecord for a symbol reference. The listing includes a symbolic value or an explanation of the contents of the field, where appropriate.

GSD TYPE | Name: SRF$B_GSDTYP
| Length: 1 byte

The GSD type is GSD$C_SYM.

DATA TYPE | Name: SRF$B_DATYP
| Length: 1 byte

This field describes the data type of a global symbol. The linker currently ignores this field.

FLAGS | Name: SRF$W_FLAGS
| Length: 2 bytes

This field is a 2-byte bit field, whose bits describe the global symbol. Only bits 0 through 3 are used. The following are the numbers, names, and corresponding meanings of each bit in the field:

Bit | Name | Meaning
--- | --- | ---
0 | GSY$V_WEAK | When this bit is set, a weak symbol definition is indicated; when clear, a strong symbol definition.
1 | GSY$V_DEF | This bit is set for a symbol definition.
2 | GSY$V_UNI | The linker ignores the value of this bit for a symbol reference.
3 | GSY$V_REL | The linker ignores the value of this bit for a symbol reference.
4--15 |  | Reserved.

NAME LENGTH | Name: SRF$B_NAMLNG
| Length: 1 byte

This field contains the length in characters of the symbol name.

SYMBOL NAME | Name: SRF$T_NAME
| Length: variable, 1 to 31 bytes

This field contains the symbol name in ASCII format.

### A.3.3 Entry-Point-Symbol-and-Mask-Definition Subrecord (GSD$C_EPM)

The following presents the name, symbolic representation, and length of each field in the entry-point-symbol-and-mask-definition subrecord. The listing includes a symbolic value or an explanation of the contents of the field, where appropriate.

GSD TYPE | Name: EPM$B_GSDTYP
| Length: 1 byte

The GSD type is GSD$C_EPM.

DATA TYPE | Name: EPM$B_DATYP
| Length: 1 byte

This field describes the data type of a global symbol. The linker currently ignores this field.

FLAGS | Name: EPM$W_FLAGS
| Length: 2 bytes

This field is a 2-byte bit field, whose bits describe the strong global symbol. Only bits 0 through 3 are used. The following are the numbers, names, and corresponding meanings of each bit in the field:

Bit | Name | Meaning
--- | --- | ---
0 | GSY$V_WEAK | When this bit is set, a weak symbol definition is indicated; when clear, a strong symbol definition.
1 | GSY$V_DEF | This bit is set for a symbol definition.
2 | GSY$V_UNI | When this bit is set, a universal symbol definition is indicated; when clear, a global symbol definition. Note that when this bit is set, the value of GSY$V_WEAK is ignored.
3 | GSY$V_REL | When this bit is set, the symbol is defined as relocatable; when clear, as absolute. When it is relocated, the value of a relocatable symbol is augmented by the base address of the module's contribution to the program section.
4--15 |  | Reserved.

PSECT INDEX | Name: EPM$B_PSINDX
| Length: 1 byte

This field contains the program section index, described in Section A.3.2. This field identifies the program section that contains the symbol definition. It may contain a number from 0 through 255 (28 --1).

VALUE | Name: EPM$L_ADDRS
| Length: 4 bytes

This field contains the value assigned to the symbol by the language processor.

ENTRY MASK | Name: EPM$W_MASK
| Length: 2 bytes

The point of entry to a procedure invoked by a CALLS or CALLG instruction has an entry mask. Transfer vectors to these procedures also use entry masks. The language processor uses a TIR command to direct the linker to insert the mask at the procedure entry point or at the transfer vector.

NAME LENGTH | Name: EPM$B_NAMLNG
| Length: 1 byte

This field contains the length in characters of the symbol name.

SYMBOL NAME | Name: EPM$T_NAME
| Length: variable, 1 to 31 bytes

This field contains the symbol name in ASCII format.

### A.3.4 Procedure-with-Formal-Argument-Definition Subrecord (GSD$C_PRO)

The following presents the name, symbolic representation, and length of each field in the procedure-with-formal-argument-definition subrecord. The listing includes a symbolic value or an explanation of the contents of the field, where appropriate.

GSD TYPE | Name: PRO$B_GSDTYP
| Length: 1 byte

The GSD type is GSD$C_PRO.

DATA TYPE | Name: PRO$B_DATYP
| Length: 1 byte

This field describes the data type of a global symbol. The linker currently ignores this field.

FLAGS | Name: PRO$W_FLAGS
| Length: 2 bytes

This field is a 2-byte bit field, whose bits describe the strong global symbol. Only bits 0 through 3 are used. The following are the numbers, names, and corresponding meanings of each bit in the field:

Bit | Name | Meaning
--- | --- | ---
0 | GSY$V_WEAK | When this bit is set, a weak symbol definition is indicated; when clear, a strong symbol definition.
1 | GSY$V_DEF | This bit is set for a symbol definition.
2 | GSY$V_UNI | When this bit is set, a universal symbol definition is indicated; when clear, a global symbol definition. Note that when this bit is set, the value of GSY$V_WEAK is ignored.
3 | GSY$V_REL | When this bit is set, the symbol is defined as relocatable; when clear, as absolute. When it is relocated, the value of a relocatable symbol is augmented by the base address of the module's contribution to the program section.
4--15 |  | Reserved.

PSECT INDEX | Name: PRO$B_PSINDX
| Length: 1 byte

This field contains the program section index, described in Section A.3.2. This field identifies the program section that contains the symbol definition. It may contain a number from 0 through 255 (28 --1).

VALUE | Name: PRO$L_ADDRS
| Length: 4 bytes

This field contains the value assigned to the symbol by the language processor.

ENTRY MASK | Name: PRO$W_MASK
| Length: 2 bytes

The point of entry to a procedure invoked by a CALLS or CALLG instruction has an entry mask. Transfer vectors to these procedures also use entry masks. The language processor uses a TIR command to direct the linker to insert the mask at the procedure entry point or at the transfer vector.

NAME LENGTH | Name: PRO$B_NAMLNG
| Length: 1 byte

This field contains the length in characters of the symbol name.

SYMBOL NAME | Name: PRO$T_NAME
| Length: variable, 1 to 31 bytes

This field contains the symbol name in ASCII format.

MINIMUM ACTUAL ARGUMENTS | Name: FML$B_MINARGS
| Length: 1 byte

This field specifies the minimum number of arguments required for a valid call to this procedure. Permissible values are 0 to 255. The number must include the function return value if it exists.

MAXIMUM ACTUAL ARGUMENTS | Name: FML$B_MAXARGS
| Length: 1 byte

This field specifies the maximum number of arguments that may be included in a valid call to this procedure. Permissible values are 0 to 255. Note that the linker does not perform argument validation; however, it will issue a warning message if the value of MINIMUM ACTUAL ARGUMENTS is greater than the value of MAXIMUM ACTUAL ARGUMENTS.

FORMAL ARG1 DESCRIPTOR | Name: None
| Length: variable, 2 to 256 bytes

This field specifies a single formal argument descriptor. There is a FORMAL ARG DESCRIPTOR field for each formal argument specified. This field contains three subfields; its format is displayed at the end of this section.

FORMAL ARGn DESCRIPTOR | Name: None
| Length: variable, 2 to 256 bytes

This field specifies the last (n) formal argument descriptor and is identical in format to previous formal argument descriptor fields. Note that if there is a function return value, this field specifies it.

Each FORMAL ARG DESCRIPTOR field contains three subfields. The content and format are as follows:

ARG VAL CTL | ARG$B_VALCTL
| Length: 1 byte

This field is the argument validation control byte. Bits 0 and 1 together define the argument passing mechanism (ARG$V_PASSMECH). Bits 2 through 7 are ignored. There are four possible values for ARG$V_PASSMECH corresponding to the four possible values (0 through 3) resulting from the combination of the values of bits 0 and 1:

ARG$V_PASSMECH | Name | Description
--- | --- | ---
0 | ARG$K_UNKNOWN | Unspecified
1 | ARG$K_VALUE | By value
2 | ARG$K_REF | By reference
3 | ARG$K_DESC | By descriptor

REM BTYE CNT | Name: ARG$B_BYTECNT
| Length: 1 byte

This field contains the length in bytes of the remainder of the argument descriptor. Permissible values are 0 through 255. Because the linker does not perform argument validation, it uses the value of this field only to determine how many subsequent bytes to ignore.

DETAILED ARGUMENT DESCRIPTION | Name: None
| Length: variable, 0 to 255 bytes

This field contains a detailed description of the argument. The linker currently ignores this field.

Previous | Next | Contents | Index

| privacy and legal statement |
4548PRO_017.HTML