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 VSI
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 VSI
The input of uppercase and lowercase characters is treated
differently for help, object, macro, and text libraries. For
details, see the VSI 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.