VMS Help INSTALL, ADD  *Conan The Librarian (sorry for the slow response - running on an old VAX)

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

    You can specify one or more of the privilege names shown in
    an appendix of the OpenVMS Guide to System Security.

 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.

    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 /AUTHPRIVILEGED 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 /AUTHPRIVILEGED qualifier.
    In other words, if you assign authorized privileges using
    /AUTHPRIVILEGED, those are the privileges that appear as
    authorized privileges.

    Table of Privilege Names

    You can specify one or more of the privilege names shown in
    an appendix of the OpenVMS Guide to System Security.

 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
       /NOWRITABLE

    Installs the file as a writable known image as long as you also
    specify the /SHARED qualifier. The /WRITABLE qualifier only
    applies to images with image sections that are shareable and
    writable. The /WRITABLE qualifier is automatically negated if the
    /NOSHARED qualifier is specified.

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.