Updated: 11 December 1998

OpenVMS Command Definition, Librarian, and Message Utilities Manual

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.

Description

When you use the /ONLY qualifier, the LIBRARY command lists or cross-references only those modules specified.

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

The /ONLY qualifier must be used with the /LIST or /CROSS_REFERENCE qualifier.

Wildcard characters are allowed in the module name specification.

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.

When used with the /EXTRACT, /COMPRESS, /CROSS_REFERENCE, or /DATA qualifier, specifies the file specification of the output file.

Format

/OUTPUT= file-spec

file-spec

The file specification of the output file.

Description

For /EXTRACT, the output file contains the modules extracted from a library; for /COMPRESS, the output file contains the compressed library; for /CROSS_REFERENCE, the output file contains the cross-reference listing; for /DATA, the output file contains the data-reduced or data-expanded library.

No wildcard characters are allowed in the file specification.

If you omit the file type in the file specification, a default is used depending on the library function qualifier and, in some cases, the library type qualifier, as follows.

Qualifier	Library Type Qualifier	Default File Type
/COMPRESS or /DATA	/HELP /MACRO /OBJECT /TEXT /SHARE	.HLB .MLB .OLB .TLB .OLB
/CROSS_REFERENCE	---	.LIS
/EXTRACT	/HELP /MACRO /OBJECT /TEXT /SHARE	.HLP .MAR .OBJ .TXT .EXE

Examples

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

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

Requests the LIBRARY command to delete one or more entries from the global symbol table in an object library.

Format

/REMOVE= (symbol[,...])

symbol

The symbol to be deleted from the global symbol table.

Description

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

Wildcard characters are allowed in the symbol specification.

To display the names of the deleted global symbols, you must also specify the /LOG qualifier.

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.

Requests the LIBRARY command to replace one or more existing library modules with the modules specified in the input files.

Format

/REPLACE

Description

The LIBRARY command first deletes any existing library modules with the same names as the modules in the input files. Then the new version of the module is inserted in the library. If a module contained in an input file does not have a corresponding module in the library, LIBRARY inserts the new module in the library.

The /REPLACE qualifier is the LIBRARY command's default operation. If you specify an input file parameter, the LIBRARY command either replaces or inserts the contents of the input file into the library. If you use the /LOG qualifier with the /REPLACE qualifier, the LIBRARY command displays, in the following format, the name of each module that it replaces or inserts:

%LIBRAR-S-REPLACED, MODULE module-name REPLACED IN library-file-spec %LIBRAR-S-INSERTED, MODULE module-name INSERTED IN library-file-spec

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.

Defines the input modules being inserted into a library as candidates for selective searches by the linker.

Format

/SELECTIVE_SEARCH

Description

If you specify /SELECTIVE_SEARCH and the library is specified as a linker input file, the linker selectively searches the modules; the linker takes from the library, for the symbol table of its output image file, only those global symbols that have been referenced by other modules.

Note that the selective search operation applies only to those modules that were inserted in the library by a LIBRARY command that included the /SELECTIVE_SEARCH qualifier; it does not apply to the library itself.

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.

Indicates that the library specified is a shareable image library.

Format

/SHARE

Description

This LIBRARY command assumes a file type of .OLB for the shareable image library and .EXE for the input files. See Section 2.4 for additional information.

On OpenVMS VAX systems, the /SHARE qualifier creates a VAX shareable image library by default. 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 /SHARE qualifier creates an Alpha shareable image library by default. Note that you cannot have Alpha modules and VAX modules in the same library. For more information, see the description of the /ALPHA qualifier.

Example

$ LIBRARY/SHARE/CREATE SHARLIB
      

This LIBRARY command creates a shareable image library called SHARLIB.OLB.

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.

Description

This qualifier is used with the /LIST qualifier. If you omit the /SINCE qualifier, you obtain all the modules regardless of the date. If you specify /SINCE without a date or time, the default is to provide the modules inserted since today.

Example

$ LIBRARY/HELP/LIST/SINCE=:12 ERRMSG
      

This LIBRARY command displays information about help modules added to ERRMSG.HLB since noon today.

Controls whether the LIBRARY command compresses individual macros before adding them to a macro library.

Format

/SQUEEZE

/NOSQUEEZE

Description

When you specify /SQUEEZE, which is the default, trailing blanks, trailing tabs, and comments are deleted from each macro before its insertion in the library.

Use /SQUEEZE only with the /CREATE, /INSERT, and /REPLACE qualifiers to conserve space in a macro library. If you want to retain the full macro, specify /NOSQUEEZE.

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.

Indicates that the library specified is a text library.

Format

/TEXT

Description

When you use the /TEXT qualifier, the library file type defaults to .TLB and the input file type defaults to .TXT.

Examples

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

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

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.

Format

/VAX

Description

On OpenVMS Alpha systems, use the /VAX qualifier to create and manipulate OpenVMS VAX object and shareable image libraries. Because the formats of macro, help, and text libraries on OpenVMS Alpha systems are identical to those on OpenVMS VAX systems, using the /VAX qualifier with the /MACRO, /HELP, and /TEXT qualifiers has no effect.

Note that you cannot have both OpenVMS Alpha and OpenVMS VAX object modules in the same object library, nor can you have both OpenVMS Alpha and OpenVMS VAX shareable images in the same shareable image library.

Examples

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

$ LIBRARY/VAX/SHARE/CREATE SHARLIB
      

This LIBRARY command creates a VAX shareable image library called SHARLIB.OLB.

Controls the screen display width (in characters) for listing global symbol names.

Format

/WIDTH= n

n

The width of the screen display.

Description

Specify the /WIDTH qualifier with the /NAMES qualifier to limit the line length of the /NAMES display.

The default display width is the width of the listing device. The maximum width is 132.

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.

MESSAGE Description

The Message utility (MESSAGE) lets you supplement OpenVMS system messages with your own messages. Your messages can indicate that an error has occurred, or they can indicate other conditions; for example, that a routine has run successfully or that a default value has been assigned.

This section describes how to use the Message utility.

3.1 Message Format

Messages are displayed as a line of alphanumeric codes. The text of the message explains the condition that caused the message to be displayed.

Messages are displayed in the following format:

%FACILITY-L-IDENT, message-text

FACILITY

Specifies the abbreviated name of the software component that issued the message.

L

Shows the severity level of the condition that caused the message. The five severity levels are represented by the following codes:

S	Success
I	Informational
W	Warning
E	Error
F	Fatal or severe

IDENT

Identifies a symbol of up to 15 characters that represents the message.

message-text

Explains the cause of the message. The message text can include up to 255 formatted-ASCII-output (FAO) arguments. For example, an FAO argument can be used to display the instruction where an error occurred or a value that you should be aware of.

% and ,

Included as delimiters if any of the first three fields---FACILITY, L, or IDENT---are present.

If you suppress FACILITY, L, and IDENT, the first character of the message text is capitalized by the Put Message ($PUTMSG) system service.

The following is a typical message:

%TYPE (1)-W- (2)OPENIN (3), error opening _DB0:[ROSE]STATS.FOR;(4) as input (5)

1. TYPE is the facility.
2. W (Warning) is the severity level.
3. OPENIN is the IDENT.
4. _DBO:[ROSE]STATS.FOR is the FAO argument.
5. "Error opening _DBO:[ROSE]STATS.FOR; as input" is the message text.

You construct messages by writing a message source file, compiling it using the Message utility, and linking the resulting object module with your facility object module. When you run your program, the Put Message ($PUTMSG) system service finds the information to use in the message by using a message argument vector.

The message argument vector includes the message code, a 32-bit value that uniquely identifies the message. The message code, which is created from information defined in the message source file, consists of the following:

• The severity level defined in the severity directive or message definition
• The message number assigned automatically by a message definition or specified with the base message number directive
• The facility number defined in the facility directive
• Internal control flags

Figure 3-1 shows the arrangement of the bits in the message code.

Figure 3-1 Message Code

You can refer to the message code in your programs by means of a global symbol called the message symbol, which also is defined by information from the message source file. The message symbol, which appears in the compiled message file, consists of the following:

• The symbol prefix defined in the facility directive
• The symbol name defined in the message definition

The message source file consists of message definition statements and directives that define the message text, the message code values, and the message symbol. The various elements that can be included in a message source file are as follows:

• Facility directive
• Severity directive
• Base message number directive
• Message definition
• Literal directive
• Identification directive
• Listing directives
• End directive

Usually, the first statement in a message source file is a .TITLE directive, which lets you specify a module name for the compiled message file. You must specify a .FACILITY directive after the .TITLE directive. All the messages defined after a .FACILITY directive are associated with that facility. A .END directive or a new .FACILITY directive ends the list of messages associated with a particular facility.

You must define a severity level for each message either by specifying a .SEVERITY directive or by including a severity qualifier as part of the message definition.

Each message defined in the message source file must have a facility and a message definition associated with it. All other message source file statements are optional. See the MESSAGE Commands section for a detailed description of the format of each of these message source file statements.

The TESTMSG.MSG file that follows is a sample message source file. The messages for the associated FORTRAN program, TEST.FOR, are defined in TESTMSG.MSG with the following lines:

.FACILITY TEST,1 /PREFIX=MSG_ .SEVERITY ERROR SYNTAX <Syntax error in string '!AS'>/FAO=1 ERRORS <Errors encountered during processing> .END

The FORTRAN program, TEST.FOR, contains the following lines:

EXTERNAL MSG_SYNTAX,MSG_ERRORS CALL LIB$SIGNAL(MSG_SYNTAX,%VAL(1),'ABC') CALL LIB$SIGNAL(MSG_ERRORS) END

In addition to defining the message data, TESTMSG.MSG also defines the message symbols MSG_SYNTAX and MSG_ERRORS that are included as arguments in the procedure calls of TEST.FOR. The function %VAL is a required FORTRAN compile-time function. The first call also includes the string ABC as an FAO argument.

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

6100PRO_008.HTML