|
HP OpenVMS Systems Documentation |
|
HP OpenVMS Command Definition, Librarian, and Message Utilities Manual
2.5.4 Retrieving Help TextYou can retrieve help text at DCL level by using the DCL command HELP or, in your program, by calling the appropriate Librarian utility (LBR) routines (as described in the OpenVMS Utility Routines Manual). By default, the HELP command retrieves help text from the system help library SYS$HELP:HELPLIB.HLB and from user help libraries associated with the logical names HLP$LIBRARY, HLP$LIBRARY_1, HLP$LIBRARY_2, and so forth. Using the /LIBRARY qualifier with the HELP command lets you search a library other than the default libraries.For more information, see the description of the HELP command in the HP OpenVMS DCL Dictionary. When you retrieve help text, you specify the key-1 topic followed by any subtopics that contain appropriate help information. LIBRARIAN returns the help text associated with the key path you specify. For example, the help text for the LIBRARY command is stored in the default system help library; thus, to retrieve the LIBRARY command's key-1 help information, you would enter the DCL command HELP LIBRARY. LIBRARIAN would return the associated help text, followed by the message "Additional information available:" and a list of all the key-2 names in the module. In this case, LIBRARIAN also returns a list of all the qualifiers specified in the qualifier lines.Example 2-2 displays the text returned by the HELP LIBRARY command.
Note that you cannot retrieve the key-2 level "Parameters" by entering HELP PARAMETERS. LIBRARIAN searches for a subkey only after finding the higher level keys. In other words, if you want to retrieve key-3 text, you have to specify the key-1 and key-2 lines that form a path to the key-3 line. Also note that you can provide information about a qualifier that has more than one form by associating two or more qualifier lines with the same help text. That is, the text associated with the qualifiers follows the two or more qualifier lines. For example:
When LIBRARIAN successfully searches the key path to the requested key, it displays all the key names in that path, followed by the help text associated with the last specified key. For example:
If you try to retrieve help text for a key that is not in the module name table, LIBRARIAN issues a message. For example:
This message is followed by a list of all the module names in the module name table. If you have correctly specified the key-1 line but have requested a subkey that does not exist, LIBRARIAN issues a message. For example:
The message includes a list of all the subkeys associated with the last key
that was specified correctly.
You can save disk space by using the Librarian utility to reduce data files. To save disk space, create a library, copy the data files you want to reduce into the library, and then use the LIBRARY/DATA=REDUCE command to reduce the size of library. When you subsequently want to use the files in their expanded form, you simply extract the data files and they will be expanded automatically. Because data expansion takes time, leave frequently used libraries in their expanded format to increase access performance. Large, infrequently accessed files are good candidates for this method when you do not want to write a program that uses the callable interface to reduce and expand data files.
See the description of the /DATA qualifier
for more information.
Programs can call Librarian utility (LBR) routines to do the following:
For VAX and Alpha systems, the OpenVMS Utility Routines Manual describes
in detail each LBR routine. For information about LBR routines on I64 systems,
see the HP OpenVMS Version 8.2 New Features and Documentation Overview.
The Librarian utility (LIBRARIAN) gives you easy access to libraries. Libraries are files in which you can store frequently used modules of code or text. FormatLIBRARY library-file-spec [input-file-spec[,...]] Command ParametersUsage Summary The DCL command LIBRARY invokes the Librarian utility.After the operations specified by LIBRARY have completed, the Librarian utility exits. If you use the /LIST qualifier to request information about a library, the
output is directed to the file specification associated with /LIST or, if you
do not supply a file specification, to SYS$OUTPUT.
When using LIBRARY, you can specify qualifiers that request more than one function in a single command, with some restrictions. Generally, you cannot specify multiple qualifiers that request incompatible functions. The qualifiers that perform library functions, related qualifiers, and qualifier incompatibilities are summarized in Table 2-2.
1The /CREATE, /INSERT, and /REPLACE qualifiers are compatible; however, if you specify more than one, /CREATE takes precedence over /INSERT, and /INSERT takes precedence over /REPLACE. The related qualifiers for /CREATE are applicable only if you enter one or more input files. 2This qualifier applies only to macro libraries. 3This qualifier applies only to object libraries and shareable image libraries. 4This positional qualifier applies only to text libraries. Note that all the qualifiers are command qualifiers except for /MODULE, which
is a positional qualifier that modifies the input file specification parameter.
Directs LIBRARIAN to work with an OpenVMS Alpha object library when used with the /OBJECT qualifier or to work with an OpenVMS Alpha shareable image library when used with the /SHARE qualifier. When used with the /CREATE qualifier, LIBRARIAN creates an OpenVMS Alpha library of either an object or shareable image type depending whether /OBJECT or /SHARE is specified. Format/ALPHA DescriptionThe /ALPHA qualifier is used to create and manipulate OpenVMS Alpha object and shareable image libraries. Because the formats of macro, help, and text libraries are identical on both system architectures, using the /ALPHA qualifier with the /MACRO, /TEXT, and /HELP qualifiers has no effect.
|
| #1 |
|---|
$ LIBRARY/ALPHA/CREATE TESTLIB ERRMSG.OBJ,STARTUP.OBJ |
This LIBRARY command creates an OpenVMS Alpha object library named TESTLIB.OLB and places the files ERRMSG.OBJ and STARTUP.OBJ as modules in the library.
| #2 |
|---|
$ LIBRARY/ALPHA/SHARE/CREATE SHARELIB.OLB |
This LIBRARY command creates an OpenVMS Alpha shareable image library called SHARELIB.OLB.
Specifies that only those modules inserted earlier than a particular time be listed.
/BEFORE [=time]
time
Limits the modules to be listed to those inserted in the library before a specified time.You can specify an absolute time or a combination of absolute and delta times. For details about specifying times, see the HP OpenVMS DCL Dictionary.
This qualifier is used with the /LIST qualifier. If you omit the /BEFORE qualifier, you obtain all the modules regardless of the dates. If you specify /BEFORE without a date or time, the default is to provide the modules inserted before today.
$ LIBRARY/LIST/BEFORE=15-APR-:15 MATHLIB |
This LIBRARY command lists the modules that were inserted into MATHLIB.OLB before 3 p.m. on April 15.
Recovers space that was occupied by modules deleted from the library. When you specify /COMPRESS, LIBRARY creates a new library. You can use options to the /COMPRESS qualifier to make some specifications in the new version of the library different from the original library.
/COMPRESS [=(option[,...])]
option
An option that alters the size or format of the library, overriding the values specified when the library was created. Options are listed in the Description section.
When you specify /COMPRESS, LIBRARY creates a new library. By default, the new library is created in your current default directory and has the same file name as the existing library and a file type that is the default for the type of library created. You can use the /OUTPUT qualifier to specify an alternate file specification for the compressed library.Specify one or more of the following options to alter the size or format of the library, overriding the values specified when the library was created (for the default values, see the description of the /CREATE qualifier):
BLOCKS:n Specifies the number of 512-byte blocks to be allocated for the library. By default, LIBRARY allocates 100 blocks for a new library. GLOBALS:n Specifies the maximum number of symbols the library can contain initially. By default, LIBRARY sets a maximum of 512 symbols for an object module library. (Macro, help, and text libraries do not have a symbol directory; therefore, the maximum for these libraries defaults to 0.) HISTORY:n Specifies the maximum number of library update history records that the library is to maintain. The maximum number of library update records you can specify is 32,767. The default is 20. KEEP Copies library update history records and any additional user data in the module header to the compressed library. KEYSIZE:n Specifies the maximum name length of modules or symbols. On VAX systems, LIBRARY assigns default name lengths of 15 characters for help modules, 31 characters for modules in object or macro libraries, and 39 characters for modules in text or shareable image libraries. The maximum length you can specify for these names is 128 characters.
Also on VAX systems, when you specify a key size value, remember that the MACRO compiler and the linker do not accept module names or global symbol names in excess of 31 characters.
On Alpha systems, LIBRARY assigns default name lengths of 15 characters for help modules, 31 characters for modules in macro libraries, 39 characters for modules in text libraries, and 128 characters for modules in object or shareable image libraries. The maximum length you can specify for these names is 128 characters.
Also on Alpha systems, when you specify a key size value, remember that the MACRO compiler does not accept module names and global symbol names in excess of 31 characters, and the linker does not accept module names in excess of 31 characters or global symbol names in excess of 64 characters.
On I64 systems, LIBRARY assigns default name lengths of 15 characters for help modules, 31 characters for modules in macro libraries, 39 characters for modules in text libraries, and 1024 characters for modules in object or shareable image libraries. The maximum length you can specify for these names is 1024 characters.
MODULES:n Specifies the maximum number of modules the library can initially contain. By default, LIBRARY sets an initial maximum of 128 modules for all library types. A library's size can grow past its initial allocation. However, for optimum performance, it is best to allocate the maximum number of modules you expect to use.
VERSION:n On VAX systems, specifies that the library is to be stored in VMS Version 2.0 library format, if n is 2; or VMS Version 3.0 library format, if n is 3. On Alpha and I64 systems, this parameter is ignored. If you specify more than one option, separate them with commas and enclose the list in parentheses.
$ LIBRARY/COMPRESS=(KEYSIZE:40,MODULES:80)/TEXT SOURCE |
This LIBRARY command creates a new version of the text library SOURCE.TLB. Space left after modules were deleted from the old version is recovered in the new version. The new version can contain up to 80 modules; the maximum length of module names in the new version is 40.
| Previous | Next | Contents | Index |