 |
HP OpenVMS Linker Utility Manual
/SYMBOL_TABLE
Directs the linker to create a symbol table file.
Format
/SYMBOL_TABLE[=file-spec]
/NOSYMBOL_TABLE (default)
Qualifier Values
file-spec
Specifies the character string you want the linker to use as the name
of the symbol table file. If you do not include a file type in the
character string, the linker appends the .STB file type to the file
name.
If you specify the /SYMBOL_TABLE qualifier without the file
specification, the linker creates a symbol table file with the file
name of the first input file and the default file type .STB. If you
append the /SYMBOL_TABLE qualifier to one of the input file
specifications, the linker creates a symbol table file with the file
name of the file to which the qualifier is appended, with the default
file type .STB.
Description
A symbol table file contains a copy of the image's global symbol table,
excluding definitions from shareable images, in object module format.
For I64 and Alpha linking, you cannot specify symbol table files as
input files in a link operation. Symbol table files of images are
intended only as an aid in debugging crash dumps using the OpenVMS
System Dump Analyzer utility (SDA). For more information, see
Section 1.2.4.
For I64 and Alpha linking, note that you can direct the linker to
include global symbols in a symbol table file associated with a
shareable image by specifying the SYMBOL_TABLE=GLOBALS option. When you
specify this option, the linker includes global symbols as well as
universal symbols in a symbol table file by default.
For VAX linking, a global symbol table produced by a link that creates
a shareable image contains only universal symbols. A global symbol
table produced by a link that creates an executable image contains all
the global symbols in the image.
For VAX linking, you can specify symbol table files as input files in
link operations if they were produced in an operation in which an
executable or system image was created. Symbol table files produced in
a link operation in which a shareable image was created do not always
contain enough information to be used as input files in link
operations. (For more information, see Section 1.2.4.)
Examples
| #1 |
$ LINK/SYMBOL_TABLE/NOEXECUTABLE MY_PROG
|
In this example, the linker produces a symbol table file named
MY_PROG.STB without producing an executable image.
| #2 |
$ LINK/SYMBOL_TABLE=MY_PROG_SYMB_TAB MY_PROG
|
In this example, the linker produces a symbol table file named
MY_PROG_SYMB_TAB.STB. An executable image file named MY_PROG.EXE is
also produced.
| #3 |
$ LINK/SHAREABLE/SYMBOL_TABLE MY_SHARE,SYS$INPUT/OPTIONS
GSMATCH=LEQUAL,1,1000
SYMBOL_VECTOR=(MYPROC=PROCEDURE, -
MYDATA=DATA, -
MYPROC2=PROCEDURE)
SYMBOL_TABLE=GLOBALS
[Ctrl/Z]
|
In this example, the linker creates a symbol table file on an I64 and
Alpha system, named MY_SHARE.STB, that contains both global symbols and
universal symbols because the linker option SYMBOL_TABLE=GLOBALS is
specified in the options file.
/SYSEXE (I64 and Alpha)
For I64 and Alpha linking, directs the linker to process the system
shareable image, SYS$BASE_IMAGE.EXE, in a link operation. The linker
looks for SYS$BASE_IMAGE.EXE in the directory pointed to by the logical
name IA64$LOADABLE_IMAGES (I64) and ALPHA$LOADABLE_IMAGES (Alpha).
Format
/SYSEXE[=[NO]SELECTIVE]
/NOSYSEXE (default)
Qualifier Values
SELECTIVE (default)
When the /SYSEXE qualifier is specified with no keyword, the linker
processes the SYS$BASE_IMAGE.EXE file selectively.
When you specify /SYSEXE with the SELECTIVE keyword, the linker
processes the SYS$BASE_IMAGE.EXE file selectively, including only those
symbols from the global symbol table of the SYS$BASE_IMAGE.EXE file
that were referenced by input files previously processed in the link
operation.
NOSELECTIVE
When you specify the NOSELECTIVE keyword, the linker includes all the
symbols from the SYS$BASE_IMAGE.EXE global symbol table in the link
operation.
Description
When you specify the /SYSEXE qualifier, the linker processes the
SYS$BASE_IMAGE.EXE file selectively after processing the
system shareable image library, IMAGELIB.OLB, and before
processing the system object library, STARLET.OLB, and the system
service shareable image, SYS$PUBLIC_VECTORS.EXE, which is associated
with STARLET.OLB. (By default, the linker processes IMAGELIB.OLB,
STARLET.OLB, and SYS$PUBLIC_VECTORS.EXE, in that order, to resolve
symbols that remain undefined after all the files specified in the LINK
command have been processed and after any user-specified libraries have
been processed.) Note that the linker qualifiers that determine whether
the linker processes the default system libraries, /SYSSHR and /SYSLIB,
do not affect SYS$BASE_IMAGE.EXE processing.
If you want the linker to process SYS$BASE_IMAGE.EXE before processing
IMAGELIB.OLB, specify SYS$BASE_IMAGE.EXE in an options file, as you
would any other shareable image. If you specify SYS$BASE_IMAGE.EXE in
your options file, do not specify the /SYSEXE qualifier in the LINK
command.
For more information about linking against the OpenVMS executive, see
Section 2.4 (I64) and Section 6.4 (Alpha).
Example
|
$ LINK/SHAREABLE/SYSEXE MY_SHARE, SYS$INPUT/OPTIONS
SYMBOL_VECTOR=(MY_PROC=PROCEDURE)
[Ctrl/Z]
|
In this example, the linker processes the OpenVMS system executive
file, SYS$BASE_IMAGE.EXE, to create a shareable image named
MY_SHARE.EXE.
/SYSLIB
Directs the linker to process the default system shareable image
library, IMAGELIB.OLB, and the default system object module library,
STARLET.OLB, to resolve symbolic references that remain undefined after
all specified input files and any default user libraries have been
processed.
Format
/SYSLIB (default)
/NOSYSLIB
Qualifier Values
None.
Description
The linker first searches IMAGELIB.OLB, the default system shareable
image library, then STARLET.OLB, the default system object library.
For I64 and Alpha linking, the linker also searches the shareable image
SYS$PUBLIC_VECTORS.EXE to resolve references to system services. (For
more information about processing SYS$PUBLIC_VECTORS.EXE, see the
description of the /SYSEXE qualifier.) The linker looks for these
default libraries in the directory pointed to by the logical name
IA64$LIBRARY (I64) or ALPHA$LIBRARY (Alpha).
For VAX linking, the linker looks for these default libraries in the
directory that the logical name SYS$LIBRARY points to.
If you specify the /NOSYSLIB qualifier and the /SYSSHR qualifier, the
/SYSSHR qualifier is ignored.
If you want the linker to search IMAGELIB.OLB but not STARLET.OLB,
specify the /NOSYSLIB qualifier (to inhibit the default search of both
default system libraries), and then specify IMAGELIB.OLB in the LINK
command line or in an options file.
Example
In this example, the linker creates the executable image MY_PROG.EXE
without referencing the default system libraries IMAGELIB.OLB or
STARLET.OLB.
/SYSSHR
Directs the linker to process the default system shareable image
library (IMAGELIB.OLB) to resolve symbolic references that remain
undefined after all specified input files and any default user
libraries have been processed.
Format
/SYSSHR (default)
/NOSYSSHR
Qualifier Values
None.
Description
The linker searches IMAGELIB.OLB, the default system shareable image
library, and resolves symbolic references that remain undefined after
all specified input files and any default user libraries have been
processed.
If you want the linker to skip processing the default shareable image
library, IMAGELIB.OLB, but still process the default system object
library, STARLET.OLB, specify the /NOSYSSHR qualifier.
See the description of the /SYSLIB qualifier for information about
controlling how the linker processes the default system libraries.
Example
In this example, the linker processes the default system object library
(STARLET.OLB), but does not process the default system shareable image
library (IMAGELIB.OLB), to resolve symbolic references while producing
an executable image named MY_PROG.EXE.
/SYSTEM (Alpha and VAX)
On Alpha and VAX systems, directs the linker to create a system image
and optionally allows you to specify the address at which the image
should be loaded into memory. A system image cannot be activated with
the RUN command; it must be bootstrapped or otherwise loaded into
memory.
Format
/SYSTEM[=base-address]
/NOSYSTEM (default)
Qualifier Values
base-address
Specifies the address at which the image is to be loaded in virtual
memory. You can specify a base address in hexadecimal (%X), octal (%O),
or decimal (%D) format. The default base address is %X80000000.
Note that if you specify the /HEADER qualifier, the linker adjusts the
base address to the next highest page boundary if it is not already a
page boundary. The next highest page boundary is the smallest number
that is greater than the value specified in the
base-address parameter and that is divisible by the
default page size (which is architecture specific) or the page size
specified using the /BPAGE qualifier.
Description
System images are intended for special purposes, such as standalone
operating system diagnostics. When the linker creates a system image,
it orders the program sections in alphanumeric order and ignores all
program section attributes.
The linker creates the system image with the file name of the first
input file and the file type .EXE. If you want a different output file
specification, specify that file specification with the /EXECUTABLE
qualifier.
If you specify the /SYSTEM qualifier, you cannot specify the /SHAREABLE
qualifier or the /DEBUG qualifier.
Example
This example directs the linker to produce a system image named
MY_SYS.EXE based at address %X80000000.
/THREADS_ENABLE
Kernel threads allow a multithreaded application to have a thread
executing on every CPU in a multiprocessor system. The /THREADS_ENABLE
qualifier allows you to turn kernel threads on and off on a per-image
basis.
When you specify this qualifier, the OpenVMS linker sets the
appropriate bits in the dynamic segment (I64) or the image header
(Alpha and VAX) of the image being linked. These bits control the
following:
- Whether the image is allowed to enter a multiple kernel threads
environment
- Whether the image can receive upcalls from the OpenVMS scheduler
Format
/THREADS_ENABLE[=(MULTIPLE_KERNEL_THREADS,UPCALLS)]
/NOTHREADS_ENABLE (default)
Qualifier Values
MULTIPLE_KERNEL_THREADS
On I64 and Alpha systems, this keyword sets the MULTIPLE_KERNEL_THREADS
bit in the dynamic segment (I64) or the image header (Alpha) of the
image being built. This bit indicates to the image activator that the
image can be run in a multiple kernel threads environment.
If you specify this keyword for OpenVMS VAX links, it is ignored.
UPCALLS
This qualifier sets the UPCALLS bit in the OpenVMS dynamic segment
(I64) or image header (Alpha and VAX) of the image being built. This
bit indicates to the image activator that the process can receive
upcalls from the OpenVMS scheduler.
When the /THREADS_ENABLE qualifier is specified without either the
MULTIPLE_KERNEL_THREADS or UPCALLS keyword, the linker sets both bits
by default.
Description
The principal benefit of threading is to allow you to launch multiple
paths of execution within a process. With threading, you can have some
threads running while others are waiting for an external event to
occur, such as I/O. The multi-threading kernel of OpenVMS can place
threads on separate central processing units for concurrent execution;
this enables a process to run faster.
The set bits allow you to control your threads environment on a
per-process basis rather than systemwide. The image activator examines
these bits to determine the environment in which the image is to run.
Caution
The OpenVMS linker does no analysis whatsoever to determine if the
image can be safely placed in a multiple kernel threads environment.
The linker only sets the bits.
|
For more information on kernel threads, see the Guide to the POSIX Threads Library.
Examples
| #1 |
$ LINK /NOTHREADS_ENABLE
|
This command, which is the default, keeps the MULTIPLE_KERNEL_THREADS
and UPCALLS bits clear in the image being built.
| #2 |
$ LINK /THREADS_ENABLE
|
For this command, the result on I64 and Alpha systems is different from
the result on VAX systems:
- On I64 and Alpha systems, this command sets the UPCALLS and
MULTIPLE_KERNEL_THREADS bits in the image being built.
- On VAX systems, the command sets only the UPCALLS bit in the image
being built.
| #3 |
$ LINK /THREADS_ENABLE=UPCALLS
|
This command sets the UPCALLS bit in the OpenVMS I64, Alpha, and VAX
images being built.
| #4 |
$ LINK /THREADS_ENABLE=MULTIPLE_KERNEL_THREADS
|
For this command, the result on I64 and Alpha systems is different from
the result on VAX systems:
- On I64 and Alpha systems, the command sets the
MULTIPLE_KERNEL_THREADS bit in the image being built.
- On VAX systems, the qualifier and keyword are ignored.
| #5 |
$ LINK /THREADS_ENABLE=(MULTIPLE_KERNEL_THREADS,UPCALLS)
|
For this command, the result on I64 and Alpha systems is different from
the result on VAX systems:
- On I64 and Alpha systems, the command sets the UPCALLS and
MULTIPLE_KERNEL_THREADS bits in the image being built.
- On VAX systems, the command sets only the UPCALLS bit in an image
being built.
/TRACE
Directs the linker to include traceback information in the image file.
If you specify the /DEBUG qualifier, the linker includes traceback
information by default, overriding the /NOTRACE qualifier if it is
specified.
Format
/TRACE (default)
/NOTRACE
Qualifier Values
None.
Description
Traceback is a facility that displays information from the call stack
when a program error occurs. The output shows which modules were called
before the error occurred.
For more information on the effects of using /TRACE combined with
/DEBUG and /DSF, see /DEBUG.
Example
In this example, the linker does not include traceback information in
the executable image named MY_PROG.EXE.
/USERLIBRARY
Directs the linker to process one or more default user libraries to
resolve symbolic references that remain undefined after all specified
input files have been processed.
Format
/USERLIBRARY[=(table[,...])]
/NOUSERLIBRARY
/USERLIBRARY=ALL (default)
Qualifier Values
table
Specifies the logical name tables that the linker searches for default
user libraries. The following keywords are the only acceptable
parameter values:
| Keyword |
Description |
|
ALL
|
Directs the linker to search the process, group, and system logical
name tables for default user library definitions. This is the default.
|
|
GROUP
|
Directs the linker to search the group logical name table for default
user library definitions.
|
|
NONE
|
Directs the linker not to search any logical name table; the
/USERLIBRARY=NONE qualifier is equivalent to the /NOUSERLIBRARY
qualifier.
|
|
PROCESS
|
Directs the linker to search the process logical name table for default
user library definitions.
|
|
SYSTEM
|
Directs the linker to search the system logical name table for default
user library definitions.
|
Description
A default user library may be an object module library or a shareable
image library.
To define a default user library, you must use the DCL command DEFINE
or ASSIGN to equate the logical name LNK$LIBRARY to the file
specification of the library, because the linker looks for this logical
name to determine if a default user library exists.
Further, to control access to the library, you can define LNK$LIBRARY
in the process, group, or system logical name tables by using the
/PROCESS qualifier, the /GROUP qualifier, and the /SYSTEM qualifier,
respectively, in the DEFINE command.
For example, if you want the library MY_LIB to be your default user
library, the library GROUP_LIB to be the default user library of
everyone else in your group, and the library ANY_LIB to be the default
user library of everyone else on the system, you would issue the
following commands:
$ DEFINE LNK$LIBRARY DB2:[MARK]MY_LIB
$ DEFINE/GROUP LNK$LIBRARY DB2:[PROJECT]GROUP_LIB
$ DEFINE/SYSTEM LNK$LIBRARY SYS$LIBRARY:ANY_LIB
|
Note that the GRPNAM and SYSNAM privileges are required to use the
/GROUP qualifier and the /SYSTEM qualifier, respectively.
If you are defining more than one library in a single logical name
table, use the logical names LNK$LIBRARY for the first library,
LNK$LIBRARY_1 for the second library, LNK$LIBRARY_2 for the third, and
so on, up to the last possible logical name of LNK$LIBRARY_999.
However, you must specify these logical names in numeric order without
skipping any, because when the linker does not find the next sequential
logical name, it stops searching in that logical name table.
The search of default user libraries proceeds as follows:
- If you specify the /USERLIBRARY=PROCESS qualifier or the
/USERLIBRARY qualifier, the linker searches the process logical name
table for the name LNK$LIBRARY. If this entry exists, the linker
translates the logical name and searches the specified library for
unresolved strong references. If you exclude PROCESS from the table
list in the /USERLIBRARY qualifier or if no entry exists for
LNK$LIBRARY, the linker proceeds to step 4 (searching the group logical
name table).
- If any unresolved strong references remain, the linker searches the
process logical name table for the name LNK$LIBRARY_1 and follows the
logic of step 1. If no entry exists for LNK$LIBRARY_1, the linker
proceeds to step 4 (searching the group logical name table).
- If any unresolved strong references remain, the linker follows the
logic of step 1 for LNK$LIBRARY_2, LNK$LIBRARY_3, and so on, until it
finds no match in the process logical name table, at which point it
proceeds to step 4.
- If you specify the /USERLIBRARY=GROUP qualifier or the /USERLIBRARY
qualifier, the linker follows the logic in steps 1 through 3 using the
group logical name table. If you exclude GROUP from the table list in
the /USERLIBRARY qualifier or when any logical name translation fails,
the linker proceeds to step 5.
- If you specify the /USERLIBRARY=SYSTEM qualifier or the
/USERLIBRARY qualifier, the linker follows the logic in steps 1 through
3 using the system logical name table. If you exclude SYSTEM from the
table list in the /USERLIBRARY qualifier or when any logical name
translation fails, the search of default user libraries is complete. By
default, the linker proceeds to search the default system libraries if
any unresolved references remain.
Search lists are not recognized in LNK$LIBRARY* logical names. Instead,
use LNK$LIBRARY_nnn with a single library specification.
Example
|
$ LINK/USERLIBRARY=(GROUP) MY_PROG
|
In this example, the linker searches only the group logical name table
to translate the logical names LNK$LIBRARY, LNK$LIBRARY_1,
LNK$LIBRARY_2, and so on.
|
