HELP LIBRARY — VMS 5.5-2H4
The Librarian Utility (LIBRARIAN) allows you easy access to
libraries. Libraries are files in which you can store frequently
used modules of code or text.
The LIBRARIAN consists of two parts: the DIGITAL Command Language
(DCL) command LIBRARY, and a collection of LIBRARIAN routines (see
VMS Utility Routines Manual) you can call from a program. You use
the LIBRARY command or the LIBRARIAN 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, the DELETE,
COPY, and RENAME commands delete, copy, and rename libraries.
For more information about file maintenance, see the VMS DCL
Dictionary.
Format
LIBRARY library-file-spec [input-file-spec[,...]]
Additional information available:
Parametersusage summaryLIBRARIAN Description
/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/WIDTH
Parameters
library-file-specification
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
NOTE
If you attempt to modify a library that was created by the
VAX-11 Version 1.0 LIBRARIAN, the library is automatically
compressed into the new format introduced with Version 2.0.
The compression occurs before the requested modification.
Furthermore, libraries created before Version 2.0 that have
not been modified or compressed will appear in a different
format when listed by the /LIST qualifier.
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, the LIBRARY command
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, the LIBRARY command 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.
usage summary
The DCL command LIBRARY invokes the Librarian Utility. After the operations specified by the LIBRARY command have completed, the Librarian Utility exits. 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 Description
You can use the LIBRARIAN to maintain the following types of
libraries:
o Object libraries, which contain the object modules of
frequently called routines. The VMS Linker searches specified
object module libraries when it encounters a reference it
cannot resolve in one of its input files.
An object library has a default file type of OLB and defaults
the file type of input files to OBJ.
o Macro libraries, which contain macro definitions used as input
to the assembler. The assembler searches specified macro
libraries when it encounters a macro that is not defined in
the input file.
A macro library has a default file type of MLB and defaults the
file type of input files to MAR.
o Help libraries, which contain modules of help text that provide
user information about a program. You can retrieve help text at
DCL level by executing the DCL command HELP, or in your program
by calling the appropriate LIBRARIAN routines.
A help library has a default file type of HLB and defaults the
file type of input files to HLP.
o Text libraries, which contain any sequential record files
that you want to retrieve as data for a program. For example,
program source code can be stored in text libraries. Each text
file inserted into the library corresponds to one library
module. Your programs can retrieve text from text libraries
by calling the appropriate LIBRARIAN routines.
A text library has a default file type of TLB and defaults the
file type of input files to TXT.
o Shareable image libraries, which contain the symbol tables of
shareable images used as input to the linker.
A shareable image library has a default type of OLB and
defaults the file type of input files to EXE.
/BEFORE
Specifies that only those modules inserted earlier than a
particular time be listed.
Format
/BEFORE[=time]
Additional information available:
Qualifier Value
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 on specifying times, see the VMS DCL Dictionary.
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.
/COMPRESS
Recovers space that was occupied by modules deleted from the
library. When you specify /COMPRESS, the LIBRARY command 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[,...])]
Additional information available:
Qualifier ValueDescriptionExample
Qualifier Value
option An option (listed under the Description section) that alters the size or format of the library, overriding the values specified when the library was created.
Description
When you specify /COMPRESS, the LIBRARY command 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, the LIBRARY
command allocates 100 blocks for a new library.
GLOBALS:n Specifies the maximum number of global symbols the
library can contain initially. By default, the LIBRARY
command 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. The LIBRARY command
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. When you specify a key
size value, remember that VAX MACRO and the VMS Linker
do not accept module names or global symbol names in
excess of 31 characters.
MODULES:n Specifies the maximum number of modules the library
can contain. By default, the LIBRARY command 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 VAX/VMS
Version 2.0 library format, if n is 2; or VAX/VMS
Version 3.0 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 may
contain up to 80 modules; the maximum length of module names in
the new version is 40.
/CREATE
Requests the LIBRARY command 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[,...])]
Additional information available:
Qualifier ValueDescriptionExamples
Qualifier Value
option An option (listed under the Description section) that overrides the system defaults to control the size of the library.
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.
Specify one or more of the following options to control the size
of the library, overriding the system defaults:
BLOCKS:n Specifies the number of 512-byte blocks to be
allocated for the library. By default, the LIBRARY
command allocates 100 blocks for a new library.
GLOBALS:n Specifies the maximum number of global symbols the
library can contain initially. By default, the LIBRARY
command 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 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. The LIBRARY command
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. When you specify a key
size value, remember that VAX MACRO and the VMS Linker
do not accept module names or global symbol names in
excess of 31 characters.
MODULES:n Specifies the maximum number of modules the library
can contain. By default, the LIBRARY command 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 VAX/VMS
Version 2.0 library format, if n is 2; or VAX/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
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.
/CROSS_REFERENCE
Requests a cross-reference listing of an object library.
Format
/CROSS_REFERENCE[=(option[,...])]
Additional information available:
Qualifier ValueDescriptionExample
Qualifier Value
option An option (listed under the Description section) that produces a cross-reference listing that is not limited to only symbols by name and symbols by value.
Description
If you omit this qualifier, cross-reference listings will not
be provided. If you specify /CROSS_REFERENCE without specifying
an option, you will obtain 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.
/DATA
Stores a library in data-reduced format, or expands a library
previously stored in data-reduced format.
Format
/DATA=option
Additional information available:
Qualifier Value
option The option REDUCE, which stores a library in data-reduced format, and the option EXPAND, which expands a library previously stored in data-reduced format. There is no default; you must specify one of the options.
Example
$ LIBRARY/TEXT/DATA=REDUCE TEXTLIB
This LIBRARY command stores the data in the text library
TEXTLIB.TLB in data-reduced format.
/DELETE
Requests the LIBRARY command to delete (physically remove) one or
more modules from a library.
Format
/DELETE=(module[,...])
Additional information available:
Qualifier Value
module The name of the module to be deleted.
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.
/EXTRACT
Copies one or more modules from a library into a file.
Format
/EXTRACT=(module[,...])
Additional information available:
Qualifier Value
module The name of the module to be copied.
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.
/FULL
Requests a full description of each module in the module name
table.
Format
/FULL
Additional information available:
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.
/GLOBALS
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
Additional information available:
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.
/HELP
Indicates that the library specified is a help library.
Format
/HELP
Additional information available:
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.
/HISTORY
Requests that update history record headers be listed (for libraries that contain a history) in the following format: username operation n modules on dd-mmm-yyy hh:mm:ss The operation referred to in the header has one of three values: replaced, inserted, or deleted.
Additional information available:
Example
$ LIBRARY/LIST/HISTORY/MACRO SETUP
This LIBRARY command lists the headers of the update history
records in the macro library SETUP.MLB.
/INSERT
Requests the LIBRARY command to add the contents of one or more
files to an existing library.
Format
/INSERT
Additional information available:
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.
/LIST
Controls whether the LIBRARY command creates a listing that
provides information about the contents of the library.
Format
/LIST[=file-spec]
/NOLIST
Additional information available:
Qualifier Value
file-spec The file specification of the file to be listed.
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.
/LOG
Controls whether the LIBRARY command verifies each library
operation.
Format
/LOG
/NOLOG
Additional information available:
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.
/MACRO
Indicates that the library specified is a macro library.
Format
/MACRO
Additional information available:
Example
$ LIBRARY/MACRO/INSERT MONTHS APRIL
This LIBRARY command inserts modules from APRIL.MAR into the
macro library MONTHS.MLB.
/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
Additional information available:
Qualifier Value
module-name The name of the module to be inserted in the library.
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.
/NAMES
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
Additional information available:
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.
/OBJECT
Indicates that the library specified is an object module library.
Format
/OBJECT
Additional information available:
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.
/ONLY
Specifies the individual modules on which the LIBRARY command can
operate.
Format
/ONLY=(module-name[,...])
Additional information available:
Qualifier Value
module-name The module on which the LIBRARY command can operate.
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.
/OUTPUT
When used with the /EXTRACT, /COMPRESS, /CROSS_REFERENCE, or /DATA
qualifier, specifies the file specification of the output file.
Format
/OUTPUT=file-spec
Additional information available:
Qualifier Value
file-spec The file specification of the output file.
Examples
1. $ LIBRARY/EXTRACT=(ALLOCATE,APPEND)/OUTPUT=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.
/REMOVE
Requests the LIBRARY command to delete one or more entries from
the global symbol table in an object library.
Format
/REMOVE=(symbol[,...])
Additional information available:
Qualifier Value
symbol The symbol to be deleted from the global symbol table.
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.
/REPLACE
Requests the LIBRARY command to replace one or more existing
library modules with the modules specified in the input files.
Format
/REPLACE
Additional information available:
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.
/SELECTIVE_SEARCH
Defines the input modules being inserted into a library as
candidates for selective searches by the linker.
Format
/SELECTIVE_SEARCH
Additional information available:
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
VMS Linker.
/SHARE
Indicates that the library specified is a shareable image library.
Format
/SHARE
Additional information available:
Example
$ LIBRARY/SHARE/CREATE SHARLIB
This LIBRARY command creates a shareable image library called
SHARLIB.OLB.
/SINCE
Specifies that only those modules inserted later than a particular
time be listed.
Format
/SINCE[=time]
Additional information available:
Qualifier Value
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 on specifying times, see the VMS DCL Dictionary.
Example
$ LIBRARY/HELP/LIST/SINCE=:12 ERRMSG
This LIBRARY command displays information about help modules
added to ERRMSG.HLB since noon today.
/SQUEEZE
Controls whether the LIBRARY command compresses individual macros
before adding them to a macro library.
Format
/SQUEEZE
/NOSQUEEZE
Additional information available:
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.
/TEXT
Indicates that the library specified is a text library.
Format
/TEXT
Additional information available:
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.
/WIDTH
Controls the screen display width (in characters) for listing
global symbol names.
Format
/WIDTH=n
Additional information available:
Qualifier Value
n The width of the screen display.
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.