Updated: 11 December 1998

OpenVMS Linker Utility Manual

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 /NOTRACEBACK qualifier if it is specified.

Format

/TRACEBACK (default)

/NOTRACEBACK

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.

Note that the traceback handler can display traceback information only from the main executable image, not from any shareable images.

Example

$ LINK/NOTRACEBACK 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.

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:

1. 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).
2. 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).
3. 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.
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.
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.

Directs the linker to produce an OpenVMS VAX image. The default action, when neither /ALPHA nor /VAX is specified, is to create an OpenVMS VAX image on an OpenVMS VAX system and to create an OpenVMS Alpha image on an OpenVMS Alpha system.

Format

/VAX

Qualifier Values

None.

Description

This qualifier is used to instruct the linker to accept OpenVMS VAX object files and library files to produce an OpenVMS VAX image.

You must inform the linker where OpenVMS VAX system libraries and shareable images are located. On an OpenVMS VAX system, you use the logical name SYS$LIBRARY to do this. On an OpenVMS Alpha system, you use the logical name VAX$LIBRARY to do this. Therefore, if the link is to occur on an OpenVMS Alpha system, you must define the logical VAX$LIBRARY so that it translates to the location of an OpenVMS VAX system disk residing on the system where the VAX linking is to occur.

For more information on cross-architecture linking, see Section 1.6.

Example

$ DEFINE VAX$LIBRARY DKB200:[VMS$COMMON.SYSLIB]
$ LINK/VAX VAX.OBJ
      

This example, performed on an OpenVMS Alpha system, shows the definition of the logical name VAX$LIBRARY to point to an OpenVMS VAX system disk mounted on device DKB200 in the appropriate area. The qualifier tells the linker to expect the object file, VAX.OBJ, to be an OpenVMS VAX object file and to link it using the OpenVMS VAX libraries and images on DKB200, if necessary.

This section describes the linker options that you may specify in a linker options file. For information about creating and using linker options files, see Chapter 1.

You can express numeric parameters in decimal (%D), hexadecimal (%X), or octal (%O) radix by prefixing the number with the corresponding radix operator. If no radix operator is specified, the linker assumes decimal radix.

The default and maximum numeric values in this manual are expressed in decimal numbers, as are the values in any linker messages relating to these options.

Options	Defaults
BASE=	See description. (VAX linking only)
CASE_SENSITIVE=YES/NO	NO
CLUSTER=	See description.
COLLECT=	None
GSMATCH=	See description.
IDENTIFICATION=	See description.
IOSEGMENT=	0,[NO]P0BUFS
ISD_MAX=	Approximately 96
NAME=	Name of the output image file
PROTECT=YES/NO	NO
PSECT_ATTR=	None
RMS_RELATED_CONTEXT=	YES
STACK=	20 pagelets
SYMBOL=	None
SYMBOL_TABLE=GLOBALS/UNIVERSALS	SYMBOL_TABLE=UNIVERSALS (Alpha linking only)
SYMBOL_VECTOR=	None (Alpha linking only)
UNIVERSAL=	None (VAX linking only)

BASE= (VAX Only)

For VAX linking, specifies the base address (starting address) that you want the linker to assign to the image.

Format

BASE=address

Option Values

address

The address at which you want the image based. You can express the number in decimal (%D), octal (%O), or hexadecimal (%X) notation. If the address specified is not divisible by 512, the linker automatically adjusts it upward to the next multiple of 512, that is, to the next highest page boundary. Do not attempt to base an image linked with a larger page size (specified using the /BPAGE qualifier).

The linker bases shareable images at address 0, by default, and bases system images at address %X80000000, by default.

Description

The BASE= option is illegal in a link operation that produces a system image. To specify a base address for a system image, use the /SYSTEM qualifier.

The BASE= option is not supported for Alpha linking. Note, however, that you can set the base address for an executable image by specifying the address as a parameter to the CLUSTER= option. You cannot create a based shareable Alpha image.

In general, the use of the BASE= option to create based images is not recommended. The memory management component of the OpenVMS operating system cannot relocate a based shareable image in the virtual address space, which could result in possible fragmentation of the virtual address space.

The linker processes the BASE= option by assigning the specified base address to the default cluster. If the linker creates additional clusters before it searches the default libraries, which it does if a CLUSTER= or COLLECT= option is specified or if a shareable image is explicitly specified, the following effects may occur:

• If the additional clusters are based (that is, if the CLUSTER= option specifies a base address or if the shareable image is a based shareable image), the linker must check that memory requirements for each based cluster do not conflict. Memory requirements conflict when more than one cluster requires the same section of address space. If they do conflict, the linker issues an error message and aborts the linking operation. If they do not conflict, the linker allocates each cluster the memory space it requests.

• If the additional clusters are not based, there will be no conflicting memory requirements. However, the linker will place each additional cluster at an address higher than that of the default cluster (because the base address of the default cluster must be the base address of the entire image). Consequently, the location of clusters (relative to each other) in the image will differ from what you would expect based on the position of each cluster in the cluster list. (Remember that the additional clusters precede the default cluster on the cluster list and that the linker typically allocates memory for clusters beginning at the first cluster on the cluster list, then the second, and so on.) For more information about the linker's clustering algorithm, see Chapter 2. For more information about the linker's memory allocation algorithm, see Chapter 3.

Directs the linker to preserve the mixture of uppercase and lowercase characters used in character string arguments to linker options.

Format

CASE_SENSITIVE=YES/NO

Option Values

YES

Enables case sensitivity. You can use any mixture of uppercase and lowercase characters when specifying the keyword YES.

NO

Disables case sensitivity. Note that you must use only uppercase characters when specifying the keyword NO because case sensitivity is enabled and the linker does not accept mixed case in keywords.

Description

Once case sensitivity has been enabled, the linker preserves the case of all succeeding character string arguments to linker options until you explicitly disable it. When the CASE_SENSITIVE= option is disabled (which is the default), the linker changes all the characters in a character string to uppercase before processing the string.

Note that the CASE_SENSITIVE= option only affects how the linker processes arguments to linker options. When it searches object files and shareable image files for symbols that need to be resolved, the linker preserves the case used in the symbol names (created by the language compilers). Also, the names of the linker options (all the characters preceding the equal sign, as in the NAME= option) are unaffected by the case-sensitivity option. The linker changes all the characters in option names to uppercase characters before processing the option, even if case sensitivity has been enabled.

Carefully delimit the section of a linker options file in which you use case sensitivity to avoid unintentional side effects. For example, if you include options in the case sensitive region that accept keyword arguments, such as YES, NO, EXE, and SHR, make sure the keywords are specified using uppercase characters. Because these keywords appear after the equal sign, they are affected by case sensitivity. Similarly, character string arguments used to name a program section, cluster, or image are also affected by case sensitivity.

Example

$ link/share/map/full test, sys$input:/opt 
case_sensitive=YES 
name=ImageName 
symbol=OneSymbol,1 
case_sensitive=NO 
universal=myroutine 
[Ctrl/Z]
 
      

In the example, the CASE_SENSITIVE= option with the value YES enables case sensitivity in the linker options file. Because case sensitivity has been enabled, the linker preserves the mix of uppercase and lowercase characters used in character string arguments to all succeeding linker options. In the example, this includes the character string ImageName passed to the NAME= option and the character string OneSymbol passed to the SYMBOL= option.

Specifying the CASE_SENSITIVE= option with the value NO turns off case sensitivity. Note that you must use uppercase characters when specifying the keyword NO. Because case sensitivity has been disabled, the linker changes all the characters in the universal symbol myroutine to uppercase. The following excerpt from the map file produced by this link illustrates how these identifiers were stored by the linker:

ImageName OneSymbol MYROUTINE

Directs the linker to create a cluster. (The linker groups input files into clusters before processing their contents.)

Format

CLUSTER=cluster-name,[base-address],[pfc],[file-spec,...]

Option Values

cluster-name

The name you want assigned to the cluster.

base-address

The base virtual address for the cluster. If you omit the base-address value, you must still enter the comma.

For Alpha linking, it is illegal to specify a base address for a cluster when creating a shareable image.

pfc (page fault cluster)

The number of pagelets read into memory by the operating system when the initial page fault occurs for a page in the cluster. If you do not specify the pfc parameter, the operating system uses the default value established by the system parameter PFCDEFAULT. If you omit the page fault cluster value, you must still enter the comma.

file-spec,...

The file you want the linker to place in the cluster. Note that you should not specify in the LINK command itself any file that you specify with the CLUSTER= option (unless you want to include two copies of the file in the final image).

Description

You can use the CLUSTER= option in the following ways:

• To control the order in which the linker processes input files
• To cause specified modules to be placed close together in virtual memory

If you do not specify the CLUSTER= option, the linker always creates at least one cluster, called the default cluster. For more information about how the linker creates clusters, see Chapter 2.

You can also create a cluster by specifying the COLLECT= option

Example

$  LINK MY_PROG,SYS$INPUT/OPT 
CLUSTER=MY_CLUSTER,,,PROG2,PROG3
 
      

In this example, the linker creates a cluster, named MY_CLUSTER, that contains the input files named PROG2.OBJ and PROG3.OBJ.

Directs the linker to place the specified program section (or program sections) into the specified cluster.

Format

COLLECT=cluster-name[/ATTRIBUTES=[RESIDENT|INITIALIZATION_CODE] ,psect-name[,...]

Option Values

cluster-name

Name of the cluster.

psect-name[,...]

Name of the program sections (psects) you want placed in the cluster.

Qualifier

/ATTRIBUTES

For Alpha linking, directs the linker to mark the cluster 'cluster-name' with the indicated qualifier keyword value. This qualifier is used to build Alpha drivers. See Writing OpenVMS Alpha Device Drivers in C for guidelines for using this qualifier.

Qualifier Values

• RESIDENT
  Marks the cluster 'cluster-name' as RESIDENT so that the image section created from that cluster has the EISD$V_RESIDENT flag set. This will cause the loader to map the image section into non-paged memory.
  
• INITIALIZATION_CODE
  Marks the cluster 'cluster-name' as INITIALIZATION_CODE so that the image section created from that cluster has the EISD$V_INITALCOD flag set. The initialization code will be executed by the loader. This keyword is specifically intended for use with program sections from modules SYS$DOINIT and SYS$DRIVER_INIT in STARLET.OLB.

Description

If the specified cluster does not already exist, the linker creates the cluster when it processes the COLLECT= option.

The linker sets the global (GBL) attribute for all the program sections specified, if they do not already have this attribute set. Program sections from a shareable image referenced in the options file with the /SHARE qualifier cannot be specified in the COLLECT= option.

Example

$  LINK MY_PROG,SYS$INPUT/OPT 
COLLECT=MY_CLUSTER,PSECT2,PSECT3 
[Ctrl/Z]
 
      

In the example, the linker creates the cluster named MY_CLUSTER, if it does not already exist, and puts the program sections named PSECT2 and PSECT3 in the cluster.

Specifies the minimum number of contiguous, uninitialized pages that the linker must find in an image section before it can extract the pages from the image section and place them in a newly created demand-zero image section. By creating demand-zero image sections (image sections that do not contain initialized data), the linker can reduce the size of images.

Format

DZRO_MIN=number-of-pages

Option Values

number-of-pages

Specifies the minimum number of contiguous pages.

For VAX linking, the linker, by default, uses a minimum of 5 pages. Each VAX page equals 512 bytes.

For Alpha linking, the linker, by default, uses a minimum of 1 page. The size of an Alpha page is CPU-specific. The initial set of Alpha systems uses an 8 KB page. The page size used is that of the current link operation. (See the /BPAGE qualifier.)

The number of pages must be equal to or greater than the value specified in the parameter.

Description

A demand-zero image section contains uninitialized, writable pages, which do not occupy physical space in the image file on disk, but which, when accessed during program execution, are allocated memory and initialized with binary zeros by the operating system. (For more information about demand-zero compression, see Chapter 3.)

When specifying a value for this option, be aware that a low value (less than the default value) increases the likelihood that the linker will encounter the required number of contiguous, uninitialized pages and thus may increase the number of demand-zero image sections the linker creates for the image (depending on the contents of the object modules). While this can reduce the size of the image file on disk, it can also decrease the image's paging performance during execution. Conversely, a value higher than the default value decreases the likelihood that the linker will encounter the required number of contiguous, uninitialized pages; decreases the number of demand-zero image sections the linker creates; and may increase the size of the image file on disk but provide better paging performance during execution.

The linker stops creating demand-zero image sections when the total number of image sections in the image reaches the value specified by the ISD_MAX= option or the default value. (For more information, see the description of the ISD_MAX= option.)

The DZRO_MIN= option is illegal in a link operation that produces a system image.

Example

$  LINK MY_PROG,SYS$INPUT/OPT 
DZRO_MIN=15 
[Ctrl/Z]
      

In this example, the value of the DZRO_MIN= is set to 15.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4548PRO_014.HTML