VMS Help RTL Routines, LIB$, LIB$CREATE_DIR  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    The Create a Directory routine creates a directory or
    subdirectory.

    Format

      LIB$CREATE_DIR  device-directory-spec [,owner-UIC]

                      [,protection-enable] [,protection-value]

                      [,maximum-versions] [,relative-volume-number]

                      [,initial-allocation]

1 - Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

2 - Arguments

 device-directory-spec

    OpenVMS usage:device_name
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Directory specification of the directory or subdirectory that
    LIB$CREATE_DIR will create. The device-directory-spec argument
    is the address of a descriptor pointing to this directory
    specification.

    The format of the device-directory-spec string conforms
    to standard OpenVMS Record Management Services (RMS)
    format. This specification must contain a directory or
    subdirectory specification. It may contain a disk specification.
    SMD$:[THIS.IS.IT] is an example of a standard RMS file
    specification, where SMD$ is the disk specification and
    [THIS.IS.IT] is the subdirectory specification.

    This specification cannot contain a node name, file name, file
    type, file version, or wildcard characters. The maximum size
    of this string is 255 characters on VAX, and 4095 characters on
    Alpha.

 owner-UIC

    OpenVMS usage:uic
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    User identification code (UIC) identifying the owner of the
    created directory or subdirectory. The owner-UIC argument is the
    address of an unsigned longword that contains the UIC. If owner-
    UIC is zero, the owner UIC is that of the parent directory. The
    specified value for owner-UIC is interpreted as a 32-bit octal
    number, with two 16-bit fields:

       bits 00-15 - Member number
       bits 16-31 - Group number

    This is an optional argument. The default is the UIC of the
    current process except when the directory is in UIC format. For
    a directory in UIC format, for example [123,321], the UIC of the
    created directory is used.

 protection-enable

    OpenVMS usage:mask_word
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Mask specifying the bits of protection-value to be set. The
    protection-enable argument is the address of an unsigned word
    containing this protection mask.

    The following diagram shows the structure of a protection mask.
    Access is allowed for bits set to 0.

           World           Group          Owner           System
    +_______________+_______________+_______________+_______________+
    | D | W | E | R | D | W | E | R | D | W | E | R | D | W | E | R |
    _________________________________________________________________
     15                                                           0

    Bits set in the protection-enable mask cause corresponding bits
    of protection-value to be set. Bits not set in the protection-
    enable mask cause corresponding bits of protection-value to take
    the value of the corresponding bit in the parent directory's
    file protection. Bits in the parent directory's file protection
    that indicate delete access do not cause corresponding bits of
    protection-value to be set, however.

    Following is an example of how the protection-value protection
    mask is defined:

                     Hexadecimal
    Mask Name        Number      Value

    Protection       %XDBFF      S:None, O:None, G:E, W:W
    enable
    Parent           %X13FF      S:RWED, O:RWED, G:RW, W:R
    directory
    Protection       %X37FF      S:RWE, O:RWE, G:RWE, W:RW
    value

    The protection-enable argument is optional. It should be
    used only when you want to change protection values from the
    parent directory's default file protection. The default for
    protection-enable is a mask of all zero bits, which results in
    the propagation of the parent directory's file protection. If
    the protection-enable mask contains zeros, protection-value is
    ignored.

 protection-value

    OpenVMS usage:file_protection
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    System/Owner/Group/World protection value of the directory you
    are creating. The protection-value argument is the address of an
    unsigned word that contains this protection mask.

    The bits of protection-value are set or cleared in the method
    described in the definition of protection-enable above.

    The protection-value argument is optional. The default is a word
    of all zero bits, which specifies full access for all access
    categories. Typically, protection-value is not omitted unless
    protection-enable is also omitted. If protection-enable is
    omitted, protection-value is ignored.

 maximum-versions

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Maximum number of versions allowed for files created in the newly
    created directories. The maximum-versions argument is the address
    of an unsigned word containing the value of the maximum number of
    versions.

    The maximum-versions argument is optional. The default is the
    parent directory's default version limit. If maximum-versions is
    zero, the maximum number of versions is not limited.

 relative-volume-number

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Relative volume number within a volume set on which the directory
    or subdirectory is created. The relative-volume-number argument
    is the address of an unsigned word containing the relative volume
    number. The relative-volume-number argument is optional. The
    default is arbitrary placement within the volume set.

 initial-allocation

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Initial number of blocks to be allocated to the directory. This
    argument is useful for creating large directories, for example
    MAIL.DIR;1. It can improve performance by avoiding the need for
    later dynamic expansion of the directory.

    The initial-allocation argument applies only to Files-11 Level 2
    volumes; it is ignored for other volumes.

    This argument is the address of an unsigned longword that
    contains the initial number of blocks to be allocated to the
    directory.

    The initial-allocation argument is optional. The default
    allocation is 1 block.