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

    The LBR$OPEN routine opens an existing library or creates a new
    one.

    Format

      LBR$OPEN  library_index [,fns] [,create_options] [,dns]

                [,rlfna] [,rns] [,rnslen]

1 - Returns

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

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

2 - Arguments

 library_index

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Library control index returned by the LBR$INI_CONTROL routine.
    The library_index argument is the address of a longword
    containing the index.

 fns

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    File specification of the library. The fns argument is
    the address of a string descriptor pointing to the file
    specification. Unless the OpenVMS RMS NAM block address was
    previously supplied in the LBR$INI_CONTROL routine and contained
    a file specification, this argument must be included. Otherwise,
    the Librarian returns an error (LBR$_NOFILNAM).

 create_options

    OpenVMS usage:vector_longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Library characteristics. The create_options argument is
    the address of an array of 20 longwords that define the
    characteristics of the library you are creating. If you are
    creating a library with LBR$C_CREATE, you must include the
    create_options argument. The following table shows the entries
    that the array must contain. Each programming language provides
    an appropriate mechanism for accessing the listed symbols.

    Offset
    in
    Longwords Symbolic Name        Contents

    0         CRE$L_TYPE           Library type:
              LBR$C_TYP_UNK (0)    Unknown/unspecified
              LBR$C_TYP_OBJ (1)    VAX object
              LBR$C_TYP_MLB (2)    Macro
              LBR$C_TYP_HLP (3)    Help
              LBR$C_TYP_TXT (4)    Text
              LBR$C_TYP_SHSTB (5)  VAX shareable image
              LBR$C_TYP_NCS (6)    NCS
              LBR$C_TYP_EOBJ (7)   Alpha object
              LBR$C_TYP_ESHSTB     Alpha shareable image
              (8)
              (9-127)              Reserved by Compaq
              LBR$C_TYP_USRLW      User library types - low end of
              (128)                range
              LBR$C_TYP_USRHI      User library types - high end of
              (255)                range
    1         CRE$L_KEYLEN         Maximum length of ASCII keys or,
                                   if 0, indicates 32-bit unsigned
                                   keys (binary keys)
    2         CRE$L_ALLOC          Initial library file allocation
    3         CRE$L_IDXMAX         Number of library indexes (maximum
                                   of eight)
    4         CRE$L_UHDMAX         Number of additional bytes to
                                   reserve in module header
    5         CRE$L_ENTALL         Number of index entries to
                                   preallocate
    6         CRE$L_LUHMAX         Maximum number of library update
                                   history records to maintain
    7         CRE$L_VERTYP         Format of library to create:
              CRE$C_VMSV2          VMS Version 2.0
              CRE$C_VMSV3          VMS Version 3.0
    8         CRE$L_IDXOPT         Index key casing option:
              CRE$C_HLPCASING      Treat character case as it is for
                                   help libraries
              CRE$C_OBJCASING      Treat character case as it is for
                                   object libraries
              CRE$C_MACTXTCAS      Treat character case as it is for
                                   macro and text libraries
    9-19                           Reserved by Compaq

    The input of uppercase and lowercase characters is treated
    differently for help, object, macro, and text libraries. For
    details, see the OpenVMS Command Definition, Librarian, and
    Message Utilities Manual.

 dns

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Default file specification. The dns argument is the address
    of the string descriptor that points to the default file
    specification. See the OpenVMS Record Management Services
    Reference Manual for details about how defaults are processed.

 rlfna

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Related file name. The rlfna argument is the address of an
    RMS NAM block pointing to the related file name. You must
    specify rlfna for related file name processing to occur. If a
    related file name is specified, only the file name, type, and
    version fields of the NAM block are used for related name block
    processing. The device and directory fields are not used. See the
    OpenVMS Record Management Services Reference Manual for details
    on processing related file names.

 rns

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor
    Resultant file specification returned. The rns argument is the
    address of a string descriptor pointing to a buffer that is to
    receive the resultant file specification string. If an error
    occurs during an attempt to open the library, the expanded name
    string is returned instead.

 rnslen

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference
    Length of the resultant or expanded file name. The rnslen
    argument is the address of a longword receiving the length
    of the resultant file specification string (or the length of
    the expanded name string if there was an error in opening the
    library).

3 - Description

    You can call this routine only after you call LBR$INI_CONTROL and
    before you call any other LBR routine except LBR$OUTPUT_HELP.

    When the library is successfully opened, the LBR routine reads
    the library header into memory and sets the default index to 1.

    If the library cannot be opened because it is already open for a
    write operation, LBR$OPEN retries the open operation every second
    for a maximum of 30 seconds before returning the RMS error, RMS$_
    FLK, to the caller.

4 - Condition Values Returned

    LBR$_ERRCLOSE      Error. When the library was last modified
                       while opened for write access, the write
                       operation was interrupted. This left the
                       library in an inconsistent state.
    LBR$_ILLCREOPT     Requested create options not valid or not
                       supplied.
    LBR$_ILLCTL        Specified library control index not valid.
    LBR$_ILLFMT        Specified library format not valid.
    LBR$_ILLFUNC       Specified library function not valid.
    LBR$_LIBOPN        Specified library already open.
    LBR$_NOFILNAM      Error. The fns argument was not supplied or
                       the RMS NAM block was not filled in.
    LBR$_OLDLIBRARY    Success. The specified library has been
                       opened; the library was created with an old
                       library format.
    LBR$_OLDMISMCH     Requested library function conflicts with old
                       library type specified.
    LBR$_TYPMISMCH     Library type does not match the requested
                       type.