HP OpenVMS Systems Documentation

For Alpha linking, declares universal symbols in shareable images.

Format

SYMBOL_VECTOR=([alias-name/]symbol-name=symbol-vector-entry-type)

Option Values

alias-name

Optionally specifies an alias name for the symbol you want to declare universal. When specified, the alias name appears in the GST of the image and values associated with the name specified in the symbol-name parameter appear in the symbol vector of the image. Note that you can specify alias names only for symbol vector entries declared using the DATA or PROCEDURE keywords. For more information about symbol vector entry types, see the following table.

symbol-name

Specifies the name of the symbol in the shareable image that you want to declare universal.

symbol-vector-entry-type

Specifies the type of the symbol vector entry. The following table lists the types of symbol vector entries supported by the linker along with the keyword you use to specify them:

Keyword	Function
1DATA	Creates a symbol vector entry for data (relocatable or constant). The linker creates an entry for the symbol in the GST of the shareable image.
1PROCEDURE	Creates a symbol vector entry for a procedure and creates an entry for the symbol in the GST of the shareable image.
PRIVATE_DATA	Creates a symbol vector entry for data; however, the linker does not create an entry for the data in the GST of the shareable image. Thus, the symbol is not available for other modules to link against.
PRIVATE_PROCEDURE	Creates a symbol vector entry for a procedure; however, the linker does not create an entry for the procedure in the GST of the shareable image. Thus, the symbol is not available for other modules to link against.
PSECT	Creates a symbol vector entry for a program section and creates an entry for the symbol in the GST of the shareable image.
SPARE	Use this keyword to create a placeholder when you delete an entry in an existing symbol vector. SPARE allows you to preserve the order of symbol vector entries when you need to create an upwardly compatible shareable image. The SPARE keyword is used alone; it is not preceded by a symbol name and equal sign.

Description

The linker creates an entry in the global symbol table (GST) of a shareable image for each symbol listed in the SYMBOL_VECTOR= option, unless the symbol is declared private, the /NOGST qualifier is specified, or the symbol is the internal name for an alias. Symbols that appear in the GST of a shareable image are available for external modules to link against. For more information about creating and using shareable Alpha images, see Chapter 4.

Example

$  LINK/SHARE MY_SHARE,SYS$INPUT/OPT
GSMATCH=lequal,1,1000
SYMBOL_VECTOR=(my_proc=PROCEDURE,-
               my_proc2=PROCEDURE,-
               SPARE,-
               my_data=DATA,-
               my_data_psect=PSECT,-
               report_err=PRIVATE_PROCEDURE)
[Ctrl/Z]
      

This example creates a symbol vector with entries for procedures, data, and program section.

For VAX linking, declares a symbol in a shareable image as universal, causing the linker to include it in the global symbol table of a shareable image.

Format

UNIVERSAL= symbol-name[,...]

Option Values

symbol-name[,...]

The name of the symbol or symbols you want to declare universal.

Description

This option may be specified only in the creation of a shareable image.

For more information about declaring universal symbols, refer to Chapter 4.

Example

$  LINK/SHARE MY_SHARE,SYS$INPUT/OPT
UNIVERSAL=MY_SYMBOL
[Ctrl/Z]
      

In this example, the linker includes the universal symbol MY_SYMBOL in the global symbol table of the shareable image MY_SHARE.EXE.

This appendix describes the VAX object language according to Compaq software specifications. The object language described is for use with all VAX family software; no subsetting will occur.

The VAX object language describes the contents of object modules to the OpenVMS Linker, as well as to the object module librarian. All language processors that produce code for execution in native mode are free to use any or all of the described object language.

This information is useful primarily to programmers writing compilers or assemblers that must generate object modules acceptable for input to the OpenVMS Linker. These programmers may also find the description of the ANALYZE/OBJECT command in the OpenVMS DCL Dictionary useful because it explains how the DCL command ANALYZE/OBJECT may be used to check whether an object module conforms to the requirements of the VAX object language.

This appendix contains nine 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 including its subrecords and fields.

The $OBJDEF macro, which defines all symbols used in this section, is available to programmers in VAX MACRO and VAX BLISS-32. VAX MACRO programmers will find this macro in the STARLET.MLB object library; VAX BLISS-32 programmers will find it in the STARLET.REQ require file.

A.1 Object Language Overview

Each object module specified as input to the linker must be in the format described by the object language. Thus, object files, object library files, and all symbol table files (which the linker creates) will conform to the format described by the object language.

The object language defines an object module as an ordered set of variable-length records. The following table shows the main record types currently available. Column 1 displays the name of the record, followed by its abbreviation. Column 2 displays the name of the record in symbolic notation; this name is placed in the first byte of the record to identify the record type. Column 3 displays the numerical code corresponding to the name in Column 2; this code may be substituted for the symbolic name in the first byte of the record, though this is not recommended.

Reserved indicates that the item must not be present because it is reserved for possible future use by the linker and Compaq. The linker produces an error if a reserved item is found in an object module.

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

• One (and only one) main-module-header (MHD) record appearing first in the object module (see Section A.2.1)
• One (and only one) language-name-header (LNM) record appearing second in the object module (see Section A.2.2)
• At least one global-symbol-directory (GSD) record
• Either one end-of-module (EOM) record or one end-of-module-with-word-psect (EOMW) record, but not both, appearing last in the object module

An object module may contain any number of GSD, TIR, DBG, and TBT records, in any order, as long as they are not first or last in the object module. Figure A-1 depicts the correct ordering of records within an object module.

Figure A-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.

Records in the object language may contain the names of program sections, object modules, language processors, utilities, and so on. Two methods of specifying names are implemented in the VAX object language:

• The standard naming method, which uses two fields of the record. The first field is the 1-byte name length field containing the length in characters of the name. The second field is the name field containing the name in ASCII notation.
• The single field naming method, which uses a single field containing the name in ASCII notation. The name is not preceded by a 1-byte name length field.

All name strings except the names specified in header records may be up to 31 characters long.

The following sections contain diagrams of the VAX records and subrecords. Each record or subrecord contains several fields. The left-hand column of a diagram gives, for each field, its name, symbolic representation, and length in bytes. The right-hand column gives the value (which may be a symbolic name), where appropriate, and a description of the field.

Note that many records contain identical fields; if the right-hand column of a diagram does not give a description of a field, that field has already been described in a previous record.

Also note that corresponding numerical codes for record types, subrecord types (in HDR and GSD records), and TIR commands are defined and are given in this section. Though these may be substituted for the symbolic name of the record or subrecord in the appropriate field, this practice is not recommended.

A.2 Header Records

The object language currently provides for the definition of six types of header records. Of the remaining possible types, types 7 to 100 are reserved for use by Compaq, and types 101 to 255 are ignored.

The following table lists the various types of header records. Column 1 lists the name of the header type, followed by its abbreviation. Column 2 lists the related symbolic representations and column 3 lists the corresponding numerical codes.

The content and format of the MHD and LNM header types, both of which are required in each object module, are described in the following subsections.

Though currently ignored by the linker, the header types SRC, TTL, CPR, MTC, and GTX exist to allow the language processors to provide printable information within the object module for documentation purposes. The format of the SRC, TTL, CPR, MTC, and GTX records consists of a record type field, header type field, and a field containing the ASCII text.

The content and format of the SRC and TTL records are depicted in Section A.2.3 and Section A.2.4. The contents of these records, as well as the MTC record (which contains information about the maintenance status of the object module), are displayed in an object module analysis. (See the description of the ANALYZE/OBJECT command in the OpenVMS DCL Dictionary.)

A.2.1 Main Module Header Record (MHD$C_MHD)

The following presents the name, symbolic representation, and length of each field in the main module header record. The listing includes a symbolic value or an explanation of the contents of the field, where appropriate.

The record type is OBJ$C_HDR.

The header type is MHD$C_MHD.

The structure level is OBJ$C_STRLVL. Because the format of the MHD record never changes, the structure level field is provided so that changes in the format of other records can be made without recompiling every module that conformed to the previous format.

The maximum record size is OBJ$C_MAXRECSIZ, which is limited to 2048 bytes. This field contains the size in bytes of the longest record that can occur in the object module.

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

This field contains the module name in ASCII format.

This field contains the module version number in standard name format.

This field contains the module creation time and date in the fixed format dd-mmm-yyyy hh:mm, where dd is the day of the month, mmm is the standard 3-character abbreviation of the month, yyyy is the year, hh is the hour (00 to 23), and mm is the minutes of the hour (00 to 59). Note that a space is required after the year and that the total character count for this time format is 17 characters (including hyphens (-), the space, and the colon (:)).

This field is currently ignored by the linker and should be padded with 17 zeros.

A.2.2 Language Processor Name Header Record (MHD$C_LNM)

The following presents the name, symbolic representation, and length of each field in the language processor name header record. The listing includes a symbolic value or an explanation of the contents of the field, where appropriate.

The record type is OBJ$C_HDR.

The header type is MHD$C_LNM.

This field, which is generated by the language processor, contains the name and version of the source language that the language processor translates into the object language. It consists of a variable-length string of ASCII characters and is not preceded by a byte count of the string.

A.2.3 Source Files Header Record (MHD$C_SRC)

The following presents the name, symbolic representation, and length of each field in the source files header record. The listing includes a symbolic value or an explanation of the contents of the field, where appropriate. The contents of this record, though ignored by the linker, are displayed in an object module analysis. (See the description of the ANALYZE/OBJECT command in the OpenVMS DCL Dictionary.)

The record type is OBJ$C_HDR.

The header type is MHD$C_SRC.

This field, which is generated by the language processor, contains the list of file specifications from which the object module was created. It consists of a variable-length string of ASCII characters and is not preceded by a byte count of the string.

A.2.4 Title Text Header Record (MHD$C_TTL)

The following presents the name, symbolic representation, and length of each field in the title text header record. The listing includes a symbolic value or an explanation of the contents of the field, where appropriate. The contents of this record, though ignored by the linker, are displayed in an object module analysis. (See the description of the ANALYZE/OBJECT command in the OpenVMS DCL Dictionary.)

The record type is OBJ$C_HDR.

The header type is MHD$C_TTL.

This field, which is generated by the language processor, contains a brief description of the object module. It consists of a variable-length string of ASCII characters and is not preceded by a byte count of the string.

A.3 Global Symbol Directory Records

GSD records contain information that the linker uses to build the global symbol table and the program section table. Using this information, the linker allocates virtual address space and combines program sections into image sections.

At least one GSD record must appear in an object module.

The first field in a GSD record is the record type GSD$B_RECTYP, whose value is OBJ$C_GSD. Subsequent fields describe one or more GSD subrecords, each of which begins with the GSD type field GSD$B_GSDTYP.

Table A-1 lists each type of GSD subrecord together with its symbolic representation and its corresponding numerical code.

Again, a single GSD record may contain one or more of the above types of subrecords. Figure A-2 displays the general format of a GSD record that contains multiple subrecords. Column 1 displays the field names; column 2 displays possible values for those fields. Note that the RECORD TYPE field appears only once at the beginning. Each subrecord begins with the GSD TYPE field.

Figure A-2 GSD Record with Multiple Subrecords

The following subsections describe the format and content of each GSD subrecord. For each subrecord, the name, length, value, and description of each field are given, where appropriate.

Note that the RECORD TYPE field is not listed with the GSD subrecords. Remember that this field must always appear first in the GSD record and that it appears only once, regardless of how many GSD subrecords are included in the GSD record.