Document revision date: 19 July 1999

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. This section describes how to use the Librarian utility (LIBRARIAN) to create, access, and maintain libraries.

2.1 Types of Libraries

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 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.
  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 LIBRARIAN 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 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.
• 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

2.2 Structure of Libraries

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 contains information 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 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:

• 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 global symbols are in the format in which they were entered. A second, identical keyword (but of a different or mixed character case) to the same library initiates a separate keyword; the previous keyword is not replaced. 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 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).

Digital 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 (-)

Digital 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

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

2.5.4 Retrieving Help Text

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

The message includes a list of all the subkeys associated with the last key that was specified correctly.

	privacy and legal statement
6100PRO_005.HTML