Updated: 11 December 1998

OpenVMS Linker Utility Manual

The end-of-module (EOM) record declares the end of the module. Either this record or the end-of-module-with-word-psect (EOMW) record must be the last record in the object module.

If the module does not contain a program section that contains the transfer address, the EOM record is 2 bytes long, consisting of only the RECORD TYPE and ERROR SEVERITY fields.

If the module does contain a program section that contains the transfer address, the EOM record can be either 7 or 8 bytes long, depending on whether the optional TRANSFER FLAGS field is included.

The fields in an EOM record are described in the following table.

RECORD TYPE	Name: EOM$B_RECTYP
	Length: 1 byte

The record type is OBJ$C_EOM.

ERROR SEVERITY	Name: EOM$B_COMCOD
	Length: 1 byte

This field contains completion codes, which are generated by the language processor. This field may contain a value from 0 to 3, where each number corresponds to a completion code. Values from 4 to 10 are reserved, and values from 11 to 255 are ignored. The following table lists the name, corresponding value, and meaning of each of the four completion codes.

Value	Name	Meaning
0	EOM$C_SUCCESS	Successful compilation or assembly; no errors detected.
1	EOM$C_WARNING	Language processor generated warning messages. The linker issues a warning message and proceeds with the linking operation.
2	EOM$C_ERROR	Language processor generated severe errors. The linker issues an error message, proceeds with the linking operation, but does not produce an output image file.
3	EOM$C_ABORT	Language processor generated fatal errors. The linker aborts the linking operation.
4--10		Reserved.
11--255		Ignored.

PSECT INDEX	Name: EOM$B_PSINDX
	Length: 1 byte

This field contains the program section index of the program section within the module that contains the transfer address. Note that this field is present only if the module contains a program section that contains the transfer address.

TRANSFER ADDRESS	Name: EOM$L_TRFADR
	Length: 4 bytes

This field contains the location of the transfer address. This location is expressed as an offset from the base of this module's contribution to the program section that contains the transfer address. Note that this field is present only if the module contains a program section that contains the transfer address.

TRANSFER FLAGS	Name: EOM$L_TFRFLG
	Length: 1 byte

This field is a 1-byte bit mask that contains information about the transfer address. When bit 0 is set (EOM$V_WKTFR = 1), a weak transfer address is indicated; when clear (EOM$V_WKTFR = 0), a strong transfer address is indicated. If bit 0 is set and a transfer address has already been defined, no error results. Bits 1 to 7 are reserved and must contain zeros. Note that this field may be present only if the module contains a program section that contains the transfer address, and even then it is optional.

A.6 End-of-Module-with-Word-Psect Record

The end-of-module-with-word-psect record is identical in format to the end-of-module record (OBJ$C_EOM), with the following exceptions:

• The field names in the EOMW record begin with EOMW instead of EOM as in the end-of-module record. For example, in the EOMW record, the RECORD TYPE field has the name EOMW$B_RECTYP.
• The PSECT INDEX field for the EOMW record is 2 bytes long instead of 1 byte as in the EOM record.

The purpose of debugger information records is to allow the language processors to pass compilation information, such as descriptions of local variables, to the debugger. The transmission of this information may make use of all the functions (commands) available in the TIR command set.

The command stream in DBG records generates a debugger symbol table (DST). The DST immediately follows the binary of the user image, and the image header contains a descriptor of where in the file such data is written. The production of the DST in memory makes use of a separate location counter within the linker. This location counter is initialized as if the DST is the highest addressed part of the program region of the image. Note, however, the DST is not mapped into the user image.

The linker produces a DST only if the /DEBUG qualifier is specified at link time.

A.8 Traceback Information Records

Traceback information records are the means by which language processors pass information to the facility that produces a traceback of the call stack. From the point of view of the linker and its processing of these records, they are identical to DBG records. That is, they may be mixed with DBG records, and all data generated goes into the DST as if they are DBG records.

The purpose of separating the information contained in DBG records is to allow inclusion of a DST containing only traceback data when no debugging is requested at link time. If the production of traceback information is disabled at link time, then these records are ignored.

A.9 Link Option Specification Records

The link option specification records are defined to allow the language processor to provide the linker with additional input files to be searched for symbol resolution at link time.

As a result, the file specifications in the link option records must be correct at link time. Also, because the files in the LNK records are encountered during the first pass of the linking operation, no related name defaulting can be performed for file specifications.

The linker can, however, apply default file types if none are present in the file specifications in the LNK records:

OBJ	Indicates object files
OLB	Indicates object libraries and shareable image libraries
EXE	Indicates shareable images

The first field in a LNK record is the record type LNK$B_RECTYP, whose value is OBJ$C_LNK. The next field describes the LNK subrecord type, LNK$B_LNKTYP.

The next table lists each LNK subrecord type, its symbolic representation, and its numeric code value.

LNK Subrecord	Symbol	Code
Object library file specification	LNK$C_OLB	0
Shareable image library file specification	LNK$C_SHR	1
Object library with inclusion list	LNK$C_OLI	2
Object file or symbol table file	LNK$C_OBJ	3
Shareable image file	LNK$C_SHA	4

FLAGS	Name: LNK$W_FLAGS
	Length: 2 bytes

This field follows the subrecord type and is a word-length bit field. Currently, only the two flag bits described in the next table are used with LNK$W_FLAGS.

Bit	Name	Meaning if Set
0	LNK$V_SELSER	Selectively searches object module or symbol table. This bit is valid only for LNK$C_OBJ subrecords.
1	LNK$V_LIBSRCH	After module inclusion, searches this library for resolution of currently undefined symbols. The need for this bit arises out of an ambiguity between the usage of the two record types LNK$C_OLI and LNK$C_OLB. The use of this bit is best illustrated by the /LIBRARY and /INCLUDE file qualifiers. Note that an input file specification such as A/INCLUDE=(B,C) corresponds to a LNK$C_OLI type, and an input file specification such as A/LIB corresponds to a LNK$C_OLB type. However, an input file such as A/LIB/INCLUDE=(B,C) is indicated by a linker options record type of LNK$C_OLI with the LNK$V_LIBSRCH bit set. This bit is valid only for LNK$C_OLI subrecords.

FILE NAME LENGTH	Name: LNK$W_NAMLNG
	Length: 2 bytes

This field is one word in length and is the length of the file name string. For LNK$C_OLI subrecord types, this length does not include the length of the list of modules to be included.

FILE NAME	Name: LNK$T_NAME
	Length: LNK$W_NAMLNG

This field is the file specification of the file to be included.

Note that for all subrecord types except LNK$C_OLI, this is the end of the LNK record. For LNK$C_OLI records, the modules to be included are described as a series of ASCII counted strings and appear immediately after the file name LNK$T_NAME. The end of the module inclusion list is indicated by 1 byte of zero.

This appendix defines Structure Level 2 of the Alpha object language. The object language describes the contents of object modules to the OpenVMS Linker utility (the linker), as well as to the OpenVMS Librarian utility. All language processors that produce code for execution in native mode are free to use any or all of the object language components.

This information is useful primarily to programmers writing compilers or assemblers that must generate object modules acceptable for input to the linker. These programmers may also find the description of the ANALYZE/OBJECT command in the OpenVMS DCL Dictionary useful. ANALYZE/OBJECT will parse the object module and perform limited integrity checking on the object.

This appendix contains seven sections. The first section provides an overview of the object language and lists the main types of records. Each subsequent section discusses a main record and its subrecords, as well as the context in which it must be used.

The symbols used in this section are available to BLISS-32 programmers in STARLET.REQ and STARLET.L32. These files also contain definitions for the VAX object language defined in Appendix A. For C programmers, these symbols are defined in EOBJRECDEF.H on Alpha systems and in OBJRECDEF.H on VAX systems.

B.1 Object Language Overview

Each object module (or compiler-generated symbol table file) specified as input to the linker must be in the format described in this appendix. The object language defines an object module as an ordered set of variable-length records. Note that for VAX object language, the record length can be determined only by the value returned by OpenVMS RMS on each read operation, but that for Alpha object language, the total length of the record is recorded in the size field (EOBJ$W_SIZE). Table B-1 shows the main record types currently available.

Table B-1 Object Record Types

Record Type	Symbol	Value
Header (HDR)	EOBJ$C_EMH	8
End-of-module (EOM)	EOBJ$C_EEOM	9
Global symbol directory (GSD)	EOBJ$C_EGSD	10
Text information and relocation (TIR)	EOBJ$C_ETIR	11
Debugger information (DBG)	EOBJ$C_EDBG	12
Traceback information (TBT)	EOBJ$C_ETBT	13
Reserved to Digital		All others

The term reserved indicates that the value must not be used in the EOBJ$W_RECTYP field because it is reserved for possible future use by Digital. The linker will issue a warning if it encounters an illegal value.

All six legal record types do not have to appear in a single object module. However, each object module must contain the following:

• One (and only one) main module header record (EOBJ$C_EMH, subtype EMH$C_MHD) appearing first in the object module (see Section B.2.1)
• One (and only one) language name header record (EOBJ$C_EMH, subtype EMH$C_LNM) appearing second in the object module (see Section B.2.2)
• At least one global symbol directory record (EOBJ$C_EGSD)
• One end-of-module (EOBJ$C_EEOM) record at the end of the object module

An object module may contain any number of global symbol directory (EOBJ$C_EGSD), text information and relocation (EOBJ$C_ETIR), debugger (EOBJ$C_EDBG), or traceback (EOBJ$C_ETBT) records as long as they are not first or last in the object module. An object file may contain any number of object modules, delimited by header and end-of-module records. Figure B-1 depicts the correct ordering of records within an object module.

Figure B-1 Order of Records in an Object Module

If a field is currently ignored by the linker, you must still allocate space for it, filling it with zeros to its entire specified length. Some structures require padding at the end with zeros in order to achieve quadword alignment.

Object records may contain the names of program sections, object modules, language processors, utilities, and so on. Most records implement names as counted strings (1-byte name length field followed by the indicated number of ASCII characters). Others, such as the EOBJ$C_EMH subrecord EOBJ$C_LNM, place the name at the end of the record and use the record's size field to extrapolate the size of the name.

Table B-2 shows the relationships between structure definitions. Each column in the table lists a structure prefix in bold letters. The meaning of the prefix is listed in Table B-3. The values in the column below the prefix represent the key on which a substructure is based. The next column in that row is another structure prefix in bold letters. For example, a simple global symbol definition record is described with four structures. The EOBJ$ structure defines the main record. The EGSD$ structure defines the envelope around the subrecords, of which the EGSY$ and ESDF$ structures define the particulars of the symbol definition.

Table B-2 Relationships of Structures in the Alpha Object Language

EOBJ$
EOBJ$C_EMH	EMH$
EOBJ$C_EEOM	EEOM$
EOBJ$C_EGSD	EGSD$
	EGSD$C_PSC	EGPS$
	EGSD$C_SYM	EGSY$
		EGSY$V_DEF=1	ESDF$
		EGSY$V_DEF=0	ESRF$
	EGSD$C_IDC	EIDC$
	EGSD$C_SPSC 1	ESGPS$
	EGSD$C_SYMV 1	ESDFV$
	EGSD$C_SYMM 1	ESDFM$
	EGSD$C_SYMG 1	EGST$
EOBJ$C_ETIR	ETIR$
EOBJ$C_EDBG	EDBG$
EOBJ$C_ETBT	ETBT$

Table B-3 Key to Structure Prefixes

EOBJ$	Object Record Defines the type and size fields of a variable-length record, and the object record types.
EMH$	Module Header Record Defines the module header record and its subrecord types.
EEOM$	End Of Module Record Defines the end-of-module record.
EGSD$	Global Symbol Directory Record Defines a global symbol directory record and its subrecord types.
EGPS$	Psect Definition Defines the GSD subrecord for a psect definition.
EGSY$	Symbol Definition or Reference Defines the common fields in a GSD subrecord for a symbol definition or reference.
ESDF$	Symbol Definition Defines the fields in the GSD subrecord for a symbol definition that follows the common fields defined by EGSY$.
ESRF$	Symbol Reference Defines the fields in the GSD subrecord for a symbol reference that follows the common fields defined by EGSY$.
EIDC$	Entity Identity Check Defines the GSD subrecord for an entity ident consistency check.
ESGPS$ 1	Shareable Psect Definition Defines the GSD subrecord for a shareable image psect definition.
ESDFV$ 1	Vectored Symbol Definition Defines the GSD subrecord for a vectored symbol.
ESDFM$ 1	Masked Symbol Definition Defines the GSD subrecord for a masked symbol.
EGST$ 1	Universal Symbol Definition Defines a GSD subrecord for a universal symbol definition.
ETIR$	Text Information and Relocation Record Defines a text information and relocation command.
EDBG$	Debugger Record Defines a record used to build a debugger symbol table. Contains TIR subrecords defined by ETIR$.
ETBT$	Traceback Record Defines a record used to build a debugger symbol table for use with the traceback facility. Contains TIR subrecords defined by ETIR$.

The following sections contain descriptions and diagrams of the Alpha object language records and subrecords.

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

4548PRO_020.HTML