Document revision date: 19 July 1999

When this qualifier is appended to an input file specification, the linker processes only those symbols in the input file that have been referenced by previously processed input files.

Format

input-file-name/SELECTIVE_SEARCH

Qualifier Values

input-file-name

The input file you want included in the link operation. The /SELECTIVE_SEARCH qualifier works with object modules and shareable images only. This qualifier is illegal with library files. (To process the modules in a library selectively, you specify the /SELECTIVE qualifier when inserting the files into the library. For more information, see the OpenVMS Command Definition, Librarian, and Message Utilities Manual.)

Description

If you do not specify the /SELECTIVE_SEARCH qualifier with an input file, the linker includes all the input file's global symbols in the global symbol table of the image it is creating by default.

Note that the /SELECTIVE_SEARCH qualifier does not affect the size of the resultant image. The entire object module is included in the image, even if only a subset of the symbols in its global symbol table are needed to resolve symbolic references. Specifying the /SELECTIVE_SEARCH qualifier can improve the performance of a link operation and conserve the linker's use of virtual memory.

Examples

$ LINK/MAP MY_MAIN,MY_PROG/SELECTIVE_SEARCH
      

In this example, the linker processes the object module MY_PROG.OBJ selectively. You can verify this processing by checking the list of symbols in the image map file created in this link. The only symbols from the file MY_PROG.OBJ that will appear in the map file are those symbols that were referenced by MY_MAIN.OBJ.

$ LINK/MAP=MY_MAIN/EXE=MY_MAIN SYS$INPUT/OPT 
CLUSTER=MY_MAIN_CLUS,,,MY_MAIN 
MY_SHARE/SHARE/SELECTIVE_SEARCH 
[Ctrl/Z]
      

In this example, the linker processes the shareable image MY_SHARE.EXE selectively. Note that, to ensure that the linker processes references to symbols in the shareable image before it processes the shareable image selectively, the input file MY_MAIN.OBJ is placed in a named cluster (MY_MAIN_CLUS), using the CLUSTER= option. If the object modules had been specified on the LINK command line, the linker would have put it in the default cluster. The linker processes named clusters before it processes the default cluster.

$ LIBRARIAN/INSERT/SELECTIVE MY_LIB MY_PROG
$ LINK MY_PROG,MY_LIB/LIBRARY
      

In this example, the object module MY_PROG.OBJ is inserted into the library MY_LIB.OLB selectively. When the library is specified in a link operation, the linker processes the object module selectively. This link operation is equivalent to the link operation in example 1.

When specified anywhere on the LINK command line, the /SHAREABLE qualifier directs the linker to create a shareable image. When the /SHAREABLE qualifier is appended to a file specification in a linker options file, it identifies the input file as a shareable image.

Format

/SHAREABLE[=file-spec]

shareable-image-file-name/SHAREABLE

Qualifier Values

file-spec

When the /SHAREABLE qualifier is used to create a shareable image, this parameter specifies the name you want the linker to assign to the shareable image being created. If you do not include a file specification, the linker assigns the shareable image the name of the file to which the /SHAREABLE qualifier is appended in the LINK command line. If the /SHAREABLE qualifier is not appended to an input file specification, the linker assigns to the shareable image the name of the first input file specified on the command line using the extension .EXE.

If you designate a file name but omit the file type, the linker assigns the shareable image the file type .EXE.

shareable-image-file-name

Specifies the name of a shareable image. Note that you can use the /SHAREABLE qualifier to identify a shareable image only in a linker options file. It is illegal to include a shareable image in a link operation by specifying it on the LINK command line.

Description

The linker creates executable images by default; you must specify the /SHAREABLE qualifier to create a shareable image. The /SHAREABLE qualifier is incompatible with the /SYSTEM qualifier.

For more information about creating and using shareable images, see Chapter 4.

Examples

$ LINK/SHAREABLE MY_SHARE,UNIVERSALS/OPT
      

This example directs the linker to produce a shareable image named MY_SHARE.EXE. The options file UNIVERSALS.OPT contains declarations of the universal symbols in the shareable image.

$ LINK/SHAREABLE=MY_APP MY_SHARE, UNIVERSALS/OPT
      

This example directs the linker to produce a shareable image named MY_APP.EXE using the object module MY_SHARE.OBJ as input.

$ TYPE MY_OPTIONS.OPT 
MY_SHARE/SHAREABLE
$ LINK MY_PROG,MY_OPTIONS.OPT/OPTION
 
      

In this example, a shareable image is included in a link operation. The shareable image is specified in the options file MY_OPTIONS.OPT, which is specified as an input file on the LINK command line.

$ LINK MY_PROG,SYS$INPUT/OPTION
MY_SHARE/SHAREABLE
[Ctrl/Z]
 
      

This example shows how the shareable image MY_SHARE.EXE is used, together with the object file MY_PROG.OBJ, to create an executable image named MY_PROG.EXE.

Note how you can specify options interactively at the command line by identifying the logical name SYS$INPUT as an options file. The linker interprets the lines following the LINK command as the contents of an options file, until you terminate the options by entering the Ctrl/Z key sequence.

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

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. (See Section 1.2.4 for more information.)

For Alpha linking, you cannot specify symbol table files as input files in a link operation. Symbol table files of Alpha images are intended only as an aid in debugging crash dumps using the OpenVMS Alpha System Dump Analyzer utility (SDA). For more information, see Section 1.2.4.

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.

Examples

$ LINK/SYMBOL_TABLE/NOEXE MY_PROG
 
      

In this example, the linker produces a symbol table file named MY_PROG.STB without producing an executable image.

$ 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.

$ LINK/SHAREABLE/SYMBOL_TABLE MY_SHARE,SYS$INPUT/OPT 
GSMATH=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 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 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 ALPHA$LOADABLE_IMAGES.

Format

/SYSEXE[=[NO]SELECTIVE]

/NOSYSEXE (default)

Qualifier Values

SELECTIVE

When you specify 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 the /SYSEXE qualifier is specified without a keyword, the linker processes the executive image selectively.

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.

Note The linker looks for SYS$BASE_IMAGE.EXE in the directory pointed to by the logical name ALPHA$LOADABLE_IMAGES.

For more information about linking against the OpenVMS executive, see Section 2.4.

Example

$  LINK/SHARE/SYSEXE  MY_SHARE, SYS$INPUT/OPT 
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.

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 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 ALPHA$LIBRARY.

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

$  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.

Format

/SYSSHR (default)

/NOSYSSHR

Qualifier Values

None.

Description

To specify that the linker should skip processing the default system 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

$ 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.

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]

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

$ 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 image header 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 Alpha systems, this keyword sets the MULTIPLE_KERNEL_THREADS bit in the image header 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 image header of the image being built. This bit indicates to the image activator that the process can receive upcalls from the OpenVMS

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 Alpha can place threads on separate central processing units for concurrent execution; this enables a process to run faster.

The new image header bits allow you to control your threads environment on a per-process basis rather than systemwide. The image activator examines the new bits in the image header 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 DECthreads.

Examples

$ LINK /NOTHREADS_ENABLE
      

This command, which is the default, keeps the MULTIPLE_KERNEL_THREADS and UPCALLS bits clear in the image header of an image being built.

$ LINK /THREADS_ENABLE
      

The result of this command is different on Alpha and VAX systems:

• On Alpha systems, this command sets the UPCALLS and MULTIPLE_KERNEL_THREADS bits in the image header of an image being built.
• On VAX systems, the command sets only the UPCALLS bit in the image header of an image being built.

$ LINK /THREADS_ENABLE=UPCALLS
      

This command sets the UPCALLS bit in the image header of both the OpenVMS Alpha and VAX images being built.

$ LINK /THREADS_ENABLE=MULTIPLE_KERNEL_THREADS
      

The result of this command is different on Alpha and VAX systems:

• On Alpha systems, the command sets the MULTIPLE_KERNEL_THREADS bit in the image header of an image being built.
• On VAX systems, the qualifier and keyword are ignored.

$ LINK /THREADS_ENABLE=(MULTIPLE_KERNEL_THREADS,UPCALLS)
      

The result of this command is different on Alpha and VAX systems:

• On Alpha systems, the command sets the UPCALLS and MULTIPLE_KERNEL_THREADS bits in the image header of an image being built.
• On VAX systems, the command sets only the UPCALLS bit in an image being built.

	privacy and legal statement
4548PRO_013.HTML