 |
HP OpenVMS Utility Routines Manual
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]
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 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:
- The first argument is the address of a string descriptor for the
output line.
- 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_NOHLPTXT
|
Specified help text cannot be found.
|
|
HLP$M_KEYNAMLIN
|
Text contains key names of the printed text.
|
|
HLP$M_OTHERINFO
|
Text is part of the information provided on 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.
- 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).
- 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.
|
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.
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.
|
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
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 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.
Description
This routine retrieves the library update history records written by
the routine LBR$PUT_HISTORY.
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.
|
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]
[, flags]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Longword condition value. Most utility routines return a condition
value. 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 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 on OpenVMS Alpha; and
passes three arguments to the routine on OpenVMS Integrity servers:
- 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.
- The record 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 key's type whose bits are as follows:
| Flag Bits |
Description |
|
LBR$M_SYM_WEAK = 1
|
UNIX-style weak symbol attributes
|
|
LBR$M_SYM_GROUP = 2
|
Group symbol attribute
|
This parameter is passed only on OpenVMS Integrity servers.
The user routine must return a value to indicate success or failure. If
the user 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.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
If present and non-zero, this argument specifies the type, or all
types, of the key provided. The flag bits are:
| Flag Bits |
Description |
|
LBR$M_SYM_WEAK = 0x1
|
UNIX-style weak symbol attribute
|
|
LBR$M_SYM_GROUP = 0x2
|
Group symbol attribute
|
|
LBR$M_SYM_ALL = 0x80000000
|
All symbols
|
The user routine will be provided the key's type through an additional
third parameter.
Description
LBR$GET_INDEX searches through the specified index for keys that match
the match_desc argument. Each time it finds a match,
it calls the user routine specified by the
routine_name argument. If you do not specify the
match_desc argument, LBR$GET_INDEX calls the user
routine for every key in the index.
For example, if you call LBR$GET_INDEX on an object library 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.
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.
|
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]
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 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.
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.
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.
|
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]
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: |
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:
- LBR$C_TYP_EOBJ (Alpha object)
- LBR$C_TYP_ESHSTB (Alpha shareable image)
- LBR$C_TYP_MLB (macro)
- LBR$C_TYP_HLP (help)
- LBR$C_TYP_TXT (text)
- LBR$C_TYP_UNK (unknown)
- LBR$C_TYP_NCS (NCS library)
- 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.
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.
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.
|
|
