HP OpenVMS systems documentation

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

Example 2-2 HELP LIBRARY Display

LIBRARY Invokes the Librarian utility to create, modify, or describe an object, macro, help, text, or shareable image library. Format: LIBRARY library-file-spec [input-file-spec[,...]] Additional information available: Command_Parameters /ALPHA /BEFORE /COMPRESS /CREATE /CROSS_REFERENCE /DATA /DELETE /EXTRACT /FULL /GLOBALS /HELP /HISTORY /INSERT /LIST /LOG /MACRO /MODULE /NAMES /OBJECT /ONLY /OUTPUT /REMOVE /REPLACE /SELECTIVE_SEARCH /SHARE /SINCE /SQUEEZE /TEXT /VAX /WIDTH

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:

$ HELP LIBRARY/GLOBALS

LIBRARY /GLOBALS /GLOBALS /NOGLOBALS Controls, for object module libraries, whether the names of global symbols in modules being inserted in the library are included in the global symbol table. By default, the LIBRARY command places all global symbol names in the global symbol table. Use /NOGLOBALS if you do not want the global symbol names included in the global symbol table.

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:

$ HELP LIBRARY/HELP LIBRARY /HELP Indicates that the library is a help library. When you specify the /HELP qualifier, the library file type defaults to .HLB and the input file type defaults to .HLP.

If you try to retrieve help text for a key that is not in the module name table, LIBRARIAN issues a message. For example:

$ HELP FIRE Sorry, no documentation on FIRE Additional information available:

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:

$ HELP LIBRARY/FIRE Sorry, no documentation on LIBRARY/FIRE Additional information available: Parameters Command_Qualifiers /BEFORE /COMPRESS . . .

The message includes a list of all the subkeys associated with the last key that was specified correctly.

2.6 Using the Librarian Utility to Save Disk Space

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.

2.7 Librarian Utility (LBR) Routines

Programs can call Librarian utility (LBR) routines to do the following:

• Initialize a library
• Open a library
• Look up a key in a library
• Insert a new key in a library
• Return the names of the keys
• Delete a key and its associated data
• Read and write information

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.

LIBRARIAN Usage Summary

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.

You can use the DCL command LIBRARY (or the LBR routines) to create a library, maintain the modules in a library, or display information about a library and its modules.

Note that libraries are files, so you can use DCL commands to manipulate libraries in their entirety; for example, you can use the DELETE, COPY, and RENAME commands to delete, copy, and rename libraries. For more information about file maintenance, see the HP OpenVMS DCL Dictionary.

Format

LIBRARY library-file-spec [input-file-spec[,...]]

Command Parameters

library-file-spec

The name of the library you want to create or modify. This parameter is required. If you do not specify a library file, you are prompted for one, as follows:

_Library:

No wildcard characters are allowed in the library file specification.

If the file specification does not include a file type and if the command string does not indicate a library type, the LIBRARY command assumes an object library type and a default file type of .OLB. You can change the default library file type by specifying the appropriate qualifier, as follows:

Qualifier	Default Library File Type
/HELP	.HLB
/MACRO	.MLB
/OBJECT	.OLB
/TEXT	.TLB
/SHARE	.OLB

input-file-spec[,...]

The names of one or more files that contain modules you want to insert into the specified library. If you specify more than one input file, separate the file specifications with commas.

The input file specification is required when you specify /REPLACE, which is the LIBRARY command's default operation, or /INSERT, which is an optional qualifier. If you do not specify an input file when you use these qualifiers, you are prompted for it, as follows:

_File:

When you use the /CREATE qualifier to create a new library, the input file specification is optional. If you include an input file specification with the /CREATE qualifier, LIBRARY first creates a new library and then inserts the contents of the input files into the library.

Note that the /EXTRACT qualifier does not accept an input file specification.

If any file specification does not include a file type and if the command string does not indicate one, LIBRARY assumes a default file type of .OBJ, designating an object file. You can control the default file type by specifying the appropriate qualifier, as follows.

Qualifier	Default Input File Type
/HELP	.HLP
/MACRO	.MAR
/OBJECT	.OBJ
/TEXT	.TXT
/SHARE	.EXE

Note also that the file type you specify with the library file specification determines the default file type of the input file specification, provided that you do not specify the /CREATE qualifier. For example, if the library file type is .HLB, .MLB, .OLB, or .TLB, the input file type default will be .HLP, .MAR, .OBJ, or .TXT, respectively. (If you specify the /CREATE qualifier and you are not creating an object library, you must use the appropriate file type qualifier.)

Wildcard characters are allowed in the input file specifications.

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.

LIBRARIAN Qualifiers

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.

Table 2-2 LIBRARY Command Qualifier Compatibilities

Qualifier	Related Qualifiers	Incompatible Qualifiers
/COMPRESS	/OUTPUT	/CREATE, /EXTRACT
/CREATE 1	/SQUEEZE, 2 /GLOBALS, 3 /SELECTIVE_SEARCH 3	/COMPRESS, /EXTRACT
/CROSS_REFERENCE	/ONLY	/EXTRACT, /LIST
/DATA	/COMPRESS	---
/DELETE	---	/EXTRACT
/EXTRACT	/OUTPUT	/COMPRESS, /CREATE, /DELETE, /INSERT, /LIST, /REMOVE, /REPLACE
/INSERT	/SQUEEZE, 2 /GLOBALS, 3 /SELECTIVE_SEARCH 3	/EXTRACT
/LIST	/FULL, /NAMES, 3 /ONLY, /HISTORY, /BEFORE, /SINCE	/EXTRACT, /CROSS_REFERENCE
/REMOVE 3	---	/EXTRACT
/REPLACE	/SQUEEZE, 2 /GLOBALS, 3 /SELECTIVE_SEARCH 3	/EXTRACT
/MODULE 4	/TEXT	/EXTRACT, /DELETE, /REMOVE

Note that all the qualifiers are command qualifiers except for /MODULE, which is a positional qualifier that modifies the input file specification parameter.

/ALPHA (VAX and Alpha only)

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.

The default is /ALPHA on OpenVMS Alpha systems and /VAX on OpenVMS VAX systems. The OpenVMS I64 Librarian does not accept this qualifier because the I64 Librarian works exclusively with I64 libraries.

Format

/ALPHA

Description

The /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.

Note You cannot have both OpenVMS Alpha and OpenVMS VAX object modules in one object library, nor can you have OpenVMS Alpha and OpenVMS VAX shareable images in the same shareable image library.

Examples

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

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

Format

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

Description

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.

Example

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

Format

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

Description

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.

Example

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