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[,...]]
1 – 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.
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.
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.
2 /ALPHA_(Alpha_and_VAX_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 it works exclusively with
I64 libraries.
Format
/ALPHA
2.1 – Examples
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.
3 /BEFORE
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.
3.1 – 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.
4 /COMPRESS
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.
You can specify one or more of the following options: BLOCKS:n,
GLOBALS:n, HISTORY:n, KEEP, KEYSIZE:n, MODULES:n, or VERSION:n.
4.1 – 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.
5 /CREATE
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.
On OpenVMS VAX systems, the /CREATE qualifier creates a VAX
library by default when used to create object and shareable
image libraries. On OpenVMS Alpha systems, the /CREATE qualifier
createsan 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.) On OpenVMS
I64 systems, the /CREATE qualifier creates an ELF library
when used to create object and shareable image libraries.
Format
/CREATE[=(option[,...])]
option
An option that overrides the system defaults to control the size
or format of the library. You can specify one or more of the
following options: BLOCKS:n, CASE_SENSITIVE:[YES/NO], GLOBALS:n,
HISTORY:n, KEEP, KEYSIZE:n, MODULES:n, or VERSION:n.
5.1 – Examples
1.$ 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.
2.$ 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.
6 /CROSS_REFERENCE
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. You can
specify one or more of the following options: ALL, MODULE, NONE,
SYMBOL, or VALUE.
6.1 – 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.
7 /DATA
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.
________________________ Note ________________________
For I64 systems, VSI strongly recommends that DCX
data-reduced ELF object libraries first be expanded
before performing Linker operations.
______________________________________________________
7.1 – Example
$ LIBRARY/TEXT/DATA=REDUCE TEXTLIB
This LIBRARY command stores the data in the text library
TEXTLIB.TLB in data-reduced format.
8 /DELETE
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.
8.1 – 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.
9 /DEMANGLED_SYMBOLS_(I64_Only)
Lists symbols from an ELF object or ELF shareable image library that
were altered by a language processor (a process known as "mangling")
and prints their corresponding "demangled" name (that is, the name
found in the source code). Mangled names are output as external symbols
from an object module or as universal symbols from a shareable image.
You can use /OUTPUT=file-spec to direct the generated output from
the demangling process to a file specification you choose. When
you do not specify a file, the default is the current disk and
directory, using the name of the library as the filename and the
extension .LIS as the file type.
Format
/DEMANGLED_SYMBOLS
9.1 – Examples
1.$ LIBRARY/DEMANGLED_SYMBOLS/OUTPUT=SYS$OUTPUT OBJLIB.OLB
This LIBRARY command outputs the demangled symbols from an
object library and displays them on the terminal.
2.$ LIBRARY/DEMANGLED_SYMBOLS/OUTPUT=DUMP.LIS SHAREIMG.OLB
This LIBRARY command outputs a full listing of the demangled
symbols from the shareable image library SHAREIMG.OLB; the
output is written to a file named DUMP.LIS.
3.$ LIBRARY/DEMANGLED_SYMBOLS/ONLY=$ONE SYMBOLIB
This LIBRARY command outputs a full listing of the demangled
symbols for the module $ONE in object library SYMBOLIB.OLB.
The output is written to a file named SYMBOLIB.LIS.
10 /EXTRACT
Copies one or more modules from a library into a file.
Format
/EXTRACT=(module[,...])
module
The name of the module to be copied.
10.1 – 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.
11 /FULL
Requests a full description of each module in the module name
table.
Format
/FULL
11.1 – 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.
12 /GLOBALS
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
12.1 – 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.
13 /HELP
Indicates that the library specified is a help library.
Format
/HELP
13.1 – 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.
14 /HISTORY
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
14.1 – Example
$ LIBRARY/LIST/HISTORY/MACRO SETUP
This LIBRARY command lists the headers of the update history
records in the macro library SETUP.MLB.
15 /INSERT
Requests the LIBRARY command to add the contents of one or more
files to an existing library.
Format
/INSERT
15.1 – 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.
16 /LIST
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.
16.1 – Examples
1.$ 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.
2.$ 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.
3.$ 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.
17 /LOG
Controls whether the LIBRARY command verifies each library
operation.
Format
/LOG
/NOLOG
17.1 – 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.
18 /MACRO
Indicates that the library specified is a macro library.
Format
/MACRO
18.1 – Example
$ LIBRARY/MACRO/INSERT MONTHS APRIL
This LIBRARY command inserts modules from APRIL.MAR into the
macro library MONTHS.MLB.
19 /MODULE
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.
19.1 – 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.
20 /NAMES
When /LIST is specified for an object module library, controls
whether the LIBRARY command lists the names of all symbols
in the global symbol table as well as the module names in the
module name table.
Format
/NONAMES (default)
Alpha and VAX
/NAMES
I64
/NAMES[=option]
option
Controls the listing of the names. You may optionally
specify one of the following keywords:
BYMODULE Lists each module followed by a list of the
symbols in the global symbol table associated
with that module. This is the default listing
format when no keyword is given with the /NAMES
qualifier.
BYSYMBOL Lists each symbol in the global symbol table
followed by a list of modules with which the
symbol is associated, in precedence order.
20.1 – 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.
21 /OBJECT
Indicates that the library specified is an object module library.
On OpenVMS VAX systems, the /OBJECT qualifier creates a VAX
library by default. 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.) On OpenVMS
I64 systems, the /OBJECT qualifier creates only ELF object
libraries.
Format
/OBJECT
21.1 – 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.
22 /ONLY
Specifies the individual modules on which the LIBRARY command can
operate.
Format
/ONLY=(module-name[,...])
module-name
The module on which the LIBRARY command can operate.
22.1 – 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 symbol display be limited to
80 characters per line.
23 /OUTPUT
When used with the /COMPRESS, /CROSS_REFERENCE, /DATA,
/DEMANGLED_SYMBOLS, or /EXTRACT qualifier, specifies the file
specification of the output file.
Format
/OUTPUT=file-spec
file-spec
The file specification of the output file.
23.1 – Examples
1.$ LIBRARY/EXTRACT=(ALLOCATE,APPEND)/OUT=MYHELP SYS$HELP:HELPLIB.HLB
This LIBRARY command specifies that the modules ALLOCATE and
APPEND be extracted from the help library HELPLIB.HLB and
output to the file MYHELP.HLP.
2.$ 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.
24 /REMOVE
Requests the LIBRARY command to delete one or more entries from
the global symbol table in a library.
Format
Alpha and VAX:
/REMOVE=(symbol[,...])
I64:
/REMOVE=(symbol[:module] [,...])
symbol
The symbol to be deleted from the global symbol table.
module
The module whose instance of the symbol is to be removed
from the global symbol table. With the support of UNIX-
style weak symbols and ELF group symbols, a symbol can have
definitions from more than one module. This extended syntax
allows you to remove from the index a symbol of a specific
module without removing the symbol instances of all other
modules from the index. The [:module] is OpenVMS I64
Librarian syntax only.
24.1 – 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.
25 /REPLACE
Requests the LIBRARY command to replace one or more existing
library modules with the modules specified in the input files.
Format
/REPLACE
25.1 – Example
$ LIBRARY/REPLACE/HELP HELPLIB NEWTEXT
This LIBRARY command inserts into the help library HELPLIB.HLB
the help modules from the file NEWTEXT.HLP. If a help module
in NEWTEXT.HLP has the same name as an existing help module in
the library, the module from NEWTEXT.HLP replaces the existing
module.
26 /SELECTIVE_SEARCH
Defines the input modules being inserted into a library as
candidates for selective searches by the linker.
Format
/SELECTIVE_SEARCH
26.1 – Example
$ LIBRARY/SELECTIVE_SEARCH/INSERT MATHLIB TRIG
This LIBRARY command inserts the modules in TRIG.OBJ into the
library MATHLIB.OLB. The inserted modules are selectively
searched when MATHLIB.OLB is specified as an input file to
the linker.
27 /SHARE
Indicates that the library specified is a shareable image
library and assumes a file type of .OLB for the shareable
image library and .EXE for the input files.
On OpenVMS VAX systems, the /SHARE qualifier creates a
VAX shareable image library by default. On OpenVMS Alpha
systems, the /SHARE qualifier creates an Alpha shareable
image library by default. (Note that you cannot have
VAX modules and Alpha modules in the same library.) On
I64 systems, the /SHARE qualifier creates only ELF
sharable image libraries.
Format
/SHARE
27.1 – Example
$ LIBRARY/SHARE/CREATE SHARELIB.OLB
This LIBRARY command creates a shareable image library called
SHARELIB.OLB.
28 /SINCE
Specifies that only those modules inserted later than a
particular time be listed.
Format
/SINCE[=time]
time
Limits the modules to be listed to those inserted in the library
since 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.
28.1 – Example
$ LIBRARY/HELP/LIST/SINCE=:12 ERRMSG
This LIBRARY command displays information about help modules
added to ERRMSG.HLB since noon today.
29 /SQUEEZE
Controls whether the LIBRARY command compresses individual macros
before adding them to a macro library.
Format
/SQUEEZE
/NOSQUEEZE
29.1 – Example
$ LIBRARY/MACRO/NOSQUEEZE/INSERT MYMACS MYMACS
This LIBRARY command inserts the macros in MYMACS.MAR into
the library MYMACS.MLB. Trailing blanks, trailing tabs, and
comments are not deleted from each macro before its insertion
into the library.
30 /TEXT
Indicates that the library specified is a text library.
Format
/TEXT
30.1 – Examples
1.$ 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.
2.$ LIBRARY/INSERT/TEXT TSTRING TEXT2
This LIBRARY command inserts the contents of the file TEXT2.TXT
into the text library TSTRING.TLB. The name of the inserted
module is TEXT2.
31 /VAX_(VAX_and_Alpha_only)
Directs LIBRARIAN to work with an OpenVMS VAX object library when
used with the /OBJECT qualifier or to work with an OpenVMS VAX
shareable image library when used with the /SHARE qualifier. When
used with the /CREATE qualifier, LIBRARIAN creates an OpenVMS
VAX 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 it works exclusively with I64
libraries.
Format
/VAX
31.1 – Examples
1.$ LIBRARY/VAX/CREATE TESTLIB ERRMSG.OBJ,STARTUP.OBJ
This LIBRARY command creates a VAX object module library named
TESTLIB.OLB and places the files ERRMSG.OBJ and STARTUP.OBJ as
modules in the library.
2.$ LIBRARY/VAX/SHARE/CREATE SHARLIB
This LIBRARY command creates a VAX shareable image library
called SHARLIB.OLB.
32 /WIDTH
Controls the screen display width (in characters) for listing
symbol names.
Format
/WIDTH=n
n
The width of the screen display.
32.1 – 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 symbol display be limited to
80 characters per line.