HP OpenVMS Systems Documentation
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
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 global symbols defined in each of the library modules.
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).
For more information about the structure of libraries, see the
OpenVMS Utility Routines Manual.
2.3 Character Case of Library Keys
The character case of module names and global symbols in libraries depends on the library type:
A shareable 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. The linker issues a warning message if the GSMATCH ID of the library module is not equal to the GSMATCH IDs found in the corresponding shareable image. A warning message is also issued if the creation date or times found in the library differ from the shareable image. For more information about GSMATCH ID processing, see the description of the linker in the OpenVMS Linker Utility Manual.
You should note that a module inserted into a shareable image library
contains only the module header and end-of-module record, which are
extracted from the global symbol table of the input shareable image.
Consequently, although it is not an illegal 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 LIBRARIAN 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, uppercase and lowercase characters. A second keyword to the same library, identically spelled but of a different or mixed character case, replaces the previous preserved keyword. However, character case is ignored for match operations. For example, help Sample and help SAMPLE access the same file.
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).
Compaq recommends that you restrict key names to the following characters:
Compaq 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
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
2.5.3 Help Text Example
The help module in Example 2-1 shows the organization of some of the help text for the DCL command LIBRARY.
|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. . . .
You can retrieve help text at DCL level by using the DCL command HELP or, in your program, by calling the appropriate Librarian utility (LBR) routines (as described in the OpenVMS Utility Routines Manual).
By default, the HELP command retrieves help text from the system help library SYS$HELP:HELPLIB.HLB and from user help libraries associated with the logical names HLP$LIBRARY, HLP$LIBRARY_1, HLP$LIBRARY_2, and so forth. Using the /LIBRARY qualifier with the HELP command lets you search a library other than the default libraries. For more information, see the description of the HELP command in the OpenVMS DCL Dictionary.
When you retrieve help text, you specify the key-1 topic followed by any subtopics that contain appropriate help information. LIBRARIAN returns the help text associated with the key path you specify. For example, the help text for the LIBRARY command is stored in the default system help library; thus, to retrieve the LIBRARY command's key-1 help information, you would enter the DCL command HELP LIBRARY. LIBRARIAN would return the associated help text, followed by the message "Additional information available:" and a list of all the key-2 names in the module. In this case, LIBRARIAN also returns a list of all the qualifiers specified in the qualifier lines. Example 2-2 displays the text returned by the HELP LIBRARY command.
|Example 2-2 HELP LIBRARY Display|
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[,...]] Additional information available: Command_Parameters /ALPHA /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 /VAX /WIDTH
Note that you cannot retrieve the key-2 level "Parameters" by entering HELP PARAMETERS. LIBRARIAN searches for a subkey only after finding the higher level keys. In other words, if you want to retrieve key-3 text, you have to specify the key-1 and key-2 lines that form a path to the key-3 line.
Also note that you can provide information about a qualifier that has more than one form by associating two or more qualifier lines with the same help text. That is, the text associated with the qualifiers follows the two or more qualifier lines. For example:
$ HELP LIBRARY/GLOBALS
LIBRARY /GLOBALS /GLOBALS /NOGLOBALS 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. By default, the LIBRARY command places all global symbol names in the global symbol table. Use /NOGLOBALS if you do not want the global symbol names included in the global symbol table.
When LIBRARIAN successfully searches the key path to the requested key, it displays all the key names in that path, followed by the help text associated with the last specified key. For example:
$ HELP LIBRARY/HELP LIBRARY /HELP Indicates that the library is a help library. When you specify the /HELP qualifier, the library file type defaults to .HLB and the input file type defaults to .HLP.
If you try to retrieve help text for a key that is not in the module name table, LIBRARIAN issues a message. For example:
$ HELP FIRE Sorry, no documentation on FIRE Additional information available:
This message is followed by a list of all the module names in the module name table.
If you have correctly specified the key-1 line but have requested a subkey that does not exist, LIBRARIAN issues a message. For example:
$ HELP LIBRARY/FIRE Sorry, no documentation on LIBRARY/FIRE Additional information available: Parameters Command_Qualifiers /BEFORE /COMPRESS . . .