HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

The LBR$DELETE_KEY routine deletes a key from a library index.

Format

LBR$DELETE_KEY library_index ,key_name

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.

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

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.

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.

The LBR$FIND routine sets the current internal read context for the library to the library module specified.

Format

LBR$FIND library_index ,txtrfa

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.

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.

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.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_INVRFA	Specified RFA not valid.
LBR$_LIBNOTOPN	Specified library not open.

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

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.

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.

Description

LBR$FLUSH cannot be called from other LBR routines that reference cache addresses or by routines called by LBR routines.

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.

The LBR$GET_HEADER routine returns information from the library's header to the caller.

Format

LBR$GET_HEADER library_index ,retary

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.

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_FREIDXBLK	Number of free preallocated index blocks
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_MAXLUHREC	Maximum number of library update history records maintained
30	LHI$L_NUMLUHREC	Number of library update history records in history
31	LHI$L_LIBSTATUS	Library status (false if there was an error closing the library)
32-128		Reserved by Compaq

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).

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_LIBNOTOPN	Specified library not open.

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:

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_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.
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.

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.