Installs the specified image file as a known image. The ADD
command is a synonym for the CREATE command.
Requires the CMKRNL privilege. Also requires the SYSGBL privilege
to create system global sections and the PRMGBL privilege to
create permanent global sections.
Format
ADD file-spec
1 – Parameter
file-spec
Names the file specification of an image to be installed as
a known image. The file specification must name an existing
executable or shareable image, which must have been linked with
the /NOTRACEBACK qualifier. If you omit the device and directory
specification, the default SYS$SYSTEM is used. The default file
type is .EXE.
The highest existing version of the file is used by default.
However, you can specify another version of the file as the known
version of the image. Even if other versions of the file exist,
the version that you specify will be the version that satisfies
all known file lookups for the image.
2 – Qualifiers
2.1 /ACCOUNTING
/ACCOUNTING
/NOACCOUNTING (default)
Enables image-level accounting for selected images even if image
accounting is disabled on the local node (by using the DCL
command SET ACCOUNTING/DISABLE=IMAGE). When image accounting
is enabled on the local node, it logs all images, and the
/NOACCOUNTING qualifier has no effect.
2.2 /ARB_SUPPORT
/ARB_SUPPORT=keyword
On Alpha systems, overrides the system parameter ARB_SUPPORT for
this installed image.
The following table shows the keywords you can use with the /ARB_
SUPPORT qualifier:
Keyword Behavior
None The obsolete kernel data cells are not maintained by
the system. Fields are initialized to zero or set to
invalid pointers at process creation.
Clear The obsolete kernel data cells are cleared or set
to invalid pointers when the code would have set up
values for backward compatibility.
Read-only The obsolete cells are updated with corresponding
security information stored in the current Persona
Security Block (PSB) when a $PERSONA_ASSUME is
issued.
Full Data is moved from the obsolete cells to the
(default) currently active PSB on any security-based operation.
For more information about obsolete kernel cells, refer to the
ARB_SUPPORT system parameter in online help.
2.3 /AUTHPRIVILEGES
/AUTHPRIVILEGES[=(priv-name[,...])]
/NOAUTHPRIVILEGES
Installs the file as a known image with the authorized privileges
specified.
Usage Notes
o If a privileged image is not located on the system volume, the
image is implicitly installed /OPEN.
o The set of privileges for a privileged image can be empty. You
must, however, list each privilege every time you define or
redefine privileges.
o The /AUTHPRIVILEGES qualifier applies only to executable
images.
o You cannot specify this qualifier for an executable image
linked with the /TRACEBACK qualifier.
o You cannot assign privilege names with the /NOAUTHPRIVILEGES
qualifier.
You can specify one or more of the privilege names described in
detail in an appendix to the OpenVMS Guide to System Security.
(ALL is the default.)
2.4 /EXECUTE_ONLY
/EXECUTE_ONLY
/NOEXECUTE_ONLY (default)
The /EXECUTE_ONLY qualifier is meaningful only to main programs.
It allows the image to activate shareable images to which the
user has execute access but no read access. All shareable images
referenced by the program must be installed, and OpenVMS RMS
uses trusted logical names (those created for use in executive or
kernel mode).
You cannot specify this qualifier for an executable image linked
with the /TRACEBACK qualifier.
2.5 /HEADER_RESIDENT
/HEADER_RESIDENT
/NOHEADER_RESIDENT
Installs the file as a known image with a permanently resident
header (native mode images only). An image installed header
resident is implicitly also installed open.
2.6 /LOG
/LOG
/NOLOG (default)
Lists the newly created known file entry along with any
associated global sections created by the installation.
2.7 /OPEN
/OPEN
/NOOPEN
Installs the file as a permanently open known image.
2.8 /PRIVILEGED
/PRIVILEGED[=(priv-name[,...])]
/NOPRIVILEGED
Installs the file as a known image with the active privileges
specified.
Usage Notes
o If a privileged image is not located on the system volume, the
image is implicitly installed /OPEN.
o The set of privileges for a privileged image can be empty.
o You must list each privilege every time you define or redefine
privileges.
o The /PRIVILEGED qualifier applies only to executable images.
o You cannot specify this qualifier for an executable image
linked with the /TRACEBACK qualifier.
o You cannot assign privilege names with the /NOPRIVILEGED
qualifier.
Installing Shareable Images
Installing an image with privileges declares that the image is
trusted to maintain system integrity and security properly.
To maintain that trust, any routine called by the privileged
image must also be trusted. For this reason, any shareable images
activated for use by a privileged image must be installed. Only
trusted logical names (names defined in executive and kernel
mode) can be used in locating shareable images to be used by a
privileged image.
Interaction of /PRIVILEGED and /AUTHPRIVILEGES Qualifiers
When you create a new entry, the privileges you assign are also
assigned for Authorized Privileges if you do not assign specific
authorized privileges with the /AUTHPRIVILEGES qualifier.
When you replace an image, any privileges assigned with the
/PRIVILEGED qualifier are not repeated as Authorized Privileges.
Also, if you use the REPLACE command with the /NOAUTHPRIVILEGES
qualifier, the Authorized Privileges become the same as the
Default Privileges (set using the /PRIVILEGED qualifier).
You can specify one or more of the privilege names described in
detail in an appendix to the OpenVMS Guide to System Security.
(ALL is the default.)
2.9 /PROTECTED
/PROTECTED
/NOPROTECTED (default)
Installs the file as a known image that is protected from
user-mode and supervisor-mode write access. You can write into
the image only from executive or kernel mode. The /PROTECTED
qualifier together with the /SHARE qualifier are used to
implement user-written services, which become privileged
shareable images.
2.10 /PURGE
/PURGE (default)
/NOPURGE
Specifies that the image can be removed by a purge operation; if
you specify /NOPURGE, you can remove the image only by a delete
or remove operation.
2.11 /RESIDENT
/RESIDENT[=([NO]CODE,[NO]DATA)]
On Alpha systems, causes image code sections or read-only
data sections to be placed in the granularity hint regions and
compresses other image sections, which remain located in process
space. If you do not specify the /RESIDENT qualifier, neither
code nor data is installed resident. If you specify the /RESIDENT
qualifier without keyword arguments, code is installed resident,
and data is not installed resident.
The image must be linked using the /SECTION_BINDING=(CODE,DATA)
qualifier. An image installed with resident code or data is
implicitly installed header resident and shared.
2.12 /SHARED
/SHARED=[NO]ADDRESS_DATA
/NOSHARED
Installs the file as a shared known image and creates global
sections for the image sections that can be shared. An image
installed shared is implicitly installed open.
When you use the ADDRESS_DATA keyword with the /SHARED qualifier,
P1 space addresses are assigned for shareable images. With the
assigned addresses, the Install utility can determine the content
of an address data section when the image is installed rather
than when it is activated, reducing CPU and I/O time. A global
section is created to allow shared access to address data image
sections.
2.13 /WRITABLE
/WRITABLE=[GALAXY[=IDENT]]
/NOWRITABLE
Installs the file as a writable known image when you also specify
the /SHARED qualifier. The /WRITABLE qualifier applies only to
images with image sections that are shareable and writable. The
/WRITABLE qualifier is automatically negated if the /NOSHARED
qualifier is specified.
You can use the GALAXY keyword with the /WRITABLE qualifier to
place write shared image sections in Galaxy global sections.
You can also use the IDENT keyword with GALAXY to include the
image ident in the name of the Galaxy global section, so that
multiple versions of an image can be used simultaneously in a
Galaxy system.
3 – Examples
1.INSTALL> ADD/OPEN/SHARED WRKD$:[MAIN]STATSHR
The command in this example installs the image file STATSHR as
a permanently open, shared known image.
2.INSTALL> ADD/OPEN/PRIVILEGED=(GROUP,GRPNAM) GRPCOMM
The command in this example installs the image file GRPCOMM as
a permanently open, known image with the privileges GROUP and
GRPNAM.
Any process running GRPCOMM receives the GROUP and GRPNAM
privileges for the duration of the execution of GRPCOMM. The
full name of GRPCOMM is assumed to be SYS$SYSTEM:GRPCOMM.EXE.
3.INSTALL> ADD/LOG GRPCOMM
The command in this example installs the image file GRPCOMM
as a known image and then displays the newly added known file
entry.
4.INSTALL> ADD/SHARED=ADDRESS_DATA WRKD$:[MAIN]INFOSHR
The command in this example installs the INFOSHR file as a
shared known image and creates shared global sections for
code sections and read-only data sections. Because the command
includes the ADDRESS_DATA keyword, address data is also created
as a shared global section.