HP OpenVMS Systems Documentation
OpenVMS Programming Concepts Manual
25.6.2 Inserting Table Information
After initializing the format data for the symbol tables, the linker enters data into the cross-reference tables by calling LIB$CRF_INS_KEY.
As the linker processes the first object module, MAPINITIAL, it encounters a symbol definition for $MAPFLG. The following is an example of a call to enter the symbol MAPINITIAL as a key in the cross-reference symbol table:
The linker then calls LIB$CRF_INS_REF to process the defining reference indicator:
Further on in the input module, the linker encounters a global symbol reference to CS$GBL. The call to store data for this reference is as follows:
The arguments are similar to the previous example, except for CRF$K_REF, which indicates that this is not the defining reference.
After it has performed symbol relocation for the module being linked, the linker calls LIB$CRF_INS_REF to build a table ordered by value.
25.6.3 Formatting Information for Output
After all input modules are processed, the linker requests the information for the map. It calls LIB$CRF_OUTPUT once for each type of output. The following MACRO example illustrates a call to list the symbols and their values. Three calls are illustrated here.
In this example, CRF$K_VALUES means that no reference indicators are to be printed, while CRF$K_SAVE means that the cross-reference table is to be saved. It is also possible to list all cross-reference data. The type of output produced by this call is shown in Section 25.5, Figure 25-2.
The following call produces such a summary and releases the storage at the same time:
CRF$K_DEFS_REFS indicates that the first two reference fields are used for the defining references, and CRF$K_DELETE indicates that the table is deleted.
Another call is made to list the symbol by value synopsis, as follows:
This is similar to the previous call in that it produces a complete
cross-reference output by value, but it does not have the defining
The cross-reference routines are located in a shareable image CRFSHR.EXE. This shareable image is part of the default system shareable image library, SYS$LIBRARY:IMAGELIB.OLB. For this reason, the cross-reference routines are automatically included in your image, unless you specify /NOSYSHR in the LINK command. If you have specified /NOSYSHR and you want to include CRFSHR.EXE, your LINK command must include the following:
$ DEFINE LNK$LIBRARY $DISK1:[DEV]PROCEDURES
When the linker is resolving global symbol references, it searches user
default libraries at the process level first, then libraries at the
group and system level. Within levels, the library defined as
LNK$LIBRARY is searched first, then LNK$LIBRARY_1, LNK$LIBRARY_2, and
18.104.22.168 Creating an Object Library
To create an object library, invoke the Librarian utility by entering the LIBRARY command with the /CREATE qualifier and the name you are assigning the library. The following example creates a library in a file named INCOME.OLB (.OLB is the default file type):
$ LIBRARY/CREATE INCOME
To add or replace modules in a library, enter the LIBRARY command with the /REPLACE qualifier followed by the name of the library (first parameter) and the names of the files containing the (second parameter). After you put object modules in a library, you can delete the object file. The following example adds or replaces the modules from the object file named GETSTATS.OBJ to the object library named INCOME.OLB and then deletes the object file:
$ LIBRARY/REPLACE INCOME GETSTATS $ DELETE GETSTATS.OBJ;*
You can examine the contents of an object library with the /LIST qualifier. Use the /ONLY qualifier to limit the display. The following command displays all the modules in INCOME.OLB that start with GET:
$ LIBRARY/LIST/ONLY=GET* INCOME
Use the /DELETE qualifier to delete a library module and the /EXTRACT
qualifier to recreate an object file. If you delete many modules, you
should also compress (/COMPRESS qualifier) and purge (PURGE command)
the library. Note that the /ONLY, /DELETE, and /EXTRACT qualifiers
require the names of modules---not file names---and that the names are
specified as qualifier values, not parameter values.
26.1.2 Text and Macro Libraries
Source code modules are stored in text libraries. The file extension for a text library is .TLB.
When using VAX MACRO assembly language, any source code module can be stored in a macro library. The file extension for a macro library is .MLB. Any source code module stored in a macro library must have the file extension .MAR.
A shareable image is a nonexecutable image that can be linked with executable images. If you have a program unit that is invoked by more than one program, linking it as a shareable image provides the following benefits:
Shareable images can also save memory, provided that they are installed
as shared images. See the OpenVMS Linker Utility Manual for more information about
creating shareable images and shareable image libraries.
Symbols are names that represent locations (addresses) in virtual
memory. More precisely, a symbol's value is the address of the first,
or low-order, byte of a defined area of virtual memory, while the
characteristics of the defined area provide the number of bytes
referred to. For example, if you define TOTAL_HOUSES as an integer, the
symbol TOTAL_HOUSES is assigned the address of the low-order byte of a
4-byte area in virtual memory. Some system components (for example, the
debugger) permit you to refer to areas of virtual memory by their
actual addresses, but symbolic references are always recommended.
26.3.1 Defining Symbols
A symbolic name can consist of up to 31 letters, digits, underscores
(_), and dollar signs ($). Uppercase and lowercase letters are
equivalent. By convention, dollar signs are restricted to symbols used
in system components. (If you do not use the dollar sign in your
symbolic names, you will never accidentally duplicate a system-defined
26.3.2 Local and Global Symbols
Symbols are either local or global in scope. A local symbol can only be referenced within the program unit in which it is defined. Local symbol names must be unique among all other local symbols within the program unit but not within other program units in the program. References to local symbols are resolved at compile time.
A global symbol can be referenced outside the program unit in which it is defined. Global symbol names must be unique among all other global symbols within the program. References to global symbols are not resolved until link time.
References to global symbols in the executable portion of a program unit are usually invocations of subprograms. If you reference a global symbol in any other capacity (as an argument or data value---see the following paragraph), you must define the symbol as external or intrinsic in the definition portion of the program unit.
System facilities, such as the Message utility and the VAX MACRO assembler, use global symbols to define data values.
The following program segment shows how to define and reference a global symbol, RMS$_EOF (a condition code that may be returned by LIB$GET_INPUT):
CHARACTER*255 NEW_TEXT INTEGER STATUS INTEGER*2 NT_SIZ INTEGER LIB$GET_INPUT EXTERNAL RMS$_EOF STATUS = LIB$GET_INPUT (NEW_TEXT, 2 'New text: ', 2 NT_SIZ) IF ((.NOT. STATUS) .AND. 2 (STATUS .NE. %LOC (RMS$_EOF))) THEN CALL LIB$SIGNAL (RETURN_STATUS BY VALUE) END IF
References to global symbols are resolved by including the module that defines the symbol in the link operation. When the linker encounters a global symbol, it uses the following search method to find the defining module:
If the linker cannot find the symbol, the symbol is said to be unresolved and a warning results. You can run an image containing unresolved symbols. The image runs successfully as long as it does not access any unresolved symbol. For example, if your code calls a subroutine but the subroutine call is not executed, the image runs successfully.
If an image accesses an unresolved global symbol, results are
unpredictable. Usually the image fails with an access violation
(attempting to access a physical memory location outside those assigned
to the program's virtual memory addresses).
22.214.171.124 Explicitly Named Modules and Libraries
You can resolve a global symbol reference by naming the defining object module in the link command. For example, if the program unit INCOME references the subprogram GET_STATS, you can resolve the global symbol reference when you link INCOME by including the file containing the object module for GET_STATS, as follows:
$ LINK INCOME, GETSTATS
If the modules that define the symbols are in an object library, name the library in the link operation. In the following example, the GET_STATS module resides in the object module library INCOME.OLB:
$ LINK INCOME,INCOME/LIBRARY
Link operations automatically check the system object and shareable
image libraries for any references to global symbols not resolved by
your explicitly named object modules and libraries. The system object
and shareable image libraries include the entry points for the RTL
routines and system services, condition codes, and other system-defined
values. Invocations of these modules do not require any explicit action
by you at link time.
126.96.36.199 User Default Libraries
If you write general-purpose procedures or define general-purpose
symbols, you can place them in a user default library. (You can also
make your development library a user default library.) In this way, you
can link to the modules containing these procedures and symbols without
explicitly naming the library in the DCL LINK command. To name a
single-user library, equate the file name of the library to the logical
name LNK$LIBRARY. For subsequent default libraries, use the logical
names LNK$LIBRARY_1 through LNK$LIBRARY_999, as described in
188.8.131.52 Making a Library Available for Systemwide Use
To make a library available to everyone using the system, define it at the system level. To restrict use of a library or to override a system library, define the library at the process or group level. The following command line defines the default user library at the system level:
$ DEFINE/SYSTEM LNK$LIBRARY $DISK1:[DEV]PROCEDURES
Some system symbols are not defined in the system object and shareable image libraries. In such cases, the OpenVMS System Services Reference Manual notes that the symbols are defined in the system macro library and tells you the name of the macro containing the symbols. To access these symbols, you must first assemble a macro routine with the following source code. The keyword GLOBAL must be in uppercase. The .TITLE directive is optional but recommended.
.TITLE macro-name macro-name GLOBAL . . . .END
The following example is a macro program that includes two system macros:
.TITLE $LBRDEF $LBRDEF GLOBAL $LHIDEF GLOBAL .END
Assemble the routine containing the macros with the MACRO command. You can place the resultant object modules in a default library or in a library that you specify in the LINK command, or you can specify the object modules in the LINK command. The following example places the $LBRDEF and $LHIDEF modules in a library before performing a link operation:
$ MACRO LBRDEF $ LIBRARY/REPLACE INCOME LBRDEF $ DELETE LBRDEF.OBJ;* $ LINK INCOME,INCOME/LIBRARY
The following LINK command uses the object file directly:
$ LINK INCOME,LBRDEF,INCOME/LIBRARY