HP OpenVMS Systems Documentation

HP OpenVMS Command Definition, Librarian, and Message Utilities Manual

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 (VAX and Alpha only) 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.

On OpenVMS I64 systems, the /CREATE qualifier creates an ELF library when used to create object and shareable image libraries.

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 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.
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 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. 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 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 I-64 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 symbol table 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 OpenVMS 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.

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.

Requests a cross-reference listing of an object library.

Format

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

option

An option that produces a cross-reference listing that is not limited to only symbols by name and symbols by value. Options are listed in the Description section.

Description

If you omit this qualifier, cross-reference listings are not provided. If you specify /CROSS_REFERENCE without specifying an option, you get cross-reference listings that contain symbols by name and symbols by value. By default, the listing file is created in your current default directory and has the same file name as the library and a file type of .LIS. You can use the /OUTPUT qualifier to specify an alternate file specification for the listing file.

You can specify one or more of the following options:

ALL	All types of cross-references
MODULE	Cross-reference listing of both the symbol references in the module and the symbol definitions
NONE	No cross-reference listing
SYMBOL	Cross-reference listing by symbol name
VALUE	Cross-reference listing of symbols by value

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

Example

$ LIBRARY/CROSS_REFERENCE=ALL/OUTPUT=SYS$OUTPUT LIBRAR      

This LIBRARY command requests a cross-reference listing of the object library LIBRAR.OLB. The cross-reference listing is displayed at the terminal. The listing includes cross-references by symbol, by value, and by module.

Stores a library in data-reduced format or expands a library previously stored in data-reduced format.

Format

/DATA= option

option

The option REDUCE, which stores a library in data-reduced format, or the option EXPAND, which expands a library previously stored in data-reduced format. There is no default; you must specify one of the options.

Description

When you specify /DATA, the DCL command LIBRARY creates a new library. By default, the new library is created in your current default directory with 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 library.

You use the /DATA qualifier to control how data is stored in the library. If you specify /DATA=REDUCE, data in the library is stored in data-reduced format; less disk space is required for the library, but access to the library generally is slower.

Note For I64 systems, HP strongly recommends that DCX data-reduced ELF object libraries first be expanded before performing Linker operations.

If you omit this qualifier, data is stored in the library in standard, rather than data-reduced, format. You can change a data-reduced library back to the standard format by specifying /DATA=EXPAND.

When you use the /DATA qualifier (with either option), LIBRARIAN also recovers space in the library that had been occupied by modules deleted from the library, just as if you had specified /COMPRESS.

Example

$ LIBRARY/TEXT/DATA=REDUCE TEXTLIB      

This LIBRARY command stores the data in the text library TEXTLIB.TLB in data-reduced format.

Requests the LIBRARY command to delete (physically remove) one or more modules from a library.

Format

/DELETE= (module[,...])

module

The name of the module to be deleted.

Description

You must specify the names of the modules to be deleted. If you specify more than one module, separate the module names with commas and enclose the list in parentheses.

Wildcard characters are allowed in the module specification.

If you specify the /LOG qualifier with /DELETE, LIBRARY issues the following message:

%LIBRAR-S-DELETED, MODULE module-name DELETED FROM library-name

Example

$ LIBRARY/DELETE=FREEZE/LOG THAW      

This LIBRARY command physically removes the module FREEZE from the object library THAW. A message is displayed to confirm that the module was deleted.

Copies one or more modules from a library into a file.

Format

/EXTRACT= (module[,...])

module

The name of the module to be copied.

Description

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

Wildcard characters are allowed in the module specification.

If you specify the /OUTPUT qualifier with /EXTRACT, the LIBRARY command writes the output into the file specified by the /OUTPUT qualifier. If you do not specify a directory, the file is written to your current default directory. If you specify /EXTRACT and do not specify /OUTPUT, the LIBRARY command writes the file into a file that has the same file name as the library and a file type of .OBJ, .EXE, .MAR, .HLP, or .TXT, depending on the type of library.

Example

$ LIBRARY/EXTRACT=(ALLOCATE,APPEND)/OUTPUT=MYHELP SYS$HELP:HELPLIB.HLB      

This LIBRARY command specifies that the modules ALLOCATE and APPEND are to be extracted from the help library HELPLIB.HLB and output to the file MYHELP.HLP in your current default directory.

Requests a full description of each module in the module name table.

Format

/FULL

Description

Use the /FULL qualifier with the /LIST qualifier to request a list of each library module in the following format, where Ident nn is the identification number of the module:

module-name [Ident nn] Inserted dd-mmm-yyyy hh:mm:ss [n symbols]

The identification number and the number of symbols appear only in object libraries.

If an update history is maintained for the library, then /LIST/FULL/HISTORY lists the module name in the update history records.

Example

$ LIBRARY/LIST=MYMAC.LIS/FULL MYMAC.MLB      

This LIBRARY command requests a full listing of the macro library MYMAC; the output is written to a file named MYMAC.LIS.

For object and shareable image module libraries, controls whether the names of global symbols in modules being inserted in the library, as well as Unix-style weak symbols and group symbols from ELF objects, are included in the global symbol table.

Format

/GLOBALS

/NOGLOBALS

Description

By default, the LIBRARY command places the module's symbol names in the global symbol table. Use /NOGLOBALS if you do not want the symbol names included in the global symbol table.

Example

$ LIBRARY/INSERT/NOGLOBALS TOOLS SPELL      

This LIBRARY command inserts the modules in SPELL.OBJ into the object library TOOLS.OLB, but symbol names in the inserted modules are not included in the library's global symbol table.

Indicates that the library specified is a help library.

Format

/HELP

Description

When you use the /HELP qualifier, the library file type defaults to .HLB and the input file type defaults to .HLP.

Example

$ LIBRARY/HELP/CREATE ERRMSG EDITERRS      

This LIBRARY command creates a help library called ERRMSG.HLB. Help text from the file EDITERRS.HLP is inserted into the library.

Requests that update history record headers be listed (for libraries that contain a history).

The operation referred to in the header has one of three values: replaced, inserted, or deleted.

Format

username operation n modules on dd-mmm-yyy hh:mm:ss

Description

The /HISTORY qualifier is used with the /LIST qualifier. Use the /HISTORY qualifier with /LIST/FULL to request that the names of updated modules be listed in addition to the update history headers.

Example

$ LIBRARY/LIST/HISTORY/MACRO SETUP      

This LIBRARY command lists the headers of the update history records in the macro library SETUP.MLB.

Requests the LIBRARY command to add the contents of one or more files to an existing library.

Format

/INSERT

Description

If an object module input file consists of concatenated object modules, the LIBRARY command creates a separate entry for each object module in the file; each module name table entry reflects an individual module name. If a macro or help file specified as input contains more than one definition, the LIBRARY command creates a separate entry for each one, naming the module name table entries according to the names specified in the .MACRO directives or in the key-1 name in the help format (see Section 2.5.1).

Unlike object, macro, and help libraries, the input file in text libraries contains data records of undefined contents. Therefore, LIBRARIAN catalogs the entire input file as a single module using the file name (not the directory or file type) as the module name. If you want to rename the inserted module, use the /MODULE qualifier.

When you use the /INSERT qualifier to insert modules into an existing library, the Librarian utility checks the module name table before inserting each module. If a module name or symbol name already exists in the library, an error message is issued and the module or symbol is not added to the library.

For OpenVMS VAX libraries, the maximum record size (established by LBR$C_MAXRECSIZ) that can be inserted into a library is 2048 bytes.

For OpenVMS Alpha and ELF libraries, the maximum record size (established by ELBR$C_MAXRECSIZ) that can be inserted into a library is 8192 bytes.

To insert or replace a module in a library, regardless of whether a current entry exists with the same name, use the /REPLACE qualifier (the default operation).

Example

$ LIBRARY/INSERT TESTLIB SCANLINE$ LINK TERMTEST,TESTLIB/LIBRARY      

This LIBRARY command adds the module SCANLINE.OBJ to the library TESTLIB.OLB. The library is specified as input to the linker by the /LIBRARY qualifier on the LINK command. If the module TERMTEST.OBJ refers to any routines or symbols not defined in TERMTEST, the linker searches the global symbol table of library TESTLIB.OLB to resolve the symbols.

Controls whether the LIBRARY command creates a listing that provides information about the contents of the library.

Format

/LIST [=file-spec]

/NOLIST

file-spec

The file specification of the file to be listed.

Description

By default, LIBRARY does not produce a listing. If you specify /LIST without a file specification, LIBRARY writes the output file to the current SYS$OUTPUT device. If you include a file specification that does not have a file type, LIBRARY uses the default file type .LIS.

If you specify /LIST with qualifiers that perform additional operations on the library, the LIBRARY command creates the listing after completing all other requests; thus, the listing reflects the status of the library after all changes have been made.

When you specify /LIST, the LIBRARY command provides, by default, the following information about the library:

Directory of OBJECT library _DBB0:[LIBRAR]LIBRAR.OLB;1 on 31-DEC-1993 10:08:28 Creation date: 12-DEC-1992 19:40:36 Creator: VAX-11 librarian V04-00 Revision date: 31-DEC-1992 16:04:58 Library format: 3.0 Number of modules: 15 Max. key length: 31 Other entries: 73 Preallocated index blocks: 35 Recoverable deleted blocks: 15 Total index blocks used: 12 Max. update history records: 10 Update history records: 5

Examples

$ LIBRARY/LIST=MYMAC.LIS/FULL MYMAC.MLB      

This LIBRARY command requests a full listing of the macro library MYMAC; the output is written to a file named MYMAC.LIS.

$ LIBRARY/LIST/NAMES/ONLY=$ONE/WIDTH=80 SYMBOLIB      

This LIBRARY command requests a full listing of the module $ONE, contained in the object library SYMBOLIB.OLB. The /WIDTH qualifier requests that the global symbol display be limited to 80 characters per line.

$ LIBRARY/INSERT/LIST ALLOBJECTS *      

This LIBRARY command inserts into ALLOBJECTS.OLB all object modules from all object files in the current directory. If any of the modules to be inserted have the same name as an existing module in the library, the existing module is replaced. The LIBRARY command then lists the resulting library on SYS$OUTPUT.