Document revision date: 19 July 1999

Sets match control parameters for a shareable image and specifies the match algorithm. This option allows you to specify 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

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 executable image to map to the shareable image when the major ID and minor ID in the image section descriptor (ISD) of the executable image are equal to the IDs in the shareable image file.
LEQUAL	Directs the image activator to allow the executable image to map to the shareable image when the major ID is equal to, and the minor ID in the ISD of the executable image is less than or equal to the minor ID in the shareable image file.
ALWAYS	Directs the image activator to allow the executable image to map to the shareable image, regardless of the values of the major ID and minor ID, providing that the image section names are the same. 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. The linker uses bits 32 through 47 of the image creation time as the default value of the major ID.

minor-id

Specifies the minor identification number. The linker uses bits 16 through 31 of the image creation time as the default value of 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 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. At this time, 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 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.

Examples

$  LINK/SHARE MY_SHARE,SYS$INPUT/OPT 
GSMATCH=LEQUAL,1,1000 
[Ctrl/Z]
      

In this example, the GSMATCH= option sets the major and minor identification numbers for this shareable image.

$  LINK/SHARE MY_SHARE,SYS$INPUT/OPT 
GSMATCH=LEQUAL,1,1001 
[Ctrl/Z]
      

In this example, the shareable image created in the previous example is relinked and the minor identification number is incremented. Note that executable images that link with the new version cannot map to the old version, whereas executable images that link with the old version can map to the new version.

$  LINK/SHARE MY_SHARE,SYS$INPUT/OPT 
GSMATCH=ALWAYS,0,0 
[Ctrl/Z]
      

By specifying the keyword ALWAYS, an executable image can run with any version of the shareable image (newer or older).

Sets the image-id field in the image header.

Format

IDENTIFICATION=id-name

Option Values

id-name

The maximum length of the identification character string is 15 characters. If the string contains characters other than uppercase and lowercase A through Z, the numerals 0 through 9, the dollar sign, and the underscore, enclose it in quotation marks.

Description

The linker uses the value of the ID of the first object module processed as the default image ID when producing any kind of image with an image header. Thereafter, as long as the image-id field is not empty, it is not changed unless the linker encounters an object module that has a transfer address on the end-of-module (EOM) object record. (A transfer address is the main entry point for the image.) When it encounters an object module that contains a transfer address, the linker uses the ID from that object module as the value of the image ID.

Because shareable images normally do not have a main entry point, the image ID usually remains as the ID of the first object module processed.

Example

$  LINK MY_PROG,SYS$INPUT/OPT 
IDENTIFICATION=MY_15_CHAR_NAME 
[Ctrl/Z]
      

Specifies the amount of space to be allocated for the image I/O segment, which holds the buffers and OpenVMS RMS control information for all files used by the image.

Format

IOSEGMENT=number-of-pages[,[NO]P0BUFS]

Option Values

number-of-pages

Specifies the number of pagelets (512-byte units) to be allocated for the image I/O segment. By default, the operating system uses the value set by the IMGIOCNT system parameter to determine the size of the image I/O space.

[NO]P0BUFS

By default, the operating system allocates the I/O segment in the P1 region of the process space and, if additional space is needed, at the end of the P0 region. If you specify NOP0BUFS, you deny OpenVMS RMS additional pages in the P0 region.

Description

Specifying the value of number-of-pages to be greater than the value of IMGIOCNT ensures the contiguity of P1 address space, providing that OpenVMS RMS does not require more pages than the value specified. If OpenVMS RMS requires more pages than the value specified, the pages in the P0 region would be used (by default).

Note that if you specify NOP0BUFS and if OpenVMS RMS requires more pages than have been allocated for it, OpenVMS RMS issues an error message.

Example

$  LINK MY_PROG,SYS$INPUT/OPT 
IOSEGMENT=100,P0BUFS 
[Ctrl/Z]
      

Specifies the maximum number of image sections allowed in the image.

Format

ISD_MAX=number-of-image-sections

Option Values

number-of-image-sections

The maximum number of image sections that may be created. You can specify the value in hexadecimal (%X), decimal (%D), or octal (%O) radix. The default is decimal radix.

Description

This option is used to control the linker's creation of demand-zero image sections by imposing an upward limit on the number of total image sections. Thus, if the linker is creating demand-zero image sections, and if the total number of image sections reaches the ISD_MAX= value, demand-zero image section creation ceases at that point. (For more information about how the linker creates demand-zero image sections, see Section 3.4.3.)

The ISD_MAX= option may be specified only in a link operation that produces an executable image. The ISD_MAX= option is illegal in a link operation that produces either a shareable or a system image.

The default value for ISD_MAX= is approximately 96. Note that any value you specify is also an approximation. The linker determines an exact ISD_MAX= value based on characteristics of the image, including the different combinations of section attributes. The exact value, however, will be equal to or slightly greater than what you specify; it will never be less.

Example

$  LINK MY_PROG,SYS$INPUT/OPT 
ISD_MAX=126 
[Ctrl/Z]
      

Sets the image-name field in the image header.

Format

NAME=image-name

Option Values

image-name

A character string up to 39 characters in length. If the name contains characters other than uppercase and lowercase A through Z, the numerals 0 through 9, the dollar sign, and the underscore, enclose it in quotation marks.

Description

If the NAME= option is not specified, the string specified with /SHARE or /EXE is used for the image-name field. If no string was specified to /SHARE or /EXE, the name of the first module processed is used.

The NAME= option does not affect the name of the image file.

The image-name field is not used by the linker or librarian.

For Alpha linking, the NAME= option also determines the string used in the shareable image list if the image contains a SYMBOL_VECTOR clause with an ALIAS keyword. The use of aliases causes the linker to set up an image with references to itself, including fixups and an entry for itself in the shareable image list.

When the file name is different from the image-name field, the image activator uses the image-name field to identify self-references in the shareable image list. The file name and the image-name field can differ if the image file is renamed, or if they are forced to differ by the NAME= option.

Example

$  LINK MY_PROG,SYS$INPUT/OPT 
NAME=MY_IMAGE 
[Ctrl/Z]
      

Specifies that the image sections in one or more clusters in a shareable image should be protected from user-mode or supervisor-mode write access.

Format

PROTECT=YES/NO

Option Values

YES

Enables protection of all the clusters defined in subsequent lines in the options file by the CLUSTER= option or the COLLECT= option, up to a line containing another PROTECT= option.

NO

Disables protection for all clusters specified on subsequent lines of a linker options file by the CLUSTER= option or the COLLECT= option, up to the line containing another PROTECT=YES option. Protection is disabled by default.

Description

This option is commonly used to protect clusters that contain privileged code or data in shareable images that implement user-written system services (called privileged shareable images). For more information about creating user-written system services, see the OpenVMS Programming Concepts Manual.

Note that the protection applies to the image sections the linker creates from the cluster, not the cluster itself. A cluster is an internal construct the linker uses to organize how it processes input files. The linker communicates the actual memory requirements of an image, including its protection, to the image activator as image section specifications.

If the entire shareable image needs to be protected, specify the /PROTECT qualifier.

Example

$  LINK MY_PROG,SYS$INPUT/OPT 
PROTECT=YES 
CLUSTER=A,,,MOD1,MOD2 
UNIVERSAL=ENTRY 
PROTECT=NO 
CLUSTER=B,,,MOD3 
PROTECT=YES 
COLLECT=B,PSECTX,PSECTY,PSECTZ 
[Ctrl/Z]
      

In this example, the modules MOD1 and MOD2 in cluster A are protected; MOD3 in cluster B is not protected; and program sections PSECTX, PSECTY, and PSECTZ in cluster B are protected. Note that other linker options, such as the UNIVERSAL= option in the example, are not affected.

Specifies the attributes of a program section.

Format

PSECT_ATTR=psect-name,attribute-keyword[,...]

Option Values

psect-name

Specifies the name of the program section whose attributes you want to set. The name may be a character string up to 31 characters in length.

attribute-keyword[,...]

One or more attributes, identified by a keyword, separated by commas. Section 3.2 lists the attributes with the keywords you use to specify them.

Description

Attributes not specified in a PSECT_ATTR= option remain unchanged.

If you specify a program section alignment that is greater than the target page size, the linker issues a warning and adjusts the alignment to be equal to the target page size.

Example

$  LINK MY_PROG,SYS$INPUT/OPT 
PSECT_ATTR=PSECT_1,NOWRT 
[Ctrl/Z]
 
      

In this example, the linker protects the program section PSECT_1 from write access and leaves all other attributes of PSECT_1 unchanged.

Enables or disables RMS related name context processing. This is also known as file specification "stickiness." The default is to have RMS related name context processing enabled. This default applies at the start of each options file regardless of the setting in a previous options file. The related name context itself (the collection of data structures RMS maintains to supply the most recently specified fields) does not carry over from one linker options file to the next. That is, previously specified fields in the previous options file are not used to fill in absent fields for file specifications in the current options file.

Format

RMS_RELATED_CONTEXT=YES/NO

Option Values

YES

Enables RMS related name context processing starting with the context previously saved by a RMS_RELATED_CONTEXT=NO command. If RMS related name context processing is already enabled, this option has no effect.

NO

Disables RMS related name context processing. When RMS related name context processing is disabled, the current context is saved for a possible future RMS_RELATED_CONTEXT=YES option. If RMS related name context processing is already disabled, specifying RMS_RELATED_CONTEXT=NO has no effect.

Description

When RMS related name processing is enabled (by default at the beginning of each options file), file specifications that do not have all fields of the file specification present will have the missing fields replaced with the corresponding fields most recently specified in earlier file specifications. When disabled, fields in the file specification that are absent are not replaced with corresponding fields of previous file specifications.

When RMS related name processing is disabled, the current related name context is saved. When RMS related name processing is enabled via this option, the saved related name context is restored.

Specifies the size of the user-mode stack.

Format

STACK=number-of-pages

Option Values

number-of-pages

Specifies the size of the stack in pagelets (512-byte units).

Description

If you do not specify the STACK= option, the linker allocates 20 pagelets (512-byte units) for the user-mode stack. Note that additional pages for the user-mode stack are automatically allocated, if needed, during program execution.

The STACK= option may be specified only in a link operation that produces an executable image.

Note that the STACK= option is primarily used to set the stack size for images that are linked with the /P0IMAGE qualifier, where the stack could grow into the mapped image and corrupt it.

Directs the linker to define an absolute global symbol with the specified name and assign it the specified value.

Format

SYMBOL=symbol-name,symbol-value

Option Values

symbol-name

A character string up to 31 characters in length.

symbol-value

The value you want to assign to the symbol. An absolute global symbol has a fixed numeric value and is therefore not relocatable. Thus, the value must be a number.

Description

The definition of a symbol specified by the SYMBOL= option constitutes the first definition of that symbol, and it overrides subsequent definitions of the symbol in input object modules. In particular:

• If the symbol is defined as relocatable in an input object module, the linker ignores this definition, uses the definition specified by the SYMBOL= option, and issues a warning message.
• If the symbol is defined as absolute in an input object module, the linker ignores this definition and uses the definition specified by the SYMBOL= option; however, it does not issue a warning message.

For more information about symbol resolution, see Chapter 2.

Note The SYMBOL= option cannot be used with the UNIVERSAL= option or the SYMBOL_VECTOR= option.

Example

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

For Alpha linking, specifies whether the linker should include global symbols in a symbol table file produced in a link operation in which a shareable image is created. By default, the linker includes only universal symbols in a symbol table file associated with a shareable image.

Format

SYMBOL_TABLE=GLOBALS/UNIVERSALS

Option Values

GLOBALS

Specifies that the linker should include global symbols and universal symbols in the symbol table file associated with the shareable image.

UNIVERSALS

Specifies that the linker should include only universal symbols in the symbol table file associated with the shareable image.

Description

This option may be specified only in the creation of a shareable image. Note that the symbol table file affected by this option cannot be used as input in a subsequent link operation but is intended to be used with the OpenVMS Alpha System Dump Analyzer utility (SDA) as an aid to debugging.

Example

$  LINK/SHARE/SYMBOL_TABLE  MY_SHARE,SYS$INPUT/OPT 
GSMATCH=lequal,1,1000 
SYMBOL_VECTOR=(proc1=PROCEDURE,- 
               proc2=PROCEDURE,- 
               proc4=PROCEDURE) 
SYMBOL_TABLE=GLOBALS 
[Ctrl/Z]
      

In the example, the symbols proc1, proc2, and proc4 are declared as universal symbols. Normally, these symbols would be the only symbols to appear in a symbol table file associated with this shareable image. (The symbol table file duplicates the global symbol table of the shareable image.) However, because the SYMBOL_TABLE=GLOBALS option is specified, the linker also puts all the global symbols in the shareable image into the symbol table file. You must specify the /SYMBOL_TABLE qualifier to obtain a symbol table file.

	privacy and legal statement
4548PRO_015.HTML