HP OpenVMS systems documentation

You now have a file containing an executable image (USEREXAMP.EXE). To execute the image, enter the following command:

$ RUN USEREXAMP

USEREXAMP.EXE displays the following prompt on your screen:

TEST>

You can now enter any of the commands you defined in TEST.CLD. For example:

TEST> SEND

The program calls CLI$DCL_PARSE to parse the command string SEND. SEND is a valid command, so CLI$DISPATCH transfers control to the SEND_COMMAND routine. This routine displays the following text:

SEND COMMAND TEST>

You can also include a parameter with the SEND command. For example:

TEST> SEND MESSAGE.TXT

DCL invokes the SEND_COMMAND routine, which displays the following text:

SEND COMMAND FILESPEC = MESSAGE.TXT TEST>

You can also enter the /EDIT qualifier with SEND. For example:

TEST> SEND/EDIT MESSAGE.TXT SEND COMMAND /EDIT is present FILESPEC = MESSAGE.TXT TEST>

You can enter other commands that your program accepts. For example:

TEST> SEARCH

The SEARCH command string invokes a different routine from the one defined by SEND. In this case, the screen displays the following text:

SEARCH COMMAND TEST>

Unlike the SEND command, the SEARCH command accepts no qualifiers. If you attempt to include a qualifier (such as /EDIT) in the SEARCH command string, CLI$DCL_PARSE signals the following error:

%CLI-W-NOQUAL, qualifier not allowed on this command

To exit from the USEREXAMP program and return to the DCL command level, issue the EXIT command:

TEST> EXIT

LIBRARIAN Description

Libraries are files that you can use to store modules of code or text. The DCL LIBRARY command invokes the Librarian utility.

This chapter describes how to use the Librarian utility (LIBRARIAN) to create, access, and maintain libraries on all OpenVMS platforms. To use Librarian (LBR) routines to create and maintain libraries and their modules, see the following documentation:

• HP OpenVMS Version 8.2 New Features and Documentation Overview---Describes new LBR routines for Executable and Linking Format (ELF) object libraries and existing routines extended for ELF object libraries (OpenVMS I64 only).
• OpenVMS Utility Routines Manual---Describes additional LBR routines that are the same on OpenVMS I64 systems and OpenVMS Alpha systems.

You can use LIBRARIAN to maintain the following types of libraries:

• Object libraries---Contain the object modules of frequently called routines. The OpenVMS Linker searches specified object module libraries when it encounters a reference it cannot resolve in one of its input files. For more information about how the linker uses libraries, see the HP OpenVMS Linker Utility Manual.
  An object library has a default file type of .OLB and defaults the file type of input files to .OBJ.
• Macro libraries---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. See the VAX MACRO and Instruction Set Reference Manual for information about defining macros on OpenVMS VAX systems. For information on porting VAX MACRO code to an OpenVMS Alpha systems, see HP OpenVMS MACRO Compiler Porting and User's Guide. For information on porting code to I64 systems, see Porting Applications from HP OpenVMS Alpha to HP OpenVMS Industry Standard 64 for Integrity Servers.
  A macro library has a default file type of .MLB and defaults the file type of input files to .MAR.
• Help libraries---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 LBR routines. For information about creating help modules for insertion into help libraries, see Section 2.5.
  A help library has a default file type of .HLB and defaults the file type of input files to .HLP.
• Text libraries---Contain 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 LBR routines.
  A text library has a default file type of .TLB and defaults the file type of input files to .TXT.
• Shareable image libraries---Contain the symbol tables of shareable images used as input to the linker. For information about how to create a shareable image library, see Section 2.4.
  A shareable image library has a default type of .OLB and defaults the file type of input files to .EXE.

You can create library files that do not have the default file type. For example, you can create the object library LIB.xxx by entering the following:

$ LIBRARY/CREATE/OBJECT LIB.xxx *.obj

You can then access the object library by entering the following:

$ LIBRARY/LIST LIB.xxx

Table 2-1 shows the libraries that are created by the Librarian utility for each OpenVMS platform:

Table 2-1 Libraries Created by OpenVMS Platform

OpenVMS VAX	OpenVMS Alpha	OpenVMS I64
VAX object	Alpha object	I64 object
VAX sharable image	Alpha sharable image	I64 sharable image
Alpha object 1	VAX object 1
Alpha sharable image 2	VAX sharable image 2
Macro	Macro	Macro
Text	Text	Text
Help	Help	Help

Every library contains a library header that describes the contents of the library; for example, its type, size, version number, creation date, and number of indexes.

Similarly, each module in the library has a module header that containsinformation about the module, including its type, attributes, and date of insertion into the library.

All libraries contain an index called the module name table (MNT); the keys in the MNT are the names of the modules in the library. Object module libraries also contain an index called the global symbol table (GST); the keys in the GST are the names of the symbols associated with each of the library modules.

For I64 systems, these symbols also include Unix-style weak symbol definitions and Group symbol definitions.

Note that the MNT catalogs modules by module name, rather than by the name of the input file that contained the inserted module. The only exception to this procedure occurs with text libraries, for which the file name of the input file containing the text automatically becomes the module name (unless you use the /MODULE qualifier).

2.3 Character Case of Library Keys

The character case of module names and symbols in libraries depends on the library type:

• Help libraries---Module names remain in the format they were entered; that is, individual uppercase and lowercase characters are preserved. However, a second, identically spelled module name (but of a different or mixed character case) to the same library replaces the previous module name, and character case is ignored for match operations. For example, help Sample and help SAMPLE access the same module.
• Object libraries --- Module names and symbol names are in the format in which they were entered. Match operations require the character case to be identical. For example, for SAMPLE, you must enter SAMPLE, not Sample or sample.
• Text and macro libraries --- By default, all module names are converted to uppercase characters. For example, Sample becomes SAMPLE. Likewise, for match operations, either Sample or sample matches SAMPLE.
  You can override this default behavior by using the CASE_SENSITIVE option to the /CREATE qualifier. If you specify CASE_SENSITIVE:YES, module names remain in the format they were entered, individual uppercase and lowercase characters are preserved, and match operations require the character case to be identical.
  To use the default behavior for macro and text libraries, do not include the CASE_SENSITIVE option with the /CREATE qualifier, or specify CASE_SENSITIVE:NO.
  The CASE_SENSITIVE option works only for macro and text libraries. If you try to use it for other library types, you will get an error message and the library creation operation will abort (no library is created).

A shareable image library or ELF sharable image library is made up of only the symbol tables of shareable images, which serve as input to the linker. To create a shareable image library, use the LIBRARY command with the /SHARE qualifier, as follows:

$ LIBRARY/CREATE/SHARE MYSHARLIB MYSHRIMG1,MYSHRIMG2,SHRIMG3

You can then specify the library in the LINK command exactly as if it were an object library.

$ LINK/MAP/FULL MYPROG, MYSHARLIB/LIBRARY

The linker includes in the link operation whatever shareable images are needed from references to MYSHARLIB.

To explicitly include a shareable image, use the /INCLUDE qualifier.

$ LINK/MAP/FULL MYPROG, MYSHARLIB/INCLUDE=(MYSHRIMG1)/LIBRARY

For each shareable image found that either contains a necessary symbol or was specifically requested with the /INCLUDE qualifier, the linker looks up the image file (default file type is .EXE) and processes it as if it had been specified in an options file.

Unless the search is disabled with the /NOSYSSHR qualifier, the linker also searches the library SYS$LIBRARY:IMAGELIB.OLB after processing any user default libraries (LNK$LIBRARY). Modules found in IMAGELIB.OLB are opened with a default file specification of SYS$LIBRARY:.EXE.

The default file type for the LIBRARY/SHARE command is .OLB for the shareable image symbol table library and .EXE for the input shareable image files.

LIBRARIAN uses the GSMATCH identification numbers (IDs) of the shareable image as the module ID in the library. This provides a convenient way to verify that the shareable image information in the library matches the shareable image information contained in a map file from a link operation.

Note that a module inserted into a shareable image library contains only module header information, which is extracted from the shareable image. Consequently, although it is not an invalid action, there is little reason to extract modules from a shareable image library.

2.5 Help Libraries

Help text is a convenient means of providing specific information about a program to an interactive user. The help text is stored as modules in help libraries. You can access the help modules by using the DCL command HELP or by calling the appropriate LBR routines (described in the OpenVMS Utility Routines Manual). In this way, a user can quickly retrieve relevant information about how to use your program.

You create help libraries the same way you create object, macro, and text libraries, using the LIBRARY/CREATE command. However, before you can insert modules into a help library, you must format the input file so that LIBRARIAN can catalog its individual modules. Section 2.5.1 and Section 2.5.2 describe how to create input files containing help modules.

2.5.1 Creating Help Files

The input files that you insert into help libraries are text files that you build with a program or a text editor. Each input file can contain one or more help modules. A help module is made up of the lines of help text that relate to the same topic, or key.

Each module within a help library contains a group of related keys, or topics, numbered key 1 through key 9. Each key represents a level within the hierarchy of the module. The key-1 name identifies the main topic of help information; for example, the name of a command in your program that requires explanation. The key-2 through key-9 names identify subtopics that are related to the key-1 name; for example, the command's parameters or qualifiers or both. This organization enables users of your program to find general information describing how to use the command and then to select subtopics that provide additional information about the command's parameters and qualifiers. The maximum length of a key-1 name is determined by the key size option of the /CREATE qualifier.

Index keywords remain in the format they were entered, that is, the character case is unchanged. A second keyword to the same library, identically spelled but of a different or mixed character case, replaces the previous preserved keyword. Character case is ignored for match operations. For example, help Sample and help SAMPLE access the same module.

The key names for help topics and subtopics can include any printable ASCII characters except those used by LIBRARIAN as either delimiters (space, horizontal tab, and comma) or comments (exclamation point).

HP recommends that you restrict key names to the following characters:

• Uppercase and lowercase letters (A,a,B,b...Z,z)
• Digits (0,1,2...9)
• Dollar sign ($)
• Underscore (_)
• Hyphen (-)

HP also recommends that you avoid---especially as the first character of a key name---certain characters that have special meaning to LIBRARIAN retrieval routines. If you use these characters in key names, you might not be able to specify them explicitly for retrieval.

The characters you should not use are as follows:

• Asterisk (*)
• Percent sign (%)
• Ellipsis (...)
• At sign (@)
• Slash (/)
• Question mark (?)
• Left parenthesis (() used as a first character
• Apostrophe (') and quotation marks (")

If a key contains any of these characters, you might be able to retrieve its help text by abbreviating the key to avoid the special characters or by using wildcard characters in their place. For information about using wildcard characters, see the OpenVMS User's Manual.

Also, note that you cannot abbreviate your retrieval key if it contains wildcard characters.

2.5.2 Formatting Help Files

Each line in a help module consists of the key number in the first column, followed by the name of the key. The subtopic lines that follow (key 2 through key 9) consist of the subkey number followed by the name of the subkey.For example, a help module for a command might have the following two key lines:

1 Command name . . . help text . . .2 Parameters

Each help source file can contain several modules. LIBRARIAN recognizes a group of key-1 and subkey lines and their associated text as a module. A module is terminated either by another key-1 line or by an end-of-file record.

A help source file has the following format:

1 key-1 name . . . help text . . .2 key-2 name . . . help text . . .n key-n name . . .1 key-1 name

LIBRARIAN stores the key-1 name in its module name table; therefore, the name of the module is the same as the key-1 name. The subsequent numbers in the first column indicate that the line is a subkey. A module can have several subkeys with the same number. For example, a help module describing a command might have the following key-2 lines:

2 parameters 2 arguments

You can insert comments anywhere in a module. When LIBRARIAN encounters an exclamation point as the first character on a line, it assumes that the line consists of comments. Comment lines that follow a key-1 line are included in the module. However, when your program retrieves help text, LIBRARIAN does not display the comments.

The help text can be any length; the only restriction to the text is that it cannot contain a number or a slash (/) in the first column of any line. A number in the first column of a line indicates that the line is a key. A slash in the first column indicates a qualifier line.

A qualifier line is similar to a key line, except that LIBRARIAN returns a list of all the qualifier lines when you request help either on a key-1 topic or on the key containing the qualifiers (usually a key-2 topic named "Qualifiers"). Therefore, if your help module describes a command that has qualifiers, LIBRARIAN provides a list of all the command's qualifiers whenever you request help on the command.

2.5.3 Help Text Example

Example 2-1 Help Text for LIBRARY Command

1 LIBRARY 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[,...]] 2 Command Parameters library-file-spec Specifies the name of the library you want to create or modify. If the file specification does not include a file type, the LIBRARY command assumes a default type of .OLB, indicating an object library. input-file-spec[,...] Specifies the names of one or more files that contain modules you want to insert or replace in the specified library. If you specify more than one input file, separate the file specifications with commas. The input-file-spec parameter 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-spec parameter is optional. If you include an input file specification with /CREATE, the LIBRARY command first creates a new library and then inserts the contents of the input files into the library. 2 Command_Qualifiers /BEFORE /BEFORE[=time] Used in conjunction with the /LIST qualifier to specify that only those modules dated earlier than a particular time be listed. You can specify an absolute time or a combination of absolute and delta times. If you omit the /BEFORE qualifier, all modules are listed regardless of date. If you specify /BEFORE without a date or time, all modules created before today are listed by default. /COMPRESS /COMPRESS[=(option[,...])] Recovers space that had been occupied by modules deleted from the library. When you specify /COMPRESS, the LIBRARY command by default creates a new version of the library in your current default directory. You can use options to the /COMPRESS qualifier to make some specifications in the new version of the library different from the original library. /CREATE /CREATE[=(option[,...])] Creates 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. By default, the LIBRARY command creates an object module library; specify /SHARE, /MACRO, /HELP, or /TEXT to change the default library type. . . .