Document revision date: 30 March 2001

The LBR$INSERT_KEY routine inserts a new key in the current library index.

Format

LBR$INSERT_KEY library_index ,key_name ,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.

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

Description

You cannot call LBR$INSERT_KEY within the user-supplied routine specified in LBR$SEARCH or LBR$GET_INDEX.

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.

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

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.

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.

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.

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.

The LBR$OPEN routine opens an existing library or creates a new one.

Format

LBR$OPEN library_index [,fns] [,create_options] [,dns] [,rlfna] [,rns] [,rnslen]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

library_index

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of a longword containing the index.

fns

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

File specification of the library. The fns argument is the address of a string descriptor pointing to the file specification. Unless the OpenVMS RMS NAM block address was previously supplied in the LBR$INI_CONTROL routine and contained a file specification, this argument must be included. Otherwise, the Librarian returns an error (LBR$_NOFILNAM).

create_options

OpenVMS usage:	vector_longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Library characteristics. The create_options argument is the address of an array of 20 longwords that define the characteristics of the library you are creating. If you are creating a library with LBR$C_CREATE, you must include the create_options argument. The following table shows the entries that the array must contain. Each programming language provides an appropriate mechanism for accessing the listed symbols.

Offset in Longwords	Symbolic Name	Contents
0	CRE$L_TYPE	Library type:
	LBR$C_TYP_UNK (0)	Unknown/unspecified
	LBR$C_TYP_OBJ (1)	VAX object
	LBR$C_TYP_MLB (2)	Macro
	LBR$C_TYP_HLP (3)	Help
	LBR$C_TYP_TXT (4)	Text
	LBR$C_TYP_SHSTB (5)	VAX shareable image
	LBR$C_TYP_NCS (6)	NCS
	LBR$C_TYP_EOBJ (7)	Alpha object
	LBR$C_TYP_ESHSTB (8)	Alpha shareable image
	(9--127)	Reserved by Compaq
	LBR$C_TYP_USRLW (128)	User library types --- low end of range
	LBR$C_TYP_USRHI (255)	User library types --- high end of range
1	CRE$L_KEYLEN	Maximum length of ASCII keys or, if 0, indicates 32-bit unsigned keys (binary keys)
2	CRE$L_ALLOC	Initial library file allocation
3	CRE$L_IDXMAX	Number of library indexes (maximum of eight)
4	CRE$L_UHDMAX	Number of additional bytes to reserve in module header
5	CRE$L_ENTALL	Number of index entries to preallocate
6	CRE$L_LUHMAX	Maximum number of library update history records to maintain
7	CRE$L_VERTYP	Format of library to create:
	CRE$C_VMSV2	VMS Version 2.0
	CRE$C_VMSV3	VMS Version 3.0
8	CRE$L_IDXOPT	Index key casing option:
	CRE$C_HLPCASING	Treat character case as it is for help libraries
	CRE$C_OBJCASING	Treat character case as it is for object libraries
	CRE$C_MACTXTCAS	Treat character case as it is for macro and text libraries
9--19		Reserved by Compaq

The input of uppercase and lowercase characters is treated differently for help, object, macro, and text libraries. For details, see the OpenVMS Command Definition, Librarian, and Message Utilities Manual.

dns

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Default file specification. The dns argument is the address of the string descriptor that points to the default file specification. See the OpenVMS Record Management Services Reference Manual for details about how defaults are processed.

rlfna

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Related file name. The rlfna argument is the address of an RMS NAM block pointing to the related file name. You must specify rlfna for related file name processing to occur. If a related file name is specified, only the file name, type, and version fields of the NAM block are used for related name block processing. The device and directory fields are not used. See the OpenVMS Record Management Services Reference Manual for details on processing related file names.

rns

OpenVMS usage:	char_string
type:	character string
access:	write only
mechanism:	by descriptor

Resultant file specification returned. The rns argument is the address of a string descriptor pointing to a buffer that is to receive the resultant file specification string. If an error occurs during an attempt to open the library, the expanded name string is returned instead.

rnslen

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	write only
mechanism:	by reference

Length of the resultant or expanded file name. The rnslen argument is the address of a longword receiving the length of the resultant file specification string (or the length of the expanded name string if there was an error in opening the library).

Description

You can call this routine only after you call LBR$INI_CONTROL and before you call any other LBR routine except LBR$OUTPUT_HELP.

When the library is successfully opened, the LBR routine reads the library header into memory and sets the default index to 1.

If the library cannot be opened because it is already open for a write operation, LBR$OPEN retries the open operation every second for a maximum of 30 seconds before returning the RMS error, RMS$_FLK, to the caller.

Condition Values Returned

LBR$_ERRCLOSE	Error. When the library was last modified while opened for write access, the write operation was interrupted. This left the library in an inconsistent state.
LBR$_ILLCREOPT	Requested create options not valid or not supplied.
LBR$_ILLCTL	Specified library control index not valid.
LBR$_ILLFMT	Specified library format not valid.
LBR$_ILLFUNC	Specified library function not valid.
LBR$_LIBOPN	Specified library already open.
LBR$_NOFILNAM	Error. The fns argument was not supplied or the RMS NAM block was not filled in.
LBR$_OLDLIBRARY	Success. The specified library has been opened; the library was created with an old library format.
LBR$_OLDMISMCH	Requested library function conflicts with old library type specified.
LBR$_TYPMISMCH	Library type does not match the requested type.

The LBR$OUTPUT_HELP routine outputs help text to a user-supplied output routine. The text is obtained from an explicitly named help library or, optionally, from user-specified default help libraries. An optional prompting mode is available that enables LBR$OUTPUT_HELP to interact with you and continue to provide help information after the initial help request has been satisfied.

Format

LBR$OUTPUT_HELP output_routine [,output_width] [,line_desc] [,library_name] [,flags] [,input_routine]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

output_routine

OpenVMS usage:	procedure
type:	procedure value
access:	write only
mechanism:	by reference

Name of a routine that writes help text a line at a time. The output_routine argument is the address of the procedure value of the routine to call. You should specify either the address of LIB$PUT_OUTPUT or a routine of your own that has the same calling format as LIB$PUT_OUTPUT.

output_width

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

Width of the help-text line to be passed to the user-supplied output routine. The output_width argument is the address of a longword containing the width of the text line to be passed to the user-supplied output routine. If you omit output_width or specify it as 0, the default output width is 80 characters per line.

line_desc

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Contents of the help request line. The line_desc argument is the address of a string descriptor pointing to a character string containing one or more help keys defining the help requested, for example, the HELP command line minus the HELP command and HELP command qualifiers. The default is a string descriptor for an empty string.

library_name

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Name of the main library. The library_name argument is the address of a string descriptor pointing to the main library file specification string. The default is a null string, which means you should use the default help libraries. If you omit the device and directory specifications, the default is SYS$HELP. The default file type is .HLB.

flags

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Flags specifying help output options. Each programming language provides an appropriate mechanism for accessing these flags. The flags argument is the address of an unsigned longword that contains the following flags, when set:

Flag	Description
HLP$M_PROMPT	Interactive help prompting is in effect.
HLP$M_PROCESS	The process logical name table is searched for default help libraries.
HLP$M_GROUP	The group logical name table is searched for group default help libraries.
HLP$M_SYSTEM	The system logical name table is searched for system default help libraries.
HLP$M_LIBLIST	The list of default libraries available is output with the list of topics available.
HLP$M_HELP	The list of topics available in a help library is preceded by the major portion of the text on help.

If you omit this longword, the default is for prompting and all default library searching to be enabled, but no library list is generated and no help text precedes the list of topics.

input_routine

OpenVMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by reference

Routine used for prompting. The input_routine argument is the address of the procedure value of the prompting routine. You should specify either the address of LIB$GET_INPUT or a routine of your own that has the same calling format as LIB$GET_INPUT. This argument must be supplied when the HELP command is run in prompting mode (that is, HLP$M_PROMPT is set or defaulted).

Description

The LBR$OUTPUT_HELP routine provides a simple, one-call method to initiate an interactive help session. Help library bookkeeping functions, such as LBR$INI_CONTROL and LBR$OPEN, are handled internally. You should not call LBR$INI_CONTROL or LBR$OPEN before you issue a call to LBR$OUTPUT_HELP.

LBR$OUTPUT_HELP accepts help keys in the same format as LBR$GET_HELP, with the following qualifications:

• If the keyword HELP is supplied, help text on HELP is output, followed by a list of HELP subtopics available.
  If no help keys are provided or if the line_desc argument is 0, a list of topics available in the root library is output.
• If the line_desc argument contains a list of help keys, then each key must be separated from its predecessor by a slash (/) or by one or more spaces.
• The first key can specify a library to replace the main library as the root library (the first library searched) in which LBR$OUTPUT_HELP searches for help. A key used for this purpose must have the form <@filespec>, where filespec is subject to the same restrictions as the library_name argument. If the specified library is an enabled user-defined default library, then filespec can be abbreviated as any unique substring of that default library's logical name translation.

In default library searches, you can define one or more default libraries for LBR$OUTPUT_HELP to search for help information not contained in the root library. Do this by equating logical names (HLP$LIBRARY, HLP$LIBRARY_1,...,HLP$LIBRARY_999) to the file specifications of the default help libraries. You can define these logical names in the process, group, or system logical name table.

If default library searching is enabled by the flags argument, LBR$OUTPUT_HELP uses those flags to determine which logical name tables are enabled and then automatically searches any user default libraries that have been defined in those logical name tables. The library search order proceeds as follows: root library, main library (if specified and different from the root library), process libraries (if enabled), group libraries (if enabled), system libraries (if enabled). If the requested help information is not found in any of these libraries, LBR$OUTPUT_HELP returns to the root library and issues a "help not found" message.

---

Previous

Next

Contents

Index

	privacy and legal statement
4493PRO_024.HTML