 |
OpenVMS Utility Routines Manual
LBR$OPEN
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]
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.
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 (8)
|
Alpha shareable image
|
|
|
(9--127)
|
Reserved by Compaq
|
|
|
LBR$C_TYP_USRLW (128)
|
User library types --- low end of range
|
|
|
LBR$C_TYP_USRHI (255)
|
User library types --- high end of 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).
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.
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.
|
LBR$OUTPUT_HELP
The LBR$OUTPUT_HELP routine outputs help text to a user-supplied output
routine. The text is obtained from an explicitly named help library or,
optionally, from user-specified default help libraries. An optional
prompting mode is available that enables LBR$OUTPUT_HELP to interact
with you and continue to provide help information after the initial
help request has been satisfied.
Format
LBR$OUTPUT_HELP output_routine [,output_width] [,line_desc]
[,library_name] [,flags] [,input_routine]
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.
Arguments
output_routine
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
write only |
| mechanism: |
by reference |
Name of a routine that writes help text a line at a time. The
output_routine argument is the address of the
procedure value of the routine to call. You should specify either the
address of LIB$PUT_OUTPUT or a routine of your own that has the same
calling format as LIB$PUT_OUTPUT.
output_width
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Width of the help-text line to be passed to the user-supplied output
routine. The output_width argument is the address of a
longword containing the width of the text line to be passed to the
user-supplied output routine. If you omit output_width
or specify it as 0, the default output width is 80 characters per line.
line_desc
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Contents of the help request line. The line_desc
argument is the address of a string descriptor pointing to a character
string containing one or more help keys defining the help requested,
for example, the HELP command line minus the HELP command and HELP
command qualifiers. The default is a string descriptor for an empty
string.
library_name
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Name of the main library. The library_name argument is
the address of a string descriptor pointing to the main library file
specification string. The default is a null string, which means you
should use the default help libraries. If you omit the device and
directory specifications, the default is SYS$HELP. The default file
type is .HLB.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Flags specifying help output options. Each programming language
provides an appropriate mechanism for accessing these flags. The
flags argument is the address of an unsigned longword
that contains the following flags, when set:
| Flag |
Description |
|
HLP$M_PROMPT
|
Interactive help prompting is in effect.
|
|
HLP$M_PROCESS
|
The process logical name table is searched for default help libraries.
|
|
HLP$M_GROUP
|
The group logical name table is searched for group default help
libraries.
|
|
HLP$M_SYSTEM
|
The system logical name table is searched for system default help
libraries.
|
|
HLP$M_LIBLIST
|
The list of default libraries available is output with the list of
topics available.
|
|
HLP$M_HELP
|
The list of topics available in a help library is preceded by the major
portion of the text on help.
|
If you omit this longword, the default is for prompting and all default
library searching to be enabled, but no library list is generated and
no help text precedes the list of topics.
input_routine
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
read only |
| mechanism: |
by reference |
Routine used for prompting. The input_routine argument
is the address of the procedure value of the prompting routine. You
should specify either the address of LIB$GET_INPUT or a routine of your
own that has the same calling format as LIB$GET_INPUT. This argument
must be supplied when the HELP command is run in prompting mode (that
is, HLP$M_PROMPT is set or defaulted).
Description
The LBR$OUTPUT_HELP routine provides a simple, one-call method to
initiate an interactive help session. Help library bookkeeping
functions, such as LBR$INI_CONTROL and LBR$OPEN, are handled
internally. You should not call LBR$INI_CONTROL or LBR$OPEN before you
issue a call to LBR$OUTPUT_HELP.
LBR$OUTPUT_HELP accepts help keys in the same format as LBR$GET_HELP,
with the following qualifications:
- If the keyword HELP is supplied, help text on HELP is output,
followed by a list of HELP subtopics available.
If no help keys are
provided or if the line_desc argument is 0, a list of
topics available in the root library is output.
- If the line_desc argument contains a list of help
keys, then each key must be separated from its predecessor by a slash
(/) or by one or more spaces.
- The first key can specify a library to replace the main library as
the root library (the first library searched) in which LBR$OUTPUT_HELP
searches for help. A key used for this purpose must have the form
<@filespec>, where filespec is subject to the
same restrictions as the library_name argument. If the
specified library is an enabled user-defined default library, then
filespec can be abbreviated as any unique substring of that
default library's logical name translation.
In default library searches, you can define one or more default
libraries for LBR$OUTPUT_HELP to search for help information not
contained in the root library. Do this by equating logical names
(HLP$LIBRARY, HLP$LIBRARY_1,...,HLP$LIBRARY_999) to the file
specifications of the default help libraries. You can define these
logical names in the process, group, or system logical name table.
If default library searching is enabled by the flags
argument, LBR$OUTPUT_HELP uses those flags to determine which logical
name tables are enabled and then automatically searches any user
default libraries that have been defined in those logical name tables.
The library search order proceeds as follows: root library, main
library (if specified and different from the root library), process
libraries (if enabled), group libraries (if enabled), system libraries
(if enabled). If the requested help information is not found in any of
these libraries, LBR$OUTPUT_HELP returns to the root library and issues
a "help not found" message.
To enter an interactive help session (after your initial request for
help has been satisfied), you must set the HLP$M_PROMPT bit in the
flags argument.
You can encounter four different types of prompt in an interactive help
session. Each type represents a different level in the hierarchy of
help available to you.
- If the root library is the main library and you are not currently
examining HELP for a particular topic, the prompt Topic? is
output.
- If the root library is a library other than the main library and if
you are not currently examining HELP for a particular topic, a prompt
of the form @<library-spec>Topic? is output.
- If you are currently examining HELP for a particular topic (and
subtopics), a prompt of the form <keyword...>subtopic?
is output.
- A combination of 2 and 3.
When you encounter one of these prompt messages, you can respond in any
one of several ways. Each type of response and its effect on
LBR$OUTPUT_HELP in each prompting situation is described in the
following table:
| Response |
Action in the Current Prompt Environment1 |
|
keyword [...]
|
(1,2) Search all enabled libraries for these keys.
|
|
|
(3,4) Search additional help for the current topic (and subtopic) for
these keys.
|
|
@filespec [keyword[...]]
|
(1,2) Same as above, except that the root library is the library
specified by
filespec. If the specified library does not exist, treat
@filespec as a normal key.
|
|
|
(3,4) Same as above; treat
@filespec as a normal key.
|
|
?
|
(1,2) Display a list of topics available in the root library.
|
|
|
(3,4) Display a list of subtopics of the current topic (and subtopics)
for which help exists.
|
|
Carriage Return
|
(1) Exit from LBR$OUTPUT_HELP.
|
|
|
(2) Change root library to main library.
|
|
|
(3,4) Strip the last keyword from a list of keys defining the current
topic (and subtopic) environment.
|
|
Ctrl/Z
|
(1,2,3,4) Exit from LBR$OUTPUT_HELP.
|
1Keyed to the prompt in the preceding list.
Condition Values Returned
|
LBR$_ILLINROU
|
Input routine improperly specified or omitted.
|
|
LBR$_ILLOUTROU
|
Output routine improperly specified or omitted.
|
|
LBR$_NOHLPLIS
|
Error. No default help libraries can be opened.
|
|
LBR$_TOOMNYARG
|
Error. Too many arguments were specified.
|
|
LBR$_USRINPERR
|
Error. An error status was returned by the user-supplied input routine.
|
|
