HP OpenVMS Systems Documentation

HP OpenVMS Linker Utility Manual

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, image 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.5.

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

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 I64 and Alpha linking. On I64, you cannot create any based image. On Alpha, however, you can create a based executable image but you cannot create a based shareable image.

On Alpha, you can set the base address for an executable image by specifying the base address argument to the CLUSTER=cluster-name,base-address option. On I64, the base address argument must be omitted in a CLUSTER= option.

In general, the use of based images is not recommended. The image activator, a component of the OpenVMS operating system, cannot relocate a based image in the virtual address space, which can result in conflicts in the address space: when two or more based images overlap. It can also result in fragmentation of the used 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 6. For more information about the linker's memory allocation algorithm, see Chapter 7.

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

CASE_SENSITIVE=NO (default)

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.

Symbol names issued by compilers are uppercased by default. But you can use compiler switches to preserve mixed-case source code names. Be aware that this may result in mixed-case module or program section names as well. For example, if you have a library include statement and the module names in the library are mixed-case, then set CASE_SENSITIVE=YES . to operate on mixed-case names in the options file,

The following excerpt from an options file illustrates how the linker changes or preserves the syntactical elements of an option line. The example contains mixed-case names that you want to preserve by setting the linker to case-sensitive mode:

case=Yes My_Lib/library/include=(Add_Func, Sub_Func) symbol_vector=(Add_Func=PROCEDURE,PAGE_COUNT=DATA) case=NO

When processed by the linker, the text appears as follows:

CASE=YES MY_LIB/LIBRARY/INCLUDE=(Add_Func,Sub_Func) SYMBOL_VECTOR=(Add_Func=PROCEDURE,PAGE_COUNT=DATA) CASE=NO

The case of all names to the right of the first equal sign in each option remains the same.

Note HP recommends that you switch to case sensitivity only when needed.

Example

$ LINK/SHAREABLE/MAP/FULL TEST,SYS$INPUT/OPTIONS
CASE_SENSITIVE=YES
NAME=ImageName
SYMBOL=OneSymbol,1
CASE_SENSITIVE=NO
SYMBOL_VECTOR=(myroutine=PROCEDURE)
[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.

On I64 systems, the base address must be omitted.

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 (I64) and Chapter 6 (Alpha and VAX).

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

Example

$  LINK MY_PROG,SYS$INPUT/OPTIONS 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 I64 and Alpha linking, directs the linker to mark the cluster 'cluster-name' with the indicated qualifier keyword value. Attributes set by this qualifier are only evaluated by the loader. This qualifier is used to build OpenVMS 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 segment (I64) or image section (Alpha) created from that cluster has the RESIDENT flag set. This will cause the loader to map the segment or image section into non-paged memory.

INITIALIZATION_CODE
Marks the cluster 'cluster-name' as INITIALIZATION_CODE so that the segment (I64) or image section (Alpha) created from that cluster has the 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 exported from a shareable image referenced in the options file with the /SHAREABLE qualifier cannot be specified in the COLLECT= option.

Example

$  LINK MY_PROG,SYS$INPUT/OPTIONS
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.

On Alpha and VAX systems, 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 on Alpha and VAX, see Chapter 7.)

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/OPTIONS
DZRO_MIN=15
[Ctrl/Z]
      

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

Sets match control parameters for a shareable image and specifies the match algorithm. This option allows you to control whether executable images that link with a shareable image must be relinked each time the shareable image is updated and relinked.

Format

GSMATCH=keyword,major-id,minor-id

GSMATCH=EQUAL,link-time-derived-major-id,link-time-derived-minor-id (default)

Option Values

keyword

Identifies the match algorithm used by the image activator. Specify one of the following keywords:

Keyword	Meaning
EQUAL	Directs the image activator to allow the image to map to the referenced shareable image when one condition is met: the major and minor ID for the shareable image, as saved at link time in the image file, are equal to the IDs found in the actual shareable image file at activation time.
LEQUAL	Directs the image activator to allow the image to map to the referenced shareable image when two conditions are met: the major ID for the shareable image, as saved at link time in the image file, is equal to the major ID found in the actual shareable image file at activation time the minor ID for the shareable image, as saved at link time in the image file, is less than or equal to the minor ID found in the actual shareable image file at activation time.
ALWAYS	Directs the image activator to unconditionally allow the image to map to the referenced shareable image: regardless of the values of the major and minor ID for the shareable image, as saved at link time in the image file, and the values of the IDs found in the actual shareable image file at activation time. Note that you must still specify values for the major ID and minor ID parameters to satisfy the requirements of the option syntax.

major-id

Specifies the major identification number.

minor-id

Specifies the minor identification number.

When a shareable image is created without specifying a GSMATCH= option, the linker by default creates one. It sets the EQUAL match control and uses portions of the image creation time, as a binary value, for the major and minor IDs. In general this is sufficient to set a unique value for the IDs each time the shareable image is linked. On I64, the linker uses bits 40 through 54 of the binary time value for the major ID and bits 8 through 39 for the minor ID. On Alpha and VAX, the linker uses bits 32 through 46 of the binary time value for the major ID and bits 16 through 31 for the minor ID.

Description

The GSMATCH= option causes a major identification parameter (major-id), a minor identification parameter (minor-id), and a match control keyword to be stored in the shareable image file. The control keyword together with the IDs is called the GSMATCH information.

When an image is linked with a shareable image, together with the reference to the shareable image its GSMATCH information is saved in the image file.

When the image is run, the image activator encounters the reference to the shareable image. At this time, the image activator compares the GSMATCH information as saved in the image with the GSMATCH information retrieved from the actual shareable image. The implementation details on I64 and Alpha are slightly different, the mechanism and its effects are the same.

The following information describes the GSMATCH mechanism for an executable image linked against a shareable image. "Executable" is used to clearly differentiate between the referencing image and the referenced image, the shareable image. However, in general any image, executable or shareable, can be linked against a shareable image and the described mechanism applies.

• On I64, the GSMATCH= option causes a major identification parameter (major-id), a minor identification parameter (minor-id), and a match control keyword to be stored in the dynamic segment of the shareable image. It is the DT_VMS_IDENT field which holds this information.
  When an executable image is linked with a shareable image, the dynamic segment of the executable image contains the name of the shareable image. This information is saved in the field DT_NEEDED. The name is accompanied by the GSMATCH information of the shareable image, taken at link time. This information is saved in the field DT_VMS_NEEDED_IDENT.
  When the executable image is run and the image activator begins processing the dynamic segment of the executable image, the image activator encounters the name of the shareable image. At that time, the image activator looks up the shareable image file based on this name, either as a logical name, pointing to a file, or as a filename in the directory SYS$LIBRARY. If an image file was found, the image activator continues to process the GSMATCH information.
• On Alpha and VAX, the GSMATCH= option causes a major identification parameter (major-id), a minor identification parameter (minor-id), and a match control keyword to be stored in the image header of the shareable image.
  When an executable image is linked with a shareable image, the image header of the executable image contains an image section descriptor (ISD) for the shareable image (as well as an ISD for each image section in the image). The ISD for the shareable image contains a major ID, minor ID, and match control keyword, which the linker copies from the shareable image at link time.
  When the executable image is run and the image activator begins processing the ISDs in the image header of the executable image, the image activator encounters the ISD for the shareable image. As such, the image activator looks up the shareable image file based on its name, either as a logical name, pointing to a file, or as a filename in the directory SYS$LIBRARY. If an image file was found, the image activator compares the image section name in the ISD to the image section name in the image header of the current shareable image file. If the image section names do not match, the image activator does not allow the executable image to map to the shareable image, regardless of the GSMATCH parameters. If the image section names match, the image activator continues to process the GSMATCH information.
• To process the GSMATCH information, the image activator compares the major ID parameters. If they do not match, the image activator does not allow the executable image to map to the shareable image unless GSMATCH=ALWAYS has been specified.
  If the major ID parameters match, the image activator compares the minor ID parameters. If the relation between the minor ID parameters does not satisfy the relation specified by the match control keyword, the image activator does not allow the executable image to map to the shareable image. Then the image activator issues an error message stating that the executable image must be relinked.
  The match control keyword must be the same in both the shareable and executable image files. If it is different, then the more restrictive match is used. For example, if a shareable image is linked with ALWAYS, and an executable image contains EQUAL (from an earlier version of the shareable image), then the test at activation time will be EQUAL.
  Thus, to create an upwardly compatible shareable image, increment only the value of the minor ID and leave unchanged the value of the major ID. If the match control keyword is LEQUAL, the executable image that links against it will run. (If the major ID is changed, executable images can never map to the shareable image unless ALWAYS is specified.) By using this convention, you can ensure that executable images that linked with an older version of the shareable image can map to the newer version.

---

Previous

Next

Contents

Index