OpenVMS DCL Dictionary

The EXIT command in this example is used as the target of an ON command; this statement ensures that the command procedure terminates whenever any warnings or errors are issued by any command in the procedure.

The procedure exits with the status value of the command or program that caused the termination. #3

$ START: 
$        IF (P1 .EQS. "TAPE") .OR. (P1 .EQS. "DISK") THEN GOTO 'P1' 
$        INQUIRE P1 "Enter device (TAPE or DISK)" 
$        GOTO START 
$ TAPE: !  Process tape files 
   .
   .
   .
$        EXIT 
$ DISK:  ! Process disk files 
   .
   .
   .
$        EXIT

The command procedure in this example shows how to use the EXIT command to terminate different command paths within the procedure. To execute the procedure, you must enter either TAPE or DISK as a parameter. The IF command uses a logical OR to test whether either of these strings was entered. If the result is true, the GOTO command branches to the corresponding label. If P1 was neither TAPE nor DISK, the INQUIRE command prompts for a correct parameter.
The commands following each of the labels TAPE and DISK provide different paths through the procedure. The EXIT command before the label DISK ensures that the commands after the label DISK are executed only if the procedure explicitly branches to DISK.
Note that the EXIT command at the end of the procedure is not required because the end of the procedure causes an implicit EXIT command. Use of the EXIT command, however, is recommended.

$ IF P1. EQS. "" THEN - 
     INQUIRE P1 "Enter filespec (null to exit)" 
$ IF P1 .EQS. "" THEN EXIT 
$ PRINT 'P1'/AFTER=20:00/COPIES=50/FORMS=6

The command procedure in this example tests whether a parameter was passed to it; if the parameter was not passed, the procedure prompts for the required parameter. Then it retests the parameter P1. If a null string, indicated by a carriage return for a line with no data, is entered, the procedure exits. Otherwise, it executes the PRINT command with the current value of P1 as the input parameter.

$ IF P1 .EQS. "" THEN INQUIRE P1 "Code" 
$ CODE = %X'P1' 
$ EXIT CODE

The command procedure in this example, E.COM, illustrates how to determine the system message, if any, associated with a hexadecimal system status code. The procedure requires a parameter and prompts if none is entered. Then it prefixes the value with the radix operator %X and assigns this string to the symbol CODE. Finally, it issues the EXIT command with the hexadecimal value. The following example uses the procedure E.COM:
$ @E 1C
%SYSTEM-F-EXQUOTA, exceeded quota
When the procedure exits, the value of $STATUS is %X1C, which equates to the EXQUOTA message. Note that you can also use the F$MESSAGE lexical function to determine the message that corresponds to a status code.

$ RUN MYPROG
[Ctrl/Y]
$ EXIT

In this interactive example, the RUN command initiates execution of the image MYPROG.EXE. Then pressing Ctrl/Y interrupts the execution. The EXIT command that follows calls any exit handlers declared by the image before terminating MYPROG.EXE.

FONT

Converts an ASCII bitmap distribution format (BDF) into binary portable compiled format (PCF) on Alpha systems and into binary server natural form (SNF) on VAX systems. The DECwindows server uses a PCF or SNF file to display a font. In addition to converting the BDF file to binary form, the font compiler provides statistical information about the font and the compilation process. For more information about using the font compiler, refer to the online help or the OpenVMS DECwindows programming documentation.

Format

FONT filespec

GOSUB

Transfers control to a labeled subroutine in a command procedure without creating a new procedure level.

Format

GOSUB label

PARAMETER

label
Specifies a label of 1 to 255 alphanumeric characters that appears as the first item on a command line. A label may not contain embedded blanks. When the GOSUB command is executed, control passes to the command following the specified label.
The label can precede or follow the GOSUB statement in the current command procedure. When you use a label in a command procedure, it must be terminated with a colon (:). If you use duplicate labels, control is always given to the label most recently read by DCL.

DESCRIPTION

Use the GOSUB command in command procedures to transfer control to a subroutine specified by the label. If the command stream is not being read from a random-access device (that is, a disk device), the GOSUB command performs no operation.
The RETURN command terminates the GOSUB subroutine procedure, returning control to the command following the calling GOSUB statement. The RETURN command accepts an optional status value.
The GOSUB command does not cause the creation of a new procedure level. Therefore, it is referred to as a "local" subroutine call. Any labels and local symbols defined in the current command procedure level are available to a subroutine invoked with a GOSUB command. The GOSUB command can be nested up to a maximum of 16 levels per procedure level.
When the command interpreter encounters a label, it enters the label in a label table. This table is allocated from space available in the local symbol table. If the command interpreter encounters a label that already exists in the table, the new definition replaces the existing one. Therefore, if you use duplicate labels, control is always given to the label most recently read by DCL. The following rules apply:

If duplicate labels precede and follow the GOSUB command, control is given to the label preceding the command.
If duplicate labels all precede the GOSUB command, control is given to the most recent label, that is, the one nearest the GOSUB command.
If duplicate labels all follow the GOSUB command, control is given to the one nearest the GOSUB command.
If a label does not exist in the current command procedure, the procedure cannot continue and is forced to exit.
Note that the amount of space available for labels is limited. If a command procedure uses many symbols and contains many labels, the command interpreter may run out of table space and issue an error message.

Example

$! 
$! GOSUB.COM 
$! 
$ SHOW TIME 
$ GOSUB TEST1 
$ WRITE SYS$OUTPUT "success completion" 
$ EXIT 
$! 
$! TEST1 GOSUB definition 
$! 
$ TEST1: 
$     WRITE SYS$OUTPUT "This is GOSUB level 1." 
$     GOSUB TEST2 
$     RETURN %X1 
$! 
$! TEST2 GOSUB definition 
$! 
$ TEST2: 
$     WRITE SYS$OUTPUT "This is GOSUB level 2." 
$     GOSUB TEST3 
$     RETURN 
$! 
$! TEST3 GOSUB definition 
$! 
$ TEST3: 
$     WRITE SYS$OUTPUT "This is GOSUB level 3." 
$     RETURN

This sample command procedure shows how to use the GOSUB command to transfer control to labeled subroutines. The GOSUB command transfers control to the subroutine labeled TEST1. The procedure executes the commands in subroutine TEST1, branching to the subroutine labeled TEST2. The procedure then executes the commands in subroutine TEST2, branching to the subroutine labeled TEST3. Each subroutine is terminated by the RETURN command. After TEST3 is executed, the RETURN command returns control back to the command line following each calling GOSUB statement. At this point, the procedure has been successfully executed.

GOTO

Transfers control to a labeled statement in a command procedure.

Format

GOTO label

PARAMETER

label
Specifies a label of 1 to 255 alphanumeric characters that appears as the first item on a command line. A label cannot contain embedded blanks. When the GOTO command is executed, control passes to the command following the specified label.
When you use a label in a command procedure, it must be terminated with a colon (:). If you use duplicate labels, control is always given to the label most recently read by DCL.

DESCRIPTION

Use the GOTO command in command procedures to transfer control to a line that is not the next line in the procedure. The label can precede or follow the GOTO statement in the current command procedure. If the command stream is not being read from a random-access device (that is, a disk device), the GOTO command performs no operation.
If the target label of a GOTO command is inside a separate IF-THEN-ELSE construct, an error message (DCL-W-USGOTO) is returned.
When the command interpreter encounters a label, it enters the label in a label table. This table is allocated from space available in the local symbol table. If the command interpreter encounters a label that already exists in the table, the new definition replaces the existing one. Therefore, if you use duplicate labels, control is always given to the label most recently read by DCL. In general:

If duplicate labels precede and follow the GOTO command, control is given to the label preceding the command.
If duplicate labels all precede the GOTO command, control is given to the most recent label, that is, the one nearest the GOTO command.
If duplicate labels all follow the GOTO command, control is given to the one nearest the GOTO command.

If a label does not exist in the current command procedure, the procedure cannot continue and is forced to exit.
Note that the amount of space available for labels is limited. If a command procedure uses many symbols and contains many labels, the command interpreter may run out of table space and issue an error message.

Examples

$ IF P1 .EQS. "HELP" THEN GOTO TELL 
$ IF P1 .EQS. "" THEN GOTO TELL 
   . 
   . 
   . 
$ EXIT 
$ TELL: 
$ TYPE SYS$INPUT 
To use this procedure, you must enter a value for P1. 
   . 
   . 
   . 
$ EXIT

In this example, the IF command checks the first parameter passed to the command procedure; if this parameter is the string HELP or if the parameter is not specified, the GOTO command is executed and control is passed to the line labeled TELL. Otherwise, the procedure continues executing until the EXIT command is encountered. At the label TELL, a TYPE command displays data in the input stream that documents how to use the procedure.

$ ON ERROR THEN GOTO CHECK 
   . 
   . 
   . 
$ EXIT 
$ CHECK:  ! Error handling routine 
   . 
   . 
   . 
$ END: 
$ EXIT

The ON command establishes an error-handling routine. If any command or procedure subsequently executed in the command procedure returns an error or severe error, the GOTO command transfers control to the label CHECK.

HELP

The HELP command invokes the HELP Facility to display information about use of the system, including formats and explanations of commands, parameters, qualifiers and system messages. In response to the Topic? prompt, you can:

Type the name of the command or topic for which you need help.
Type INSTRUCTIONS for more detailed instructions on how to use HELP.
Type HINTS if you are not sure of the name of the command or topic for which you need help.
Type /MESSAGE for help with the HELP/MESSAGE utility.
Type a question mark (?) to redisplay the most recently requested text.
Press the RETURN key one or more times to exit from HELP.

You can abbreviate any topic name, although ambiguous abbreviations result in all matches being displayed.

Format

HELP [topic[subtopic...]]

PARAMETER

topic[subtopic...]
Specifies the topics or topic and subtopics on which you want information from a help library.

DESCRIPTION

Information within help libraries is arranged in a hierarchical manner. The levels are as follows:

None---If you do not specify a keyword, the Help facility describes the HELP command and lists the topics that are documented in the root library. Each item in the list is a keyword in the first level of the hierarchy.
Topic-name---If you specify a keyword by naming a topic, the Help facility describes the topic as it is documented in either the root library or in one of the other enabled default libraries. Keywords for additional information available on this topic are listed.
Topic-name subtopic---If you specify a subtopic following a topic, the Help facility provides a description of the specified subtopic.
@filespec followed by any of the previous levels---If you specify a help library to replace the current root library, the Help facility searches that library for a description of the topic or subtopic specified. The file specification must take the same form as the file specification included with the /LIBRARY command qualifier. However, if the specified library is an enabled user-defined default library, the file specification can be abbreviated to any unique leading substring of that default library's logical name translation.

To use the Help facility on OpenVMS in its simplest form, enter the HELP command from your terminal. The Help facility displays a list of topics at your terminal and the prompt Topic?. To see information on one of the topics, type the topic name after the prompt. The system displays information on that topic.
If the topic has subtopics, the HELP command lists the subtopics and displays the Subtopic? prompt. To get information on one of the subtopics, type the name after the prompt. To see information on another topic, press the Return key. You can now ask for information on another topic when the Help facility displays the Topic? prompt. Press the Return key to exit the Help facility and return to DCL command level.
If you use an asterisk (*) in place of any keyword, the HELP command displays all information available at the level that the asterisk replaces. For example, HELP COPY * displays all the subtopics under the topic COPY.
If you use an ellipsis (...) immediately after any primary keyword, the Help facility displays all the information on the specified topic and all subtopics of that topic. For example, HELP COPY...displays information on the COPY topic as well as information on all the subtopics under COPY. The ellipsis can only be used from the topic level; it cannot be used from the subtopic level.
The asterisk (*) and the percent sign (%) wildcard characters are allowed in the keyword.

QUALIFIERS

/EXACT
Use with the /PAGE=SAVE and /SEARCH qualifiers to specify a search string that must match the search string exactly and must be enclosed with quotation marks (" ").
If you specify the /EXACT qualifier without the /SEARCH qualifier, exact search mode is enabled when you set the search string with the Find (E1) key.
/HIGHLIGHT[=keyword]

/NOHIGHLIGHT (default)
Use with the /PAGE=SAVE and /SEARCH qualifiers to specify the type of highlighting you want when a search string is found. When a string is found, the entire line is highlighted. You can use the following keywords: BOLD, BLINK, REVERSE, and UNDERLINE. BOLD is the default highlighting.
/INSTRUCTIONS (default)

/NOINSTRUCTIONS
Displays an explanation of the HELP command along with the list of topics (if no topic is specified). By default, the HELP command display includes a description of the facility and the format, along with the list of topics. If you specify the /NOINSTRUCTIONS qualifier, only the list of topics is displayed.
/LIBLIST (default)

/NOLIBLIST
Displays any auxiliary help libraries.
/LIBRARY=filespec

/NOLIBRARY
Uses an alternate help library instead of the default system library, SYS$HELP:HELPLIB.HLB. The specified library is used as the main (root) help library, and is searched for Help facility information before any user-defined default help libraries are checked.
If you omit the device and directory specification, the default is SYS$HELP, the logical name of the location of the system help libraries. The default file type is .HLB.
The /NOLIBRARY qualifier excludes the default help library from the library search order.
/MESSAGE
Displays descriptions of system messages. See the HELP/MESSAGE command in this manual.
/OUTPUT[=filespec]

/NOOUTPUT
Controls where the output of the command is sent. By default, the output is sent to SYS$OUTPUT, the current process default output stream or device.
If you enter the /OUTPUT qualifier with a partial file specification (for example, /OUTPUT=[JONES]), HELP is the default file name and LIS is the default file type. The asterisk (*) and the percent sign (%) wildcard characters are not allowed.
If you enter the /NOOUTPUT qualifier, output is suppressed.
/PAGE[=keyword]

/NOPAGE (default)
Controls the display of information on the screen.
You can use the following keywords with the /PAGE qualifier:

CLEAR_SCREEN Clears the screen before each page is displayed.

SCROLL Displays information one line at a time.

SAVE[= n] Enables screen navigation of information, where n is the number of pages to store.

The /PAGE=SAVE qualifier allows you to navigate through screens of information. The /PAGE=SAVE qualifier stores up to 5 screens of up to 255 columns of information. When you use the /PAGE=SAVE qualifier, you can use the following keys to navigate through the information:

Key Sequence Description

Up arrow (<uparrow symbol>), Ctrl/B Scroll up one line.

Down arrow (<downarrow symbol>) Scroll down one line.

Left arrow ( <-) Scroll left one column.

Right arrow (->) Scroll right one column.

Find (E1) Specify a string to find when the information is displayed.

Insert Here (E2) Scroll right one half screen.

Remove (E3) Scroll left one half screen.

Select (E4) Toggle 80/132 column mode.

Prev Screen (E5) Get the previous page of information.

Next Screen (E6), Return, Enter, Space Get the next page of information.

F10, Ctrl/Z Exit. (Some utilities define these differently.)

Help (F15) Display utility help text.

Do (F16) Toggle the display to oldest/newest page.

Ctrl/W Refresh the display.

The /PAGE qualifier is not compatible with the /OUTPUT qualifier.
/PROMPT (default)

/NOPROMPT
Permits you to solicit further information interactively. If you specify the /NOPROMPT qualifier, the Help facility returns you to DCL command level after it displays the requested information.
If the /PROMPT qualifier is in effect, one of four different prompts is displayed, requesting you to specify a particular help topic or subtopic. Each prompt represents a different level in the hierarchy of help information. The four prompt levels are as follows:

Topic?---The root library is the main library and you are not currently examining the Help facility information for a particular topic.
[library-spec] Topic?---The root library is a library other than the main library and you are not currently examining the Help facility information for a particular topic.
[keyword] Subtopic?---The root library is the main library and you are currently examining the Help facility information for a particular topic (or subtopic).
A combination of 2 and 3.

When you encounter one of these prompts, you can enter any one of the responses described in the following table:

Response Current Prompt Environment Action

keyword[...] 1,2 Searches all enabled libraries for the keyword.

3,4 Searches additional help libraries for the current topic (or subtopic) for the keyword.

@filespec
keyword[...] 1,2 Same as above, except that the library specified by @filespec is now the root library. If the specified library does not exist, the Help facility treats @filespec as a normal keyword.
Displays a list of topics available in the root library.

3,4 Same as above; treats @filespec as a normal keyword.
Displays the list of subtopics of the current topic (or subtopics) for which help exists.

[Return] 1 Exits from the Help facility.

2 Changes root library to main library.

3,4 Prompts for a topic or subtopic at the next higher level.

[Ctrl/Z] 1,2,3,4 Exits from the Help facility.

/SEARCH="string"
Use with the /PAGE=SAVE qualifier to specify a string that you want to find in the information being displayed. Quotation marks are required for the /SEARCH qualifier, if you include spaces in the text string.
You can also dynamically change the search string by pressing the Find key (E1) while the information is being displayed. Quotation marks are not required for a dynamic search.
/USERLIBRARY=(level[,...])

/NOUSERLIBRARY
Names the levels of search for information in auxiliary libraries. The levels are as follows:

PROCESS Libraries defined at process level

GROUP Libraries defined at group level

SYSTEM Libraries defined at system level

ALL All libraries (default)

NONE No libraries (same as the /NOUSERLIBRARY qualifier)

Auxiliary help libraries are libraries defined with the logical names HLP$LIBRARY, HLP$LIBRARY_1, HLP$LIBRARY_2, and so on. Libraries are searched for information in this order: root (current) library, main library (if not current), libraries defined at process level, libraries defined at group level, libraries defined at system level, and the root library. If the search fails, the root library is searched a second time so that the context is returned to the root library from which the search was initiated. The default is the /USERLIBRARY=ALL qualifier. If you specify only one level for the Help facility to search, you can omit the parentheses.
/WRAP

/NOWRAP (default)
Use with the /PAGE=SAVE qualifier to limit the number of columns to the width of the screen and to wrap lines that extend beyond the width of the screen to the next line.
The /NOWRAP qualifier extends lines beyond the width of the screen and can be seen when you use the scrolling (left and right) features provided by the /PAGE=SAVE qualifier.

Key Sequence	Description
Up arrow (<uparrow symbol>), Ctrl/B	Scroll up one line.
Down arrow (<downarrow symbol>)	Scroll down one line.
Left arrow ( <-)	Scroll left one column.
Right arrow (->)	Scroll right one column.
Find (E1)	Specify a string to find when the information is displayed.
Insert Here (E2)	Scroll right one half screen.
Remove (E3)	Scroll left one half screen.
Select (E4)	Toggle 80/132 column mode.
Prev Screen (E5)	Get the previous page of information.
Next Screen (E6), Return, Enter, Space	Get the next page of information.
F10, Ctrl/Z	Exit. (Some utilities define these differently.)
Help (F15)	Display utility help text.
Do (F16)	Toggle the display to oldest/newest page.
Ctrl/W	Refresh the display.

Response	Current Prompt Environment	Action
keyword[...]	1,2	Searches all enabled libraries for the keyword.
	3,4	Searches additional help libraries for the current topic (or subtopic) for the keyword.
@filespec keyword[...]	1,2	Same as above, except that the library specified by @filespec is now the root library. If the specified library does not exist, the Help facility treats @filespec as a normal keyword. Displays a list of topics available in the root library.
	3,4	Same as above; treats @filespec as a normal keyword. Displays the list of subtopics of the current topic (or subtopics) for which help exists.
`[Return]`	1	Exits from the Help facility.
	2	Changes root library to main library.
	3,4	Prompts for a topic or subtopic at the next higher level.
`[Ctrl/Z]`	1,2,3,4	Exits from the Help facility.

Examples

$ HELP
HELP
  .
  .  (HELP message text and list of topics)
  .
Topic?

In this example, the HELP command is entered without any qualifiers or parameters. This example produces a display of the help topics available from the root help library, SYS$HELP:HELPLIB.HLB.
If you enter one of the listed topics in response to the Topic? prompt, the Help facility displays information about that topic and a list of subtopics (if there are any). If one or more subtopics exist, the Help facility prompts you for a subtopic, as follows:
Topic? ASSIGN
ASSIGN
  .
  .  (HELP message text and subtopics)
  .
ASSIGN Subtopic?
If you type a subtopic name, the Help facility displays information about that subtopic, as follows:
ASSIGN Subtopic? Name
ASSIGN
  Name
  .
  .  (HELP message text and subtopics, if any)
  .
ASSIGN Subtopic?
If one or more sub-subtopics exist, the Help facility prompts you for a sub-subtopic; otherwise, as in the previous example, the facility prompts you for another subtopic of the topic you are currently inspecting.
Entering a question mark (?) redisplays the Help facility message and options at your current level. Pressing the Return key does either of the following:

Moves you back to the previous help level if you are in a subtopic level.
Terminates the Help facility if you are at the first level.

Pressing Ctrl/Z terminates the Help facility at any level.

$ HELP COPY...

The HELP command in this example displays a description of the COPY command and of the command's parameters and qualifiers. Note that the ellipsis can be used only from the topic level; it cannot be used from the subtopic level.

$ HELP/NOPROMPT ASSIGN/GROUP
  .
  .  (ASSIGN/GROUP HELP message)
  .
$
$ HELP/NOPROMPT/PAGE EDIT *
  .
  .  (HELP messages on all first-level EDIT subtopics)
  .
$

The two HELP commands request help on specific topics. In each case, the HELP command displays the help message you request and then returns you to DCL command level and the dollar sign prompt ($).
The first command requests help on the /GROUP qualifier of the ASSIGN command. The asterisk (*) in the second example is a wildcard character. It signals the Help facility to display information about all EDIT subtopics, which are then displayed in alphabetical order. The /NOPROMPT qualifier suppresses prompting in both sample commands. The /PAGE qualifier on the second HELP command causes output to the screen to stop after each screen of information is displayed.

$ HELP FILL
Sorry, no documentation on FILL
Additional information available:
 .
 .  (list of first-level topics )
 .
Topic? @EDTHELP FILL
FILL
 .
 .  (FILL HELP message)
 .
@EDTHELP Topic?

When you enter a request for help on a topic that is not in the default help library, you can instruct the Help facility to search another help library for the topic. In this example, entering the command @EDTHELP FILL instructs the Help facility to search the help library SYS$HELP:EDTHELP.HLB for information on FILL, an EDT editor command. The Help facility displays the message and prompts you for another EDT editor topic.

$ SET DEFAULT SYS$HELP
$ DEFINE HLP$LIBRARY EDTHELP
$ DEFINE HLP$LIBRARY_1 MAILHELP
$ DEFINE HLP$LIBRARY_2 BASIC
$ DEFINE HLP$LIBRARY_3 DISK2:[MALCOLM]FLIP
$ HELP REM

You can use logical names to define libraries for the Help facility to search automatically if it does not find the specified topic in the OpenVMS root help library. This sequence of commands instructs the Help facility to search libraries in addition to the default root library, SYS$HELP:HELPLIB.HLB.

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  9996P017.HTM
  OSSG Documentation
  26-NOV-1996 11:17:19.01
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

CLEAR_SCREEN	Clears the screen before each page is displayed.
SCROLL	Displays information one line at a time.
SAVE[= n]	Enables screen navigation of information, where n is the number of pages to store.

PROCESS	Libraries defined at process level
GROUP	Libraries defined at group level
SYSTEM	Libraries defined at system level
ALL	All libraries (default)
NONE	No libraries (same as the /NOUSERLIBRARY qualifier)