HP OpenVMS Systems Documentation

OpenVMS User's Manual

Only the node, device, and directory portions of each translation
of the logical name are used.

Normal logical precedence takes place. Users can override a system
definition of DCL$PATH by defining their own. If a system definition
exists and the user does not want the feature, it can be turned off by
overriding the logical with a definition of " ".

The set of valid characters for DCL verbs and symbol names differs
from the set of valid characters for file names. For example, DCL
symbols cannot contain a hyphen (-) or start with a dollar sign ($). If
the image or procedure you wish to execute is not valid as a DCL symbol
name, it cannot be directly invoked by this new feature.

DCL has not parsed the command. It is up to the image being invoked
to perform its own command parsing. For C programs, use the "argc" and
"argv" parameters to the main() routine. For programs written in other
languages, call LIB$GET_FOREIGN to obtain the entire command line,
which must then be parsed by the program.

If a directory contains both a command procedure and an executable
image, whichever file is found first will be invoked. On OpenVMS
systems, directories are in alphabetical order, so a ".COM" file will
be found before a ".EXE" file. A network file specification in the
DCL$PATH logical pointing to a node running some other operating
systems could result in a ".EXE" file being found before a ".COM" file.
Because DCL performs the search with the invalid verb as the file
specification and "DCL$PATH:.*" as the default file specification, it
is possible to define a logical in such a way that a specific file is
found. For example, if you define the logical FOO to be "FOO.EXE", and
type "FOO" at the DCL prompt, you will never invoke FOO.COM, only
FOO.EXE.

Caution

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.

You cannot use automatic foreign commands on any versions of the
OpenVMS operating system prior to Version 6.2.

Because new verbs can be added to the DCL command table at any
time, a command that works with automatic foreign commands one day may
not work at a later date.

The automatic foreign commands feature does not work in all cases.
In the following example, DCL (which looks only at the first four
characters of any verb) finds a match with the SHOW verb (the first
four letters of SHOWME) and executes the SHOW USERS command instead of
the SHOWME.COM procedure. If you defined SHOWME as a DCL symbol, then
the SHOWME command would invoke SHOWME.COM.

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:

Basic information for writing command procedures

Step-by-step procedure for writing command procedures

Executing command procedures

Exiting, interrupting, and error handling command procedures

Login command procedures

There are two types of DCL command procedures:

Simple Execute a series of DCL commands in the order in which
they are written

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.

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

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:

At the beginning of a procedure to describe the procedure and the
parameters passed to it.

At the beginning of each block of commands to describe that section
of the procedure.

To separate command sequences with lines containing both a dollar
sign and an exclamation point ($!). This makes it easier to see the
outline of the command procedure. If you insert blank lines, the
command interpreter interprets them as data lines and produces a
message warning you that the data lines were ignored.

The following rules apply when writing comments in command procedures:

Use an exclamation point (!) to indicate the beginning of a
comment; the command interpreter ignores all text to the right of an
exclamation point when the command procedure executes.

To include a literal exclamation point in a command line, enclose
the exclamation point in quotation marks (" ").

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.

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.

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.

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:

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.

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.

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.

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.

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.

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.

If all commands have been tested and no valid
command name is found, then the program will output, "You have entered
an invalid command."