Document revision date: 19 July 1999

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.

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.

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]

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.

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 (see Section 11.1.2.3).

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:

• 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'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.

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.

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.

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.

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_OBJ (VAX object)
• LBR$C_TYP_SHSTB (VAX shareable image)
• 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.

	privacy and legal statement
4493PRO_023.HTML