LBR Routines
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help LBR Routines *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
The Librarian (LBR) routines let you create and maintain
libraries and their modules, and use the data stored in library
modules.
| 1 - LBR$CLOSE |
The LBR$CLOSE routine closes an open library.
Format
LBR$CLOSE library_index
1.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.
1.2 - Argument
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 the longword that
contains the index.
1.3 - Description
When you are finished working with a library, you should call
LBR$CLOSE to close it. Upon successful completion, LBR$CLOSE
closes the open library and deallocates all of the memory used
for processing it.
1.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_LIBNOTOPN Specified library not open.
| 2 - LBR$DELETE_DATA |
The LBR$DELETE_DATA routine deletes the module header and data
associated with the specified module.
Format
LBR$DELETE_DATA library_index ,txtrfa
2.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.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 the longword that
contains the index.
txtrfa
OpenVMS usage:vector_longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Record's file address (RFA) of the module header for the module
you want to delete. The txtrfa argument is the address of the 2-
longword array that contains the RFA. You can obtain the RFA of a
module header by calling LBR$LOOKUP_exit KEY or LBR$PUT_RECORD.
2.3 - Description
If you want to delete a library module, you must first call
LBR$DELETE_KEY to delete any keys that point to it. If no library
index keys are pointing to the module header, LBR$DELETE_DATA
deletes the module header and associated data records; otherwise,
this routine returns the error LBR$_STILLKEYS.
Note that other LBR routines may reuse data blocks that contain
no data.
2.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_INVRFA Specified RFA not valid.
LBR$_LIBNOTOPN Specified library not open.
LBR$_STILLKEYS Keys in other indexes still point at the
module header. Therefore, the specified module
was not deleted.
| 3 - LBR$DELETE_KEY |
The LBR$DELETE_KEY routine deletes a key from a library index.
Format
LBR$DELETE_KEY library_index ,key_name
3.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.
3.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.
key_name
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Key to be deleted from the library index. For libraries with
binary keys, the key_name argument is the address of an unsigned
longword containing the key number.
For libraries with ASCII keys, the key_name argument is the
address of the string descriptor pointing to the key with the
following argument characteristics:
Argument
Characteristics Entry
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
3.3 - Description
If LBR$DELETE_KEY finds the key specified by key_name in the
current index, it deletes the key. Note that, if you want to
delete a library module, you should first use LBR$DELETE_KEY to
delete any keys that point to it, then use LBR$DELETE_DATA to
delete the module's header and associated data.
You cannot call LBR$DELETE_KEY from within the user-supplied
routine specified in LBR$SEARCH or LBR$GET_INDEX.
3.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_KEYNOTFND Specified key not found.
LBR$_LIBNOTOPN Specified library not open.
LBR$_UPDURTRAV Specified index update not valid in a user-
supplied routine specified in LBR$SEARCH or
LBR$GET_INDEX.
| 4 - LBR$FIND |
The LBR$FIND routine sets the current internal read context for
the library to the library module specified.
Format
LBR$FIND library_index ,txtrfa
4.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.
4.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 the longword that
contains the index.
txtrfa
OpenVMS usage:vector_longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Record's file address (RFA) of the module header for the module
you want to access. The txtrfa argument is the address of a 2-
longword array containing the RFA. You can obtain the RFA of a
module header by calling LBR$LOOKUP_KEY or LBR$PUT_RECORD.
4.3 - Description
Use the LBR$FIND routine to access a module that you had accessed
earlier in your program. For example, if you look up several
keys with LBR$LOOKUP_KEY, you can save the RFAs returned by
LBR$LOOKUP_KEY and later use LBR$FIND to reaccess the modules.
Thus, you do not have to look up the module header's key every
time you want to access the module. If the specified RFA is
valid, LBR$FIND initializes internal tables so you can read the
associated data.
4.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_INVRFA Specified RFA not valid.
LBR$_LIBNOTOPN Specified library not open.
| 5 - LBR$FLUSH |
The LBR$FLUSH routine writes modified blocks back to the library
file and frees the virtual memory the blocks had been using.
Format
LBR$FLUSH library_index ,block_type
5.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.
5.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 the longword that
contains the index.
block_type
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Extent of the flush operation. The block_type argument contains
the longword value that indicates how the flush operation
proceeds. If you specify LBR$C_FLUSHDATA, the data blocks are
flushed. If you specify LBR$C_FLUSHALL, first the data blocks and
then the current library index are flushed.
Each programming language provides an appropriate mechanism for
accessing these symbols.
5.3 - Description
LBR$FLUSH cannot be called from other LBR routines that reference
cache addresses or by routines called by LBR routines.
5.4 - Condition Values Returned
LBR$_NORMAL Operation completed successfully.
LBR$_BADPARAM Error. A value passed to the LBR$FLUSH routine
was either out of range or an illegal value.
LBR$_WRITERR Error. An error occurred during the writing of
the cached update blocks to the library file.
| 6 - LBR$GET_HEADER |
The LBR$GET_HEADER routine returns information from the library's
header to the caller.
Format
LBR$GET_HEADER library_index ,retary
6.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.
6.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 the longword that
contains the index.
retary
OpenVMS usage:vector_longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Array of 128 longwords that receives the library header. The
retary argument is the address of the array that contains the
header information. The information returned in the array is
listed in the following table. Each programming language provides
an appropriate mechanism for accessing this information.
Offset
in
Longwords Symbolic Name Contents
0 LHI$L_TYPE Library type (see LBR$OPEN for possible
values)
1 LHI$L_NINDEX Number of indexes
2 LHI$L_MAJORID Library format major identification
3 LHI$L_MINORID Library format minor identification
4 LHI$T_LBRVER ASCIC version of Librarian
12 LHI$L_CREDAT Creation date/time
14 LHI$L_UPDTIM Date/time of last update
16 LHI$L_UPDHIS Virtual block number (VBN) of start of
update history
17 LHI$L_FREEVBN First logically deleted block
18 LHI$L_FREEBLK Number of deleted blocks
19 LHI$B_NEXTRFA Record's file address (RFA) of end of
library
21 LHI$L_NEXTVBN Next VBN to allocate at end of file
22 LHI$L_ Number of free preallocated index blocks
FREIDXBLK
23 LHI$L_FREEIDX List head for preallocated index blocks
24 LHI$L_HIPREAL VBN of highest preallocated block
25 LHI$L_IDXBLKS Number of index blocks in use
26 LHI$L_IDXCNT Number of index entries (total)
27 LHI$L_MODCNT Number of entries in index 1 (module
names)
28 LHI$L_MHDUSZ Number of bytes of additional
information reserved in module header
29 LHI$L_ Maximum number of library update history
MAXLUHREC records maintained
30 LHI$L_ Number of library update history records
NUMLUHREC in history
31 LHI$L_ Library status (false if there was an
LIBSTATUS error closing the library)
32-128 Reserved by Compaq
6.3 - Description
On successful completion, LBR$GET_HEADER places the library
header information into the array of 128 longwords.
Note that the offset is the byte offset of the value into the
header structure. You can convert the offset to a longword
subscript by dividing the offset by 4 and adding 1 (assuming
that subscripts in your programming language begin with 1).
6.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_LIBNOTOPN Specified library not open.
| 7 - LBR$GET_HELP |
The LBR$GET_HELP routine retrieves help text from a help library,
displaying it on SYS$OUTPUT or calling your routine for each
record returned.
Format
LBR$GET_HELP library_index [,line_width] [,routine] [,data]
[,key_1] [,key_2 . . . ,key_10]
7.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.
7.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 the longword that
contains the index.
line_width
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Width of the help text line. The line_width argument is the
address of a longword containing the width of the listing line.
If you do not supply a line width or if you specify 0, the line
width defaults to 80 characters per line.
routine
OpenVMS usage:procedure
type: procedure value
access: read only
mechanism: by reference
Routine called for each line of text you want output. The routine
argument is the address of the procedure value for this user-
written routine.
If you do not supply a routine argument, LBR$GET_HELP calls the
Run-Time Library procedure LIB$PUT_OUTPUT to send the help text
lines to the current output device (SYS$OUTPUT). However, if you
want SYS$OUTPUT for your program to be a disk file rather than
the terminal, you should supply a routine to output the text.
If the user-written routine returns an error status with low bit
clear, the LBR$GET_HELP routine passes this status to the caller.
If the user-written routine returns a success status with low bit
set, the LBR$GET_HELP routine returns 1 to the caller.
The routine you specify is called with an argument list of four
longwords:
1. The first argument is the address of a string descriptor for
the output line.
2. The second argument is the address of an unsigned longword
containing flag bits that describe the contents of the text
being passed. The possible flags are as follows:
HLP$M_ Specified help text cannot be found.
NOHLPTXT
HLP$M_ Text contains key names of the printed text.
KEYNAMLIN
HLP$M_ Text is part of the information provided on
OTHERINFO additional help available.
Each programming language provides an appropriate mechanism
for accessing these flags. Note that, if no flag bit is set,
help text is passed.
3. The third argument is the address stipulated in the data
argument specified in the call to LBR$GET_HELP (or the address
of a 0 constant if the data argument is zero or was omitted).
4. The fourth argument is a longword containing the address of
the current key level.
The routine you specify must return with success or failure
status. A failure status (low bit = 0) terminates the current
call to LBR$GET_HELP.
data
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Data passed to the routine specified in the routine argument. The
data argument is the address of data for the routine. The address
is passed to the routine specified in the routine argument. If
you omit this argument or specify it as zero, then the argument
passed in your routine will be the address of a zero constant.
key_1,key_2, . . . ,key_10
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by descriptor
Level of the help text to be output. Each key_1,key_2, . . . ,key_
10 argument is the address of a descriptor pointing to the key
for that level.
If the key_1 descriptor is 0 or if it is not present, LBR$GET_
HELP assumes that the key_1 name is HELP, and it ignores all the
other keys. For key_2 through key_10, a descriptor address of 0,
or a length of 0, or a string address of 0 terminates the list.
The key argument may contain any of the following special
character strings:
String Meaning
* Return all level 1 help text in the library.
KEY . . .Return all help text associated with the specified key
and its subkeys (valid for level 1 keys only).
* . . . Return all help text in the library.
7.3 - Description
LBR$GET_HELP returns all help text in the same format as the
output returned by the DCL command HELP; that is, it indents two
spaces for every key level of text displayed. (Because of this
formatting, you may want to make your help messages shorter than
80 characters, so they fit on one line on terminal screens with
the width set to 80.) If you do not want the help text indented
to the appropriate help level, you must supply your own routine
to change the format.
Note that most application programs use LBR$OUTPUT_HELP instead
of LBR$GET_HELP.
7.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_LIBNOTOPN Specified library not open.
LBR$_NOTHLPLIB Specified library not a help library.
| 8 - LBR$GET_HISTORY |
The LBR$GET_HISTORY routine returns each library update history
record to a user-specified action routine.
Format
LBR$GET_HISTORY library_index ,action_routine
8.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.
8.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 the longword that
contains the index.
action_routine
OpenVMS usage:procedure
type: procedure value
access: modify
mechanism: by reference
User-supplied routine for processing library update history
records. The action_routine argument is the address of the
procedure value of this user-supplied routine. The routine is
invoked once for each update history record in the library.
One argument is passed to the routine, namely, the address of
a descriptor pointing to a history record.
8.3 - Description
This routine retrieves the library update history records written
by the routine LBR$PUT_HISTORY.
8.4 - Condition Values Returned
LBR$_NORMAL Normal exit from the routine.
LBR$_EMPTYHIST History empty. This is an informational code,
not an error code.
LBR$_INTRNLERR Internal Librarian routine error occurred.
LBR$_NOHISTORY No update history. This is an informational
code, not an error code.
| 9 - LBR$GET_INDEX |
The LBR$GET_INDEX routine calls a user-supplied routine for
selected keys in an index.
Format
LBR$GET_INDEX library_index ,index_number ,routine_name
[,match_desc]
9.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.
9.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 the longword that
contains the index.
index_number
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Number of the library index. The index_number argument is the
address of a longword containing the index number. This is the
index number associated with the keys you want to use as input to
the user-supplied routine .
routine_name
OpenVMS usage:procedure
type: procedure value
access: read only
mechanism: by reference
User-supplied routine called for each of the specified index
keys. The routine_name argument is the address of the procedure
value for this user-supplied routine.
LBR$GET_INDEX passes two arguments to the routine:
o A key name.
- For libraries with ASCII keys, the key_name argument is the
address of a string descriptor pointing to the key. Note
that the string and the string descriptor passed to the
routine are valid only for the duration of that call. The
string must be copied privately if you need it again for
more processing.
- For libraries with binary keys, the key_name argument is
the address of an unsigned longword containing the key
number.
o The record's file address (RFA) of the module's header for
this key name. The RFA argument is the address of a 2-longword
array that contains the RFA.
The routine must return a value to indicate success or failure.
If the routine returns a false value (low bit = 0), LBR$GET_INDEX
stops searching the index and returns the status value of the
user-specified routine to the calling program.
The routine cannot contain calls to either LBR$DELETE_KEY or
LBR$INSERT_KEY.
match_desc
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Key matching identifier. The match_desc argument is the address
of a string descriptor pointing to a string used to identify
which keys result in calls to the user-supplied routine. Wildcard
characters are allowed in this string. If you omit this argument,
the routine is called for every key in the index. The match_desc
argument is valid only for libraries that have ASCII keys.
9.3 - Description
LBR$GET_INDEX searches through the specified index for a key that
matches the argument match_desc. Each time it finds a match, it
calls the routine specified by the routine_name argument. If you
do not specify the match_desc argument, it calls the routine for
every key in the index.
For example, if you call LBR$GET_INDEX with match_desc equal to
TR* and index_number set to 1 (module name table), then LBR$GET_
INDEX calls routine_name for each module whose name begins with
TR.
9.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_ILLIDXNUM Specified index number not valid.
LBR$_LIBNOTOPN Specified library not open.
LBR$_NULIDX Specified library empty.
| 10 - LBR$GET_RECORD |
The LBR$GET_RECORD routine returns the next data record in the
module associated with a specified key.
Format
LBR$GET_RECORD library_index [,inbufdes] [,outbufdes]
10.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.
10.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 the longword that
contains the index. The library must be open and LBR$LOOKUP_KEY
or LBR$FIND must have been called to find the key associated with
the module whose records you want to read.
inbufdes
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
User buffer to receive the record. The inbufdes argument is
the address of a string descriptor that points to the buffer
that receives the record from LBR$GET_RECORD. This argument is
required when the Librarian subroutine record access is set to
move mode (which is the default). This argument is not used if
the record access mode is set to locate mode. The Description
section contains more information about the locate and move
modes.
outbufdes
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String descriptor that receives the actual length and address of
the data for the record returned. The outbufdes argument is the
address of the string descriptor for the returned record. The
length and address fields of the string descriptor are filled in
by the LBR$GET_RECORD routine. This parameter must be specified
when Librarian subroutine record access is set to locate mode.
This parameter is optional if record access mode is set to move
mode. The Description section contains more information about the
locate and move modes.
10.3 - Description
Before calling LBR$GET_RECORD, you must first call LBR$LOOKUP_
KEY or LBR$FIND to set the internal library read context to the
record's file address (RFA) of the module header of the module
whose records you want to read.
LBR$GET_RECORD uses two record access modes: locate mode and
move mode. Move mode is the default. The LBR$SET_LOCATE and
LBR$SET_MOVE subroutines set these modes. The record access
modes are mutually exclusive; that is, when one is set, the other
is turned off. If move mode is set, LBR$GET_RECORD copies the
record to the user-specified buffer described by inbufdes. If you
have optionally specified the output buffer string descriptor,
outbufdes, the Librarian fills it with the actual length and
address of the data. If locate mode is set, LBR$GET_RECORD
returns the record by way of an internal subroutine buffer,
pointing the outbufdes descriptor to the internal buffer. The
second parameter, inbufdes, is not used when locate mode is set.
10.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_LIBNOTOPN Specified library not open.
LBR$_LKPNOTDON Requested key lookup not done.
RMS$_EOF Error. An attempt has been made to read past
the logical end of the data in the module.
| 11 - LBR$INI_CONTROL |
The LBR$INI_CONTROL routine initializes a control structure,
called a library control index, to identify the library for use
by other LBR routines.
Format
LBR$INI_CONTROL library_index ,func [,type] [,namblk]
11.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.
11.2 - Arguments
library_index
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Library control index returned by the LBR$INI_CONTROL routine.
The library_index argument is the address of a longword that is
to receive the index.
func
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Library function to be performed. The func argument is the
address of the longword that contains the library function.
Valid functions are LBR$C_CREATE, LBR$C_READ, and LBR$C_UPDATE.
Each programming language provides an appropriate mechanism for
accessing these symbols.
type
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Library type. The type argument is the address of the longword
containing the library type. Valid library types include the
following:
o LBR$C_TYP_OBJ (VAX object)
o LBR$C_TYP_SHSTB (VAX shareable image)
o LBR$C_TYP_EOBJ (Alpha object)
o LBR$C_TYP_ESHSTB (Alpha shareable image)
o LBR$C_TYP_MLB (macro)
o LBR$C_TYP_HLP (help)
o LBR$C_TYP_TXT (text)
o LBR$C_TYP_UNK (unknown)
o LBR$C_TYP_NCS (NCS library)
o For user-developed libraries, a type in the range of LBR$C_
TYP_USRLW through LBR$C_TYP_USRHI.
namblk
OpenVMS usage:nam
type: longword (unsigned)
access: read only
mechanism: by reference
OpenVMS RMS name block (NAM). The namblk argument is the address
of a variable-length data structure containing an RMS NAM block.
The LBR$OPEN routine fills in the information in the NAM block
so it can be used later to open the library. If the NAM block
has this file identification in it from previous use, the
LBR$OPEN routine uses the open-by-NAM block option. This argument
is optional and should be used if the library will be opened
many times during a single run of the program. For a detailed
description of RMS NAM blocks, see the OpenVMS Record Management
Services Reference Manual.
11.3 - Description
Except for the LBR$OUTPUT_HELP routine, you must call LBR$INI_
CONTROL before calling any other LBR routine. After you
initialize the library control index, you must open the library
or create a new one using the LBR$OPEN routine. You can then call
other LBR routines that you need. After you finish working with a
library, close it with the LBR$CLOSE routine.
LBR$INI_CONTROL initializes a library by filling the longword
referenced by the library_index argument with the control index
of the library. Upon completion of the call, the index can be
used to refer to the current library in all future routine calls.
Therefore, your program must not alter this value.
You can have up to 16 libraries open simultaneously in your
program.
11.4 - Condition Values Returned
LBR$_NORMAL Library control index initialized
successfully.
LBR$_ILLFUNC Requested function not valid.
LBR$_ILLTYP Specified library type not valid.
LBR$_TOOMNYLIB Error. An attempt was made to allocate more
than 16 control indexes.
| 12 - LBR$INSERT_KEY |
The LBR$INSERT_KEY routine inserts a new key in the current
library index.
Format
LBR$INSERT_KEY library_index ,key_name ,txtrfa
12.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.
12.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 the longword that
contains the index.
key_name
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Name of the new key you are inserting.
If the library uses binary keys, the key_name argument is the
address of an unsigned longword containing the value of the key.
If the library uses ASCII keys, the key_name argument is the
address of a string descriptor of the key with the following
argument characteristics:
Argument
CharacteristicsEntry
OpenVMS char_string
usage
type character string
access read only
mechanism by descriptor
txtrfa
OpenVMS usage:vector_longword_unsigned
type: longword (unsigned)
access: modify
mechanism: by reference
The record's file address (RFA) of the module associated with
the new key you are inserting. The txtrfa argument is the address
of a 2-longword array containing the RFA. You can use the RFA
returned by the first call to LBR$PUT_RECORD.
12.3 - Description
You cannot call LBR$INSERT_KEY within the user-supplied routine
specified in LBR$SEARCH or LBR$GET_INDEX.
12.4 - Condition Values Returned
LBR$_DUPKEY Index already contains the specified key.
LBR$_ILLCTL Specified library control index not valid.
LBR$_INVRFA Specified RFA does not point to valid data.
LBR$_LIBNOTOPN Specified library not open.
LBR$_UPDURTRAV LBR$INSERT_KEY was called by the user-defined
routine specified in LBR$SEARCH or LBR$GET_
INDEX.
| 13 - LBR$LOOKUP_KEY |
The LBR$LOOKUP_KEY routine looks up a key in the library's
current index and prepares to access the data in the module
associated with the key.
Format
LBR$LOOKUP_KEY library_index ,key_name ,txtrfa
13.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.
13.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 the longword that
contains the index.
key_name
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Name of the library key. If the library uses binary keys, the
key_name argument is the address of the unsigned longword value
of the key.
If the library uses ASCII keys, the key_name argument is the
address of a string descriptor for the key with the following
argument characteristics:
Argument
Characteristics Entry
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
txtrfa
OpenVMS usage:vector_longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
The record's file address (RFA) of the library module header.
The txtrfa argument is the address of the 2-longword array that
receives the RFA of the module header.
13.3 - Description
If LBR$LOOKUP_KEY finds the specified key, it initializes
internal tables so you can access the associated data.
This routine returns the RFA (consisting of the virtual block
number (VBN) and the byte offset) to the 2-longword array
referenced by txtrfa. Note that the RFA is only 6 bytes long.
13.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_INVRFA RFA obtained not valid.
LBR$_KEYNOTFND Specified key not found.
LBR$_LIBNOTOPN Specified library not open.
| 14 - 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]
14.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.
14.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).
14.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.
14.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.
| 15 - 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]
15.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.
15.2 - 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_ The process logical name table is searched for
PROCESS 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_ The list of default libraries available is output
LIBLIST 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).
15.3 - 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:
o 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.
o 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.
o 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.
1. If the root library is the main library and you are not
currently examining HELP for a particular topic, the prompt
Topic? is output.
2. 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.
3. If you are currently examining HELP for a particular topic
(and subtopics), a prompt of the form <keyword...>subtopic? is
output.
4. 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 Environment
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 (1,2) Same as above, except that the root
[keyword[ . . . ]] 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.
15.4 - 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.
| 16 - LBR$PUT_END |
The LBR$PUT_END routine marks the end of a sequence of records
written to a library by the LBR$PUT_RECORD routine.
Format
LBR$PUT_END library_index
16.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.
16.2 - Argument
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.
16.3 - Description
Call LBR$PUT_END after you write data records to the library
with the LBR$PUT_RECORD routine. LBR$PUT_END terminates a module
by attaching a 3-byte logical end-of-file record (hexadecimal
77,00,77) to the data.
16.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_LIBNOTOPN Specified library not open.
| 17 - LBR$PUT_HISTORY |
The LBR$PUT_HISTORY routine adds an update history record to the
end of the update history list.
Format
LBR$PUT_HISTORY library_index ,record_desc
17.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.
17.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 the longword that
contains the index.
record_desc
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Library history record. The record_desc argument is the address
of a string descriptor pointing to the record to be added to the
library update history.
17.3 - Description
LBR$PUT_HISTORY writes a new update history record. If the
library already contains the maximum number of history records
(as specified at creation time by CRE$L_LUHMAX; see LBR$OPEN for
details), the oldest history record is deleted before the new
record is added.
17.4 - Condition Values Returned
LBR$_NORMAL Normal exit from the routine.
LBR$_INTRNLERR Internal Librarian error.
LBR$_NOHISTORY No update history. This is an informational
code, not an error code.
LBR$_RECLNG Record length greater than that specified by
LBR$C_MAXRECSIZ. The record was not inserted
or truncated.
| 18 - LBR$PUT_RECORD |
The LBR$PUT_RECORD routine writes a data record beginning at the
next free location in the library.
Format
LBR$PUT_RECORD library_index ,bufdes ,txtrfa
18.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.
18.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 the longword that
contains the index.
bufdes
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Record to be written to the library. The bufdes argument is the
address of a string descriptor pointing to the buffer containing
the output record. The maximum record size for VAX libraries is
symbolically defined as LBR$C_MAXRECSIZ; for Alpha libraries, the
symbolic maximum record size is ELBR$_MAXRECSIZ.
txtrfa
OpenVMS usage:vector_longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Record's file address (RFA) of the module header. The txtrfa
argument is the address of a 2-longword array receiving the
RFA of the newly created module header upon the first call to
LBR$PUT_RECORD.
18.3 - Description
If this is the first call to LBR$PUT_RECORD, this routine first
writes a module header and returns its RFA to the 2-longword
array pointed to by txtrfa. LBR$PUT_RECORD then writes the
supplied data record to the library. On subsequent calls to
LBR$PUT_RECORD, this routine writes the data record beginning
at the next free location in the library (after the previous
record). The last record written for the module should be
followed by a call to LBR$PUT_END.
18.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_LIBNOTOPN Specified library not open.
| 19 - LBR$REPLACE_KEY |
The LBR$REPLACE_KEY routine inserts a key in an index by changing
the pointer associated with an existing key or by inserting a new
key.
Format
LBR$REPLACE_KEY library_index ,key_name ,oldrfa ,newrfa
19.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.
19.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 the longword that
contains the index.
key_name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Library key (for libraries with ASCII keys). The key_name
argument is the address of a string descriptor for the key.
key_name
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Library key (for libraries with binary keys). The key_name
argument is the address of an unsigned longword value for the
key.
oldrfa
OpenVMS usage:vector_longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Old record file address (RFA). The oldrfa argument is the address
of a 2-longword array containing the original RFA (returned by
LBR$LOOKUP_KEY) of the module header associated with the key you
are replacing.
newrfa
OpenVMS usage:vector_longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
New RFA. The newrfa argument is the address of a 2-longword array
containing the RFA (returned by LBR$PUT_RECORD) of the module
header associated with the new key.
19.3 - Description
If LBR$REPLACE_KEY does not find the key in the current index,
it calls the LBR$INSERT_KEY routine to insert the key. If
LBR$REPLACE_KEY does find the key, it modifies the key entry
in the index so that it points to the new module header.
19.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_INVRFA Specified RFA not valid.
LBR$_LIBNOTOPN Specified library not open.
| 20 - LBR$RET_RMSSTV |
The LBR$RET_RMSSTV routine returns the status value of the last
OpenVMS RMS function performed by any LBR subroutine.
Format
LBR$RET_RMSSTV
20.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.
20.2 - Arguments
None.
20.3 - Description
The LBR$RET_RMSSTV routine returns, as the status value, the
status of the last RMS operation performed by the Librarian.
Each programming language provides an appropriate mechanism for
accessing RMS status values.
20.4 - Condition Values Returned
This routine returns any condition values returned by RMS
routines.
| 21 - LBR$SEARCH |
The LBR$SEARCH routine finds index keys that point to specified
data.
Format
LBR$SEARCH library_index ,index_number ,rfa_to_find
,routine_name
21.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.
21.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 the longword that
contains the index.
index_number
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Library index number. The index_number argument is the address of
a longword containing the number of the index you want to search.
rfa_to_find
OpenVMS usage:vector_longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Record's file address (RFA) of the module whose keys you are
searching for. The rfa_to_find argument is the address of
a 2-longword array containing the RFA (returned earlier by
LBR$LOOKUP_KEY or LBR$PUT_RECORD) of the module header.
routine_name
OpenVMS usage:procedure
type: procedure value
access: read only
mechanism: by reference
Name of a user-supplied routine to process the keys. The routine_
name argument is the address of the procedure value of a user-
supplied routine to call for each key entry containing the RFA
(in other words, for each key that points to the same module
header).
This user-supplied routine cannot contain any calls to
LBR$DELETE_KEY or LBR$INSERT_KEY.
21.3 - Description
Use LBR$SEARCH to find index keys that point to the same module
header. Generally, in index number 1 (the module name table),
just one key points to any particular module; thus, you would
probably use this routine only to search library indexes where
more than one key points to a module. For example, you might
call LBR$SEARCH to find all the global symbols associated with an
object module in an object library.
If LBR$SEARCH finds an index key associated with the specified
RFA, it calls a user-supplied routine with two arguments:
o The key argument, which is the address of either of the
following:
- A string descriptor for the key name (libraries with ASCII
key names)
- An unsigned longword for the key value (libraries with
binary keys)
o The RFA argument, which is the address of a 2-longword array
containing the RFA of the module header
The routine must return a value to indicate success or failure.
If the specified routine returns a false value (low bit = 0),
then the index search terminates.
Note that the key found by LBR$SEARCH is valid only during the
call to the user-supplied routine. If you want to use the key
later, you must copy it.
21.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_ILLIDXNUM Specified library index number not valid.
LBR$_KEYNOTFND Librarian did not find any keys with the
specified RFA.
LBR$_LIBNOTOPN Specified library not open.
| 22 - LBR$SET_INDEX |
The LBR$SET_INDEX routine sets the index number to use when
processing libraries that have more than one index.
Format
LBR$SET_INDEX library_index ,index_number
22.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.
22.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 the longword that
contains the index.
index_number
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Index number you want to establish as the current index number.
The index_number argument is the address of the longword that
contains the number of the index you want to establish as the
current index.
22.3 - Description
When you call LBR$INI_CONTROL, the Librarian sets the current
library index to 1 (the module name table, unless the library is
a user-developed library). If you need to process another library
index, you must use LBR$SET_INDEX to change the current library
index.
Note that macro, help, and text libraries contain only one
index; therefore, you do not need to call LBR$SET_INDEX. Object
libraries contain two indexes. If you want to access the global
symbol table, you must call the LBR$SET_INDEX routine to set the
index number. User-developed libraries can contain more than one
index; therefore, you may need to call LBR$SET_INDEX to set the
index number.
Upon successful completion, LBR$SET_INDEX sets the current
library index to the requested index number. LBR routines number
indexes starting with 1.
22.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_ILLIDXNUM Library index number specified not valid.
LBR$_LIBNOTOPN Specified library not open.
| 23 - LBR$SET_LOCATE |
The LBR$SET_LOCATE routine sets the record access of LBR
subroutines to locate mode.
Format
LBR$SET_LOCATE library_index
23.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.
23.2 - Argument
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 the longword that
contains the index.
23.3 - Description
Librarian record access may be set to move mode (the default
set by LBR$SET_MOVE) or locate mode. The setting affects the
operation of the LBR$GET_RECORD routine.
If move mode is set (the default), LBR$GET_RECORD copies the
requested record to the specified user buffer. If locate mode is
set, the record is not copied. Instead, the outbufdes descriptor
is set to reference the internal LBR subroutine buffer that
contains the record.
23.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_LIBNOTOPN Specified library not open.
| 24 - LBR$SET_MODULE |
The LBR$SET_MODULE routine reads, and optionally updates, the
module header associated with a given record's file address
(RFA).
Format
LBR$SET_MODULE library_index ,rfa [,bufdesc] [,buflen]
[,updatedesc]
24.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.
24.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 the longword that
contains the index.
rfa
OpenVMS usage:vector_longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Record's file address (RFA) associated with the module header.
The rfa argument is the address of a 2-longword array containing
the RFA returned by LBR$PUT_RECORD or LBR$LOOKUP_KEY.
bufdesc
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Buffer that receives the module header. The bufdesc argument
is the address of a string descriptor pointing to the buffer
that receives the module header. The buffer must be the size
specified by the symbol MHD$B_USRDAT plus the value of the
CRE$L_UHDMAX create option. The MHD$ and CRE$ symbols are
defined in the modules $MHDDEF and $CREDEF, which are stored
in SYS$LIBRARY:STARLET.MLB.
buflen
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Length of the module header. The buflen argument is the address
of a longword receiving the length of the returned module header.
updatedesc
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Additional information to be stored with the module header.
The updatedesc argument is the address of a string descriptor
pointing to additional data that the Librarian stores with
the module header. If you include this argument, the Librarian
updates the module header with the additional information.
24.3 - Description
If you specify bufdesc, the LBR routine returns the module header
into the buffer. If you specify buflen, the routine also returns
the buffer's length. If you specify updatedesc, the routine
updates the header information.
You define the maximum length of the update information (by
specifying a value for CRE$L_UHDMAX) when you create the library.
The Librarian zero-fills the information if it is less than the
maximum length or truncates it if it exceeds the maximum length.
24.4 - Condition Values Returned
LBR$_HDRTRUNC Buffer supplied to hold the module header was
too small.
LBR$_ILLCTL Specified library control index not valid.
LBR$_ILLOP Error. The updatedesc argument was supplied
and the library was a Version 1.0 library or
the library was opened only for read access.
LBR$_INVRFA Specified RFA does not point to a valid module
header.
LBR$_LIBNOTOPN Specified library not open.
| 25 - LBR$SET_MOVE |
The LBR$SET_MOVE routine sets the record access of LBR
subroutines to move mode.
Format
LBR$SET_MOVE library_index
25.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.
25.2 - Argument
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 the longword that
contains the index.
25.3 - Description
Librarian record access may be set to move mode (the default,
set by LBR$SET_MOVE) or locate mode. The setting affects the
operation of the LBR$GET_RECORD routine. If move mode is set,
LBR$GET_RECORD copies the requested record to the specified user
buffer. For details, see the description of LBR$GET_RECORD.
25.4 - Condition Values Returned
LBR$_ILLCTL Specified library control index not valid.
LBR$_LIBNOTOPN Specified library not open.
|
|
