VMS Help System Services, $SET SECURITY  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Modifies the security characteristics of a protected object.

    Format

      SYS$SET_SECURITY  [clsnam] ,[objnam] ,[objhan] ,[flags]

                        ,[itmlst] ,[contxt] ,[acmode]

    C Prototype

      int sys$set_security  (void *clsnam, void *objnam, unsigned

                            int *objhan, unsigned int flags, void

                            *itmlst, unsigned int *contxt, unsigned

                            int *acmode);

1 - Arguments

 clsnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Name of the object class. The clsnam argument is the address of
    a descriptor pointing to a string that contains the name of the
    object class.

    The following is a list of the protected object class names:

       CAPABILITY
       COMMON_EVENT_CLUSTER
       DEVICE
       FILE
       GLXGRP_GLOBAL_SECTION
       GLXSYS_GLOBAL_SECTION
       GROUP_GLOBAL_SECTION
       ICC_ASSOCIATION
       LOGICAL_NAME_TABLE
       QUEUE
       RESOURCE_DOMAIN
       SECURITY_CLASS
       SYSTEM_GLOBAL_SECTION
       VOLUME

 objnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Name of the protected object whose associated security profile
    is going to be retrieved. The objnam argument is the address
    of a descriptor pointing to a string containing the name of the
    protected object.

    The format of an object name is class specific. The following
    table lists object names and describes their formats:

    Object Class        Object Name Format

    CAPABILITY          A character string. Currently, the only
                        capability object is VECTOR.

    COMMON_EVENT_       Name of the event flag cluster, as defined
    CLUSTER             in the Associate Common Event Flag Cluster
                        ($ASCEFC) system service.

    DEVICE              Standard device specification, described in
                        the OpenVMS User's Manual.

    FILE                Standard file specification, described in the
                        OpenVMS User's Manual.

    GROUP_GLOBAL_       Section name, as defined in the Create and
    SECTION             Map Section ($CRMPSC) system service.

    ICC_ASSOCIATION     ICC security object name node::association_
                        name. The special node name, ICC$::, refers
                        to entries in the clusterwide registry. For
                        registry entries, the Access Access Type does
                        not apply.

    LOGICAL_NAME_TABLE  Table name, as defined in the Create Logical
                        Name Table ($CRELNT) system service.

    QUEUE               Standard queue name, as described in the Send
                        to Job Controller ($SNDJBC) system service.

    RESOURCE_DOMAIN     An identifier or octal string enclosed in
                        brackets.

    SECURITY_CLASS      Any class name shown in the Object Class
                        column of this table, or a class name
                        followed by a period (.) and the template
                        name. Use the DCL command SHOW SECURITY to
                        display possible template names.

    SYSTEM_GLOBAL_      Section name, as defined in the Create and
    SECTION             Map Section ($CRMPSC) system service.

    VOLUME              Volume name or name of the device on which
                        the volume is mounted.

 objhan

    OpenVMS usage:object_handle
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Data structure identifying the object to address. The objhan
    argument is an address of a longword containing the object
    handle. You can use the objhan argument as an alternative to the
    objnam argument; for example, a channel number clearly specifies
    the file open on the channel and can serve as an object handle.

    The following table shows the format of the object classes:

    Object Class         Object Handle Format

    COMMON_EVENT_        Event flag number
    CLUSTER
    DEVICE               Channel number
    FILE                 Channel number
    RESOURCE_DOMAIN      Resource domain identifier
    VOLUME               Channel number

 flags

    OpenVMS usage:flags
    type:         mask_longword
    access:       read only
    mechanism:    by value
    Mask specifying processing options. The flags argument is a
    longword bit vector wherein a bit, when set, specifies the
    corresponding option. The flags argument requires the contxt
    argument.

    The following table describes each flag:

    Symbolic Name   Description

    OSS$M_LOCAL     Do not update the master profile for the
                    specified object. This flag allows you to call
                    $SET_SECURITY several times to modify a local
                    copy of a profile; once the modifications are
                    satisfactory, you can clear the OSS$M_LOCAL flag,
                    set the OSS$M_RELCTX flag, and have $SET_SECURITY
                    update the master profile. The flag applies only
                    to calls made with the contxt argument.

    OSS$M_RELCTX    Release the context structure at the completion
                    of this request.

    The $OSSDEF macro defines symbolic names for the flag bits. You
    construct the flags argument by specifying the symbolic names of
    each desired option.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying which information about the process or
    processes is to be modified. The itmlst argument is the address
    of a list of item descriptors, each of which describes an item
    of information. The list of item descriptors is terminated by a
    longword of 0.

    With the item list, the user modifies the protected object's
    characteristics. The user defines which security characteristics
    to modify. If this argument is not present, only the flags
    argument is processed. Without the itmlst argument, you can
    only manipulate the security profile locks or release contxt
    resources.

    Refer to the OpenVMS System Services Reference Manual to view the
    item code diagram and descriptor fields table.

 contxt

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Value used to maintain protected object processing context when
    dealing with a single protected object across multiple $GET_
    SECURITY/$SET_SECURITY calls. Whenever the context value is
    nonzero, the class name, object name, or object handle arguments
    are disregarded. An input value of 0 indicates that a new context
    should be established.

    Because an active context block consumes process memory, be sure
    to release the context block by setting the RELCTX flag when the
    profile processing is complete. $SET_SECURITY sets the context
    argument to 0 once the context is released.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Access mode to be used in the object protection check. The acmode
    argument is the address of a longword containing the access mode.
    The acmode argument defaults to kernel mode; however, the system
    compares acmode with the caller's access mode and uses the least
    privileged mode. The access modes are defined in the system macro
    $PSLDEF library.

    Compaq recommends that this argument be omitted (passed as zero).