[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS Linker Utility Manual


Previous Contents Index

A.5 End-of-Module Record

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:

A.7 Debugger Information Records

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.


Appendix B
Alpha Object Language

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:

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$    


1This record is reserved for use by the linker.

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$.


1This record is reserved for use by the linker.

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


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
4548PRO_020.HTML