Updated: 11 December 1998

OpenVMS Linker Utility Manual

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

Note that if bits 2 through 7 in ARG$B_VALCTL are not equal to 0 or the value of ARG$B_BYTECNT is not equal to 0, or both, then recompiling the object module may be necessary if that argument validation is implemented in a future version of the linker.

A.3.5 Symbol-Definition-with-Word-Psect Subrecord (GSD$C_SYMW)

This subrecord is identical in format to the global symbol definition subrecord described in Section A.3.2.1, with the exception that the PSINDX field in this subrecord is 2 bytes long.

The field names in this record begin with SYMW, instead of SYM as in the global symbol definition subrecord. For example, in this subrecord the name of the GSD TYPE is SYMW$B_GSDTYP.

Note that the name of the PSECT INDEX field in this subrecord is SYMW$W_PSINDX.

A.3.6 Entry-Point-Definition-with-Word-Psect Subrecord (GSD$C_EPMW)

This subrecord is identical in format to the entry-point-symbol-and-mask-definition subrecord described in Section A.3.3, with the exception that the PSINDX field in this subrecord is 2 bytes long.

The field names in this record begin with EPMW, instead of EPM as in the entry-point-symbol-and-mask-definition subrecord. For example, in this subrecord the name of the GSD TYPE is EPMW$B_GSDTYP.

Note that the name of the PSECT INDEX field in this subrecord is EPMW$W_PSINDX.

A.3.7 Procedure-Definition-with-Word-Psect Subrecord (GSD$C_PROW)

This subrecord is identical in format to the procedure with formal argument definition subrecord described in Section A.3.4, with the exception that the PSINDX field in this subrecord is 2 bytes long.

The field names in this record begin with PROW, instead of PRO as in the procedure-with-formal-argument-definition subrecord. For example, in this subrecord the name of the GSD TYPE is PROW$B_GSDTYP.

Note that the name of the PSECT INDEX field in this subrecord is PROW$W_PSINDX.

A.3.8 Entity-Ident-Consistency-Check Subrecord (GSD$C_IDC)

This subrecord allows for the consistency checking of an entity at link time. Using this subrecord, a compiler may emit code to check the consistency of any type of entity that has either an ASCIC or binary ident string associated with it.

The following presents the name, symbolic representation, and length of each field in the entity ident consistency check subrecord. The listing includes a symbolic value or an explanation of the contents of the field, where appropriate.

GSD TYPE	Name: IDC$B_GSDTYP
	Length: 1 byte

The GSD type is GSD$C_IDC.

FLAGS	Name: IDC$W_FLAGS
	Length: 2 bytes

The FLAGS field is a 2-byte bit field, of which only the first five bits are used. When bit 0 (IDC$V_BINIDENT) is set, that is, when IDC$V_BINIDENT = 1, the ident is a 32-bit binary value; when clear, the ident is an ASCIC string.

Bits 1 and 2 (IDC$V_IDMATCH) specify the ident match control for 32-bit binary idents and are thus only significant when IDC$V_BINIDENT = 1. IDC$V_MATCH may take two values: 0 (IDC$C_LEQ) or 1 (IDC$C_EQUAL).

When IDC$V_MATCH = IDC$C_LEQ, the binary ident of the entity specified in the subrecord must be less than or equal to the binary ident of the entity that is listed in the entity name table.

When IDC$V_MATCH = IDC$C_EQUAL, the binary ident of the entity specified in the subrecord must be equal to the binary ident of the entity that is listed in the entity name table. Remaining values of IDC$V_MATCH, that is, the numbers 2 to 8, are reserved.

Bits 3 to 5 (IDC$V_ERRSEV) specify error message severity levels. When the value of IDC$V_ERRSEV is 0, the message severity is warning; when 1, success; when 2, error; when 3, informational; when 4, severe.

Bits 6 to 15 in the FLAGS field are reserved.

NAME LENGTH	Name: IDC$B_NAMLNG
	Length: 1 byte

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

ENTITY NAME	Name: IDC$T_NAME
	Length: variable, 1 to 31 bytes

This field contains the entity name in ASCII format.

IDENT LENGTH	Name: None
	Length: 1 byte

This field contains the length in bytes of the ident string. For binary idents, this field contains the value 4.

IDENT STRING	Name: None
	Length: variable, 1 to 31 bytes

This field contains the ident string. The ident string may be an ASCIC string or a 32-bit binary value. If this string specifies a 32-bit binary value, it consists of 24 bits of minor ident and 8 bits of major ident, analogous to the global section match values for a shareable image. If this string specifies an ASCIC string, its length is variable.

OBJECT NAME LENGTH	Name: None
	Length: 1 byte

This field contains the length in bytes of the name of the entity in the entity name table.

OBJECT NAME	Name: None
	Length: 1 to 31 bytes

This field contains the name of the entity in the entity name table.

When this GSD subrecord is processed during Pass 1, the linker searches the entity name table (which is a single name table for all entity types) for an entity of the same name. If the linker locates such an entity, it compares the idents. If the idents do not satisfy the specified match control value, the linker issues a warning message.

A.3.9 Environment-Definition/Reference Subrecord (GSD$C_ENV)

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

GSD TYPE	Name: ENV$B_GSDTYP
	Length: 1 byte

The GSD type is GSD$C_ENV.

FLAGS	Name: ENV$W_FLAGS
	Length: 2 bytes

This is a 2-byte bit field.

Bit 0 (ENV$V_DEF) is a bit mask. When ENV$V_DEF = 1, the subrecord describes an environment definition; when clear, an environment reference.

Bit 1 (ENV$V_NESTED) is set to indicate that the current environment is nested within another environment. The parent environment index is ENV$W_ENVINDX.

Bits 2 through 15 are not used.

ENVIRONMENT INDEX	Name: ENV$W_ENVINDX
	Length: 2 bytes

This field contains the environment index, a number from 0 through 65,535. As with a program section, each environment is assigned a number (its index) that the TIR records and GSD records use to refer to it.

If the current environment is contained within another environment (for example, a nested environment), then this field contains the index of the surrounding or "parent" environment. Otherwise, this field is 0. However, because a 0 could also be interpreted as the current environment being contained within environment 0, the ENV$V_NESTED bit may be tested to clear up this ambiguity.

NAME LENGTH	Name: ENV$B_NAMLNG
	Length: 1 bytes

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

ENVIRONMENT NAME	Name: ENV$T_NAME
	Length: variable, 1 to 31 bytes

This field contains the environment name.

The linker reports any undefined environments at the end of Pass 1. Note that a total of 65,535 environments may be defined or referenced in any single object module.

A.3.10 Module-Local Symbol Definition/Symbol Reference Subrecord (GSD$C_LSY)

This subrecord, as with the global symbol specification subrecord described in Section A.3.2, has two formats: one for a symbol definition and one for a symbol reference. The following subsections describe each of these formats.

A.3.10.1 Module-Local Symbol Definition

The format of a module-local symbol definition is identical to the format of the symbol-definition-with-word-psect subrecord described in Section A.3.5, with the following exceptions:

• The field names in this record begin with LSDF instead of SYMW as in the symbol-definition-with-word-psect subrecord. For example, in this subrecord the name of the GSD TYPE is LSDF$B_GSDTYP.
• The module-local symbol definition subrecord contains an additional field, directly following the FLAGS field and preceding the PSINDX field: the ENVIRONMENT INDEX field (LSDF$W_ENVINDX).
• Only two of the four bits in the FLAGS field are used in this subrecord. Because this is a definition, LSY$V_DEF must be set. Bit 3 (LSY$V_REL) is set or not set depending on whether the module-local symbol is relocatable or not relocatable, respectively. Bit 0 (LSY$V_WEAK) and bit 2 (LSY$V_UNI) are ignored because a module-local symbol may not be defined as either weak or universal.

The format of a module-local symbol reference is identical to the format of the global symbol reference subrecord described in Section A.3.2.2, with the following exceptions:

• The field names in this record begin with LSRF instead of SRF as in the global symbol reference subrecord. For example, in this subrecord the name of the GSD TYPE is LSRF$B_GSDTYP.
• The module-local symbol reference subrecord contains an additional field directly following the FLAGS field and preceding the NAME LENGTH field: the ENVIRONMENT INDEX field (LSRF$W_ENVINDX).
• Only bit 1 (LSY$V_DEF) in the FLAGS field is used. Because this is a reference, LSY$V_DEF must be 0. Bits 0, 2, and 3 are ignored.

This subrecord is identical in format to the entry-point-definition-with-word-psect subrecord described in Section A.3.6, with the following exceptions:

• The field names in this record begin with LEPM instead of EPMW as in the entry-point-definition-with-word-psect subrecord. For example, in this subrecord the name of the GSD TYPE is LEPM$B_GSDTYP.
• The module-local entry point definition subrecord contains an additional field directly following the FLAGS field and preceding the PSINDX field: the ENVIRONMENT INDEX field (LEPM$W_ENVINDX).

This subrecord is identical in format to the procedure-definition-with-word-psect subrecord described in Section A.3.7, with the following exceptions:

• The field names in this record begin with LPRO instead of PROW as in the procedure-definition-with-word-psect subrecord. For example, in this subrecord the name of the GSD TYPE is LPRO$B_GSDTYP.
• The module-local procedure definition subrecord contains an additional field directly following the FLAGS field and preceding the PSINDX field: the ENVIRONMENT INDEX field (LEPM$W_ENVINDX).

This subrecord is identical in format to the program section definition subrecord described in Section A.3.1, with the following exceptions:

• This subrecord is generated only by the linker and is reserved to the linker.
• This subrecord is only legal in the global symbol table (GST) of a shareable image.
• This subrecord contains an additional 4-byte field directly following the ALLOCATION field and preceding the PSECT NAME LENGTH field: the BASE field (SGPS$L_BASE). The BASE field contains the base address of this program section in the shareable image.
• The field names in this subrecord begin with SGPS instead of GPS as in the program section definition subrecord. For example, in this subrecord the name of the GSD TYPE is SGPS$B_GSDTYP.

This subrecord is identical in format to the global symbol definition subrecord described in Section A.3.2.1, with the exception of an additional longword field, SDFV$L_VECTOR.

The field names in this record begin with SDFV instead of SDF as in the global symbol definition subrecord. For example, in this subrecord the name of the GSD type field is SDFV$B_GSDTYPE instead of SDF$B_GSDTYPE.

This subrecord is reserved for use by Digital only.

A.3.15 Vectored-Entry-Point-Definition Subrecord (GSD$C_EPMV)

This subrecord is identical in format to the entry point symbol and mask definition subrecord described in Section A.3.3, with the exception of an additional longword field, EPMV$L_VECTOR.

The field names in this record begin with EPMV instead of EPM as in the entry-point-symbol-and-mask-definition subrecord. For example, in this subrecord the name of the GSD type field is EPMV$B_GSDTYPEl instead of EPM$B_GSDTYPEl.

This subrecord is reserved for use by Digital only.

A.3.16 Vectored-Procedure-Definition Subrecord (GSD$C_PROV)

This subrecord is identical in format to the procedure definition subrecord described in Section A.3.4, with the exception of an additional longword field, PROV$L_VECTOR.

The field names in this record begin with PROV instead of PRO as in the procedure definition subrecord. For example, in this subrecord the name of the GSD type field is PROV$B_GSDTYP instead of PRO$B_GSDTYP.

This subrecord is reserved for use by Digital only.

A.3.17 Symbol-Definition-with-Version-Mask Subrecord (GSD$C_SYMM)

This subrecord is identical in format to the global symbol definition subrecord described in Section A.3.2.1, with the exception of an additional longword field, SDFM$L_VERSION_MASK.

The field names in this record begin with SDFM instead of SDF as in the global symbol definition subrecord. For example, in this subrecord the name of the GSD type field is SDFM$B_GSDTYPE instead of SDF$B_GSDTYPE.

This subrecord is reserved for use by Digital only.

A.3.18 Entry-Point-Definition-with-Version-Mask Subrecord (GSD$C_EPMM)

This subrecord is identical in format to the entry-point-symbol-and-mask-definition subrecord described in Section A.3.3, with the exception of an additional longword field, EPMM$L_VERSION_MASK.

The field names in this record begin with EPMM instead of EPM as in the entry-point-symbol-and-mask-definition subrecord. For example, in this subrecord the name of the GSD type field is EPMM$B_GSDTYPE instead of EPM$B_GSDTYPE.

This subrecord is reserved for use by Digital only.

A.3.19 Procedure-Definition-with-Version-Mask Subrecord (GSD$C_PROM)

This subrecord is identical in format to the procedure definition subrecord described in Section A.3.4, with the exception of an additional longword field, PROV$L_VECTOR.

The field names in this record begin with PROV instead of PRO as in the procedure definition subrecord. For example, in this subrecord the name of the GSD type field is PROV$B_GSDTYP instead of PRO$B_GSDTYP.

This subrecord is reserved for use by Digital only.

A.4 Text Information and Relocation Records (OBJ$C_TIR)

A text information and relocation record contains commands and data that the linker uses to compute and record the contents of the image.

The linker's creation of the binary content of an image file is controlled by the language processor using the commands contained in TIR records.

A TIR record consists of the RECORD TYPE field (TIR$B_RECTYP) followed by one COMMAND field and one DATA field for each TIR command in the record. Because a TIR record may contain many TIR commands, it may be quite long. It may not, however, exceed the record size limit for the object module. This limit is set in the MAXIMUM RECORD SIZE field (MHD$W_RECSIZ) in the main module header record (MHD$C_MHD).

The fields in a TIR record are described in this section. Note that the description given for the first COMMAND and first DATA field applies to all TIR commands but one, the STORE IMMEDIATE command, while the description given for the second COMMAND and second DATA field applies only to the STORE IMMEDIATE command. This does not imply that the STORE IMMEDIATE command must follow other TIR commands; TIR commands may appear within the TIR record in any order.

RECORD TYPE	Name: TIR$RECTYP
	Length: 1 byte

The record type is OBJ$C_TIR.

COMMAND	Name: None
	Length: 1 byte

This field designates the TIR command. This description of the COMMAND field applies to all TIR commands except the STORE IMMEDIATE command, which is described in the following COMMAND field. There are 85 TIR commands (excluding the STORE IMMEDIATE command), and each has a positive number ranging from 0 to 84 that is used to encode the command in the field.

DATA	Name: None
	Length: variable

This field contains the data upon which the previously specified (in the COMMAND field) TIR command operates. The length of this field is implied by the command itself. For example, if the previous COMMAND field specifies a stack-byte command, the length of this DATA field is 1 byte.

COMMAND	Name: None
	Length: 1 byte

This field contains the name of a TIR command. This description of the COMMAND field applies only to the STORE IMMEDIATE command. The STORE IMMEDIATE command is designated by any negative number (bit 7 is set) in the COMMAND field. The absolute value of the COMMAND field is the length in bytes of the following DATA field. The STORE IMMEDIATE command directs the linker to write the contents of the DATA field directly to the output image file, without using the internal stack. Thus, from 1 to 128 bytes of data may be immediately stored by means of this command.

DATA	Name: None
	Length: variable

This field contains the data upon which the previously specified TIR command operates. The length of this field is given by the command itself. When the previous COMMAND field contains a STORE IMMEDIATE command, the length of this DATA field is the absolute value of the COMMAND field.

Most TIR commands operate on values on the linker's internal stack, which is longword-aligned at all times. Values placed on the stack by TIR commands are retained during processing of other record types; however, the stack must be completely collapsed when the EOM or EOMW record is processed. The minimum stack space available is never less than 25 elements.

TIR commands fall into four categories:

• Stack commands place data on the stack.
• Store commands pop data from the stack and write it to the output image file. The only exception is the STORE IMMEDIATE command, which writes data directly to the image file without using the stack.
• Operator commands perform arithmetic operations on data currently on the stack.
• Control commands reposition the linker's location counter.

In the interest of linker performance, a few implementation decisions and their possible side effects should be noted.

• The linker does not execute a STORE REPEATED command when the value being stored is zero. Such a command is, in effect, a null operation. The reason for this is twofold. First, the pages of an image are guaranteed to be zero anyway, unless otherwise initialized by the compiler. Second, demand-zero compression works only on pages that have not been initialized; thus, not allowing a STORE REPEATED command to initialize a page with zeros permits the linker to compress that page.
• The linker is a two-pass processor of object modules. It ignores TIR records on its first pass but processes them on its second pass to produce the output image file. TIR records are not processed if the linking operation is aborted because of a command or link-time error before the linker's second pass. Consequently, user or compiler errors (such as truncation errors) that are usually detectable during the linker's second pass are not detected in this case.
  TIR commands are described in the following four subsections. Section A.4.1 discusses the stack commands; Section A.4.2, the store commands; Section A.4.3, operator commands; and Section A.4.4, control commands. The commands are presented in numerical order, based on their equivalent numerical codes (in decimal), except for the STORE IMMEDIATE command, which does not have a specific numerical code. The STORE IMMEDIATE command has been described under the second TIR COMMAND.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4548PRO_018.HTML