HP OpenVMS Systems Documentation

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.

The record type is OBJ$C_EOM.

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.

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.

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.

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:

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.

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.

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.

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.

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 Compaq. 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 the following records:

• global symbol directory (EOBJ$C_EGSD) records
• text information and relocation (EOBJ$C_ETIR) records
• debugger (EOBJ$C_EDBG) records
• traceback (EOBJ$C_ETBT) records

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.

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