Updated: 11 December 1998

OpenVMS Command Definition, Librarian, and Message Utilities Manual

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 global symbol references in the module and the global 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.

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.

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.

Format

/GLOBALS

/NOGLOBALS

Description

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.

Example

$ LIBRARY/INSERT/NOGLOBALS TOOLS SPELL
      

This LIBRARY command inserts the modules in SPELL.OBJ into the object library TOOLS, but global 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 global 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 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 global 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.

Controls whether the LIBRARY command verifies each library operation.

Format

/LOG

/NOLOG

Description

If you specify /LOG, the LIBRARY command displays the module name, followed by the library operation performed, followed by the library file specification.

Other applications of the /LOG qualifier appear in the descriptions of /DELETE and /REPLACE.

Example

$ LIBRARY/REMOVE=(LIB_EXTRCT_MODS,LIB_INPUT_MAC)/LOG LIBRAR
      

This LIBRARY command requests the removal of the global symbols LIB_EXTRCT_MODS and LIB_INPUT_MAC from the object library LIBRAR.OLB. The /LOG qualifier requests that the removal of the symbols be confirmed by messages.

Indicates that the library specified is a macro library.

Format

/MACRO

Description

When you specify the /MACRO qualifier, the library file type defaults to .MLB and the input file type defaults to .MAR.

Example

$ LIBRARY/MACRO/INSERT MONTHS APRIL
      

This LIBRARY command inserts modules from APRIL.MAR into the macro library MONTHS.MLB.

Names a text module that you want to replace or insert into a text library. It also modifies the input file specification parameter.

Format

/MODULE= module-name

module-name

The name of the module to be inserted in the library.

Description

When you insert text modules into a library, the input file you specify is assumed to be a single module. Therefore, the file name of the input file specification becomes the module name. If you want the file you are inserting to have a module name different from its input file name, use the /MODULE qualifier to name the added module.

You can also use the /MODULE qualifier to enter a text module interactively. If you specify the logical name SYS$INPUT as the input file and use the /MODULE qualifier, the LIBRARY command inserts the text you enter from the terminal into the specified library module. To terminate the terminal input, press Ctrl/Z.

Remember that the /MODULE qualifier is an input file qualifier; it assumes that you are either replacing or inserting a new text module. Therefore, the qualifiers that remove modules---/EXTRACT, /DELETE, /REMOVE---are incompatible with /MODULE.

Note that you must place the /MODULE qualifier after the input file you specify.

Example

$ LIBRARY/INSERT/TEXT TSTRING SYS$INPUT/MODULE=TEXT1
      

This LIBRARY command inserts a module named TEXT1 into the text library TSTRING.TLB. The input is taken from SYS$INPUT.

When /LIST is specified for an object module library, controls whether the LIBRARY command lists the names of all global symbols in the global symbol table as well as the module names in the module name table.

Format

/NAMES

/NONAMES

Description

The default is /NONAMES, which does not list the global symbol names. If you specify /NAMES, each module entry name is displayed in the following format:

module "module-name" global-symbol global-symbol global-symbol global-symbol . . . . . . . . . . . .

If you specify /NAMES and the library is a macro, help, or text library, no symbol names are displayed.

Example

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

Indicates that the library specified is an object module library.

Format

/OBJECT

Description

Libraries are assumed to be object module libraries unless you specify the /SHARE, /MACRO, /TEXT, or /HELP qualifier. The library file type for object module libraries defaults to .OLB and the input file type defaults to .OBJ.

On OpenVMS VAX systems, the /OBJECT qualifier creates a VAX library by default. Note that you cannot have VAX modules and Alpha modules in the same library file. For more information, see the description of the /VAX qualifier.

On OpenVMS Alpha systems, the /OBJECT qualifier creates an Alpha library by default. Note that you cannot have Alpha modules and VAX modules in the same library file. For more information, see the description of the /ALPHA qualifier.

Example

$ LIBRARY/OBJECT/INSERT MONTHS APRIL
      

This LIBRARY command inserts modules from APRIL.OBJ into the object library MONTHS.OLB. The /OBJECT qualifier is optional.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6100PRO_007.HTML