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

OpenVMS User's Manual

Previous Contents Index

12.14.1 Using Automatic Foreign Commands

Note the following:


If you are a privileged user and set your default device and directory to other user accounts, you should not place "SYS$DISK:[]" in the definition of the DCL$PATH logical name. Doing so will cause DCL to search the current directory, where a typographical error or poor placement of the translation within the search list could cause user images in the current directory to be found and mistakenly invoked with privileges.

12.14.2 Automatic Foreign Command Restrictions

Note the following restrictions:

Chapter 13
Introduction to Command Procedures

A command procedure is a file that contains DCL commands and data lines used by DCL commands. Some simple command procedures might contain only one or two DCL commands; complex command procedures can function as sophisticated computer programs. When a command procedure runs, the DCL interpreter reads the file and executes the commands it contains.

If your system manager has set up a system login command procedure, it is executed whenever you log in. A system login command procedure lets your system manager ensure that certain commands are always executed when you and other users on the system log in.

After running the system login command procedure, the system runs your personal login command procedure, if one exists. Your personal login command procedure lets you customize your computing environment. The commands contained in it are executed every time you log in. When you log in, the system automatically executes up to two login command procedures (the systemwide login command procedure and your own login command procedure, if it exists).

The person who sets up your account might have placed a login command procedure in your top-level directory. If a login command procedure is not in your top-level directory, you can create one yourself. Name it LOGIN.COM and place it in your top-level directory. Unless your system manager tells you otherwise, the LOGIN.COM file that you create will run whenever you log in.

This chapter is divided into major sections that include the following:

There are two types of DCL command procedures:

13.1 Basic Information for Writing Command Procedures

There are two ways to create command procedures:

The file that you create can contain command lines, labels, comments, conditional statements, and variables.

13.1.1 Default File Type

The default file type for command procedures is .COM. If you specify the .COM file type when you name a command procedure, you can execute the procedure by specifying the file name only. The SUBMIT and execute procedure (@) commands assume the file type is .COM unless you specify otherwise.

13.1.2 Writing Commands

The following are suggestions for including commands in command procedures:

13.1.3 Writing Command Lines

When writing command lines:

Note that command lines that do not begin with a dollar sign might be correctly interpreted by DCL, but Compaq strongly recommends that any DCL command line start with a dollar sign.

13.2 Using Labels in Command Lines

Labels are used in DCL command procedures to mark the beginning of loops, sections of code, or subroutines. Note the following rules when using labels:

13.2.1 Labels in Local Symbol Tables

As the command interpreter encounters labels, it enters them in a special section of the local symbol table. The amount of space available for labels is limited. If a command procedure uses many symbols and contains many labels, the command interpreter might run out of symbol table space and issue an error message. If this occurs, include the DELETE/SYMBOL command in your procedure to delete symbols as they are no longer needed. (Note, however, that you cannot delete labels.)

13.2.2 Duplicate Labels

If a command procedure uses the same label more than once, the new definition replaces the existing one in the local symbol table.

When duplicate labels exist, the GOTO command transfers control to the label that DCL has processed most recently. The GOTO command also uses the following rules when processing duplicate labels:

13.3 Using Comments in Command Procedures

It is good programming practice to include comments in command procedures. Comments can be helpful when updating or troubleshooting the command procedure. Comments can be used as follows:

The following rules apply when writing comments in command procedures:

13.4 How to Write Command Procedures

Before you begin writing a command procedure, perform the tasks interactively that the command procedure will execute. As you type the necessary commands, note any variables and conditionals that are used, and any iterations that occur.

The following sections contain the steps to write a simple command procedure. The example used throughout these sections is a command procedure called CLEANUP.COM. This procedure can be used to clean up a directory.


13.5 Steps for Writing Command Procedures

Follow these steps to write a command procedure:
Step Task
1 Design the command procedure.
2 Assign variables and test conditionals.
3 Add loops.
4 End the command procedure.
5 Test and debug the program logic.
6 Add cleanup tasks.
7 Finish the procedure.

13.5.1 Step 1: Design the Command Procedure

Follow these steps to design a command procedure:
Step Task
1 Decide which tasks your procedure will perform.
2 Determine any variables your command procedure will use and how they will be loaded.
3 Determine what conditionals the command procedure requires and how you will test them.
4 Decide how you will exit from the command procedure.

There are certain commands that are usually executed during clean up operations. The following table lists those commands and the tasks that they perform:
Command Task Performed
DIRECTORY Displays the contents of the current directory
TYPE filespec Displays a file
PURGE filespec Purges a file
DELETE filespec Deletes a file
COPY filespec new-filespec Copies a file


Any data that changes when you perform a task is a variable. If you create or delete files in your directory, the file names will be different each time you clean your directory; therefore, the file names in CLEANUP.COM are variables.


Any command that must be tested each time you execute a command procedure is considered conditional. Because any or all of the commands in CLEANUP.COM might be executed, depending on the operation you need to perform, each command is conditional.

Design Decisions

After you have determined what variables and conditionals you will use in the CLEANUP.COM command procedure, you must decide how to load the variables, test the conditionals, and exit from the command procedure. For the CLEANUP.COM command procedure, the following decisions have been made:
Task How Accomplished
Load variables The command procedure gets the file names from the terminal.
Test conditionals The command procedure:
  • Gets a command name from the terminal and executes the appropriate statements based on the command name.
  • Ensures that the first two characters of each command name are read to differentiate between the DELETE and DIRECTORY commands.
Exit from loop You must enter the EXIT command to exit from the loop.

To make command procedures easier to understand and maintain, write statements so the procedures execute from the first command to the last command.

13.5.2 Step 2: Assign Variables and Test Conditionals

There are many ways to assign values to variables. In this section, we will discuss using the INQUIRE command. For additional methods, see Chapter 14.

Follow these steps to assign values to variables and test conditionals:
Step Task
1 Assign values to variables using the INQUIRE command.
2 Determine which action should be taken.
3 Test the conditional using IF and THEN statements.
4 Write program stubs and insert them into the command procedure as placeholders for commands.
5 Write error messages, if necessary. Using the INQUIRE Command

The INQUIRE command prompts for a value, reads the value from the terminal, and assigns the value to a symbol.

By default, the INQUIRE command:

The following command line is used in CLEANUP.COM to prompt the user for a command name. The INQUIRE command equates the value entered to the symbol COMMAND.

  "Enter command (DELETE, DIRECTORY, PRINT, PURGE, TYPE)" Preserving Literal Characters

To preserve lowercase characters, multiple spaces and tabs when using the INQUIRE command, enclose your response in quotation marks (" "). To include quotation marks in your response, enclose the quoted text in quotation marks (""text""). Testing Conditionals Using IF and THEN

After the INQUIRE command prompts for a variable, the command procedure must include a statement that determines what action is to be taken. For example, to determine which command to execute, you must include statements in the command procedure that check the command entered by the user against each possible command.

To test whether a condition is true, use the IF and THEN commands. The following table shows the possibilities that you must check for in CLEANUP.COM:
If... Then...
a match is found, execute the command.
a match is not found, go on to the next command.
no match is found after all valid commands have been checked, output an error message. Writing Program Stubs

A program stub is a temporary section of code that you use in your procedure while you test the design. Usually, a program stub outputs a message stating the function that it is replacing. After the overall design works correctly, replace each stub with the correct coding.

Example: Assigning Variables and Testing Conditionals

The following example shows how to assign variables and test conditionals:

$! Execute if user entered DELETE 
$    WRITE SYS$OUTPUT "This is the DELETE section."       (3)
$! Execute if user entered DIRECTORY 
$ DIRECTORY:                                              (4)
$    WRITE SYS$OUTPUT "This is the DIRECTORY section." 
$! Execute if user entered TYPE 
$ TYPE: 
$    IF COMMAND .NES "TYPE" THEN GOTO ERROR               (5)
$    WRITE SYS$OUTPUT "This is the TYPE section." 
$    WRITE SYS$OUTPUT "You have entered an invalid command." (6)

As you examine the example, note the following:

  1. This IF statement tests to see if the command that the user entered (COMMAND) is equal to "DELETE". If COMMAND is equal to DELETE, then the command procedure executes the next command.
  2. This statement also includes a GOTO command. A GOTO command is used to change the flow of execution to a label in the procedure. In this case, the procedure will go to the DIRECTORY label if COMMAND is not equal to DELETE.
  3. This statement is a program stub. After the logic of the command procedure is tested, this line will be replaced with the actual commands required for a DELETE operation.
  4. This is the label for the DIRECTORY subroutine. Note that the labels that identify each command block are the same as the commands on the option list. This allows you to use the symbol COMMAND (which is equated to the user's request) in the GOTO statement.
  5. This IF statement tests to see if the "TYPE" command was entered. If "TYPE" was entered, the procedure will output "This is the TYPE section." However, because this is the last command you will be testing for, if the command entered is not "TYPE," the program will display an error message.
  6. If all commands have been tested and no valid command name is found, then the program will output, "You have entered an invalid command."

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