| Previous | Contents | Index |
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.
LBR$OUTPUT_HELP output_routine [,output_width] [,line_desc] [,library_name] [,flags] [,input_routine]
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.
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).
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.
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.
- If the root library is the main library and you are not currently examining HELP for a particular topic, the prompt Topic? is output.
- 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.
- If you are currently examining HELP for a particular topic (and subtopics), a prompt of the form <keyword...>subtopic? is output.
- 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 Environment1 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 [keyword[...]] (1,2) Same as above, except that the root 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.
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.
The LBR$PUT_END routine marks the end of a sequence of records written to a library by the LBR$PUT_RECORD routine.
LBR$PUT_END library_index
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.
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.
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.
LBR$_ILLCTL Specified library control index not valid. LBR$_LIBNOTOPN Specified library not open.
The LBR$PUT_HISTORY routine adds an update history record to the end of the update history list.
LBR$PUT_HISTORY library_index ,record_desc
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.
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.
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.
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.
The LBR$PUT_MODULE routine puts an entire module, with the module's record file address (RFA), from memory space into the current library.
LBR$PUT_MODULE library_index, mod_addr, mod_len, txtrfa
library_index
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
Library control index returned by the LBR$INI_CONTROL library routine. The library_index argument is the address of the longword that contains the index.mod_addr
OpenVMS usage: address type: quadword address access: read only mechanism: by 32-bit or 64-bit reference
The address from which the Library service obtains the 64-bit address of where the module is mapped in memory. The mod_addr argument is the 32- or 64-bit virtual address of a naturally aligned quadword containing the virtual address location of the module to write to the library.mod_len
OpenVMS usage: byte_count type: quadword (unsigned) access: read only mechanism: by 32- or 64-bit reference
The 64-bit virtual address of a naturally aligned quadword containing the length of the module that the Library service is to write into the library.txtrfa
OpenVMS usage: vector_longword_unsigned type: longword (unsigned) access: write only mechanism: by reference
The module's record file address (RFA) of the library module header. The txtrfa argument is the address of the 2-longword array receiving the RFA of the newly created module header.
The LBR$PUT_MODULE routine puts an entire module, with the module's record file address (RFA), from memory space into the current library. LBR$PUT_END is not required when you write an entire module to the current library.
The LBR$PUT_RECORD routine writes a data record beginning at the next free location in the library.
LBR$PUT_RECORD library_index ,bufdes ,txtrfa [, mod_size]
OpenVMS usage: cond_value type: longword (unsigned) access: write only
Longword condition value. Most utility routines return a condition value. Condition values that this routine can return are listed under Condition Values Returned.
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 I64 and 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.mod_size
OpenVMS usage: byte_count type: longword (unsigned) access: read only mechanism: by value
The value from mod_size is read on the first call to this routine and ignored otherwise. The value specifies the size of the module to be entered so that contiguous space is allocated within the library for that module. This argument is ignored for non-ELF object libraries and for data-reduced ELF object libraries. The LBR$PUT_END routine is still required to terminate the byte stream and close off the module.
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.
LBR$_ILLCTL Specified library control index not valid. LBR$_LIBNOTOPN Specified library not open.
| Previous | Next | Contents | Index |