Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Command Definition, Librarian, and Message Utilities Manual


Previous Contents Index


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 


Chapter 2
Librarian Utility

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:

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:

2.4 Shareable Image Libraries

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:

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:

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.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6100PRO_005.HTML