Document revision date: 19 July 1999

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 the files. When you subsequently want to use the files in their expanded form, use the LIBRARY/DATA=EXPAND command and extract the expanded data files.

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 records

The OpenVMS Utility Routines Manual describes in detail each LBR routine.

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 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 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 one, the LIBRARY command assumes a default type of .OLB, indicating an object library. You can change the default library file type by specifying the appropriate qualifier, as follows:

Qualifier	Default 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 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-1.

Table 2-1 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

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.

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 that you cannot have both OpenVMS Alpha and OpenVMS VAX object modules in one object library, nor can you one 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 SHARLIB
      

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 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 global symbols the library can contain initially. By default, LIBRARY sets a maximum of 512 global symbols for an object module library. (Macro, help, and text libraries do not have a global 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 global symbols. The maximum length you can specify for these names is 128 characters. 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. 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. 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.
MODULES:n	Specifies the maximum number of modules the library can 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	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.

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.

Requests the DCL command LIBRARY to create a new library. When you specify /CREATE, you can optionally specify a file or a list of files that contains modules to be placed in the library.

Format

/CREATE [=(option[,...])]

option

An option that overrides the system defaults to control the size or format of the library. Options are listed in the Description section.

Description

By default, the /CREATE qualifier creates an object module library. To indicate that the library is a macro, help, text, or shareable image library, specify /MACRO, /HELP, /TEXT, or /SHARE.

On OpenVMS VAX systems, the /CREATE qualifier creates a VAX library by default when used to create object and shareable image libraries. Note that you cannot have VAX modules and Alpha modules in the same library. For more information, see the description of the /VAX qualifier.

On OpenVMS Alpha systems, the /CREATE qualifier creates an Alpha library by default when used to create object and shareable image libraries. Note that you cannot have Alpha modules and VAX modules in the same library. For more information, see the description of the /ALPHA qualifier.

Specify one or more of the following options to override the system defaults:

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.
CASE_SENSITIVE: [YES/NO]	Specifies whether key operations on macro or text libraries are case sensitive. The default, CASE_SENSITIVE:NO, causes all module names to be converted to uppercase. CASE_SENSITIVE:YES causes current and subsequent key operations to behave as they do for object libraries. See Section 2.3 for a full description. This option is valid only for macro and text libraries.
GLOBALS:n	Specifies the maximum number of global symbols the library can contain initially. By default, LIBRARY sets a maximum of 512 global symbols for an object module library. (Macro, help, and text libraries do not have a global 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.
KEYSIZE:n	Specifies the maximum name length of modules or global symbols. The maximum length you can specify for these names is 128 characters. 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. 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 symbol table libraries. 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.
MODULES:n	Specifies the maximum number of modules the library can 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	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.

If you specify more than one option, separate them with commas and enclose the list in parentheses.

Examples

$ LIBRARY/CREATE TESTLIB ERRMSG,STARTUP
      

This LIBRARY command creates an object module library named TESTLIB.OLB and places the files ERRMSG.OBJ and STARTUP.OBJ as modules in the library.

$ LIBRARY/MACRO/CREATE=(BLOCKS:40,MODULES:100) MYMAC TEMP
$ MACRO MYMAC/LIBRARY,CYGNUS/OBJECT
      

This LIBRARY command creates a macro library named MYMAC.MLB from the macros in the file TEMP.MAR. The new library has room for 100 modules in a 40-block file. If the input file contains multiple macros, each macro is entered in the new library.

	privacy and legal statement
6100PRO_006.HTML