|
HP OpenVMS Systems Documentation |
|
HP OpenVMS Linker Utility Manual
/SYMBOL_TABLE
Directs the linker to create a symbol table file. Format/SYMBOL_TABLE[=file-spec] Qualifier Values
DescriptionA symbol table file contains a copy of the image's global symbol table, excluding definitions from shareable images, in object module format.
|
| #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.
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).
/SYSEXE[=[NO]SELECTIVE]/NOSYSEXE (default)
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.
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).
$ 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.
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.
/SYSLIB (default)/NOSYSLIB
None.
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.
$ LINK/NOSYSLIB MY_PROG
|
In this example, the linker creates the executable image MY_PROG.EXE without referencing the default system libraries IMAGELIB.OLB or STARLET.OLB.
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.
/SYSSHR (default)/NOSYSSHR
None.
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.
$ LINK/NOSYSSHR MY_PROG
|
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.
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.
/SYSTEM[=base-address]/NOSYSTEM (default)
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.
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.
$ LINK/SYSTEM MY_SYS
|
This example directs the linker to produce a system image named MY_SYS.EXE based at address %X80000000.
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
/THREADS_ENABLE[=(MULTIPLE_KERNEL_THREADS,UPCALLS)]/NOTHREADS_ENABLE (default)
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.
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.
| #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.
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.
/TRACE (default)/NOTRACE
None.
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.
$ LINK/NOTRACE MY_PROG
|
In this example, the linker does not include traceback information in the executable image named MY_PROG.EXE.
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.
/USERLIBRARY[=(table[,...])]/NOUSERLIBRARY
/USERLIBRARY=ALL (default)
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.
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_LIBNote 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.
$ 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.
| Previous | Next | Contents | Index |