HP OpenVMS Systems Documentation
HP OpenVMS Command Definition, Librarian, and Message Utilities Manual
You now have a file containing an executable image (USEREXAMP.EXE). To execute the image, enter the following command:
USEREXAMP.EXE displays the following prompt on your screen:
You can now enter any of the commands you defined in TEST.CLD. For example:
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:
You can also include a parameter with the SEND command. For example:
DCL invokes the SEND_COMMAND routine, which displays the following text:
You can also enter the /EDIT qualifier with SEND. For example:
You can enter other commands that your program accepts. For example:
The SEARCH command string invokes a different routine from the one defined by SEND. In this case, the screen displays the following text:
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:
To exit from the USEREXAMP program and return to the DCL command level, issue the EXIT command:
$ LIBRARY/CREATE/OBJECT LIB.xxx *.obj
$ LIBRARY/LIST LIB.xxx
Table 2-1 shows the libraries that are created by the Librarian utility for each 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|
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.
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:
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:
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.
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
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.
|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. . . .