 |
OpenVMS Linker Utility Manual
GSMATCH=
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
| #1 |
$ 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.
| #2 |
$ 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.
| #3 |
$ 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).
IDENTIFICATION=
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]
|
IOSEGMENT=
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]
|
ISD_MAX=
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]
|
NAME=
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]
|
PROTECT=
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.
PSECT_ATTR=
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.
RMS_RELATED_CONTEXT=
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.
STACK=
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.
SYMBOL=
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]
|
SYMBOL_TABLE= (Alpha Only)
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.
|
