Digital PDFs

AA-LA11A-TE

December 1988

179 pages

Original

6.9MB

Document:	Guide to Using VMS 5.0 Command Procedures 198804
Order Number:	AA-LA11A-TE
Revision:
Pages:	179
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/5.0/AA-LA11A-TE_Guide_to_Using_VMS_5.0_Command_Procedures_198804.pdf

OCR Text

VMS
•

digital

Guide to Using VMS Command Procedures

Order Number AA-LA 11 A-TE

Guide to Using VMS
Command Procedures
Order Number: AA-LA 11 A-TE

April 1988
This document describes how to design, write, and execute command
procedures using the VMS DIGITAL Command Language (DCL).

Revision/Update Information:

This document supersedes the Guide to
Using DCL and Command Procedures
on VAX/VMS, Version 4.0.

Software Version:

VMS Version 5.0

digital equipment corporation
maynard, massachusetts

April 1988
The information in this document is subject to change without notice and should
not be construed as a commitment by Digital Equipment Corporation. Digital
Equipment Corporation assumes no responsibility for any errors that may appear
in this document.
The software described in this document is furnished under a license and may be
used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment
that is not supplied by Digital Equipment Corporation or its affiliated companies.
Copyright © 1988 by Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-10
DECSYSTEM-20
DECUS
DECwriter

DIBOL
EduSystem
IAS
MASSBUS
PDP
PDT
RSTS
RSX

UNIBUS
VAX
VAXcluster
VMS
VT

~U~UD~DTM
ZK4499

HOW TO ORDER ADDITIONAL DOCUMENTATION
DIRECT MAIL ORDERS
USA & PUERTO Rico*

CANADA

INTERNATIONAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire
03061

Digital Equipment
of Canada Ltd.
100 Herzberg Road
Kanata, Ontario K2K 2A6
Attn: Direct Order Desk

Digital Equipment Corporation
PSG Business Manager
c/o Digital's local subsidiary
or approved distributor

In Continental USA and Puerto Rico call 800-258-1710.
In New Hampshire. Alaska, and Hawaii call 603-884-6660.
In Canada call 800-267-6215.
*Any prepaid order from Puerto Rico must be placed with the local Digital subsidiary (809-754-7575).
Internal orders should be placed through the Software Distribution Center (SOC), Digital Equipment
Corporation, Westminster, Massachusetts 01473.

Production Note
This book was produced with the VAX DOCUMENT electronic publishing
system, a software tool developed and sold by DIGITAL. In this system,
writers use an ASCII text editor to create source files containing text and
English-like code; this code labels the structural elements of the document,
such as chapters, paragraphs, and tables. The VAX DOCUMENT software,
which runs on the VMS operating system, interprets the code to format the
text, generate a table of contents and index, and paginate the entire document.
Writers can print the document on the terminal or line printer, or they can use
DIGITAL-supported devices, such as the LN03 laser printer and PostScript®
printers (PrintServer 40 or LN03R ScriptPrinter), to produce a typeset-quality
copy containing integrated graphics.

PostScript is a trademark of Adobe Systems, Inc.

Contents
PREFACE

xiii

NEW AND CHANGED FEATURES

xvii

CHAPTER 1 DEVELOPING COMMAND PROCEDURES

1-1

1.1
1.1.1
1.1.2
1.1.3
1.1.4

FORMATTING COMMAND PROCEDURES
Documenting Command Procedures
Using Multiple Lines for a Single Command
Using Complete Command Names and Qualifier Names
Using Labels

1-2
1-3
1-3
1-4
1-4

1.2
1.2.1
1.2.2
1.2.3
1.2.4

EXECUTING COMMAND PROCEDURES
Executing Command Procedures Interactively
Submitting Command Procedures for Batch Execution
Executing Command Procedures on a Remote Node
Changing Command Levels

1-5
1-5
1-6
1-6
1-7

1.3
1.3.1
1.3.2

1-9
1-9
1-9

1.4

USING A COMMAND PROCEDURE TO DEFINE PARAMETERS
OR QUALIFIERS

1-12

1.5

TESTING AND DEBUGGING COMMAND PROCEDURES

1-13

1.6

MAINTAINING COMMAND PROCEDURES

1-13

Contents

CHAPTER 2 DCL CONCEPTS
2.1
2.1.1
2.1.2
2.1.3
2.1.4
2.1.5
2.1.6
2.1.7

LOGICAL NAMES
Creating and Deleting Logical Names
Using Logical Names
Logical Name Tables
Displaying Logical Names
Access Modes and Attributes
Search Lists
System-Defined Logical Names

2-1
2-2
2-2
2-3
2-4
2-4
2-4
2-5

2.2
2.2.1
2.2.2

PROCESS PERMANENT FILES
Default Process Permanent Files
Redefining System-Defined Logical Names

2-5
2-6
2-7

2.3
2.3.1
2.3.2
2.3.3
2.3.4
2.3.5

SYMBOLS
Types of Symbols
Creating Symbols
Displaying the Value of a Symbol
Masking the Value of Symbols
Deleting Symbols

2-7
2-7
2-8
2-8
2-8
2-9

2.4
2.4.1

2-9
2-10

2.4.2

EXPRESSIONS
Values in Expressions
Character Strings • 2-10
Integers• 2-10
Symbols • 2-11
Lexical Functions • 2-11
Operators Used in Expressions

2.5
2.5.1
2.5.2
2.5.3

SYMBOL SUBSTITUTION
Using Apostrophes as Substitution Operators
Using Ampersands as Substitution Operators
Distinguishing between Symbols and Logical Names

2-14
2-14
2-15
2-15

2.4.1.1
2.4.1.2
2.4.1.3
2.4.1.4

2-1

2-12

Contents

CHAPTER 3 COMMAND PROCEDURE INPUT/OUTPUT

3-1

3.1
3.1.1
3.1.2

PASSING DATA TO COMMAND PROCEDURES
Passing Parameters
Prompting for Input

3-1
3-1
3-4

3.2
3.2.1
3.2.2
3.2.3

PASSING DATA TO COMMANDS AND IMAGES
Including Data in the Command Procedure
Supplying Data to an Image
Defining SYS$1NPUT as a File

3-5
3-5
3-6
3-7

3.3
3.3.1
3.3.2
3.3.3
3.3.4
3.3.5
3.3.6

DIRECTING OUTPUT FROM COMMAND PROCEDURES
Redirecting Output from Command Procedures
Redirecting Output from Commands and Images
Redirecting Error Messages
Using Global Symbols to Return Data
Using Logical Names to Return Data
Verifying Command Procedure Execution

3-7
3-8
3-8
3-10
3-11
3-12
3-12

3.4
3.4.1
3.4.2

WRITING DATA TO THE TERMINAL
Using the WRITE Command
Using the TYPE Command

3-14
3-14
3-15

CHAPTER4 USING LEXICAL FUNCTIONS

4-1

4.1
4.1.1
4.1.2

OBTAINING INFORMATION ABOUT YOUR PROCESS
Changing Verification Settings
Changing Default Protection

4-2
4-3
4-4

4.2
4.2.1
4.2.2
4.2.3

OBTAINING INFORMATION ABOUT THE SYSTEM
Determining Your Node Name
Obtaining Information About Queues
Obtaining Information About Processes

4-4
4-5
4-5
4-5

4.3
4.3.1
4.3.2

OBTAINING INFORMATION ABOUT FILES AND DEVICES
Searching for a File in a Directory
Deleting Old Versions of Files

4-6
4-7
4-7

4.4

TRANSLATING LOGICAL NAMES

4-8
vii

Contents

4.5
4.5.1
4.5.2
4.5.3

MANIPULATING STRINGS
Determining if a String or Character is Present
Extracting Part of a String
Formatting Output Strings

4-9
4-9
4-9
4-11

4.6
4.6.1
4.6.2
4.6.3

MANIPULATING DATA TYPES
Converting Data Types
Evaluating Expressions
Determining Whether a Symbol Exists

4-13
4-13
4-13
4-14

CHAPTER 5 DESIGN AND LOGIC

viii

5-1

5.1

DESIGN

5-1

5.2
5.2.1
5.2.2
5.2.3
5.2.4

CODING
Obtaining Variables
Coding the General Design
Testing and Debugging
Filling in the Program Stubs

5-2
5-2
5-2
5-4
5-5

5.3
5.3.1
5.3.2
5.3.3
5.3.4
5.3.5
5.3.6

TECHNIQUES FOR CONTROLLING EXECUTION FLOW
IF Command
GOTO Command
GOSUB Command
CALL Command
Loops
Case Statements

5-6
5-6
5-9
5-10
5-12
5-14
5-15

5.4
5.4.1
5.4.2
5.4.3

TERMINATING COMMAND PROCEDURES
Using the EXIT Command
Passing Status Values with the EXIT Command
Using the STOP Command

5-16
5-17
5-18
5-18

Contents

CHAPTER 6 FILE INPUT/OUTPUT

6-1
6-1
6-1

6.1.3
6.1.4

COMMANDS FOR FILE 1/0
OPEN Command
Opening a File for Reading • 6-2
Opening a File for Writing• 6-2
Opening a File for Reading and Writing • 6-3
Opening Shareable Files • 6-3
READ Command
Designing Read Loops • 6-4
Reading Records Randomly from Indexed Sequential
Files• 6-4
WRITE Command
CLOSE Command

6.2
6.2.1
6.2.2
6.2.3

MODIFYING A FILE
Updating Records in a File
Creating a New Output File
Appending Records to a File

6-6
6-7
6-8
6-9

6.3

HANDLING 1/0 ERRORS

6-10

6.1
6.1.1

6.1.1.1
6.1.1.2
6.1.1.3
6.1.1.4
6.1.2

6.1.2.1
6.1.2.2

CHAPTER 7 CONTROLLING ERROR CONDITIONS AND CTRL/Y
INTERRUPTS

6-3

6-5
6-6

7-1

7.1
7.1.1
7.1.2
7.1.3

DETECTING ERRORS IN COMMAND PROCEDURES
Condition Codes and $STATUS
Severity Levels and $SEVERITY
Commands That Do Not Set $STATUS

7-1
7-1
7-2
7-2

7.2
7.2.1
7.2.2

ERROR CONDITION HANDLING
ON Command
Disabling Error Checking

7-3
7-4
7-5

7.3
7.3.1
7.3.2
7.3.3

HANDLING CTRL/Y INTERRUPTS
Interrupting a Command Procedure
Setting a CTRL/Y Action Routine
Disabling and Enabling CTRL/Y Interruptions

7-6
7-6
7-7
7-10

Contents

CHAPTER 8 WORKING WITH BATCH JOBS
8.1
8.1.1
8.1.2
8.1.3

SUBMITTING A BATCH JOB
Checking for Batch Jobs in Your Login Command Procedure
Submitting Multiple Command Procedures
Controlling a Batch Job

8-1
8-2
8-3
8-3

8.2

PASSING DATA TO BATCH JOBS

8-4

8.3
8.3.1
8.3.2
8.3.3

BATCH JOB OUTPUT
Saving the Log File
Reading the Log File
Including All Command Output in the Batch Job Log

8-5
8-5
8-5
8-6

8.4
8.4.1
8.4.2

CONTROLLING JOBS IN A BATCH QUEUE
Changing Job Characteristics
Deleting and Stopping Batch Jobs

8-6
8-7
8-8

8.5

RESTARTING BATCH JOBS

8-9

8.6

SYNCHRONIZING BATCH JOB EXECUTION

8-10

APPENDIX A ANNOTATED COMMAND PROCEDURES

8-1

A-1

A.1

CONVERT.COM

A-3

A.2

REMINDER.COM

A-6

A.3

DIR.COM

A-9

A.4

SYS.COM

A-11

A.5

GETPARMS.COM

A-13

A.6

EDITALL.COM

A-15

A.7

FORTUSER.COM

A-17

Contents

A.8

LISTER.COM

A-20

A.9

CALC.COM

A-22

A.10

BATCH.COM

A-24

A.11

COMPILE_FILE.COM

A-28

APPENDIX B SUMMARY OF LEXICAL FUNCTIONS

B-1

APPENDIX C COMMANDS FREQUENTLY USED IN COMMAND
PROCEDURES

C-1

INDEX

FIGURES
6-1

Symbol Substitution with the WRITE Command

7-1
7-2
7-3

ON Command Actions

8-1

TABLES
2-1
3-1
4-1
7-1

Flow of Execution Following CTRL/Y Action

6-6
7-5
7-9

Default CTRL/Y Action for Nested Procedures

7-10

Synchronizing Batch Job Execution

8-10

Summary of Operators in Expressions

2-13
3-9
4-2
7-4

Commands Performed Within the Command Interpreter _
Commonly Changed Process Characteristics
ON Command Keywords and Actions

Preface
Intended Audience
All users of the VMS operating system can benefit from using command
procedures. You can write command procedures to perform either simple
tasks or complex tasks that approximate the capabilities of a high-level
programming language.
This manual presents key concepts and techniques for developing command
procedures using the VMS DIGITAL Command Language (DCL). Many
examples, including examples of complete command procedures, are intended
to demonstrate applications of the concepts and techniques discussed. The
examples included in this document include elementary, advanced, and
complex command procedures.

Document Structure
This guide contains eight chapters and three appendixes:
•

Chapter 1 is an introduction to using and developing command
procedures.

•

Chapter 2 describes some of the DCL concepts that you use when
developing command procedures.

•

Chapter 3 discusses sending input to and receiving output from command
procedures.

•

Chapter 4 discusses the use of lexical functions in command procedures.

•

Chapter 5 discusses concepts used in designing a command procedure
and describes techniques for controlling execution flow in a command
procedure.

•

Chapter 6 describes how to access files for input and output in a
command procedure.

•

Chapter 7 describes error handling within command procedures.

•

Chapter 8 describes how to use command procedures in batch processes.

•

Appendix A contains eleven annotated sample command procedures.

•

Appendix B is a summary of lexical functions.

•

Appendix C lists DCL commands that are frequently used in command
procedures.

xiii

Preface

Associated Documents
The following documents contain information related to this guide:

•

Introduction to VMS contains general information about using the VMS
operating system.

•

VMS DCL Concepts Manual describes the DIGITAL Command Language
(DCL), defines the format and use of file specifications, and (of particular
interest to those writing command procedures) contains many examples
of specific DCL commands.

•

VMS DCL Dictionary contains complete descriptions of all DCL
commands.

Conventions
Convention

Meaning
In examples, a key name (usually abbreviated)
shown within a box indicates that you press
a key on the keyboard; in text, a key name is
not enclosed in a box. In this example, the key
is the RETURN key. (Note that the RETURN
key is not usually shown in syntax statements
or in all examples; however, assume that you
must press the RETURN key after entering a
command or responding to a prompt.)

xiv

CTRL/C

A key combination, shown in uppercase with a
slash separating two key names, indicates that
you hold down the first key while you press the
second key. For example, the key combination
CTRL/C indicates that you hold down the key
labeled CTRL while you press the key labeled C.
In examples, a key combination is enclosed in a
box.

$SHOW TIME
05-JUN-1988 11 :55:22

In examples, system output (what the system
displays) is shown in black. User input (what
you enter) is shown in red.

$ TYPE MYFILE.DAT

In examples, a vertical series of periods, or
ellipsis, means either that not all the data that
the system would display in response to a
command is shown or that not all the data a
user would enter is shown.

input-file, ...

In examples, a horizontal ellipsis indicates
that additional parameters, values, or other
information can be entered, that preceding
items can be repeated one or more times, or
that optional arguments in a statement have
been omitted.

Preface

Convention

Meaning

[logical-name]

Brackets indicate that the enclosed item is
optional. (Brackets are not, however, optional
in the syntax of a directory name in a file
specification or in the syntax of a substring
specification in an assignment statement.)

quotation marks
apostrophes

The term quotation marks is used to refer
to double quotation marks (" ). The term
apostrophe (') is used to refer to a single
quotation mark.

New and Changed Features
The following additions have been made to this manual since it was produced
at Version 4.0:
•

Chapter 1 contains instructions for using the TYPE command to execute
command procedures located on remote nodes.

•

Chapter 2 contains instructions for using the SET SYMBOL command to
mask global or local symbols in a command procedure.

•

Chapter 4 describes the F$GETQUI lexical function and includes an
example illustrating how to use this lexical function.

•

Chapter 5 describes the enhanced IF language construct. The IF language
construct now allows you to specify a block of commands following the
THEN command, and supports a new ELSE command. This chapter
also describes the CALL command, which transfers control to a labeled
subroutine and creates a new procedure level.

•

Chapter 8 contains information about the new SET ENTRY and SHOW
ENTRY commands, which allow you to display information about a batch
job and change the characteristics of a batch job.

•

Appendix A contains a new example command procedure called
COMPILEJILE.COM. This command procedure illustrates the use
of the enhanced IF language construct.

xvii

Developing Command Procedures

A command procedure is a file that contains DCL commands and data lines
used by DCL commands. You can write command procedures to execute
simple tasks or complex tasks that approximate the capabilities of a high-level
programming language. When you execute a command procedure, the DCL
command interpreter reads the file and executes the commands it contains.
This manual describes how to design and write command procedures. It
explains tasks such as obtaining input, writing output, establishing loops,
and designing error-checking routines, as well as the DCL concepts you must
understand to write command procedures. This manual also describes how to
execute command procedures interactively and in batch mode.
A simple command procedure can contain a sequence of commands that you
use frequently. For example, you might enter the DIRECTORY command
each time you set default to the subdirectory where you keep your work files.
You can use the following command procedure, called GO-DIR.COM, to set
default to the work directory, called [PERRY.ACCOUNTS], and display a list
of files in that directory.
$ SET DEFAULT [PERRY.ACCOUNTS]
$ DIRECTORY
$ EXIT

Enter the following command to execute GO_DIR.COM:
$ ©GO_DIR

This command tells the DCL command interpreter to read the file GO_
DIR.COM and to execute the commands in the file. Therefore, the command
interpreter sets your default directory to [PERRY.ACCOUNTS] and issues
the DIRECTORY command. The system displays the output from the
DIRECTORY command on your terminal.
You can revise GO_DIR.COM to allow you to set default to any directory
and obtain a list of the files in the directory:
$ INQUIRE DIR_NAME "Directory name"
$ SET DEFAULT 'DIR_NAME'
$ DIRECTORY
$EXIT

When you execute this version of GO_DIR.COM, the INQUIRE command
prompts for a directory name, the SET DEFAULT command moves you
to that directory, and the system displays the output of the DIRECTORY
command on your terminal.

1-1

Developing Command Procedures
1 .1 Formatting Command Procedures

1 .1

Formatting Command Procedures
Use a text editor (or the DCL command CREATE) to create and format a
command procedure. When you name the command procedure, use the
file type COM. Both the @ command, which is used to execute command
procedures interactively, and the SUBMIT command, which is used to execute
command procedures in batch mode, append the default file type COM to the
file name you specify. If you use another file type, you must specify the file
type when you execute the command procedure.
Command procedures contain DCL commands that you want the DCL
command interpreter to execute and data lines that are used by these
commands. Commands must begin with a dollar sign. You can start the
command immediately after the dollar sign, or you can place one or more
spaces or tabs before the command to make the command procedure easier to
read.
Data lines, unlike commands, usually do not begin with a dollar sign. Data
lines are used as input data for commands or programs. Data lines are used
by the most recently issued command; the DCL command interpreter does
not process data lines.

Note: If you need to begin a data line with a dollar sign, use the DECK and
EOD commands. See Chapter 3 for more information.
The following example illustrates command lines and data lines in a
command procedure.
$ MAIL
SEND
THOMAS
MY MEMO
Do you have a few minutes to talk about the
ideas I presented in my memo?
$ !
$ SHOW USERS THOMAS
$ EXIT

The first line is a command and must therefore start with a dollar sign. The
next lines are data lines that are used by the Mail Utility; these lines must not
start with dollar signs. Note that the data lines correspond to the way that the
image (invoked by the command) expects the data. Therefore, the data lines
provide a MAIL command (SEND), a recipient (THOMAS), a subject (MY
MEMO) and the text of the mail message. When the command interpreter
finds a new line that begins with a dollar sign, the Mail Utility is terminated.
Use the following formatting conventions to make your command procedures
easier to read and maintain:
•

Use comments to document your command procedures.

•

If a command is very long or includes many qualifiers, continue it on
more than one line. Terminate the first line of the command string with a
hyphen character; do not start a continuation line with a dollar sign.

•

Use complete command names and qualifier names.

•

Use labels to identify related groups of commands and use indentation to
make loops and conditional coding easier to understand.

These formatting conventions are described in the following sections.

1-2

Developing Command Procedures
1 .1 Formatting Command Procedures

1.1.1

Documenting Command Procedures
It is good programming practice to document your command procedures
so they are easy to read and to maintain. At the beginning of a command
procedure, use comments to describe the procedure and any parameters
that are passed to it. Also, use comments at the beginning of each block of
commands to describe that section of the procedure.
The exclamation point ( ! ) begins a comment in command procedures. DCL
considers everything to the right of an exclamation point to be a comment
and ignores this information when processing the line.
The following example uses comments to document a command procedure
and to make it easier to read.
$! This procedure sends mail to THOMAS and
$! asks him if he has time to talk
$!
$!
$ MAIL
SEND
THOMAS

MY MEMO
Do you have a few minutes to talk about the
ideas I presented in my memo?
$!
$ EXIT

Note that whenever you insert a blank line in a command procedure,
you must start the line with a dollar sign. If you omit the dollar sign,
DCL interprets the line as data and issues a warning message. Also, you
should include an exclamation point after the dollar sign. Although not
required, the exclamation point helps the procedure run faster because the
command interpreter ignores the line as a comment rather than searching for
a command.
If you must use an exclamation point character as part of the text in a
command line, enclose it in quotation marks so the command interpreter will
not interpret the exclamation point as a comment delimiter. If you use an
exclamation point character in a data line, the image to which you pass the
data processes the exclamation point.

1.1.2

Using Multiple Lines for a Single Command
If you are writing a command that includes many qualifiers, you can make
the command procedure more readable by listing the qualifiers on separate
lines rather than running them together. To do this, use the hyphen as a
continuation character, just as you do for interactive command continuation.
Do not begin the continued line with a dollar sign. For example:
$

PRINT TEST.OUT /AFTER=18:00 /COPIES=10 /QUEUE=LPBO:

The spaces preceding each qualifier are not required, but they make the
command string more readable.

1-3

Developing Command Procedures
1 . 1 Formatting Command Procedures

1.1.3

Using Complete Command Names and Qualifier Names
Even though DCL syntax rules allow truncation, you should use complete
command, qualifier, and keyword names in command procedures. This helps
to document the command procedure, because DCL commands and qualifiers
are generally named according to the functions they perform. For example,
compare the following two lines:
$PRINT ALPHA.LIS/COPIES=2
$ PR ALPHA/C=2

The first command line expresses clearly the request to print two copies of the
file ALPHA.LIS. The second line is terse and may not be easily interpreted by
other users (or remembered by yourself).
If you use abbreviations in command procedures, these abbreviations may not

uniquely identify commands in a future release of the VMS operating system.

1.1.4

Using Labels
In longer command procedures, you can improve readability by using
labels to identify related groups of commands. A label can have up to
255 characters, cannot contain embedded blanks, and must be terminated by
a colon. When labels mark the start of a loop, use spaces or tabs to indent
the commands in the body of the loop. (A loop is a group of commands that
executes repeatedly until a condition is met.) When you indent commands,
the dollar sign should still be in column 1. For example:
$! This procedure modifies the fifth
$! record in the file EMPLOYEES.DAT
$!
$ OPEN/READ/WRITE IN_FILE EMPLOYEES.DAT
$ COUNT = 1
$ FIND_RECORD:
$
IF COUNT .GT. 5 THEN GOTO REVISE
$
READ IN_FILE RECORD
$
COUNT = COUNT + 1
$
GOTO FIND_RECORD
$!
$ REVISE:

In this example, the label FIND_RECORD begins the loop used to search for
the fifth record in the file. The commands in the loop are indented, making
the body of the loop easier to read.
The commands IF and GOTO, and techniques for constructing loops in
command procedures, are described in Chapter 5.

1-4

Developing Command Procedures
1.2 Executing Command Procedures

1.2

Executing Command Procedures
You can execute command procedures in two modes: interactive and batch.
In interactive mode, the commands within a command procedure execute
as if you were entering them from your terminal. You cannot execute any
other commands from your terminal until the procedure terminates. In batch
mode, the system creates a separate process to run the command procedure.
After you submit a batch job, you can continue to use your terminal while the
batch job executes.
You can also use the TYPE command to execute a command procedure on a
remote node.

1.2.1

Executing Command Procedures Interactively
To execute a command procedure interactively, enter the @character (execute
procedure command) followed by the file specification of the procedure. If
you do not enter a complete file specification, the command interpreter uses
your current disk and directory and a default file type of COM. For example,
the following command executes the command procedure WEATHER.COM,
which is located in your current default directory:
$ ©WEATHER

When you enter the@ command, the command interpreter executes the
commands in the file WEATHER.COM. Each command in WEATHER.COM
executes sequentially. The command interpreter issues the DCL prompt
at your terminal when WEATHER.COM finishes executing. You can then
resume interactive work.
If a command procedure is not in your default directory or does not have the

file type COM, give the complete file specification, as shown in the following
example:
$ ©DISK2: [COMMON] SETUP

For command procedures that you execute frequently, you can define a
symbol name as a synonym for the entire command line. For example:
$ SETUP = "©DISK2: [COMMON] SETUP"

Whenever you want to run DISK2:[COMMON]SETUP.COM, you can use the
symbol SETUP as if it were a command:
$ SETUP

The command interpreter replaces the symbol SETUP with its value
(@DISK2:[COMMON]SETUP.COM) and then executes the procedure.

1-5

Developing Command Procedures
1 .2 Executing Command Procedures

1.2.2

Submitting Command Procedures for Batch Execution
If you create and use procedures that require lengthy processing time-for
example, the compilation or assembly of large source programs-submit these
procedures as batch jobs. You can use your terminal to perform other tasks
while the batch job executes.

Use the SUBMIT command to execute a command procedure as a batch job.
The SUBMIT command assumes your current disk and directory defaults
and a default file type of COM for the command procedure. For example, to
submit the command procedure WEATHER.COM (in your default directory)
for batch execution, enter the following command:
$ SUBMIT WEATHER
Job WEATHER (queue SYS$BATCH, entry 210) started on SYS$BATCH
$

In this example, the system displays a message showing that the job has
been queued; the message gives you the job number (210) and the name of
the system queue on which the job is entered (SYS$BATCH). Then the DCL
prompt is displayed, and you can continue using the terminal.
Your job stays in the queue until the system is ready to run the job. Then the
system creates another process for you using your account and your process
characteristics. The system runs the job from that process and deletes the
process when the job is completed. For more information on batch jobs, see
Chapter 8.

1.2.3

Executing Command Procedures on a Remote Node
You can use the TYPE command to execute a command procedure
interactively on any remote node. The output of the command procedure
is displayed on the user's terminal at the local node. For example, the TYPE
command lets you execute command procedures to list the users logged on
to the remote node, or to display the status of services in the local cluster not
provided clusterwide. A sample command procedure follows:
$ ! SHOWUSERS.COM
$ IF F$MODE () . EQS . "NETWORK" THEN DEFINE/USER SYS$0UTPUT SYS$NET
$ SHOW USERS

This command procedure can be used with the TYPE command to display at
the user's local node a list of users logged on to the remote node on which
the command procedure resides.
To execute a command procedure in the default DECnet account of the
remote node, specify the command procedure as a parameter to the TYPE
command as follows:
$TYPE node_name: :"TASK=comrnand_procedure"

The variable node_name is the name of the remote node on which the
command procedure resides. The variable command_procedure is the name of
the command procedure.
To execute a command procedure in the SYS$LOGIN directory (the top-level
directory) of another account on the remote node, use an access control string
in the command, as follows:

1-6

Developing Command Procedures
1 .2 Executing Command Procedures

$ TYPE node_name"user_name password": :"TASK=command_procedure"

The variable user_name is the user name of the account on the remote node,
password is the password of the account on the remote node, and command_
procedure is the name of the command procedure.
The following command executes the command procedure
SHOWUSERS.COM and displays the output from this command procedure
on the user's terminal. The command procedure resides in the SYS$LOGIN
directory of account BIRD on node ORIOLE.
$TYPE ORIOLE"BIRD FLIESFAST": :"TASK=SHOWUSERS"
VAX/VMS Interactive Users
09-DEC-1988 17:20:13.30
Total number of interactive users = 5
Username
Process Name
PID
Terminal
FLICKER
Freddie
00536278
TXA1:
ROBIN
Red
00892674
VTA2:
DOVE
Whitie
00847326
TXA3:
DUCK
Donna
02643859
RTA1:

1.2.4

Changing Command Levels
A command level is an input stream for the DCL command interpreter. When
you log in and enter commands at your terminal, you are entering commands
from command level zero. A simple interactive command procedure executes
at command level 1. When the procedure terminates and the DCL prompt
reappears on your screen, you are back at command level zero.
There are two ways to create a new command level within a complex
command procedure. You can use the CALL command to call a subroutine
that exists within the command procedure or you can nest command
procedures by using an execute procedure ( @ ) command inside one
procedure to execute another procedure. When you use the CALL command
or nest a command procedure, you increase the command level by one.
The maximum number of command levels you can achieve with the CALL
command or by nesting command procedures is 32.
The following example command procedure creates the indicated command
levels when you execute it interactively.

1-7

Developing Command Procedures
1 .2 Executing Command Procedures

$ ! Example of command procedure levels
$ WRITE SYS$0UTPUT "This is an example"
$ ©EXAMPLE
$ DEFINE FRIEND CAROL
$ ON WARNING THEN EXIT
$ CALL SUB1
$ DEASSIGN FRIEND
$ EXIT
$ SUB1:
$ SUBROUTINE

0
8
C)

$
$
$

CALL SUB2
EXIT
ENDSUBROUTINE
$ SUB2:
$ SUBROUTINE

EXIT
ENDSUBROUTINE
$ EXIT
$
$

0 The command procedure begins executing at command level 1.
8

The nested command procedure EXAMPLE.COM executes at command
level 2.

After EXAMPLE.COM finishes executing, the DEFINE command executes
at command level 1.

The CALL SUBl command creates a new command level; subroutine
SUBl executes at command level 2.

The CALL SUB2 command within subroutine SUBl creates a new
command level. Subroutine SUB2 executes at command level 3.

The EXIT command within SUBl returns control to the DEASSIGN
command following the CALL SUBl command. The DEASSIGN
command executes at command level 1.

The EXIT command within SUB2 returns control to subroutine SUBl, that
is executing at command level 2. Note that this command executes before
the previously described command.

In a batch job, command level zero is defined as the command procedure that
is submitted for batch execution. If the batch job contains an@ command,
then the commands in the nested procedure are executed at command level
1. In batch jobs, as in interactive mode, you can create up to 32 command
levels.

1-8

Developing Command Procedures
1 .3 Login Command Procedures

1 .3

Login Command Procedures
Each time you log in, the system automatically executes login command
procedures if they exist. The system also executes these procedures at the
beginning of every batch job you submit. The system executes two types of
login command procedures:
•

A system (or group) login command procedure

•

Your personal login command procedure

These login procedures are described in the following sections.

1.3.1

A System or Group-Defined Login Command Procedure
If a systemwide (or groupwide) login command procedure exists, it is

executed before your personal login command procedure. When the system
login command procedure terminates, it passes control to your personal
login command procedure. System and group login command procedures
allow your system manager to make sure that certain commands are always
executed when you log in.
To establish a system or group login command procedure, your system
manager equates the logical name SYS$SYLOGIN to the appropriate login
command procedure. Your system manager can specify that this login
command procedure be used for all system users or for a certain group of
users.

1.3.2

Your Personal Login Command Procedure
After executing a system or group login command procedure, the system
executes your personal login command procedure. Use your personal login
command procedure to execute the same commands each time you log in.
Name your login command procedure LOGIN.COM and place it in your
default login directory, unless your system manager tells you otherwise.
The following sample LOGIN.COM procedure illustrates some techniques
you can use when writing your login command procedure.

1-9

Developing Command Procedures
1 .3 Login Command Procedures

$! Exit if this is a batch job or another
$! type of noninteractive process
$!
$ IF F$MODE () . NES . II INTERACTIVE II THEN EXIT 0
$!
$! Execute command procedures that contain
$! my symbol, logical name, and keypad definitions
$!
$ ©DISK3: [MARCIA] SYMBOLS
@
$ ©DISK3: [MARCIA]LOGICALS
9
$ ©DISK3: [MARCIA]KEYDEF
~
$!
$! Change my prompt string to an abbreviation
$! of my node name
$!
$ NODE = F$GETSYI("NODENAME") 0
$ PROMPT = F$EXTRACT(0,3,NODE)
$SET PROMPT= "''PROMPT'> II
$!
$! Type the system notices
CD
$TYPE SYS$SYSTEM:NOTICE.TXT
$!
$! Run a program that displays today's appointments
$ RUN DISK3: [MARCIA.PROG]REMINDER

0 The F$MODE lexical function returns the mode (interactive, batch,
network or other) that the process is in when the LOGIN.COM procedure
is being executed. This statement causes the procedure to exit unless
you are using the system interactively. You should test the mode at the
beginning of your LOGIN.COM procedure to ensure that commands used
only in interactive mode are not executed in any other mode; in some
cases these commands can abort noninteractive processes.

In this example, the symbols, logical names, and keypad definitions are
kept in separate files because they are easier to maintain. Also, this keeps
the LOGIN.COM procedure easier to read. However, if you prefer, you
can keep your symbols, logical .names, and keypad definitions in your
LOGIN.COM procedure.
This command executes a command procedure that creates symbol
assignments. Use symbols to create special abbreviations for commands
you enter frequently. You must define global symbols or the symbols will
be deleted after the command procedure exits. The following example
shows global symbol definitions in a sample SYMBOLS.COM file:
$ DISPLAY == "MONITOR PROCESSES/TOPCPU"
$ GO == "SET DEFAULT"
$ LP == "SHOW QUEUE/ALL SYS$PRINT"
$ SS == "SHOW SYMBOL"
$ REM == "©DISK3: [MARCIA.PROG]REMINDER"
$MAIN== "SET DEFAULT DISK3: [MARCIA]"

1-10

This command executes a command procedure that defines logical names.
Use logical names to refer to files or directories that you access often. You
can also use logical names to refer to user names.

Developing Command Procedures
1 .3 Login Command Procedures

The following example shows a sample LOGICALS.COM file:
$! Directories
$DEFINE HOME DISK3:[MARCIA]
$ DEFINE REV DISK3: [MARCIA.REVIEWS]
$DEFINE TOOLS DISK3: [MARCIA.TOOLS]
$!
$! Files

$DEFINE EQUIP DISK3: [MARCIA.LISTS]EQUIPMENT.DAT
$!
$! Users

$ DEFINE JON DAISY: :HARRIS
$ DEFINE JANE DAISY: :MOORE

This command executes a command procedure that sets up DCL keypad
definitions. You can press a defined key to enter an entire command (or
a command segment) with one keystroke. The following example shows
keypad definitions in a sample KEYDEF.COM file:
$ DEFINE/KEY PF3 "SHOW USERS" /TERMINATE
$ DEFINE/KEY KP7 "SPAWN" /TERMINATE
$ DEFINE/KEY KP8 "ATTACH II
$ DEFINE/KEY KP4 "SET HOST II

This group of commands determines the name of the node you are
logging into and changes the DCL prompt to reflect the node name.
The F$GETSYI lexical function determines the node name and the
F$EXTRACT lexical function extracts the first three characters of the
name. The SET PROMPT command changes the prompt from a dollar
sign to the first three characters of the node name.

This command displays the system notices that your system manager
keeps in the file SYS$SYSTEM:NOTICE.TXT.

This command runs a program that displays your daily appointments. If
you have programs that you always run after you log in, you may prefer
to execute them directly from your LOGIN.COM file.

The system manager assigns the file specification for your login command
procedure in the LGICMD field for your account. Accounts are maintained
in the user authorization file (UAF). In most installations, the login command
procedure is called LOGIN.COM. However, if you want to execute a file
other than the one named in the LGICMD field for your account, use
the /COMMAND qualifier when you log in. See the description of the
login procedure in the VMS DCL Dictionary for information on using the
/COMMAND qualifier.

1-11

Developing Command Procedures
1 .3 Login Command Procedures

Your system manager can set up a captive account by placing the name of a
special command procedure in the LGICMD field for your account. If you log
into a captive account, you can perform only the functions specified in the
command procedure listed in the LGICMD field of your account; you cannot
use the complete set of DCL commands. For more information on captive
accounts, see the Guide to Setting Up a VMS System.

1 .4

Using a Command Procedure to Define Parameters or Qualifiers
You can create a command procedure that specifies only parameters or
qualifiers and then use the command procedure within a DCL command
string. This type of command procedure is useful when there is a set of
parameters or qualifiers that you frequently use with one or more particular
commands. To execute the command procedure, use the execute procedure
(@) command in the command string where you would normally use the
qualifiers or parameters.
For example, suppose you frequently use the same set of qualifiers when
you enter the LINK command. You could create a command procedure that
contains the following qualifiers:
$!This command procedure contains command qualifiers
$!for the LINK command
$!
/DEBUG/SYMBOL_TABLE/MAP/FULL/CROSS_REFERENCE

To use this command procedure, execute it on the command line where you
would otherwise place the qualifiers. For example, if you name the command
procedure DEFLINK.COM, you would use the following command line to
link to an object module named SYNAPSE.OBJ using the qualifiers that you
specified in the command procedure:
$ LINK SYNAPSE©DEFLINK

Note that you cannot include a space before the @ character when the
command procedure begins with a qualifier name.
The next example shows a command procedure named P ARAM.COM that
contains parameters:
$!This command procedure contains parameters
$!for the LINK command
$!
CHAP1, CHAP2

To execute the procedure, use it in a command string in place of a parameter
name:
$ DIRECTORY ©PARAM

Note that the@ character must be preceded by a space when the command
procedure begins with a parameter.

1-12

Developing Command Procedures
1.5 Testing and Debugging Command Procedures

1.5

Testing and Debugging Command Procedures
Typically, command procedures need to be tested, then debugged. You can
debug command procedures by controlling the input and output to them and
by using the SET VERIFY and SET NOVERIFY commands. When you enter
the SET VERIFY command, the system displays the lines in the command
procedure on your terminal while the procedure executes.
The following example shows the execution of SYMBOLS.COM when
verification is set:
$ SET VERIFY
$ ©SYMBOLS
$ DISPLAY == "MONITOR PROCESS/TOPCPU"
$ GO == "SET DEFAULT"
$ LP == "SHOW QUEUE/ALL SYS$PRINT"
$ SS == "SHOW SYMBOL"
$REM== "©DISK3: [MARCIA.TOOLS]REMINDER"
$MAIN== "SET DEFAULT DISK3: [MARCIA]"
$

Verification remains in effect until you enter the SET NOVERIFY command
or use the F$VERIFY lexical function to change the verification setting.
Chapter 4 contains more information on changing verification settings.

1.6

Maintaining Command Procedures
Command procedures are easy to maintain if you format them correctly,
document them adequately, and verify that they execute. New versions of
the VMS operating system may include enhancements to the DCL command
language and changes to current commands that require you to make changes
to a command procedure.
Generally, DIGITAL makes changes to DCL commands (and to functions of
the DCL command interpreter) only to add new features and to correct errors.
However, a new release may occasionally change the format or results of
a particular command, command parameter, or qualifier. To maintain your
command procedures effectively, read the release notes issued with each VMS
release.

1-13

DCLConcepts

This chapter describes how to use logical names, process permanent files,
symbols, expressions, and lexical functions. You will use logical names,
symbols, expressions, and lexical functions as variables within command
procedures that resemble high-level language programs. (A variable is a
placeholder that represents a value that can change each time a command
procedure runs.)
The information in this chapter will help you understand the examples in
later chapters of tl)is manual. If you are already familiar with these topics,
skip this chapter and go to Chapter 3. For a more basic introduction, see the
Introduction to VMS; for complete reference information, see the VMS DCL

Concepts Manual.

2.1

Logical Names
A logical name is a name that can be used in place of another character string.
A logical name is equated to a string (called an equivalence string), or to a list
of strings (called a search list). When you use a logical name, the equivalence
string is substituted for the logical name. The most common reason for using
logical names is to represent files, directories, and devices.
For example, if the logical name TEST_FILE is equated to the equivalence
string STATISTICS you can enter the following command:
$ RUN TEST_FILE

The system substitutes the equivalence string STATISTICS for the logical
name TEST_FILE and runs the program STATISTICS.EXE. (The RUN
command supplies the default file type EXE.)
In general, whenever a command accepts a file or a device name, the
command checks whether the name you provide is a logical name. If the
name is a logical name, then the system replaces the logical name with its
actual value and executes the appropriate command.
When the system translates a logical name and replaces the logical name with
its equivalence string, the system examines the equivalence string to see if it
is also a logical name. If it is, the system performs a second translation. This
process, called iterative translation, can occur a maximum of 10 times.

2-1

DCL Concepts
2.1 Logical Names

2.1.1

Creating and Deleting Logical Names
You can use the ASSIGN or DEFINE commands to create a logical name;
this section demonstrates the DEFINE command. (Note that syntax for the
ASSIGN command differs from the syntax for the DEFINE command. For
information on using the ASSIGN command, see the VMS DCL Dictionary.)
The syntax for defining a logical name is as follows:
$ DEFINE logical-name equivalence-name[, ... ]

For example, the following command creates the logical name WORKFILE
and equates it to the equivalence string DISK2:[WALSH.REPORTS]WORK_
SUMMARY.DAT:
$DEFINE WORKFILE DISK2: [WALSH.REPORTS]WORK_SUMMARY.DAT

Use the DEASSIGN command to delete a logical name. For example, if you
no longer want to keep the logical name WORKFILE, you can delete it with
the following command:
$ DEASSIGN WORKFILE

2.1.2

Using Logical Names
When you use the system interactively, you can use logical names to refer to
your files and work directories. For example, if you create the logical name
COMS to translate to the directory name DISK7:[WALSH.COMMAND_
PROC], you can use the name COMS instead of typing the long device and
directory names. The following example shows how to define the logical
name COMS and use it as part of a file specification.
$DEFINE COMS DISK7: [WALSH.COMMAND_PROC]
$ TYPE COMS:PAYROLL.COM
$ SET DEFAULT COMS

Note that when you use a logical name as part of a file specification, the
logical name must be at the beginning (leftmost) part of the file specification,
and must be followed by a colon. There are, however, special rules for
using logical names in network file specifications. See the VMS DCL Concepts
Manual for more information.
Logical names are also used to refer to the devices on your system. You
should not refer to a device using its physical device name (such as DBAl);
instead you should use the logical name assigned by your system manager.
Also, certain commands such as ALLOCATE and MOUNT allow you to create
your own logical names when you work with disks and tapes.
In command procedures, you will often use logical names when performing
input and output from files. When you open a file with the OPEN command,
you also create a logical name for the file. The READ, WRITE, and CLOSE
commands use the logical name, not the actual file specification, to refer to
the file. For example:
$ OPEN INFILE DISK3: [WALSH]DATA.DAT
$ READ INFILE RECORD
$ CLOSE INFILE

When closing the file, the CLOSE command deassigns the logical name
INFILE.

2-2

DCL Concepts
2.1 Logical Names

2.1.3

Logical Name Tables
The system maintains logical names in logical name tables. Some logical
name tables are available only to your process. Others are shareable, they are
available to other users on the system. In general, the names you work with
are in the following four tables:
Process table

The names in this table are available only to your process.
The actual name for your process table is LNM$PROCESS_
TABLE. However, use the logical name LNM$PROCESS to
refer to your process table.

Job table

The names in this table are available to your process, and
to any of your subprocesses. The actual name for your
job table is LNM$JQB_xxx (xxx represents a job number.)
However, use the logical name LNM$JOB to refer to your job
table.

Group table

The names in this table are available to all users in
your group. The actual name for your group table is
LNM$GROUP_xxx (xxx represents a group number.)
However, use the logical name LNM$GROUP to refer to
your group table.

System table

The names in this table are available to all users on
the system. The actual name for your system table is
LNM$SYSTEM_TABLE. However, use the logical name
LNM$SYSTEM to refer to the system table.

When you use a logical name, the system looks in the process, job, group,
and system tables (in that order) to obtain the name's translation. You can,
however, change the way that the system translates logical names; see the
VMS DCL Concepts Manual for more information.
By default, the DEFINE and DEASSIGN commands place and delete names
from your process table. However, you can request a different table with the
/TABLE qualifier. For example:
$ DEFINE/TABLE=LNM$SYSTEM REVIEWERS DISK3: [PUBLIC]REVIEWERS.DIS

Note that you need special privileges to place or delete names in the group or
system tables; see the VMS DCL Concepts Manual for more information.
Most of the time you will create logical names in your process table. However
if you are a system manager or if your work requires you to add names to

shareable tables, you will need to work with the group and system tables. See
the VMS DCL Concepts Manual for more information on the special privileges
you need to work with shareable tables.
You can create logical name tables in addition to those provided by the VMS
operating system. To create additional tables, use the CREATE/NAME_
TABLE command.
The system maintains logical name tables in two types of directories: a
process-private directory (LNM$PROCESS_DIRECTORY) and a shareable
directory (LNM$SYSTEM_DIRECTORY). There is only one shareable
directory table for your system, but each process has its own process-private
directory. All logical name tables and any logical names that translate to
tables are kept in these directory tables. For example, your table names
LNM$PROCESS, LNM$JOB, and LNM$GROUP are kept in your processprivate directory; LNM$SYSTEM is kept in the shareable directory.

2-3

DCL Concepts
2.1 Logical Names

2.1.4

Displaying Logical Names
Use the SHOW LOGICAL command to display logical names and their
equivalence strings. The SHOW LOGICAL command searches certain logical
name tables for the name (or names) you specify. If you do not specify a
table to be searched, the SHOW LOGICAL command searches your process,
job, group, and system tables. However, you can change the default search
order, or you can specify other logical name tables to be searched.
The following command displays the equivalence string for the logical name
INTRO:
$ SHOW LOGICAL INTRO
"INTRO" = "DISK6: [OCONNELL. INTRO] II (LNM$PROCESS_TABLE)

This command uses the default search order and searches the process, job,
group, and system tables for the logical name INTRO. The SHOW LOGICAL
command displays the logical name, its translation, and the table where the
logical name was found.
If you do not specify a name with the SHOW LOGICAL command, then all
names in the process, job, group, and system tables are displayed unless you
have changed your default search order.

Note that you can use the /TABLE qualifier to specify a table for the SHOW
LOGICAL command to search. For example, if you enter the command
SHOW LOGICAL/TABLE=LNM$PROCESS, names in the process table are
displayed.

2.1.5

Access Modes and Attributes
Logical names have access modes and attributes that are associated with the
names. (The SHOW LOGICAL/FULL command displays these modes and
attributes.) When you create a logical name, the name is created in supervisor
mode unless you use a qualifier to specify a different mode. No attributes are
applied unless you explicitly request them.
In command procedures, you usually create names in supervisor mode.
However, sometimes you may want to create a temporary logical name
assignment that lasts only for the execution of one command. To create a
temporary logical name, use the DEFINE command with the /USER_MODE
qualifier. (See Chapter 3 for more information.)
For more information on access modes and attributes, see the VMS DCL

Concepts Manual.

2.1.6

Search Lists
A search list is a logical name that has more than one equivalence string. For
example:
$ DEFINE MY_FILES DISK1: [COOPER], DISK2: [COOPER]

You can use a search list in any place you can use a logical name. When you
use a search list, the system translates the search list using each equivalence
string in the search list definition. For example:

2-4

DCL Concepts
2.1 Logical Names

$TYPE MY_FILES:CHAP1.RNO

This command attempts to type the file DISKl:[COOPER]CHAPl.RNO.
If this file does not exist, the system will look for the file
DISK2:[COOPER]CHAP1 .RNO.
For more information on how commands process search lists, see the VMS
DCL Concepts Manual.

2.1.7

System-Defined Logical Names
When your system is booted (that is, when the operating system is started
up), a set of systemwide logical names are created and placed in the system
logical name table (LNM$SYSTEM). These logical names allow you to refer to
commonly used files or devices without remembering their actual names. For
example, if you want a list of your operating system's programs, you do not
need to know the name of the disk and directory where these programs are
stored. Instead, you can use the logical name SYS$SYSTEM as shown:
$ DIRECTORY SYS$SYSTEM

See the VMS DCL Concepts Manual for a complete list of systemwide logical
names.
Every time you log in, the system creates a group of logical names for your
process and places these names in your process table. For example, the logical
name SYS$LOGIN refers to your default device and directory when you log
in. If you have changed your current defaults by using the SET DEFAULT
command, you can use the following command to display a file from your
initial default directory:
$ TYPE SYS$LOGIN:DAILY_NOTES.DAT

For a complete list of your default process logical names, see the VMS DCL
Concepts Manual. Note that four of your default process logical names refer to
process permanent files; these are described in Section 2.2.1.

2.2

Process Permanent Files
Process permanent files are files that can remain open for the life of your
process. By default, DCL creates four process permanent files for you when
you log in. In addition, anytime you enter a command that opens a file, DCL
opens the file as a process permanent file. For example, if you open a file
with the OPEN command, this file is opened as a process permanent file. The
file remains open until you explicitly close the file, or until you log out.
Process permanent files are stored in a special area in memory. Note that if
you keep a large number of files open at the same time, you can exhaust this
area. If this occurs, close some of the files (or log out).

2-5

DCL Concepts
2.2 Process Permanent Files

2.2.1

Default Process Permanent Files
By default, DCL creates and assigns logical names to four process permanent
files. You often use these names in command procedures to do things such as
read data from the terminal and display data. (See Chapter 3.)
The default process permanent files are as follows:
SYS$COMMAND

The initial file from which DCL reads input. (A file from which
DCL reads input is called an input stream.) The command
interpreter uses SYS$COMMAND to "remember" the original
input stream.

SYS$ERROR

The default file to which DCL writes error messages generated
by warnings, errors and severe errors.

SYS$1NPUT

The default file from which DCL reads input.

SYS$0UTPUT

The default file to which DCL writes output. (A file to which
DCL writes output is called an output stream.)

If you use the SHOW LOGICAL command to determine the equivalence
string for a process permanent file, only the device portion of the string is
displayed. For example:
$ SHOW LOGICAL/FULL SYS$INPUT
"SYS$INPUT" [exec] = "_TTB4:" [concealed,terminal] (LNM$PROCESS_TABLE)

However, the equivalence strings for process permanent files also contain
special characters that the system uses to locate the correct files. The system
uses these special characters internally and does not display them to users.
When you use the system interactively, DCL equates SYS$INPUT,
SYS$0UTPUT, and SYS$ERROR and SYS$COMMAND to your terminal.
However, when you execute command procedures and submit batch jobs,
DCL creates new equivalences for these logical names.
When you execute a command procedure interactively, the following occurs:
•

SYS$INPUT is equated to the command procedure; therefore, DCL
obtains data from the command procedure. This assignment is temporary.
After the command procedure terminates, SYS$INPUT has its original
value.

•

SYS$0UTPUT, SYS$COMMAND, and SYS$ERROR remain equated to
the terminal.

When you submit a batch job, the following occurs:
•

SYS$INPUT and SYS$COMMAND are equated to the batch job
command procedure.

•

SYS$0UTPUT and SYS$ERROR are equated to the batch job log file.

When you nest command procedures, the equivalence for SYS$INPUT
changes to point to the command procedure that is currently executing.
However, the equivalences for SYS$0UTPUT, SYS$ERROR, and
SYS$COMMAND remain the same unless you explicitly change them.

2-6

DCL Concepts
2.2 Process Permanent Files

2.2.2

Redefining System-Defined Logical Names
DCL provides default values for SYS$INPUT, SYS$0UTPUT, SYS$ERROR,
and SYS$COMMAND that you ordinarily need not change. However, when
you want to perform certain input and output operations, as described in
Chapter 3, you must change these equivalences.
For information on redefining the default process permanent files, see the
VMS DCL Concepts Manual.

2.3

Symbols
A symbol is a name that represents a numeric, character, or logical value.
When you use a symbol in a DCL command line, DCL replaces the symbol
with its value. For example, you can enter the following command to equate
the symbol LP to the command SHOW QUEUE/ ALL SYS$PRINT:
$ LP = "SHOW QUEUE/ALL SYS$PRINT"

After defining the symbol, you can enter the following:
$ LP

DCL will substitute the string SHOW QUEUE/ ALL SYS$PRINT for the
symbol LP.
In command procedures, symbols help you perform programming tasks. For
example, you can use symbols as variables in expressions. You can also use
symbols to pass parameters to and from command procedures. In addition,
commands such as READ, WRITE, and INQUIRE use symbols to refer to data
records. See Chapter 4 for more information on tasks you can perform using
symbols.

2.3.1

Types of Symbols
You can create two types of symbols, local and global. Local symbols are
accessible from the current command level, and from command procedures
executed from the current command level. Global symbols are accessible at
all command levels. Use an = (Assignment Statement) to create a symbol.
To create a local symbol, use one equal sign; to create a global symbol, use
two equal signs. In the following example, SS is a local symbol and GO is a
global symbol.
$ SS = "SHOW SYMBOL"
$ GO == "SET DEFAULT"

DCL places local symbols in the local symbol table for the current command
level. DCL maintains a local symbol table for each command level as long as
the command level is active; when a command level is no longer active, its
local symbol table (and all the symbols it contains) is deleted.
DCL maintains one global symbol table for the duration of the process and
places all global symbols in that table. Therefore, a global symbol exists for
the duration of the process, unless the symbol is explicitly deleted.
When DCL determines the value of a symbol, it looks in the local symbol
table for the current command level. If DCL does not find the symbol there,
it searches in the local symbol tables for previous command levels. If it does
not find the symbol, DCL then looks in the global symbol table.

2-7

DCL Concepts
2.3 Symbols

2.3.2

Creating Symbols
Use an assignment statement to create a symbol. An assignment statement
has the following format:
$ symbol=[=] expression

The left side of the assignment statement defines the symbol name; the right
side of the assignment statement contains an expression. When you create a
symbol, DCL evaluates the expression and assigns the result to the symbol. If
the evaluated expression is an integer, then the symbol has an integer value.
If the expression evaluates to a character string, then the symbol has a string
value. If you used two equal signs, the symbol is a global symbol; if you used
one equal sign, the symbol is a local symbol.
The following example creates a local symbol and a global symbol:
$ SUM = 5 + 7
$ NAME == "MORTIMER" + " SNERD"

The local symbol SUM has an integer value because the expression (5 +
7) evaluates to an integer (12). The global symbol NAME has a string value
because the expression evaluates to a character string ("MORTIMER SNERD").
Note that you must enclose character strings in quotation marks when they
are used in expressions.

2.3.3

Displaying the Value of a Symbol
Use the SHOW SYMBOL command to display the value of a symbol. For
example:
$ SHOW SYMBOL SUM

SUM = 12

Hex = OOOOOOOC

Octal = 00000000014

$ SHOW SYMBOL NAME

NAME == "MORTIMER SNERD"

Note that when a symbol has an integer value, the SHOW SYMBOL
command displays the value in decimal, hexadecimal, and octal notation.

2.3.4

Masking the Value of Symbols
The SET SYMBOL command masks the values of local and global symbols
without deleting these symbols. Use the SET SYMBOL command to isolate
the local or global symbols in a command procedure from the symbols
defined in other command procedures. For example, if your complex
command procedure executes another command procedure, you can use
the same symbol names in both procedures if you specify the SET SYMBOL
command in the second command procedure.
The SET SYMBOL/SCOPE=NOLOCAL command causes all local symbols
defined at an outer procedure level to be inaccessible to the current procedure
level and any inner level. For example, if you specify the SET SYMBOL
/SCOPE=NOLOCAL command at procedure levels 2 and 4, procedure level
2 can access only level 2 local symbols. Procedure level 3 can access levels 2
and 3 local symbols, and level 4 can access only level 4 local symbols.

2-8

DCL Concepts
2.3 Symbols

The SET SYMBOL/SCOPE=NOGLOBAL command causes all global symbols
to become inaccessible for all subsequent commands in the current and inner
procedure levels until either the SET SYMBOL/SCOPE=GLOBAL command
is specified or the procedure exits to a level at which global symbols were
accessible.

2.3.5

Deleting Symbols
You can delete local symbols with the DELETE/SYMBOL command. By
default, DELETE/SYMBOL attempts to delete symbols from the current
local symbol table. If you want to delete a global symbol, you must use the
/GLOBAL qualifier. To delete the global symbol GO, enter the following
command:
$ DELETE/SYMBOL/GLOBAL GO

2.4

Expressions
Expressions are values or groups of values that DCL evaluates. There are two
types of expressions:
•

Integer expression-an expression that evaluates to an integer

•

Character string expression-an expression that evaluates to a character
string

Expressions are used in symbol assignment statements (on the right side of
the equal sign), in IF statements, in WRITE commands, and as arguments for
lexical functions.
Expressions can contain character strings, integers, lexical functions, symbols
or combinations of these values. When used in expressions, these values
are called operands. If an expression contains more than one operand,
the operands are connected by operators that specify the operations to be
performed. The following examples illustrate expressions:
y = 25

This integer expression contains only one
operand, the number 25. Therefore, the
value 25 is assigned to the symbol Y.

x = y -8

This integer expression contains two
operands: Y and 8. Y is a symbol and
8 is an integer. The minus sign is an
operator indicating subtraction. When
DCL evaluates this expression, it replaces
the symbol Y with its actual value and
performs the subtraction.

TITLE = "TWELFTH" + " NIGHT"

This string expression contains two
operands: "TWELFTH" and " NIGHT".
Because both operands are character
strings, the plus sign indicates that the
strings should be concatenated. When
DCL evaluates this expression, the result is
"TWELFTH NIGHT".

2-9

DCL Concepts
2.4 Expressions

IF COUNT .EO. 4 THEN EXIT

2.4.1

In this IF statement, DCL determines
whether the integer expression COUNT
.EO. 4 is true. DCL replaces the symbol
COUNT with its actual value and tests
whether it equals 4. If it does, then the
command procedure exits.

Values in Expressions
The following sections describe values that can be used in expressions. These
values include the following:

2.4.1.1

•

Character strings

•

Integers

•

Symbols

•

Lexical functions

Character Strings
When you use a character string in an expression, you must enclose it in
quotation marks. (If you do not use quotation marks, DCL processes the
string as a symbol.) To include quotation marks within a string, type two
consecutive quotation marks. For example:
$PROMPT= "Type ""YES"" or ""NO"""
$ SHOW SYMBOL PROMPT
PROMPT = "Type "YES" or "ND""

To continue a character string over two lines, use a plus sign (for string
concatenation) and a hyphen (for continuation):
$ ADVICE = "A STITCH IN TIME " + _$ "SAVES NINE"
$ SHOW SYMBOL ADVICE
ADVICE = "A STITCH IN TIME SAVES NINE"

You cannot use the hyphen continuation character within a quoted character
string.

2.4.1.2

Integers
Specify integers as decimal numbers (numbers in base 10) unless you use
the radix operator %X (for hexadecimal) or %0 (for octal). Do not place
quotation marks around integers. For example:
$ NUM = 17
$ HEXNUM = %X1AB

2-10

DCL Concepts
2.4 Expressions

2.4.1.3

Symbols
When you use a symbol in an expression, the symbol's value is automatically
substituted for the symbol; do not surround the symbol name with quotation
marks. The following example uses the symbol COUNT in an expression:
$ COUNT = 3
$ TOTAL = COUNT + 1
$ SHOW SYMBOL TOTAL
TOTAL = 4 Hex = 00000004

Octal = 00000000004

The value for COUNT (3) is automatically substituted when the expression is
evaluated and the result is assigned to the symbol TOTAL.
Remember that when you use symbols within character strings, you must
use apostrophes to request symbol substitution. See Section 2.5.1 for more
information.

2.4.1.4

Lexical Functions
Lexical functions return information about an item or a list of items. (These
items are called arguments.) You invoke a lexical function by typing its name
and its argument list. You must always surround the argument list with
parentheses.

When you specify arguments for lexical functions, follow the rules for writing
expressions: enclose character strings in quotation marks; do not enclose
integers, symbols, and lexical functions in quotation marks.
You can use lexical functions in expressions in the same way you would
normally use character strings, integers, and symbols. When you use a lexical
function in an expression, DCL automatically evaluates the function and
replaces the function with its return value. For example:
$ SUM = F$LENGTH("BUMBLEBEE") + 1
$ SHOW SYMBOL SUM
SUM = 10
Hex = OOOOOOOA Octal = 00000000012

The F$LENGTH function returns the length of the value specified as its
argument. DCL automatically determines the return value (9) and uses this
value to evaluate the expression. Therefore, the result of the expression (9 +
1) is 10, and this value is assigned to the symbol SUM.
Note that each lexical function returns information as either an integer or a
character string. Also, note that you must specify the arguments for a lexical
function as either integer or character string expressions.
For example, the F$LENGTH function requires an argument that is a character
string expression, and it returns a value that is an integer. In the previous
example, the argument "BUMBLEBEE" is a character string expression and the
return value( 9) is an integer.
The following examples show different ways you can specify the argument for
the F$LENGTH function; in each example the argument is a character string
expression. The first example shows a symbol that is used as an argument:
$ BUG = "BUMBLEBEE"
$ LEN = F$LENGTH(BUG)
$ SHOW SYMBOL LEN
LEN = 9 Hex = 00000009

Octal = 00000000011

When you use the symbol BUG as an argument, do not place quotation
marks around it. The lexical function automatically substitutes the value
"BUMBLEBEE" for BUG, determines the length, and returns the value 9.

2-11

DCL Concepts
2.4 Expressions

This example shows an argument that contains both a symbol and a character
string:
$ BUG = "BUMBLEBEE"
$ LEN = F$LENGTH(BUG)
$ SHOW SYMBOL LEN
LEN = 9 Hex = 00000009 Octal = 00000000011
$ LEN = F$LENGTH(BUG + "S")
$ SHOW SYMBOL LEN
LEN = 10 Hex = OOOOOOOA Octal = 00000000012

The symbol BUG is not enclosed in quotation marks, but the string "S" is. The
argument must be evaluated before the F$LENGTH function can determine
the length. The value represented by the symbol BUG ("BUMBLEBEE")
is concatenated with the string "S"; the result is "BUMBLEBEES". The
F$LENGTH function determines the length of the string "BUMBLEBEES"
and returns the value 10.
The next example uses another lexical function as the argument for the
F$LENGTH function. (The F$DIRECTORY function returns the name of your
current default directory, including the square brackets. In this example, the
current default directory is [SALMON].)
$LEN = F$LENGTH(F$DIRECTORY())
$ SHOW SYMBOL LEN
LEN = 8 Hex = 00000008 Octal = 00000000010

Do not place quotation marks around the F$DIRECTORY function when it is
used as an argument; the function is automatically evaluated. The result of
the F$DIRECTORY function must be returned before the F$LENGTH function
can determine the length. Then, the F$LENGTH function determines the
length of your default directory, including the square brackets.
Appendix B gives a brief description of each lexical function. For complete
information, see the Lexical Functions section in the VMS DCL Dictionary.

2.4.2

Operators Used in Expressions
When an expression has more than one operand, the operands are connected
by operators. Table 2-1 lists the operators in the order in which they are
evaluated if there are two or more operators in an expression. The operators
are listed from highest to lowest precedence; that is, operators at the top
of the table are performed before operators at the bottom. If an expression
contains operators that have the same order of precedence, the operations are
performed from left to right.
You can override the normal order of precedence by using parentheses. For
example:
$ RESULT = 4 * (6 + 2)
$ SHOW SYMBOL RESULT
RESULT = 32 Hex = 00000020

Octal = 00000000040

In this example, the parentheses force the addition to be performed before the
multiplication. If you had not used the parentheses, the multiplication would
have been performed first and the result would have been 26. See the VMS
DCL Concepts Manual for complete information on using each operator.

2-12

DCL Concepts
2 .4 Expressions

Table 2-1

Summary of Operators in Expressions

Operator

Precedence

Description

Indicates a positive number

Indicates a negative number

Multiplies two numbers

Divides two numbers

Adds two numbers or concatenates two character
strings

Subtracts two numbers or reduces a string

.EOS.

Tests if two character strings are equal

.GES.

Tests if first string is greater than or equal to
second

.GTS.

Tests if first string is greater than second

.LES.

Tests if first string is less than or equal to second

.LTS.

Tests if first string is less than second

.NES.

Tests if two strings are not equal

.EO.

Tests if two numbers are equal

.GE.

Tests if first number is greater than or equal to
second

.GT.

Tests if first number is greater than second

.LE.

Tests if first number is less than or equal to
second

.LT.

Tests if first number is less than second

.NE.

Tests if two numbers are not equal

.NOT.

Logically negates a number

.AND.

Combines two numbers with a logical AND

.OR.

Combines two numbers with a logical OR

When you write expressions that contain two or more values connected by
operators, the values should all have the same data type. Values either have
string or integer data types. String data includes character strings, symbols
with string values, and lexical functions that return string values. Integer
data includes integers, symbols with integer values, and lexical functions that
return integer values.
If you use different data types, DCL converts values to the same type before
evaluating the expression. In general, if you use both string and integer
values, the string values are converted to integers. The only exception is
when DCL performs string comparisons; in these comparisons, integers are
converted to strings. See the VMS DCL Concepts Manual for more information
on how DCL converts integers to strings, and strings to integers.

2-13

DCL Concepts
2.5 Symbol Substitution

2.5

Symbol Substitution
In certain contexts, DCL assumes that a string of characters beginning with a
letter is a symbol name or a lexical function. In these contexts, DCL tries to
replace the symbol or lexical function with its value. If you use a symbol or
lexical function in any other context, you must use a substitution operator to
request symbol substitution.
DCL automatically evaluates symbols and lexical functions when they are
used in expressions. Therefore, DCL evaluates symbols and lexical functions
automatically when they are as follows:
•

On the right side of an= or== assignment statement

•

In an argument for a lexical function

•

In a DEPOSIT, EXAMINE, IF, or WRITE command

In addition, DCL evaluates symbols at the beginning of a line when the
symbol is not followed by an equal sign or a colon. (The examples in the
previous sections used symbols and lexical functions in places where they
were automatically evaluated.)
You can use symbols and lexical functions in other places in command lines
if you use special operators to request symbol substitution. In general, use

apostrophes to request symbol substitution. There are special cases where
you must use an ampersand instead.

2.5.1

Using Apostrophes as Substitution Operators
Use apostrophes to request symbol substitution when you use symbols and
lexical functions in places where they are not automatically substituted. Place
apostrophes around the symbol for which you are requesting substitution.
For example:
$ FILENAME = "CALENDAR.DAT"
$ TYPE 'FILENAME'

In this example, the apostrophes indicate that FILENAME is a symbol that
DCL should translate. If the symbol FILENAME is equated to the string
"CALENDAR.DAT", then the file CALENDAR.DAT is displayed. If you had
not included the apostrophes, DCL would not have performed the symbol
substitution.
You can use apostrophes to perform symbol substitution when you
concatenate two symbol names, as follows:
$ NAME = "EXAMPLES"
$TYPE= .TST"
$PRINT 'NAME''TYPE'
11

When the command is executed, the values for NAME and TYPE are
substituted for the symbols. The two strings "EXAMPLES" and ".TST" are
concatenated, forming the file name "EXAMPLES.TST".
To request symbol substitution for a symbol within a character string, place
two apostrophes before the symbol name and one apostrophe after it. For
example:

2-14

DCL Concepts
2.5 Symbol Substitution

$ PROMPT_STRING = "Creating file ''FILENAME'. TST"

If the current value of the symbol FILENAME is the string "BUGS", the result
of the symbol substitution is the string "Creating file BUGS.TST".

2.5.2

Using Ampersands as Substitution Operators
The ampersand can also be used to request symbol substitution. The
difference between the apostrophe and the ampersand is the time when
substitution occurs. Symbols preceded by apostrophes are substituted
during the first phase of DCL command processing; symbols preceded by
ampersands are substituted during the second phase. Sometimes, the result
of using these operators is the same:
$ TYPE 'FILENAME'
$ TYPE &FILENAME

If symbol FILENAME is equated to the string "BUGS", then both commands
will type the file BUGS.LIS. (The TYPE command provides the default file
type LIS.)

However, sometimes you must use the ampersand to get the correct results.
For example, when you pass parameters to a command procedure these
parameters are equated to the symbols Pl through P8. You may need to use
the following syntax when you are refering to parameters that were passed to
a procedure:
$ PRINT &P'COUNT'

In this example, you want to print the file indicated by the first parameter,
Pl. First, DCL replaces the symbol COUNT with its value. If its value were
1, the resulting string would be as follows:
$ PRINT &Pi

Next, DCL performs the substitution requested by the ampersand, and
substitutes the appropriate value for Pl. If Pl were COMMENTS.DAT, the
resulting string would be as follows:
$PRINT COMMENTS.DAT

In general, do not use the ampersand for symbol substitution unless it is
required to translate your symbols correctly. For complete information on
symbol substitution, see the VMS DCL Concepts Manual.

2.5.3

Distinguishing between Symbols and Logical Names
It is easy to confuse symbols and logical names, especially when symbols
are used in place of file specifications (as shown in some previous examples).
The main difference between logical names and symbols is the manner in
which they are translated: DCL performs symbol substitution, but utilities
and programs perform logical name translation.

When you enter a command string, DCL examines the string to make sure it
is valid. While examining the string, DCL checks for symbols in the places
where it expects to find symbols. DCL also checks for symbols in places
indicated by substitution operators. After DCL evaluates the command string,
the command starts to execute. The command must then examine the file or
device specification to determine what file to process. When doing this, the
command checks whether the specification contains a logical name.

2-15

Command Procedure Input/Output

This chapter describes how to send input to and receive output from
command procedures. It discusses the following topics:

3.1

•

Passing input data to command procedures and to commands and images
you execute from within command procedures

•

Controlling output from command procedures

•

Displaying information at the terminal

Passing Data to Command Procedures
You may need to pass input data to a command procedure when you execute
the command procedure. DCL provides three ways to pass this input data:
•

Passing data to a command procedure using parameters

•

Issuing a prompt to the user at the terminal; the user enters data
interactively.

•

Reading data from an input file.

The following sections describe how to pass parameters and how to obtain
data from a user at a terminal. See Chapter 6 for information on reading data
from a file.

3.1.1

Passing Parameters
When you execute a command procedure interactively, you can pass up
to eight parameters by placing the values of the parameters after the file
specification of the command procedure. To pass parameters to a batch job,
use the /PARAMETERS qualifier to the SUBMIT command. See Chapter 8
for more information on passing parameters to batch jobs.
Parameter values are assigned to the local symbols Pl through PS. For
example:
$ ©COPYSORT INSORT.DAT OUTSORT.DAT

When this command procedure is executed, two parameters are passed:
INSORT.DAT and OUTSORT.DAT. The first parameter (Pl) has the value
INSORT.DAT; the second (P2) has the value OUTSORT.DAT.
The command procedure COPYSORT.COM can then use the symbols Pl and
P2 to refer to the files it is processing. For example:

3-1

Command Procedure Input/Output
3.1 Passing Data to Command Procedures

$ ! Copy and sort a file
$ !

$COPY 'Pi' USER_DISK: [MARY]*.*
$ SORT 'Pi' 'P2'
$ EXIT

This command procedure copies the file INSORT.DAT from your current
default directory to USER_DISK:[MARY]*.*· Then, it sorts INSORT.DAT and
places the sorted file in OUTSORT.DAT.
By using parameters, you can process different files each time you run the
procedure, but you do not need to rewrite the procedure.
When you list parameters on a command line, separate them with one or
more spaces, tabs, or both. To pass a null parameter, use a set of quotation
marks as a place holder in the command string. For example:
$ ©COPYFILES 1111 USER_DISK: [MARY]*.*

When COPYFILES.COM is executed, Pl will be a null string, but P2 will
have the value "USER_DISK:[MARY]*.*".
You can specify a parameter as an integer, a string, or a symbol. When you
specify a parameter as an integer, the integer is converted to a string when it
is assigned to one of the symbols Pl through P8. For example:
$ ©ADDER 24 25

When you specify a parameter as a string, DCL automatically converts the
letters in the string to uppercase. To preserve spaces, tabs, or lowercase
letters, enclose the string in quotation marks. If you pass fewer than eight
parameters, the extra symbols are assigned null string values. If you attempt
to pass more than eight parameters, the system displays an error message and
the command procedure does not execute.
The following command procedure PARAMS.COM displays the parameters
passed to the procedure:
$ ! Displaying parameters
$ SHOW SYMBOL/LOCAL/ALL
$ EXIT

You can execute the procedure with the following parameters:
$ ©PARAMS Paul Cramer
P8 = ""

P7 = ""
P6 = ""

P5 = 1111
P4 = 1111
P3 = 1111
P2 = "CRAMER"
Pi = "PAUL"

Pl is assigned the value "PAUL" and P2 is assigned the value "CRAMER";
the strings are converted to uppercase because they are not surrounded in
quotation marks.
The following command passes only one parameter, "Paul Cramer"; the
quotation marks preserve the lowercase letters and spaces.

3-2

Command Procedure Input/Output
3.1 Passing Data to Command Procedures

$ ©PARAMS "Paul Cramer"
P8 = ""

P7 = ""

P6 = ""
P5 = ""

P4 = ""
P3

= ""

P2 = ""

P1 = "Paul Cramer"

To pass the value of a symbol, place apostrophe characters before and after
the symbol. When passing the symbol, DCL removes quotation marks that
enclose the string. The following commands create the symbol NAME and
pass values PAUL and CRAMER to the command procedure SEARCH.COM.
$ NAME = "Paul Cramer"
$ ©SEARCH 'NAME'

When you enter a nested procedure, new symbols Pl through PB are created
in the local symbol table for the nested procedure. These symbols are
assigned values passed by the invoking procedure.
The following example invokes SEARCH.COM, which in turn invokes the
nested command procedure GETNAME.COM.
$ ©SEARCH "Paul Cramer"

$ ! SEARCH.COM
$ ©GETNAME 'P1' Joe Cooper

Because Pl in SEARCH.COM is the string Paul Cramer, which contains
no quotation marks, it is passed to NAME.COM as two parameters. In
NAME.COM, Pl through PB are defined as follows:
Pl= PAUL
P2 =CRAMER
P3 =JOE
P4 =COOPER
PS-PB= Null
Because DCL removes quotation marks when passing a symbol, to preserve
spaces, tabs, and lowercase characters in a symbol value, you must enclose
the value in three sets of quotation marks. In the following example, the
literal value in Pl is enclosed in three sets of quotation marks and passed to
NAME.COM. If Pl originally contained the value "Paul Cramer", the value
"Paul Cramer" is passed to NAME.COM.
$ ! DATA.COM
$ QUOTE = """
$ P1 = QUOTE + P1 + QUOTE
$ ©NAME 'P1' "Joe Cooper"

In this example, Pl is Paul Cramer and P2 is Joe Cooper in the command
procedure NAME.COM.
An alternative is to enclose the text in quotation marks and, where a symbol
appears, precede it with two apostrophes, and follow it with one apostrophe.
$ ! DATA.COM
$ ©NAME "' 'P1'"

3-3

Command Procedure Input/Output
3.1 Passing Data to Command Procedures

3.1.2

Prompting for Input
You can use the INQUIRE command to prompt for input to be used by a
command procedure. The INQUIRE command issues a prompt, reads the
user's response from the terminal, and assigns it to a symbol. For example:
$ INQUIRE FILE "Filename"

This command issues the prompt "Filename: "to your terminal and assigns
your response to the symbol FILE. By default, the INQUIRE command inserts
a colon and a space at the end of the prompt string. You can suppress
this with the /NOPUNCTUATION qualifier as described in the VMS DCL

Dictionary.
The INQUIRE command converts your response to uppercase, replaces
multiple blanks and tabs with a single space, and removes leading and trailing
spaces. The INQUIRE command also performs apostrophe substitution for
symbols and lexical functions. To preserve lowercase characters, multiple
spaces, and tabs, enclose your response in quotation marks. Also, to include
quotation marks in your response, use two sets of quotation marks in the
places you want quotation marks to appear. For example:
$ INQUIRE FILE "Filename"
Filename: "OZ'"'WITCH GLINDA"": : [GLINDA] SPELLS. DAT"
$ SHOW SYMBOL FILE
FILE= "OZ"WITCH GLINDA":: [GLINDA] SPELLS.DAT"

Usually when you include an access control string, you enclose the user name
and password in quotation marks. However, when you provide the string in
response to the INQUIRE command, you must enclose the user name and
password in double quotation marks.
You can also use the READ command to obtain data and retain the original
case, spaces, and quotation marks. With the READ command, you do not
have to enclose your response in quotation marks or use two sets of quotation
marks to insert a quotation mark. For example:
$ READ/PROMPT=" Filename: " SYS$COMMAND FILE
Filename: OZ"witch glenda":: [glenda]spells.dat
$ SHOW SYMBOL FILE
FILE= "OZ"witch glenda":: [glenda]spells.dat"

You may find it useful to write command procedures that can either accept
parameters or prompt for user input if the required parameters are not
specified. For example:
$ ! Prompt for a file name if name
$ ! is not passed as a parameter
$ IF P1 .EQS. "" THEN INQUIRE P1 "Filename"

$COPY 'P1' DISKS: [RESERVED]*.*
$ EXIT

Note: If you submit a command procedure for execution as a batch job, DCL
reads the value for a symbol specified in an INQUIRE command from the
data line following the INQUIRE command. If you do not include a data
line, DCL assigns the symbol a null value.

3-4

Command Procedure Input/Output
3.2 Passing Data to Commands and Images

3.2

Passing Data to Commands and Images
When you execute DCL commands that execute images supplied with your
system or when you run your own images, you may need to provide input
data. Images obtain input from SYS$INPUT, the default input stream. In
a command procedure, SYS$INPUT is defined as the command procedure
file. Therefore, if commands or images require input data, they will look in
the command procedure file. However, you can redefine SYS$INPUT if you
want to provide data from your terminal or from an input file. The following
sections describe different methods of passing data to commands and images.

3.2.1

Including Data in the Command Procedure
Use data lines to include data for commands and images within the
procedure. The following command procedure runs the image CENSUS.EXE,
which requires input data. CENSUS.EXE obtains input from SYS$INPUT, the
command procedure file.
$!

Execute CENSUS

$ RUN CENSUS
1981
1982
1983

$ EXIT

Note that the command procedure passes the text on a data line directly
to CENSUS.EXE; DCL does not process the data lines. If you include DCL
symbols or expressions on data lines, DCL will not substitute values for the
symbols or evaluate the expressions. If you use an exclamation point in a
data line, the image to which you pass the data processes the exclamation
point.
To include data lines that begin with dollar signs in the input stream, you
must define the input data in a way that prevents the command interpreter
from attempting to execute the data as a command. To delimit such an input
stream, use the DECK and EOD (End of Deck) commands. For example:
$ ! Everything between the commands DECK and EOD
$ ! is written to the file WEATHER.COM
$ !
$ CREATE WEATHER.COM
$ DECK

$ FORTRAN SUMMER
$ LINK SUMMER
$ RUN SUMMER
$ EOD
$ !
$ ! Now execute WEATHER.COM
$ ©WEATHER
$ EXIT

This command procedure creates and executes WEATHER.COM. Because the
data lines begin with dollar signs, these lines are delimited by DECK and
EOD.

3-5

Command Procedure Input/Output
3.2 Passing Data to Commands and Images

You can also place programs in the command procedure file by specifying
the name of the data file as SYS$INPUT. This causes the compiler to read
the program from the command procedure, rather than from another file.
The following example illustrates a command procedure that contains a
FORTRAN command followed by the program's statements:
$ FORTRAN/OBJECT=TESTER/LIST=TESTER SYS$INPUT
C THIS IS A TEST PROGRAM
A=1
B =2

STOP
END
$ PRINT TESTER.LIS
$ EXIT

In this example, the FORTRAN command uses the logical name SYS$INPUT
to identify the file to be compiled. Because SYS$INPUT is equated to the
command procedure, the FORTRAN compiler compiles the statements
following the FORTRAN command (up to the next line that begins with
a dollar sign). When the compilation completes, two output files are created:
TESTER.OBJ and TESTER.LIS. The PRINT command then prints the listing
file.
Include data in the command procedure when you always pass the same data
to the command or image you are running. However, if you want to pass
different data without rewriting the command procedure, you can redefine
SYS$INPUT to either your terminal or to a data file. The following sections
describe these techniques.

3.2.2

Supplying Data to an Image
To run an image from a command procedure and supply data to the image
interactively, redefine SYS$INPUT to be your terminal. After you redefine
SYS$INPUT as your terminal, the image called from the command procedure
obtains input from your terminal rather than from data lines in the command
procedure. Use this method of obtaining input when you execute command
procedures interactively. You cannot supply data interactively to batch mode
command procedures.
Use the following command to redefine SYS$INPUT as your terminal:
$ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND

SYS$COMMAND is a logical name that is, by default, defined as your
terminal when you are using the system interactively.
When you redefine SYS$INPUT (or any other logical name for a process
permanent file) you should use the /USER_MODE qualifier. The /USER_
MODE qualifier creates a temporary logical name assignment that is in effect
only until the next image completes.
For example, if you want to execute the image CENSUS.EXE but you want to
provide the years interactively, you can include the following commands in
your procedure:
$ ! Execute· CENSUS getting data from the terminal
$ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND
$ RUN CENSUS
$ EXIT

3-6

Command Procedure Input/Output
3.2 Passing Data to Commands and Images

The DEFINE/USER_MODE command temporarily redefines SYS$INPUT
while CENSUS.EXE is running, so CENSUS.EXE obtains its input from the
terminal. After CENSUS.EXE completes, SYS$INPUT reverts to its original
definition (the command procedure file.)
To use any DCL command or utility that requires interactive input in a
command procedure, you must redefine SYS$INPUT to be your terminal. For
example, the next command procedure uses the EDT editor:
$ ! Obtain a list of your files
$ DIRECTORY
$ !

$ ! Get file name and invoke the EDT editor
$ EDIT_LOOP:
$
INQUIRE FILE "File to edit (Press RET to end)"
$
IF FILE . EQS. II II THEN EXIT
$
DEFINE/USER_MODE SYS$INPUT SYS$COMMAND
$
EDIT 'FILE'
$
GOTO EDIT_LOOP

This command procedure prompts for file names until you terminate the loop
by pressing the RETURN key. When you enter a file name, the procedure
automatically invokes the EDT editor to edit the file. While the editor is
running, SYS$INPUT is defined as the terminal so you can enter your edits
interactively.

3.2.3

Defining SYS$1NPUT as a File
You can also redefine SYS$INPUT to be a data file. For example, the
following command procedure executes the image CENSUS.EXE, and the
input data is provided in the file YEARS.DAT:
$ !Execute CENSUS using data in YEARS.DAT
$ DEFINE/USER_MODE SYS$INPUT YEARS.DAT
$ RUN CENSUS
$ EXIT

If you redefine SYS$INPUT to be a file, you can change the data processed

by the command procedure by editing the data file.

3.3

Directing Output from Command Procedures
Command procedures can direct output in the following ways:
•

Writing data to the default output file, or redirecting data to another file

•

Displaying error messages when certain types of errors occur

•

Returning values as global symbols or logical names

•

Displaying verification of command and data lines

The following sections describe these methods of directing output.

3-7

Command Procedure Input/Output
3.3 Directing Output from Command Procedures

3.3.1

Redirecting Output from Command Procedures
In general, when you execute command procedures interactively, they display
output at your terminal. This happens because command procedures send
output to SYS$0UTPUT, which by default is defined as your terminal. Batch
jobs send output to a batch job log file. See Chapter 8 for more information
on batch job output.
You can redirect output to a file by using the /OUTPUT qualifier when
you execute a command procedure. In the following example, output from
SETD.COM is written to the file RESULTS.TXT instead of to the terminal:
$ ©SETD/OUTPUT=RESULTS.TXT

To determine the outcome of the command procedure, you can use the TYPE
command to display the file RESULTS.TXT or the PRINT command to print
it.

Note: When you use the /OUTPUT qualifier, be sure to place it immediately
after the command procedure file name, with no intervening spaces.
Otherwise DCL interprets the qualifier as a parameter to be passed to the
procedure.
When you redirect command procedure output to a file, the procedure sends
error messages to the terminal as well as to the file receiving the output. (See
Section 3.3.3 for more information on controlling error messages.)

3.3.2

Redirecting Output from Commands and Images
To suppress or redirect output from an individual command or image, use the
/OUTPUT qualifier with that command (if the command has an /OUTPUT
qualifier) or redefine SYS$0UTPUT for the duration of the command's
execution.
For example, to trap the output from the DIRECTORY command, you can use
the /OUTPUT qualifier. The output from the DIRECTORY command will be
sent to the specified file while the output from other commands will still be
sent to the terminal. For example:
$ ! Trap the output from DIRECTORY in NUMBER.DAT
$ ! Accumulate this information in GRAND_TOTAL.DAT
$

$ DIRECTORY/TOTAL/OUTPUT=NUMBER.DAT
$ APPEND/LOG NUMBER.DAT GRAND_TOTAL.DAT
$ EXIT

When you execute this procedure, do not use the /OUTPUT qualifier with
the@ command because you want to redirect only the output from the
DIRECTORY command.
However, some commands do not have /OUTPUT qualifiers. To trap the
output from such a command, temporarily redefine SYS$0UTPUT as a file.
(SYS$0UTPUT is the logical name that commands and images generally use
to determine where to send output.) You can also redefine SYS$0UTPUT to
trap the output from a user-written program.

3-8

Command Procedure Input/Output
3.3 Directing Output from Command Procedures

The following example shows how to redirect the output from the SHOW
USERS command to a file. Because you used the /USER_MODE qualifier,
the new definition for SYS$0UTPUT is in effect only for the execution of the
SHOW USERS command. (The /USER_MODE qualifier creates a temporary
logical name assignment that is in effect only until the next image completes.)
Then, SYS$0UTPUT reverts to its default definition (the terminal).
$ DEFINE/USER_MODE SYS$0UTPUT SHOW_USER.DAT
$ SHOW USERS
$ !

$ ! Process the information in SHOW_USER.DAT
$ OPEN/READ INFILE SHOW_USER.DAT
$ READ INFILE RECORD

$ CLOSE INFILE
$ EXIT

To suppress output entirely from a command, temporarily define
SYS$0UTPUT as a null device. For example:
$ DEFINE/USER_MODE SYS$0UTPUT NL:
$ APPEND NEW_DATA.DAT STATS.DAT

You cannot use the DEFINE/USER_MODE command to redirect output
from DCL commands that are executed within the command interpreter.
Table 3-1 lists the commands that are executed within the command
interpreter. Instead, you can redirect output from commands that are executed
within the command interpreter by using the DEFINE command to redefine
SYS$0UTPUT, and then using the DEASSIGN command to delete the
definition when you are through with it. For example:
$ DEFINE SYS$0UTPUT TIME.DAT
$ SHOW TIME
$ DEASSIGN SYS$0UTPUT

After you deassign SYS$0UTPUT, its default value is restored.
Table 3-1

Commands Performed Within the Command Interpreter
ALLOCATE

ASSIGN

ATTACH

CALL

CANCEL

CONNECT

CONTINUE

CREATE/LOGICAL_NAME_TABLE

DEALLOCATE

DEASSIGN

DEBUG

DECK

DEFINE

DEFINE/KEY

DELETE/SYMBOL

DISCONNECT

ELSE

ENDIF

ENDSUBROUTINE

EOD

EXAMINE

EXIT

GOSUB

GOTO

INQUIRE

OPEN

READ

RECALL

RETURN

3-9

Command Procedure Input/Output
3.3 Directing Output from Command Procedures

Table 3-1 (Cont.)

3.3.3

Commands Performed Within the Command Interpreter

SET CONTROL

SET DEFAULT

SET KEY

SET ON

SET OUTPUT_RA TE

SET PROMPT

SET PROTECTION/DEFAULT

SET UIC

SET SYMBOL/SCOPE

SET VERIFY

SHOW DEFAULT

SHOW KEY

SHOW QUOTA

SHOW STATUS

SHOW SYMBOL

SHOW TIME

SHOW TRANSLATION

SPAWN

STOP

SUBROUTINE

THEN

WAIT

WRITE

Redirecting Error Messages
By default, command procedures send error messages to the file indicated
by SYS$ERROR. You can redefine SYS$ERROR to direct error messages to
a specified file. However, if you redefine SYS$ERROR to be different from
SYS$0UTPUT (or if you redefine SYS$0UTPUT without also redefining
SYS$ERROR), DCL commands and images using standard VMS error display
mechanisms send error and severe error messages to both SYS$ERROR and
SYS$0UTPUT. Therefore, you receive these messages twice-once in the file
indicated by the definition of SYS$ERROR, and once in the file indicated by
SYS$0UTPUT. Success, informational, and warning messages are sent only
to the file indicated by SYS$0UTPUT.
If you want to suppress error messages from a DCL command, be sure that
neither SYS$ERROR nor SYS$0UTPUT is equated to the terminal. For
example, the following command procedure accepts a directory name as a
parameter, sets the default to that directory, and purges files in the directory.
In order to suppress error messages, the procedure temporarily defines
SYS$ERROR and SYS$0UTPUT as the null device.
$ ! Purge files in a directory and suppress messages
$ !
$SET DEFAULT 'P1'
$ ! Suppress messages
$ !
$ DEFINE/USER_MODE SYS$ERROR NL:

$ DEFINE/USER_MODE SYS$DUTPUT NL:
$ PURGE
$ EXIT

You can also use the SET MESSAGE command to suppress messages. For
example:

3-10

Command Procedure Input/Output
3.3 Directing Output from Command Procedures

$ ! Purge files in a directory and suppress messages
$ !

$SET DEFAULT 'Pi'
$ ! Suppress messages
$ !

$ SET MESSAGE/NOFACILITY /NOIDENTIFICATION /NOSEVERITY /NOTEXT
$ PURGE
$ SET MESSAGE/FACILITY /IDENTIFICATION /SEVERITY
/TEXT
$ EXIT

Note that if you run one of your own images from a command procedure
and the image references SYS$ERROR, the image sends error messages
only to the file indicated by SYS$ERROR-even if SYS$ERROR is different
from SYS$0UTPUT. Only DCL commands and images using standard VMS
error display mechanisms send error messages to both SYS$ERROR and
SYS$0UTPUT when these files are different.

3.3.4

Using Global Symbols to Return Data
To return a value from a command procedure (either to a calling procedure
or to DCL command level), you can assign the value to a global symbol
because the global symbol can be read at any command level. You should
use comments to explain the use of any global symbols.
The following command procedure, AVERAGE.COM, computes the average
of up to eight numbers that are passed as parameters:
$ ! Find sum of the numbers (SUM) and
$ ! determine how many numbers are being averaged (COUNT)
$ !

$ IF Pi . EQS. II II THEN GOTO ERR
$ COUNT = i
$ SUM = 0
$ LOOP:
$ IF p 'COUNT' . EQS . II II THEN GOTO DONE
$ SUM = &P'COUNT' + SUM
$
COUNT = COUNT + i
$ GOTO LOOP
$

Compute the average and store in the global symbol AVERAGE

$ DONE:
$ AVERAGE == SUM/(COUNT-i)
$ EXIT
$ !
$ ERR:

$
$

WRITE SYS$0UTPUT "No numbers were provided."
EXIT

You can invoke AVERAGE.COM from another procedure, and then use the
global symbol AVERAGE to indicate the average. For example:

3-11

Command Procedure Input/Output
3.3 Directing Output from Command Procedures

$ ©AVERAGE 34 60 22 86
$WRITE SYS$0UTPUT "The average is ",AVERAGE

3.3.5

Using Logical Names to Return Data
You can also use logical names to return data from a nested command
procedure to the calling procedure. When a logical name is defined, it
is available at any command level. The following command procedure,
REPORT.COM, obtains the file name for a report. Then the procedure
defines the logical name REPORT_FILE, using the user-supplied name as the
equivalence string. Finally, the procedure executes a program that writes a
report to REPORT_FILE.
$! Obtain the name of a file and then run
$! REPORT.EXE to write a report to the file
$!
$ INQUIRE FILE "Name of report file"
$ DEFINE/NOLOG REPORT_FILE 'FILE'
$ RUN REPORT
$ EXIT

If you invoke REPORT.COM from another procedure to create the report file,

the calling procedure can use the logical name REPORT_FILE to refer to the
report file. For example:
$! Command procedure that updates data files
$! and optionally prepares reports
$!
$ UPDATE:

$INQUIRE REPORT "Prepare a report [Y or N]"
$ IF REPORT THEN GOTO REPORT_SEC
$ EXIT
$!
$ REPORT_SEC:
$ ©REPORT
$ WRITE SYS$0UTPUT "Report written to " F$TRNLNM("REPORT_FILE")
$EXIT

3.3.6

Verifying Command Procedure Execution
By default, only the output from commands and images is displayed when
you execute command procedures interactively. If you also want to see
the DCL command lines, data lines, and comment lines, use the SET
VERIFY command. You can enter the SET VERIFY command either within
the command procedure or at the interactive command level. If you set
verification, the SET VERIFY command will be in effect for all subsequent
command procedures you execute during the terminal session until you enter
the SET NOVERIFY command.
For example, to display lines in a particular command procedure, place the
SET VERIFY command at the beginning of the procedure and place the SET
NOVERIFY command at the end:

3-12

Command Procedure Input/Output
3.3 Directing Output from Command Procedures

$ ! Turn verification on
$ !

$ SET VERIFY
$ LOOP:
$
INQUIRE FILE "File name"
$
IF FILE . EQS. 1111 THEN EXIT
$
PRINT 'FILE'
$
GOTO LOOP
$ Turn verification off
$

$ SET NOVERIFY

You can interrupt the interactive execution of a command procedure to turn
verification on if that command procedure contains neither the SET VERIFY
command nor a CTRL/Y handler. As shown in the following example, press
CTRL/Y to interrupt execution, enter the SET VERIFY command, and enter
the CONTINUE command to continue execution of the command procedure
(with verification turned on.)
$ ©MASTER
lcTRL/YI

Interrupt
$ SET VERIFY
$ CONTINUE
$
The next step in this procedure is to

Verifying that a command procedure executes successfully is the principal
debugging tool for detecting errors in a command procedure. If the SET
NOVERIFY command is in effect and an error occurs, it may be difficult to
determine which command caused the error. With the SET VERIFY command
in effect, it is much easier to determine the cause of the error.
You can use the SET VERIFY command with special keywords to indicate
that only command lines or data lines are to be verified. See the VMS DCL
Dictionary for more information on the SET VERIFY command.
You can also use the F$VERIFY lexical function to change verification states.
For example:
$ ! Turn verification on
$ !
$ TEMP = F$VERIFY(1)
$ LOOP:
$
INQUIRE FILE "File name"
$
IF FILE .EQS."" THEN EXIT
$
PRINT 'FILE'
$
GOTO LOOP
$ Turn verification off
$

$ TEMP = F$VERIFY(O)
$ EXIT

See Chapter 4 for information on how to save verification settings before you
change them.

3-13

Command Procedure Input/Output
3.4 Writing Data to the Terminal

3.4

Writing Data to the Terminal
There are several ways that you can write data to the terminal. The most
common ways are with the WRITE command and the TYPE command, as
described in the following sections.

3.4.1

Using the WRITE Command
When you execute a command procedure interactively, you can use the
WRITE command to display lines at the terminal. To do this, specify the
output file as SYS$0UTPUT. You must express the data you want to write
as a string expression; the data can be a character string, a symbol, a lexical
function, or a combination of these entities.
The following example shows different ways you can use the WRITE
command:
$ ! The following line writes a character string
$WRITE SYS$0UTPUT "Two files were written."
$ !
$ ! The following line writes a symbol
$ FILE = "STAT1.DAT"
$ WRITE SYS$0UTPUT FILE
$ !

$ AFILE = "STAT1.DAT"
$ BFILE = "STAT2.DAT"
$ ! The following line writes a character string that
$ ! contains a symbol
$ WRITE SYS$0UTPUT " ' 'AFILE' and ' 'BFILE' were written. "
$ !

$ ! The following line writes a list of items
$ WRITE SYS$0UTPUT AFILE, " and " , BFILE," were written."
$EXIT

To display a long line, continue the line over two lines. For example:
$ ! writing a long line
$ WRITE SYS$0UTPUT "REPORT BY MARY JONES" + II PREPARED APRIL 15,
1984"
$ EXIT

To include quotation marks in a string you are writing, use two sets of
quotation marks in the places you want quotes to appear. For example:
$ ! including quotes
$ WRITE SYS$0UTPUT "SUMMARY OF ""Q AND A"" SESSION"
$ EXIT

3-14

Command Procedure Input/Output
3.4 Writing Data to the Terminal

3.4.2

Using the TYPE Command
Use the TYPE command to display text that is several lines long and does
not require symbol substitution. The TYPE command writes data from the
file you specify to SYS$0UTPUT. For interactive command procedures,
SYS$INPUT is, by default, the file you are typing from. The TYPE command
reads data from the data lines that follow and displays these lines on the
terminal. For example:
$ ! Using TYPE to display lines
$ TYPE SYS$INPUT
REPORT BY MARY JONES
PREPARED APRIL 15, 1988
SUBJECT: Analysis of Tax Deductions for 1987

$ EXIT

When you use the TYPE command to display data, DCL does not process
the data lines. Therefore, DCL does not evaluate symbols, expressions, and
lexical functions. Use the WRITE command to display data if you need to
evaluate symbols, expressions, or lexical functions.
You can also use the TYPE command to execute command procedures on a
remote node. See Section 1.2.3 for instructions.

3-15

Using Lexical Functions

This chapter shows some types of information you can obtain and manipulate
within a command procedure using lexical functions. It shows how to get
information about

•

Your process

•
•
•
•
•

The system
Files and devices
Logical names
Strings
Data types

This chapter gives general information for each lexical function; for complete
descriptions, see the VMS DCL Dictionary. In addition, Appendix B lists each
lexical function and its arguments.
Many lexical functions return information that you can also get from DCL
commands. You can manipulate information in a command procedure more
easily if you obtain it from a lexical function, rather than from a command.
For example, you can use either the F$ENVIRONMENT function or the
SHOW DEFAULT command to obtain the name of your current default
directory. If you use the F$ENVIRONMENT function, you can assign the
result to a symbol, and then use this symbol later in the procedure, as
follows:
$ DIR_NAME = F$ENVIRONMENT("DEFAULT")
$ SET DEFAULT DISK4: [TEST]

$ SET DEFAULT 'DIR_NAME'

The F$ENVIRONMENT function returns the current default disk and
directory, and stores this value in the symbol DIR_NAME. At the end of
the procedure, you use the symbol DIR_NAME to restore the default with
the SET DEFAULT command.
If you obtain the value of the current default directory with the SHOW

DEFAULT command, rather than the F$ENVIRONMENT lexical function,
you cannot assign this output to a symbol. Instead, you must redirect the
output of the SHOW DEFAULT command to a file. To reset the default
directory, you must open the file containing the SHOW DEFAULT command
output, read and parse the record containing the directory name, reset the
directory, and close the file. Then, you must delete the file containing the
SHOW DEFAULT output.

4-1

Using Lexical Functions
4.1 Obtaining Information About Your Process

4.1

Obtaining Information About Your Process
You can use the following lexical functions to obtain information about your
process:
F$DIRECTORY

Returns the current default directory string.

F$ENVIRONMENT

Returns information about the command environment for
your process.

F$GET JPI

Returns accounting, status, and identification information
about your process, or about other processes on the
system.

F$MODE

Shows the mode in which your process is executing.

F$PRIVILEGE

Indicates whether your process has the specified
privileges.

F$PROCESS

Returns the name of your process.

F$SETPRV

Sets the specified privileges. This function also indicates
whether the specified privileges were previously enabled
before you used the F$SETPRV function.

F$USER

Returns your user identification code.

F$VERIFY

Indicates whether verification is on or off.

You often change process characteristics for the duration of a command
procedure, and then restore them. Table 4-1 shows process characteristics
that are commonly changed in command procedures; it also gives the lexical
functions that save these characteristics and the DCL commands that change
and restore the original settings.
Note that if you save process characteristics, you may need to ensure that
an error or CTRL/Y interrupt does not cause the procedure to exit before
restoring the original characteristics. See Chapter 7 for more information on
handling errors and CTRL/Y interrupts.
Table 4-1

Commonly Changed Process Characteristics

Characteristic

Operation

Command/Lexical Function

Control characters

Save:

F$ENVIRONMENT("CONTROL")

Restore:

SET CONTROL

Save:

F$ENVIRONMENT("PROMPT")

Restore:

SET PROMPT

Save:

F$ENVIRONMENT("PROTECTION")

Restore:

SET PROTECTION/DEFAULT

Save:

F$ENVIRONMENT("KEY_ST ATE")

Restore:

SET KEY

Save:

F$ENVIRONMENT("MESSAGE")

DCL prompt

Default protection

Key state

Message format

4-2

Using Lexical Functions
4.1 Obtaining Information About Your Process

Table 4-1 (Cont.)
Characteristic

Privileges

Verification

4.1.1

Commonly Changed Process Characteristics
Operation

Command/Lexical Function

Restore:

SET MESSAGE

Save:

F$PRIVILEGE or F$SETPRV

Restore:

F$SETPRV or SET PROCESS/PRIVILEGES

Save:

F$VERIFY or F$ENVIRONMENT

Restore:

F$VERIFY or SET VERIFY

Changing Verification Settings
It is a common technique to turn verification off for the duration of a

command procedure. This prevents users from displaying a procedure's
contents while executing the procedure. In command procedures, you can set
or disable two types of verification:
Procedure verification

Displays each command line as it is being
executed

Image verification

Displays each data line as it is being processed

The SET [NO]VERIFY command and the F$VERIFY function turn both types
of verification on or off unless you explicitly request that only one type of
verification be changed.
In general, you keep your procedure and image verification settings the
same. That is, you will keep them both on or off. However, you do not have
to keep them the same. Therefore, before you change these settings in a
command procedure, you should save each verification setting separately. For
example:
$ ! Save each verification state
$ ! Turn both states off
$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE")
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(O)

$ ! Restore original verification states
$ SAVE_VERIFY_IMAGE = F$VERIFY(SAVE_VERIFY_PROCEDURE,SAVE_VERIFY_IMAGE)

The F$ENVIRONMENT function returns the current image verification
setting, and assigns this value to the symbol SAVE_VERIFY_IMAGE. Next,
the F$VERIFY function returns the current procedure verification setting
and assigns this value to the symbol SAVE_VERIFY_PROCEDURE. The
F$VERIFY function also turns off both image and procedure verification.
Note that you can use the F$ENVIRONMENT function to obtain the
procedure verification setting, and then you can use the F$VERIFY function
to turn verification off. However, it is shorter to use F$VERIFY to accomplish
both tasks in one command line, as shown in the previous example.

4-3

Using Lexical Functions
4.1 Obtaining Information About Your Process

At the end of the procedure, you use the F$VERIFY function to restore the
original settings (specified by the symbols SAVE_VERIFY_PROCEDURE and
SAVE_VERIFY_IMAGE.)

4.1.2

Changing Default Protection
You may want to change the default file protection within a command
procedure. The following command procedure changes the default protection
associated with files created while the procedure is executing. The procedure
restores the original default file protection before terminating.
$ SAVE_PROT = F$ENVIRONMENT("PROTECTION")
$ SET PROTECTION = (SYSTEM:RWED, OWNER:RWED, GROUP, WORLD)/DEFAULT

$ SET PROTECTION=('SAVE_PROT')/DEFAULT
$ EXIT

Note that the F$ENVIRONMENT function returns the default protection code
using the syntax required by the SET PROTECTION command. This allows
you to use the symbol SAVE_PROT with the SET PROTECTION command
to restore the original default file protection.

4.2

Obtaining Information About the System
You can use the following lexical functions to obtain information about the
system:
F$GETOUI

Returns information about queues, batch and print
jobs currently in those queues, form definitions, and
characteristic definitions kept in the system job queue file.

F$GETSYI

Returns information about your local system or about a
node in your cluster (if your system is part of a cluster).

F$1DENTIFIER

Converts identifiers from named to numeric format, and
vice versa.

F$MESSAGE

Returns the message text associated with a status code.

F$PID

Returns the process identification number for processes
that you are allowed to examine.

F$TIME

Returns the current date and time.

The following sections describe how to obtain information about the system.

4-4

Using Lexical Functions
4.2 Obtaining Information About the System

4.2.1

Determining Your Node Name
If your system is part of a network or a cluster where you can log into many

different nodes, you can set the DCL prompt to indicate which node you
are currently using. To do this, include the F$GETSYI function in your
login command procedure to determine the node name. Then use the SET
PROMPT command to set a unique prompt for the node. For example:
$ NODE = F$GETSYI("NODENAME")
$SET PROMPT= "''NODE'$
II

If you want to use only a portion of the node name in your prompt string,

use the F$EXTRACT function to extract the appropriate characters. (See
Section 4.5.2 for more information on extracting characters.)

4.2.2

Obtaining Information About Queues
You can use the F$GETQUI function to get many types of information about
batch and print queues. You must have either READ access to the job or
SYSPRV or OPER privilege to obtain information about jobs and files in
queues.
The following example shows how to determine if the batch queue VAXl_
BATCH is in a stopped state. The value returned is either TRUE or FALSE. If
the queue is not stopped, the command procedure submits a job to the queue.
$ QSTOPPED = F$GETQUI ("DISPLAY_QUEUE",
$ IF QSTOPPED THEN GOTO NOBATCH
$ SUBMIT/QUEUE=VAX1_BATCH TEST.COM
$ NOBATCH:

4.2.3

QUEUE_STOPPED 11 , "VAX1_BATCH")

Obtaining Information About Processes
You can use the F$PID function to get the process identification number (PID)
for all processes that you are allowed to examine. You can obtain PIDs for all
processes on the system if you have WORLD privilege; you can obtain PIDs
for all processes in your group if you have GROUP privilege. If you have
neither GROUP nor WORLD privilege, you can obtain only the PID for your
process.
The following example shows how to obtain and display the PIDs for the
processes you are allowed to examine.

4-5

Using Lexical Functions
4.2 Obtaining Information About the System

$ ! Display the time when this procedure
$ ! begins executing
$ WRITE SYS$0UTPUT F$TIME()
$ !

$ CONTEXT = 1111
$ START:
$ ! Obtain and display PIDs until
$ ! F$PID returns a null string
$ !

$ PID = F$PID(CONTEXT)
$ IF PID .EQS. 1111 THEN EXIT
$WRITE SYS$0UTPUT "Pid --- ''PID'"
$ GOTO START

In this example, the system uses the symbol CONTEXT to hold a pointer into
the system list of PIDs. Each time through the loop, the system changes the
pointer to locate the next PID in the list. The procedure exits after all PIDs
have been displayed.
After you obtain a PID, you can use the F$GETJPI function to obtain specific
information about the process. For example, you can enhance the above
procedure so that it displays the PID and the UIC for each process:
$ CONTEXT = 1111
$ START:
$ ! Obtain and display PIDs and UICs
$ !

$ PID = F$PID(CONTEXT)
$ IF PID . EQS. 1111 THEN EXIT
$ UIC = F$GETJPI(PID, 11 UIC 11 )
$ WRITE SYS$0UTPUT "Pid --- ''PID'
$ GOTO START

Uic--- ''UIC' "

Note that you can shorten this command procedure by including the
F$GETJPI function within the WRITE command, as follows:
$ CONTEXT = 1111
$ START:
$ PID = F$PID(CONTEXT)
$ IF PID .EQS. 1111 THEN EXIT
$ WRITE SYS$0UTPUT "Pid --- ''PID'
$ GOTO START

4.3

Uic --- ''F$GETJPI(PID, 11UIC 11 ) ' "

Obtaining Information About Files and Devices
You can use the following lexical functions to obtain information about files
and devices:
F$FILE_A TTRIBUTES

Returns information about file attributes.

F$GETDVI

Returns information about a specified device.

F$PARSE

Parses a file specification and returns the requested
field(s).

F$SEARCH

Searches a directory for a file.

The following sections describe how to obtain some commonly used file
information;

4-6

Using Lexical Functions
4.3 Obtaining Information About Files and Devices

4.3.1

Searching for a File in a Directory
Before processing a file, a command procedure should use the F$SEARCH
function to test whether the file exists. For example, the following command
procedure uses F$PARSE to apply a device and directory string to the file
STATS.DAT. Then the procedure uses the F$SEARCH function to determine
whether STATS.DAT is present in DISK3:[JONES.WORK]. If it is, the
command procedure processes the file. Otherwise, the command procedure
prompts for another input file.
$ FILE = F$PARSE("STATS .DAT", "DISK3: [JONES. WORK]",,, "SYNTAX_ONLY")
$ IF F$SEARCH(FILE) .EQS. "" THEN GOTO GET_FILE
$ PROCLSS_FILE:

$ GET_FILE:
$
INQUIRE FILE "File name"
$
GOTO PROCESS_FILE

After determining that a file exists, the procedure can use the F$P ARSE or the
F$FILE_ATTRIBUTES function to get additional information about the file.
For example:
$ IF F$SEARCH("STATS.DAT") .EQS. "" THEN GOTO GET_FILE
$ PROCESS_FILE:
$
NAME = F$PARSE("STATS.DAT",, "NAME")

$ GET_FILE:
$
INQUIRE FILE "File name"
$
GOTO PROCESS_FILE

4.3.2

Deleting Old Versions of Files
If a command procedure creates files that you do not need after the procedure

terminates, delete or purge these files before you exit from the procedure. Use
the PURGE command to delete all versions except the most recent one; use
the DELETE command with a version number to delete a specific version of
the file or with a wildcard character in the version field to delete all versions
of the file.
To avoid error messages when using the DELETE command within a
command procedure, use the F$SEARCH function to verify that a file exists
before you try to delete it. For example, you can write a command procedure
that creates a file named TEMP.DAT only if certain modules are executed.
The following line issues the DELETE command only if TEMP.DAT exists:
$ IF F$SEARCH("TEMP.DAT") .NES. "" THEN DELETE TEMP.DAT;*

4-7

Using Lexical Functions
4.4 Translating Logical Names

4.4

Translating Logical Names
You can use the following lexical functions to translate logical names:
F$LOGICAL

Returns the equivalence string for a logical name.

F$TRNLNM

Returns either the equivalence string or the requested attributes
for a logical name.

Note: The F$TRNLNM function supersedes the F$LOGICAL function that
was used in earlier versions of the VMS operating system. You should
use F$TRNLNM (instead of F$LOGICAL) to ensure that your command
procedure processes logical names using the current system techniques.
In some situations, you may want to use logical names rather than symbols as
variables in command procedures. Programs can access logical names more
easily than they can access DCL symbols. Therefore, to pass information to
a program that you run from a command procedure, obtain the information
using a symbol. Then use the DEFINE command to equate the value of the
symbol to a logical name.
The following example tests whether the logical name NAMES has been
defined. If it has, the procedure runs PAYROLL.EXE. Otherwise, the
procedure obtains a value for the symbol FILE and uses this value to create
the logical name NAMES. PAYROLL.EXE uses the logical name NAMES to
refer to the file of employee names. For example:
$ ! Make sure that NAMES is defined
$ IF F$TRNLNM ("NAMES") . NES. "" THEN GOTO ALL_ SET
$ INQUIRE FILE "File with employee names"
$ DEFINE NAMES 'FILE'
$ !

$ ! Run PAYROLL, using the file indicated by NAMES
$ ALL_SET: .
$ RUN PAYROLL

You can also use the F$TRNLNM function to assign the value of a logical
name to a symbol. For example:
$ DEFINE NAMES DISK4: [JONES]EMPLOYEE_NAMES.DAT
$ RUN PAYROLL

$ FILE = F$TRNLNM(NAMES)
$WRITE SYS$0UTPUT "Finished processing ",FILE

This command procedure defines a logical name that is used in the program
PAYROLL. At the end of the procedure, the WRITE command displays
a message indicating that the file was processed. Because the WRITE
command does not translate logical names, you need to equate the logical
name (NAMES) to a symbol (FILE). Then you can use the symbol FILE to
display the file name.

4-8

Using Lexical Functions
4. 5 Manipulating Strings

4.5

Manipulating Strings
You can use the following lexical functions to manipulate character strings:

4.5.1

F$CVTIME

Returns information about a time string.

F$EDIT

Edits a character string.

F$ELEMENT

Extracts an element from a string in which the elements are
separated by delimiters.

F$EXTRACT

Extracts a section of a character string.

F$FAO

Formats an output string.

F$LENGTH

Determines the length of a string.

F$LOCATE

Locates a character or a substring within a string and returns the
offset.

Determining if a String or Character is Present
One common reason for examining strings is to determine whether a character
(or substring) is present within a character string. To do this, use the
F$LENGTH and the F$LOCATE functions. If the value returned by the
F$LOCATE function equals the value returned by the F$LENGTH function,
then the character you are looking for is not present.
The following procedure requires a file name that includes the version
number. To determine whether a version number is present, the procedure
tests whether a semicolon (which precedes a version number in a file name)
is included in the file name that the user enters:
$ INQUIRE FILE "Enter file (include version number)"
$ IF F$LOCATE(";", FILE) .EQ. F$LENGTH(FILE) THEN GOTO NO_VERSION

The F$LOCATE function returns the offset for the semicolon. Offsets start
with 0; thus, if the semicolon were the first character in the string, the
F$LOCATE function would return the integer 0. If the semicolon is not
present within the string, the F$LOCATE function returns an offset that is
one more than the offset of the last character in the string. This value is the
same as the length returned by F$LENGTH, which measures the length of
the string starting with the number 1.

4.5.2

Extracting Part of a String
To extract a portion of a string, use either the F$EXTRACT function or the
F$ELEMENT function. Use the F$EXTRACT function to extract a substring
that starts at a defined offset; use the F$ELEMENT function to extract part of
a string between two delimiters. In order to use either of these functions, you
must know the general format of the string you are parsing.

Note: You do not need to use F$EXTRA CT or F$ELEMENT to parse file
specifications or time strings. Instead, use F$P ARSE or F$CVTIME to
extract the desired portion of these strings.

4-9

Using Lexical Functions
4.5 Manipulating Strings

The following command procedure uses the F$EXTRACT function to extract
the group portion of the UIC. This allows the procedure to execute a different
set of commands depending on the user's UIC group.
$ UIC = F$USER ()
$ GROUP_LEN = F$LOCATE( 11 , 11 ,UIC) - 1
$GROUP= F$EXTRACT(1,GROUP_LEN, UIC)
$GOTO 'GROUP'_SECTION

$ WRITERS_SECTION:

$ MANAGERS_SECTION:

First, the procedure determines the UIC with the F$USER function. Next,
the procedure determines the length of the group name by using F$LOCATE
to locate the offset of the comma. The comma separates the group from the
user portion of a UIC. Everything between the left bracket and the comma
is part of the group name. For example, the group name from the UIC
[WRITERS,SMITH] is WRITERS.
After determining the length, the procedure extracts the name of the group
with the F$EXTRACT function. The name starts with offset 1, and ends with
the character before the comma. Finally, the procedure directs execution to
the appropriate label.
Note that you can determine the length of the group name at the same time
you extract it. For example:
$ UIC = F$USER ()
$GROUP= F$EXTRACT(1, F$LOCATE( 11 , 11 ,UIC) - 1, UIC)
$GOTO 'GROUP'_SECTION

If a string contains a delimiter that separates different parts of the string, use
the F$ELEMENT function to extract the part that you want. For example, in a
protection code, each type of access is separated by a comma. For example:
$ PROT = F$ENVIRONMENT("PROTECTION")
$ SHOW SYMBOL PROT
PROT = "SYSTEM=RWED, OWNER=RWED, GROUP=RE, WORLD"

Thus, you can use F$ELEMENT to obtain different types of access by
extracting the portions of the string between the commas. To determine
SYSTEM access, obtain the first element; to determine OWNER access, obtain
the second element, and so on.
The following example extracts the world access portion (the fourth element)
from your default protection code. Note that when you use the F$ELEMENT
function, element numbers start with zero. For this reason, use the integer 3
to specify the fourth element. For example:
$ PROT = F$ENVIRONMENT("PROTECTION")
$ WORLD_PROT = F$ELEMENT(3,",".PROT)

4-10

Using Lexical Functions
4. 5 Manipulating Strings

In this example, the F$ELEMENT function returns everything between the
third comma and the end of the string. Thus, if your default protection
allowed read access for world users, the string "WORLD=R" would be
returned.
After you obtain the world access string, you may need to examine it further.
For example:
$ PROT = F$ENVIRONMENT("PROTECTIDN")
$ WORLD_PROT = F$ELEMENT(3,",".PROT)
$IF F$LOCATE("=", WORLD_PROT) .EQ. F$LENGTH(WORLD_?ROT) THEN GOTO NO_WORLD_ACCESS

4.5.3

Formatting Output Strings
You can use the WRITE command to write a string to a record. For example,
the following command procedure uses the WRITE command to display the
process name and process identification number for processes on the system.
$ ! Initialize context symbol to get PIDs
$ CONTEXT = ""
$ ! Write headings
$ WRITE SYS$0UTPUT "Process Name
PID"
$ !

$ GET_PID:
$ PID = F$PID(CONTEXT)
$ IF PID .EQS. "" THEN EXIT
$WRITE SYS$0UTPUT F$GETJPI(PID,"PRCNAM"),"
$ GOTO GET_PID

" , F$GET JPI (PID, "PID")

Note that the output from the WRITE command inserts five spaces between
the process name and and the user name, but the columns do not line up.
For example:
Process Name
PID
MARCHESANO
2CA0049C
TRACTMEN
2CA0043A
FALLON
2CA0043C
ODONNELL
2CA00453
PERRIN
2CA004DE
CHAMPIONS
2CA004E3

To line up the columns, you can use the F$FAO function to define record
fields, and place the process name and user name in these fields. When
you use the F$FAO function, use a control string to define the fields in the
record; then specify the values to be placed in these fields. For example, the
following procedure uses the F$FAO function to define a 16 character field
and a 12 character field. The F$FAO function places the process name in the
first field, skips a space, and then places the PIO in the second field.

4-11

Using Lexical Functions
4.5 Manipulating Strings

$ ! Initialize context symbol to get PIDs
$ CONTEXT = 1111
$ ! Write headings
$ WRITE SYS$0UTPUT "Process Name
PID 11
$ !

$ GET_PID:
$ PID = F$PID(CONTEXT)
$ IF PID .EQS. 1111 THEN EXIT
$LINE= F$FA0( 11 !16AS !12AS", F$GETJPI(PID,"PRCNAM 11 ) , F$GETJPI(PID, 11 PID 11 ) )
$ WRITE SYS$0UTPUT LINE
$ GOTO GET_PID

Now when you execute the procedure, the columns will be correctly
formatted:
Process Name
MARCHESANO
TRACTMEN
FALLON
ODONNELL
PERRIN
CHAMPIONS

PID
2CA0049C
2CA0043A
2CA0043C
2CA00453
2CA004DE
2CA004E3

Another way to format fields in a record is to use a character string overlay.
The following example uses an overlay to place the process name in the first
16 characters (starting at offset 0) of the symbol RECORD. Then the PID is
placed in the next 12 characters (starting at offset 17):
$ ! Initialize context symbol to get PIDs
$ CONTEXT = 1111
$ ! Write headings
$ WRITE SYS$0UTPUT "Process Name
PID"
$ !

$ GET_PID:
$ PID = F$PID(CONTEXT)
$ IF PID .EQS. 1111 THEN EXIT
$ RECORD[0,16] := 'F$GETJPI(PID, 11 PRCNAM 11 ) '
$ RECORD[17,12] := 'F$GETJPI(PID, 11 PID")'
$ WRITE SYS$0UTPUT RECORD
$ GOTO GET_PID

This procedure produces the same type of formatted columns you created
with the F$FAO function:
Process Name
MARCHES AND
TRACTMEN
FALLON
ODONNELL
PERRIN
CHAMPIONS

PID
2CA0049C
2CA0043A
2CA0043C
2CA00453
2CA004DE
2CA004E3

Note, however, that the F$FAO function is more powerful than a character
string overlay; you can perform a wider range of output operations with the
F$FAO function.

4-12

Using Lexical Functions
4.6 Manipulating Data Types

4.6

Manipulating Data Types
You can use the following lexical functions to convert data from strings to
integers, and from integers to strings:

4.6.1

F$CVSI

Extracts bit fields from a character string and converts the result,
as a signed value, to an integer.

F$CVUI

Extracts bit fields from a character string and converts the result,
as an unsigned value, to an integer.

F$1NTEGER

Converts a string expression to an integer.

F$STRING

Converts an integer expression to a string.

F$TYPE

Determines the data type of a symbol.

Converting Data Types
Use the F$INTEGER and F$STRING functions to convert between integers
and strings. For example, the following command procedure converts data
types. If you enter a string, the command procedure shows the integer
equivalent. If you enter an integer, the command procedure shows the string
equivalent. Note how the F$TYPE function is used to form a label name in
the GOTO statement; F$TYPE returns "STRING" or "INTEGER" depending
on the data type of the symbol.
$ IF P1 .EQS. "" THEN INQUIRE P1 "Value to be converted"
$GOTO CONVERT_'F$TYPE(P1)'
$

$ CONVERT_STRING:
$WRITE SYS$0UTPUT "The string ''P1' is converted to ''F$INTEGER(P1)'"
$ EXIT
$

$ CONVERT_INTEGER:
$WRITE SYS$0UTPUT "The integer ''P1' is converted to ''F$STRING(P1)'"
$ EXIT

4.6.2

Evaluating Expressions
Some commands, such as INQUIRE and READ, accept only string data. If
you use these commands to obtain data that you want to evaluate as an
integer expression, use the F$INTEGER function to convert and evaluate this
data. For example:
$ INQUIRE EXP "Enter integer expression"
$ RES = F$INTEGER('EXP')
$WRITE SYS$0UTPUT "Result is",RES

The following example shows sample output from this command procedure:
Enter integer expression: 9 + 7
Result is 16

Note that you must place apostrophes around the symbol EXP when you use
it as an argument for the F$INTEGER function. This causes DCL to substitute
the value for EXP during the first phase of symbol substitution. In the above
example, the value "9 + 7" is substituted. When the F$INTEGER function
processes the argument "9 + 7", it evaluates the expression and returns the
correct result.

4-13

Using Lexical Functions
4. 6 Manipulating Data Types

4.6.3

Determining Whether a Symbol Exists
Use the F$TYPE function to determine whether a symbol exists; the F$TYPE
function returns a null string if a symbol is undefined. For example:

$ IF F$TYPE(TEMP) . EQS. '"' THEN TEMP = "YES"
$ IF TEMP .EQS. "YES" THEN GOTO TEMP_SEC

This procedure tests whether the symbol TEMP has been previously defined.
If it has, then the current value of TEMP is retained. If TEMP is not defined,
then the IF statement assigns the value "YES" to TEMP.

4-14

Design and Logic

The normal flow of execution in a command procedure is sequential: the
commands in the procedure execute, in order, until the end of the file is
reached. However, in many cases you will want to control whether certain
statements are executed or the conditions under which the procedure should
continue executing.
This chapter discusses the commands that you can use in a command
procedure to control or alter the flow of execution:

5.1

•

The CALL command transfers control to a labeled subroutine in a
command procedure and creates a new command level.

•

The IF command tests the value of an expression and executes a
command or block of commands following the THEN command if
the result of the expression is true. If the result of the expression is false
and the ELSE command is specified, the command or block of commands
following the ELSE command execute.

•

The GOSUB command transfers control to a labeled subroutine in a
command procedure but does not create a new command level.

•

The GOTO command transfers control to a labeled line in the procedure.

•

The Execute Procedure command (@) invokes (or calls) another
command procedure and creates another command level.

•

The EXIT command terminates the current procedure and returns control
to the previous command level.

•

The STOP command terminates the current procedure and returns to
command level 0.

Design
Before writing a command procedure, analyze the tasks you want to perform.
You may find it helpful to perform the tasks interactively to identify the steps
involved in performing the tasks. In particular, look for the following:
Variables

Data that change each time you perform the task

Conditionals

Conditions that must be tested each time you perform the
task

Iterations

Groups of commands that are performed repetitively until a
condition is met

For example, you decide to write a command procedure to clean up a
directory. Before you start, you clean up one of your directories interactively
and notice that you do the following:
•

Enter the DIRECTORY command to see what files are in the directory

•

Enter the PURGE command to delete old versions of files

5-1

Design and Logic
5.1 Design
I

•

Enter the TYPE command to display the contents of a file before you
decide whether to delete it

•

Enter the PRINT command to print a hard copy of a file before you delete
it

•

Enter the DELETE command to delete files you no longer want to keep

After determining the commands you use to clean a directory, you identify
the following variables: the command to be executed and the file to be
processed. These variables change each time you perform the procedure.
Next, you identify the following conditionals. First, you need to determine
which command to perform. If the requested command is not one of the
commands that the procedure performs, you need to output an error message
and get another command. Also, you need to determine when to terminate
the procedure.
Finally, you decide that the command procedure will repeat the following
sequence of commands until the directory is clean: obtain a command, see
if you are done, perform the command if the command is valid, and obtain
another command.

5.2

Coding
To make the command procedure easier to understand and maintain, try to
write the statements so that the procedure executes straight through from the
first command to the last command. This section shows the steps you use to
code a command procedure to clean up a directory. This example command
procedure used in this section is called CLEAN.COM.

5.2.1

Obtaining Variables
First, decide how to obtain the values for your variables. You can use
any of the methods for obtaining input described in Chapter 3. However,
one of the most common methods for obtaining values for variables is
to use the INQUIRE command to equate the values to symbols. In this
command procedure, the procedure obtains the command from the user who
is executing the procedure and equates the value to the symbol COMMAND:
$

5.2.2

INQUIRE COMMAND "Enter command (DELETE, DIRECTORY, PRINT, PURGE, TYPE)"

Coding the General Design
According to your design, the first thing you want to do after you obtain a
command is to see whether you are through, or whether you need to perform
the command. To do this, you decide to add an EXIT command so you can
test whether the user entered "EXIT". For example:
$
$

5-2

INQUIRE COMMAND "Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)"
IF COMMAND .EQS. "EXIT" THEN EXIT

Design and Logic
5.2 Coding
Next, you need to determine which command to execute. To do this, check
the command entered by the user against each possible command. If you
find a match, execute the command. If you do not find a match, go on to the
next command. If there is no match after you have checked for each valid
command, output an error message.
To test whether a condition is true, use the IF ... THEN commands. To change
the flow of execution, use the GOTO command to direct the flow of execution
to a label in the command procedure. Also, use program stubs as placeholders
for the code that performs each command. A 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 it is replacing. After the
overall design works correctly, replace each stub with the correct code. For
example:
$
$

INQUIRE COMMAND "Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)"
IF COMMAND .EQS. "EXIT" THEN EXIT

$!
$!Execute if user entered DELETE
$ DELETE:
$
IF COMMAND .NES. "DELETE" THEN GOTO DIRECTORY
$
WRITE SYS$0UTPUT "This is the DELETE section."
$!
$!Execute if user entered DIRECTORY
$ DIRECTORY:
$
IF COMMAND .NES. "DIRECTORY" THEN GOTO PRINT
$
WRITE SYS$0UTPUT "This is the DIRECTORY section."
$!
$!Execute if user entered PRINT
$ PRINT:
$
IF COMMAND .NES. "PRINT" THEN GOTO PURGE
$
WRITE SYS$0UTPUT "This is the PRINT section."
$!
$!Execute if user entered PURGE
$ PURGE:
$
IF COMMAND .NES. "PURGE" THEN GOTO TYPE
$
WRITE SYS$0UTPUT "This is the PURGE section."
$!
$!Execute if user entered TYPE
$ TYPE:
IF COMMAND .NES. "TYPE" THEN GOTO ERROR
$
WRITE SYS$0UTPUT "This is the TYPE section."
$
$!
$ ERROR:
$
WRITE SYS$0UTPUT "You entered an invalid command."
$

$ EXIT

Now that you have the lines that test your conditionals, finish the design by
adding the loop that allows you to obtain a command, process the command,
and repeat the process until the user enters the EXIT command. To do this,
direct the flow of execution back to the beginning of the procedure after the
procedure executes a command. Leave the loop only when the user enters
the EXIT command. For example:

5-3

Design and Logic
5.2 Coding

$ GET_COMMAND_LOOP:
$
INQUIRE COMMAND "Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)"
IF COMMAND .EQS. "EXIT" THEN GOTO END_LOOP
$
$!
$!Execute if user entered DELETE
$
DELETE:
$
IF COMMAND .NES. "DELETE" THEN GOTO DIRECTORY
$
WRITE SYS$0UTPUT "This is the DELETE section."
$
GOTO GET_COMMAND_LOOP
$!
$!Execute if user entered DIRECTORY
$
DIRECTORY:
$
IF COMMAND .NES. "DIRECTORY" THEN GOTO PRINT
$
WRITE SYS$0UTPUT "This is the DIRECTORY section."
$
GOTO GET_COMMAND_LOOP
$!
$!Execute if user entered PRINT
$ PRINT:
$
IF COMMAND .NES. "PRINT" THEN GOTO PURGE
$
WRITE SYS$0UTPUT "This is the PRINT section."
$
GOTO GET_COMMAND_LOOP
$!
$!Execute if user entered PURGE
$ PURGE:
$
IF COMMAND .NES. "PURGE" THEN GOTO TYPE
$
WRITE SYS$0UTPUT "This is the PURGE section."
$
GOTO GET_COMMAND_LOOP
$!
$!Execute if user entered TYPE
$ TYPE:
$
IF COMMAND .NES. "TYPE" THEN GOTO ERROR
$
WRITE SYS$0UTPUT "This is the TYPE section."
$
GOTO GET_COMMAND_LOOP
$!
$ ERROR:
$
WRITE SYS$0UTPUT "You entered an invalid command."
$
GOTO GET_COMMAND_LOOP
$!
$ END_LOOP:
$ WRITE SYS$0UTPUT "Directory ''F$DIRECTORY0' has been cleaned."
$ EXIT

5.2.3

Testing and Debugging
Once you have written the code using program stubs, test the overall logic
of the command procedure. Test all possible paths of execution. To test
CLEAN.COM, enter each valid command, enter an invalid command, and
exit using the EXIT command. For example:
$ ©CLEAN
Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE): DELETE
This is the DELETE section.

Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE): EXIT

5-4

Design and Logic
5.2 Coding

Use the SET VERIFY and SHOW SYMBOL commands to help debug
command procedures. When verification is set, you can see errors and the
lines that generate them. For example, the following section of CLEAN.COM
contains a spelling error. You can determine where the error occurs by
turning verification on before you execute the procedure.
$ SET VERIFY
$ ©CLEAN
$ GET_COMMAND_LOOP:
$
INQUIRE COMMAND -

"Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)"
Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE): EXIT
$
IF COMMAND .EQS. "EXIT" THEN GOTO END_LOP
%DCL-W-USGOTO, target of GOTO not found - check spelling and presence of label

The label END_LOP is spelled incorrectly. To correct the error, change the
label to END_LOOP.
The next example uses the SHOW SYMBOL command to determine how the
symbol COMMAND is defined.
$ SET VERIFY
$ ©CLEAN

$ GET_COMMAND_LOOP:

INQUIRE COMMAND "ENTER COMMAND (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)"
ENTER COMMAND (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE): EXIT
$ SHOW SYMBOL COMMAND
COMMAND = "EXIT"
$
IF COMMAND .EQS. "exit" THEN GOTO END_LOOP
$

In this example, the SHOW SYMBOL command shows that the symbol
COMMAND has the value "EXIT". (The INQUIRE command automatically
converts input to uppercase.) The IF statement that tests the command uses
lowercase characters in the string "exit", so DCL determines that the strings
are not equal. To correct the error, make sure the quoted string in the IF
statement is written in capital letters; the rest of the string can use either
uppercase or lowercase. For example:
$

5.2.4

if command .eqs. "EXIT' then goto end_loop

Filling in the Program Stubs
When your general design works correctly, complete the command procedure
by substituting commands for the program stubs. After you replace a stub
with commands, test it to make sure the procedure works correctly. For a
complicated task, it might be helpful to test the commands before adding
them to the procedure.
The following example shows the code for the TYPE section of CLEAN.COM:
$! Execute if user entered TYPE
$ TYPE:
$
IF COMMAND .NES. "TYPE" THEN GOTO ERROR
$
INQUIRE FILE "File to type"
$
TYPE 'FILE'
$
GOTO GET_COMMAND_LOOP

5-5

Design and Logic
5.3 Techniques for Controlling Execution Flow

5.3

Techniques for Controlling Execution Flow
The previous section illustrated some techniques you can use when designing
procedures and directing the flow of execution. This section describes these
techniques in more detail.

5.3.1

IF Command
The IF command tests the value of an expression and executes a command or
block of commands when the result of the expression is true. When the result
of the expression is false, one of the following occurs:
•

When one command follows the THEN command, it is not executed and
the following command executes.

•

When a block of commands follows the THEN command, and the ELSE
command is not specified, the command immediately following the
ENDIF command executes~

•

When the ELSE command is specified, the command or block of
commands following the ELSE command executes.

The IF command can have one of the three following formats. The first
format executes a single command when the expression specified to the IF
command is true.
$ IF expression THEN [$] command

The second format executes a block of commands when the expression
specified to the IF command is true.
$ IF expression
$
THEN
$
command
$
command

$ ENDIF

The third format executes one or more commands when the expression
specified to the IF command is true, and executes one or more commands
when the condition is false.
$ IF expression
$
THEN
$
command

command

$
$

ELSE
command
command

$ ENDIF

5-6

Design and Logic
5.3 Techniques for Controlling Execution Flow

Note the following restrictions when using the IF-THEN-ELSE language
construct:
•

IF statements can be nested to 16 levels.

•

A command block started by a THEN statement must be terminated by
either an ELSE or an ENDIF statement.

•

A command block started by an ELSE statement must be terminated by
an ENDIF statement.

•

A THEN statement must be the first executable statement following an IF
statement.

•

You cannot specify a label on a line containing a THEN or an ELSE
statement. You can, however, specify a label on a line containing an
ENDIF statement. Programs may branch within the current command
block, but branching into the middle of another command block is not
recommended.

The expression following the IF command can consist of one or more numeric
constants, string literals, symbolic names, or lexical functions separated by
logical, arithmetic, or string operators. An expression is true when it has one
of the following values:
•

An odd integer value

•

A character string value that begins with any of the letters Y, y, T, or t

•

A character string value that contains numbers that form an integer with
an odd value (for example, the string "27")

An expression is false when it has one of the following values:
•
•

An even integer value
A character string value that begins with any letter other than Y, y, T, or
t

•

A character string value that contains numbers that form an integer with
an even value (for example, the string "28")

When you write an expression for an IF command, follow the rules for writing
expressions given in Chapter 2. (These rules are explained in more detail in
the VMS DCL Concepts Manual.) In particular, remember the following:
•

When you use symbols in IF statements, their values are automatically
substituted. Do not use apostrophes as substitution operators unless you
need to force iterative translation.

•

String comparison operators end in the letter "S". For example, use
operators such as .EQS., .LTS., and .GTS. to compare strings. By contrast,
the operators .EQ., .LT., and .GT. are used for comparing integers.

•

When you test to see whether two strings are equal, the strings must
use the same case in order for DCL to find a match. That is, the string
"COPY" does not equal the string "copy" or the string "CoPy".

5-7

Design and Logic
5.3 Techniques for Controlling Execution Flow

The following examples illustrate expressions that can be used with the IF
command. For additional examples, see the description of the IF command
in the VMS DCL Dictionary. The first example uses a logical operator and
executes only one command following the THEN statement.
$INQUIRE CONT "Do you want to continue [Y/N]"
$ IF .NOT. CONT THEN EXIT

In this example, when the symbol CONT is not true, the procedure exits.
The next example uses a symbol and a label within the IF expression:
$INQUIRE CHANGE "Do you want to change the record [Y/N]"
$ IF CHANGE THEN GOTO GET_CHANGE

$ GET_CHANGE:

In this example, when the symbol CHANGE is true, the procedure transfers
control to the label GET_CHANGE. Otherwise the procedure executes the
command following the IF command.
The next example illustrates two different IF commands. The first IF
command compares two integers; the second IF command compares two
strings. Note that the .EQ. operator is used for the integer comparison and
the .EQS. operator is used for the string comparison.
$ COUNT = 0
$ LOOP:
$
COUNT = COUNT + 1
$
IF COUNT .EQ. 9 THEN EXIT
$
IF P'COUNT' .EQS. "" THEN EXIT

$ GOTO LOOP

First, the value of COUNT is compared to the integer 9; when the values are
equal, then the procedure exits. When the values are not equal, the procedure
continues. The loop terminates after eight parameters (the maximum number
allowed) have been processed.
In the second IF command, the string value of the symbol P'COUNT' is
compared to a null string to see whether the symbol is undefined. Note
that you must use apostrophes to force iterative substitution of the symbol
COUNT. For example, when COUNT is 2, the result of the first translation is
P2. Then, the value of P2 is used in the string comparison.
You can execute a block of commands after the THEN command when
the result of the IF expression is true. When using a block of commands,
place the THEN command as the first command on the line following the IF
command. In the following example, two SET TERMINAL commands execute
and the procedure transfers control to the label PROCEED when F$MODE
equals "INTERACTIVE". When F$MODE does not equal "INTERACTIVE",
the procedure exits.

5-8

Design and Logic
5.3 Techniques for Controlling Execution Flow

$ IF F$MODE () . EQS. II INTERACTIVE II
$ THEN
$
SET TERMINAL/DEVICE=VT200
$
SET TERMINAL/WIDTH=132
$
GOTO PROCEED
$ ENDIF
$ EXIT
$PROCEED:

The following example illustrates how to use a block of commands with the
IF command in conjunction with the ELSE command. When the condition
is true, the procedure writes a message to SYS$0UTPUT and executes the
SHOW DEVICE and SET DEVICE commands. When the condition is not
true, the procedure writes two messages to SYS$0UTPUT.
$ INQUIRE DEV "Device to check"
$ IF F$GETDVI (DEV, "EXISTS")
$ THEN
$
WRITE SYS$0UTPUT "The device exists."
$
SHOW DEVICE 'DEV'
$
SET DEVICE/ERROR_LOGGING 'DEV'
$ ELSE
$
WRITE SYS$0UTPUT "The device does not exist."
$
WRITE SYS$0UTPUT "Error logging has not been enabled."
$ ENDIF
$ EXIT

You can also execute a separate command procedure when the result of the IF
expression is true. The following example executes the command procedure
EXIT_ROUTINE.COM when the result of the IF expression is true:
$ GET_COMMAND_LOOP:
$
INQUIRE COMMAND "Enter command (COPY, DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)"
$
IF COMMAND .EQS. "EXIT" THEN ©EXIT_ROUTINE

5.3.2

GOTO Command
The GOTO command passes control to a labeled line in a command
procedure. You can precede any command string in a command procedure
with a label. The rules for entering labels are as follows:
•

A label must appear as the first item on a line after the dollar sign.

•

A label can have up to 255 characters.

•

A label can contain no embedded space characters.

•

A label must be terminated with a colon.

For example:
$ GOTO BYPASS

$ BYPASS:

5-9

Design and Logic
5.3 Techniques for Controlling Execution Flow

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 may 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.
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 uses the following rules when
processing duplicate labels:
•

If duplicate labels all precede the GOTO command, control transfers to
the label nearest the GOTO command.

•

If duplicate labels precede and follow the GOTO command, control
transfers to the preceding label nearest the GOTO command.

•

If duplicate labels all follow the GOTO command, control transfers to the
label nearest the GOTO command.

The GOTO command is especially useful within a THEN clause to cause
a procedure to branch forward or backward. For example, when you use
parameters in a command procedure, you can test the parameters at the
beginning of the procedure and branch to the appropriate label:
$ IF P1 . NES. 1111 THEN GOTO OKAY
$ INQUIRE P1 "Enter file spec"
$ OKAY:
$ PRINT/COPIES=10 'P1'

In this example, the IF command checks that Pl is not a null string. If Pl
is a null string, the GOTO command is not executed and the INQUIRE
command prompts for a parameter value. Otherwise, the GOTO command
causes a branch around the INQUIRE command. In either case, the procedure
executes the PRINT command following the line labeled OKAY.

5.3.3

GOSUB Command
The GOSUB command transfers control to a labeled subroutine in a command
procedure. If the label does not exist in the command procedure, the
procedure cannot continue executing and is forced to exit. You can nest
the GOSUB command up to 16 times per procedure level.
The GOSUB command is a local subroutine call; it does not create a new
procedure level. Because the GOSUB command does not create a new
procedure level, all labels and local symbols defined in the current command
procedure level are available to a subroutine invoked with GOSUB.
The rules for entering subroutine labels are as follows:

5-10

•

A label must appear as the first. item on a line after the dollar sign.

•

A label can have up to 255 characters.

•

A label can contain no embedded space characters.

Design and Logic
5.3 Techniques for Controlling Execution Flow

•

A label must be terminated with a colon.

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 may run out of 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.
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 GOSUB command transfers control to the label that DCL
has processed most recently. The GOSUB command uses the following rules
when processing duplicate labels:
•

If duplicate labels all precede the GOSUB command, control transfers to
the label nearest the GOSUB command.

•

If duplicate labels precede and follow the GOSUB command, control
transfers to the preceding label nearest the GOSUB command.

•

If duplicate labels all follow the GOSUB command, control transfers to
the label nearest the GOSUB command.

The RETURN command terminates a subroutine and returns control to the
command following the GOSUB command. You can specify a value for
$STATUS with the RETURN command that overrides the value that DCL
assigns to $STATUS at the end of the subroutine. This value must be 'an
integer between zero and four or an equivalent expression. If you specify a
value for $STATUS, DCL interprets this value as a condition code. If you do
not specify a value for $STATUS, the current value of $STATUS is saved. See
Chapter 7 for more information about condition codes and $STATUS.
The following example shows how you can use the GOSUB command to
transfer control to subroutines.
$!
$! GOSUB.COM
$!
$ SHOW TIME
$ GOSUB TEST1 0
$WRITE SYS$0UTPUT "GOSUB level 1 has completed successfully."
$ SHOW TIME
$ EXIT
$!
$! TEST1 GOSUB definition
$!
$ TEST1:
$
WRITE SYS$0UTPUT "This is GOSUB level 1."
$
GOSUB TEST2 f)
$
RETURN %X1 0
$!
.
$! TEST2 GOSUB definition
$!
$ TEST2:
$
WRITE SYS$0UTPUT "This is GOSUB level 2."
$
WAIT 00:00:02
$
RETURN C)

The first GOSUB command transfers control to the subroutine labeled
TESTl.

5-11

Design and Logic
5.3 Techniques for Controlling Execution Flow

The procedure executes the commands in subroutine TESTl, branching to
the subroutine labeled TEST2.

The RETURN command in subroutine TESTl returns control to the main
command procedure, and passes a value of 1 to $STATUS, indicating
successful completion.

e The RETURN command in subroutine TEST2 returns control to
subroutine TESTl. Note that this command executes before command 3.

5.3.4

CALL Command
The CALL command transfers control to a labeled subroutine in a command
procedure and creates a new procedure level. The CALL command allows
you to keep more than one related command procedure in a single file,
making the procedures easier to manage. The subroutine label, which must
be unique, can precede or follow the CALL command in the command
procedure. Section 5.3.3 contains rules for entering subroutine labels.
In addition to the label, you can pass up to eight optional parameters to the
subroutine. These parameters assign character string values to the symbols
Pl through PS. Separate each parameter with one or more spaces. Use
quotation marks ( "") to specify a null parameter. Use alphanumeric and
special characters to specify parameters, with the following restrictions.
•

The command interpreter converts alphabetic characters to uppercase
and uses spaces to delimit each parameter. To pass a parameter that
contains embedded spaces or literal lowercase letters, place the parameter
in quotation marks.

•

If the first parameter begins with a slash character ( / ), enclose the
parameter in quotation marks.

•

If the parameter contains literal quotation marks and spaces, enclose the
entire string in quotation marks and use a double set of quotation marks
within the string. The following example equates the string Never say
"quit" to Pl.
$ CALL SUB1 "Never say ""quit"""

•

To use a symbol as a parameter, enclose the symbol with apostrophes.
$ CALL SUB2 'WHOLE'

By default, the CALL command sends output to SYS$0UTPUT. The CALL
command has an optional /OUTPUT qualifier that allows you to direct output
from the subroutine to a file. The default file type for the output file is LIS.
Do not use wildcard characters in the output file specification.
You can nest subroutines called with the CALL command and procedures
called with the@ (execute procedure) command to a maximum of 32
command levels. Unless they are masked using the SET SYMBOL command,
local symbols defined in an outer level are available to any inner procedure
or subroutine levels and global symbols are available at any command level.
Labels are valid only for the level in which they are defined.
The SUBROUTINE and ENDSUBROUTINE commands define the beginning
and the end of a CALL subroutine. The label defining the entry point to
the subroutine immediately precedes the SUBROUTINE command. The
EXIT command may be placed immediately before the ENDSUBROUTINE

5-12

Design and Logic
5.3 Techniques for Controlling Execution Flow

command, but it is not required to terminate the subroutine. The
ENDSUBROUTINE command terminates the subroutine and transfers control
to the command line immediately following the CALL command.
Command lines in a subroutine execute only when the subroutine is called
with the CALL command. During the line-by-line execution of the command
procedure, the command language interpreter skips all commands between
the SUBROUTINE and the ENDSUBROUTINE commands.
The following example includes two subroutines called SUBl and SUB2. The
subroutines do not execute until they are called with the CALL command.
$

$! CALL.COM
$

$! Define subroutine SUB1
$!
$ SUB1: SUBROUTINE

$ CALL SUB2 !Invoke SUB2 from within SUB1

$©FILE

!Invoke another procedure command file

$ EXIT
$ ENDSUBROUTINE !End of SUB1 definition
$!
$! Define subroutine SUB2
$!
$ SUB2: SUBROUTINE
$ EXIT
$ ENDSUBROUTINE !End of SUB2 definition
$!
$! Start of main routine. At this point, both SUB1 and SUB2
$! have been defined but none of the previous commands have
$! been executed.
$!
$ START:
$ CALL/OUTPUT=NAMES. LOG SUB1 "THIS IS P1 "·

$ CALL SUB2 "THIS IS P1 II "THIS IS P2"

$ EXIT

!Exit this command procedure file

In this example, the CALL command invokes the subroutine SUBl and directs
output to the file NAMES.LOG. Subroutine SUBl calls subroutine SUB2. The
procedure executes SUB2, invoking the command procedure FILE.COM with
the@ (execute procedure) command. When all the commands in SUBl have
executed, the CALL command in the main procedure calls SUB2 a second
time. The procedure exits when SUB2 finishes executing.

5-13

Design and Logic
5.3 Techniques for Controlling Execution Flow

5.3.5

Loops
A loop is a group of statements that execute until a condition is met. When
you write loops, do the following:
1

Begin the loop with a label.

Test a variable to determine whether you need to execute the commands
in the loop. (This is the termination variable.)

If you do not need to execute the loop, go to the end of the loop.

If you need to execute the loop, perform the commands in the loop and
then return to the beginning of the loop.

You can also write loops that test the termination variable at the end of the
loop. Note that when you test the termination variable at the end of the loop,
the commands in the body of the loop are executed at least once.
The following examples show different ways you can write loops. The first
example tests the termination variable at the beginning of the loop; the loop
terminates when the value of the symbol FILE is the null string.
$ LOOP:

$
$
$

$
$!

INQUIRE FILE "File (press RET to quit)"
IF FILE . EQS. '"' THEN GOTO DONE
! Process file

GOTO LOOP

$ DONE:

In this example, the INQUIRE command requests a file name. If the response
is a null value (you pressed CTRL/Z or the RETURN key) the loop does not
execute. Otherwise, the loop executes repeatedly until you enter a null value.
The next example uses a counter to control the number of times a loop
executes. In this example, the loop executes 10 times; the termination variable
is tested at the end of the loop.
$! Obtain 10 file names and store them in the
$! symbols FILE_1 through FILE_10
$!
$ COUNT = 0
$ LOOP:
$
COUNT = COUNT + 1
$
INQUIRE FILE_'COUNT' "File"
$
IF COUNT .LT. 10 THEN GOTO LOOP
$!
$ PROCESS_FILES:

5-14

Design and Logic
5.3 Techniques for Controlling Execution Flow

This example uses the symbol COUNT to keep track of how many times the
commands in the loop are executed. The example also uses COUNT to create
the symbol names FILE_l, FILE_2 and so on through FILE_lO. Note that
the value of COUNT is incremented at the beginning of the loop but is tested
at the end of the loop. Therefore, when COUNT is incremented from 9 to
10, the loop executes a last time (obtaining a value for FILE_lO) before the IF
statement finds a false result.
To perform a loop for a known sequence of values, use the F$ELEMENT
lexical function. The F$ELEMENT function obtains items from a list of
items separated by delimiters. You must supply the item number, the item
delimiter, and the list as arguments for F$ELEMENT. See the VMS DCL
Dictionary for more information. For example:
$ FILE_LIST = "CHAP1/CHAP2/CHAP3/CHAP4/CHAP5"
$ NUM = 0
$!
$! Process each file listed in FILE_LIST
$ PROCESS_LOOP:
$
FILE= F$ELEMENT(NUM, 11 / 11 ,FILE_LIST)
$
IF FILE . EQS . II I II THEN GOTO DONE
$
COPY 'FILE' .MEM MORRIS: :DISK3: [DOCSET]*.*
$
NUM = NUM + 1
$
GOTO PROCESS_LOOP
$!
$ DONE:
$WRITE SYS$0UTPUT "Finished copying files."
$ EXIT

This command procedure uses a loop to copy the files listed in the symbol
FILE_LIST to a directory on another node. The first file returned by the
F$ELEMENT function is CHAP!, the next file is CHAP2, and so on. Each
time through the loop, the value of NUM is increased so that the next file
name is obtained. When the F$ELEMENT returns a slash, all the items from
FILE_LIST have been processed and the loop is terminated.

5.3.6

Case Statements
A case statement is a special form of conditional code that executes one out of
a set of command blocks depending on the value of a variable or expression.
Although DCL does not provide a case statement, you can perform the
function of a case statement in the following way:

Equate a symbol to a string that contains a list of options.

Obtain the desired option from the user.

Use the F$LOCATE and F$LENGTH lexical functions to verify that the
user's option is valid; that is, the option is one of the choices listed.

Use the GOTO command to direct the flow of execution to the
appropriate block of commands. The labels that identify each block
of commands should be the same as the options you specify in your
option list.

For example, you can rewrite CLEAN.COM (shown in Section 5.2.2) so that
it verifies that a command is valid at the beginning of the procedure. If the
command is valid, then the procedure executes the command. Note that the
labels that identify each command block are the same as the commands in

5-15

Design and Logic
5.3 Techniques for Controlling Execution Flow

the option list. This allows you to use the symbol COMMAND (which is
equated to user's request) in the GOTO statement.
$ COMMAND_LIST = "DELETE/DIRECTORY/EXIT/" + "PRINT/PURGE/TYPE/"
$!
$ GET_COMMAND_LOOP:
$
INQUIRE COMMAND "Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)"
IF F$LOCATE(COMMAND+"/",COMMAND_LIST) .EQ. $
F$LENGTH(COMMAND_LIST) THEN GOTO ERROR
GOTO 'COMMAND'
$
$!
$!Execute if user entered DELETE
$
DELETE:
$
WRITE SYS$0UTPUT "This is the DELETE section."

$
GOTO GET_COMMAND_LOOP
$!
$!Execute if user entered DIRECTORY
$
DIRECTORY:
$
WRITE SYS$0UTPUT "This is the DIRECTORY section."

GOTO GET_COMMAND_LOOP

$!
$ EXIT:
$ WRITE SYS$0UTPUT "Directory ''F$DIRECTORY0' has been cleaned."
$ EXIT
$!
$! Error section
ERROR:
$
WRITE SYS$0UTPUT "You entered an invalid command."
$
GOTO GET_COMMAND_LOOP
$

5.4

Terminating Command Procedures
You can use either the EXIT or STOP command to terminate the execution
of a command procedure. When included in a command procedure, the
EXIT command terminates execution of the current command procedure
and returns control to the previous command level. The STOP command,
however, returns control to command level 0, regardless of the current
command level. If you execute the STOP command in a batch job, the batch
job terminates.
You can interrupt a command procedure by pressing CTRL/Y and then using
the EXIT command or STOP command to terminate the procedure. In this
case, both commands return you to command level 0. For example:
$ ©TESTALL [ill]
JcTRL/YJ

$ EXIT [ill]
$

5-16

Design and Logic
5.4 Terminating Command Procedures

In the preceding example, you interrupt the procedure TESTALL by pressing
CTRL/Y. The EXIT command terminates processing of the procedure and
restores command level 0. Note that you could have also entered the STOP
command after you interrupted the procedure.

Note: When you interrupt a command procedure, if the command (or image)
that you interrupt declares any exit-handling routines, the EXIT command
gives these routines control. However, the STOP command does not
execute these routines.

5.4.1

Using the EXIT Command
You can use the EXIT command to ensure that a procedure does not execute
certain lines. For example, if you write an error-handling routine at the end
of a procedure, you would place an EXIT command before the routine, as
follows:

$
EXIT ! End of normal execution path
$ ERROR_ROUTINE:

The EXIT command is also useful for writing procedures that have more than
one execution path. For example:
$ 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

To execute this command 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 so, the GOTO command branches appropriately,
using the parameter as the branch label. If Pl was neither TAPE nor DISK,
the INQUIRE command prompts for a correct parameter; the GOTO START
command establishes a loop.
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 do not execute unless the
procedure branches explicitly to the label DISK.
Note that the EXIT command at the end of the procedure is not required
because the end-of-file of the procedure causes an implicit EXIT command.
Use of the EXIT command, however, is recommended.

5-17

Design and Logic
5.4 Terminating Command Procedures

5.4.2

Passing Status Values with the EXIT Command
When a command procedure exits, the command interpreter returns the
condition code for the previous command in a special symbol called
$STATUS. (The condition code provides information about whether the most
recent command executed successfully. See Chapter 7 for more information
on condition codes.)
When you use the EXIT command in a command procedure, you can specify
a value that overrides the value that DCL would have assigned to $STATUS.
This value, called a status code, must be specified as an integer expression.
When a command procedure contains nested procedures to create multiple
command levels, you can use the EXIT command to return a value that
explicitly overrides the default condition codes.
For example, suppose the procedure A.COM contains the following lines:
$! This is file A.COM
$!
$ ©B

The procedure B.COM contains the following lines:
$! This is file B.COM
$!
$ ON WARNING THEN GOTO ERROR

$ ERROR:
$ EXIT 1

The ON command means that if any warnings, errors, or severe errors occur
when B.COM is executing, the procedure is directed to the label ERROR.
Here, the condition code is explicitly set to 1, indicating success. Therefore,
when B.COM terminates it passes a success code back to A.COM regardless
of whether an error occurred.

5.4.3

Using the STOP Command
You can use the STOP command in a command procedure or batch job to
ensure that all procedure levels are terminated if a severe error occurs. For
example:
$ ON SEVERE_ERROR THEN STOP

If you include this line in a command procedure and a severe error occurs, the
command procedure terminates. In a command procedure that is executed
interactively, control is returned to command level 0. In a batch job, the job
terminates.

5-18

File Input/Output

The basic steps in reading and writing files from a command procedure are as
follows:
•

Use the OPEN command to open a file. The OPEN command assigns
a logical name to the file and specifies whether the file is to be read,
written, or both read and written.

•

Use the READ or WRITE commands to read or write records to the file.
When you perform input and output to files, you usually design a loop
to read a record, process the record, and write the modified record to
either the same or to another file. You execute the commands in this loop
(reading, processing, and writing records) until you are through.

•

Use the CLOSE command to close the file. Unless you explicitly close it,
a file remains open until you log out.

This chapter describes how to use the OPEN, READ, WRITE, and CLOSE
commands. In addition, it shows how to modify files and how to handle
errors when you perform file operations.

6.1

Commands for File 1/0
The following sections describe the DCL commands for performing input and
output to files.

6.1.1

OPEN Command
The OPEN command can open sequential, relative, or indexed sequential
access method files. When opening a file, the OPEN command assigns a
logical name to the file and places the name in the process logical name table.
Subsequent READ, WRITE, and CLOSE commands use this logical name to
refer to the file.
When you open a file from a command procedure, be sure to include the
file's device and directory names. This ensures that your command procedure
opens the correct file regardless of the directory from which you execute the
command procedure.
The OPEN command opens files as process-permanent. Therefore, these files
remain open for the duration of your process unless you explicitly close them
(with the CLOSE command). These files are subject to RMS restrictions on
using process-permanent files.
You do not have to explicitly open SYS$INPUT, SYS$0UTPUT,
SYS$COMMAND, and SYS$ERROR in order to read or write to them because
the system opens these files for you when you log in. For more information
on reading or writing to process-permanent files, see Chapter 3.
The following sections describe how to open a file for reading, writing, and
both reading and writing, and how to open a shareable file.

6-1

File Input/Output
6.1 Commands for File 1/0

6.1.1.1

Opening a File for Reading
To open a file for reading, use the /READ qualifier; this is the default when
you use the OPEN command. The following example opens a file for reading:
$ OPEN/READ INFILE DISK4: [MURPHY] STATS.DAT

When you open a file for reading, you can read, but not write records. The
OPEN /READ command places the record pointer at the beginning of the file.
Each time you read a record, the pointer moves to the next record.

6.1.1.2

Opening a File for Writing
To open a file for writing, use either the /WRITE qualifier or the/ APPEND
qualifier. These qualifiers are mutually exclusive, so you can use only one of
them on a command line.

The /WRITE qualifier (used without the /READ qualifier) creates a new file
and places the record pointer at the beginning of the file. The OPEN/WRITE
command always creates a sequential file in print file format. The record
format for the file is variable with fixed control (VFC), with a two-byte record
header. Note that if you specify a file that already exists, the OPEN/WRITE
command opens a new file with a version number one greater than the
existing file.
The following example opens a file for writing and writes records to the file:
$ OPEN/WRITE OUTFILE DISK4: [MURPHY] NAMES.DAT
$ UPDATE:

INQUIRE NEW_RECORD "Enter name"
WRITE OUTFILE NEW_RECORD
$ IF OUTFILE .EQS. "" THEN GOTO EXIT_CODE
$ GOTO UPDATE
$ EXIT_CODE:
$
CLOSE OUTFILE
$
EXIT
$
$

The/ APPEND qualifier, unlike the /WRITE qualifier, does not open a new
version of a file. The /APPEND qualifier opens an existing file and positions
the record pointer at the end of the file. This allows you to add records to the
end of a file.
The following command procedure appends records to the end of the file
NAMES.DAT:
$ OPEN/APPEND OUTFILE DISK4: [MURPHY] NAMES.DAT

$ INQUIRE NEW_RECORD "Enter name"
$ WRITE OUTFILE NEW_RECORD

$ CLOSE OUTFILE

6-2

File Input/Output
6.1 Commands for File 1/0

6.1.1.3

Opening a File for Reading and Writing
To open a file for reading and writing, use both the /READ and /WRITE
qualifiers. For example:
$ OPEN/READ/WRITE FILE DISK4: [MURPHY] STATS.DAT

This OPEN command places the record pointer at the beginning of the file
STATS.DAT so you can read the first record. When you use this method of
opening a file, you can only replace the record you have most recently read;
you cannot write new records to the end of the file. Also, a revised record
must be exactly the same size as the record being replaced.

6.1.1.4

6.1.2

Opening Shareable Files
To open a shareable file, use the /SHARE qualifier when you open the
file. When you use the /SHARE qualifier, other users may read or write
to the file. Use /SHARE=READ to allow other users to read the file; use
/SHARE=WRITE to allow other users to write to the file. In addition, other
users may access the file with the TYPE or SEARCH command.

READ Command
Use the READ command to read a record and assign its contents to a symbol.
For example:
$ OPEN/READ INFILE DISK4: [MURPHY] STATS.DAT
$ READ/END_OF_FILE=END_LOOP INFILE RECORD

$END_LOOP:
$ CLOSE INFILE
$ EXIT

In this example, the READ command reads a record from the file INFILE and
assigns the record's contents to the symbol RECORD.
When you specify a symbol name for the READ command, the command
interpreter places the symbol name in the local symbol table for the current
command level. If you use the same symbol name for more than one READ
command, each READ command redefines the value of the symbol name.
For example:
$ BEGIN:

READ/END_OF_FILE=END_LOOP INFILE RECORD

GOTO BEGIN

$ END_LOOP:
$
CLOSE INFILE

EXIT

Each time through this loop, the READ command reads a new record from
the input file and uses this record to redefine the value of the symbol
RECORD.

6-3

File Input/Output
6.1 Commands for File 1/0

In order to read from a file, the file must be opened with read access. You
can read records that are less than or equal to 1024 characters in length.
6.1.2.1

Designing Read Loops

When you read from files, you generally read and process each record until
you reach the end of the file. To determine when you reach the end of a
file, use the /END_OFJILE qualifier with the READ command. By using
this qualifier, you can construct a loop to read records from a file, process
the records, and exit from the loop when you have finished reading all the
records. For example:
$ OPEN/READ INFILE DISK4: [MURPHY] STATS.DAT
$ READ_LOOP:
$
READ/END_OF_FILE=END_LOOP INFILE RECORD

$
$!

GOTO READ_LOOP

$ END_LOOP:
$
CLOSE INFILE
$EXIT

In this example, the procedure executes the READ command repeatedly
until the end-of-file status is returned. Then, the procedure branches to the
line labeled END-LOOP. Note that the labels you specify for /END_OF_
FILE qualifiers are subject to the same rules as labels specified for a GOTO
command.
You should always use the /END_OF_FILE qualifier when you use the
READ command in a loop. Otherwise, when the error condition indicating
the end-of-file is returned by the VMS Record Management Services (VMS
RMS}, the command interpreter performs the error action specified by the
current ON command. For example, VMS RMS returns the error status
%RMS-E-EOF. This causes a command procedure to exit unless the procedure
has established its own error handling.
6.1.2.2

Reading Records Randomly from Indexed Sequential Files

You can use the READ command with the /INDEX and /KEY qualifiers
to read records randomly from indexed sequential access method files. The
/KEY and /INDEX qualifiers specify that a record should be read from the file _
by finding the specified key in the index, and returning the record associated
with that key. If you do not specify an index, the primary index, 0, is used.
After you read a record randomly, you can read the remainder of the file
sequentially from that point using READ commands without the /KEY or
/INDEX qualifiers.
You can use the READ command with the /DELETE qualifier to delete
records from indexed sequential access method files. The /DELETE qualifier
causes a record to be deleted from a file after it has been read. Use the
/DELETE qualifier with the /INDEX and /KEY qualifiers to delete a record
specified by a given key.
For more information on the /DELETE, /INDEX, and /KEY qualifiers, see the
description of the READ command in the VMS DCL Dictionary.

6-4

File Input/Output
6.1 Commands for File 1/0

6.1.3

WRITE Command
Use the WRITE command to write a record to a file. Specify the data to
be written as a character string expression, or as a list of expressions. For
example:
$ OPEN/WRITE OUTFILE DISK4: [MURPHY]NEW_STATS.DAT
$ WRITE OUTFILE "File created April 15, 1984"

$ CLOSE OUTFILE

When you specify data for the WRITE command, follow the rules for
character string expressions described in Chapter 2. Note that the WRITE
command automatically substitutes symbols and lexical functions, as follows:
$OPEN/WRITE OUTFILE DISK4:[MURPHY]NEW_STATS.DAT
$ INQUIRE NAME "Enter name"
$ WRITE OUTFILE NAME

In this example, the WRITE command writes the value of the symbol NAME
to NEW_STATS.DAT.
You can intersperse symbol names and literal character strings within a
WRITE command, as follows:
$WRITE OUTFILE "Count is 11 ,COUNT, 11 • 11

If the value of COUNT is 4, this WRITE command writes the following string
to the file OUTFILE:
Count is 4.

Another way to mix literal strings with symbol names is to place the entire
string within quotation marks and use double apostrophes to request symbol
substitution. For example:
$ WRITE OUTFILE "Count is ''COUNT'."

Figure 6-1 shows different ways of specifying data for the WRITE command.
The WRITE command can write records only to files that have been opened
for writing. (You can use either the /WRITE or the /APPEND qualifiers
to open files for writing.) When the WRITE command writes a record,
it positions the record pointer after the record just written. The WRITE
command can write a record that is up to 2048 bytes long.
If you want to write a record that is longer than 1024 bytes, or if any
expression in the WRITE command is longer than 255 bytes, you must
use the /SYMBOL qualifier when you write the record. See the description
of the WRITE command in the VMS DCL Dictionary for more information on
writing long records.

You can use the WRITE command with the /UPDATE qualifier to change a
record rather than insert a new one. To use the /UPDATE qualifier, you must
have opened a file for both reading and writing. (See Section 6.2.1.)-

6-5

File Input/Output
6.1 Commands for File 1/0

Figure 6-1

Symbol Substitution with the WRITE Command

$ @FIGURE

DBA1:[HIGGINS]FIGURE.COM

$ TYPE DATA.OUT
the character strins

ABC
COUNT IS ll
MODE IS INTERACTIVE
FOURTH PARAMETER

e
0
0
0

$ ABC = "the character strins"
$ COUNT = ll
$ Pll ="fourth Para111eter"
$ OPEN WRITE OUTFILE DATA.OUT
$ WRITE OUTFILE ABC
$ WRITE OUTFILE "ABC"
$ WRITE OUTFILE "COUNT IS "tCOUNT
$ WRITE OUTF I LE "MODE IS ' 'F$MODE ( ) '"
$ WRITE OUTFILE P'COUNT'
$ CLOSE OUTFILE

The WRITE command automatically performs symbol substitution on character strings that are not enclosed in
quotation marks; substitution is not recursive.

f) If a character string is enclosed in quotation marks, the WRITE command does not perform symbol substitution.
f) When two or more symbol names or character strings are specified, the WRITE command concatenates the strings
before it writes the record to the output file.

Q Within character strings, the command interpreter performs substitution requested by apostrophes during command
input; the WRITE command executes the results.

If the data specified for a WRITE command contains an apostrophe, the command interpreter performs symbol
substitution during command input (as in
the WRITE command performs substitution on the resulting command
string.

Q );

ZK-830-82

6.1.4

CLOSE Command
The CLOSE command closes a file and deassigns the logical name created by
the OPEN command. For example:
$ OPEN INFILE DISK4: [MURPHY] STATS.DAT

$ CLOSE INFILE

Be sure to close all files you open in a command procedure before the
command procedure terminates. If you fail to close an open file, the file
remains open when the command procedure terminates and the logical name
assigned to the open file is not deleted from the process logical name table.

6.2

Modifying a File
I

You can modify files in the following three ways:
•

Update records in the current version of the file.

•

Read records from an input file and create a new version of the file that
incorporates your changes.

•

Append records to the current version of the file.

The following sections describe these methods.

6-6

File Input/Output
6.2 Modifying a File

6.2.1

Updating Records in a File
When you update a file, you can replace existing records although you cannot
add new records. When you update a file, you do not create a new version of
the input file.
In a sequential file, you can update individual records only if the revised
records are exactly the same size as the existing records. In an indexed
sequential file, you can update individual records regardless of the record
sizes.
To update records in a file, do the following:
1

Open the file for both read and write access.

Use the READ command to obtain the records that you want to modify.

Modify the record. In a sequential file, the text of this record must be
exactly the same size as the original record. If the text of the modified
record is shorter, pad the record with spaces, adding spaces to the end of
the modified record until it is the same length as the original record. If
the text of the modified record is longer, you cannot use this method to
modify the file.

Use the WRITE command with the /UPDATE qualifier to write the
modified record back to the file.

Continue using the READ and WRITE commands to read and update the
records in the file until you have finished updating the file.

Use the CLOSE command to close the file.

After you close the file, it contains the same version number as when you
started even though individual records have been changed.
The following command procedure shows how to make changes to a
sequential file by reading and updating individual records.
$! Open STATS.DAT and assign it the logical name FILE
$!
$ OPEN/READ/WRITE FILE DISK4: [MURPHY] STATS.DAT
$ BEGIN_LOOP:
$! Read the next record from FILE into the symbol RECORD
$
READ/END_OF_FILE=END_LOOP FILE RECORD
$! Display the record and see if the user wants to change it
$! If yes, get the new record. If no, repeat loop
$!
PROMPT:
$
WRITE SYS$0UTPUT RECORD
$
INQUIRE/NOPUNCTUATION OK "Change? Y or N [Y] "
$
IF OK .EQS. "N" THEN GOTO BEGIN_LOOP
$
INQUIRE NEW_RECORD "New record"
$
$! Compare the old and new records
$! If old record is shorter than new record, issue an error message
$! If old record and new record are the same length, write the record
$! Otherwise pad new record with spaces so it is correct length
$!
OLD_LEN = F$LENGTH(RECORD)
$
NEW_LEN = F$LENGTH(NEW_RECORD)
$
IF OLD_LEN .LT. NEW_LEN THEN GOTO ERROR
$
IF OLD_LEN .EQ. NEW_LEN THEN GOTO WRITE_RECORD
$
SPACES = II
$
PAD = F$EXTRACT(O,OLD_LEN-NEW_LEN,SPACES)
$

6-7

File Input/Output
6.2 Modifying a File

$
$!
$
$
$
$!
$
$
$
$!
$
$
$

6.2.2

NEW_RECORD = NEW_RECORD + PAD
WRITE_RECORD:
WRITE/UPDATE FILE NEW_RECORD
GOTO BEGIN_LOOP
ERROR:
WRITE SYS$0UTPUT "Error -- New record is too long"
GOTO PROMPT
END_LOOP:
CLOSE FILE
EXIT

Creating a New Output File
To make extensive changes to a file, you may need to rewrite the entire
file. Because you are creating a new output file, you can modify the size of
records, add records, or delete records.
To create a new output file, follow these steps:
1

Use the OPEN command to open a file for read access. This is the input
file, the file you are modifying.

Use the OPEN command to open a new file for write access. This is the
output file, the file that you are creating. If you give the output file the
same name as the input file, the output file will have a version number
one greater than the input file.

Use the READ command to read a record from the file you are modifying.

If the record needs to be changed, modify the record and then use the
WRITE command to write the record to the new file. If the record is
correct, then write it directly to the new file. If the record is to be deleted,
do not write it to the new file.

Continue reading and processing records until you have finished.

Use the CLOSE command to close both the input and the output files.

The following example shows a command procedure that reads a record from
an input file, processes the record, and copies the record into an output file.

6-8

File Input/Output
6.2 Modifying a File

$! Open STATS.DAT for reading and assign it
$! the logical name INFILE
$! Open a new version of STATS.DAT for writing
$! and assign it the logical name OUTFILE
$!
$ OPEN/READ INFILE DISK4: [MURPHY] STATS.DAT
$ OPEN/WRITE OUTFILE DISK4: [MURPHY] STATS.DAT
$!
$ BEGIN_LOOP:
$! Read the next record from INFILE into the symbol RECORD
$!
READ/END_OF_FILE=END_LOOP INFILE RECORD
$
$! Display the record and see if the user wants to change it
$! If ~es, get the new record. If no, write record directly
$! to OUTFILE
$!
PROMPT:
$
WRITE SYS$0UTPUT RECORD
$
INQUIRE/NOPUNCTUATION OK "Change? Y or N [Y] II
$
IF OK .EQS. "N" THEN GOTO WRITE_RECORD
$
INQUIRE RECORD "New record"
$
$!
WRITE_RECORD:
$
WRITE OUTFILE RECORD
$
GOTO BEGIN_LOOP
$
$!
$! Close input and output files
$!
END_LOOP:
$
CLOSE INFILE
$
CLOSE OUTFILE
$
EXIT
$

6.2.3

Appending Records to a File
The OPEN/ APPEND command allows you to append records to the end of
an existing file. To append records, follow these steps:
1

Use the OPEN command with the /APPEND qualifier to position the
record pointer at the end of the file. The/ APPEND qualifier does not
create a new version of the file.

Use the WRITE command to write new data records. Continue adding
records until you are through.

Use the CLOSE command to close the file.

The following example appends new records to a file.

6-9

File Input/Output
6.2 Modifying a File

$! Open STATS.DAT to append files and assign
$! it the logical name FILE
$!
$ OPEN/APPEND FILE DISK4: [MURPHY] STATS.DAT
$!
$ BEGIN_LOOP:
$! Obtain record to be appended and place this
$! record in the symbol RECORD
$!
$
PROMPT:
$
INQUIRE RECORD "Enter new record (press RET to quit) "
$
IF RECORD . EQS. '"' THEN GOTO END_LOOP
$! Write record to FILE
$!
WRITE FILE RECORD
$
GOTO BEGIN_LOOP
$
$!
$! Close FILE and exit
$!
END_LOOP:
$
CLOSE FILE
$
$

6.3

EXIT

Handling 1/0 Errors
Use the /ERROR qualifier with the OPEN, READ, WRITE, and CLOSE
commands to handle errors. The /ERROR qualifier directs control to a label
in your command procedure if an 1/0 error occurs. Also, the /ERROR
qualifier suppresses error messages that would normally be displayed on the
terminal. The following example uses the /ERROR qualifier with the OPEN
command:
$ OPEN/READ/ERROR=CHECK FILE CONTINGEN.DOC

$ CHECK:
$ WRITE SYS$0UTPUT "Error opening file"

The OPEN command requests that the file CONTINGEN.DOC be opened for
reading. If the file cannot be opened (for example, if the file does not exist),
the OPEN command returns an error condition. Control is then transferred to
the label CHECK.
The error path specified by the /ERROR qualifier overrides the current ON
condition established for the command level. If an error occurs and the target
label is successfully given controt the reserved global symbol $STATUS
retains the code for the error. You can use the F$MESSAGE lexical function
in your error-handling routine to display the message in $STATUS:
$ OPEN/READ/ERROR=CHECK FILE 'Pl'

6-10

File Input/Output
6.3 Handling 1/0 Errors

$ CHECK:
$ ERR_MESSAGE = F$MESSAGE($STATUS)
$ WRITE SYS$0UTPUT "Error opening file: ",P1
$ WRITE SYS$0UTPUT ERR_MESSAGE

If an error occurs while you are using the OPEN, READ, WRITE, or CLOSE

commands and you did not specify an error action, the current ON command
action is taken. (See Chapter 7.)
When a READ command receives an end of file message, the error action is
determined in the following way. If you used the /END_OFJILE qualifier,
control is passed to the specified label. If /END_OF_FILE is not specified,
control is given to the label specified with the /ERROR qualifier. If neither
qualifier is specified, the current ON action is taken.

6-11

Controlling Error Conditions and CTRL/Y Interrupts

This chapter describes what happens when an error condition or a CTRL/Y
interrupt occurs while a command procedure is executing. It also describes
how you can use the ON, SET [NO]ON, and SET [NO]CONTROL commands
to change the defaults for handling error conditions and CTRL/Y interrupts.

7 .1

Detecting Errors in Command Procedures
When each DCL command in a command procedure completes execution, the
command interpreter saves a condition code that describes the reason why
the command terminated. This code can indicate successful completion or it
can identify an informational or error message.
The command interpreter examines the condition code after it performs each
command in a command procedure. If an error that requires special action
has occurred, the system performs the action. Otherwise, the next command
in the procedure executes.

7.1.1

Condition Codes and $STATUS
The command interpreter saves the condition code as a 32 bit longword in
the reserved global symbol $STATUS. $STATUS conforms to the format of a
VMS message code as follows:
•

Bits 0-2 contain the severity level of the message.

•

Bits 3-15 contain the message number.

•

Bits 16-27 contain the number associated with the facility that generated
the message.

•

Bits 28-31 contain internal control flags.

When a command completes successfully, $STATUS has an odd value. (Bits
0-2 contain a 1 or a 3.) When any type of warning or error occurs, $STATUS
has an even value. (Bits 0-2 contain a 0, 2, or 4.) The command interpreter
maintains and displays the current hexadecimal value of $STATUS. Display
the ASCII translation of $STATUS by entering the following commands:
$ SHOW SYMBOL $STATUS
$STATUS = II %X109110A2"
$ WRITE SYS$0UTPUT F$MESSAGE(%X109110A2)
%CREATE-E-OPENOUT, error opening !AS as output

7-1

Controlling Error Conditions and CTRL/Y Interrupts
7 .1 Detecting Errors in Command Procedures

7.1.2

Severity Levels and $SEVERITY
The low-order three bits of $STATUS represent the severity of the condition
that caused the command to terminate. This portion of the condition code is
contained in the reserved global symbol $SEVERITY. $SEVERITY can have
the values 0 through 4, with each value representing one of the following
severity levels:
Value

Severity

Warning
Success

Error

Information

Fatal error

Note that the success and information codes have odd numeric values and
warning and error codes have even numeric values. You can test for the
successful completion of a command with IF commands that perform logical
tests on $SEVERITY or $STATUS as follows:
$ IF $SEVERITY THEN GOTO OKAY
$ IF $STATUS THEN GOTO OKAY

These IF commands branch to the label OKAY if $SEVERITY and $STATUS
have true (odd) values. When the current value in $SEVERITY and $STATUS
is odd, the command or program completed successfully. If the command or
program did not complete successfully, then $SEVERITY and $STATUS are
even; therefore the IF expression is false.
Instead of testing that a condition is true, you can test whether it is false. For
example:
$IF .NOT. $STATUS THEN ...

The command interpreter uses the severity level of a condition code to
determine whether to take the action defined by the ON command as
described in Section 7.2.1.

7.1.3

Commands That Do Not Set $STA TUS
Most DCL commands invoke system utilities that generate status values and
error messages when they complete. However, there are several commands
that do not change the values of $STATUS and $SEVERITY if they complete
successfully. These commands are as follows:

7-2

CONTINUE

DECK

SET SYMBOL/SCOPE

DEPOSIT

SHOW STATUS

EOD

SHOW SYMBOL

EXAMINE

STOP

GOTO

WAIT

Controlling Error Conditions and CTRL/Y Interrupts
7 .1 Detecting Errors in Command Procedures

If any of these commands results in a nonsuccessful status, however, that
condition code will be placed in $STATUS, and the severity level will be
placed in $SEVERITY.

7. 2

Error Condition Handling
By default, the command interpreter executes an EXIT command when a
command results in an error or severe error. This causes the procedure to exit
to the previous command level. For other severity levels (success, warning,
and informational) the command procedure continues.
There is one exception to the way that the command interpreter handles
errors. If you reference a label in a command procedure and the label does
not exist (for example, if you include the command GOTO ERRl and ERRl
is not used as a label in the procedure) then the GOTO command issues a
warning and the command procedure exits. You can, however, override this
behavior if you use the ON command to specify an action for the command
procedure to take on warnings. (Section 7.2.1 describes the ON command.)
When the system issues an EXIT command as part of an error handling
routine, it passes the value of $STATUS back to the previous command
level, with one change. The command interpreter sets the high-order digit
of $STATUS to 1 so that the command interpreter does not redisplay the
message associated with the status value.
For example, the following command procedure TEST.COM contains an error
in the output file specification:
$ CREATE DUMMY.DAT\
THIS IS A TEST FILE
$ SHOW TIME

When you execute the procedure, the CREATE command returns an error
in $STATUS and displays the corresponding message. The command
interpreter then examines the value of $STATUS, determines that an error
occurred, issues an EXIT command, and returns the value of $STATUS. When
the procedure exits, the error message is not redisplayed, as the CREATE
command already displayed the message once. At DCL command level you
can see that $STATUS contains the error message, but the high-order digit
has been set to 1.
$ ©TEST
%CREATE-E-OPENOUT, error opening DUMMY.DAT as output
-RMS-F-SYN, file specification syntax error
%DCL-W-SKPDAT, image data (records not beginning with "$") ignored
$ SHOW SYMBOL $STATUS
$STATUS = "%X109110A2"
$ WRITE SYS$0UTPUT F$MESSAGE(%X109110A2)
%CREATE-E-OPENOUT, error opening !AS as output

You can use the ON and SET [NO]ON commands to change the way that the
system responds to errors in command procedures.

7-3

Controlling Error Conditions and CTRL/Y Interrupts
7 .2 Error Condition Handling

7.2.1

ON Command
The ON command specifies an action to be performed if an error of a
particular severity or worse occurs. If such an error occurs, the system
takes the following actions:
•

The action specified by the ON command is performed.

•

The system sets $STATUS and $SEVERITY to indicate the result of the
specified ON action. (In general, these are set to success.)

•

The default error action (to exit if an error or severe error occurs) is reset.

The format of the ON command is as follows:
ON condition THEN [$] command

You can specify error conditions with one of the keywords WARNING,
ERROR, or SEVERE_ERROR. If an ON command action is established for a
specific severity level, the command interpreter performs the specified action
when errors of the same or worse severity occur. When less severe errors
occur, the command interpreter continues processing the file. Table 7-1
summarizes how the ON command controls error handling.
Table 7-1

ON Command Keywords and Actions

ON Keyword

Action Taken

WARNING

Command procedure performs the specified action if a
warning, error, or severe error occurs.

ERROR

Command procedure performs the specified action if an error
or severe error occurs; the procedure continues if a warning
occurs.

SEVERE_ERROR

Command procedure performs the specified action if a
severe (fatal) error occurs; the procedure continues if a
warning or error occurs.

For example, if you want to override the default error handling so that
a procedure exits when warnings, errors, or severe errors occur, use the
following command:
$ ON WARNING THEN EXIT

An ON command action is executed only once; thus, after a command
procedure performs the action specified in an ON command, the default
error action is reset. For example, suppose that your procedure includes the
following command:
$ ON ERROR THEN GOTO ERR1

In this case, the command procedure executes normally until an error or
severe error occurs. If such an error occurs, then the procedure resumes
executing at ERRl, $STATUS and $SEVERITY are set to success, and the
default error action is reset. If a second error occurs before another ON
or SET NOON command is executed, the procedure exits to the previous
command level.

7-4

Controlling Error Conditions and CTRL/Y Interrupts
7 .2 Error Condition Handling

The action specified by an ON command applies only within the command
level in which the command is executed. Therefore, if you execute an ON
command in a procedure that invokes another procedure, the ON command
action does not apply to the nested procedure.

Note: Only one ON statement can be in effect at any one time. If more than one
ON statement has been issued, only the last one is in effect.
Figure 7-1 illustrates ON command actions. Also, the sample procedures
FORTUSER.COM and CALC.COM in Appendix A illustrate the use of the
ON command to establish error handling.
Figure 7-1

ON Command Actions
DBA 1:[HIGGINS]FORT.COM

@FORT

0
8

ON ERROR THEN CONTINUE
FORTRAN A

FORTRAN B

ON WARNING THEN D(IT

FORTRAN C

D( IT

0 This ON command overrides the default command action (on warning, continue; on error or severe error, exit). If an
error or severe error occurs while A.FOR is being compiled, the command procedure continues with the next
command.

fJ The default command action is reset if the previous ON command takes effect. Thus, if an error or severe error
occurs while both A.FOR and B.FOR are being compiled, the command procedure exits.

If the command procedure does not exit before this command is executed, this command action takes effect.

Q If a warning, error, or severe error occurs while C.FOR is being compiled, the command procedure exits.
ZK-826-82

7.2.2

Disabling Error Checking
You can prevent the command interpreter from checking the status returned
from commands by using the SET NOON command in your command
procedure. When you use the SET NOON command, the command
interpreter continues to place values in $STATUS and $SEVERITY, but
does not perform any error checking. You can restore error checking with the
SET ON command or with an ON command. For example:
$ SET NOON
$ RUN TESTA
$ RUN TESTB
$ SET ON

7-5

Controlling Error Conditions and CTRL/Y Interrupts
7 .2 Error Condition Handling

The SET NOON command preceding these RUN commands ensures that the
command procedure continues if either of the programs TESTA or TESTB
return an error condition. The SET ON command restores the default error
checking by the command interpreter.
When a procedure disables error checking, it can explicitly check the value of
$STATUS following the execution of a command or program. For example:
$ SET NOON
$ FORTRAN MYFILE
$ IF $STATUS THEN LINK MYFILE
$ IF $STATUS THEN RUN MYFILE
$ SET ON

In the previous example, the first IF command checks whether $STATUS
has a true value (that is, if it is an odd numeric value). If so, the FORTRAN
command was successful and the LINK command executes. After the LINK
command executes, $STATUS is tested again. If $STATUS is odd, the RUN
command executes; otherwise, the RUN command does not execute. The
SET ON command restores the current ON condition action; that is, whatever
condition was in effect before the SET NOON command was executed.
The SET ON or SET NOON command applies only at the current command
level, that is, the command level at which the command is executed. If you
use the SET NOON command in a command procedure that calls another
command procedure, the default error checking mechanism will be in effect
within the nested procedure. Note that SET NOON has no meaning when
entered interactively at command level 0.

7 .3

Handling CTRL/Y Interrupts
By default, when you press CTRL/Y while a command procedure is
executing, the command interpreter prompts for command input at a special
command level called CTRL/Y command level. From CTRL/Y command
level, you can enter DCL commands that are executed within the command
interpreter, and then resume execution of the command procedure with the
CONTINUE command. In addition, you can stop the procedure by entering a
DCL command that forces the command procedure to stop executing.
You can override the way that command procedures process CTRL/Y
interrupts by using the ON command as described in Section 7.3.2.

7.3.1

Interrupting a Command Procedure
You can interrupt a command procedure that is executing interactively
by pressing CTRL/Y. When you press CTRL/Y, the command interpreter
establishes a new command level, called the CTRL/Y level, and prompts for
command input. When the interruption occurs depends on the command or
program that is executing:
•

7-6

If the command is executed by the command interpreter itself (for
example, IF, GOTO, or an assignment statement), the command
completes execution before the command interpreter prompts for a
command at the CTRL/Y level.

Controlling Error Conditions and CTRL/Y Interrupts
7 .3 Handling CTRL/Y Interrupts

•

If the command or program is a separate image (that is, an image other

than the command interpreter), the command is interrupted and the
command interpreter prompts for a command at the CTRL/Y level.
At the CTRL/Y level, the command interpreter stores the status of all
previously established command levels, so that it can restore the correct
status after any CTRL/Y interrupt.
After you interrupt a procedure, you can do the following:
•

Enter a DCL command that is executed within the command interpreter.
Among these commands are the SET VERIFY, SHOW TIME, SHOW
TRANSLATION, ASSIGN, EXAMINE, DEPOSIT, SPAWN and ATTACH
commands. After you enter one or more of these commands, you can
resume the execution of the procedure with the CONTINUE command.
(See Table 3-1 for a complete list of commands that are executed within
the command interpreter.)
When you enter the CONTINUE command, the command procedure
resumes execution with the interrupted command or program, or with the
line after the most recently completed command.

•

Enter a DCLcommand that executes another image. When you enter any
command that invokes a new image, the command interpreter returns
to command level 0 and executes the command. This terminates the
command procedure's execution. Any exit handlers declared by the
interrupted image are allowed to execute before the new image is started.

•

Enter the EXIT or STOP command to terminate the command procedure's
execution. If you use the EXIT command, exit handlers declared by the
interrupted image are allowed to execute. However, the STOP command
does not execute these routines.

If you interrupt the execution of a privileged image, you can enter only

the CONTINUE, SPAWN, or ATTACH commands if you want to save the
context of the image. If you enter any other commands (except from within
a subprocess that you have spawned or attached to), the privileged image is
forced to exit.

7.3.2

Setting a CTRL/Y Action Routine
The ON command, which defines an action to be taken in case of error
conditions, also provides a way to define an action routine for a CTRL/Y
interrupt that occurs during execution of a command procedure. The action
that you specify overrides the default CTRL/Y action (that is, to prompt for
command input at the CTRL/Y command level).
For example:
$ ON CONTROL_Y THEN EXIT

If a procedure executes this ON command, a subsequent CTRL/Y interrupt

during the execution of the procedure causes the procedure to exit. Control is
passed to the previous command level.

7-7

Controlling Error Conditions and CTRL/Y Interrupts
7 .3 Handling CTRL/Y Interrupts

When you press CTRL/Y to interrupt a procedure that uses ON CONTROL_
Y, the following actions are taken:
•

If the command currently executing is a command executed within the
command interpreter, the command completes and the CTRL/Y action is
taken.

•

If the current command or program is executed by an image other than
the command interpreter, the image is forced to exit and the CTRL/Y
action is taken. If the image has declared an exit handler, however, the
exit handler is executed before the CTRL/Y action is taken. The image
cannot be continued following the CTRL/Y action.

The execution of a CTRL/Y action does not automatically reset the default
CTRL/Y action (that is, to prompt for command input at the CTRL/Y
command level). A CTRL/Y action remains in effect until one of the
following conditions occurs:
•

The procedure terminates (as a result of pressing CTRL/Y, executing an
EXIT or STOP command, or a default error condition handling action)

•

Another ON CONTROL_Y command is executed

•

The procedure executes the SET NOCONTROL=Y command (See
Section 7.3.3.)

For example, a procedure can contain the following line:
$ ON CONTROL_Y THEN SHOW TIME

When this procedure executes, each CTRL/Y interrupt results in the execution
of the SHOW TIME command. After each SHOW TIME command executes,
the procedure resumes execution at the command following the command
that was interrupted.
Figure 7-2 illustrates two ON CONTROL_Y commands and describes the
flow of execution following CTRL/Y interruptions.

7-8

Controlling Error Conditions and CTRL/Y Interrupts
7 .3 Handling CTRL/V Interrupts

Figure 7-2

Flow of Execution Following CTRL/Y Action

OBA 1:(HIGGINS]FILES.COM

$ @FILES
$ ON CONTROL_Y THEN GOTO CLEAN_UP

0
$

$ TYPE STATUS, OUT; 1 •
$ IF $STATUS THEN DELETE STATUS,OUTi1

$ E)<IT
$ CLEAN-UP:
$ DELETE STATUS.OUTi1
$ DELETE *•TMPi*
$

E)<IT

DBA1:[HIGGINS] PRIV.COM

$ @PR II.I
$ ON CONTROL_Y THEN WRITE SYS$0UTPUT" InterruPtion not

Interruption not allowed ••• continuins

allo1,1ed ••• continuins"

$ TYPE STATUS, OUT; 1
$ IF $STATUS THEN DELETE STATUS,OUTi1

The CTRL/Y interrupt at
occurs during execution of the TYPE command, at
Control is transferred to the label
CLEAN_UP. After executing the routine, the command procedure exits, at
and returns control to the interactive
command level.

The CTRL/Y interrupt ate occurs during execution of the TYPE command, at G). The WRITE command specified in the
ON command is executed. Then, the command procedure continues execution at the command following the interrupted
command.
ZK-827-82

A CTRL/Y action can be specified in each active command level, and affects
only the command level in which it is specified. Figure 7-3 illustrates what
happens when CTRL/Y is pressed during the execution of a nested command
procedure.

7-9

Controlling Error Conditions and CTRL/Y Interrupts
7.3 Handling CTRL/Y Interrupts

Figure 7-3
$

Default CTRL/V Action for Nested Procedures

@SEARCH

DBA1:(HIGGINS]SEARCH.COM

ON CONTROL_Y THEN GOTO CLEAN_UP

@SUBSEARCH
NE)<T _STEP:

$
$

E)<I T
CLEAN_UP:

DBA 1:[HIGGINS] SUBSEARCH.COM

@SUBSUB

DBA 1:[HIGGINS] SUBSUB.COM

ON CONTROL_Y THEN SHOW TIME

E)<IT

If a CTRL/Y interrupt occurs while SEARCH.COM is executing, control is transferred to the label CLEAN_UP.

f) If a CTRL/Y interrupt occurs while SUBSEARCH.COM is executing, control is transferred to the label NEXT_STEP in
SEARCH.COM. Because no CTRL/Y action is specified in SUBSEARCH.COM, the procedure exits to previous command level when a CTRL/Y interrupt occurs.

t) If a CTRL/Y interrupt occurs while SUBSUB.COM is executing, the SHOW TIME command is executed.
ZK-828-82

7.3.3

Disabling and Enabling CTRL/Y Interruptions
The SET NOCONTROL=Y command disables CTRL/Y handling: that is, if a
command procedure executes the SET NOCONTROL=Y command, pressing
CTRL/Y has no effect.
The SET NOCONTROL=Y command also cancels the current CTRL/Y action
established with the ON CONTRQL _ Y command. To reestablish the default
CTRL/Y action, use the following two commands:
$ SET NOCONTROL=Y

$ SET CONTROL=Y

7-10

Controlling Error Conditions and CTRL/Y Interrupts
7 .3 Handling CTRL/Y Interrupts

The first command disables CTRL/Y handling and cancels the current ON
CONTRQL _ Y action; the second command enables CTRL/Y handling. At
this point, the default action is reinstated: if CTRL/Y is pressed during the
execution of the procedure, the command interpreter prompts for a command
at the CTRL/Y command level.
You can use the SET NOCONTROL=Y command at any command level; it
affects all command levels until the SET CONTROL=Y command reenables
CTRL/Y handling.

Note: The ON CONTROL_Y and SET NOCONTROL=Y commands are
intended for special applications. DIGIT AL does not recommend,
in general, that you disable CTRL/Y interrupts. ~To exit from a
nonterminating loop when CTRL/Y is disabled, you must delete the
process from which the looping procedure is executing from another
terminal.

7-11

Working with Batch Jobs

A batch job consists of one or more command procedures that you execute
from another process. To execute a batch job, use the SUBMIT command to
place the job in a batch queue. A batch queue is a list of batch jobs waiting
to execute. After the system places your job in the batch queue, you can
continue using your terminal interactively. Thus, a batch job allows you to
use your terminal for other work while the system executes your command
procedure.
The system creates a detached process to execute your batch job. To create
the detached process, the system logs in using the information from your
UAF record. The system executes the system login command procedure and
your login command procedure, and then executes the command procedures
in the batch job. As these procedures execute, output is written to a log file.
When the batch job completes, you can print the log file or save it in one of
your directories.
You use batch jobs to execute command procedures under the following
conditions:
•

The command procedure takes a long time to execute

•

You want to schedule the command procedure for execution after a
specific time, such as after normal working hours

•

You want to execute the command procedure at a reduced priority,
because it uses a disproportionate amount of system resources

This chapter describes the following techniques for manipulating batch jobs.

8.1

•

Submitting batch jobs

•

Controlling batch job output

•

Controlling jobs in a batch queue

•

Restarting batch jobs

•

Synchronizing batch jobs

Submitting a Batch Job
Use the SUBMIT command to enter a command procedure into a batch queue.
By default, the SUBMIT command places command procedures into a queue
named SYS$BATCH. If you omit the file type when you submit a command
procedure, the type defaults to COM. For example:
$ SUBMIT UPDATE
Job UPDATE (queue SYS$BATCH, entry 201) started on SYS$BATCH

8-1

Working with Batch Jobs
8.1 Submitting a Batch Job

This command creates a job called UPDATE that contains the command
procedure UPDATE.COM. This job is entered in the queue SYS$BATCH and
is assigned the entry number 201. (After a job has been submitted, you refer
to it using the entry number.) The system message shows that SYS$BATCH
has started to execute your job.
When you submit a command procedure for batch execution, the system
saves the complete file specification for the command procedure, including
the version number. If you update a command procedure after you submit
it, the batch job executes the version of the command procedure that you
submitted, rather than the new version.
Because your login defaults are not usually the defaults needed to access files
mentioned in your command procedures, use one of the following methods
to ensure that the correct files are accessed:
•

Use complete file specifications-When referring to a file in a command
procedure or when passing a file to a command procedure, include the
device and directory names as part of the file specification.

•

Use the SET DEFAULT command-Before referring to a file in a
command procedure, use the SET DEFAULT command at the beginning
of the command procedure to specify the proper device and directory.

As a batch job executes, it writes output to a log file. By default, the log file
has the same name as the command procedure you submit, with a file type
of LOG. When the job is finished, the system prints the log file and deletes it
from your directory. See Section 8.3.1 for information on saving log files.

8.1.1

Checking for Batch Jobs in Your Login Command Procedure
Each time you submit a batch job, the system executes your login command
procedure. You can cause sections of your login command procedure to be
included or omitted when you execute batch jobs by using the F$MODE()
lexical function to test for batch jobs.
For example, you might have a section in your login command procedure that
includes commands, logical names, and symbols that you use exclusively for
batch jobs. You might label this section BATCH_COMMANDS, then include
the following command at the beginning of your login command procedure:
IF F$MODE()

. EQS. "BATCH" THEN GOTO BATCH_COMMANDS

To prevent the system from executing any commands in your login command
procedure when you submit a batch job, place the following command at the
beginning of the procedure:
IF F$MODE ()

. NES. "INTERACTIVE" THEN EXIT

You can place this command anywhere in your login command procedure.
When you submit a batch job, the system executes your login command
procedure only to the point at which the preceding command is placed.

8-2

Working with Batch Jobs
8.1 Submitting a Batch Job

8.1.2

Submitting Multiple Command Procedures
When you enter the SUBMIT command, you can specify several command
procedures to be executed in one job. For example:
$ SUBMIT UPDATE.SORT
Job UPDATE (queue SYS$BATCH, entry 207) started on SYS$BATCH

This SUBMIT command creates a batch job that executes UPDATE.COM,
then SORT.COM. Unless you specify a name with the /NAME qualifier, the
SUBMIT command uses the name of the first command procedure as the job
name. Note that if an error causes any command procedure in a job to exit,
the entire job terminates.
When a batch job executes, the operating context of the first procedure
(UPDATE.COM) is not preserved for the second procedure (SORT.COM).
That is, the system deletes local symbols created by UPDATE.COM before
SORT.COM executes. Global symbols, however, are preserved.
You cannot specify different parameters for individual command procedures
within a single job. The following example passes the same two parameters
to UPDATE.COM and SORT.COM:
$ SUBMIT UPDATE, SORT/PARAMETERS = _$ (DISK1: [ACCOUNT.BILLS]DATA.DAT, DISK2: [ACCOUNT]NAME.DAT)
Job UPDATE (queue SYS$BATCH, ENTRY 208) started on SYS$BATCH

8.1.3

Controlling a Batch Job
Use qualifiers to the SUBMIT command to control how a batch job is
submitted. The following list describes some common operations and the
qualifiers you use to perform them. For a complete list of qualifiers to the
SUBMIT command, see the VMS DCL Dictionary.
You can do the following when you submit a batch job:
•

Name the job-Use the /NAME qualifier to specify a name for the batch
job. Otherwise the job name defaults to the file name of the first (or only)
command procedure in the job.

•

Specify the time when the batch job starts to execute-Use the /AFTER
qualifier to specify a time after which the job can be executed. When you
use /AFTER, the job remains in the batch queue until the specified time;
then it executes. To hold a job in the queue until you explicitly release
it, use the /HOLD qualifier. (To release a job that is being held, use the
SET ENTRY/RELEASE command.)

•

Request notification of job completion-Use the /NOTIFY qualifier to
have the system send a message to your terminal when the batch job
finishes executing.

•

Send the job to a specific queue-Use the /QUEUE qualifier to send a
batch job to a queue other than SYS$BATCH. To execute a command
procedure that is located on a remote node, use the /REMOTE qualifier.
This sends the job to SYS$BATCH at the remote node.

•

Specify execution characteristics-You can specify execution
characteristics such as working set default, working set extent, working
set size, job scheduling priority, and CPU time limit.

8-3

Working with Batch Jobs
8.1 Submitting a Batch Job

•

Pass parameters-Use the /PARAMETERS qualifier to pass parameters to
a batch job.

•

Save the log file-Use the /NOPRINTER or /KEEP qualifiers to save a
batch job log file. See Section 8.3 for information on controlling batch job
output.

•

Make the batch job restartable-Use the /RESTART qualifier to enable
you to restart the job if the system fails while the job is executing. See
Section 8.5 for information on restarting batch jobs.

If you submit jobs frequently using the same qualifiers, place a global symbol
for the SUBMIT command string in your login command procedure. For
example:
$ SUBMIT == "SUBMIT/NOTIFY/NOPRINTER"

8.2

Passing Data to Batch Jobs
The default input stream (SYS$INPUT) for a batch job is the command
procedure that is being executed. Because a detached process is executing the
batch job, you cannot redefine SYS$INPUT to the terminal (as you can with
command procedures that you execute interactively.) This means that you
cannot enter input to a command procedure executing in a batch job from
your terminal. Therefore, pass input to a batch job in one of the following
ways:
•

Include the data in the command procedure itself

•

Temporarily define SYS$INPUT as a file

•

Pass parameters to the command procedure

To include data in a command procedure, place the data on the lines after the
command or image. For example:
$! Execute AVERAGE.EXE
$ RUN AVERAGE
647

899
532

401

$ EXIT

To define SYS$INPUT temporarily as a file, use the DEFINE/USER_MODE
command. For example:
$ DEFINE/USER_MODE SYS$INPUT STATS.DAT
$ RUN AVERAGE
$ EXIT

To pass parameters to a command procedure, use the /PARAMETERS
qualifier when you submit the batch job. For example:
$ SUBMIT/PARAMETERS=(DISK1: [PAYROLL] EMPLOYEES.DAT) CHECKS
Job CHECKS (queue SYS$BATCH, entry 209) started on SYS$BATCH

Note that you cannot specify different parameters for individual command
procedures within a single job; use separate SUBMIT commands if you need
to pass different groups of parameters.

8-4

Working with Batch Jobs
8.2 Passing Data to Batch Jobs

Note: The SHOW QUEUE/FULL command displays full information about jobs
in a batch queue. This display includes any parameters you pass to the
procedure. Therefore, do not pass confidential information (such as a
password) to a batch job.

8.3

Batch Job Output
If you use the SUBMIT command without any qualifiers that change the log

file name, the log file has the same name as the first command procedure
in the batch job, and a file type of LOG. The system writes output to the
log file once each minute. (To specify a different time interval, include the
SET OUTPUT-RATE command in your command procedure.) When the job
finishes, the system sends the log file to the default system print queue and
deletes it from your directory after it prints unless you specify otherwise.
Section 8.3.1 describes how to save the log file or prevent it from printing
automatically.
The batch job log file includes all output to SYS$0UTPUT and SYS$ERROR.
It also includes, by default, all command lines executed in the command
procedure. To prevent the command lines from being printed, use either the
SET NOVERIFY command or the F$VERIFY lexical function in your command
procedure. When the job completes, the system writes job termination
information (using the long form of the system logout message) to the log file.
When a batch job fails to complete successfully, you can examine the log file
to determine the point at which the command procedure failed and the error
status that caused the failure.

8.3.1

Saving the Log File
To save the log file, use either the /KEEP or the /NOPRINTER qualifier.
The /KEEP qualifier saves the log file after it is printed; the /NOPRINTER
qualifier saves the log without printing it. (If you specify neither of these
qualifiers, the default action occurs. The log file is queued to the default
print queue SYS$PRINT and is deleted after it prints.) The /KEEP and
/NOPRINTER qualifiers save the log file in your default login directory. The
log file has the same name as the first command procedure in the batch job,
and a file type of LOG. To specify an alternate file name or directory name,
or both, use the /LOGJILE qualifier. To rename and save the log file, you
must use /LOG _FILE plus either /KEEP or /NOPRINTER. For example:
$ SUBMIT/LOG_FILE=DISK2: [JONES.RESULTS]/NOPRINTER _$ DISK2: [JONES.RESULTS]UPDATE

8.3.2

Reading the Log File
You can use the TYPE command to read the log file to determine how much
of a batch job has completed. However, if you attempt to display the log file
while the system is writing to it, you receive a message indicating that the file
is locked by another user. If this occurs, wait a few seconds and try again.

8-5

Working with Batch Jobs
8.3 Batch Job Output

8.3.3

Including All Command Output in the Batch Job Log
Typically, a batch job command procedure that compiles, links, and executes
a program creates additional printed output such as a compiler listing or a
linker map. To produce printed copies of these files, a batch job command
procedure can contain the PRINT commands necessary to print them, as in
the following example:
$ FORTRAN BIGCOMP
$ PRINT BIGCOMP
$ LINK/MAP/FULL BIGCOMP
$ PRINT BIGCOMP.MAP

When this command procedure completes processing, there are three separate
output listings: the batch job log, the compiler listing, and the linker map.
If you want a batch job log to contain all output from the command

procedure, including printed listings of compiler or linker output files, you
can do either of the following:
•

Use the TYPE command instead of the PRINT command in the command
procedure. The TYPE command writes to SYS$0UTPUT. (In a batch job,
SYS$0UTPUT is equated to the batch job log file.)

•

Use qualifiers on appropriate commands to direct the output to
SYS$0UTPUT.

The following example shows the second technique:
$ FORTRAN/LIST=SYS$0UTPUT BIGCOMP
$ LINK/MAP=SYS$0UTPUT/FULL BIGCOMP

When these commands are executed in a batch job, the output files from the
compiler and the linker are written directly to the log file. Note that if you
use this technique, the output files are not saved on disk unless you save the
log file.

8.4

Controlling Jobs in a Batch Queue
Once a job has been entered in a batch job queue, you can monitor its status
with the SHOW ENTRY command or the SHOW QUEUE command. The
SHOW ENTRY command works as follows:
$ SUBMIT EXCHAN.DAT
Job EXCHAN (queue SYS$BATCH entry 999) started on SYS$BATCH
$ SHOW ENTRY 999
Jobname

Username

EXCHAN
BLASS
On batch queue SYS$BATCH

Entry Status
999 Executing

The SHOW QUEUE command works as follows:
$ SUBMIT/NOPRINTER/PARAMETER=STATS.DAT UPDATE
Job UPDATE (queue SYS$BATCH entry 1080) started on BOSTON_BATCH
$ SHOW QUEUE BOSTON_BATCH
Batch queue BOSTON_BATCH on BOSTON::

8-6

Jobname

Username

Entry Status

UPDATE

ODONNELL

1080 Executing

Working with Batch Jobs
8.4 Controlling Jobs in a Batch Queue

If you had no jobs in the queue, the system would display the following
message:
$ SHOW QUEUE BOSTON_BATCH
Batch queue BOSTON_BATCH, on BOSTON::

To see complete information on your jobs, use the /FULL qualifier to the
SHOW ENTRY or SHOW QUEUE command:
$ SHOW ENTRY/FULL 999
Jobname

Username

Entry Status

EXCHAN
999 Executing
BLASS
On batch queue BOSTON_BATCH
Submitted 23-NOV-1987 13:12 /PRIORITY=100
WRKD: [BLASS]EXCHAN.DAT;3
$ SHOW QUEUE/FULL BOSTON_BATCH
Job UPDATE (queue BOSTON_BATCH, entry 1080) started on BOSTON_BATCH
Batch queue BOSTON_BATCH, on BOSTON::
/BASE_PRIORITY=3 /JOB_LIMIT=5 /OWNER=[EXEC] /PROTECTION=(S:E,O:D,G:R,W:W)
Jobname

Username

Entry Status

UPDATE
ODONNELL
1080 Executing
Submitted 15-FEB-1984 10:46 /KEEP /PARAM=("STATS.DAT") /NOPRINTER /PRIO=~
_BOSTON$DQA2: [ODONNELL]TEMP.COM;1 (executing)

The /FULL qualifier displays statistics about BOSTON _BATCH and
characteristics associated with your job.
To see the status of other jobs in the queue, use the SHOW QUEUE/ ALL
command. For example:
$ SHOW QUEUE/ALL BOSTON_BATCH
Batch queue BOSTON_BATCH on BOSTON::
Jobname

-------

no privilege
no privilege
UPDATE

Username

Entry Status

ODONNELL

923 Executing
939 Holding until 27-DEC-1987 19:00
1080 Executing

--------

Note that unless you are a privileged user, you may be able to obtain
information only about jobs that have been submitted under your account.
See the VMS DCL Dictionary for more information on the SHOW ENTRY and
SHOW QUEUE commands.

8.4.1

Changing Job Characteristics
After a job has been submitted to the queue but before the job starts to
execute, you can use the SET ENTRY or the SET QUEUE/ENTRY command
with the appropriate qualifiers to change characteristics associated with the
job. For example, to change the name of a batch job while it is pending in a
batch queue, you can enter either of the following commands:
$ SET QUEUE/ENTRY=209/NAME=NEW_NAME SYS$BATCH
$ SET ENTRY 209 /NAME=NEW_NAME

Both of these commands change the name of the job number 209 to NEW_
NAME.

8-7

Working with Batch Jobs
8.4 Controlling Jobs in a Batch Queue

The following list contains some of the changes you can make with the SET
ENTRY or SET QUEUE/ENTRY commands; for a complete list of qualifiers
see the VMS DCL Dictionary. Note that most of the qualifiers allowed with
the SUBMIT command can also be used with SET ENTRY and the SET
QUEUE/ENTRY commands.
You can make the following changes:

8.4.2

•

Delay processing of a job-Use the/ AFTER qualifier to specify a time
after which the job can be executed; use the /HOLD qualifier to hold a
job until you explicitly release it.

•

Release a job-Use the /NOHOLD or /RELEASE qualifier to release a
job that was submitted with the /HOLD or /AFTER qualifiers.

•

Send a job to a different queue-Use the /REQUEUE qualifier to change
the queue on which the job will execute.

•

Change execution characteristics-You can change execution
characteristics such as working set default, working set extent, working
set size, job scheduling priority, and CPU time limit.

•

Change the parameters to be passed to a job-Use the /PARAMETERS
qualifier to change the parameters.

Deleting and Stopping Batch Jobs
You can delete batch jobs before or during execution. To delete an entry
that is pending or already executing in a batch queue, use the DELETE
/ENTRY command. For example, the following command deletes a job in
SYS$BATCH:
$ DELETE/ENTRY=210 SYS$BATCH

You need special privileges to delete a job that you did not submit. See the

VMS DCL Dictionary for more information.
When a job terminates as a result of a DELETE/ENTRY command, the log
file is neither printed nor deleted from your directory.
When you terminate a job using the DELETE/ENTRY command, it is handled
as an abnormal termination because the operating system's normal job
termination activity is preempted. As a result, the batch job log does not,
for example, contain the standard logout message that summarizes job time
and accounting information. Termination that results either from an explicit
EXIT command or STOP command or the implicit execution of either of these
commands (as the result of the current ON condition), however, is considered
normal termination. The operating system performs proper run-down and
accounting procedures after a normal termination.

8-8

Working with Batch Jobs
8. 5 Restarting Batch Jobs

8.5

Restarting Batch Jobs
If the system fails while your batch job is executing, your job does not

complete. When the system recovers and the queue is restarted, your job is
aborted and the next job in the queue is executed. However, by specifying
the /RESTART qualifier when you submit a job, you indicate that the system
should reexecute the job if the system crashes before the job completes.
By default, a batch job is restarted beginning with the first line. However,
you can specify a different starting point so that you do not reexecute parts of
the job that have completed successfully. To do this, follow these steps:
•

Begin each possible starting point in the procedure with a label. After the
label, use the SET RESTART_VALUE command to set the restarting point
to that label. If the batch job is interrupted by a system crash and is then
restarted, the SET RESTART_VALUE command assigns the appropriate
label name to the global symbol BATCH$RESTART.

•

At the beginning of the procedure, test the value of the symbol
$RESTART. ($RESTART is a global symbol that the system maintains
for you. $RESTART has the value "TRUE" if one of your batch jobs
was restarted after it was interrupted by a system crash. Otherwise,
$RESTART has the value "FALSE".) If $RESTART is true, execute a
GOTO statement using BATCH$RESTART as the transfer label.

The following command procedure shows how to use restart values in a batch
job.
$ ! set default to the directory containing
$ ! the file to be updated and sorted

$ SET DEFAULT DISK1: [ACCOUNTS.DATA84]
$
$ ! check for restarting

$ IF $RESTART THEN GOTO 'BATCH$RESTART'
$

$ UPDATE_FILE:
$ SET RESTART_VALUE = UPDATE_FILE

$ SORT_FILE:
$ SET RESTART_VALUE = SORT_FILE

EXIT

To submit this command procedure as a batch job that can be restarted, use
the /RESTART qualifier when you submit the job. If you restart a job that
was interrupted by a system crash, the job starts executing in the section
where it was interrupted. For example, if the job is interrupted during the
SORT_FILE routine, it starts executing at the label SORTJILE when it is
restarted.
In addition to restarting a job after a system crash, you can also restart a job
after you explicitly stop the job. To stop a job and then restart it on the same
or a different queue, use the STOP /QUEUE/REQUEUE/ENTRY command.
For example:
$ STOP/QUEUE/REQUEUE/ENTRY=212 SYS$BATCH

8-9

Working with Batch Jobs
8.5 Restarting Batch Jobs

This command stops job 212 on SYS$BATCH, and requeues it on
SYS$BATCH. (To enter this command, job 212 must have been submitted
with the /RESTART qualifier.) When the batch job executes the second time,
the system uses the global symbol BATCH$RESTART to determine where to
begin executing the job.

8.6

Synchronizing Batch Job Execution
You can use the SYNCHRONIZE and WAIT commands within a command
procedure to place the procedure in a wait state. The SYNCHRONIZE
command causes the procedure to wait for the completion of a specified job,
while the WAIT command causes the procedure to wait for a specified period
of time to elapse. For example, if two jobs are submitted concurrently to
perform cooperative functions, one job can contain the following command:
$ SYNCHRONIZE BATCH25

After this command is executed, the command procedure cannot continue
execution until the job identified by the job name BATCH25 completes
execution. Figure 8-1 shows an example of command procedures that are
submitted for concurrent execution, but which must be synchronized for
proper execution. Each procedure compiles a large source program.
Figure 8-1

Synchronizing Batch Job Execution
DBA 1 :[HIGGINS]MAINCOMP.COM

$SUBMIT MAINCOMP
JOB 314 entered on ctueue SYS$BATCH
$SUBMIT MINCOMP
JOB 315 entered on ctueue SYS$BATCH

$ FORTRAN ALPHA/LIST

0
0

@ $ SYNCHRONIZE MINCOMP
$ LINK/MAP/FULL ALPHA1BETA
$ E>'. IT

DBA 1 :[HIGGINS] MINCOMP.COM

I
.

$$ FORTRAN BETA/LIST
E>'.IT

0 Individual SUBMIT commands are required to submit two separate jobs. Two separate processes will be created.
@ After the FORTRAN command is executed, the SYNCHRONIZE command is executed. If job 315 has completed
execution, job 314 continues with the next command. However, job 314 will not execute the next command, if job 315
is either current or pending.
ZK-832-82

If you specify a job name with the SYNCHRONIZE command, the jobs to be
synchronized must have the same group number in their user identification
codes (UICs). To synchronize jobs that have different group numbers, you
must specify the job entry number with the SYNCHRONIZE command rather
than the job name. For example:
$ SYNCHRONIZE/ENTRY=454

This SYNCHRONIZE command places the current command procedure in a
wait state until job 454 completes.

8-10

Working with Batch Jobs
8.6 Synchronizing Batch Job Execution

The WAIT command is useful for command procedures that must have access
to a shared system resource such as a disk or tape drive. The following
example shows a procedure that requests the allocation of a tape drive; if the
command does not complete successfully, the procedure places itself in a wait
state. After a five-minute interval, it retries the request:
$ TRY:

$
ALLOCATE DM: RK:
$
IF $STATUS THEN GOTO OKAY
$
WAIT 00:05
$
GOTO TRY
$ OKAY:
$ REQUEST/REPLY/TO=DISKS "Please mount BACK_UP_GMB on ''F$TRNLNM("RK")'"

The IF command following the ALLOCATE request checks the value of
$STATUS. If the value of $STATUS indicates successful completion, the
command procedure continues. Otherwise, the procedure executes the WAIT
command; the WAIT command specifies a time interval of five minutes. After
waiting five minutes, the next command, GOTO, is executed, and the request
is repeated. This procedure continues looping and attempting to allocate a
device until it succeeds or until the batch job is deleted or stopped.

8-11

Annotated Command Procedures

This appendix contains complete command procedures that demonstrate the
concepts and techniques discussed in this book. Each section in this appendix
discusses one command procedure and contains the following information:
•

The name of the procedure

•

A listing of the procedure

•

Notes that explain concepts or techniques used by the procedure

•

The results of a sample execution of the procedure

The command procedures are as follows:
CONVERT.COM

Section A.1 contains the sample command procedure CONVERT.COM. This
procedure converts an absolute time (for a time in the future) to a delta time.
Therefore, the procedure determines the time between the current time and
the time that you specify. The procedure illustrates the use of the F$TIME
and F$CVTIME lexical functions and the use of assignment statements to
perform arithmetic calculations and to concatenate symbol values.
REMINDER.COM

Section A.2 contains the sample command procedure REMINDER.COM. This
procedure displays a reminder message on your terminal at a specified time.
The procedure prompts for the time you want the message to be displayed,
and for the text of the message. The procedure uses CONVERT.COM to
convert the time to a delta time. The procedure then spawns a subprocess
that waits until the specified time and displays your reminder message. The
procedure illustrates the use of the F$ENVIRONMENT, F$VERIFY, and
F$GETDVI functions.
DIR.COM

Section A.3 contains the sample command procedure DIR.COM. This
procedure imitates the DCL command DIRECTORY /SIZE=ALL/DATE,
displaying the block size (used and allocated) and creation date of the
specified files. It illustrates use of the F$P ARSE, F$SEARCH, F$FILE_
ATTRIBUTES, and F$FAO lexical functions.
SYS.COM

Section A.4 contains the sample command procedure SYS.COM. This
procedure returns statistics about processes in the current process list. If
the current process has GROUP privilege, the procedure returns statistics for
all processes in the group. If the current process has WORLD privilege, the
procedure returns statistics for all processes on the system. If the current
process has neither GROUP nor WORLD privilege, the procedure returns
statistics for the current process. This procedure illustrates use of the F$PID,
F$EXTRACT, and F$GETJPI lexical functions.

A-1

Annotated Command Procedures

GETPARMS.COM

Section A.5 contains the sample command procedure GETPARMS.COM.
This procedure returns the number of parameters passed to a procedure.
GETPARMS.COM can be called from another procedure to determine how
many parameters were passed to the calling procedure.
EDIT ALL.COM

Section A.6 contains the sample command procedure EDITALL.COM. This
procedure invokes the EDT editor repeatedly to edit a group of files with
the same file type. This procedure illustrates how to use lexical functions to
extract file names from columnar output. It also illustrates a way to redefine
the input stream for a program invoked within a command procedure.
FORTUSER.COM

Section A.7 contains the sample command procedure FORTUSER.COM.
This example of a system-defined login command procedure provides a
controlled terminal environment for an interactive user who creates, compiles,
and executes FORTRAN programs. If a user logs into a captive account
where FORTUSER.COM is listed as the login command procedure, then the
user can execute only the commands accepted by FORTUSER.COM. This
procedure also illustrates using lexical functions to step through an option
table, comparing a user-entered command with a list of valid commands.
LISTER.COM

Section A.8 contains the sample command procedure LISTER.COM. This
procedure prompts for input data, formats the data in columns, and sorts
it into an output file. This procedure illustrates the READ and WRITE
commands, as well as the character substring overlay format of an assignment
statement.
CALC.COM

Section A.9 contains the sample command procedure CALC.COM. This
procedure performs arithmetic calculations and converts the resulting value to
hexadecimal and decimal values.
BATCH.COM

Section A.10 contains the sample command procedure BATCH.COM. This
procedure accepts a command string, a command procedure, or a list of
commands and then executes these commands as a batch job.
COMPILEJILE.COM

Section A.11 contains the sample command procedure COMPILE_FILE.COM.
This procedure compiles, links, and runs a file written in PASCAL or
FORTRAN. It proinpts for a file to process, and determines if the file type
is PAS or FOR. If the file type is not PAS or FOR, or if the file does not exist
in the current default directory, the command procedure outputs appropriate
error messages. This command procedure illustrates the use of the IF-THENELSE language construct.

A-2

Annotated Command Procedures
A.1 CONVERT.COM

A.1

CONVERT.COM
$
$
$
$
$
$

Procedure to convert an absolute time to a delta time.
The delta time is returned as the global symbol WAIT_TIME.
Pi is the time to be converted.
P2 is an optional parameter - SHOW - that causes the
procedure to display WAIT_TIME before exiting

Check for inquiry

$ IF Pi . EQS. "?" . OR. Pi . EQS.

II II

THEN GOTO TELL

$
$

Verify the parameter:

$
$
$

$
$

hours must be less than 24
minutes must be less than 60
time string must contain only hours
and minutes

Change error and message handling to
use message at BADTIME

$ ON WARNING THEN GOTO BADTIME
f.)
$ SAVE_MESSAGE = F$ENVIRONMENT("MESSAGE")
$ SET MESSAGE/NOFACILITY/NOIDENTIFICATION/NOSEVERITY/NOTEXT
$ TEMP = F$CVTIME(Pi)
$ !

$ ! Restore default error handling and message format
$ ON ERROR THEN EXIT
$ SET MESSAGE'SAVE_MESSAGE'
$

$ IF F$LENGTH(Pi) .NE. 5 .OR. F$LOCATE(": II ,Pi) .NE. 2 THEN GOTO BADTIME
$

Get the current time

$ TIME = F$TIME()
$
$
$
$

Extract the hour and minute fields from both the current time
value (TIME) and the future time (Pi)

$ MINUTES = F$CVTIME(TIME, "ABSOLUTE", "MINUTE")
$HOURS= F$CVTIME(TIME, 11 ABSOLUTE 11 , 11 HOUR 11 )
$ FUTURE_MINUTES = F$CVTIME(Pi, "ABSOLUTE", "MINUTEn)
$ FUTURE_HOURS = F$CVTIME(Pi, "ABSOLUTE". "HOUR")
$
$
$
$
$

Current minutes Ct
Current hours
Minutes in future time
Hours in future time

Convert both time values to minutes
Note the implicit string to integer conversion being performed

$ CURRENT_TIME = HOURS*60 + MINUTES
G)
$ FUTURE_TIME = FUTURE_HOURS*60 + FUTURE_MINUTES
$
$
$
$
$

Compute difference between the future time and the current time
(in minutes)

$ MINUTES_TO_WAIT = FUTURE_TIME - CURRENT_TIME
$
$
$
$

If the result is less than 0 the specified time is assumed to be
for the next day; more calculation is required.

$ IF MINUTES_TO_WAIT .LT. 0 THEN C)
MINUTES_TO_WAIT = 24*60 + FUTURE_TIME - CURRENT_TIME

A-3

Annotated Command Procedures
A.1 CONVERT.COM

$
$
$
$

Start looping to determine the value in hours and minutes from
the value expressed all in minutes

$
HOURS_TO_WAIT = 0
$ HOURS_TO_WAIT_LOOP:
C)
$
IF MINUTES_TO_WAIT .LT. 60 THEN GOTO FINISH_COMPUTE
$
MINUTES_TO_WAIT = MINUTES_TO_WAIT - 60
$
HOURS_TO_WAIT = HOURS_TO_WAIT + 1
$
GOTO HOURS_TO_WAIT_LOOP
$ FINISH_COMPUTE:
$ !

$ ! Construct the delta time string in the proper format
$ !

$ WAIT_TIME == F$STRING(HOURS_TO_WAIT)+ 11 • 11 + F$STRING(MINUTES_TO_WAIT)- 4D
+ ":00.00"
$

$ ! Examine the second parameter
$

$ IF P2 .EQS.

"SHOW" THEN SHOW SYMBOL WAIT_TIME

$ !
$ ! Normal exit
$

$EXIT
$ !

$ BADTIME:
48
$ ! Exit taken if first parameter is not formatted correctly
$ ! EXIT command returns but does not display error status
$ !

$ SET MESSAGE'SAVE_MESSAGE'
$WRITE SYS$0UTPUT "Invalid time value: ",Pi,", format must be hh:mm"
$ WRITE SYS$0UTPUT "Hours must be less than 24; minutes must be less than 60"
$ EXIT %X10000000
$ !
$ !

$ TELL:
41)
$ ! Display message and exit if user enters inquiry or enters
$ ! an illegal parameter
$ !

$ TYPE SYS$INPUT
This procedure converts an absolute time value to
a delta time value. The absolute time must be in
the form hh:mm and must indicate a time in the future.
On return, the global symbol WAIT_TIME contains the
converted time value. If you enter the keyword SHOW
as the second parameter, the procedure displays the
resulting value in the output stream. To invoke this
procedure, use the following syntax:
©CONVERT hh:mm [SHOW]
$ EXIT

Notes

A-4

The procedure checks whether the parameter was omitted or whether the
value entered for a parameter is the question mark character (?). In either
case, the procedure branches to the label TELL.

The procedure uses the F$CVTIME function to verify that the time value
is a valid 24-hour clock time; the F$CVTIME returns a warning message if
the input time is not valid. Therefore, the procedure changes the default
ON action to direct control to the label BADTIME if the F$CVTIME
function returns an error.

Annotated Command Procedures
A.1 CONVERT.COM

The procedure uses the F$ENVIRONMENT function to save the current
message setting, and then sets the message format so that no warning
or error messages are displayed. After checking the time values, the
procedure restores the default ON condition and message format.

The procedure checks the format of the parameter. It must be a time
value in the format:
hh:mm

The IF command checks (1) that the length of the entered value is 5
characters and (2) that the third character (offset of 2) is a colon. The
IF command contains the logical OR operator: if either expression is
true (that is, if the length is not 5 or if there is not a colon in the third
character position), the procedure branches to the label BADTIME.

G The F$TIME lexical function places the current time value in the symbol
TIME.

The F$CVTIME function extracts the "minute" and "hour" fields from the
current time (saved in the symbol TIME). Then the F$CVTIME function
extracts the "minute" and "hour" fields from the time you want to convert.

These assignment statements convert the current and future times to
minutes. When you use the symbols MINUTES, HOURS, FUTURE_
HOURS, and FUTURE-MINUTES in the assignment statements, the
system automatically converts these values to integers.

The procedure then subtracts the current time (in minutes) from the future
time (in minutes).

If the result is less than 0, the future time is interpreted as being on the
next day. In this case, the procedure adds 24 hours to the future time,
and then subtracts the current time.

The procedure enters a loop in which it calculates, from the value of
MINUTES_TO_WAIT, the number of hours. Each time through the
loop, it checks whether MINUTES_TO_WAIT is greater than 60. If so, it
subtracts 60 from MINUTES_TO_WAIT and adds 1 to the accumulator
for the number of hours (HOURS_TO_WAIT).

4D When the procedure exits from the loop, it concatenates the hours and
minutes values into a time string. The symbols HOURS_TO_WAIT and
MINUTES_TO_WAIT are replaced by their character string equivalents
and separated with an intervening colon. The resulting string is assigned
to the symbol WAIT_TIME, which holds the delta time value for the
future time. WAIT_TIME is defined as a global symbol so that it is not
deleted when the procedure CONVERT.COM exits.

CD If a second parameter, SHOW, was entered, the procedure displays the
resulting time value. Otherwise, it exits.
~

At the label BADTIME, the procedure displays an error message that
shows the incorrect value entered as well as the format it requires. After
issuing the error message, CONVERT.COM exits. The EXIT command
returns an error status in which the high order digit is set to 1. This
suppresses the display of an error message.
The procedure explicitly specifies an error status with the EXIT command,
so you can execute CONVERT.COM from within another procedure.
When CONVERT.COM completes, the calling procedure can determine
whether a time was successfully translated.

A-5

Annotated Command Procedures
A.1 CONVERT.COM

4» At the label TELL, the procedure displays information about what
the procedure does. The TYPE command displays the lines listed in
SYS$INPUT, the input data stream.
Sample Execution
$ SHOW TIME
10-JUN-1984 10:38:26
$ ©CONVERT 12:00 SHOW
WAIT_TIME = "1:22:00.00"

The SHOW TIME command displays the current date and time.
CONVERT.COM is executed with the parameters 12:00 and SHOW. The
procedure converts the absolute time 12:00 to a delta time value and displays
it on the terminal.

A.2

REMINDER.COM
$
$
$
$
$
$

Procedure to obtain a reminder message and display this
message on your terminal at the time you specify.
Save current states for procedure and image verification
Turn verification off for duration of procedure

$ SAVE_VERIFLIMAGE = F$ENVIRONMENT("VERIFY_IMAGE")
$ SAVE_VERIFY_PROC = F$VERIFY(O)

$
$
$
$
$

Places the current process in a wait state until a specified
absolute time. Then, it rings the bell on the terminal and
displays a message.

Prompt for absolute time

$
$

$ GET_TIME:
$ INQUIRE REMINDER_TIME "Enter time to send reminder (hh:mm)"
$ INQUIRE MESSAGE_TEXT "Enter message"
$ !
$ ! Call the CONVERT.COM procedure to convert the absolute time
$ ! to a delta time
$

$
$

$
$
$
$
$
$
$
$
$

Create a command file that will be executed
in a subprocess. The subprocess will wait until
the specified time and then display your message
at the terminal. If you are working at a DEC_CRT
terminal, the message has double size blinking
characters. Otherwise, the message has normal letters.
In either case, the terminal bell rings when the
message is displayed.

$CREATE WAKEUP.COM
! Lines starting with $ are data lines
$ DECK
$ WAIT 'WAIT_TIME'
@t
$IF F$GETDVI("SYS$0UTPUT","TT_DECCRT") .NES. "TRUE" THEN GOTO OTHER_TERM
$ BELL[0,7] = %X07
! Create symbol to ring the bell

A-6

Annotated Command Procedures
A.2 REMINDER.COM

$ !

$ DEC_CRT_ONLY:
$ Create symbols to set special graphics (for DEC_CRT terminals only)
$
$
$
$
$
$
$
$
$
$
$
$
$

SET_FLASH = "<ESC>[1;5m"
SET_NOFLASH = "<ESC>[Om"
TOP = "<ESC>#3"
BOT = "<ESC>#4"

Turn on blinking characters
Turn off blinking characters
Double size characters (top portion)
Double size characters (bottom portion)

Write double size, blinking message to the terminal and ring the bell
WRITE SYS$0UTPUT BELL, SET_FLASH, TOP, MESSAGE_TEXT
WRITE SYS$0UTPUT BELL, BOT, MESSAGE_TEXT
WRITE SYS$0UTPUT F$TIME(), SET_NOFLASH
GOTO CLEAN_UP

$ OTHER_TERM:
$
WRITE SYS$0UTPUT BELL,MESSAGE_TEXT
$
WRITE SYS$0UTPUT F$TIME()
$ !

$ CLEAN_UP:
$
DELETE WAKEUP.COM;*
$ EDD
$ !

$ ! Now continue executing commands.
$ !

$ SPAWN/NOWAIT/INPUT=WAKEUP.COM ~
$END:
0
$
Restore verification
$
SAVE_VERIFY_PROC = F$VERIFY(SAVE_VERIFY_PROC, SAVE_VERIFY_IMAGE)
$
EXIT
$

$ BADTIME:
$
WRITE SYS$0UTPUT "Time must be entered as hh:mm"
$
GOTO GET_TIME

Notes

The procedure uses the F$ENVIRONMENT function to save the image
verification setting in the symbol SAVE_VERIFY-1MAGE. Next, the
procedure uses the F$VERIFY function to save the procedure verification
setting in the symbol SAVE_VERIFY_PROC. The F$VERIFY function also
turns both types of verification off.

The procedure uses the INQUIRE command to prompt for the time when
the reminder message should be sent. This value is used as input to the
procedure CONVERT.COM. The procedure also prompts for the text of
the message.

The procedure executes a nested procedure, CONVERT.COM. Be sure to
specify the disk and directory as part of the file specification; this ensures
that the system can locate CONVERT.COM regardless of the directory
from which you execute REMINDER.COM.
CONVERT.COM converts your reminder to a delta time, and returns this
time in the global symbol WAIT_TIME. This delta time indicates the time
interval from the current time until the time when the message should be
sent. If CONVERT.COM returns an error, the procedure branches to the
label BADTIME.

A-7

Annotated Command Procedures
A.2 REMINDER.COM

The procedure uses the CREATE command to create a new procedure,
WAKEUP.COM. This procedure is executed from within a subprocess. To
allow the CREATE command to read lines that begin with dollar signs,
use the DECK and EOD commands to surround the input for the CREATE
command. Therefore, all lines between the DECK and EOD commands
are written to WAKEUP.COM.

WAKEUP.COM performs the following tasks:
•

It waits until the time indicated by the symbol WAIT_TIME.

•

It creates the symbol BELL to ring the terminal bell.

•

It determines whether the terminal is a DEC_CRT terminal and can
accept escape sequences to display double size, blinking characters.
(To see whether you have a DEC_CRT terminal, enter the SHOW
TERMINAL command and see whether this characteristic is listed.)

•

If the terminal is a DEC_CRT terminal, then the procedure defines
the symbols SET_FLASH, TOP, and BOT. These symbols cause
the terminal to use flashing, double-size characters. The procedure
also defines the symbol SET_NOFLASH to return the terminal to
its normal state. To enter the escape character ( <ESC> ) when you
create these definitions using the EDT editor, press the ESC key twice.

After defining these symbols, the procedure writes three lines to the
terminal. The first line rings the bell, turns on flashing characters, and
displays (using double size characters) the top half of your message.
The second line rings the bell again, and displays the bottom half of
your message. The third line writes the current time and then turns
off the flash characteristic to return your terminal to normal.
If you do not have a DEC_CRT terminal, then the procedure rings
your terminal bell, and displays your message and the time.

•

The DELETE command causes the procedure WAKEUP.COM to
delete itself after it executes.

After creating WAKEUP.COM, the procedure spawns a subprocess and
directs the subprocess to use WAKEUP.COM as the input command file.
The /NOWAIT qualifier allows you to continue working at your terminal
while the subprocess executes commands from WAKEUP.COM. At the
specified time, WAKEUP.COM displays your message on your terminal.
Note that, by default, the SP AWN command passes global and local
symbols to a subprocess. Therefore, although you provide values for
the symbols WAIT_TIME and MESSAGE_TEXT in REMINDER.COM,
WAKEUP.COM can also access these symbols.

The procedure restores the original verification settings before it exits.

Sample Execution
$ @REMINDER
Enter time ~o send reminder (hh:mm): 12:00
Enter message: TIME FOR LUNCH
%DCL-S-SPAWNED, process BLUT0_1 spawned
$

TIME FOR LUNCH
15-APR-1984 12:00:56.99

A-8

Annotated Command Procedures
A.2 REMINDER.COM

The procedure prompts for a time value and for your message. Then the
procedure spawns a subprocess that displays your message. You can continue
working at your terminal; at the specified time, the subprocess rings the
terminal bell, displays your message, and displays the time.

A.3

DIR.COM
$ !

$ ! Command procedure implementation of DIRECTORY/SIZE=ALL/DATE
$ ! command
$ !

$ SAVE_vERIFY_IMAGE = F$ENVIRONMENT("VERIFLIMAGE")
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(O)
$ !

$ ! Replace any blank field of the P1 file specification with
$ ! a wildcard character
$ !

$ P1 = F$PARSE(P1,"*·*;*")

$ !

$ ! Define initial values for symbols
$ !

$ FIRST_TIME = "TRUE"
$ FILE_COUNT = 0
$ TOTAL_ALLOC = 0
$ TOTAL_USED = 0
$

$ LOOP:
$
$
$
$
$

FILESPEC = F$SEARCH(P1)
Find next file in directory
IF FILESPEC .EQS. "" THEN GOTO DONE
If no more files, then done
IF .NOT. FIRST_TIME THEN GOTO SHOW_FILE
Print header only once

$
$
$
$
$
$
$
$
$
$
$
$

Construct and output the header line
FIRST_TIME = "FALSE"
8
DIRSPEC = F$PARSE(FILESPEC, , , "DEVICE") +F$PARSE(FILESPEC,,, "DIRECTORY")
WRITE SYS$0UTPUT ""
WRITE SYS$0UTPUT "Directory 11 ,DIRSPEC
WRITE SYS$0UTPUT 1111
LASTDIR = DIRSPEC
Put the file name together, get some of the file attributes, and
type the information out

A-9

Annotated Command Procedures
A.3 DIR.COM

$ !

$SHOW_FILE:
$
FILE_COUNT = FILE_COUNT + 1
$
FILENAME= F$PARSE(FILESPEC, ,, "NAME") + F$PARSE(FILESPEC,,, "TYPE") + F$PARSE(FILESPEC,,, "VERSION")
ALLOC = F$FILE_ATTRIBUTES(FILESPEC, "ALQ")
$
USED = F$FILE_ATTRIBUTES(FILESPEC, "EOF")
$
TOTAL_ALLOC = TOTAL_ALLOC + ALLOC
$
TOTAL_USED = TOTAL_USED + USED
$
REVISED= F$FILE_ATTRIBUTES(FILESPEC,"RDT")
$
LINE= F$FA0("!19AS !5UL/!5<!UL!> !17AS",FILENAME,$
USED, ALLOC, REVISED)
WRITE SYS$0UTPUT LINE
$
GOTO LOOP
$
$
$

Output summary information, reset verification, and exit

$DONE:
0
$
WRITE SYS$0UTPUT 1111
$
WRITE SYS$0UTPUT "Total of ''FILE_COUNT' files, "+ "' 'TOTAL_USED' I' 'TOTAL_ALLOC' blocks."
SAVE_VERIFY_PROCEDURE = F$VERIFY(SAVE_VERIFY_PROCEDURE,SAVE_VERIFY_IMAGE)
$
$
EXIT

Notes

A-10

This procedure uses the F$P ARSE function to place asterisks in blank
fields in Pl, the user-supplied file specification. If you do not specify
a parameter when you execute DIR.COM, then the F$PARSE function
assigns the value "*.*;*" to Pl. This causes DIR.COM to display all files
in the current default directory.

The F$SEARCH lexical function searches the directory for the file (or
files) indicated by Pl. If Pl contains any wildcards (asterisks), the
F$SEARCH function returns all matching file specifications. After the last
file specification has been returned, the procedure branches to the label
DONE.

The first time through the loop, the procedure writes a header for the
directory display. This header includes the device and directory names.
To obtain these names, the procedure uses the F$PARSE function.

The procedure uses the F$PARSE lexical function to extract the file name
from each file specification in the directory. The F$FILE_ATTRIBUTES
lexical function then obtains blocks used, blocks allocated, and creation
date information about each file. Finally, the F$FAO function formats a
single display line for each file in the directory. The F$FAO function uses
the file name and file attribute information as arguments.

When F$SEARCH returns a null string, the procedure branches to the
label DONE and displays summary information showing the total number
of files, the total number of blocks used, and the total number of blocks
allocated in the directory.

Annotated Command Procedures
A.3 DIR.COM

Directory DISK4: [VERN]
BATCH.COM;1
CALC.COM;3
CONVERT.COM;1

1/3
1/3
5/6

16-JUN-1984 11:43
16-JUN-1984 11:30
16-JUN-1984 15:23

2/3
1/3
1/3

16-JUN-1984 13:17
16-JUN-1984 09:49
16-JUN-1984 11:29)

Total of 15 files, 22/48 blocks.

The procedure returns information on all COM files in the directory [VERN].

A.4

SYS.COM
$ !

$ ! Displays information about owner, group, or system processes.
$ !

$ ! Turn off verification and save current settings
$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE")
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(O)
$ CONTEXT = ""
! Initialize PIO search context

$ !

$ ! Output header line.
$ !

$ WRITE SYS$0UTPUT " PIO
Username
"name State Pri Image"

Term

Process " + -

$ !

$ ! Output process information.
$ !

$LOOP:
$

$
$
$
$
$
$
$
$
$
$
$
$
$
$
$
$

Get next PIO.

If null, then done.

PIO = F$PID(CONTEXT)
C)
IF PIO .EQS. "" THEN GOTO DONE
Get image file specification and extract the file name.
IMAGNAME = F$GETJPI(PID, 11 IMAGNAME 11 )
0
IMAGNAME = F$PARSE(IMAGNAME,, , 11 NAME 11 , 11 SYNTAX_ONLY")
Get terminal name.

If none, then describe type of process.

TERMINAL= F$GETJPI(PID, 11 TERMINAL 11 )
IF TERMINAL .EQS. "" THEN TERMINAL= 11 - 11 +F$EXTRACT(0,3,F$GETJPI(PID, 11 MODE 11 ))+ 11 - 11
IF TERMINAL .EQS. 11 -INT- 11 THEN TERMINAL = 11 -DET- 11
IF F$GETJPI(PI0,"0WNER") .NE. 0 THEN TERMINAL= "-SUB-"

A-11

Annotated Command Procedures
A.4 SYS.COM

$
$
$
$
$

Get some more information, put process line together,
and output it.

LINE= F$FA0( 11 !AS !12AS !7AS !15AS !5AS !2UL/!UL !10AS 11 , PID,F$GETJPI(PID, 11 USERNAME 11 ),TERMINAL,F$GETJPI(PID,11PRCNAM11) ,F$GETJPI(PID,11STATE11) ,F$GETJPI(PID,11PRI11) ,F$GET JP I (PIO' II PRIB II) ' IMAGNAME)
WRITE SYS$0UTPUT LINE
GOTO LOOP
Restore verification and exit.

$DONE:
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(SAVE_VERIFY_PROCEDURE,SAVE_VERIFY_IMAGE)
$ EXIT

Notes

A-12

The symbol CONTEXT is initialized with a null value. This symbol will
be used with the F$PID function to obtain a list of process identification
numbers.

The procedure writes a header for the display.

The procedure gets the first process identification (PID) number. If
the current process lacks GROUP or WORLD privilege, the PID of the
current process is returned. If the current process has GROUP privilege,
the first PID in the group list is returned. The first PID in the system
list is returned if the current process has WORLD privilege. The function
continues to return the next PID in sequence until the last PID is returned.
At this point, a null string is returned, and the procedure branches to the
end.

The procedure uses the F$GETJPI lexical function to get the image file
specification for each PID. The F$P ARSE function extracts the file name
from the specification returned by the F$GETJPI function.

The procedure uses the F$GETJPI function to get the terminal name for
each PID. The F$EXTRACT function extracts the first three characters of
the MODE specification returned by F$GETJPI(PID,"MODE") to determine
the type of process. The F$GETJPI function is used again to determine
whether the process is a subprocess.

The procedure uses the F$GETJPI lexical function to get the user name,
process name, process state, process priority, and process base priority for
each PID returned. The F$FAO lexical function formats this information
into a screen display.

Annotated Command Procedures
A.4 SYS.COM

00050011
00040013
00140015
00080016
00070017

Username
NETNONPRIV
STOVE
MAROT
THOMPSON
JUHLES

00040018 MARCO
0018001A VERN
0033001B YISHA
0002004A SYSTEM

Term
-NETRTA6:
-DET-DETTTF1:

Process name
MAIL_14411
STOVE
DMFBOACP
MTAOACP
JUHLES

TTA2:
RTA3:
RTA7:
-DET-

MARCO
VERN
YI SHA
ERRFMT

State
LEF
LEF
HIB
HIB
LEF

Pri Image
9/4 MAIL
9/4
9/8 F11BAC
12/8 MTAAACP
9/4

HIB
LEF
CUR
HIB

9/4 RTPAD
9/4
4/4
12/7 ERRFMT

This procedure returns information on all processes on the system. The
current process has WORLD privilege.

A.5

GETPARMS.COM
$ ! Procedure to count the number of parameters passed to a command
$ ! procedure. This number is returned as the global symbol PARMCOUNT.
$ !
$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT( 11 VERIFY_IMAGE 11 )
0
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(O)
$

$ IF P1 . EQS.
$
$
$
$
$
$

? 11

THEN GOTO TELL

8 .

Loop to count the number of parameters passed. Null parameters are
counted until the last non-null parameter is passed.
COUNT = 0
LASTNONNULL = 0

$ LOOP:
$
IF COUNT .EQ. 8 THEN GOTO END_COUNT
$
COUNT = COUNT + 1
$
IF P'COUNT' .NES. 1111 THEN LASTNONNULL = COUNT
$ GOTO LOOP
$ !

$ END_COUNT:

$ ! Place the number of non-null parameters passed into PARMCOUNT.
$ !

$ PARMCOUNT == LASTNONNULL
$ !

$ ! Restore verification setting, if it was on, before exiting
$ !
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(SAVE_VERIFY_PROCEDURE,SAVE_VERIFY_IMAGE) CD
$ EXIT
$ !

$ TELL:
0
$ TYPE SYS$INPUT
This procedure counts the number of parameters passed to
another procedure.
This procedure can be called by entering
the string:

A-13

Annotated Command Procedures
A.5 GETPARMS.COM

@GETPARMS 'Pl 'P2 'P3 'P4 'P5 'P6 'P7 'P8
in any procedure. On return, the global symbol PARMCOUNT
contains the number of parameters passed to the procedure.
$ !

$ EXIT

Notes

The procedure saves the current image and procedure verification settings
before setting verification off.

If a question mark character was passed to the procedure as a parameter,
the procedure branches to the label TELL (Note 6).

A loop is established to count the number of parameters that were
passed to the procedure. The counters COUNT and LASTNONNULL
are initialized to 0 before entering the loop. Within the loop, COUNT is
incremented and tested against the value 8. If COUNT is equal to 8, the
maximum number of parameters has been entered. Each time a non-null
parameter is passed, LASTNONNULL is equated to that parameter's
number.
Each time the IF command executes, the symbol COUNT has a different
value. The first time, the value of COUNT is 1 and the IF command
checks Pl. The second time, it checks P2, and so on.

When the parameter count reaches 8, the procedure branches to END_
COUNT. The symbol LASTNONNULL contains the count of the last
non-null parameter passed. This value is placed in the global symbol
PARM COUNT. PARM COUNT must be defined as a global symbol so
that its value can be tested at the calling command level.

The original verification settings are restored.

At the label TELL, the TYPE command displays data that is included
in the input stream. (In command procedures, the input stream is the
command procedure file.) The TYPE command displays instructions on
how to use GETPARMS.COM.

Sample Execution

The procedure SORTFILES.COM requires the user to pass three non-null
parameters. The SORTFILES.COM procedure can contain the following lines:
$ ©GETPARMS 'Pl' 'P2' 'P3' 'P4' 'P5' 'P6' 'P7' 'P8'
$ IF PARMCOUNT .NE. 3 THEN GOTO NOT_ENOUGH

$NOT_ENOUGH:
$ WRITE SYS$0UTPUT "Three non-null parameters required.
$ EXIT

Type SORTFILES HELP for info."

The procedure SORTFILES.COM can be invoked as follows:
$ ©SORTFILES DEF 4
Three non-null parameters required. Type SORTFILE HELP for info.

A-14

Annotated Command Procedures
A.5 GETPARMS.COM

In the previous example, the procedure SORTFILES.COM defines the symbol
GETP ARMS as a synonym for @GETP ARMS and its parameters. For this
procedure to be properly invoked, that is, for the parameters that are passed
to SORTFILES to be passed to GETP ARMS intact for processing, the synonym
must be preceded with an apostrophe.
If the return value from GETP ARMS is not 3, SORTFILES outputs an error
message and exits.

A.6

EDITALL.COM
$ ! Procedure to edit all files in a directory with a
$ ! specified file type. Use P1 to indicate the file type.
$ !

$ ON CONTROL_Y THEN GOTO DONE
$ ON ERROR THEN GOTO DONE

! CTRL/Y action

$ ! Check for file type parameter. If one was entered, continue;
$ ! otherwise, prompt for a parameter.
$ !

$ IF P1 . NES. "" THEN GOTO OKAY
@
$ INQUIRE P1 "Enter file type of files to edit"
$ !

$ ! List all files with the specified file type and write the DIRECTORY
$ ! output to a file named DIRECT.OUT
$ !
$ OKAY:
$ DIRECTORY/VERSIONS=1/COLUMNS=1 .,
/NODATE/NOSIZE /NOHEADING/NOTRAILING /OUTPUT=DIRECT.OUT *· 'P1'
$ IF .NOT. $STATUS THEN GOTO ERROR_SEC
C»

$ !

$ OPEN/READ/ERROR=ERROR_SEC DIRFILE DIRECT.OUT

$ !
$ ! Loop to read directory file
$ !

$ NEWLINE:
0
$
READ/END=DONE DIRFILE NAME
$
DEFINE/USER_MODE SYS$INPUT SYS$COMMAND:
$
EDIT 'NAME'
$
GOTO NEWLINE

Redefine SYS$INPUT
Edit the file

$ DONE:
0
$
CLOSE DIRFILE/ERROR=NOTOPEN
$ NOTOPEN:
$
DELETE DIRECT.OUT;*
$ EXIT

Close the file
Delete temp file

$ !

$ ERROR_SEC:
$
WRITE SYS$0UTPUT "Error:
$
DELETE DIRECT.OUT;*
$ EXIT

,F$MESSAGE($STATUS)

A-15

Annotated Command Procedures
A.6 EDITALL.COM

Notes

ON commands establish condition handling for this procedure. If
CTRL/Y is pressed at any time during the execution of this procedure, the
procedure branches to the label DONE. Similarly, if any error or severe
error occurs, the procedure branches to the label DONE.

The procedure checks whether a parameter was entered. If not, the
procedure prompts for a file type.

The DIRECTORY command lists all files with the file type specified
as Pl. The command output is written to the file DIRECT.OUT. The
/VERSIONS=l qualifier requests that only the highest numbered version
of each file be listed. The /NOHEADING and /NOTRAILING qualifiers
request that no heading lines or directory summaries be included in the
output. The /COLUMNS=l qualifier ensures that one file name per
record is given.

e The IF command checks the return value from the DIRECTORY command
by testing the value of $STATUS. If the DIRECTORY command does not
complete successfully, then $STATUS has an even integer value, and the
procedure branches to the label ERROR_SEC.

The OPEN command opens the directory output file and gives it a logical
name of DIRFILE.

The READ command reads a line from the DIRECTORY command output
into the symbol name NAME. After it reads each line, the procedure uses
the DEFINE command to redefine the input stream for the edit session
(SYS$INPUT) to be the terminal. Then, it invokes the editor, specifying
the symbol NAME as the file specification. When the edit session is
completed, the command interpreter reads the next line in the command
procedure and branches to the label NEWLINE. When the procedure has
edited all files of the specified file type in the directory, it branches to the
label DONE.

The label DONE is the target label for the /END qualifier on the READ
command and the target label for the ON CONTROL_Y and ON ERROR
conditions set at the beginning of the procedure. At this label, the
procedure performs the necessary cleanup operations.
The CLOSE command closes the DIRECTORY command output file; the
/ERROR qualifier specifies the label on the next line in the file. This use
of /ERROR suppresses any error message that would be displayed if the
directory file is not open. For example, this would occur if CTRL/Y were
pressed before the directory file were opened.
The second step in cleanup is to delete the temporary directory file.

*
%DELETE-I-FILDEL, device: [directory]DIRECT.OUT;1 deleted (x blocks)

The procedure EDITALL is invoked with Pl specified as DAT. The procedure
creates a directory listing of all files in the default directory whose file types
are DAT and invokes the editor to edit each one. After you finish editing
the last file with the file type dat, the procedure deletes the temporary file
DIRECT.OUT and displays an informational message at your terminal.

A-16

Annotated Command Procedures
A. 7 FORTUSER.COM

A.7

FORTUSER.COM
$ ! Procedure to create, compile, link, execute, and debug
$ ! FORTRAN programs. Users can enter only the commands listed
$ ! in the symbol OPTION_TABLE.
$ SET NOCONTROL=Y .,
$ SAVE_vERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE")
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(O)
$ OPTION_TABLE = "EDIT/COMPILE/LINK/RUN/EXECUTE/DEBUG/PRINT/HELP/FILE/DONE/"
$ TYPE SYS$INPUT C)

VMS FORTRAN Command Interpreter
Enter name of file with which you would like to work.
$

$ ! Set up for initial prompt
$ !

$ PROMPT = "!NIT"
$ GOTO HELP

8
! Print the initial help message

$ ! after the first prompting message, use the prompt: Command
$

$ !NIT:
$ PROMPT = 11 GET_COMMAND 11
$ GOTO FILE
$
$
$
$
$

Get initial file name

Main command parsing routine. The routine compares the current
command against the options in the option table. When it finds
a match, it branches to the appropriate label.

$ GET_COMMAND:
$
ON CONTROL_Y THEN GOTO GET_COMMAND
CTRL/Y resets prompt Ct
$
SET CONTROL=Y
If any, reset prompt
$
ON WARNING THEN GOTO GET_COMMAND
$
INQUIRE COMMAND "Command"
$
IF COMMAND .EQS. "" THEN GOTO GET_COMMAND
$
IF F$LOCATE(COMMAND + "/", OPTION_TABLE) .EQ. F$LENGTH(OPTION_TABLE) - 0
THEN GOTO INVALID_COMMAND
GOTO 'COMMAND'
$
$

$ INVALID_COMMAND: f)
$
WRITE SYS$0UTPUT " Invalid command"
$

$ HELP: 0
$
TYPE SYS$INPUT
The commands you can enter are:
FILE
Name of FORTRAN program in your current
default directory. Subsequent commands
process this file.
EDIT
Edit the program.
COMPILE Compile the program with VAX FORTRAN.
LINK
Link the program to produce an executable image.
Run the program's executable image.
RUN
EXECUTE Same function as COMPILE, LINK, and RUN.
Run the program under control of the debugger.
DEBUG
Queue the most recent listing file for printing.
PRINT
Return to interactive command level.
DONE
HELP
Print this help message.
Enter CTRL/Y to restart this session

A-17

Annotated Command Procedures
A. 7 FORTUSER.COM

$ GOTO 'PROMPT'
C)
$EDIT:
~
$
DEFINE/USER_MODE SYS$INPUT SYS$COMMAND:
$
EDIT 'FILE_NAME'.FOR
$
GOTO GET_COMMAND
$ COMPILE:
$
FORTRAN 'FILE_NAME'/LIST/OBJECT/DEBUG
$
GOTO GET_COMMAND
$ LINK:
LINK 'FILE_NAME'/DEBUG
$
PURGE 'FILE_NAME'.*/KEEP=2
$
GOTO GET_COMMAND
$
$ RUN:
$
DEFINE/USER_MODE SYS$INPUT SYS$COMMAND:
$
RUN/NODEBUG 'FILE_NAME'
$
GOTO GET_COMMAND
$ DEBUG:
$
DEFINE/USER_MODE SYS$INPUT SYS$COMMAND:
$
RUN 'FILE_NAME'
$
GOTO GET_COMMAND
$ EXECUTE:
$
FORTRAN 'FILE_NAME'/LIST/OBJECT
$
LINK/DEBUG 'FILE_NAME'
$
PURGE 'FILE_NAME' .*/KEEP=2
$
RUN/NODEBUG 'FILE_NAME'
$
GOTO GET_COMMAND
$ PRINT:
$
PRINT 'FILE_NAME'
$
GOTO GET_COMMAND
$ BADFILE: ~
$
WRITE SYS$0UTPUT "File must be in current default directory."
$ FILE:
INQUIRE FILE_NAME "File name"
$
IF FILE_NAME . EQS . "" THEN GOTO FILE
$
IF F$PARSE(FILE_NAME,, ,"DIRECTORY") .NES. F$DIRECTORY() - Q)
$
THEN GOTO BADFILE
FILE_NAME = F$PARSE(FILE_NAME,,, "NAME")
$
GOTO GET_COMMAND
$
$ DONE:
$ EXIT

Notes

A-18

The SET NOCONTROL=Y command ensures that the user who logs in
under the control of this procedure cannot interrupt the procedure or any
command or program in it.

f.)

The option table lists the commands that the user will be allowed to
execute. Each command is separated by a slash.

The procedure introduces itself.

The symbol name PROMPT is given the value of a label in the procedure.
When the procedure is initially invoked, this symbol has the value
INIT. The HELP command text terminates with a GOTO command that
specifies the label PROMPT. When this text is displayed for the first time,
the GOTO command results in a branch to the label HELP. This displays
the HELP message that explains the commands that you can enter.
Then, the procedure branches back to the label INIT, where the value
for PROMPT is changed to "GET_COMMAND." Finally, the procedure
branches to the label FILE to get a file name. Thereafter, when the help

Annotated Command Procedures
A. 7 FORTUSER.COM

text is displayed, the procedure branches to the label GET_COMMAND
to get the next command.

The CTRL/Y condition action is set to return to the label GET_
COMMAND, as is the warning condition action. The procedure prompts
for a command and continues to prompt, even if nothing is entered. To
terminate the session and return to interactive command level, enter the
command DONE.

The procedure uses the F$LOCATE and F$LENGTH lexical functions
to determine whether command is included in the list of options. The
F$LOCATE function searches for the user-entered command, followed by
a slash. (For example, if you enter EDIT, the procedure searches for EDIT
/.) If the command is not included in the option list, then the procedure
branches to the label INVALID_COMMAND. If the command is valid,
the procedure branches to the appropriate label.

At the label INVALID_COMMAND, the procedure writes an error
message and displays the help text that lists the commands that are valid.

The help text lists the commands that are valid. This text is displayed
initially. It is also displayed whenever the user enters the HELP
command or any invalid command.

C> At the conclusion of the HELP text, the GOTO command specifies the
symbol name PROMPT. When this procedure is first invoked, the symbol
has the value INIT. Thereafter, it has the value GET_COMMAND.
4m>

Each valid command in the list has a corresponding entry in the option
table and a corresponding label in the command procedure. For the
commands that read input from the terminal, for example, EDIT, the
procedure contains a DEFINE command that defines the input stream as
SYS$COMMAND.

4D At the label BADFILE, the procedure displays a message indicating that
the file must be in the current directory. Then the procedure prompts for
another file name.

4D After obtaining a file name, the procedure checks that you have not
specified a directory that is different from your current default directory.
The procedure then uses the F$PARSE function to extract the file name.
(Each command supplies the appropriate default file type.) Next,
the procedure branches back to the label GET_COMMAND to get a
command to process the file.
Sample Execution

This example illustrates how to use this command procedure as a captive
command procedure.
Username: CLASS30
Password:
VMS Version 5.0
VMS FORTRAN Command Interpreter
Enter name of file with which you would like to work.
The commands you can enter are:

A-19

Annotated Command Procedures
A. 7 FORTUSER.COM

FILE
EDIT
COMPILE
LINK
RUN
EXECUTE
DEBUG
PRINT
DONE
HELP

Name of FORTRAN program in your current
default directory. Subsequent commands
process this file.
Edit the program.
Compile the program with VAX FORTRAN.
Link the program to produce an executable image.
Run the program's executable image.
Same function as COMPILE, LINK and RUN.
Run the program under control of the debugger.
Queue the most recent listing file for printing.
Return to interactive command level.
Print this help message.

Enter CTRL/Y to restart this session
File name: AVERAGE
Command: COMPILE
Command: LINK
Command: RUN
Command: FILE
File name: READFILE
Command: EDIT

This sample execution illustrates a session in which a user named CLASS30
logs in to the account controlled by the FORTUSER command procedure. The
FORTUSER command procedure displays the commands the user is allowed
to execute, as well as an instruction for restarting the session. Next, the user
specifies the file AVERAGE, compiles, links, and runs it. Then, the user enters
the FILE command to begin working on another file.

A.8

LISTER.COM
$
$
$
$
$

Procedure to accumulate programmer names and document
file names. After all names and files are entered, they are
sorted in alphabetic order by programmer name and printed on
the system printer.

$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE")
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(O)

$ !

$ OPEN/WRITE OUTFILE DATA.TMP

! Create output file

$ !

$ ! Loop to obtain programmers' last names and file names,
$ ! and write this data to DATA.TMP.
$ !
$ LOOP:
0
$
INQUIRE NAME "Programmer (press RET to quit)"
$
IF NAME .EQS. "" THEN GOTO FINISHED
$
INQUIRE FILE "Document file name"
$
RECORD[0,20] :='NAME'
~
$
RECORD[21,20] :='FILE'
$
WRITE OUTFILE RECORD
$
GOTO LOOP
$ FINISHED:
$
CLOSE OUTFILE

A-20

Annotated Command Procedures
A.8 LISTER.COM

$ !

$ DEFINE/USER_MODE SYS$0UTPUT: NL:
! Suppress sort output
$ SORT/KEY=(POSITION:1,SIZE=20) DATA.TMP DOC.SRT 0
$ !

$ OPEN/WRITE OUTFILE DOCUMENT.DAT
0
$ WRITE OUTFILE "Programmer Files as of ",F$TIME()
$ WRITE OUTFILE ""
$ RECORD[0,20] :="Programmer Name"
$ RECORD[21,20] :="File Name"
$ WRITE OUTFILE RECORD
$ WRITE OUTFILE ""
$ !

$ CLOSE OUTFILE 8
$APPEND DOC.SRT DOCUMENT.DAT
$PRINT DOCUMENT.DAT
$ !

$ INQUIRE/CLEAN_UP "Delete temporary files [Y,N]"
CS)
$ IF CLEAN_UP THEN DELETE DATA.TMP;*,DOC.SRT;*
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(SAVE_VERIFY_PROCEDURE,SAVE_VERIFY_IMAGE)
$EXIT

Notes

0 LISTER.COM saves the current verification setting and sets verification
off.

The OPEN command opens a temporary file for writing.

INQUIRE commands prompt for a programmer name and for a file
name. If a null line, signaled by RETURN, is entered in response to the
INQUIRE command prompt, the procedure assumes that no more data is
to be entered and branches to the label FINISHED.

After assigning values to the symbols NAME and FILE, the procedure
uses the character string overlay format of an assignment statement
to construct a value for the symbol RECORD. In columns 1 through
21 of RECORD, the current value of NAME is written. The command
interpreter pads the value of NAME with spaces to fill the 20-character
length specified.
Similarly, the next 20 columns of RECORD are filled with the value of
FILE. Then, the value of RECORD is written to the output file.

After the file has been closed, the procedure sorts the output file
DATA.TMP. The DEFINE command directs the SORT command output
to the null file NL. Otherwise, these statistics would be displayed on the
terminal.
The sort is performed on the first 20 columns, that is, by programmer
name.
The sorted output file has the name DOC.SRT.

The procedure creates the final output file, DOCUMENT.DAT, with the
OPEN command. The first lines written to the file are header lines, giving
a title, the date and time of day, and headings for the columns.

The procedure closes the file DOCUMENT.DAT and appends the sorted
output file, DOC.SRT, to it. Then, the output file is queued to the system
printer.

A-21

Annotated Command Procedures
A.8 LISTER.COM

Last, the procedure prompts to determine whether to delete the
intermediate files. If a true response (T, t, Y, or y) is entered to the
INQUIRE command prompt, the files DATA.TMP and DOC.SRT are
deleted. Otherwise, they are retained.

Sample Execution
$ @LISTER
Programmer: WATERS
Document file name: CRYSTAL.CAV
Programmer: JENKINS
Document file name: MARIGOLD.DAT
Programmer: MASON
Document file name: SYSTEM.SRC
Programmer: ANDERSON
Document file name: JUNK.J
Programmer: ~
Delete temporary files [Y,N] :y

The output file resulting from this execution of the procedure is as follows:
Programmer Files as of 31-DEC-1989 16:18:58.79

A.9

Programmer Name

File Name

ANDERSON
JENKINS
MASON
WATERS

JUNK.J
MARIGOLD.DAT
SYSTEM.SRC
CRYSTAL.CAV

CALC.COM
$
$
$
$
$
$
$
$

$
$
$

Procedure to calculate expressions. If you enter an
assignment statement, then CALC.COM evaluates the expression
and assigns the result to the symbol you specify. In the next
iteration, you can use either your symbol or the symbol Q to
represent the current result.
If you enter an expression, then CALC.COM evaluates the
expression and assigns the result to the symbol Q. In
the next iteration, you can use the symbol Q to represent
the current result.

$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT( 11 VERIFY_IMAGE 11 )
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(O)
$ START:
$
ON WARNING THEN GOTO START «t
$
INQUIRE STRING "Cale"
@
$
IF STRING .EQS. 1111 THEN GOTO CLEAN_UP
$
IF F$LOCATE( 11 =11 ,STRING) .EQ. F$LENGTH(STRING) THEN GOTO EXPRESSION
$

$ ! Execute if string is in the form symbol = expression
$ STATEMENT:
C)
'STRING' ! Execute assignment statements
$
SYMBOL= F$EXTRACT(O,F$LOCATE( 11 =11 ,STRING)-1,STRING)
get symbol name
$
Q = 'SYMBOL'
! Set up q for future iterations
$
LINE= F$FA0( 11 Decimal = !SL
Hex= !-!XL
Octal= !-!OL 11 ,Q)
$
WRITE SYS$0UTPUT LINE
$
GOTO START
$
$

A-22

Annotated Command Procedures
A.9 CALC.COM

$ !

$ ! Execute if string is an expression
$ EXPRESSION:
0
$
Q = F$INTEGER('STRING')
$
LINE= F$FAO("Decimal = !SL
$
WRITE SYS$0UTPUT LINE
$
GOTO START

Can use Q in next iteration
Hex= !-!XL
Octal = !-!OL",Q)

$ CLEAN_UP:
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(SAVE_VERIFY_PROCEDURE,SAVE_VERIFY_IMAGE)
$ EXIT

Notes

The procedure establishes an error handling condition that restarts
the procedure. If a warning or an error of greater severity occurs, the
procedure will branch to the beginning where it resets the ON condition.
This technique ensures that the procedure will not exit if the user enters
an expression incorrectly.

The INQUIRE command prompts for an arithmetic expression. The
procedure accepts expressions in either of the following formats:
name = expression
expression

If you press RETURN, the procedure assumes the end of a CALC session
and exits.
If you enter input in the format "name= expression" then the procedure
continues executing at the label STATEMENT. Otherwise, the procedure
branches to the label EXPRESSION.

The procedure executes the assignment statement and assigns the result
of the expression to the symbol. Then the procedure extracts the symbol
name, and assigns the value of the symbol to Q. This allows you to use
either Q or your symbol during the next iteration of the procedure. Next,
the procedure displays the result and then branches back to the label
START.

The procedure evaluates the expression and assigns the result to the
symbol Q. This allows you to use Q during the next iteration of the
procedure. Next, the procedure displays the result and then branches
back to the label START.

Sample Execution
$ ©CALC
Cale: 2 * 30
Decimal = 60
Hex = 0000003C Octal = 00000000074
Cale: Q + 3
Decimal = 63
Hex = 0000003F Octal = 00000000077
Cale: TOTAL = Q + 4
Decimal = 67
Hex = 00000043 Octal = 00000000103
Cale: 5 + ?
Decimal = 12
Hex = OOOOOOOC Octal = 00000000014
Cale:~

A-23

Annotated Command Procedures
A.9 CALC.COM

After each prompt from the procedure, the user enters an arithmetic
expression. The procedure displays the results in decimal, hexadecimal,
and octal. A null line, signaled by pressing RETURN on a line with no data,
concludes the CALC session.

A.10

BATCH.COM
$ VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE")

$ VERIFY_PROCEDURE = F$VER1FY(O)
$!
$! Turn off verification and save current settings.
$! (This comment must appear after you turn verification
$! off; otherwise it will appear in the batch job log file.)
$!
$!
$! If this is being executed as a batch job,
$! (from the SUBMIT section below) go to the EXECUTE_BATCH_JOB section
$! Otherwise, get the information you need to prepare to execute the
$! batch job.
$!
$ IF F$MODE() . EQS. "BATCH" THEN GOTO EXECUTE_BATCH_JOB
0
$!
$!
$! Prepare to submit a command (or a command procedure) as a batch job.
$! First, determine a mnemonic process name for the batch job. Use the
$! following rules:
$!
$! 1) If the user is executing a single command, then use the verb name.
$!
Strip off any qualifiers that were included with the command.
$! 2) If the user is executing a command procedure, then use the file name.
$! 3) Otherwise, use BATCH.
$!
$ JOB_NAME = P1
fJ
$ IF JOB_NAME .EQS. "" THEN JOB_NAME = "BATCH"
$IF F$EXTRACT(0,1,JOB_NAME) .EQS. "@" THEN JOB_NAME = F$EXTRACT(1,999,JOB_NAME)
$ JOB_NAME = F$EXTRACT(O,F$LOCATE( 11 / 11 ,JOB_NAME),JOB_NAME)
$ JOB_NAME = F$PARSE(JOB_NAME,,, "NAME", "SYNTAX_ONLY")
$ IF JOB_NAME .EQS. "" THEN JOB_NAME = "BATCH"
$!
$!
$! Get the current default device and directory.
$!
$ ORIGDIR = F$ENVIRONMENT( 11 DEFAULT 11 )
$!
$!
$! Concatenate the parameters to form the command string to be executed.
$! If the user did not enter a command string, the symbol COMMAND will have
$ ! a null value.
$!
$ COMMAND = P1 + II II + P2 + II II + P3 + II II + P4 + II II + P5 + II II + P6 + II II + P7 + II II + PB
$!
$!
$! If the user is executing a single command and if both the command and the
$! original directory specification are small enough to be passed as
$! parameters to the SUBMIT command, then submit the batch job now
$!
$ IF (P1 .NES. '"') .AND. (F$LENGTH(COMMAND) .LE. 255) .AND. 0
(F$LENGTH(ORIGDIR) .LE. 255) THEN GOTO SUBMIT
$!

A-24

Annotated Command Procedures
A.10 BATCH.COM

$!
$! If the single command to be executed in the batch job is very large, or
$! if you have to prompt for commands to execute in the batch job, then
$! create a temporary command procedure to hold those commands and get the
$! fully expanded name of the command procedure.
$!
$ CREATE_TEMP_FILE:
$ ON CONTROL_Y THEN GOTO CONTROL_Y_HANDLER C)
$ OPEN/WRITE/ERROR=FILE_OPEN_ERROR TEMPFILE SYS$SCRATCH:'JOB_NAME' .TMP (D
$ FILESPEC = F$SEARCH("SYS$SCRATCH:" + JOB_NAME + ".TMP")
$!
$! By default, have the batch job continue if it encounters any errors.
$!
$ WRITE TEMPFILE "$ SET NOON"
$!
$! Either write the single large command to the file, or prompt for
$! multiple commands and write them to the file.
$!
II THEN GOTO WRITE_LARGE_COMMAND
$ IF COMMAND .NES. II
$
$
$
$
$
$
$

LOOP:
READ /END_OF_FILE=CLOSE_FILE /PROMPT="Command:
IF COMMAND .EQS. 1111 THEN GOTO CLOSE_FILE
WRITE TEMPFILE 11 $ ",COMMAND
GOTO LOOP

SYS$COMMAND COMMAND

$ WRITE_LARGE_COMMAND:
WRITE TEMPFILE "$",COMMAND

$
$

$!
$! Finish the temporary file by defining a symbol so that you will know
$! the name of the command procedure to delete and then close the file.
$! Define the symbol COMMAND to mean "execute the command procedure
$! you have just created". Then submit the batch job and execute
$! this command procedure in the batch job.
$!
$ CLOSE_FILE:
8
111111
$ WRITE TEMPFILE "$ BATCH$DELETE_FILESPEC
,FILESPEC, 11111111
$
CLOSE TEMPFILE
$ ON CONTROL_Y THEN EXIT
$ COMMAND = "©" + FILESPEC
$!
$!
$! Submit BATCH.COM as a batch job, and pass it two parameters.
$! P1 is the command (or name of the command procedure) to execute.
$! P2 is the directory from which to execute the command.
$!
$ SUBMIT:
0
$ SUBMIT/NOTIFY/NOPRINT 'F$ENVIRONMENT("PROCEDURE")' /NAME='JOB_NAME' /PARAMETERS=("''COMMAND'"."''ORIGDIR'")
GOTO EXIT
$
$!
$!
$! The user pressed CTRL/Y while the temporary command procedure was open.
$! Close the command procedure, delete it if it exists, and exit.
$!

A-25

Annotated Command Procedures
A.10 BATCH.COM

$ CONTROL_Y_HANDLER:
C)
$ CLOSE TEMPFILE
$ IF F$TYPE(FILESPEC) .NES. "" THEN DELETE/NOLOG 'FILESPEC'
$ WRITE SYS$0UTPUT "CTRL/Y caused the command procedure to abort."
$ GOTO EXIT
$!
$!
$! The temporary command procedure could not be created.
$! Notify the user and exit.
$!
$ FILE_OPEN_ERROR:
4D
$ WRITE SYS$0UTPUT "Could not create sys$scratch: 11 ,job_name, 11 .tmp"
$ WRITE SYS$0UTPUT "Please correct the situation and try again."
$!
$!
$! Restore the verification states and exit.
$!
$EXIT:
•
$ VERIFY_PROCEDURE = F$VERIFY(VERIFY_PROCEDURE,VERIFY_IMAGE)
$ EXIT
$!
$!
$! BATCH.COM was invoked as a batch job. Pi contains the command
$! to execute and P2 the default directory specification.
$! Return a status code that indicates the termination status of Pi.
$!
$ EXECUTE_BATCH_JOB:
~
$
SET NOON
$
VERIFY_PROCEDURE = F$VERIFY(VERIFY_PROCEDURE,VERIFY_IMAGE)
$
SET DEFAULT 'P2'
$
'Pi'
$
IF F$TYPE(BATCH$DELETE_FILESPEC) .EQS. "" THEN EXIT $STATUS
$
STATUS = $STATUS
$
DELETE /NOLOG 'BATCH$DELETE_FILESPEC'
$
EXIT STATUS

Notes

A-26

This IF statement tests whether BATCH.COM is executing in batch mode.
When you invoke BATCH.COM interactively, you provide (as parameters)
a command string or a command procedure that is to be executed as a
batch job. If you do not supply any parameters, then BATCH.COM
prompts you for commands, writes these commands to a file, and then
executes this command procedure as a batch job. After BATCH.COM
prepares your command(s) for execution from a batch job, it uses the
SUBMIT command to submit itself as a batch job and execute your
command(s) from this job. (See Note 8.) When you invoke BATCH.COM
as a batch job, the procedure branches to the label EXECUTE_BATCH_
JOB. Note that you must specify the command or command procedure to
execute as Pl and the default directory as P2 if you execute BATCH.COM
in batch mode.

These commands prepare the batch job for execution. First, the procedure
constructs a name for the batch job. If a command string was passed,
then BATCH.COM uses the verb name as the job name. If a command
procedure was passed, then BATCH.COM uses the file name. If no input
was passed, then BATCH.COM names the job BATCH.

The parameters are concatenated to form the command string to be
executed. The command string is assigned to the symbol COMMAND.

Annotated Command Procedures
A.10 BATCH.COM

The SUBMIT command cannot pass a parameter that is greater than 255
characters. Therefore, the procedure tests that the command string and
directory name are less than 255 characters long. If both strings are less
than 255 characters (and if the user did, in fact, pass a command string),
then the procedure branches to the label SUBMIT.

tD The procedure establishes a CTRL/Y handler, so clean-up operations are
performed if the user presses CTRL/Y during this section of the command
procedure.

The procedure creates a temporary file to contain the commands to be
executed. If the user supplies a long command string, the procedure
branches to WRITE_LARGE_COMMAND and writes this command to
the temporary file. Otherwise, the procedure prompts for the commands
to be executed. Each command is written to the temporary file.

Before you close the temporary file, write a symbol assignment statement
to the file. This statement assigns the file name for the temporary file to
the symbol BATCH$DELETEJILESPEC. After closing the temporary file,
the procedure resets the default CTRL/Y handler. Then the procedure
defines the symbol COMMAND so that, when executed, the symbol
COMMAND invokes the temporary command file.

The procedure submits itself as a batch job, using the defined job name.
(See Note 2.) The procedure also passes two parameters: the command
or command procedure to be executed, and the directory from which the
command should be executed. Then the procedure branches to the label
EXIT. (See Note 11.)

This section performs clean-up operations if the user types CTRL/Y while
the temporary file is being created.

CD This section writes an error message if the temporary file cannot be
created.

4D The procedure resets the original verification settings and then exits.
f> These commands are executed when BATCH.COM runs in batch mode.
First, ON error handling is disabled and the user's default verification
settings are set. Then the default is set to the directory indicated by P2,
and the command or command procedure indicated by Pl is executed. If
a temporary file was created, this file is deleted. The completion status for
Pl is saved before deleting BATCH$DELETEJILESPEC. This completion
status is returned by the EXIT command.
Sample Execution
$ ©BATCH RUN MYPROG
Job RUN (queue SYS$BATCH, entry 1715) started on SYS$BATCH

This example uses BATCH.COM to run a program from within a batch job.

A-27

Annotated Command Procedures
A.11 COMPILE_flLE.COM

A.11

COMPILE_FILE.COM
$! This command procedure compiles, links, and runs a file written in Pascal
$! or FORTRAN.
$!
$ ON CONTROL_Y THEN EXIT
$!
$ TOP:
$ INQUIRE FILE "File to process"
$ IF F$SEARCH (FILE) . NES . II II 0
$ THEN
$ FILE_ TYPE = F$PARSE(FILE,,, "TYPE") @
! determine file type
$ FILE_TYPE = F$EXTRACT(1,F$LENGTH('FILE_TYPE') ,FILE_TYPE) ! remove period
$! Remove type from file specification
$ PERIOD_LOC = F$LOCATE(". II ,FILE)
$ FILE = F$EXTRACT(O,PERIOD_LOC,FILE)
$ ON WARNING THEN GOTO OTHER
$ GOTO 'FILE_TYPE'
$ ELSE 9
$ WRITE SYS$0UTPUT FILE, "does not exist"
$ ENDIF Q
$!
$ GOTO END
$!
$!
$!
$FOR: 0
$ ON ERROR THEN GOTO PRINT
$ FORTRAN/LIST 'FILE'
$ GOTO LINK
$!
$ PAS:
$ ON ERROR THEN GOTO PRINT
$ PASCAL/LIST 'FILE'
$ GOTO LINK
$!
$ OTHER: 0
$ WRITE SYS$0UTPUT "Can't handle files of type . ''FILE_TYPE"'
$ GOTO END
$!
$ LINK: f)
$ ON ERROR THEN GOTO END
II
$ WRITE SYS$0UTPUT "Successful compilation
$ LINK 'FILE'
$ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND
$ RUN 'FILE'
$ GOTO CLEANUP
$!
$ PRINT: fD
$ WRITE SYS$0UTPUT "Unsuccessful compilation, printing listing file
$ PRINT 'FILE'
$!
$ CLEANUP:
$ DELETE 'FILE' .OBJ;
$ DELETE 'FILE' .LIS;
$!
$ END:
$ INQUIRE/NOPUNCTUATION ANS "Process another file (Y or N)? "
$ IF ANS THEN GOTO TOP
$EXIT

A-28

Annotated Command Procedures
A.11 COMPILE_FILE.COM

Notes

The IF command uses the F$SEARCH lexical function to search the
directory and determine if the file exists.

The command block following the THEN command:

•

uses the F$LENGTH lexical function to determine the length of the
file type

•

determines the file type

•

removes the period from the file type

•

removes the file type from the file specification to determine the file
name

•

removes the period from the file name

•

defines an action to perform if an error occurs

•

branches to the label defined by the symbol FILE_TYPE

If the file you entered at the "File to process:" prompt does not exist in

the directory, the command following the ELSE command executes.

The ENDIF command ends the IF-THEN-ELSE command language
construct.

The procedure compiles the FORTRAN program and branches to the
LINK label. If an error occurs during the compilation, the procedure
branches to the PRINT label.

The procedure displays that the program compiled correctly, links and
runs the program, and branches to the CLEANUP label. The program
branches to the END label if an error occurs.

The procedure enters the listing file of the program in the default print
queue.

Sample Execution
$ ©COMPILE_FILE
File to process: RAND.PAS
Successful compilation
%DELETE-I-FILDEL,WORK: [DESCH]RAND.OBJ;1 deleted (3 blocks)
%DELETE-I-FILDEL,WORK: [DESCH]RAND.LIS;1 deleted (9 blocks)
Process another file (Y or N)? N ~

A-29

Summary of Lexical Functions

The following list summarizes each lexical function and its arguments. For
complete information on each function, including examples, see the VMS DCL

Dictionary.
F$CVSl(bit-position ,count ,integer)
Extracts bit fields from character string data and converts the result, as a
signed value, to an integer.
F$CVTI M E([input-time][,output-time][, field])
Retrieves information about an absolute, combination, or delta time string.
F$CVUl(bit-position ,count ,integer)
Extracts bit fields from character string data and converts the result, as an
unsigned value, to an integer.
F$DIRECTORY()
Returns the current default directory name string.
F$EDIT(string ,edit-list)
Edits a character string based on the edits specified.
F$ELEMENT(element-number ,delimiter ,string)
Extracts an element from a string in which the elements are separated by a
specified delimiter.
F$ENVIRONMENT(item)
Obtains information about the DCL command environment.
F$EXTRACT(offset ,length ,string)
Extracts a substring from a character string expression.
F$FAO(control-string [,arg1 ,arg2 ... arg15])
Invokes the $FAO system service to convert the specified control string to a
formatted ASCII output string.
F$FILE_ATTRIBUTES(file-spec ,item)
Returns attribute information for a specified file.
F$GETDVl(device-name ,item)
Invokes the $GETDVI system service to return a specified item of information
for a specified device.
F$GETJPl(pid ,item)
Invokes the $GETJPI system service to return accounting, status, and
identification information for a process.

B-1

Summary of Lexical Functions

F$GETQUl(function [,item] [,object-id] [,flags])
Invokes the $GETQUI system service to return information about queues,
batch and print jobs currently in those queues, form definitions, and
characteristic definitions kept in the system job queue file.
F$GETSYl(item [,node])
Invokes the $GETSYI. system service to return status and identification
information about the local system, or about a node in the local cluster, if
your system is part of a cluster.
F$1DENTIFIER(identifier,conversion-type)
Converts an identifier in named format to its integer equivalent, or vice versa.
F$1 NTEGER(expression)
Returns the integer equivalent of the result of the specified expression.
F$LENGTH(string)
Returns the length of a specified string.
F$LOCATE(substring ,string)
Locates a character or character substring within a string and returns its offset
within the string.
F$LOGICAL(logical-name)
Translates a logical name and returns the equivalence name string.
F$M ESSAGE(status-code)
Returns the message text associated with a specified system status code value.
F$MODE()
Shows the mode in which a process is executing.
F$PARSE(file-spec [,default-spec] [,related-spec] [,field])
Invokes the $PARSE RMS service to parse a file specification and return either
the expanded file specification or the particular file specification field that you
request.
F$PI D(context-symbol)
For each invocation, returns the next process identification number in
sequence.
F$PRIVILEGE(priv-states)
Returns a value of "TRUE" or "FALSE" depending on whether your current
process privileges match the privileges listed in the argument.
F$PROCESS()
Returns the current process name string.
F$SEARCH(file-spec [,stream-id])
Invokes the $SEARCH RMS service to search a directory file, and returns the
full file specification for a file you name.

B-2

Summary of Lexical Functions

F$SETPRV(priv-states)
Sets the specified privileges and returns a list of keywords indicating the
previous state of these privileges for the current process.
F$STRI NG(expression)
Returns the string equivalent of the result of the specified expression.
F$TIME()
Returns the current date and time of day, in the format dd-mmm-yyyy
hh:mm:ss.cc.
F$TRNLNM(logical-name [,table] [,index] [,mode] [,case] [,item])
Translates a logical name and returns the equivalence name string or the
requested attributes of the logical name.
F$TVPE(symbol-name)
Determines the data type of a symbol.
F$USER()
Returns the current user identification code (UIC).
F$VERIFV([procedure-value] [,image-value])
Returns the integer 1 if command procedure verification is set on; returns the
integer 0 if command procedure verification is set off. The F$VERIFY function
also can set new verification states.

B-3

Commands Frequently Used in Command Procedures

The following DCL commands are frequently used in command procedures.
This list also includes commands that you use to control interactive command
procedures and batch jobs. See the VMS DCL Dictionary for complete
reference information on each DCL command.
Name

Function

Executes a command procedure.
Symbol assignment; equates a local symbol name to
an integer expression or character string expression.
Symbol assignment; equates a global symbol name to
an integer expression or character string expression.
String assignment; equates a local symbol name to a
character string. Commonly used to equate a symbol
to a command string without having to enclose the
string in quotation marks.
String assignment; equates a global symbol name to a
character string. Commonly used to equate a symbol
to a command string without having to enclose the
string in quotation marks.

ASSIGN

Equates a logical name to a physical device name,
to a complete file specification, or another logical
name, and places the equivalence name string in the
process, group, or system logical name table.

CALL

Transfers control to a labeled subroutine in a
command procedure and creates a new procedure
level.

Closes a file that was opened for input or output with
the OPEN command and deassigns the logical name
specified when the file was opened.

CONTINUE

Resumes execution of a command procedure or
image that was interrupted by pressing CTRL/Y or
CTRL/C.

DEASSIGN

Cancels a logical name assignment made with the
ALLOCATE, ASSIGN, or DEFINE command.

DECK

Marks the beginning of an input stream for a
command procedure when the first nonblank
character in any data record in the input stream is
a dollar sign ($).

DEFINE

Equates a logical name to a physical device name,
to a complete file specification, or to another logical
name, and places the equivalence name string in the
process, group, or system logical name table.

C-1

Commands Frequently Used in Command Procedures

C-2

Name

Function

DELETE/ENTRY

Deletes one or more entries from a print or batch job
queue.

DELETE/SYMBOL

Deletes a symbol definition from a local symbol table
or from the global symbol table.

ENDSUBROUTINE

Terminates a CALL subroutine and returns control to
the command following the CALL command.

EOD

Marks the end of an input stream for a command
procedure.

EOJ

Marks the end of a batch job submitted through a
system card reader.

EXIT

Terminates processing of the current command
procedure.

GO SUB

Transfers control to a labeled subroutine in a
command procedure but does not create a new
procedure level.

GOTO

Transfers control to a labeled statement in a
command procedure.

IF ... THEN

Tests the value of an expression and executes a
command if the test is true.

INQUIRE

Requests interactive assignment of a value for a local
or global symbol during the execution of a command
procedure.

JOB

Marks the beginning of a batch job submitted through
a system card reader.

ON ... THEN

Defines the default courses of action when a
command or program executed within a command
procedure ( 1) encounters an error condition or (2) is
interrupted by CTRL/Y.

OPEN

Opens a file for reading or writing.

PASSWORD

Specifies the password associated with the user
name specified on a JOB card for a batch job
submitted through a card reader.

Queues one or more files for printing, either on a
default system printer or a specified device.

READ

Reads a single record from a specified input file and
assigns the contents of the record to a specified
symbol name.

RETURN

Terminates a GOSUB subroutine procedure and
returns control to the command following the GOSUB
command.

SET CARD_READER

Defines the default ASCII translation mode for a card
reader.

SET CONTROL

Enables interrupts caused by CTRL/Y and CTRL/T.

SET ENTRY

Changes the current status or attributes of a job that
is not currently executing in a queue.

SET NOCONTROL

Disables interrupts caused by CTRL/Y and CTRL/T.

Commands Frequently Used in Command Procedures

Name

Function

SET NOON

Prevents the command interpreter from performing
error checking following the execution of commands.

SET NOVERIFY

Prevents command lines in a command procedure
from being displayed at a terminal or printed in a
batch job log file.

SET ON

Causes the command interpreter to perform error
checking following the execution of commands.

SET OUTPUT_RA TE

Sets the rate at which output is written to a batch job
log file.

SET REST ART_ VALUE

Establishes a test value for restarting portions of a
batch job.

SET QUEUE/ENTRY

Changes the current status or attributes of a file that
is queued for printing or for batch job execution but
not yet processed.

SET SYMBOL

Controls access to local and global symbols in
command procedures.

SET VERIFY

Causes command lines in a command procedure to
be displayed at a terminal or printed in a batch job log
file.

SHOW ENTRY

Displays the current status of an entry in a print or
batch job queue.

SHOW QUEUE

Displays the current status of entries in the print or
batch job queues.

STOP/ABORT

Aborts a job that is currently being printed.

STOP/ENTRY

Deletes an entry from a batch queue while it is
running.

STOP /REQUEUE

Stops the printing of the job currently being printed
and places that job at the end of the output queue.

SUBMIT

Enters one or more command procedures in the batch
job queue.

SUBROUTINE

Begins a CALL subroutine. During the line-byline command procedure execution, the command
language interpreter skips all commands between the
SUBROUTINE and the ENDSUBROUTINE commands.

SYNCHRONIZE

Places the process issuing this command into a wait
state until a specified batch job completes execution.

WAIT

Places the current process in a wait state until a
specified period of time has elapsed.

WRITE

Writes a record to a specified output file.

C-3

Index
CTRL/Y (cont'd.)

A
Access mode
supervisor mode• 2-4
user mode• 2-4
Ampersand (&)
requesting symbol substitution• 2-15
Annotated command procedures• A-1 to A-29
Apostrophe
requesting symbol substitution• 2-14
APPEND qualifier (OPEN command)• 6-9
ASSIGN command• 2-2

B
Batch execution of command procedure • 1-6
Batch job
deleting (stopping) after submission• 8-8
providing input to• 8-4
restarting • 8-9
specifying a queue • 8-3
stopping • 8-8
submitting a command procedure as• 8-1
synchronizing multiple procedures• 8-10
uses of• 8-1
Batch job log file• 8-5

c
CLOSE command• 6-1
Command
continuing to a second line• 1-3
in command procedures• C-1 to C-3
Command level, definition• 1-7
Comment character (I)• 1-3
Condition code
as symbol $SEVERITY• 7-2
assymb~$STATUS•7-1

definition• 7-1
Continuation character (-) • 1-3
CTRL/Y
action taken during execution• 7-6

default action for nested procedure • 7-9
disabling• 7-10
interrupting a command procedure• 7-6
with ON command• 7-7

D
Data lines• 1-2
in command procedures• 3-5
Data type
DCL conversion rules• 2-13
DEASSIGN command• 2-2
DECK command• 3-5
DEFINE command• 2-2
DELETE /ENTRY command• 8-8
DELETE/SYMBOL command• 2-9
Dollar sign ($)
including as data• 3-5
in command procedure• 1-2

E
EOD command• 3-5
Equal to operator
symbol for in expressions• 2-13
Equivalence string
definition• 2-1
Error condition
determining severity level• 7-2
Error handling
disabling CTRL/Y • 7-6
disabling error checking• 7-5
handling 1/0 errors• 6-10
specifying actions for different severity levels•
7-4
with ON command• 7-4
Errors
locating with SET VERIFY• 3-12
Exclamation point(!)
as a comment character• 1-3
Execute Procedure (@) command• 1-5
Execution of command procedure on remote
node• 1-6

lndex-1

Index

EXIT command• 5-16

F
F$CVSI lexical function• B-1
F$CVTIME lexical function • B-1
F$CVUI lexical function• B-1
F$DIRECTORY lexical function• B-1
F$EDIT lexical function• B-1
F$ELEMENT lexical function• B-1
wlthF$EXTRACT•4-9
F$ENVIRONMENT lexical function• B-1
obtaining current default• 4-3
F$EXTRACT lexical function• B-1
extracting a string• 4-9
F$F AO lexical function• B-1
defining record fields• 4-11
F$FILE_A TTRIBUTES lexical function• B-1
F$GETDVI lexical function• B-1
F$GET JPI lexical function • B-1
F$GETQUI lexical function• B-1
obtaining queue information• 4-5
F$GETSYI lexical function• B-2
obtaining system or cluster information• 4-5
F$1DENTIFIER lexical function• B-2
F$1NTEGER lexical function• B-2
converting data type• 4-13
evaluating data• 4-13
F$LENGTH lexical function• B-2
with F$LOCA TE• 4-9
F$LOCA TE lexical function• 8-2
with F$LENGTH • 4-9
F$LOGICAL lexical function
see F$TRNLAM lexical function
F$MESSAGE lexical function• B-2
F$MODE lexical function• B-2
F$P AASE lexical function • B-2
F$PID lexical function• B-2
obtaining process identification• 4-5
F$PRIVILEGE lexical function• 8-2
F$PROCESS lexical function• B-2
F$SEARCH lexical function• B-2
avoiding command procedure errors• 4-7
searching for a file• 4-7
F$SETPRV lexical function• 8-2
F$STRING lexical function• B-3
converting data type • 4-13
F$TIME lexical function• 8-3

lndex-2

F$TRNLNM lexical function• B-3
translating logical names• 4-8
F$TYPE lexical function• B-3
F$USER lexical function • B-3
F$VERIFY lexical function• B-3
changing VERIFY state• 3-13
File type
default• 1-2

G
GOSUB command • 5-10
GOTO command
with labels• 5-9
with the IF ... THEN language construct• 5-1 O
Greater than operator
symbol for in expressions• 2-13
Greater than or equal to operator
symbol for in expressions• 2-13

H
Hyphen
see Continuation character

I
IF command
controlling execution flow• 5-6
evaluating input of INQUIRE command• 5-8
executing a block of commands after• 5-8
restrictions to the IF-THEN-ELSE construct• 5-6
syntax rules for• 5-6
testing severity level• 7-2
with GOTO command• 5-1 O
Input
data lines• 1-2, 3-5
entering from a terminal• 3-6
obtaining with INQUIRE command• 3-4
obtaining with READ command• 3-4
opening a file to accept• 6-2
passing as a parameter to a command
procedure • 3-1
to an executable image• 3-5
to batch jobs• 8-4

Index

INQUIRE command

Logical name table (cont'd.)

converting input data with• 3-4
evaluating input from using the IF command•
5-8
in a batch job command procedure• 3-4
obtaining input• 3-4
using to obtain a value for a variable• 5-2
Interactive execution of command procedure• 1-5

process table• 2-3
system table• 2-3
LOGIN.COM
See Login command procedure
Login command procedure• 1-9
execution of for batch jobs• 8-2
location of• 1-11
personal • 1-9
system-defined• 1-9
Loop
in a command procedure• 5-14

L
Label
in command procedure• 1-4
with the GOSUB command• 5-10
with the GOTO command • 5-9
Less than operator
symbol for in expressions• 2-13
Less than or equal to operator
symbol for in expressions• 2-13
Lexical functions• B-1 to B-3
definition• 2-11, 4-1
evaluating• 2-11
specifying arguments for• 2-11
summary of• B-1
with WRITE command• 6-5
Log file
contents of• 8-5
examining during execution of batch job• 8-5
status when batch job is stopped abnormally•
8-8
Logical names
access modes of• 2-4
assigning• 2-2
attributes of• 2-4
creating• 2-2
definition• 2-1
deleting• 2-2
differences from symbols• 2-15
displaying• 2-4
in a file specification• 2-2
search list• 2-4
to obtain output value• 3-12
to refer to a device• 2-2
translation of• 2-1
with the OPEN command• 6-1
Logical name table
creating• 2-3
definition• 2-3
group table• 2-3
job table• 2-3

N
Nested command procedure• 1-7
default CTRL/Y action• 7-9
Not equal to operator
symbol for in expressions• 2-13

0
ON command
for error handling • 7-4
specifying severity level • 7-4
with CTRL/Y • 7-7
with severity level• 7-2
OPEN command • 6-1
appending records to an existing file• 6-9
creating a new output file• 6-8
opening a file for reading• 6-2
opening a file for writing• 6-2
opening a shareable file• 6-3
Operators
in expressions• 2-12
rules for data types• 2-13
Output
creating a new ouput file• 6-8
default for batch job command procedures•
3-8
default for interactive command procedures•
3-8
directing in a command procedure• 3-7
redefining for interactive command procedures•
3-8
suppressing by redefining SYS$0UTPUT • 3-8
to a terminal• 3-14

lndex-3

Index

p
Parameters
case value of strings• 3-2
null•3-2
passing to a command procedure• 3-1
Process permanent files
changing the default value of• 2-7
definition• 2-5
SYS$COMMAND • 2-6
SYS$ERROR • 2-6
SYS$1NPUT • 2-6
SYS$0UTPUT•2-6

R
READ command• 6-3
case value of data obtained• 3-4
using to obtain data • 3-4
Reading a record• 6-3
READ qualifier (OPEN command)• 6-2
Record
appending to a file• 6-9
reading from a file• 6-2
updating• 6-7
writing to a file• 6-2
Restarting a batch job• 8-9

s
Search list
definition• 2-4
translation of• 2-4
SET CONTROL_Y command• 7-10
SET ENTRY command• 8-7
SET NOON command• 7-5
SET QUEUE/ENTRY command• 8-7
SET SYMBOL command• 2-8
SET VERIFY command
changing with F$VERIFY lexical function• 3-13
debugging command procedure with• 1-13
$SEVERITY global symbol
commands that do not set• 7-2
definition• 7-2
testing for successful (odd) value• 7-2
value with SET NOON • 7-5

lndex-4

Severity level
determining• 7-2
specifying error handling based upon• 7-4
testing for with IF command• 7-2
use of ON command with• 7-2
Shareable files
opening• 6-3
SHOW ENTRY command• 8-6
SHOW LOGICAL command• 2-4
SHOW QUEUE command• 8-6
$ST A TUS global symbol
commands that do not set• 7-2
definition• 7-1
format of• 7-1
severity of error condition• 7-2
testing for successful (odd) value• 7-2
value with SET NOON• 7-5
STOP command• 5-16
Strings
comparing, using operators• 5-7
SUBMIT command
specifying multiple command procedures with•
8-3
with batch job command procedure• 1-6, 8-1
Symbols
as variables• 2-7
creating• 2-7
definition• 2-7
deleting• 2-9
determining the value of• 2-7
differences from logical names• 2-15
evaluating using IF command• 5-8
global•2-7
local• 2-7
masking the value of• 2-8
obtaining an output value with• 3-11
substitution• 2-14
with the WRITE command• 6-5
SYNCHRONIZE command• 8-10
SYS$COMMAND process permanent file• 2-6
changing the default value of• 2-7
in batch job command procedure• 2-6
in interactive command procedure• 2-6
using to define SYS$1NPUT as your terminal•
3-6
SYS$ERROR process permanent file• 2-6
changing the default value of• 2-7
in batch job command procedure• 2-6, 8-5
in interactive command procedure• 2-6
SYS$1NPUT process permanent file• 2-6
changing the default value of• 2-7

Index

SYS$1NPUT process permanent file (cont'd.)
in batch job command procedure• 2-6, 8-4
in interactive command procedure• 2-6
redefining as a data file• 3-7
redefining as a terminal• 3-6
redefining to allow input to an image• 3-5
SYS$0UTPUT process permanent file• 2-6
changing the default value of• 2-7
in batch job command procedure• 2-6, 8-5
in interactive command procedure• 2-6
redefining• 3-8

T
TYPE command• 3-15
using to execute command procedure on
remote node • 1-6

u
User mode assignments• 3-6
USER_MODE qualifier (DEFINE command)• 3-6

v
Variable
definition• 2-1

w
WAIT command
synchronizing command procedures• 8-10
WRITE command• 3-14, 6-5
updating records• 6-7
with symbols• 6-5
writing a string to a record• 4-11

lndex-5

Reader's Comments

Guide to Using VMS
Command Procedures
AA-LA 11 A-TE

Please use this postage-paid form to comment on this manual. If you require a written reply to a software
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your
comments on an SPR form.
Thank you for your assistance.

I rate this manual's:
Accuracy (software works as manual says)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent

Good

Fair

Poor

D
D
D
D
D
D
D
D

D
D
D
D

D
D

D
D
D
D
D

D
D
D
D
D
D

·o

D
D
D
D

I would like to see more /less

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page

Description

Additional comments or suggestions to improve this manual:

I am using Version _ _ _ of the software this manual describes.

Name/Title

Dept.
Date

Company
Mailing Address
Phone

I
I
I
I
I
I
·- Do Not Tear - Fold Here and Tape -------------------~lllr------""!'--------
No Postage

mnmaoma™

~;::;:i
in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGIT AL EQUIPMENT CORPORATION
Corporate User Publications-Spit Brook
ZK01-3/J35 110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

111 ..... 11.11 .... 11 .... 1.11.1 .. 1.1 .. 1.. 1.1 ••• 1.11 .. 1
-- Do Not Tear • Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -