Digital PDFs

AA-H782B-TE

December 1982

172 pages

Original

7.3MB

Document:	VAX/VMS Guide to Using Command Procedures
Order Number:	AA-H782B-TE
Revision:
Pages:	172
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/3.0/AA-H782B-TE_VAX_VMS_3.0_Guide_to_Using_Command_Procedures_198205.pdf

OCR Text

VAX/VMS
Guide to Using
Command Procedures
Order No. AA-H782B-TE

May 1982
This manual presents key concepts and techniques for developing
command procedures using the VAX/VMS DIGITAL Command
Language (DCL).

REVISION/UPDATE INFORMATION:

This document supersedes
the VAX/VMS Guide to Using
Command Procedures
(Order No. AA-H782A-TE).

SOFTWARE VERSION:

VAX/VMS Version 3.0

digital equipment corporation · maynard, massachusetts

First Printing, March 1980
Revised, May 1982
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

@ 1980, 1982 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
DECnet
DECsystem-10
DECSYSTEM-20
DEC US
DECwriter

DIBOL
EduSystem
IAS
MASS BUS
PDP
PDT
RSTS

RSX
UNIBUS
VAX
VMS
VT

mo~nomo
ZK2127

HOW TO ORDER ADDITIONAL DOCUMENTATION
In Continental USA and Puerto Rico call

800-258-1710

In New Hampshire, Alaska, and Hawaii call
In Canada call

603-884-6660

613-234-7726 (Ottawa-Hull)
800-267-6146 (all other Canadian)

DIRECT MAIL ORDERS (USA & PUERTO RICO)*
Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire 03061

DIRECT MAIL ORDERS (CANADA)
Digital Equipment of Canada Ltd.
940 Belfast Road
Ottawa, Ontario K1G 4C2
Attn: A&SG Business Manager

DIRECT MAIL ORDERS (INTERNATIONAL)
Digital Equipment Corporation
A&SG Business Manager
clo Digital's local subsidiary or
approved distributor

*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, Northboro, Massachusetts 01532

A-MN-EI.SM498-00-0

CONTENTS

Page
PREFACE

SUMMARY OF TECHNICAL CHANGES
CHAPTER 1

xiii

DEVELOPING COMMAND PROCEDURES

1.1
CREATING COMMAND PROCEDURES
• • • • • • • •
1. 2
FORMATTING AND DOCUMENTING COMMAND PROCEDURES
1. 2.1
Continuing Commands on More than One Line
1. 2. 2
Documenting Command Procedures •
• • • •
1.2.2.1
Using Comments • • • • •
• ••
1.2.2.2
Spelling Out Command and Qualifier Names •
1.2.2.3
Using Indentation
••••••••••••••
1. 3
EXECUTING COMMAND PROCEDURES • • • • •
• • •
1. 3.1
Executing Command Procedures in Interactive Mode
Submitting Command Procedures for Batch
1. 3. 2
Execution • • • • • • • • • • • • • • • • • •
Submitting Batch Jobs Through the Card Reader
Executing Nested Command Procedures
1. 3. 4
1. 3. 5
Using Log in Command Fi 1 es •
• • • •
The LOGIN.COM File • • • • • • • • •
1.3.5.1
1.3.5.2
A System- or Group-Defined Login File
1. 4
TESTING AND DEBUGGING COMMAND PROCEDURES •
1. 5
MAINTAINING COMMAND PROCEDURES • • • • • • •
1. 3. 3

CHAPTER 2

2.1
2.2
2.2.1
2.2.2
2.3
2.4
2.5
2.5.1
2.5.2
2.6
CHAPTER 3

3.1
3 .1.1
3.1. 2
3 .1. 3
3.2
3.3
3.4

1-5
1-6
1-6
1-7
1-7
1-7
1-7
1-8
1-9

1-10
1-11

1-13
1-14
1-14
1-14
1-16
1-16

CONTROLLING COMMAND PROCEDURE I/O
SYSTEM-DEFINED LOGICAL NAME EQUIVALENCES •
• •
VERIFYING COMMAND PROCEDURE EXECUTION
Verification in Batch Jobs • • •
• ••
Changing Verification Settings • • • • • • • • •
CONTROLLING INTERACTIVE OUTPUT • • • • • • • • • •
INCLUDING COMMAND AND PROGRAM DATA IN COMMAND
PROCEDURES • • • • • • • • • • • • • •
•
• • • •
REDEFINING SYS$INPUT AND SYS$0UTPUT
User Mode Assignments
• • •
Suppressing Output •
•
• •
DISPLAYING OUTPUT DATA •

2-1
2-2
2-3
2-4
2-4
2-5
2-7
2-8
2-9
2-9

USING SYMBOLS IN COMMAND PROCEDURES
SYMBOL NAMES • • • • • • • • • • • • •
• • •
Symbol Types and Expressions • • • •
Value Type Conversion in Expressions •
• ••
Lexical Functions in Expressions • • • • • • • •
EQUATING SYMBOLS TO CHARACTER STRING EXPRESSIONS •
EQUATING SYMBOLS TO INTEGER AND LOGICAL
EXPRESSIONS
• • • • • • •
• • •
OPERATORS IN EXPRESS IONS • • • • • • • • •
iii

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

CONTENTS
Page

3.4.1
3.4.2
3.4.3
3.4.4
3.4.5
3.5
3.6
3.7
3.8
3.9
3.9.1
3.9.2
3.9.3
3.10
3.10.1
3.10.2
3.10.3
3.10.4
3 .11
3.12
CHAPTER 4

4.1
4.2
4.2.1
4.3
4.4
4.5
4.5.1
4.5.2
4.5.3
4.5.4
4.5.5
4.6
4.7
CHAPTER 5

5.1
5.2
5.2.1
5.2.2
5.2.3
5.2.4
5.2.5
5.2.6
5.2.7
5.2.8
5.2.9
5.2.10
5.2.11
5.2.12
5.2.13
5.2.14
5.2.15
5.2.16
5.2.17
5.3
5.3.1
5.3.2

Logical Operations • •
• 3-7
Arithmetic Comparisons •
• 3-8
String Comparisons • • •
• 3-8
Arithmetic Operations
• 3-9
String Operations
3-10
SPECIAL-PURPOSE STRING ASSIGNMENTS •
3-10
REPLACING SUBSTRINGS IN CHARACTER STRING SYMBOL
VALUES • • • • • • •
3-11
ARITHMETIC OVERLAYS
• • • • • • •
3-12
CHANGING THE CONTEXT OF A SYMBOL •
3-13
SYMBOL TABLES
• • • • • • • • • •
3-14
Local Symbols
• • • • • • •
3-14
Global Symbols • • • • • • • • •
3-15
Order of Search of Symbol Tables • • • • •
3-15
PASSING PARAMETERS TO COMMAND PROCEDURES •
3-16
Specifying Parameters for the Execute Procedure
Command
• • • • • • • • • • • • •
• • • •
3-16
Delimiting Parameters • • • • •
3-16
Passing Parameters to Batch Jobs •
3-17
Redefining Parameters • • • •
3-18
THE INQUIRE COMMAND
• • • • • •
3-18
DELETING SYMBOLS • • • • • • • • • •
3-20
SYMBOL SUBSTITUTION IN COMMAND PROCEDURES
COMMAND SYNONYM SUBSTITUTION • • • • • • • •
• 4-1
USING APOSTROPHES AS SUBSTITUTION OPERATORS • • • 4-2
Substitution within Character Strings
• • • • • 4-2
AUTOMATIC EVALUATION • • • • • • • • • • • •
• 4-2
USING AMPERSANDS AS SUBSTITUTION OPERATORS •
• 4-3
REPETITIVE AND ITERATIVE SUBSTITUTION
• 4-4
Steps in Symbol Substitution • • • • • •
• 4-4
Iterative Substitution Using Apostrophes • • • • 4-5
Iterative Substitution Using Command Synonyms • 4-7
Iterative Substitution Using Ampersands
• 4-7
Iterative Substitution in Expressions
• • 4-8
UNDEFINED SYMBOLS
• • • • • • •
• • • • • 4-9
VERIFICATION OF SYMBOL SUBSTITUTION
4-10
USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
THE FORMAT OF LEXICAL FUNCTIONS
• • • • •
INFORMATIONAL FUNCTIONS
• • • • • • • • • • • •
The F$MODE Lexical Function
•••••
The F$VERIFY Lexical Function
••••••••
The F$DIRECTORY Lexical Function •
• •••
The F$PROCESS Lexical Function •
The F$USER Lexical Function
••••
The F$LOGICAL Lexical function •
• • • •
The F$TIME Lexical Function
• • • •
The F$MESSAGE Lexical Function •
• •
The F$FILE ATTRIBUTES Lexical Function •
The F$GETDVI Lexical Function
•
The F$GETJPI Lexical Function
• • • •
The F$GETSYI Lexical Function
• • • •
The F$PARSE Lexical Function • •
The F$PID Lexical Function • • • • • • • •
The F$SEARCH Lexical Function
The F$PRIVILEGE Lexical Function •
• •••
The F$SETPRV Lexical Function
•••••
STRING MANIPULATION FUNCTIONS
• • • •
The F$LENGTH Lexical Function
•••••
The F$LOCATE Lexical Function
•••••
iv

•
•
•
•
•
•
•
•
•
•
•
•

5-1
5-4
5-5
5-6
5-6
5-7
5-7
5-7
5-8
5-8
5-9
5-9
5-12
5-14
5-15
5-16
5-17
5-18
5-18
5-19
5-19
5-20

CONTENTS
Page
5.3.3\
5.3.4
5.3.5
5.3.6
5.3.7
5.4
CHAPTER 6
6.1
6 .1.1
6 .1. 2
6.2
6.2.1
6.2.2
6.3
6.4
6.4.1
6.4.2
6.4.3
CHAPTER 7
7.1
7 .1.1
7 .1. 2
7 .1. 3
7 .1. 4
7 .1. 5
7 .1. 6
7.2
7.2.1
7.2.2
7.2.3
CHAPTER 8
8.1
8.2
8.2.1
8.2.2
8.2.3
8.2.4
8.3
8.3.1
8.3.2
8.4
8.5
8.6
8.7
CHAPTER 9
9.1
9 .1.1
9.1. 2
9 .1. 3
9.2
9.2.1

The F$EXTRACT Lexical Function
THE F$INTEGER Lexical Function
The F$STRING Lexical Function
The F$CVTIME Lexical Function
The F$FAO Lexical Function • •
FUNCTIONS THAT MANIPULATE BINARY

5-21
5-21
5-22
5-22
5-23
5-26

•
•
•••••
• • • • •
DATA

CONTROLLING EXECUTION FLOW IN COMMAND PROCEDURES
THE IF COMMAND • • • • • • • • • • • • •
• • 6-1
Using Logical Operators in IF Commands •
• • 6-3
Using Symbols in IF Commands • • •
• • 6-4
THE GOTO COMMAND • • • • • • • • • • • • • • • • • 6-5
Using GOTO Within a THEN Clause
• • 6-7
Using GOTO to Establish Loops
• 6-7
NESTING PROCEDURES: THE EXECUTE PROCEDURE COMMAND 6-8
THE EX! T AND STOP COMMANDS •
• • • • • • • • • 6-8
Using the EXIT Command • • ·
• • • • • • • • • 6-8
Passing Status Values with the EXIT Command
6-9
Using the STOP Command • •
• • • • • • • •
6-10
CONTROLLING ERROR CONDITIONS AND CTRL/Y INTERRUPTS
ERROR CONDITION HANDLING •
• • •
Severity Levels
••••
The ON Command • • • • •
• • • •
Disabling Error Checking •
•
System Messages • • • •
Commands That Do Not Set $STATUS • • •
Status Codes Returned by Compatibility
Commands • • • • • • • •
CTRL/Y INTERRUPT HANDLING
• • • • • • •
Interrupting a Command Procedure •
Setting a CTRL/Y Action Routine
•
Disabling CTRL/Y Interruptions •

•
•
•
•
•

7-1
7-1
7-2
7-4
7-4
7-5

•
•
•
• • • • •
• • • • •

7-5
7-5
7-5
7-7
7-9

• • • •
• • •
•
• • • •
• • • •
Mode

•

CREATING, READING, AND WRITING FILES
OPENING FILES
• • • • • • • • • • • •
READING FILES
• • • •
• • • • •
Specifying Symbol Names for the READ Command
Handling End-of-File Conditions
••••
Reading Records Rand9mly from ISAM Files •
Deleting Records from ISAM Files • • • •
WRITING FILES
• • • • •
• • • •
Symbol Substitution in the WRITE Command •
Updating Records Using the WRITE Command •
APPENDING RECORDS TO EXISTING FILES
ERROR HANDLING • • • • • • • • • • •
COMMUNICATING WITH PROCESS-PERMANENT FILES •
FILE FORMATS • • •
• • • • • • •

• • 8-2
• • 8-3
• • 8-3
• 8-3
• 8-4
• • 8-4
• 8-4
• 8-5
• 8-5
• • 8-5
8-6
• 8-7
• 8-8

CONTROLLING BATCH JOBS
HOW THE SYSTEM EXECUTES BATCH JOBS • • • • •
The Batch Job Queue
•••••••••••••
Controlling Jobs in the Batch Job Queue
Concatenating Procedures into a Single Job • •
BATCH JOB OUTPUT • • • • • • • • • • • • • • • •
Including All Command Output in the Batch Job
Log

•

•
•
•
•
•

9-1
9-1
9-2
9-4
9-4

• 9-5

CONTENTS
Page

9.2.2
9.2.3
9.3
APPENDIX A
A. l

A.2
A.3
A. 4
A. 5
A. 6
A. 7
A.8
A.9

Saving the Batch Job Log File
• • • 9-5
Terminating a Batch Job Abnormally •
• 9-6
SYNCHRONIZING BATCH JOB EXECUTION
• • • • • • • • 9-6
ANNOTATED COMMAND PROCEDURES
CONVERT.COM
WAKEUP.COM •
DIR. COM
SYS.COM
GETPARMS.COM
EDITALL.COM
FORTUSER.COM
LISTER. COM •
CALC. COM • •

••••

•
••••
•

•

• A-3

. . . • • • .
• • • • •
• • • •

•

. A-6
• A-8
A-10
A-12
A-14
A-16
A-20
A-22

INDEX

FIGURES
FIGURE

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

2-2
2-3
3-1
3-2
4-1
4-2
4-3
6-1
6-2
7-1
7-2
7-3
8-1
8-2
9-1
9-2

Executing a Command Procedure in Interactive Mode 1-10
Submitting a Command Prodedure to a Batch Job
1-11
Queue
• • • • • • • • • • • • • • • • • • •
A Card Reader Batch Job
•••••••
1-12
Submitting a Batch Job Through a System Card
Reader • • • • • • • • • • • • • • • • • • •
1-13
Executing System and User Login Files
1-15
Logical Name Assignment at Different Command
Levels • • • • • • • • • • • • • • • • • •
• 2-3
An Input Data Stream with Dollar Signs • • •
• 2-6
Displaying Data in the Output Stream • • • •
2-10
Replacing Character Strings in Assignment
Statements • • • • • • • • • • • • • • • • •
3-12
Using a /PARAMETERS Qualifier Card • • • •
3-18
Example of the Three Phases ·of Symbol Substitution 4-5
Example of Iterative Substitution
• • • • •
4-6
Iterative Substitution Using a Command Synonym •
4-8
The IF Command • • • •
• • • •
6-3
THe GOTO Command • • • • • • •
6-6
ON Command Actions • • • ·• • •
7-3
Flow of Execution Following CTRL/Y Action
7-8
Default CTRL/Y Action for Nested Procedures
7-9
Steps in Reading and Writing Files. • • •
8-2
Symbol Substitution with the WRITE Command •
8-6
How the System Executes a Batch Job
9-2
Synchronizing Batch Job Execution
• • • •
9-7

TABLES
TABLE

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

Commands Frequently Used in Command Procedures • • 1-2
Summary of Command Procedure Output
• • • •
• 2-5
Commands that Prohibit Redirection of Output
• 2-9
Rules for Determining Expression Modes • • •
• 3-3
Summary of Lexical Function Value Types • • • • • 3-4
Summary of Operators in Expressions
• • • • 3-7
ASCII Character Set and Hexadecimal Values •
• 3-9
Summary of Lexical Fune t ions • • • • • • •
• 5-2
F$FILE_ATTR!BUTES Items • • • • • • • • • • • •
5-10
vi

CONTENTS
Page
5-3
5-4
5-5
5-6
7-1

F$GETDVI Items • • • • •
5-10
F$GETJPI Items •
• • • • •
• • • •
5-13
F$GETSYI Items •
• • • • • • • •
5-15
Summary of FAQ Directives
•••
5-25
Severity Levels for ON Command Actions •
• 7-2

vii

PREFACE

MANUAL OBJECTIVES
This manual presents key concepts and techniques for developing
command procedures using the VAX/VMS DIGITAL Command Language (DCL).
Many examples, including examples of complete command procedures, are
included to demonstrate applications of the concepts and techniques
discussed.

INTENDED AUDIENCE
All users of the VAX/VMS operating system can benefit from using
command procedures.
Command procedures can be constructed both to
serve very simple purposes and to perform complex tasks
that
approximate the capabilities of a high-level programming language.
For example, you can construct frequently used command sequences into
command procedures and thereby sava keystrokes; you can also write
sophisticated command sequences that pass parameters, test status
values, process files, and perform similar program-like tasks.

STRUCTURE OF THIS DOCUMENT
Each chapter in this manual builds on material presented in earlier
chapters.
Thus, if command procedure development is new to you, read
the associated documents, then study this
manual
sequentially
beginning with Chapter 1.
If, however, you are an experienced
programmer with some knowledge of command procedures,· you may want to
simply skim the Table of Contents and Index for the specific topics
you need.
This manual contains nine chapters and one appendix.
•

Chapter 1, Developing Command
procedures and describes the
development.

•

Chapter 2, Controlling Command Procedure I/O, describes the
system-defined logical name equivalences and how to use them
to control input to and output from command procedures.

•

Chapter 3, Using Symbols in Command Procedures, describes how
you can define and manipulate command symbols in command
procedures.

•

Chapter 4, Symbol Substitution in Command Procedures, defines
the mechanism of symbol substitution and describes ways you
control symbol substitution in command procedures.

•

Chapter 5, Using Lexical Functions in Command Procedures,
shows how to use the DCL lexical functions in command
procedures to obtain information about the status of a process
and to manipulate character strings.

Procedures, defines command
steps in command procedure

PREFACE
•

Chapter 6, Controlling Execution Flow in Command Procedures,
describes ways to use the DCL commands IF, GOTO, EXIT, and
STOP to control the sequen.ce in which command procedure lines
are executed.

•

Chapter 7, Controlling Error Conditions and CTRL/Y Interrupts,
shows how you can establish error condition routines based on
the severity of errors encountered during command procedure
execution and handle CTRL/Y interrupts that occur during
command procedure execution.

•

Chapter 8, Creating, Reading, and Writing Files, describes how
to manipulate sequential and indexed sequential (ISAM) files
using command procedures.

•

Chapter 9, Controlling Batch Jobs, describes how the system
creates batch jobs and how you can control their execution
from within command procedures.

•

Appendix A, Annotated Command Procedures, contains several
complete command procedures that illustrate the techniques
described in Chapters 1 ~hrough 9.

ASSOCIATED DOCUMENTS
The VAX/VMS Guide to Using Command Procedures is not a stand-alone
document.
You snould understand the material presented in the
following manuals before using this guide:
•

VAX/VMS Primer. This tutorial guide to the use of the VAX/VMS
operating system introduces new users to the DIGITAL Command
Language (DCL), the use of a text editor,
interactive and
batch mode operations,
files and file specifications, and
logical names.

•

VAX/VMS Summary Description ~ Glossary. This manual
is a
technical
summary
of
VAX/VMS concepts and components,
including those process concepts of interest to the user of
command procedures.
The manual also contains a glossary of
VAX-11 terms.

•

VAX/VMS Command Language user's Guide.
This manual
is the
primary reference document for
information about DCL.
The
manual contains complete descriptions of all DCL commands,
defines the grammar for the DCL command language, defines file
specification and usage, and (of particular use to command
procedure developers)
contains many examples of specific
commands. You should use the VAX/VMS Command Language User's
Guide as a
reference source while studying the material in
this manual.

CONVENTIONS USED IN THIS DOCUMENT
This manual uses the following graphic conventions.
This symbol indicates that you
the RETURN key on the terminal.

press

These symbols indicate that you hold
down the CTRL key while you press a
terminal key, for example Y.

PREFACE
$

SHOW TIME

05-JUN-1982

$
$
$

11:55:22

FORTRAN MYFILE
LINK MYFILE
RUN MYFILE

$ LOOP:

$ GOTO LOOP

quotation marks
apostrophe

In examples of interactive dialog, all
the lines you type are shown in red
letters. Everything the system prints
or displays is shown in black letters.
When
the
contents
of a command
procedure are shown, the lines in the
file are always shown in uppercase
letters.
A vertical ellipsis in an example
means that
not all the lines in the
command procedure are shown; or that
not all the data the system would
display is shown.
The term
quotation marks is used
to refer to double quotation marks
("). The term apostrophe is used to
refer to a single quotation mark (').

SUMMARY OF TECHNICAL CHANGES

This manual introduces new rules for assigning symbols (Chapter 3) and
includes descriptions of 13 new lexical functions (Chapter 5). The
new lexical functions are:
F$CVTIME
F$FAO
F$FILE ATTRIBUTES
F$GETDVI
F$GETJPI

F$GETSYI
F$INTEGER
F$PARSE
F$PID
F$PRIVILEGE

F$SEARCH
F$SETPRV
F$STRING

Numerous other small changes have been made to this
incorporate
corrections,
additions,
clarifications,
formatting and syntax improvements.

xiii

manual to
and minor

CHAPTER 1
DEVELOPING COMMAND PROCEDURES

A DCL command procedure is a file that
commands.

contains

sequence

DCL

Common uses for command procedures include constructing sequences of
commands you frequently use during interactive terminal sessions and
defining a batch job stream to submit from a terminal session or a
system card reader. As you become more skilled in creating and using
command procedures, you will discover many other applications for
them.
The annotated examples in Appendix A of this manual illustrate
only some of the uses of more complex command procedures.
In its simplest form, a command procedure consists of one or more
command lines for the DCL command interpreter to execute.
For
example, a procedure to compile, link, and execute the FORTRAN program
ALPHA could contain the lines:

$
$
$

FORTRAN/LIST ALPHA
LINK/MAP ALPHA
RUN ALPHA

In its most complex form, a command procedure can resemble a program
written in a high-level programming language:
it can establish loops
and error-checking routines;
perform arithmetic calculations and
input/output operations;
manipulate character string data; call
other command procedures;
pass
parameters
to
other
command
procedures; and test values set in other command procedures.
This chapter summarizes the steps in command procedure development:
•

Creating command procedures

•

Formatting and documenting command procedures

•

Executing command procedures

•

Testing and debugging command procedures

•

Maintaining command procedures

The remaining chapters in this guide discuss some of the key
and techniques for developing and using command procedures.
is information on how to:
•

Control command procedure input and output

•

Pass parameters to and from command procedures

•

Use symbols in command procedures

•

Control symbol substitution in command procedures

1-1

concepts
Included

DEVELOPING COMMAND PROCEDURES
•

Use the DCL lexical functions in command procedures

•

Direct the flow of command procedure execution

•

Handle status
procedures

•

Create, read, and write files using command procedures

•

Control batch
procedures

returns

jobs

and

CTRL/Y

batch

interrupts

job

queues

from

command

Some of the DCL commands that you use in command procedures are
summarized in Table 1-1. Note that many of these commands can be used
in contexts other than command procedures, but are particularly
relevant to command procedures. You should use the VAX/VMS Command
Language User's Guide as a reference for the grammar or use of any
command, including those illustrated in this manual.
Table 1-1:

Commands Frequently Used in Command Procedures

Name

Function

@filename

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.

label:

Defines a label for a GOTO statement.

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

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.
(continued on next page)

1-2

DEVELOPING COMMAND PROCEDURES
Table 1-1 (Cont.}:

Commands Frequently Used in Command Procedures

Name

Function

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.

DELETE/ENTRY

Deletes one or more entries from
or batch job queue.

DELETE/SYMBOL

Deletes a symbol definition from a
local
symbol table or from the global symbol
table.

EOD ·

Marks the end of an
command procedure.

EOJ

Marks the end of a batch job
through a system card reader.

EXIT

Terminates processing
command procedure.

the

current

GOTO

Transfers control to a
labeled
in a command procedure.

statement

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.

Lexical Functions

Return information
string expressions
process.

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.

input

stream

for

submitted

about
integer
and
and about the current

(continued on next page)

1-3

DEVELOPING COMMAND PROCEDURES
Table 1-1 (Cont.):

Commands Frequently Used in Command Procedures

Name

Function

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 logical name.

SET CARD READER
-

Defines the default ASCII translation mode
for a card reader.

SET CONTROL

Enables interrupts caused
CTRL/T.

CTRL/Y

and

SET NOCONTROL

Disables interrupts caused by
CTRL/T.

CTRL/Y

and

SET NOON

Prevents the command interpreter
from
performing error checking following the
execution of commands.

SET NOVERIFY

a
command
Prevents command lines in
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 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 VERIFY

causes command
lines
in
a
command
procedure to be displayed at a terminal or
printed in a batch job log file.

SHOW QUEUE

Displays the current status of entries
the print and/or batch job queues.

STOP/ABORT

Aborts a
printed.

currently

being

STOP/ENTRY

Deletes an entry from a batch queue
it is running.

while

STOP/REQUEUE

Stops the printing of the job currently
being printed and places that job at the
end of the output queue.

job

that

(continued on next page)

1-4

DEVELOPING COMMAND PROCEDURES
Table 1-1 (Cont.):

Commands Frequently Used in Command Procedures

Name

Function

SUBMIT

Enters one or more command
the batch job queue.

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

1.1

record

procedures

specified

output

CREATING COMMAND PROCEDURES

There are several ways to create command procedures.
Interactive
users can create a command procedure by using a VAX/VMS text editor
such as EDT or SOS or by using the DCL command CREATE.
Batch job
users can either
(1)
create a command procedure interactively and
submit the command procedure from a terminal or (2) punch a card deck
that includes the command procedure and submit the card deck to a
system card reader.
The following examples show the creation of a simple command procedure
by two different methods:
the CREATE command and the EDT editor:

$
$
$
$

CREATE FRED.COMIBD)
RUN A lliD)
RUN B lliD)
RUN C lliD)

(CTRL/Z)

$ EDIT FRED.COMIBD)
Input file does not exist
[EOB]
*C IBD)
$ RUN A lliD)
$. RUN B lliD)
$ RUN C lliD)
(CTRL/Z)

*EXIT
DBAl: [USER]FRED.COM;l 3 lines
$
You can construct command procedures that contain only data to be read
by a command or program;
that contain only qualifiers or parameters
for a command;
or that contain both. When you specify the Execute
Procedure (@) command in any position in a command string, the command
interpreter assumes that the at sign (@) character is followed by the
name of a file with a file type of COM, and begins reading input from
the specified command procedure.

1-5

DEVELOPING COMMAND PROCEDURES
For example, you could create a command procedure that contains a
number of qualifiers you frequently use together when you issue a LINK
command, as shown below:
/DEBUG/SYMBOL_TABLE/MAP/FULL/CROSS_REFERENCE
If this command procedure is named DEFLINK.COM, you can request these
qualifiers on a LINK command line to link an object module.
The
following example shows how to enter the LINK command to link an
object module named SYNAPSE.OBJ:
$

LINK SYNAPSE@DEFLINK

Note that no space precedes the at sign {@) character in this example.
If you type a space before the at sign, the command interpreter
assumes that the command file contains a file specification for
the
LINK
command.
Because the LINK command allows only one file
specification, an error would result when this command was parsed.

1.2

FORMATTING AND DOCUMENTING COMMAND PROCEDURES

Each line in a command procedure represents a line that you want the
DCL command interpreter to process.
You enter the lines into the
command procedure in the order in which you want the system to process
them.
For example,
to create a command procedure file named
TESTALL.COM that contains RUN commands to execute the program images
named A.EXE, B.EXE, and C.EXE, you could create a file containing the
following lines:

$
$
$

RUN A
RUN B
RUN C

To execute this command procedure from an interactive terminal
session, you would use the Execute Procedure {@) command, as follows:
$

@TESTALL

When you create a command procedure, you must begin each line with a
dollar sign
{$), whether the line starts a command string or is a
comment; you can follow the dollar sign with no blank spaces or tabs
or with one or more blank spaces or tabs.
The format used for command strings within command procedures is the
same as the format you would use to enter commands interactively, with
the exception that you must begin each command string with a dollar
sign.

1.2.1

Continuing Commands on More than One Line

You can continue any command string on more than one line by using the
hyphen character, just as you do for interactive command continuation.
You must not, however, begin any continuation line with a dollar sign.
For example:

PRINT TEST.OUT /AFTER=l8:00 /COPIES=lO /QUEUE=LPBO:

1-6

DEVELOPING COMMAND PROCEDURES
The qualifiers for this PRINT command are placed on separate lines in
the command procedure for readability.
The hyphen continuation
character is used to indicate that the command continues after the
first command line.
The spaces preceding each qualifier are not
required. They are included to make the command string more readable.

1.2.2

Documenting Command Procedures

Although no rules govern the precise format of lines in a command
procedure, it is good programming practice to make your command
procedures self-documenting so that they are easy to read and to
maintain.
The techniques described in the following sections are
useful for clear command procedure documentation.

1.2.2.1 Using Comments - Comments are as
important
in
command
procedures as they are in source programs and should be used
frequently. Whether a comment is a separate line or part of a line in
a command procedure, always precede it with an exclamation point (!).
For example:
$
$
$
$
$
$

FRED.COM

VAX/VMS V3.0

COMPILES, LINKS, RUNS ALPHA.FOR
COMPILE
LINK
GO

FORTRAN/LIST ALPHA
LINK/MAP ALPHA
RUN ALPHA

If you must use a literal exclamation point in a command line, enclose
it in quotation marks, so the command interpreter will not interpret
the exclamation· point as a comment delimiter.
Note that
the
exclamation point character can be used in data lines because data
lines do not begin with a dollar sign and are not processed by the
command interpreter.

1.2.2.2 Spelling Out Command and Qualifier Names - Do not
truncate
DCL command and qualifier names used in command procedures. Although
the grammar rules of DCL allow truncation, it is wise to spell out
full
command
and
qualifier
names
to ensure that ambiguous
abbreviations do not occur in the future.
Moreover, a procedure that spells out command names and qualifiers is
self-documenting, as 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).

1.2.2.3
improve

Using Indentation - In longer command procedures, you can
readability by tabbing command lines to offset them from

1-7

DEVELOPING COMMAND PROCEDURES
labels you use.
For example:

The dollar sign ($) should always

column

$
COUNT = 1
$ LOOPER:
$
IF COUNT .GT. 10 THEN GOTO ENDLOOP
$
DEFINE SWITCH 'COUNT'
$
RUN ALPHA
$
COUNT = COUNT + 1
$
GOTO LOOPER
$ ENDLOOP:
In the example above, the labels LOOPER and ENDLOOP clearly delimit
the portion of the command procedure that performs this particular
loop.
The commands IF and GOTO, and techniques for
constructing loops
in
command procedures, are described in Chapter 6, Controlling Execution
Flow in Command Procedures.

1.3

EXECUTING COMMAND PROCEDURES

When you log in to the VAX/VMS operating system, the system creates a
detached process for you,
and assigns to
the process the user
privileges, execution priority, and resource quotas that determine the
process context
the nature of the images that the process will be
allowed to execute.
There are two operating modes for command procedures, interactive mode
and batch mode.
You execute a command procedure in interactive mode
only when you issue the @ command during an interactive terminal
session or from a
command procedure.
The only other method of
initiating a command procedure (issuing the SUBMIT command) results in
the creation of a separate process used to run a batch job.
When you issue the Execute Procedure
(@)
command from a
detached
process,
the command
interpreter returns control to the interactive
DCL command level only after the command procedure either has been
successfully executed or has been terminated, for example, as the
result of an error condition.
Command procedure execution is serial,
just as
is the execution of any image within a detached process.
Thus, you cannot do any interactive work from the process while the
command procedure is being executed.
However, when you issue the SUBMIT command from a detached process,
a
separate process
is created for the batch job defined by the SUBMIT
command.
As soon as the batch job is queued, but before the
job is
executed,
control is returned to the process that executed the SUBMIT
command.
The batch process created
by
the
system
executes
independeptly from the submitting process, allowing you to do work at
the terminal.
Upon completion, the operating system deletes the batch
process.
You can execute DCL command procedures in five different ways.
•

You can issue the Execute Procedure
(@)
command during an
interactive terminal session.
This method is called executing
command procedures from interactive mode.

•

You can issue the SUBMIT command during an interactive
terminal session.
This method is called submitting command
procedures for batch execution.

1-8

DEVELOPING COMMAND PROCEDURES
•

You can place a card deck that contains a command procedure in
a system card reader. This method is called submitting batch
jobs through the card reader.

•

You can issue the Execute Procedure (@) command from a command
procedure.
This method is called executing nested command
procedures.

•

You can construct a special command procedure file,
called a
login command file,
that VAX/VMS automatically attempts to
locate and execute each time you login to the operating
system.

The following sections illustrate these methods of
execution.

1.3.1

command

procedure

Executing Command Procedures in Interactive Mode

When you execute a command procedure in interactive mode, first enter
the
Execute
Procedure
(@)
command and then enter the file
specification of the command procedure.
The command interpreter
assumes your current disk and directory defaults and a default file
type of COM.
For example,
to execute the
command
procedure
WEATHER.COM located in your default directory, issue this command:

@WEATHER

Figure 1-1 illustrates the execution of a command procedure in
interactive mode.
When you enter the Execute Procedure (@) command,
the command interpreter finds, then executes the file TESTALL.COM in
your default directory.
Each command string in TESTALL.COM is then
executed sequentially.
When the end-of-file for TESTALL.COM is
reached,
the command interpreter returns control to the interactive
command level and issues the dollar sign prompt at your terminal. 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:

@DBB2: [COMMON] SETUP.FIL

This command executes a command procedure that is located on the disk
DBB2:
in the directory [COMMON]. The command procedure file name is
SETUP.FIL.
For command procedures that you execute frequently, you can define
symbol name as a synonym for the entire command line.
For example:

SETUP := @DBB2: [COMMON] SETUP.FIL

This is an assignment statement that defines the symbolic name SETUP
to be equivalent to the string @DBB2: [COMMON] SETUP.FIL. This symbol
can be used, for example, as a command name during the current
terminal session.
If you wanted to be able to use this symbol every time you logged in
to VAX/VMS, you would include this symbol in a global assignment in
your login command file.
Refer to Section 1.3.5, Using Login Command
Files, for this method of executing a command procedure.

1-9

DEVELOPING COMMAND PROCEDURES

U'sernarrie:
Pass1A1ord:

..
$

HIGGINS

OBA 1:[HIGGINS]TESTALL.COM

@TESTALL

Command interpreter
finds TEST ALL.COM
on default device
and .directory ...

$
$
$

RUN A
RUN B
RUN C

r- $
~

then executes the
TEST ALL.COM commands sequentially ...

and returns control
to interactive command level after
TEST ALL.COM
completes
ZK-790-82

Figure 1-1:

1.3.2

Executing a Command Procedure in Interactive Mode

Submitting Command Procedures for Batch Execution

If you use the Execute Procedure {@) command interactively, you cannot
enter other commands to do other work while the procedure is
executing. If you create and use procedures that require lengthy
processing time -- for example, the compilation or assembly of large
source programs -- you can submit the procedure for execution as a
batch job instead of using the Execute Procedure command. Once the
batch job is queued by the operating system, your terminal is free for
you to continue interactive work.
The SUBMIT command requests the operating system to enter a command
procedure into a batch job queue. The SUBMIT command assumes your
current disk and directory defaults and a default file type of COM for
the command procedure. For example, to execute the command procedure
TESTALL.COM in your default directory, you could issue the command:
$

SUBMIT TESTALL
Job 210 entered on queue 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 it entered the job (SYS$BATCH).
Batch queues are normally set up and started by the system manager or
the system operator; in most cases, one of these queues will be named
SYS$BATCH.
Figure 1-2 illustrates how the SUBMIT command is used to queue the
file TESTALL.COM as a batch job. Although control is returned to you
as soon as the job is queued successfully, TESTALL.COM is not executed
1-10

DEVELOPING COMMAND PROCEDURES
until the operating system creates a process for it. The execution of
the batch job begins with an automatic login to your account and an
execution of your login command file
(if you have one).
Note,
however,
that the batch job is a separate process with its own unique
process context;
for example,
it cannot access symbols that you
define interactively.
UsernaMe: HIGGINS
Pass1A1ord:

$ SUBMIT TESTALL
~

Job 210 entered on

ueue SYS$BATCH

DBA 1:[HIGGINS]TEST ALL.COM

Command interpreter
finds TESTALL.COM
on default device
and directory ...

$ RUN A
$ RUN B
$ RUN C

then requests queue
for the batch job

SYS$BATCH QUEUE
TEST ALL.COM gets a
job number and is
placed in SYS$BATCH
queue

JOB NUMBER 208
JOB NUMBER 208
JOB NUMBER 210

•

Command interpreter
returns job information (and control)
to interactive
command level

i
When Job 210
can be executed,
a process is
created to execute
the job. When
the job is completed,
the process is
deleted
ZK-811-82

Figure 1-2:

1.3.3

Submitting a Command Procedure to a Batch Job Queue

Submitting Batch Jobs Through the Card Reader

When you submit a batch job through a system card reader, you must
precede the card deck containing the command procedure with cards.
containing JOB and PASSWORD commands. These cards specify your user
name and password and, when executed, effect a login for you. The

1-11

DEVELOPING COMMAND PROCEDURES
last card in the deck must contain the EOJ command.
The EOJ card,
when executed, is equivalent to logging out. Figure 1-3 illustrates a
card reader batch job.
L$EOJ
... command input stream ...

$PASSWORD HENRY

$JOB HIGGINS

ZK-812-82

Figure 1-3:

A Card Reader Batch Job

Note that you can prevent other users from seeing your password
suppressing printing when you keypunch the PASSWORD card.

When the system reads a job from the card reader, it validates the
user name and password specified on the JOB and PASSWORD cards. Then,
it copies the entire card deck into a temporary disk file named
INPBATCH.COM in your default directory and queues the job for batch
execution. Thereafter, processing is the same as for jobs submitted
interactively with the SUBMIT command.
When the batch job is
completed, the operating system deletes the INPBATCH.COM file.
When the system reads input from the card reader, it
two special types of card:
•

Translation mode cards

•

EOF cards

also

recognizes

Translation mode cards in the batch job's input stream change the
current translation mode. The translation mode is based on the device
type of the card punch on which the cards were punched. An 026 punch
is indicated by an 026 translation mode card (12-2-4-8 overpunch). An
029 card punch is indicated by an 029 translation mode
card
(12-0-2-4-6-8 overpunch).
The default card translation mode can be
set with the SET CARD READER command.
An EOF card (12-11-0-1-6-7-8-9) overpunch or card
command signals the end of the job.

containing

EOJ

Figure 1-4 illustrates a batch job submitted th~ough a system card
reader.
The command interpreter reads the cards and creates a file,
INPBATCH.COM, in the user's default disk and directory.
The system
queues the joh in the SYS$BATCH queue. After the job is executed, the
system deletes the file INPBATCH.COM from the user's default disk and
directory.

1-12

DEVELOPING COMMAND PROCEDURES

$ JOB HIGGINS

OBA 1:[HIGGINS]INPBATCH.COM

Command interpreter
reads cards and
creates INPBATCH.COM
in default disk
and directory...

RUN A

RUN B

RUN C

then requests queue
for the batch job
SYS$BATCH QUEUE

INPBATCH.COM gets a
job number and is
placed in the
SYS$BATCH queue

- - _..

JOB NUMBER 208
JOB NUMBER 208
JOB NUMBER 210

I
When job 21 O can
be executed, the
INPBATCH.COM file
is executed. When
the job is completed,
INPBATCH.COM is
deleted from
OBA 1:[HIGGINS]

I
I
I

~-- ---

----'

ZK-813-82

Figure 1-4:

1.3.4

Submitting a Batch Job Through a System Card Reader

Executing Nested Command Procedures

Command procedures can be nested. That is, one command procedure can
contain an Execute Procedure (@) command to execute another command
procedure.
In this case, the command interpreter reads input from the
second command procedure file until it reaches the end of the file or
until that procedure exits; it then returns control to the first
command procedure.
The maximum number of command procedures you can nest is eight.
For
more information on nesting command procedures, refer to Section 2.1,
System-Defined Logical Name Equivalences, and Section 6.3, Nesting
Procedures:
The Execute Procedure Command.

1-13

DEVELOPING COMMAND PROCEDURES
1.3.5

Using Login Command Files

There is a special type of procedure, called a login command file,
that the system automatically attempts to locate and execute each time
you log in to the operating system.
This file also is executed
automatically,
if present, at the beginning of every batch job you
submit.

1.3.5.1 The LOGIN.COM File - Use the LOGIN.COM file to execute any
command or sequence of commands that you typically execute at the
start of each terminal session.
For example, if you define synonyms
for DCL commands, you can place the global assignment statements for
the command name synonyms in your LOGIN.COM file so they will be
available every time you log in.
The LOGIN.COM file can also contain
commands to assign logical names,
run programs, execute command
procedures, or display message files.
For example, a LOGIN.COM file
could contain the following statements:
$
$
$
$
$
$
$

QP :== SHOW QUEUE/DEVICE/FULL
QB :== SHOW QUEUE/BATCH/FULL
TIM :== SHOW TIME
SET PROTECTION = (GROUP:RE,WORLD)/DEFAULT
DEFINE PAY DBAl: [MALCOLM.PAYROLL]
DEFINE DOC DBAl: [MALCOLM.DOCUMENTS]
TYPE SYS$SYSTEM:NOTICE.TXT

You can use the Execute Procedure (@) command to test your LOGIN.COM
file.
You can also set up your LOGIN.COM file so that it executes
different commands depending on whether the current process mode is
interactive or batch.
For an example of how to do this, see Section
5.2.1, The F$MODE Lexical Function.
When you create your login file, you should locate it on your default
disk and directory, and name it LOGIN.COM.
This is the default
specification for the LGICMD in the user authorization file
(UAF).
The LGICMD defines the name of the user login file in the UAF.
The name of your login file does not have to be LOGIN.COM, although
this convention predominates. The system manager, who authorizes use
of the system, can assign any name in the UAF.
However, the name the
system manager assigns in your UAF must match your login file in order
for that file to be executed at login.
Another approach to assigning login files is for the system manager to
set up a login file to be executed on behalf of a selected number of
users. When a system manager has defined such a file, the commands in
that file are executed instead of any user-defined login files.
However, the end of the system manager's file can, and usually does
contain the command:
@LOGIN
which then executes the individual user-defined login files.

1.3.5.2 A System- or Group-Defined Login File - The system
manager
can optionally specify, for all system users or users having the same
group UIC, a login file that is executed before the login file
specified by the user's LGICMD.
He does this by assigning the logical
name SYS$SYSLOGIN to a system-defined login file.
The commands in the

1-14

DEVELOPING COMMAND PROCEDURES
following example define SYS$SYLOGIN as either a system or group
logical name for SYS$MANAGER:SYSLOGIN.COM, the system-defined login
file.
$ DEFINE/SYSTEM SYS$SYLOGIN SYS$MANAGER:SYSLOGIN.COM
or
$ DEFINE/GROUP SYS$SYLOGIN SYS$MANAGER:SYSLOGIN.COM
The DEFINE/SYSTEM command places SYS$SYLOGIN into the system logical
name table,
and the DEFINE/GROUP command places SYS$SYLOGIN into the
group logical name table.
Thus, at login,
the system-defined login
file
is executed for all users on the system or all users in a
particular group, depending on how SYS$SYLOGIN was defined.
Once the
execution of this login file completes, the individual user-defined
login files (LGICMD defined) are executed.
The difference between the user-defined
login
file
and
the
system-defined login file is
illustrated in Figure 1-5. The file
specification
for
the
system-defined
login
file
is
SYS$MANAGER:SYSLOGIN.COM.
The file specification for the user-defined
login file is DBAl: [HIGGINS] LOGIN.COM. When user HIGGINS logs in, the
system-defined login file executes first.
After the system-defined
login file completes, the command interpreter locates and executes the
user-defined login file on the default disk and directory for user
HIGGINS.
System Start-up Procedure

$ DEF I NE I SYSTEM SYS$SYLOG INSYSSMANAGER: SYSLOG IN. COM

Username· HIGGINS
Pass1,1ord:
WELCOME TO l,JA)-(fl,JMS

15-JUN-1882 10:33:36

SYSLOGIN.COM runs
until the end-of-file,
when control is
passed to
LOGIN.COM

SYS$SYLOGIN

$TYPE SYS$SYSTEM:NOTICE,T>(T
$ SHOW DAYTIME

When LOGIN.COM is
completed, control is
returned to user at
terminal.

$ QP:==SHOW QUEUE/DEt.JICE/FULL
$ASSIGN DBA1: CHIGGINS' PAYROLL J PAY

ZK-814-82

Figure 1-5:

Executing System and User Login Files

1-15

DEVELOPING COMMAND PROCEDURES
NOTE
In some installations, a system-defined
login
file
can
control an entire
terminal session.
Such a procedure,
which can restrict the commands a user
is allowed to execute, is illustrated in
the
sample
command
procedure
FORTUSER.COM in Appendix A.

1.4

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 use of the commands SET VERIFY and SET NOVERIFY.
Methods
for debugging command procedures are discussed in Section 2.2,
Verifying Command Procedure Execution.

1.5

MAINTAINING COMMAND PROCEDURES

If the command procedures you develop are correctly formatted,
carefully documented, and verified, their maintenance is relatively
easy. Because new versions of the VAX/VMS operating system may
include enhancements to the DCL command language, you should be aware
of new commands and any changes to current commands.
Generally, DIGITAL makes changes to the DCL commands
(and to the
functions of the DCL command interpreter) only to add new features,
and to correct errors, but a new release may occasionally change the
format or results of a particular command, command parameter, or
qualifier.
For effective maintenance, study the release notes issued
with each VAX/VMS release for the effect, if any, of changes to the
DCL command language or the DCL command language processor.

1-16

CHAPTER 2
CONTROLLING COMMAND PROCEDURE I/O

This chapter discusses the concepts and techniques you use to control
input to and output from command procedures. The topics covered are:

2.1

•

How the system-defined equivalences for process logical names
function at different command levels

•

How to use the SET VERIFY command as a debugging aid and as a
means of controlling responses and messages from DCL commands
and programs

•

How to write command procedure output to a disk file

•

How to include command or program data in a command procedure

•

How to use the DEFINE command to
SYS$INPUT and SYS$0UTPUT

•

How to display data at your terminal or place data in a batch
job's output stream

redefine

equivalences

for

SYSTEM-DEFINED LOGICAL NAME EQUIVALENCES

When you log in, the operating system creates a detached process for
you and establishes the initial equivalences to the following process
logical names:
•

SYS$INPUT
The default command and data input stream for
this process. The command interpreter uses SYS$INPUT to read
commands and data that are required by commands.

•

SYS$0UTPUT -- The default output stream for commands and
program images that execute in this process. The 6ommand
interpreter uses SYS$0UTPUT when it issues prompting and
informational messages.

•

SYS$ERROR -- The default error message stream for
this
process.
The command interpreter writes error and warning
messages to SYS$ERROR.

•

SYS$COMMAND
The initial command input stream for
this
process.
The
command interpreter uses SYS$COMMAND to
"remember" the original input device.

•

SYS$DISK -The default device for this
command interpreter uses this equivalence
device name portion of file specifications.

process.
The
to fill in the

•

SYS$LOGIN -- The device and directory that are
when you log in.

the

2-1

defaults

CONTROLLING COMMAND PROCEDURE I/O
•

SYS$SCRATCH -- The default device
temporary files are written.

and

directory

which

When you execute a command procedure, the command interpreter provides
a new equivalence name for SYS$INPUT, equating it to the command
procedure itself. This equivalence overrides the original assignment
for the duration of the command procedure.
When c~mmand procedures are nested, the command interpreter redefines
the equivalence name for SYS$INPUT, equating it to the file from which
the current command procedure is read.
That is, the SYS$INPUT
equivalence is changed as the current command level changes.
The logical names SYS$ERROR and
SYS$COMMAND
do
not
change.
SYS$COMMAND is always equated to the initial command level:
if you
execute a command procedure interactively, SYS$COMMAND is always
equated to your terminal;
if you submit a batch job, SYS$COMMAND is
always equated to the initial batch input file.
The equivalence for
SYS$0UTPUT does not change unless the /OUTPUT qualifier is specified
when you enter the Execute Procedure (@} command.
In other words, the initial command input level, command level O,
is
the level at which, by default, SYS$INPUT and SYS$COMMAND are the
same.
Figure 2-1 illustrates logical name
levels.

2.2

assignments

various

command

VERIFYING COMMAND PROCEDURE EXECUTION

By default, the output from a command procedure executed interactively
is displayed on the terminal. This output includes:
•

Responses and messages from DCL commands

•

All data messages displayed
SYS$0UTPUT and SYS$ERROR

programs

that

write

If you also want to see the DCL commands and comment lines displayed
at the terminal, you can use the SET VERIFY command.
Issue SET VERIFY
either within the command procedure or at the interactive command
level;
the command affects all command procedures you subsequently
execute during the terminal session.
For example, to display lines in a particular command procedure, you
could place the SET VERIFY command at the beginning of the procedure
and place the SET NOVERIFY command at the end of the procedure, as
follows:

$ SET VERIFY
$ RUN TESTA
$ RUN TESTB
$ SET NOVERIFY
The SET NOVERIFY command at the end of this procedure restores
default setting for interactive command procedure execution.

the

Note that verifying a command procedure's execution is the principal
debugging tool for detecting errors in a command procedure.
If SET
NOVERIFY is in effect and an error occurs,
it may be difficult to
determine which command caused the error. With SET VERIFY in effect,
it is much easier to determine the cause of the error.

2-2

CONTROLLING COMMAND PROCEDURE I/O

User name: HIGGINS
Password:

A
V

input
output
error
command

TTB3:
TTB3:
TTB3:
TTB3:

__________.,,,.

$@PROC1

PROC1.COM

input
output
error
command

OBA 1:PROC1.COM
TTB3:
TTB3:
TTB3:

___________.,..
e

$ @PROC2/0UTPUT=PROC2.0UT

PROC2.COM

$EXIT

input
output
error
command

OBA 1:PROC2.COM
OBA 1:PROC2.0UT
TT83:
TTB3:
0882 :PROC3.COM

$ @0882:PROC3

input

$EXIT~

e ~~~ut

command

OBB2:PROC3. COM
OBA 1:PROC2.0UT
TT83:
TTB3:

$EXIT

$SUBMIT BATCH1
$next-command

OBA 1:BATCH1.COM
OBA 1:BATCH1.LOG
OBA 1:BATCH1.LOG
OBA 1:BATCH1.COM

output
error
command

OBA 1:BA TCH2.COM
OBA 1:BATCH1.LOG
OBA 1:BATCH1.LOG
OBA 1:BATCH1.COM

$ @8ATCH3/0UTPUT=8A TCH3.0UT

8ATCH3.COM

input
output
error
command

$EXIT

OBA l:BA TCH3.COM
OBA l:BA TCH3.0UT
OBA 1:BATCH1.LOG
OBA 1:BATCH1.COM

I
I
I
I
I
I
I

_ _ _ _ _J
Key:

input
output
error
command

Input stream (SYS$1NPUT)
Output stream (SYS$0UTPUT)
Error stream (SYS$ERROR)
Command stream (SYSSCOMMAND)

Transfer of control
Command Level
Execution occurs in a separate process
ZK-815-82

Figure 2-1:

2.2.1

Logical Name Assignment at Different Command Levels

Verification in Batch Jobs

In a batch job, the verification fs set on by default;
all DCL
commands and comment lines are written to the batch job log file with
the command responses and messages.
2-3

CONTROLLING COMMAND PROCEDURE I/O
You can use the SET NOVERIFY command in a batch job to suppress
verification.
For example, if a procedure loops around a command or
set of commands, you might want to suppress verification while the
looP. executes and restore it afterward.
You can also use the SET NOVERIFY command at the beginning of your
LOGIN.COM file.
Otherwise, the contents of this file will appear at
the beginning of every batch job log.
However, you must include a SET
VERIFY command at the end of your LOGIN.COM file if you want the batch
job log file to exclude the login file while containing verification
information of the batch job.

2.2.2

Changing Verification Settings

The SET VERIFY and SET NOVERIFY commands are executed within the
command interpreter and therefore can be issued while a command
procedure is executing without affecting the command or program image
currently executing.
For example, if you interactively execute a command procedure that
does not contain the SET VERIFY command and you decide, after
execution begins,
that you want to see the DCL command lines
displayed, you can interrupt the procedure by pressing CTRL/Y as shown
below:

@MASTER~

(CTRL/Y)

"'y

$ SET VERIFY~
$ CONTINUE lBrn
$
The next step in this procedure is to concatenate all
$
related files into a single master file before print-

In the above example the Execute Procedure
(@)
command runs the
procedure MASTER.COM.
Then, CTRL/Y is pressed to interrupt the
procedure's execution, causing the command interpreter to prompt for
command input.
When the SET VERIFY command is entered, the default
verification setting is changed so that the lines in the procedure
will be displayed on the terminal. The CONTINUE command is issued to
resume execution of the command procedure.
The next few lines
displayed, in this case, are comment lines in the procedure.

You can write a command procedure that tests the current verification
setting, changes it if necessary, and restores the original setting
before the command procedure completes execution.
This technique
requires an understanding of the lexical function F$VERIFY (see
Section 5.2.2).

2.3

CONTROLLING INTERACTIVE OUTPUT

When you use the Execute Procedure
(@)
command interactively, the
system
equates
the logical device SYS$INPUT with the command
procedure, while SYS$0UTPUT and SYS$ERROR remain assigned to your
terminal.
In this way, output resulting from command or program
execution and system messages are displayed on your terminal.

2-4

CONTROLLING COMMAND PROCEDURE I/O
If you want a permanent record of the output from the execution of a
command procedure, you can use the /OUTPUT qualifier of the Execute
Procedure
(@)
command.
The
/OUTPUT
qualifier
redefines
the
equivalence name for SYS$0UTPUT from the default (the terminal) to a
disk file.
For example:
$ @TESTALL/OUTPUT=TESTALL.LOG
When you issue this command, all the data that._is normally displayed
on your terminal as TESTALL.COM is executed is written instead to the
disk file named TESTALL.LOG.
To d~termine the outcome of the command
procedure, you can use the TYPE command to display the file or the
PRINT command to print it.
For example:
$ TYPE TESTALL.LOG
Note that most DCL commands and VAX/VMS utilities write warning and
error messages to both SYS$0UTPUT and SYS$ERROR. Therefore, when you
use the /OUTPUT qualifier to redefine SYS$0UTPUT, you will still see
all error and warning messages that occur during the execution of the
command procedure, even though all data will be written only to
SYS$0UTPUT. You cannot redefine SYS$ERROR.
Table 2-1 summarizes the output from a command procedure, based on the
output device and whether verification is on or off.
Table 2-1:
Output Device

Summary of Command Procedure Output
VERIFY

NOVERIFY

SYS$0UTPUT
(terminal)

Terminal displays:
All DCL command
lines and comment lines·

Terminal displays:
All messages to
SYS$0UTPUT and
SYS$gRROR

Log File
(/OUTPUT
qualifier
specified)

Terminal displays:
All messages to
SYS$ERROR

Log File contains:
All DCL command
lines and comment lines

Log File contains:
All messages to
SYS$0UTPUT

All messages to
SYS$0UTPUT

2.4

INCLUDING COMMAND AND PROGRAM DATA IN COMMAND PROCEDURES

In a command procedure, you can issue a command that requires input
data or run a program that requires input data.
By default, the input
data will be read from SYS$INPUT, the command input stream.
SYS$INPUT
is the command procedure.
For example, when you issue the CREATE command, the system reads input
lines for a file from the command input stream. When you issue the
CREATE command interactively, the command input stream (SYS$INPUT)
is
your terminal, and you indicate the end of the input data by pressing
CTRL/Z.

2-5

CONTROLLING COMMAND PROCEDURE I/O
When you include the CREATE command in a command procedure, the input
stream is the command procedure itself. You include the input data
lines for the file in the command procedure, immediately following the
CREATE command line.
The following example illustrates a command
procedure that creates a file named WEATHER.DAT,
includes the data
lines that make up WEATHER.DAT,
and
issues the RUN command for a
program that reads the WEATHER.DAT file.

$ CREATE WEATHER.DAT
JAN
39
3
FEB
42
1
MAR
50
7

DEC
46
$ RUN WEATHER.FOR

In this example, the end of the input data for the file WEATHER.DAT is
indicated by the RUN command line. The end of input data for any
command or program that is reading input data from a command procedure
is indicated by a line that begins with the dollar sign {$) character,
or by 'the physical end-of-file of the command procedure.
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, you use the DECK and EOD (End of
Deck) commands. These commands are particularly useful for batch
users who submit all work through the system card reader.
For
example, if you use the CREATE command to write a command procedure to
a file,
you would use the DECK and EOD commands as shown in Figure
2-2, which illustrates a batch job that creates and executes the
command procedure WEATHER.COM.
end of input stream

$ EOJ

input stream for
CREATE command - - - - -

input stream with
dollar signs follows
$CREATE WEATHER.COM

ZK-816-82

Figure 2-2:

An Input Data Stream with Dollar Signs

2-6

CONTROLLING COMMAND PROCEDURE I/O
You can also place input statements for a compiler into a command
procedure's input stream by specifying the name of the data file as
SYS$INPUT.
The compiler will read its input from the command
procedure. The following example illustrates a command procedure that
contains a FORTRAN command followed by source statements:
$ FORTRAN/LIST SYS$INPUT:TESTER
C THIS IS A TEST PROGRAM
A = 1
B = 2

STOP
END
$ PRINT TESTER.LIS
In this example, the file specification given to the FORTRAN command
includes the device specification SYS$INPUT. Thus, the compiler reads
the statements following the FORTRAN command {up to the next line that
begins with a dollar sign) instead of looking in your default device
and directory for a source program named TESTER.FOR.
When the
compilation is completed, two output files are created: TESTER.OBJ
and TESTER.LIS. The PRINT command is then executed to print the
output listing file.

2.5

REDEFINING SYS$INPUT AND SYS$0UTPUT

The techniques shown in the preceding section are particularly useful
in batch applications. In interactive applications, they can be used
for iterative testing of programs under development.
For example,
consider the following command procedure:
$ FORTRAN AVERAGE
$ LINK AVERAGE
$ RUN AVERAGE
33
66
99
9999

In this example, the FORTRAN, LINK, and RUN commands compile, link,
and execute an interactive program that normally reads its input from
the terminal. In this case, the data is read from the command
procedure so the procedure can be used to test the source program each
time it is revised.
You can use this technique whenever you can provide a program with a
nonvarying set of input data. However, you may want to run a program
from a command procedure and supply the program with input from the
terminal.
For example, if you want to run the program AVERAGE and
supply its input data from the terminal, you must redefine the input
stream.
To do so~ you include a DEFINE command in the command
procedure before the RUN command:
$ DEFINE SYS$INPUT SYS$COMMAND:
$ RUN AVERAGE

This DEFINE command redefines the input stream and equates it to the
initial command stream (SYS$COMMAND).
When the program AVERAGE is
executed it reads input from the terminal rather than from the command
procedure.

2-7

CONTROLLING COMMAND PROCEDURE I/O
When a DEFINE command in a command procedure equates SYS$INPUT to
SYS$COMMAND,
all
subsequent
programs
(other than the command
interpreter itself) that read input from SYS$INPUT will actually read
the input from SYS$COMMAND (that is, from the terminal).
For example:
$ DEFINE SYS$INPUT SYS$COMMAND:
$ EDIT AVERAGE.FOR
$ FORTRAN AVERAGE
$ LINK AVERAGE
$ RUN AVERAGE
In this example, both the EDIT and RUN commands invoke interactive
programs that normally read from SYS$INPUT.
In this procedure,
however, both of the programs run by these commands will read input
from the current SYS$COMMAND device, the terminal. When the editing
session is completed, the next command in the procedure is executed.
At the end of the procedure, the command interpreter restores the
defaults associated with the initial command level in the terminal
session.
Note that changing the assignments for the logical names SYS$INPUT and
SYS$COMMAND does not affect the device from which the command
interpreter reads its input:
such devices are known to the command
interpreter from the time you log in.
In the case of a batch job, the
devices are known from the beginning of the job.

2.5.1

User Mode Assignments

When you use a DEFINE command in a command procedure to change the
equivalence of a
logical name for a process-permanent file (such as
SYS$INPUT), you can use the DEASSIGN command
to
cancel
the
equivalence.
The following command procedure shows how the DEASSIGN command is used
to change an equivalence name.
$ DEFINE SYS$INPUT SYS$COMMAND:
$ EDIT AVERAGE.FOR
$ DEASSIGN SYS$INPUT
$ FORTRAN AVERAGE
$ LINK AVERAGE
$ RUN AVERAGE
33

66
99
9999

this input data will be ignored

In this example, the DEFINE command changes SYS$INPUT so that the
editor can be run from the command procedure. Later, the input data
for the program AVERAGE follows the RUN command in the procedure. The
DEFINE command, however, has redefined the input stream and this
assignment (the terminal) is still in effect.
The ·DEASSIGN command
cancels the logical name assignment for SYS$INPUT at the end of the
editing session and restores the default command input stream, so when
the RUN command executes the AVERAGE program, AVERAGE reads its data
from the command procedure instead of from the terminal.
A more convenient way to run the above example is to use the
/USER_MODE qualifier in the DEFINE command. A user-mode logical name

2-8

CONTROLLING COMMAND PROCEDURE I/O
assignment exists only for the execution of one program image, in this
example, for the duration of the editing session:
$ DEFINE/USER MODE SYS$INPUT SYS$COMMAND:
$ EDIT AVERAGE.FOR
$ FORTRAN AVERAGE
$ LINK AVERAGE
$ RUN AVERAGE
33
66
99
9999
When the editing session
is
over,
the
command
interpreter
automatically cancels the logical name assignment for SYS$INPUT and
restores the default for the current command level.
Then, when the
AVERAGE program reads input data from SYS$INPUT, it reads the data
that is in the command input stream.
For another example of running the editor from a command
file, see the sample procedure EDITALL.COM in Appendix A.

2.5.2

procedure

Suppressing Output

Many commands or programs that you execute produce output and display
this output
(by default) on SYS$0UTPUT. When you execute a command
procedure, you may want to suppress this output or direct it to
another file.
You can do this by redefining SYS$0UTPUT.
For example:
$ DEFINE/USER MODE SYS$0UTPUT STATISTIC.SRT .
$ SORT/KEY=(POSITION:l,SIZE:40)/STATISTICS INFILE.DAT OUTFILE.DAT
In the above example, statistics that the SORT command normally
displays are redirected to the file STATISTIC.SRT.
The DEFINE command
specifies the /USER MODE qualifier so that when execution of the SORT
image is complete~,
the default equivalence will be reestablished.
You can use this technique to suppress the output from any DCL command
that displays output data on SYS$0UTPUT.
Table 2-2 lists the commands
that do not allow output to be redirected.
Table 2-2:
ALLOCATE
DEASSIGN
SHOW PROTECTION
SHOW STATUS
SHOW TRANSLATION

Commands that Prohibit Redirection of Output
ASSIGN
DEFINE
SHOW QUOTA
SHOW SYMBOL
SPAWN

ATTACH
SHOW DEFAULT
SHOW RMS DEFAULT
SHOW TIME

The sample command procedure LISTER.COM in Appendix A
how to define SYS$0UTPUT to suppress program output.

2.6

illustrates

DISPLAYING OUTPUT DATA

There are many different ways to display data on your terminal or in
the output stream for a batch job during the execution of a command
procedure.
One method, discussed in Section 3.11,
is to use the
INQUIRE command.
Four other methods, using the TYPE, CREATE, COPY,

2-9

CONTROLLING COMMAND PROCEDURE I/O
and WRITE commands are illustrated in Figure 2-3. The first part of
the figure shows a file, OUTPUT.COM, created by the CREATE command.
The second part of the figure shows the resulting display when the
Execute Procedure command (@OUTPUT) is executed from the terminal.
$
$
$

CREATE OUTPUT.COM
TYPE SYS$INPUT:
THESE LINES ARE IN THE INPUT STREAM.
THE TYPE COMMAND DISPLAYS THEM IN THE OUTPUT STREAM+
CREATE SYSSOUTPUT:
THESE LINES <AS WELL AS ANY BLANK LINES PRECEDING AND
FOLLOWING> ARE IN THE INPUT STREAM.
THE CREATE COMMAND CREATES A FILE IN THE OUTPUT STREAM+

COPY SYSSINPUT: SYS$0UTPUT
THE COPY COMMAND COPIES DATA FROM THE INPUT STREAM
INTO THE OUTPUT STREAM.
NOTE THAT FOR EACH OF THESE COMMANDS <CREATE AND COPY>
A LINE BEGINNING WITH A DOLLAR SIGN INDICATES THE END
OF THE INPUT DATA+

S WRITE SYSSOUTPUT •THE WRITE COMMAND WRITES A SINGLE DATA LINE+•
$WRITE SYSSOUTPUT •LINES WRITTEN BY THE WRITE COMMAND ARE,•
$WRITE SYS$0UTPUT •HOWEVER, PROCESSED BY THE COMMAND INTERPRETER.u
$

'"'Z
$

(WUTPUT
THESE LINES ARE IN THE INPUT STREAM+
THE TYPE COMMAND DISPLAYS THEM IN THE OUTPUT STREAM+
THESE LINES <AS WELL AS ANY BLANK LINES PRECEDING AND
FOLLOWING> ARE IN THE INPUT STREAM+
THE CREATE COMMAND CREATES A FILE IN THE OUTPUT STREAM+

•

THE COPY COMMAND COPIES DATA FROM THE INPUT STREAM
INTO THE OUTPUT STREAM+
NOTE THAT FOR EACH OF THESE COMMANDS <CREATE AND COPY>
A LINE BEGINNING WITH A DOLLAR SIGN INDICATES THE END
OF THE INPUT DATA.
THE WRITE COMMAND WRITES A SINGLE DATA LINE+
LINES WRITTEN BY THE WRITE COMMAND ARE,
HOWEVER, PROCESSED BY THE COMMAND JNTERPRETER+
$
ZK-817-82

Figure 2-3:

Displaying Data in the Output Stream

The primary difference between the commands that read data from the
input stream (such as TYPE, COPY, and CREATE) and the WRITE command is
that the command interpreter does not process input data lines.
It
does, however, process data in a WRITE command string. Thus, a WRITE

2-10

CONTROLLING COMMAND PROCEDURE I/O
command can contain symbol names for data
(variable values or
character strings)
and
the symbol names will be replaced with their
current values before the line is written.
The next three chapters contain detailed information on creating and
using symbols
in command procedures.
The WRITE command is discussed
in Chapter 8.

2-11

CHAPTER 3
USING SYMBOLS IN COMMAND PROCEDURES

A command symbol is a character string name that has a value.
In
VAX/VMS command procedures, you can define symbols as constants or
variables and manipulate them in much the same way that you manipulate
variables
in
a
programming language.
In fact,
the symbolic
capabilities of the command interpreter, together with commands such
as IF and GOTO, make the DCL command language very much like a
programming language.
For example, you can define a symbol to represent a
as shown below:

character

string

$ FILE = "ALPHA"
This command, called an assignment statement, gives the symbol name
FILE the value ALPHA. Subsequently, the file ALPHA can be referred to
symbolically by specifying the symbol name FILE.
For example:

$ FORTRAN 'FILE'
The apostrophes surrounding the symbol name FILE are substitution
operators;
they tell the command interpreter that the word they
surround is a symbol name. The command interpreter substitutes the
value ALPHA for the symbol FILE before parsing the FORTRAN command.
This chapter describes the syntax of symbol names and gives examples
of defining symbol values. Chapter 4 provides detailed information on
how the command interpreter substitutes values for symbols during
command processing;
Chapter 5 introduces the command language's
lexical functions.

3.1

SYMBOL NAMES

An assignment statement equates a symbol name with a character string
value or a signed integer value. You can use assignment statements in
command procedures to perform string substitution and manipulation,
arithmetic operations, and logical comparisons.
The rules for forming a symbol name are:
Begin a symbol name with an alphabetic letter (A through Z) ,
• an
underscore
( ), or a dollar sign
($). All lowercase
letters you enter-are translated to uppercase by
interpreter.
•

Use from 1 to 255 characters, including any of the
listed above.

3-1

the

command

characters

USING SYMBois IN COMMAND PROCEDURES
You can define symbol names and use them as variable data in a qommand
procedure by:
•

Equating symbol names to expressions, constant values, lexical
functions,. or to other variable symbol names with assignment
statements (described in Sections 3.2 through 3.7)

•

Passing parameters to a command procedure when you invoke it,
or to a batch job when you submit it to a queue (described in
Section 3.10)

•

Using the INQUIRE command to
during the execution of a
Section 3.11)

•

Using the READ command to read a character string from an
input file or device and assigning the character string value
that was a symbol name (described in Chapter 8)

prompt for a symbol's value
command procedure (described in

You can delete symbol names from local and
described in Section 3.12.

3.1.1

global

symbol

tables

Symbol Types and Expressions

You can equate a symbol to either a string expression or an integer
expression.
The actual value assigned to a symbol is the result of
the expression. Expressions can contain character strings,
integers,
lexical functions, or symbols. For example:
$ CODE = 4 + F$INTEGER("6") - A
This command assigns the symbol CODE to an expression containing an
integer
(4), a lexical function (F$INTEGER("6")), and a symbol (A).
The actual value assigned to the symbol CODE is the result of the
expression.
In this example, the expression evaluates to an integer
value.
The value type (string or integer) assigned to a symbol is determined
by the mode (whether the expression evaluates to a string or integer
value) of the expression.
If the expression evaluates to a string,
the symbol is assigned a string value.
If the expression evaluates to
an integer, the symbol is assigned an integer value.
The mode of an expression is determined by the types of values used in
the expression and the operations used to manipulate them. Table 3-1
lists the rules for determining the mode of an expression.

3.1.2

Value Type Conversion in Expressions

In expressions that contain both integer and string values as
operands, string values are automatically converted to integer values
before any operation is performed. Numeric strings are converted to
integer values; alphabetic strings are converted to the integer 1 if
the string begins with T, t, Y, or y, or to the integer 0 if the
string begins with any other letter. The following examples show how
string values are converted to integer values:
String

Integer

"123"
"Test"
"file"

1 (True)
0 (False)

123

3-2

USING SYMBOLS IN COMMAND PROCEDURES
The only exception to the implicit conversion rule described above
occurs
in
string comparison operations.
In string comparison
operations, any integer value in the expression is converted to a
string value before the string comparison is performed. The following
examples show how integer values are converted to string values in
string comparison expressions:
Integer

String

123

"123"

1
0

"l"
"O"

You can also perform value conversion explicitly using
and F$STRING lexical functions (see Chapter 5).
Table 3-1:

the

F$INTEGER

Rules for Determining Expression Modes

Expression

Mode and Resultant
Value Type

Integer value
String value
Integer lexical function
String lexical function
Integer symbol
String symbol
+, -, or .NOT. any value
Any value .AND. or .OR. any value
String + or - string
Integer + or - any value
Any value + or - integer
Any value * or I any value
Any value (string comparison) any value
Any value (arithmetic comparison) any value

Integer
String
Integer
String
Integer
String
Integer
Integer
String
Integer
Integer
Integer
Integer
Integer

In the above table, if "any value" is a character string value, it is
converted to an integer value before the operation is performed,
except for the string comparison expression.
In 1string comparison
expressions, if "any value" is an integer, it is converted to a string
value before the string comparison is performed.

3.1.3

Lexical Functions in Expressions

The command language contains constructs called lexical functions that
return information about the process and system, and manipulate
integer and string expressions.
You can use lexical functions in expressions in the same way you would
normally use integer values, string values, or symbols. However, the
value and type returned by a lexical function depends on the function.
Lexical functions return either a string or integer value. For
example:
$A= F$STRING(81)
$ SHOW SYMBOL A
A = "81"

3-3

USING SYMBOLS IN COMMAND PROCEDURES
Since the value returned by the lexical function F$STRING in this
example is the character string "81", the symbol A is assigned the
string value "81". Thus, whenever A is used in an expression,
its
type is a string.
Table 3-2 lists the
types.
Table 3-2:

lexical

functions

and

their

respective

Summary of Lexical Function Value Types
Function

Value Type
Integer
Integer
String
String
String
String
Integer or
Integer or
Integer or
Integer or
Integer
Integer
Integer
String
String
String
String
String
String
String
String
String
String
String
String
Integer

F$CVSI
F$CVUI
F$CVTIME
F$DIRECTORY
F$EXTRACT
F$FAO
F$FILE ATTRIBUTES
F$GETDVI
F$GETJPI
F$GETSYI
F$INTEGER
F$LENGTH
F$LOCATE
F$LOGICAL
F$MESSAGE
F$MODE
F$PARSE
F$PID
F$PRIVILEGE
F$PROCESS
F$SEARCH
F$SETPRV
F$STRING
F$TIME
F$USER
F$VERIFY

string
string
string
string

For a complete description of the lexical functions,
their
formats, and their use in command procedures, see Chapter 5.

3.2

value

required

EQUATING SYMBOLS TO CHARACTER STRING EXPRESSIONS

The format of an assignment statement that equates a symbol name to
character string value is:

symbol-name = string-expression
A string expression can contain character st~ings, lexical functions
that evaluate to character strings, or other symbols assigned to
character strings.
Character strings can contain any alphanumeric or
and must be enclosed in quotation marks (").

3-4

special

characters

USING SYMBOLS IN COMMAND PROCEDURES
Some examples of character string assignment statements as they
appear in a command procedure are:

would

$ NAME = "MYFILE.DAT"
$ TEMP = "TEMPORARY FILE CREATED"
$ TOPIC = "THE " + TEMP
$ COUNT = F$STRING(65)
$ OUTPUTMESSAGE = "Beginning ••• "
$ TOTAL= "NUMBER OF FILES = " + F$STRING(B)
$ SUBTOTAL = TOTAL
In all of these examples, symbol names are assigned to character
string expressions. Some of these expressions contain a single value
that is either a character string, symbol name, or a lexical function.
Notice,
however,
that some string expressions are composed of
character strings, symbols, and lexical functions used as operands in
expressions.
For example, the following assignment contains the
o·perands "THE " (character string) and TEMP (string symbol):
$ TOPIC = "THE " + TEMP
The plus sign (+)
operator in this example concatenates the two
operands to form a single character string that is assigned to the
symbol TOPIC.
So,
if the symbol TEMP was assigned the value
"TEMPORARY FILE CREATED", the value for the symbol TOPIC would be "THE
TEMPORARY FILE CREATED". Note that both ,operands in the expression
must be character strings for string concatenation to occur.
You can also subtract a character string from another string in an
expression using the string reduction (-) operator. Note that both
operands must be character strings for string reduction to occur.
In
a reduction operation, the character string following the minus sign
is removed from the string preceding the minus sign.
For example:
FILENAME = "TEMPFILE" -

"TEMP"

The minus sign in this example removes the character string "TEMP"
from the string "TEMPFILE". As a result, the character string "FILE"
is assigned to the symbol FILENAME.
In a subtraction operation, if the string follo~ing the minus sign
occurs more than once in the preceding string, only the first
occurrence is removed.

3.3

EQUATING SYMBOLS TO INTEGER AND LOGICAL EXPRESSIONS

The format of an assignment statement that equates a symbol name to an
integer value or expression is:
symbol-name

integer-expression

Some examples are:
$ COUNT
1
$ VALUE
%XlC
$ SUM = 1 + 7 - 4/3 + 10
An expression can be any integer value or an integer or logical
expression.
You can specify a value in a non decimal radix by using
the radix operator (%X for hexadecimal, %D for decimal,
or %0 for

3-5

USING SYMBOLS IN COMMAND PROCEDURES
octal) as shown in the second example above. When you define a value
in either hexadecimal or octal, the command interpreter converts the
value to a decimal integer.
When the command interpreter evaluates an expression, it assigns the
expression a value based on the result of the operations specified in
the expression:
•

If the expression contains arithmetic comparison operators or
string comparison operators, it is assigned the value 1 (true)
if it results in an odd numeric value;
the expression is
assigned the value O (false) if it results in an even numeric
value.

•

If the expression contains logical operators or arithmetic
operators,
the result is the value of the logical or
arithmetic operations.

The following sections show how to specify .integer and logical
expressions using assignment statements.
Note that the rules for
specifying and using expressions in assignment statements also apply
to specifying expressions in the IF command, in lexical functions, and
in all contexts in which the command interpreter automatically
performs expression evaluation.
The IF command is described in
Chapter 6.
For clarity, the examples in this chapter show literal integer and
character string values in expressions.
Additional examples of
expressions are shown throughout this manual;
these examples will
show how to use symbols as variables or constants in expressions.

3.4

OPERATORS IN EXPRESSIONS

~able

3-3 lists the valid operators you can use in forming expressions
and defines the order of precedence of evaluation.
Logical and
comparison operators must be preceded by a period
{.)
with no
intervening blanks.
The operator must be terminated with a period.
You can type· any number of blanks or tabs between operators and
operands.
For example, the following expressions are equivalent:
A.EQS.B
A .EQS.

Each operator {except .NOT.
have operands on each side.

and the unary plus or minus

signs)

must

When you specify more than one operation in an expression,
the
operations are performed in the order of precedence list~d in Table
3-3, where 1 is the lowest precedence and 7 is the highest.
For
example, multiplication is performed before addition. Use parentheses
to override the order in which operators are evaluated:
expressions
within parentheses are evaluated first.
Operations of the same precedence are performed from left to right, as
they appear in the command.

3-6

USING SYMBOLS IN COMMAND PROCEDURES
Table 3-3:

Summary of Operators in Expressions

Type

Operator

Precedencel

Logical
Operators

.OR.
.AND.
.NOT.

Arithmetic
Comparison
Operators

String
Comparison
Operators

Arithmetic
Operators

2
3

.EQ.
.GE.
.GT.
.LE.
.LT.
.NE.

4
4
4

.EQS.
.GES.
.GTS.
.LES.
.LTS.
.NES.

I
String
Operators

1. Lowest precedence is l;

3.4.1

Arithmetic equal to
Arithmetic greater than or equal to
Arithmetic greater than
Arithmetic less than or equal to
Arithmetic less than
Arithmetic not equal to
equal to
greater than or equal to
greater than
less than or equal to
less than
not equal to

4
4

5
5
7
7
6
6

A.r i thmet ic sum
Arithmetic difference
Arithmetic unary plus
Arithmetic unary negate
Arithmetic product
Arithmetic division (integer quotient)

5
5

String concatenation
String reduction

Logical OR
Logical AND
Logical complement

String
String
String
String
String
String

4
4
4

Operation

highest precedence is 7.

Logical Operations

Use logical operators to perform logical functions on integer values
or to construct complicated expressions. Some examples are listed
below:
Expression
A
B

c
D

3 .OR.
5
3 .AND.
5
.NOT.3
3 + 4 .AND.

Value of Symbol
A

7
1
-4
6

2 + 4

Operands for logical operations are integer values, symbol names
equated to integer values, or expressions that yield integer values.
If you specify a character ~tring value as an operand, it is converted
to an integer value before the operation is performed.
Note that logical operators can be used
well.
For example:

arithmetic

sense

A = %Xl000 .OR. %X0001
This expression performs a logical OR operation on two values.
The
resulting value of the symbol A is %Xl001, or 4097. Note that one of
the two values in the' OR expression (%X0001) is logically true;
the

3-7

USING SYMBOLS IN COMMAND PROCEDURES
other value (%Xl000) is logically false.
The resulting value of A
(%1001)
is logically true. An arithmetic OR always yields a logical
as well as an arithmetic result.

3.4.2

Arithmetic Comparisons

Use arithmetic comparison operators to compare integer values.
If the
result of an arithmetic comparison is true, the expression has a value
of l;
if the result of the comparison is false, the expression has a
valµe of O.
Some examples are listed below:
Expression

Value of Expression
1
0
0
1
1
1

1. LE. 2

l.GT. 2
1 + 3 • EQ. 2 + 5
"TRUE".EQ.l
"FALSE".EQ.O
"123".EQ.123

(true)
(false)
(false)
{true)
(true)
(true)

Operands in arithmetic comparisons are integer values, symbol names
equated to integer values, or expressions that yield integer values.
If you specify a character string value as an operand, it is converted
to an integer value before the comparison i~ performed.

3.4.3

String Comparisons

Use string comparison operators to compare
character
strings.
Character string comparison is based on the binary values of the ASCII
characters in the string.
The ASCII characters and their hexadecimal
values are listed in Table 3-4.
The following rules apply to
character string comparisons:
•

The comparison is on a character-by-character basis:
the
comparison terminates as soon as two characters do not match.

•

If one string is longer than the other, the shorter string is
padded on the right with nulls (an ASCII value of %XOO) before
the comparison is made. Note that a null has a lower numeric
value than any of the alphabetic or numeric characters.

•

Lowercase letters have higher numeric
letters.

values

than

uppercase

If the result of a comparison is true, the expression is given a value
of l;
if the comparison is false, the expression is given a value of
o. Some examples are listed below:
Expression

Value of Expression

"MAYBE".LTS."maybe"
"ABCD".LTS."EFG"
"YES".GTS."YESS"
"AAB" .GTS. II AAA"
"TRUE".EQS.l
"FALSE".EQS.O
"123".EQS.123

1
1
0
1

(true)
(true)
(false)
(true)
o (false)
0 (false)
,l (true)

Operands in string comparisons are character strings, expressions that
yield character strings, or symbol names equated to character strings.
If you specify an integer value as an operand, it is converted to a
string before the comparison is performed.
3-8

USING SYMBOLS IN COMMAND PROCEDURES
If you do not enclose a character string in quotation marks, the
command interpreter assumes the string is a symbol name and issues an
error message if the symbol is not ~efined.
Table 3-4:

ASCII Character Set and Hexadecimal Values

HEX
Code

ASCII
Char.

HEX
Code

ASCII
Char.

HEX
Code

00
01
02
03
04
OS
06
07
08
09
OA
OB

NUL
SOH
STX
ETX
EOT
ENQ
ACK
BEL
BS
HT
LF
VT
FF
CR

20
21
22
23
24
2S
26
27
28
29
2A
.2B
2C
20
2E
2F
30
31
32
33
34
3S
36
37
38
39
3A
3B
3C
30
3E
3F

40
41
42
43
44
4S
46
47
48
49
4A
4B
4C
40
4E
4F

OD
OE
OF
10
11

12
13
14
lS
16
17
18
19
!A
lB
lC
lD
lE
lF

SI
OLE
DC!
DC2
DC3
DC4
NAK
SYN
ETB
CAN
EM
SUB
ESC
FS
GS
RS

!
II

#
$
%
&
I

(
)

*
,
-

0
1
2
3
4

Sl
S2
S3
S4
SS
S6
S7
S8
S9
SA
SB
SC
SD
SE
SF

6
7
8
9
:
;

<
=
>
?

ASCII
Char.

HEX
Code

ASCII
Char.

60
61
62
63
64
6S
66
67
68
69
6A
6B
6C
60
6E
6F
70
71
72
73
74
7S
76
77
78
79
7A
7B
7C
70
7E
7F

A
B

c
D
E

F
G

H
I
J
K

L
M
N
0
p
Q

w
x
y

z
[

\
1
I\

c
d
e
f
g

h
i
j
k

1
m
n
0

p
q
r

s
t

u
v
w
x

y
z
{

I
}
"v

DEL
ZK-820-82

3.4.4

Arithmetic Operations

Use arithmetic operators to perform calculations on integers.
In
arithmetic operations, all nondecimal (specified by radix operators)
and character string values are converted to integer values before the
operation is performed, except when string concatenation and string
reduction are being performed (see Section 3.4.5). The result of the
arithmetic operation is an integer.
All arithmetic is integer
arithmetic;
that is, all fractional values are truncated.
Some
examples are listed below:

Expression

Result

5 + 10 I 2
* 3 - 4 * 6 I 2

B = 5
c = 5

* (6

%X50
E = %Xl0 + 5
F = 6 I 4
G = -5 + 4

- 8 I

B =
1) c =
D =
E =
F =
G =

3-9

10
3
2
80
21
1
-1

USING SYMBOLS IN COMMAND PROCEDURES
Operands in arithmetic operations are integer values,
symbol names
equated to
integer values, or expressions that yield integer values.
If you specify a string value as an operand, it is converted to an
integer value before the operation is performed.
The sample procedure CONVERT.COM in Appendix A illustrates
assignment statements that perform calculations.

3.4.5

arithmetic

String Operations

Use string operators to either concatentate or reduce strings.
In
order for string concatenation and reduction to occur, both operands
must be character string values.
In a string concatenation operation,
the plus sign
(+)
operator
concatenates two character strings to form a single character string.
In a string reduction operation, the minus sign (-) operator subtracts
one character string from another.
If the string following the minus
sign in a string reduction operation occurs more than once in the
preceding string, only the first occurrence is removed.
Some examples of string operations are listed below:

A
B

Expression

Result

"MYFILE" + ".MEM"
"FILENAME.MEM" - "FILE"
"LISTING.LIS" - "LIS"

"MYFILE.MEM"
"NAME.MEM"
"TING.LIS"

Operands in string operations are string values, symbol names
to string values, or expressions that yield string values.

3.5

equated

SPECIAL-PURPOSE STRING ASSIGNMENTS

An optional format for assigning a character string value to a
name is:

symbol

symbol-name := character string
With this form of string assignment statement, character string values
are automatically converted to uppercase.
Also,
any leading and
trailing spaces and tabs are removed, and multiple spaces and tabs
between characters are compressed to a single space.
The := format is
useful in command procedures that manipulate file specifications or
command strings. For example:
$ KILL := delete sys$batch
/entry=
$ SHOW SYMBOL KILL
KILL = "DELETE SYS$BATCH /ENTRY="
$ KILL 132
In this example, the command string assigned to the symbol KILL is
converted to uppercase,
and the multiple spaces between the command
parameters are reduced to a single space.
If you want to prohibit uppercase conversion and retain required space
and tab characters in a string, you must place quotation marks around
the string, for example:
$ NAME := "job
search"
$ SHOW SYMBOL NAME
NAME = "job
search"
3-10

USING SYMBOLS IN COMMAND PROCEDURES
You can continue a symbol assignment
example:

than

one

line.

For

string.

For

$ LONG NAME := THIS IS A VERY LONG SYMBOLNAME VALUE CONTINUED MORE THAN ONE-LINE
To assign a null string to a symbol, do not
example:

specify

$ NULL :=

3.6

REPLACING SUBSTRINGS IN CHARACTER STRING SYMBOL VALUES

A special format of the character string assignment statement allows
you to replace data within a defined substring of a value.
This
format is:
symbol-name[offset,size] := character-string-value
The offset is the position of the substring relative to the first
character in the string, and the size is the length of the substring.
The square brackets are required notation, and no spaces are allowed
between the right bracket and the colon or between the symbol name and
the left bracket. You can specify any integer expression for offset
and size.
Integer values can be in the range of 0 through 254.
This type of assignment statement evaluates the current value of
symbol-name and then replaces a specified string of characters with
the specified character string value.
For example:

$ A := ABCDEF
$ A [ 0, 3] : = DEF
The first assignment statement above gives the symbol name A the value
ABCDEF.
The second assignment statement specifies that the value DEF
replaces three characters in the value of A, beginning at an offset of
· 0 from the beginning of the string. The result is that the value of A
becomes DEFDEF.
The symbol name you specify can be undefined initially.
The
assignment statement creates the symbol name and provides leading or
trailing spaces in the symbol value if necessary.
For example:
$ B[4,3] := GHI
If the symbol named B does not have a value when this assignment
statement is executed, the resulting value of B is "
GHI", that is,
B has four leading spaces before the characters GHI.
You can use this
format to create a blank line of any number of characters.
For
example:

$ LINE[0,80] :=

" "

This assignment statement gives the symbol named LINE a value of 80
blank spaces.
The following example shows how you can use this
assignment statement syntax to align data in columns for output:
$ RECORD[0,20] := "Programmer"
$ RECORD[25,15 ] := "File Name"

3-11

USING SYMBOLS IN COMMAND PROCEDURES
These two assignment statements construct a value for the symbol
RECORD.
The first statement fills in the first 20 columns of the
value; the second statement fills in columns 26 through 40.
Columns
20 through 24 contain blanks.
The sample procedure LISTER.COM in Appendix A illustrates further uses
of replacing character strings in assignment statements.
Figure 3-1 illustrates some applications of string substitutions using
offsets. In the figure, substitutions change the current value of the
symbol FILENAME from its
initial
assignment,
MYFILE.DAT,
to
TRTEST.DAT;l.
Then, the current value of the symbol COMMAND is
combined with the string TRTEST.DAT.;l to produce a new assignment for
COMMAND.
Interactive Assignment

Resulting Symbol Value

Comments

FILENAME:=MYFILE.DAT

MYF I LE. DAT

The result is the initial value of symbol
FILENAME

FILENAME[012J:=TR

TR F I LE • DAT

Two characters starting at offset 0 are overlaid

FILENAME[214J:=TESTING.LIS

TRTEST. DAT

When the string value is longer than the character count the value is truncated to the count

FILENAME[1012J:=;1

TRTEST. DAT; 1

When the length of the string is equal to the
value of the offset, the string is appended to
the current value

·COMMAND:= TY PE

TYPE

This is the initial value of the symbol command

COMMAND[5113J:='FILENAME'

TYPE TR TE s T • DAT ; 1

Appends a space and the current value of
FILENAME to the TYPE command verb.
ZK-818-82

Figure 3-1:

3.7

Replacing Character Strings in Assignment Statements

ARITHMETIC OVERLAYS

One format of an arithmetic assignment statement can be used to
perform binary overlays in the current value of a symbol name. This
format is:
$ symbol-name[bit-position,size]= integer-expression
The bit-position is the location relative to bit 0 at which the
overlay is to occur, and size is the number of bits to be overlaid.
The square brackets are required notation, and no spaces are allowed
between the right bracket and the colon or between the symbol name and
the left bracket. The bit-position and size are integer expressions.
Literal values are assumed to be decimal.

3-12

USING SYMBOLS IN COMMAND PROCEDURES
This type of assignment statement evaluates the current value of the
symbol name and then replaces the specified number of bits with the
value on the right-hand side of the assignment statement.
This form of an assignment statement can store a maximum of 32 bits at
a time.
You can use this statement to equate a symbol name to a
binary value.
For example:

$ BELL[0,32]=%X07
This statement gives the symbol named BELL a value equivalent to a
hexadecimal 7,
the ASCII code for the bell character (CTRL/G) on a
terminal.
The arithmetic overlay technique
WAKEUP.COM in Appendix A.

3.8

used

the

sample

procedure

CHANGING THE CONTEXT OF A SYMBOL

After a symbol is defined, it can be interpreted as character
or integer data, depending on the context in which it is used:

string

•

It can be used in an arithmetic context,
for example,
addition, subtraction, multiplication, or division.

•

It can be used as a character string in an expression
can be concatenated or reduced with another string.

•

It can be used as a logical value and tested to see whether it
is 1 (true) or O (false).

For example, suppose a symbol, COUNT, is assigned the value
arithmetic assignment statement:

$ COUNT = 4
Then the value of COUNT can be used
such as the examples below:

other

assignment

statements

$ TOTAL = COUNT + 1

An arithmetic assignment statement
that adds the value of COUNT to the
value 1 and equates the result to the
symbol TOTAL, which now equals 5.

$ SYMBOL := P'COUNT'

A string assignment statement that
appends the character string value of
COUNT to the character P.
SYMBOL now
equals P4.

$ RESULT=TEMP.OR.COUNT

A logical OR operation on the symbols
TEMP and COUNT.
If either value is
true the symbol RESULT will have a
true value assigned to it.

If you define a null character string value for a symbol, that symbol
has a value of O when it is used in an arithmetic context.
For
example:

$ A
""
$ B
2
$ c = A + B
After these statements are executed, the symbol C has a value of 2.

3-13

USING SYMBOLS IN COMMAND PROCEDURES
Two lexical functions, F$INTEGER and F$STRING, enable you to change
the context of a particular expression.
The F$INTEGER lexical
function converts a string expression to an integer value.
The
F$STRING function converts an integer expression to a string value.
For a complete description of these two lexi~al functions, see Chapter

3.9

SYMBOL TABLES

The command interpreter maintains symbol names
values in two types of symbol table:
•

A ~ocal symbol table that
each active command level

•

The global symbol table that contains
all command levels

contains

and

their

symbols

associated

symbols

with

accessible

Symbol tables are of particular importance in the understanding of
symbol substitution.
Symbol substitution is described in full in
Chapter 4.
The following
symbols.

3.9.1

sections

describe

how

define

local

and

global

Local Symbols

The command interpreter maintains a symbol table for each active
command level.
These tables are called local symbol tables, and the
symbols they contain can be accessed only from the current command
level or from a lower command level.
For example, symbols defined by
you at your terminal can be accessed by command procedures you run
interactively, but the converse is not true.
Use a single equal sign (= or :=)
a local symbol.
For example:

in an assignment statement to define

$ COUNT = 1
$ OUTDAT = "Beginning tests •••• "
A local symbol exists as long as the command level at which it was
defined remains active,
unless the symbol is specifically deleted.
For example, if you define the symbol COUNT interactively (at command
level 0),
any command procedure you subsequently execute (until you
log out) can refer to the symbol COUNT and obtain its current value.
As
another
example, the command procedure A.COM contains the
following:

$ TOTAL
$ @B

The procedure B.COM contains the line:
$ NEWTOTAL = TOTAL + 1

When B is executed, the symbol name TOTAL is accessible and can be
referenced or replaced, because the commarid level at which TOTAL was
defined is still active.

3-14

USING SYMBOLS IN COMMAND PROCEDURES
If B.COM defines a value for TOTAL, that definition establishes a new
value for TOTAL while B is executed. When execution of B is completed
and control returns to procedure A, the value of the symbol TOTAL in A
is unchanged.
Local symbols are deleted as soon as the command procedure that
defined them exits. In the above example, the symbol NEWTOTAL defined
in the procedure B.COM is deleted when execution of B.COM is
completed.
In addition to the local symbols that you create, the local symbol
table for each command level contains eight special symbols named Pl,
P2, and so on to PS. These symbols represent values, or parameters,
that can be passed to a procedure.
The techniques for passing
parameters to command procedures are described in Section 3.10.

3.9.2

Global Symbols

In addition to the local symbol tables, the command interpreter
maintains a global symbol table.
A global symbol exists for the
duration of the process, unless specifically deleted,
and
is
recognized at any command level. To define a global symbol, use two
equal signs (== or :==) in the assignment statement. For example:
$ RESULT == 50
$ FILENAME :== MYFILE.DAT
These assignment statements define the global symbols named RESULT and
FILENAME.
Global symbols are frequently used to define command synonyms.
Normally, you would place all the synonyms in your LOGIN .• COM file to
make the definitions available for every terminal session.
These
synonyms must be defined as global symbols; otherwise, they would be
deleted as soon as the procedure LOGIN.COM was executed.
In addition to the global symbols that you create, the global symbol
table contains two special symbols whose values are set by the command
interpreter. These symbols, named $STATUS and $SEVERITY, contain
values indicating the success or failure of the most recently executed
image. For information on these symbols and how to use them in
command procedures, see Chapter 7.

3.9.3

Order of Search of Symbol Tables

When the command interpreter performs symbol substitution, it searches
symbol tables in the following order:
1.

The local symbol table for the current command level

Local symbol tables for each previous
searching backwards from the current level

The global symbol table

command

level,

You can use the SHOW SYMBOL command to display the current value of
any symbol.
By default, the SHOW SYMBOL command uses the same order
of search to locate symbol definitions, that is, it searches the local
symbol tables and then the global symbol table to locate a specified
symbol name.

3-15

USING SYMBOLS IN COMMAND PROCEDURES
3.10

PASSING PARAMETERS TO COMMAND PROCEDURES

When you develop and write command procedures, a
primary concern is
the ability to act on different data, or· parameters, each time you
execute the procedure.
The command
interpreter provides a direct
method for
specifying,
at execution or submission time, values to
correspond to symbols within the procedure.
For example, the command procedure named RUNTEST contains the lines:

$ DEFINE/USER MODE INFILE 'Pl'
$ DEFINE/USER-MODE OUTFILE 'P2'
$ RUN SORTER The program SORTER.EXE reads a file using the logical name INFILE and
writes an output file
using the logical name OUTFILE.
To assign
equivalences to these logical names, values must be provided for
Pl
and P2 when the procedure is executed.
Note, however, that Pl and P2 are special symbol names;
the command
interpreter defines eight of these special symbols for
use as
parameters within command procedures. These local symbols are named
Pl,
P2,
and so on to PS.
The command interpreter interprets them as
character string values and gives them null values by default
if you
do not specify values for them.

3.10.1

Specifying Parameters for the Execute Procedure Command

When you execute a procedure with the Execute Procedure
(@)
command,
you enter the values for Pl, P2, and so on, as command parameters, as
follows:
$ @RUNTEST INSORT.DAT OUTSORT.DAT
This command string gives the symbol named Pl a
value of INSORT.DAT
and
the symbol P2 a
value of OUTSORT.DAT.
The values for the
parameters are assigned according to the order in which you specify
them,
that is, the first parameter you enter is Pl, the second is P2.
In this example, P3 through P8 are equated to null strings because no
values are specified for them.
You can equate any parameter to a null
string by using a
set of
quotation marks as a place holder in the command string.
For example:

$ @RUNTEST "" OUTSORT.DAT
This command string sets the parameter Pl to a null string
P2 a value of OUTSORT.DAT.

3.10.2

and

gives

Delimiting Parameters

When you specify parameters for a command procedure that you execute
with the Execute Procedure (@) command, spaces in the command string
delimit parameters.
For example, the following command passes the
three parameters A, B, and c, to the procedure TESTFILE.COM:

$ @TESTFILE A B C

3-16

USING SYMBOLS IN COMMAND PROCEDURES
To

pass

parameter that contains lowercase
letters,
special
or embedded blanks, enclose the entire parameter in
quotation marks. For example:
character~,

$ @TESTFILE "lowercase parameter"

When the procedure TESTFILE.COM
equated to the string:

executed,

the

parameter

lowercase parameter
When you specify parameters, you can specify a string with embedded
quotation marks.
In this case, the quotation marks are preserved in
the string. For example:
$ @TESTFILE abc"def"ghi

In this example, the parameter Pl is equated to the·string:
ABC"def"GHI
The characters that are not within quotation marks are converted to
uppercase, but the string in quotation marks, including the quotation
marks, is left intact.

3.10.3

Passing Parameters to Batch Jobs

To pass parameters to a batch job with the
/PARAMETERS qualifiers, as follows:

SUBMIT

command,

use

the

This SUBMIT command passes the string AVERAGE as the parameter Pl
the procedure TESTFILE.COM.

for

$ SUBMIT TESTFILE/PARAMETERS=AVERAGE

Commas delimit parameters within a list for the SUBMIT command.
When
you specify more than one parameter, separate them with commas and
enclose them in parentheses as in the following example.
$ SUBMIT RUNTEST/PARAMETERS=(INSORT.DAT,OUTSORT.DAT)

Within the parameter list for the SUBMIT command, you can equate a
parameter to a null string by using a set of quotation marks as a
place holder. For example:
$ SUBMIT RUNTEST/PARAMETERS=("",OUTSORT.DAT)

This SUBMIT command equates the parameter Pl
gives P2 a value of OUTSORT.DAT.

null

string

and

Note that you can submit more than one file for batch execution in a
single SUBMIT command. If you specify parameters with the /PARAMETERS
qualifier when you submit a list of command procedures, however, the
parameters you specify are equated to Pl, P2, and so on in each file
you specify. For example:
$ SUBMIT TESTA,TESTB/PARAMETER=lO

When the procedure TESTA is executed in the batch job, the symbol
named Pl has the value of 10. When execution of TESTA is completed
the job executes TESTB; in TESTB also, the symbol Pl has the value of
10, unless the procedure TESTA redefines the value of Pl.

3-17

USING SYMBOLS IN COMMAND PROCEDURES
You can also use the /PARAMETERS qualifier on a JOB command when you
submit batch jobs through the system card reader. The syntax for
specifying parameters on the JOB card is identical with th~ syntax of
specification on the SUBMIT command. For example, a batch job could
refer to symbols Pl and P2. When you place cards in the card reader,
the JOB card could be continued onto a card that specified different
values for these parameters for different runs of the procedure.
The
JOB command might appear as shown on the two cards illustrated in
Figure 3-2.

ZK-819-82

Figure 3-2:

3.10.4

Using a /PARAMETERS Qualifier Card

Redefining Parameters

The symbol names Pl through PB, although defined by default if not
specified, are not reserved to the command interpreter. You can, in
your command procedures, define values for these symbol names or
redefine them, as needed. For example:
$ Pl = Pl - 1

This assignment statement assumes
decreases the current value by
symbol Pl as an integer value.

that Pl has an integer value,
one, and then stores it in a local

Another example is:
$ IF Pl .EQS.

"" THEN INQUIRE Pl "Input file name"

This command checks whether a value was specified for Pl; if not, the
INQUIRE command requests interactive assignment of a value for Pl.
The IF command is described in Chapter 6.
The INQUIRE command is
described in the following section.

3.11

THE INQUIRE COMMAND

When you execute a command procedure interactively, you can use the
INQUIRE command to define a value for a symbol.while the command
procedure is executing. When the INQUIRE command is executed from the
command procedure, the command interpreter issues a prompting message
to SYS$COMMAND, that is, the terminal; the text of the message is
taken from the INQUIRE command line, as shown in the example below.

3-18

USING SYMBOLS IN COMMAND PROCEDURES
The procedure RUNTEST contains the lines:
$
$
$
$
$

INQUIRE IN "INPUT FILE"
INQUIRE OUT "OUTPUT FILE"
DEFINE/USER MODE INFILE 'IN'
DEFINE/USER=MODE OUTFILE 'OUT'
RUN SORTER

When you execute this procedure, the terminal interaction might appear
as follows (if SET NOVERIFY is in effect):
$ @RUNTEST (Bill
INPUT FILE: DBAl:INSORT.DAT(Bill
OUTPUT FILE: DBA2:0UTSORT.DAT~
$
When these INQUIRE commands are executed, the prompting messages INPUT
FILE:
and OUTPUT FILE:
are displayed, and you must enter values for
the symbols IN and OUT before the command procedure continues.
The
prompt strings INPUT FILE and OUTPUT FILE are optional parameters for
the INQUIRE command;
if you do not specify them, the command uses the
symbol names IN and OUT to prompt for values.
By default, the INQUIRE command appends a colon (:) and a space to the
prompt string;
you do not need to include them when you specify the
prompt string to the INQUIRE command.
If you do not want the colon
and space to be appended to the prompt string, use the /NOPUNCTUATION
qualifier, as described in the VAX/VMS Command Language User's Guide.
Note that you can request a lowercase prompting message or a prompting
message that contains special characters or blanks by enclosing the
prompt string in quotation marks, as shown below:
$ INQUIRE FILE "Enter name of file to edit"
When this INQUIRE command is executed, the following prompting message
is displayed on SYS$COMMAND (normally, the terminal):
Enter name of file to edit:
The symbol name FILE and the value you enter in response to this
prompt are placed
in the local symbol table for the current command
level.
The INQUIRE command also accepts entries for the global symbol table.
To define a globai symbol name with the INQUIRE command, use the
/GLOBAL qualifier.
For example:
$ INQUIRE/GLOBAL FILE "Enter name of file to edit"
When you respond to this prompt, the symbol name FILE
the global symbol table with whatever value you enter.

entered

When you do not enter any data in response to an INQUIRE command,
specified symbol name is given a null value.
For example:

in
the

$ INQUIRE FILE "File"
$ IF FILE .EQS.
"" THEN EXIT
In the above example, the INQUIRE command is followed by a test to
determine whether a value was entered.
If not, the procedure exits.
The sample procedures EDITALL.COM and
illustrate the use of this technique.

3-19

CALC.COM

Appendix

USING SYMBOLS IN COMMAND PROCEDURES
3.12

DELETING SYMBOLS

The DELETE/SYMBOL command deletes symbols. You can delete one or all
local symbols from the local symbol table for the current command
level or one or all global symbols from the global symbol table.
For
example, the following command deletes the local symbol named TOTAL:

$ DELETE/SYMBOL TOTAL
The /GLOBAL qualifier indicates that a global symbol is to be deleted.
For example:

$ DELETE/SYMBOL/GLOBAL/ALL
This command de.letes all global symbols.
Because the command interpreter automatically deletes local symbol
tables when a command procedure exits, you do not normally need to
delete symbols. However, if you have defined many global symbols for
command synonym definitions or
if you execute a procedure that
requires many local symbols or many symbols with character string
values, you may run out of symbol table space.
The maximum number of symbols that can be
depends on:

defined

any

one

time

•

The amount of space available to the command interpreter to
contain local and global symbol tables and labels for the
current process. The amount of space is determined for each
process
by
the
SYSGEN parameter CLISYMTBL.
For more
information on this parameter,
see the
VAX/VMS
System
Management and Operations Guide.

•

The size of the symbol names and their values.
The command
interpreter incurs 14 bytes of overhead for every symb?l
definition, and it allocate~ space for symbol definitions in
8-byte
increments.
For example,
24 bytes are required to
maintain the average symbol name and its value, which together
would consist of from 5 to 12 characters (bytes).

When the command interpreter
following warning message:

runs

out

space,

issues

the

%DCL-W-SYMOVF, no room for symbol definitions
Then, it takes
conditions.

whatever

action

currently

defined

for

warning

If a command procedure that you are developing exhausts symbol table
space,
try to recreat~ the procedure using nesting (as described in
Section 6.3), so that inactive symbols will be deleted when the
procedure that defines them exits.
Or, you can delete all global
symbol table definitions for command synonyms before you execute the
command procedure (as described above).

3-20

CHAPTER 4
SYMBOL SUBSTITUTION IN COMMAND PROCEDURES

While it processes a command string, the command interpreter performs
symbol substitution by replacing symbol names in the command string
with their current values. To use symbols in . commands and command
procedures, you will need to understand the mechanics of symbol
substitution discussed in this chapter:

4.1

•

How the command interpreter handles command synonyms
4.1)

•

How to use the substitution operators, the apostrophe (')
ampersand (&) characters (Sections 4.2 and 4.4)

•

When the command
(Section 4.3)

•

How to use repetitive and iterative substitution (Section 4.5)

•

What happens to symbols that
remain
undefined
command-interpreter processing (Section 4.6)

•

How to verify that symbol substitution
4.7)

interpreter

performs

automatic

takes

(Section
and

evaluation

place

during
(Section

COMMAND SYNONYM SUBSTITUTION

When the command interpreter processes a command string, it examines
the first token in the command string to determine whether it is a
symbol name.
A token is a nonblank character string that is
terminated with a blank or a special character. In this context, a
special character is any character that is not valid in a symbol. name.
If the token represents a symbol, the command interpreter replaces the
symbol name with its current value. Then, it executes the command
string.
For example, the following assignment
PDEL as a command synonym:

statement

defines

the

symbol

$ PDEL = "DELETE SYS$PRINT/ENTRY="
Then PDEL is used as the first token in a command string:
$ PDEL 181
The command interpreter replaces
executes the command string:

PDEL

DELETE SYS$PRINT/ENTRY=l81

4-1

with

its

current

value

and

SYMBOL SUBSTITUTION IN COMMAND PROCEDURES
In this example, the command synonym PDEL is delimited with a blank
character.
Note that, depending on the command, other characters can
serve as delimiters.
In the following example, the left parenthesis
delimits the symbol name PDEL because the parentheses are valid
delimiters:
$ PDEL(l81,182,183)
This command deletes three jobs in the queue SYS$PRINT.

4.2

USING APOSTROPHES AS SUBSTITUTION OPERATORS

When you use a symbol name in place of a command parameter or
qualifier, you must use an apostrophe
(') to request the command
in~erpreter to replace the symbol name with its
current value.
For
example:
$ TYPE 'FILENAME'
In this example, the string FILENAME is a symbol name used as a
parameter for the TYPE command;
the apostrophes surrounding the
string indicate to the command interpreter that FILENAME is a symbol
name and not a literal string.
You can concatenate two or more symbol names in a command
shown in the following example:

string,

$ NAME = "MYFILE"
$ TYPE= ".TST"
$PRINT 'NAME''TYPE'
If this example is executed,
MYFILE.TST.

the

command

queues

Note that you must properly delimit symbol names
by
apostrophes around each symbol name in the command string.

4.2.1

copy

placing

Substitution within Character Strings

Within character strings enclosed in quotation marks, you can request
·symbol substitution by placing two apostrophes before the symbol name
and one apostrophe following it. For example:
$PROMPT STRING= "Creating file' 'FILENAME'~TST"
If the current value of the symbol named FILENAME
symbol name PROMPT STRING is given the value:

WIDGET,

the

Creating file WIDGET.TST

4.3

AUTOMATIC EVALUATION

The command interpreter assumes, in certain contexts, that a string of
characters beginning with an alphabetic character is a symbol name.
In these contexts, evaluation is automatic and you need no~ delimit
symbol names with apostrophes. In fact, if you use apostrophes, the
results are quite different because iterative substitution will occur
(see Section 4.5).

4-2

SYMBOL SUBSTITUTION IN COMMAND PROCEDURES
Symbol evaluation is automatically performed in expressions in:
•

Assignment statements using = or == (not := or:==)

•

Tokens enclosed in brackets
assignment ~tatements

•

Lexical function processing
(see
Functions in Command Procedures)

•

IF commands
Procedures)

the

left-hand

Lexical

Command

•

WRITE commands (see Chapter 8, Creating, Reading, and
Files)

Writing

The DEPOSIT and EXAMINE commands
(the DEPOSIT and EXAMINE
commands provide an interactive debugging capability at the
command level;
for descriptions of these commands, see the
VAX/VMS Command Language User's Guide)

Chapter

Execution

Using

(see

Chapter

side

Flow

It is important to note that, in any of these contexts, the command
interpreter assumes that any string of characters beginning with an
alphabetic letter is a symbol name and that any string of characters
beginning with an arabic numeral or with the radix operator (%) is a
literal numeric value.
For example, when you use an arithmetic
expression on the right-hand side of
automatically as follows:

assignment statement, the
the statement is evaluated

$.TOTAL= COUNT+ 1
No apostrophes are needed to request substitution for the symbol COUNT
in
this
assignment
statement because the command interpreter
automatically substitutes values for symbols as it executes arithmetic
assignments.
Similarly, in an IF command:
$ IF A .EQ. B THEN GOTO NEXT
In the example above, the IF command assumes that both A and B are
symbol names and uses their current values to test their equality. No
apostrophes are necessary.

4.4

USING AMPERSANDS AS SUBSTITUTION OPERATORS

In addition to the normal'substitution operator,
the apostrophe
(')
described
above,
the command interpreter recognizes a special
operator, the ampersand (&).
In many usages, the two operators are
functionally equivalent.
For example,
the following two commands
would have the same result if the string FILENAME is currently equated
to a character string value:
$ TYPE 'FILENAME'
$ TYPE &FILENAME
In the first command, the command interpreter replaces the string
FILENAME with its current value just after it has read the command
input. The second command replaces the string FILENAME with its
current value while it is analyzing, or parsing, the command.

4-3

SYMBOL SUBSTITUTION IN' COMMAND PROCEDURES
The following examples show how the results can vary depending on
whether you use an apostrophe
(')
or an ampersand
(&)
as the
substitution operator:.

$ B = "MYFILE.DAT"
$ A := &B
$ B = "NEWFILE.TMP"
$ TYPE 'A'
In this example, the second assignment statement equates the symbol
name A to the current value of B (MYFILE.DAT) as the line is scanned,
but substitution is not made. Thus, when the current value of B is
redefined in the third assignment statem~nt, the new current value of
B (NEWFILE.TMP) is equated to A. The TYPE command, when executed,
displays the file NEWFILE.TMP.
The use of an ampersand
(&) as
syntactically similar to the use
following exceptions:

a
of

substitution
operator
is
an apostrophe('), with the

•

You cannot use an amper~and within a character string;
that
is, an ampersand must follow a delimiter (any blank or special
character) •

•

You cannot use ampersands to request substitution
character strings enclosed in quotation marks.

within

•

You cannot use ampersands to concatenate two
names.

symbol

•

You cannot terminate a symbol name with an ampersand.

Ampersands are most effective as substitution operators when they are
used with apostrophes to provide iterative substitution, as described
in the next section.

4.5

REPETITIVE AND ITERATIVE SUBSTITUTION

Substitution is either repetitive or iterative when substitution for a
symbol or token in a command string occurs more than once during the
processing of a single command string.
Specifically,
repetitive
substitution results when more than one type of substitution occurs in
a single command string.
Iterative substitution occurs when the
command interpreter examines the value substituted to see if the value
itself is a symbol.
This happens automatically when you use an
apostrophe as a substitution ~perator.
By understanding the order in which the command interpreter performs
different
types
of
symbol substitution, you can control how
substitution occurs in your command procedures.

4.5.1

Steps in Symbol Substitution

The command interpreter performs symbol substitution in
of command processing. These phases are:
1.

three

phases

Command input scanning. During this phase, also called the
lexical input phase,
the command interpreter reads the
command input and replaces all tokens that are preceded with
apostrophes
(or double apostrophes, for strings within
quotation marks) •

4-4

SYMBOL SUBSTITUTION IN COMMAND PROCEDURES
2.

Command parsing. During this phase, the command interpreter
analyzes the command string:
(1) it determines whether the
first token is a command synonym and, if it is, replaces it
with its current value and
(2) performs all substitution
requested with ampersands.

Expression evaluation.
During this phase,
the
command
interpreter replaces symbols during the actual execution of a
command, for example, the IF command. This substitution is
not, by default, iterative.

Figure 4-1 illustrates a command procedure, DOIT.COM, that contains a
command string on which substitution is performed three times, each
time during a different phase of command processing.
$
$

COUNT = 1
@DOIT ABC.DAT;!

DBA1:[HIGGINS] DOIT.COM
8 ~~~~~~~~~~~~~~~,...-~~~~~~~~~~~~~--

IF p I COUNT I . NES.
DELETE B:P 'COUNT

II II

THEN -

E>< IT

0 The symbol name count is assigned the value 1.
8 The command procedure DOIT.COM is invoked; and is passed a parameter, the file ABC.DAT;1.
C) The IF command is processed by the command interpreter in three phases.
First, command input scanning: all substitution requested by the use of apostrophes is performed; the result is:
IF Pl

.NES.

1111

THEN DELETE B:P1

Second, command parsing: all substitution requested by the use of ampersands is performed; the result is:
IF Pl

.NES,

1111

THEN DELETE ABC.DATi1

Third, command execution: all character strings used as expressions are evaluated and substitution is performed on
these strings. The command line executed is:
IF ABC,DATi1

.NES,

1111

THEN DELE;,TE ABC.DAT;!
ZK-821-82

Figure 4-1:

Example of the Three Phases of Symbol Substitution

Note that the command interpreter does not scan, and therefore does
not perform substitution on, any lines in a command procedure that are
read as input data by commands or programs executed within the
procedure. For example:
$ RUN AVERAGE
55
55
9999
The program AVERAGE reads from SYS$INPUT, that is, the command input
stream. The data lines 55, 55, and 9999 are never read by the command
interpreter. Thus, in this context you cannot use symbol riames.

4.5.2

Iterative Substitution Using Apostrophes

When you use an apostrophe to request symbol substitution, the command
interpreter performs iterative substitution from left to right in the
4-5

SYMBOL SUBSTITUTION IN COMMAND PROCEDURES
command string. This means that for each token on the line,
the
string resulting from the substitution is scanned again to determine
whether the string contains any
apostrophes.
If
there
are
apostrophes, the command interpreter performs substitution and again
examines the resulting string for apostrophes.
Figure 4-2 illustrates a simple case of iterative substitution.
Note
that the command interpreter repeats the substitution as many times as
necessary to complete the substitution of a value for the token;
there is no practical limit to the layers of symbol definition.
DBA 1:[HIGGINS]TYPE.COM

0
8

$FILE:= "'A'"
$ A := MYFILE+DAT

$TYPE 'FILE'

E)<I T

O The symbol name FILE is equated to the value 'A' while the quotation marks prevent the command interpreter from
substituting a value for 'A' -

in fact, there is no value for A yet defined.

fJ A is equated to the file MYFILE.DAT

0 When the command interpreter scans this TYPE command, it substitutes the current value of 'FILE', resulting in
TYPE 'A'
Since the current value contains apostrophes, the command interpreter scans the line again (substitution recurs) and
substitutes the value of ·A.'. The command string executed is:

TYPE MYFILE.DAT

Figure 4-2:

ZK-822-82

Example of Iterative Substitution

Substitution using apostrophes is not, however, iterative when values
are substituted for symbols within strings that are enclosed in
quotation marks. For example:
$ SYMBOL = "NAME"
$A= "'SYMBOL'"
$' B = 'A'
After the last assignment statement in this example is executed,
the
resulting value of the symbol B is NAME. This result is achieved in
the following steps:
•

The symbol name A is replaced with its current value:
'SYMBOL'

•

Because this value has apostrophes in i~,
the
command
interpreter replaces the value SYMBOL with its current value:
NAME

•

Because this value has no apostrophes, it is the
given to the symbol name B.

4-6

final

value

SYMBOL SUBSTITUTION IN COMMAND PROCEDURES
Note, however, what happens if you define B as follows:
$ B ="''A"'

In this case, B has the value 'SYMBOL'. The symbol name A is replaced
only once because substitution is never iterative within character
strings enclosed in quotation marks.

4.5.3

Iterative Substitution Using Command Synonyms

The command interpreter performs iterative substitution automatically
only when an apostrophe is in the command string.
In some cases, you
may want to nest command synonym definitions, as follows:

$ COMMAND

$ EXEC

"TYPE A.B"

"'COMMAND' "

$ EXEC
In this example, when the command synonym EXEC is processed,
the
command interpreter performs substitution only once. The resulting
string is 'COMMAND';
the command interpreter issues an error message
because it cannot detect a command on the llne. To correctly use the
command synonym EXEC, you must enclose it in apostrophes, as shown
below:

$ 'EXEC'
Figure 4-3 shows another example of using an apostrophe with a command
synonym to force iterative substitution.
The example shows the
results of substitution first, without using an apostrophe and then,
the results of substitution when an apostrophe is specified. The
procedure in Figure 4-3 is similar to the GETPARMS.COM procedure in
Appendix A.

4.5.4

Iterative Substitution Using Ampersands

An ampersand as a substitution operator is most effective when you
want substitution to occur from right to left on a token. A common
use was shown in Figure 4-1:
to use the same command string to
process multiple parameters
(or symbol names assigned incremental
values), you must use an ampersand so that iterative substitution
occurs in -the correct order.
For example, the command string in
Figure 4-1 uses the following syntax:
$ DELETE &P'COUNT'
This causes the command interpreter to first replace the symbol COUNT
with its value and then, during parsing, to replace the symbol Pl with
its value. Note what would happen if the token were specified as
follows:
$DELETE 'P''COUNT'

4-7

SYMBOL SUBSTITUTION IN COMMAND PROCEDURES
In this example, the command interpreter, during initial scanning of
the command, performs normal left-to-right substitution.
I~ attempts
to replace the separate tokens P and COUNT.
Because P is not a
defined symbol, only COUNT is replaced. The DELETE command string
would be:
DELETE 1
The action the command interpreter takes when a symbol is undefined
depends on. the context of the command.
For additional details, see
Section 4.6.
For an example of using iterative substitution to process parameters
passed to a command procedure, see the procedure in Section 6.1.2.

$
$

GETPARMS:=="@GETPARMS Ip 1
@TESTPARM A B c
PB
PB
P7
P7
PG
PG
P5
P5
P4
P4
P3
P3
P2
P2
Ip 1
P1
PB
P7
PG
P5
P4
D
c
P3
B
P2
P1
A

of)

I
I

~·0

OBA 1:[HIGGINS]TESTPARM.COM

0
0

$
$
$

GET PARMS
'GET PARMS
E)-(IT

OBA 1:[HIGGINS]GETPARMS.COM

G· f)

$
$

SHOW SYMBOLS/ALL
E)OT

0 Global symbol GETPARMS is defined. Quotation marks prevent the command interpreter from substituting values for
P1-P8 when it assigns a value to GETPARMS.

8 TESTPARM.COM is invoked, and passed four parameters.
0 The command interpreter substitutes the current value of GETPARMS during command parsing because it is the first
token in a command string. The command synonym is executed; there is no recursion.

Q GETPARMS.COM is invoked. The parameters passed to it have not been replaced because these symbol names

contain apostrophes. The result of the SHOW SYMBOL command is displayed at G).
(i) TESTPARM.COM resumes execution here. Because an apostrophe precedes the command string, the command
interpreter is forced to perform recursive substitution before it executes the command.

f) GETPARMS.COM is invoked. The parameters are substituted and the results displayed at (!).
ZK-823-82

Figure 4-3:

4.5.5

Iterative Substitution Using a Command Synonym

Iterative Substitution in Expressions

When the command .interpreter analyzes an expression in a command,
any
symbols specified in the expression are replaced only once;
iteration
is not automatic. You can, however,
force iteration by using an
apostrophe or an ampersand in the expression. When you design a
procedure to force iteration in this way, you must remember:

4-8

SYMBOL SUBSTITUTION IN COMMAND PROCEDURES
•

The command interpreter performs all substitution requested by
apostrophes and ampersands before the command string is
executed.

•

Commands that automatically perform symbol substitution do so
after the command string has been processed by the command
interpreter.

The following example illustrates
command:

iterative

substitution

$ IF P'COUNT' .EQS. "" THEN GOTO END
When the command interpreter scans this input line,
it replaces the
symbol name COUNT with its current value.
If the current value of
COUNT is 1, the command string, after scanning, is:
IF Pl .EQS. "" THEN GOTO END
Because this string has no apostrophes, the command interpreter does
not perform any more substitution:
however, when the IF command
executes, it automatically evaluates the symbol name Pl and replaces
it with its current value.
Note, however, that if the token resulting from substitution by the
command interpreter is not a valid symbol name, the command will fail
because a symbol is undefined.
For example:

$ FILENAME = "A.B"
$ IF 'FILENAME' .NES. "" THEN TYPE 'FILENAME'
When the command interpreter processes this command string,
it
replaces the symbol name FILENAME with its current value. After
substitution, the command string is:
IF A.B .NES.

"" THEN TYPE A.B

Because A.B is not a valid symbol, an error occurs.
For this IF
command to be processed correctly, you must omit the apostrophes, as
shown below:

$ IF FILENAME .NES.

"" THEN TYPE 'FILENAME'

Apostrophes are required
in the TYPE command string because the
command interpreter does not automatically replace symbols in TYPE
commands.
For an example of using an apostrophe in an arithmetic assignment
statement to force iteration, see the sample procedure CALC.COM in
Appendix A.

4.6

UNDEFINED SYMBOLS

If a symbol is not defined when it is used in a command string, the
command interpreter either issues an error message or replaces the
symbol with a null string or a O, depending on the context. The rules
are:
•

During command input scanning and during command parsing,
the
command interpreter replaces all undefined symbols that are
preceded with apostrophes or ampersands with null strings or
zeros.

4-9

SYMBOL SUBSTITUTION IN COMMAND PROCEDURES
•

During expression evaluation, the command interpreter issues a
warning message and does not complete command processing.

These rules are most easily illustrated by comparing special-purpose
string assignment statements with arithmetic assignments statements.
In a special purpose string assignment statement, the value on the
right-hand side is assumed to be literal character data. You must use
an apostrophe to request substitution to occur before a symbol name is
assigned a value. For example:

$ TYPE := .TST
$ FILE := MYFILE'TYPE'
$ PRINT 'FILE'
In this example, the symbol name is replaced with its current value
while the command input is read;
the assignment statement gives the
symbol FILE a value of MYFILE.TST.
If a symbol name does not have a
value,
the command interpreter, by default, replaces the symbol name
in the command string with a null string. In the above example, if
TYPE is not defined, the command interpreter gives the symbol FILE a
value of MYFILE.
Note that, to the command interpreter, a null string can be a
meaningful construct.
In the above example, the absence of a file
type in the file specification for the PRINT command causes the PRINT
command to use the default file type of ~IS.
In an arithmetic assignment, however, the value of the right-hand side
is evaluated as an expression, which must have a value. For example:
$ A
1
$ B
2
$ c = A + B

In this case, the symbols A and B must have values or the expression
that assigns a value to C is meaningless.
If A or B is not defined,
the command interpreter issues a warning message and does not give a
value to c. Note that if either A or B is defined as a null string,
the command interpreter assumes it has a value of O;
then,
the
expression is valid.

4.7

VERIFICATION OF SYMBOL SUBSTITUTION

The SET VERIFY and SET NOVERIFY commands control whether the command
interpreter displays lines in a command procedure as it executes them.
When verification is in effect, the command interpreter displays each
command line after it has completed initial scanning and before the
command is parsed and executed. Thus, you see displayed the res~its
of symbol substitution performed during scanning, but not the results
of symbol substitution performed during command parsing and execution.
For example:
$ SET VERIFY
$ COUNT = 1
$ IF P'COUNT'

.NES. "" THEN GOTO &P'COUNT'

When this procedure is executed interactively, the following lines are
displayed on the terminal:

$ COUNT = 1
$ IF Pl .NES. "" THEN GOTO &Pl
The SET VERIFY command is not displayed unless verification is already
in effect.
4-10

CHAPTER 5
USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES

The command language includes constructs, called lexical functions,
that return information about the current process and about arithmetic
and string expressions. The functions are called lexical functions
because the command interpreter evaluates them during the command
input scanning (or lexical processing) phase.
You can use lexical functions in any context in which you normally use
symbols, expressions, or literal values.
In command procedures, you
can use lexical functions to translate logical names,
perform
character string manipulations, and determine the current processing
mode of the procedure.

5.1

THE FORMAT OF LEXICAL FUNCTIONS

The general format of a lexical function is:
F$function-name([args, ••• ])
F$
Indicates that what follows is a lexical function.
Note that in
forward GOTO commands the command interpreter evaluates lexical
functions while it searches for the specific label.
function-name
Specifies the function to be evaluated. All function names are
keywords.
You can truncate function names to any unique
abbreviation.
(

)

Enclose function arguments, if any. The parentheses are required
for all functions,
including functions. that do not accept any
arguments.
args, •••
Specify arguments for the function, if any.
You can specify arguments using any of the following:
•

Integer values

•

Numeric string or
quotation marks)

character

5-1

string

values

(enclosed

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
•

Symbols

•

Other lexical functions

•

Expressions equivalent to any of the above {see Section
for a description of expressions)

3.1.1

All arguments specified for lexical functions that begin
with
alphabetic characters are assumed to be symbol names;
therefore,
substitution is automatic.
T~ble

5-1 summarizes the lexical functions,
their formats, and the
information returned by each. The remainder of this chapter describes
lexical functions in more detail and gives examples of their use.
Table 5-1:

Summary of Lexical Functions

Function

Value Returned

F$CVSI(bit-position,width,string)

Signed value extracted
the specified string

from

F$CVUI{bit-position,width,string)

Unsigned value extracted from
the specified string

F$CVTIME{time)

Standard ASCII date and time
string
of
the
form
dd-mmm-yyyy hh:mm:ss:cc converted to a string of the
form yyyy-mm-dd hh:mm:ss:cc

F$DIRECTORY{)

Current
default
name
string,
brackets

F$EXTRACT{offset,length,string)

Substring
beginning
at
specified
.offset
for
specified length of indicated
string

F$FAO{control-string
[,argl,arg2, ••• argl5])

Specified control string
converted to
a
formatted
ASCII output string

F$FILE ATTRIBUTES
{file-spec,item)

File
attribute information
about the specified file

F$GETDVI{device-name,item)

Specific device information
about the specified device

F$GETJPI{pid,item)

Accounting,
status,
and
identification
information
about the specified process

F$GETSYI{item)

Status
and
identification
information about the system

directory
including

{continued on next page)

5-2

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
Table 5-1 (Cont.):

Summary of Lexical Functions

Function

Value Returned

F$INTEGER(expression)

Integer equivalent of
the
result
of
the
specified
string expression

F$LENGTH(string)

Length of specified string

F$LOCATE(substring,s~ring)

Relative offset of specified
string
substring
within
indicated; or, the length of
the string if the substring
is not found

F$LOGICAL(logical-name)

Equivalence name of specified
logical
name
(first match
found in ordered search of
process, group,
and system
logical name tables); or, a
null string if no match is
found

F$MESSAGE(status-code)

Message text associated with
the specified integer status
code value

F$MODE ()

One of the character strings
"INTERACTIVE",
"BATCH", or
"NETWORK"

F$PARSE(file-spec
[,default-spec]
[,related-spec] [,field])

Either the full file specification for the specified
file or the particular file
specification field that you
specify

F$PID(context-symbol)

Process identification
number

F$PRIVILEGE(privstates)

Either "TRUE"
or
"FALSE"
depending
on whether your
current process
privileges
match the privilege states
listed in the argument

F$PROCESS ()

Current process name string

F$SEARCH(file-spec
[,stream-id])

Full file specification
of the file that matches the
specified file specification

F$SETPRV(privstates)

List of keywords indicating
the previous state of the
specified privilege states;
in addition, sets the piocess
privileges to
the
states
given in the arguments

(pid)

(continued on next page)

5-3

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
Table 5-1 (Cont.):

Summary of Lexical Functions

Function

Value Returned

F$STRING(expression)

Numeric string equivalent of
the result of the specified
arithmetic expression

F$TIME()

Current date and time of day,
in the format:
dd-mmm-yyyy hh:mm:ss.cc

F$USER ()

Current user identification
code
(UIC) ,
in the format
[g ,m]

F$VERIFY([value])

If no argument is used:
numeric
value
of
1
verification is set on;
numeric
value
of
0
verification is set off

a
if
a
if

If an argument is used:
the
same value as F$VERIFY () ;
in addition, the state of the
argument's
low-order
bit
turns verification on
(if
state is.l) or off (if state
is 0)

5.2

INFORMATIONAL FUNCTIONS

The command language provides the following informational functions:
•

F$MODE returns a character string that shows the mode in which
the process is currently executing. That is, F$MODE returns
the string "INTERACTIVE", "BATCH", or "NETWORK".

F$VERIFY returns an integer value
indicating whether the
• verification
setting is currently on or off, and may turn
verification on or off.
•

F$DIRECTORY returns the current default directory name string.

•

F$PROCESS returns the character string name of the process.

•

F$USER returns the current user identification code
the process.

(UIC)

•

F$LOGICAL returns the equivalence name string of
logical name.

specified

•

F$TIME returns the current date and time.

•

F$MESSAGE returns a character string representing the
text associated with a specific system status value.

•

F$FILE ATTRIBUTES returns the specified item of file attribute
information about the specified file.
The data returned is
either in integer or string format.

5-4

message

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
F$GETDVI invokes the $GETDVI system service to return
• specified
item
of device-related information about

the
the

specified device.
•

F$GETJPI invokes the $GETJPI system service
to
return
accounting,
status, and identification information about the
specified process.

•

F$GETSYI invokes the $GETSYI system service to return
and identification information about the system.

•

F$PARSE returns either the expanded specification for the
specified file or the particular file specification field that
you specify.

•

F$Pib returns as a character string a process identification
(PID)
number and updates the context symbol to remember the
current position in the process list.

•

F$SEARCH returns the full file specification of tha file
matches the indicated file specification.

•

F$PRIVILEGE returns either "TRUE" or "FALSE"
depending on
whether your current process privileges match the privilege
states listed in the argument.

•

list of
F$SETPRV allows you to set privileges and returns a
keywords indicating the previous state of the specified
privileges.

status

that

Each of these functions is described in greater detail below.

5.2.1

The F$MODE Lexical Function

The F$MODE function is useful in command procedures that must act
differently when executed·. in batch mode than when executed in
interactive mode.
The F$MODE function has no arguments, but must be
followed by parentheses.
For example, a command procedure can use the F$MODE function to test
whether the procedure is being executed during an interactive terminal
session or within a batch or network job:
$ IF F$MODE()
$ INTDEF:

.NES.

"INTERACTIVE" THEN GOTO BATDEF

$ EXIT
$ BATDEF:

The IF command in the above example compares the character string
returned by F$MODE with the character string INTERACTIVE;
if they are
equal,
control branches to the label BATDEF.
Otherwise,
the
statements following the label INTDEF are executed and the procedure
exits before the statements at BATDEF.
In other words, this procedure
has two sets of initialization commands:
one for interactive mode and
one for batch or ·network jobs.

5-5

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
5.2.2

The F$VERIFY Lexical Function

You can use the F$VERIFY function to test or to save the current
verification setting.
If you use this function with no arqument, it
returns a value of 0 or 1, based on whether verification of command
procedures is off (0) or on (1).
The format of the F$VERIFY function is:
F$VERIFY([value])
A command procedure can save the current setting
and then later restore the setting:

before

changing

$ SAVE VERIFY = F$VERIFY()
$ SET NOVERIFY

$ IF SAVE VERIFY THEN SET VERIFY
The assignment statement saves the current verification setting before
the SET NOVERIFY command disables verification. Later, the value of
SAVE VERIFY is tested;
if it has a value of 1, verification was
prevTo.usly on;
if .so, the SET VERIFY command is executed and
verification is restored.
Otherwise, verification was initially off
and remains off.
If you use the F$VERIFY function with an argument, the function still
returns the current verification setting.
However,
the command
interpreter then examines the state of the low-order bit in the
argument and turns verification off if the value is O, or on if the
value is 1.
For example, you could construct a procedure that will not display (or
print)
commands, regardless of what the initial state of verification
is:
$ VERIFY

= F$VERIFY(O)

$ IF VERIFY .EQ.

1 THEN SET VERIFY

This procedure uses the assignment statement to set verification off
when the assignment is scanned, then restores the previous setting at
the end of the procedure. Note that this example is the same as the
previous example.

5.2.3

The F$DIRECTORY Lexical Function

The F$DIRECTORY function returns the current default directory name
string,
including square brackets ([]).
If you use the SET DEFAULT
command and specify angle brackets (<>) in a directory specification,
the F$DIRECTORY function returns angle brackets in the directory
string.
The F$DIRECTORY function has no arguments, but
parentheses.

5-6

must

followed

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
The following example shows how to use the F$DIRECTORY function to
save the name of the current default directory in a command procedure
and later restore it:
$ SAVE DIR = F$DIRECTORY(}
$ SET DEFAULT [MALCOLM.TESTFILES]

$ SET DEFAULT 'SAVE DIR'
In this example, the assignment statement equates the symbol SAVE DIR
to the current directory. Then, the SET DEFAULT command establishes a
new default directory. Later, the symbol SAVE DIR is used in the SET
DEFAULT command that restores the original default directory.

5.2.4

The F$PROCESS Lexical Function

The F$PROCESS lexical function returns the current process name
string. The F$PROCESS function has no arguments, but must be followed
by parentheses.
By default, an interactive user has a process name string that is the
same as the login user name. A batch job is given a process name in
the format _JOBxxx, where xxx is the job number assigned to the job.

5.2.5

The F$USER Lexical Function

The F$USER lexical function returns the current user identification
code
(UIC},
including brackets
([]}.
The F$USER function has no
arguments, but must be followed by parentheses.

5.2.6

The F$LOGICAL Lexical Function

The F$LOGICAL function translates a logical name and returns the
equivalence name string. The translation is not iterative, that is,
the resulting string is not checked to determine whether it is a
logical name. The function uses the normal search order to locate the
logical name:
it searches the process, group, and system logical name
tables,
in that order; and returns the equivalence name for the first
match found.
The format of the F$LOGICAL function is:
F$LOGICAL(logical-name}
The logical-name is a character string expression that is equivalent
to the literal logical name to be translated. Since the logical name
argument is case-sensitive, you must type the name in the proper case.
Upper-case conversion is not performed.
You can use the F$LOGICAL function to save the current equivalence of
a lbgical name and later restore it. The following example shows (1)
the use of the F$LOGICAL function to determine the name of the current
terminal device and
(2)
the creation of a group logical name table
entry based on the equivalence string:
$ DEFINE/GROUP TERMINAL 'F$LOGICAL("SYS$COMMAND"}'

5-7

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
This example illustrates another important point about
lexical
functions:
all
arguments . specified for lexical functions are
automatically evaluated. This means that arguments that begin with
alphabetic characters are assumed to be symbol names and the command
interpreter will attempt to replace them.
If the symbol is undefined,
the command interpreter will replace it with ~ null string. Thus,
since the argument SYS$COMMAND is not a symbol name, you must enclose
it in quotation marks.
The following example combines the F$DIRECTORY and
functions:

F$LOGICAL

lexical

$ SAVE_DIR = F$LOGICAL ( "SYS$DISK") +F$DIRECTORY ()
This assignment statement concatenates the results of two lexical
functions.
The symbol SAVE DIR consists of a full device and
directory name string.
If there is no current assignment for a specified logical name,
the
function returns a null string. Thus, to test for an unassigned name,
you could use a command similar to the following:
$ IF F$LOGICAL("INFILE")

5.2.7

.EQS.

"" THEN GOTO ASSIGN

The F$TIME Lexical Function

The F$TIME lexical function returns the current date and time string.
The F$TIME function has no arguments, but must be followed by
pa re,ntheses.
The time string returned has the following fixed, 23-character format:
dd-mmm-yyyy hh:mm:ss.cc
When the current day of the month is any of the values 1 through 9,
the first character in the returned string is a blank character;
thus, the time portion of the string is always in character position
13,
that is, at an offset of 12 characters from the be9inning of the
string.
You can use this function to time-stamp files
command procedures. For example:

that

you

create

with

In this example OUTFILE is the name of a file that is opened
writing. The WRITE command. is described in detail in Chapter 8.

for

$ TIME STAMP = F$TIME()
$ WRITE OUTFILE TIME STAMP

For another example of the F$TIME function, see Section 5.3.3.
The sample procedure CONVERT.COM in Appendix A shows how to use
time string returned by F$TIME to calculate a delta time value.

5.2.8

the

The F$MESSAGE Lexical Function

The F$MESSAGE lexical function returns the
associated with a specific numeric value.
The format of the F$MESSAGE function is:
F$MESSAGE(status-code)
5-8

message

text,

any,

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
The status-code is an integer expression.
For example, the status code %XlC is associated with the message
EXQUOTA.
To obtain the text of this message, use the F$MESSAGE
function as shown below:
$ ERROR TEXT = F$MESSAGE(%XlC)
After this assignment statement is made, the symbol ERROR TEXT has the
va.lue:
%SYSTEM-F-EXQUOTA, EXCEEDED QUOTA
Note that although each message in the system message file has a
numeric value or range of values associated with it, there are many
possible numeric values that do not have corresponding messages.
For
more information on completion status values and messages, see Chapter
7.

5.2.9

The F$FILE_ATTRIBUTES Lexical Function

The F$FILE ATTRIBUTES lexical function returns attribute information
about the- specified file. The data returned is either in integer or
string format, depending on which item you request.
The format of the F$FILE ATTRIBUTES function is:
F$FILE_ATTRIBUTES(file-spec,item)
The file-spec specifies the name of the file you are requesting
attribute information about.
You can specify the file name as a
character string expression or as a symbol equated to a string
expression.
However, you may specify only one file name. No wild
card characters are allowed in the file specification.
The item specifies which attribute of the file is to be return~d.
Specify the item as a character string expression or as a symbol
equated to a character string. The item can be any one of the VAX~ll
RMS field names listed in Table 5-2.
The following example returns the owner UIC of the file QUEST.DAT:
$ UIC = F$FILE ATTRIBUTES("QUEST.DAT","UIC")
$ SHOW SYMBOL UIC
UIC = "(023,205]"

5.2.10

The F$GETDVI Lexical Function

The F$GETDVI lexical function invokes the $GETDVI system service to
return a specified item of information about the specified device.
This function allows a process to obtain information about a device to
which the process has not necessarily assigned a channel.
The format of the F$GETDVI lexical function is:
F$GETDVI(device-name,item)
The device-name is a character string expression that may evaluate to
either a physical device name or a logical name equated to the
physical device name.
If the first character is an underscore (_),

5-9

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
the name is considered a physical device name.
Otherwise,
a single
level of logical name translation is performed, and the equivalence
name, if any, is used.
Specify the device name as a character string
expression or as a symbol equated to a character string expression.
The item specifies the type of device information to be returned.
It
may be specified as a
character string expression or as a symbol
equated to a character string expression. You can specify any one of
the items listed in Table 5-3.
Table 5-2:

F$FILE_ATTRIB.UTES Items.

Item

Attribute

Type

ALQ
BDT
BKS
BLS
CBT
CDT
CTG
DEQ
DID
DVI·
EDT
EOF
FID
FSZ
GRP
MBM
MRN
MRS
NOA
NOK
ORG
PRO
PVN
RAT
RCK
RDT
RFM

Allocation Quantity
Backup Date/Time
Bucket Size
Block Size
True If Contiguous-Best-Try
Creation Date/Time
True If Contiguous
Default Extension Quantity
Directory ID String
Device Name String
Expiration Date/Time
Number of Blocks Used
File ID String
Fixed Control Area Size
Owner Group Number
Owner Member Number
Maximum Record Number
Maximum Record Size
Number of Areas
Number of Keys
File Organization (SEQ, REL, IDX)
File Protection String
Prologue Version Number
Record Attributes (CR, PRN, FTN)
True If Read Check
Revision Date/Time
Record Format String (VAR, FIX,
VFC~ UDF, STM, STMLF, STMCR)
Revision Number
Owner UIC String
True If Write Check

Integer
String
Integer
Integer
Boolean
String
Boolean
Integer
String
String
String
Integer
String
Integer
Integer
Integer
Integer
Integer
Integer
Integer
String
String
Integer
String
Boolean
String
String

RVN

UIC
WCK

Table 5-3:
Item
ACPPID
ACPTYPE
ALL
AVL
CCL
CLUSTER

Integer
String
Boolean

F$GETDVI Items

Information Returned
ACP process ID
ACP type code ( FllCVl,
F11CV2, MTA, NET, REM)
Device is allocated
Device is available for use
Carriage control device
Volume cluster size

Type
String
String
Boolean
Boolean
Boolean
Integer

(continued on next page)

5-10

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
Table 5-3 (Cont.):

F$GETDVI Items

Item

Information Returned

Type

CYLINDERS

Number of cylinders on the
volume (disk)
Device buffer size
Device characteristics
Device class
Device-dependent information
Additional device-dependent
data
Device Name
Device type
Device is directory structured
Device marked for dismount
Device has error logging
enabled
Error count
True if device exists
Files-oriented device
Device is mounted foreign
Number of free blocks on the
volume (disk)
Device is a generic device
Device capable of providing
input
Logical volume name
Number of logical blocks on
the volume
Maximum files on volume (disk)
Device is a mailbox
Device is mounted
Mount count
Network device
Device name of next volume
in volume set (disk)
Device is capable of providing
output
Operation count
Device is an operator
UIC of device owner
Process identification of
device owner
Device has read checking
enabled
Device is record oriented
Blocked record size
Reference count of processes
using device
Device allows random access
Device name of root volume
in volume set (disk)
Device is real-time
Device is single directory
structured
Number of sectors per track
(disk)
Volume serial number (disk)
Device is shareable
Device is being spooled

Integer

DEVBUFSIZ
DEVCHAR
DEVCLASS
DEVDEPEND
DEVDEPEND2
DEVNAM
DEVTYPE
DIR
DMT
ELG
ERRCNT
EXISTS
FOD
FOR
FREEBLOCKS
GEN
IDV
LOGVOLNAM
MAXBLOCK
MAXFILES
MBX
MNT
MOUNTCNT
NET
NEXTDEVNAM
ODV
OPCNT
QPR
OWNUIC
PID
RCK
REC
RECSIZ
REFCNT
RND
ROOTDEVNAM
RTM
SDI
SECTORS
SERIALNUM
SHR
SPL

Integer
Integer
Integer
Integer
Integer
String
Integer
Boolean
Boolean
Boolean
Integer
Boolean
Boolean
Boolean
Integer
Boolean
Boolean
String
Integer
Integer
Boolean
Boolean
Integer
Boolean
String
Boolean
Integer
Boolean
String
String
Boolean
Boolean
Integer
Integer
Boolean
String
Boolean
Boolean
Integer
Integer
Boolean
Boolean

(continued on next page)

5-11

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
Table 5-3 (Cont.):

Information Returned

Type

Sequential block-oriented
device (that is, magnetic tape)
Device is software write-locked
Number of tracks per cylinder
(disk)
Volume transaction count
Device is a terminal
Unit number
Count of volumes in volume
set (disk)
Volume name
Number of current volume in
volume set (disk)
Volume protection mask
Device has write checking
enabled

Boolean

Item
SQD
SWL
TRACKS
TRANSCNT
TRM
UNIT
VOLCOUNT
VOLNAM
VOLNUMBER
VPROT
WCK

F$GETDVI Items

Boolean
Integer
Integer
Boolean
Integer
Integer
String
Int~ger

String
Boolean

The following example returns an error count for DQAO:
$ERR= F$GETDVI(" DQAO","ERRCNT")
$ SHOW SYMBOL ERR ERR = 0 Hex = 00000000 Octal = 000000

5.2.11

The F$GETJPI Lexical Function

The F$GETJPI lexical function invokes the $GETJPI system service to
return accounting, status, and identification information about the
specified process.
user privileges are
required
to
obtain
information about:
•

Other processes in the same group (GROUP privilege)

•

Any other process in the system (WORLD privilege)

The format of the F$GETJPI lexical function is:
F$GETJPI(pid,item)
The pid specifies the identification number of the process for which
information is being reported. When you specify the pid, you can
omit the leading zeroes. Specify the pid as a charact~r strirtg
expression or a symbol equated to a character string expression.
If
you specify a null string (""), the current process is used.
The item specifi~s the type of process information to be returned.
It can be specified as a character string expression or a symbol
equated to a character string expression. You may specify any one
of the items listed in Table 5-4.
The following
003B0018:

example

returns

the

user

$NAME= F$GETJPI("3B0018","USERNAME")
$ SHOW SYMBOL NAME
II
NAME = "USER

5-12

name

for

the

process

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
Table 5-4:
Item
ACCOUNT
APTCNT
AS TACT
ASTCNT
ASTEN
ASTLM
AUTHPRIV
BIOCNT
BI OLM
BUFIO
BYTCNT
BYTLM
CPULIM
CPUTIM
CURPRIV
DFPFC
DFWSCNT
DIOCNT
DI OLM
DI RIO
EFCS
EFCU
EFWM
EN QC NT
ENQLM
EXCVEC
FILCNT
FILLM
FINALEXC
FREPOVA
FREPlVA
FREPTECNT
GPGCNT
GRP
IMAGNAME
I MAG PR IV
JOBPRCCNT
LOG I NT IM
MEM

F$GETJPI Items

Information Returned

Type

Account name string
(8 characters filled with
tra i1 i ng blanks)
Active pag~ table count
Access modes with active ASTs
Remaining AST quota
Access modes with ASTs enabled
AST limit quota
Privileges the process
is authorized to enable
Remaining buffered I/O quota
Buffered I/O limit quota
Count of process buffered
I/O operations
Remaining buffered I/O count
quota
Buffered I/O byte count
limit quota
Limit on process CPU time
C?U time used in hundredths
of a second
P~ocess's current privileges
Default page fault cluster size
Default working set size
Remaining direct I/O quota
Direct I/O limit quota
Count of direct I/O operations
for the process
Local event flags 0 through 31
Local event flags 32 through 63
Event flag wait mask
Lock request quota remaining
Lock request quota limit
Address of a list of exception
vectors
Remaining open file quota
Open file quota
Address of a list of
final exception vectors
First free page at end of
program region
First free page at end of
control region
Number of pages
available for virtual memory
expansion
Global page count in working
set
Group number of UIC
Current image file name
Privileges the current
image was installed with
Number of subprocesses
owned
Process creation time
Member number of UIC

String
Integer
Integer
Integer
Integer
Integer
String
Integer
Integer
Integer
Integer
Integer
Integer
Integer
String
Integer
Integer
Integer
Integer
Integer
Integer
Integer
Integer
Integer
Integer
Integer
Integer
Integer
Integer
Integer
Integer
Integer
Integer
Integer
String
String
Integer
String
Integer

(continued on next page)

5-13

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
Table 5-4 (Cont.):
Item
MODE
OWNER
PAGEFLTS
PAGFILCNT
PGFLQUOTA
PID
PPGCNT
PRCCNT
PRCLM
PRCNAM
PRI
PRIB
PROCPRIV
SITESPEC
STATE
S'l S

TERMINAL
TMBU
TQCNT
TQLM
UIC
USERNAME
VIRTPEAK
VOLUMES
WSAUTH
WSAUTHEXT
WSEXTENT
WSPEAK
WSQUOTA
WSSIZE

5.2.12

F$GETJPI Items

Information Returned

Type

Current process mode (BATCH,
INTERACTIVE, or NETWORK)
Process identification of
process owner
Count of page faults
Current paging file
usage
Paging file quota (maximum
virtual page count)
Process identification
Process page count
Count of subprocesses
Subprocess quota
Process name
Current process priority
Process's base priority
Process's default String
privileges
Contents of per-process
site-specific longword
Process state
Process status flags
Login terminal name for
interactive users
Termination mailbox unit number
Remaining timer queue entry
quota
Timer queue entry quota
Process's UIC
User name string (12 characters
filled with trailing blanks)
Peak virtual address size
Count of currently mounted
volumes
Maximum authorized working
set size
Maximum authorized
working set extent
Current working set
size extent
Working set peak
Working set size quota
Process's current working
set size

String
String
Integer
Integer
Integer
String
Integer
Integer
Integer
String
Integer
Integer
Integer
String
Integer
String
Integer
Integer
Integer
String
String
Integer
Integer
Integer!'
Integer
Integer
Integer
Integer
Integer

The F$GETSYI Lexical Function

The F$GETSYI lexical function invokes the $GETSYI system service to
return status and identification information about the system. The
format of the F$GETSYI lexical function is:
F$GETSYI ( i tern)
The item specifies the type of information to be reported about the
system.
It can be specified as either a character string expression
or a symbol equated to a character string expression.
You can
specify any one of the items listed in Table 5-5.

5-14

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
Table 5-5:
Item
SID
VERSION
CPU

F$GETSYI Items

,,
Type

Information Returned
System identification register
System version (8 characters
filled with trailing blanks)
CPU type (1 represents VAX-11/780,
2 represents VAX-11/750,
3 represents VAX-11/730}

Integer
String
Integer

The following example returns the system identification:

$ SYSID = F$GETSYI("SID"}
$ SHOW SYMBOL SYSID
SID = 19923201 Hex = 01300101 Octal

5.2.13

= 000401

The F$PARSE Lexical Function

The F$PARSE lexical function returns either the expanded file
specification for the file you designate, or the particular file
specification field that you request.
The format of the F$PARSE lexical function is:
F$PARSE(file-spec[ ,default-spec] [,related-spec] [,field])
The file-spec is a character string expression that specifies the
name of the file to be returned. The device and directory names, if
omitted, default to your current default disk and directory names,
unless the missing fields are replaced by a default-spec or
related-spec.
If you omit the file name, file type, or version
number, a null () specification is returned unless the missing field
is specified as a default-spec· or related-spec.
Wild
card
characters are allowed in the file specification.
The default-spec is a character string expression that is a file
specification.
It is substituted in the output string if a
particular field in the file specification is missing. You can make
further substitutions in the file specification by specifying a
related-spec as a character string expression.
For a further
description of how to use the default-spec and related-spec, see the
VAX-11 Record Management Services User's Guide.
If an error is detected
returns a null string.

during

the

parse,

the

F$PARSE

NOTE
When
specifying
directories
and
devices,
whether explicitly (as a
device-spec or a related-spec)
or
implicitly (by current default), the
specified device must contain
the
specified directory.
If the directory
is not on the device, a null string is
returned.

5-15

function

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
In the following example, the F$PARSE lexical function
expanded file specification for the file JAMES.MAR:

returns

the

$SET DEF DBA2:[FIRST]
$SPEC= F$PARSE("JAMES.MAR","[ROOT]")
$ SHOW SYMBOL SPEC
SPEC= "DBA2:[ROOT]JAMES.MAR;"
The default device and directory in this example is DBA2: [FIRST].
Since the directory name
[ROOT]
is specified as the default
directory in the symbol assignment, it is substituted for [FIRST] in
the output string.
If
(ROOT]
was not on DBA2:, however, a null
string would be returned. Note that the default device returned in
the output string is DBA2:
and the default version number for the
file is null.
The field argument causes the F$PARSE lexical function to return a
specific portion of a file specification. The field name cannot be
abbreviated. You can specify any one of the following field names:
NODE
DEVICE
DIRECTORY
NAME
TYPE
VERSION

Node name
Device name
Directory name
File name
File type
File version number

The F$PARSE lexical function in the following
directory name of the specified file:

example

returns

the

Note that since the default-spec and related-spec are omitted
the argument list; commas (,) must be inserted in their place.

from

$SET DEFAULT DBl:[VARGO]
$ SPEC = F$PARSE ("INFO. co~f" , , , 'II DlRECTO'tU(")
$ SHOW SYMBOL SPEC
SPEC= "[VARGO]"

5.2.14

The F$PID Lexical Function

The F$PID function returns, as a character string, a process
identification
(PIO)
number and updates the context symbol to
remember the current position in the process list. You can use the
F$PID function to obtain the PIDs of all processes in your group or
on the system. The format of the F$PID lexical function is:
F$PID(context-symbol)
If the context symbol is undefined or equated to a null string (""),
F$PID returns the first PID in the process list. The PID of your
process is returned if you lack GROUP or WORLD privilege.
If you
have GROUP privilege, the first PIO in your group list is returned.
If you have WORLD privilege, the first PID in the system list is
returned.
Once the context symbol
is initialized, each subsequent F$PID
function returns the next PID in sequence, and updates the context
symbol. After the last PID in the process list is returned,
the
F$PID function returns a null string.

5-16

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
Th.e following command procedure displays a list of PIDs dependent on
your process's privileges:
$ CONTEXT = ""
$ START:
$
PID
F$PID(CONTEXT)
$
IF PID .EQS. "" THEN EXIT
$
SHOW SYMBOL PID
$
GOTO START
The PIDs displayed by this command procedure depend on
of your process. When run with GROUP privilege, the
in your group are displayed.
In order for the command
return all the PIDs on the system, your process would
privilege. Without GROUP or WORLD privilege, only
displayed.

5.2.15

the privilege
PIDs of users
procedure to
require WORLD
your PID is

The F$SEARCH Lexical Function

The F$SEARCH lexical function returns, as a character string,
full file specification that matches the file-spec you name.
format of the F$SEARCH lexical function is:

the
The

F$SEARCH(file-spec[,stream-i~])

The file-spec may contain one or more blank or wild card fields (for
example, directory name, file name, and file type, and so on) of a
file specification.
A file-spec must be a character
string
expression or a symbol equated to a character string.
The stream-id can be any positive integer. You use it to specify
the search stream when you want to maintain the context for several
searches performed simultaneously. For example:
$ START:
$
COM= F$SEARCH(".COM.",l)
$
DAT= F$SEARCH(".DAT.",2)
$
SHOW SYMBOL COM
$
SHOW SYMBOL DAT
$
IF (COM.EQS."") .OR. (DAT.EQS."") THEN EXIT
$
GOTO START
This command procedure searches the default disk and directory for
COM and DAT files simultaneously.
Notice that the stream-id is
specified for each F$SEARCH function so that context for each
function is maintained throughout the search.
If you omit the stream-id, F$SEARCH assumes an implicit single
stream.
Each
subsequent F$SEARCH function, having the same
file-spec, returns the next file specification that matches the
specified file-spec. After the last file specification is returned,
the next F$SEARCH function returns a null string.
The following command procedure displays the file-specs
.EXE files in the SYS$SYSTEM directory:
$ START:
$
FILE = F$SEARCH("SYS$SYSTEM:*.EXE")
$
IF FILE .EQS. "" THEN EXIT
$
SHOW SYMBOL FILE
$
GOTO START

5-17

all

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
5.2.16

The F$PRIVILEGE Lexical Function

The F$PRIVILEGE lexical function returns a value of either "TRUE" or
"FALSE" depending on whether your current process privileges match
the privilege states listed in the argument.
The format of the F$PRIVILEGE function is:
F$PRIVILEGE(privstates)
The privstates argument must be a character string expression
equated to a privilege keyword or a list of privilege keywords
separated by commas. Part I of the VAX/VMS Command Language User's
Guide contains a list of the valid privilege names you can specify
as keywords.
If "NO" precedes the privilege keyword, then the privilege must be
disabled in order for the function to return a "TRUE" value. The
F$PRIVILEGE function checks each of the keywords in the specified
list, and if the result for any one is false, the string "FALSE" is
returned.
For example, suppose your process has OPER, USER, TMPMBX, and NETMBX
privileges, and you specify the following:
$ PROCPRIV = F$PRIVILEGE("OPER,GROUP,TMPMBX,NONETMBX")
$ SHOW SYMBOL PROCPRIV
"FALSE"
In this example, a value of "FALSE" is returned because your process
has NETMBX privilege, but NONETMBX was specified in the privstate
list. Although the boolean result for the other three keywords is
true,
the entire expression is declared false since the result for
NONETMBX was false.

5.2.17

The F$SETPRV Lexical Function

The F$SETPRV lexical function invokes the $SETPRV system service to
enable or disable specified user privileges and return a list of
keywords indicating the previous state of privileges for the current
process.
If a privilege cannot be set, the function will return the
specific privilege keyword prefixed by "NO".
The format of the F$SETPRV function is:
F$SETPRV(privstates)
The privstates argument is a character string expression that
evaluates to a privilege keyword or a list of privilege keywords
separated by commas. Part I of ·the VAX/VMS Command Language User's
Guide contains a list of valid privilege names you can specify as
keywords.
In addition to the privilege names listed in the VAX/VMS Command
Language User's Guide, you can specify either of the following
privilege keywords:
ALL
NOA LL

Enables all known privileges
Disables all known privileges

In order to enable privileges, your process must be authorized to
set the specified privilege. For detailed information on privilege
restrictions, see the VAX/VMS System Services Reference Manual.

5-18

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
The following example enables and disables certain privileges and
returns a
list of keywords indicating the previous state of the
specified privileges:
$ OLDPRIV = F$SETPRV("OPER,NOTMPMBX"}
$ SHOW SYMBOL OLDPRIV
"NOOPER,TMPMBX"
In this example, the privilege OPER was enabled and TMPMBX was
disabled.
The keywords NOOPER and TMPMBX were returned in the
keyword list, showing the previous state of these privileges.

5.3

STRING MANIPULATION FUNCTIONS

A string can be either a literal character string
(one enclosed in
quotation marks},
a symbol name that has been equated to a string
value, or an expression that evaluates to a string.
The terms
associated with string manipulation are "substring" and "offset."
•

A substring is any
string.

contiguous

•

An offset is the relative position of a character or a
substring in a string with respect to the beginning of the
string.
The first character in a string is always offset
position 0 from the beginning of the string (which always·
begins at the leftmost character in the string}.

The following lexical functions
strings:

5.3.1

set

allow

length

you
of

characters

manipulate

specified

within

character

•

F$LENGTH returns the
integer value.

string

•

F$LOCATE returns the offset within a string of a specified
character or character substring as an integer value.

•

F$EXTRACT returns a substring from
character string as a string value.

•

F$INTEGER returns the
string expression.

integer

equivalent

•

F$STRING returns the
integer expression.

string

equivalent

•

F$CVTIME returns the standard ASCII date and time string of
the form dd-mmm-yyyy hh:mm:ss:cc converted to a string of the
form yyyy-mm-dd hh:mm:ss:cc.

•

F$FAO returns the specified control
formatted ASCII output string.

specified

the

specified

the

specified

within

string

converted

The F$LENGTH Lexical Function

The ·F$LENGTH lexical function returns· the length
string.
The format of the F$LENGTH function is:
F$LENGTH(string}

5-19

specified

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
The string is a character string expression or a symbol equated
character string expression.

For example:
$ MESSAGE = F$MESSAGE{%XlC)
$ STRING LENGTH = F$LENGTH(MESSAGE)
After these assignment statements, the symbol MESSAGE has the value:
%SYSTEM-F-EXQUOTA, exceeded quota
The symbol STRING LENGTH has a value equal to the number of characters
in the value of the symbol named MESSAGE, that is, 33.
For additional examples on the use of F$LENGTH, see
procedures CONVERT.COM and FORTUSER.COM in Appendix A.

5.3.2

the

sample

The F$LOCATE Lexical Function

The F$LOCATE lexical function locates a character or character
substring within a string and returns its offset within the string.
If the character or character substring is not found,
the function
returns the length of the string that was searched.
The format of the F$LOCATE function is:
F$LOCATE(substring,string)
The substring is the string of characters that you want to locate
within the string and string is the string in which the characters are
to be found.
Specify substring and string as a character string
expression or a symbol equated to character string expression.
For example:
$ FILE SPEC = "MYFILE.DAT;l"
$ NAME=LENGTH = F$LOCATE(".",FILE_SPEC)
The F$LOCATE function in the above example returns the position of the
period in the string with respect to the beginning of the string.
Thus NAME LENGTH equals the length of the file name in the file
specification MYFILE.DAT, that is, 6.
Note in the above example that the character to be located,
the
period,
is specified literally and is therefore enclosed in quotation
marks. The symbol FILE SPEC is automatically replaced by its current
value during the processing of the function.
A common technique 'to determine whether a character or character
string is in a string is to compare the result of a locate function
with the length of the string, as shown in the following example:
$ INQUIRE TIME "Enter time"
$ IF F$LOCATE(":",TIME) .EQ. F$LENGTH(TIME) THEN GOTO NO COLON
In this example, the INQUIRE command prompts for a time value. The IF
command checks for the presence of a colon in the string entered in
response to the prompt.
If the value returned by the F$LOCATE
function equals the value returned by the F$LENGTH function, the colon
is not present.

5-20

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
5.3.3

The F$EXTRACT Lexical Function

The F$EXTRACT function returns a substring from a character string
value.
When you use this function, you specify the location within
the string that marks the beginning of the substring ~nd the number of
characters you want to extract. The format is:
F$EXTRACT(offset,length,string)
The offset is the position, relative to the beginning of the string,
that marks the beginning of the substring you want to extract; the
length is the number of characters you want to extract;
and the
string is the string from which the substring is to be extracted.
Specify offset and length as an integer expression or a symbol equated
to an integer expression.
Specify string as a character string
expression or a symbol equated to a character string expression.
The following example shows a procedure that displays a different
message depending on whether the current daytime is morning or
afternoon.
It first obtains the current time of day by using the
F$TIME function.
Then, it extracts the hours from the date and time
string returned by F$TIME:
$ IF F$EXTRACT(l2,2,F$TIME()) .GES. 12 THEN GOTO AFTERNOON
$ MORNING:
$WRITE SYS$0UTPUT "Good morning!"
$ EXIT
$ AFTERNOON:
$WRITE SYS$0UTPUT "Good afternoon!"
$ EXIT
The string returned by F$TIME always contains the hours field
beginning at an offset of 12 characters from the start of the string.
The F$EXTRACT
beginning at
value 12.

function extracts two characters from the string,
this offset, and compares the value extracted with the

Frequently, manipulation of a character string value requires that you
locate a particular character within a string and then extract a
substring beginning or ending at that location.
For example:
$FILENAME= F$EXTRACT(O,F$LOCATE(".",Pl) ,Pl)
In this example, the lexical function F$LOCATE gives the numeric value
representing the position of a period in the character string value of
Pl.
This function is used as an argument in the F$EXTRACT function to
specify the number of characters to extract from the string.
If a
procedure is invoked with the parameter MYFILE.DAT,
these statements
result in the symbol FILENAME being given the value MYFILE.
Note that the F$LOCATE function in the above example assumes that the
file specification does not contain a node name or a directory
specification inciuding a subdirectory name.
Checking
a
file
specification
for
fields such as these would require a more
complicated sequence of functions.

5.3.4

THE F$INTEGER Lexical Function

The F$INTEGER lexical function returns the integer equivalent of the
result of the specified integer expression. You can use this function
to set a symbol to an integer value and use the symbol in an operation
that requires an integer type value.
5-21

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
The format of the F$INTEGER function is:
F$INTEGER(expression)
The following example shows how the
convert a string expression:

F$INTEGER

function

used

$ A = "23"
$ B = F$INTEGER("-9" + A)
$ SHOW SYMBOL B
B = -923 Hex=FFFFFC65 Octal=l76145
The F$INTEGER function in the above example returns the integer
equivalent of the expression
("-9" + A), which evaluates to the
character string "-923". Here, since the expression contains two
character strings, the plus sign (+)
is a string concatenation
operator. Note that the symbol A was assigned the numeric character
string "23".
For additional details on.implicit string to integer
section 3 .1. 2.

5.3.5

conversion,

see

The F$STRING Lexical Function

The F$STRING lexical function converts the result of the specified
integer expression to a string.
The format of the F$STRING function
is:
F$STRING(expression)
The following example shows how
convert an integer expression:

the

F$STRING

function

used

$ A = 5
$ B = F$STRING(-2 +A)
$ SHOW SYMBOL B
B = "3"

The F$STRING function in the above example converts the result of the
expression, (-2 +A) to the numeric string, "3". Note that the symbol
A was assigned the integer value 5.
For additional details on implicit integer to string
section 3 .1. 2.

5.3.6

conversion,

see

The F$CVTIME Lexical Function

The F$CVTIME lexical function converts a standard ASCII date/time
string of the form "dd-mmm-yyyy hh:mm:ss.cc" to a string of the form
"yyyy-mm-dd hh:mm:ss.cc". You can use the resultant string to compare
two dates (using .LTS and .GTS. operators).
The format of the F$CVTIME function is:
F$CVTIME (time)
The time must be specified as a string expression or a symbol equated
to a string expression in the form "dd-mmm-yyyy hh:mm:ss.cc". The
time specification must contain some part of the date field,
or an
error is displayed. Absolute time keywords (TODAY, TOMORROW, and so
on) are not allowed in the time specification.

5-22

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
The following example gets the
comparison time:

system

time

and

converts

$ TIME = F$TIME()
$ SHOW SYMBOL TIME
TIME= "13-JUN-1982 10:56:23.10"
$ TIME = F$CVTIME(TIME)
$ SHOW SYMBOL TIME
TIME= "1982-06-13 10:56:23.10"

5.3.7

The F$FAO Lexical Function

The F$FAO lexical function invokes the $FAQ system service to convert
the specified control string to a formatted ASCII output string. By
specifying arguments, you can use the F$FAO function to:
•

Insert variable character string data into an output string

•

Convert integer values into the ASCII representations of their
decimal, hexadecimal, and octal equivalents, and substitute
results into the output string

The format of the F$FAO function is:
F$FAO(control-string[,argl,arg2 ••• argl5])
The control string may be any length and may contain any number of FAQ
directives
(see Table 5-6). These directives control the processing
performed by the F$FAO lexical function.
An FAQ directive may have
any one of the following formats:
Format

Function

!DD

On~

!n(DD)

A directive repeated a specified number of times

!lengthDD

A directive generating
specified length

!n(lengthDD)

A directive repeated a specified number of times
generating output fields of a specified length

directive

output

string

The exclamation point (!) indicates that the following character or
characters are to be interpreted as an FAO directive. DD ls a one- or
two-character uppercase code indicating the action that F$FAO is to
perform.
When specifying repeat counts, n is a decimal value
specifying the number of times the directive is to be repeated.
The
length value is a decimal value that instructs F$FAO to generate an
output field of "length" characters.
Each directive may require one or more arguments to the F$FAO lexical
function.
For each directive that uses an argument, you must supply
the argument as an integer expression or character string expression
in the argument list. If you specify an argument whose type (integer
or string) does not match that of directive it follows,
unpredictable
results will be returned.
You can use the F$INTEGER and F$STRING
lexical functions to convert arguments to the proper type.

5-23

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
In the following example, the FAQ directive !SL converts
equated to the symbol COUNT to a character string.

the

number

$ COUNT = 57
$REPORT= F$FAO("NUMBER OF FORMS= !SL",COUNT)
Note that COUNT is assigned a integer value of 57.
returns the ASCII string, "NUMBER OF FORMS= 57".

The F$FAO function

Directives may also include:
•

A repeat count

•

An output field length

A repeat count is specified as follows:
! n (DD)

In the following example, the symbols A, B,
the control string.

c, and D are inserted into

$ A = "ERR"
$ B
"IS"
$ c
"HUM"
$ D
"AN"
$ PHRASE = F$FAO("TO !3(AS)",A,B,C+D)
The resultant string is "TO ERRISHUMAN". Since the specified repeat
count for the !AS directive is 3, F$FAO looks for three arguments.
The arguments in this example include the symbol A ("ERR"), the symbol
B ("IS"), and the expression C+D ("HUMAN"). Note that the values of
these string arguments are concatenated
to
form
the
string
"ERRISHUMAN".
Arguments must correspond exactly to the order of their respective
directives.
In most cases, an error message is not displayed if you
misplace an argument.
If there are not enough arguments listed, F$FAO will continue reading
past the end of an argument list.
Therefore, always be sure to
include enough arguments to satisfy the requirements of all the
directives in a control string.
An output field length is specified as follows, where length is a
decimal value instructing F$FAO to place the output from a directive
into a field of "length" characters in the output string.
!lengthDD
A directive may contain both a
specified as:

repeat

count

and

output

length

! n ( lengthDD)
Repeat counts and output lengths may also be specified as var-iables by
specifying a number sign (#) in place of an absolute numeric value.
If # is specified for a repeat count, the next argument passed to
F$FAO must contain the count as a binary expression. The same is true
when specifying # for a length value.
When a variable output field is specified with a repeat count, only
one length parameter is required, since each output string will have
the specified length.

5-24

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
For example:

$ A
"ERR"
$ B
"IS"
$ C
"HUMAN"
$PHRASE= F$FAO("TO ll(IAS)",3,6,A,B,C)
The string returned by the F$FAO lexical function in this example is:
"TO ERR

HUMAN "

Each argument string is output to a
field having a length of six
characters.
Since each string is less than six characters, each field
is padded with blank spaces.
Table 5-6 summarizes the FAQ
required by each directive.
Table 5-6:
Instruction

directives

and

lists

the

arguments

Summary of FAO Directives
Parameter

Description

Character string insertion
1AS

Inserts a character string as is;
the field length defaults to the
length of the character string;
short values inserted in explicitlength fields are left-justified
and blank filled; long values
inserted in explicit-length fields
~re truncated on the right

Character string

Zero-filled numeric conversion
OB

ow
OL
XB

XL
ZB

Converts a byte, word, or longword
to octal notation
Converts a byte, word, or longword
to hexadecimal notation

A binary number;
for byte and
word conversions
only the
low-order 8 or
16 bits are used

Converts a byte, word, or longword
decimal notation

ZL
Output field lengths default to 2 (byte), 4 (word),
and 8 (longword) for hexadecimal -- 3, 6, and 11 for
octal -- and the required number of characters for
decimal; the numbers are right-justified and zerofilled on the left; explicit-length fields longer
than the default are blank-filled on the left;
explicit-length fields shorter than the default are
truncated on the left
Blank-filled numeric conversion
1UB
1UW

1UL
1 SB

Converts a byte, word, or longword
to decimal notation without
adjusting for negative numbers
Converts a byte, word, or longword

A binary number;
for byte and.
word conversions
only the

(continued on next page)

5-25

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
Table 5-6 (Cont.):

Description

Parameter

to decimal notation with negative
numbers converted properly

low-order 8 or
16 bits are used

Instruction
!SW
!SL

Summary of FAO Directives

Output field lengths default to the required number
of characters; values shorter than explicit-length
fields are right-justified and blank-filled; values
longer than explicit-length fields cause the field
to be filled with asterisks
Special formatting

!/
!%S
! n< ••• !>

!nc

Inserts a carriage return
Inserts a tab
Inserts a form feed
Inserts an uppercase S if the most
recently converted number is not 1
Left-justifies and blank-fills all
data represented by the
instructi~ns ••• in fields n
characters wide
Repeats the character represented
by c for n times

None

Inserts the current time
Inserts the current date/time

Binary number 0
Binary number 0

Time
!%T
!%D

Parameter interpretation
Reuses the last parameter
Skips the next parameter

5.4

None

FUNCTIONS THAT MANIPULATE BINARY DATA

There are two methods used to assign binary data to a
symbol name.
The first method is to perform a binary overlay in the current value
of a symbol name by using the syntax:
symbol-name [bit-po si ti on, size]= integer-expression
This method is described in Section 3.7, Arithmetic Overlays.
The second method is to use the READ command to
read data
into a
symbol name from a file whose records contain binary data.
The READ
command is described in Section 8.2.
Two lexical functions are provided to manipulate
has been assigned to a symbol name:

F$CVUI
F$CVSI

for operations on unsigned quantities
for operations on signed quantities

5-26

binary

data

that

USING LEXICAL FUNCTIONS IN COMMAND PROCEDURES
These integer conversion functions extract bit fields from character
string data and convert the result to either signed (F$CVSI) or
unsigned (F$CVUI) decimal values.
The formats of these functions
are:
F$CVUI(bit-position,width,string)
F$CVSI(bit-position,width,string)
The bit-position is the offset of the value to be converted from the
beginning of the string;
the width is the number of bits that are
to be extracted for conversion to an integer value; and the string
is the the character string from which the bits are taken.
The
low-order (rightmost) bit of a
string
is position number O for
determining
the offset.
You specify the value of the string by
using an integer expression.
For example, consider the following arithmetic overlay of the symbol
name A, where the hexadecimal value 2B is assigned to all 32 bits of
the symbol:
$ A[0,32]=%X2B
Note that the ASCII representation of this symbol name is now the
character. You could determine this by typing the command:

$ SHOW SYMBOL A
The F$CVSI and F$CVUI lexical functions can now be used
to extract
fields
from the symbol A and convert these fields to their decimal
values.
For example, consider the extraction
(and conversion)
of
the low-order four bits from the symbol A:
X

F$CVSI(0,4,A)

F$CVUI(0,4,A)

The results of these converaions are X = -5 and Y = 11, because the
F$CVSI function treats the low-order four bits of the value %X2B as
a signed integer,. while the F$CVUI function treats the low-order
four bits of the value %X2B as an unsigned intege~.

5-27

CHAPTER 6
CONTROLLING EXECUTION FLOW IN COMMAND PROCEDURES

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

6.1

•

The IF command tests the value of a symbol or expression and
executes a given command string based on the result of the
test.

•

The GOTO command transfers control to a labeled
procedure.

•

The Execute Procedure (@) command invokes (or calls)
command
level
and begins execution of another
procedure.

•

The EXIT and STOP commands terminate the current procedure and
restore control either to the calling command procedure or to
command level O, respectively.

line

the

another
command

THE IF COMMAND

The IF command tests the value of an expression and executes a given
command
if the result of the expression is true. An expression is
true if:
•

It has an odd integer value.

•

It has a character string value that begins with
letters Y, y, T, or t.

•

It has an odd numeric string value

any

the

any

letter

An expression is false if:
•

It has an even integer value.

•

It has a character string value that begins
except Y, y, T, or t.

•

It has an even numeric string value

6-1

with

CONTROLLING EXECUTION FLOW IN COMMAND PROCEDU~ES
The following examples show valid expressions used in IF commands.
Example

$ IF A + B .EQ.

10 THEN command

Explanation
Executes the given command if the
sum of the defined symbols A and B
is 10

$ IF A THEN command

Executes the given command if the
symbol A has an odd integer value,
is equated to a character string
that begins with the letters Y, y,
T, or t
(true}, or has an odd
numeric string value

$ IF .NOT.

Executes the given command if the
symbol A has an even integer value,
is equated to a character string
that begins with any letter except
Y, y, T, or t (false}, or has an
even numeric string value

A THEN command

$ IF COUNT .LE.

$ IF Pl .EQS.

100 THEN command

Executes the given command if the
symbol COUNT has a current value
less than or equal to 100

"TYPE" THEN command Executes the given command i f the
passed to the
first
parameter
command procedure was the word TYPE

The target command of an IF command can be any valid DCL command; you
can optionally precede the command with a dollar sign. The command is
executed only if the expression is true.
Otherwise, execution
continues with the next command in the procedure, as illustrated in
Figure 6-1. After the THEN command string
is executed, control
returns
to the next command
in the sequence unless the THEN
command-string results in a transfer of control.
The target command of an IF command can be another
example:

command.

For

$ IF A .EQ. B THEN IF C .EQ. D THEN IF E .EQ. F THEN RESULT = 1
In this IF command, each expression is tested in turn.
If the result
of the first expression is true, the second IF command is executed;
if that expression is true, the next IF command is executed.
If all
of the IF command expressions are true, ~ESULT is given a value of l;
otherwise, RESULT is not given a value.
The only practical limit on the number of IF commands that can be
nested
in a single command string
is the limit on the number of
characters that can be specified in a command string. This limit is
approximately 132 characters.

6-2

CONTROLLING EXECUTION FLOW IN COMMAND PROCEDURES

..
$ command-string

'true

$ IF expression

t---~~

THEN command-string

false

Yes

GOTO label

Execute procedure

return to calling
procedure

$ next command-string
ZK-824-82

Figure 6-1:

6.1.1

The IF Command

Using Logical Operators in IF Commands

The example in the preceding section
logical AND operation, as follows:

can

also

written

using

$ IF A .EQ.
B .AND.
C • EQ.
D .AND.
E • EQ.
F THEN RESULT
1
This IF command expression consists of several operations;
the THEN
command string
is executed only if all tests performed within the
expression are true. Note that the
.EQ.
operator has a higher
precedence than the
.AND.
operator;
the arithmetic comparisons in
this command will be performed before the logical operations.

6-3

CONTROLLING EXECUTION FLOW IN COMMAND PROCEDURES
The other logical operators, OR and NOT, are also useful
in IF
expressions.
For example, the following command tests whether one or
the other of two expressions is true:
$ IF Pl .EQS.

"DISK" .OR.

Pl .EQS.

"TAPE" THEN GOTO 'Pl'

The THEN command string in this example is executed if the parameter
Pl is currently equal to either of the character strings DISK or TAPE.
Note that when you use the AND or the OR logical operators,
the
expressions on each side of the operator mus~ be complete. The syntax
is:

$ IF expression .OR. expression THEN command
$ IF expression .AND. expression THEN command
The logical NOT operator tests whether an expression is not true,
therefore reverses the sense of the test.
For example:

$ IF .NOT.

and

RESULT THEN command

The IF command above tests whether RESULT is false.
useful following INQUIRE commands.
For example:

This construct is

$ INQUIRE CONT "Do you want to continue"
$ IF .NOT. CONT THEN EXIT
If the response to the INQUIRE command is any even numeric value or
any character string that begins with a letter other than T, t, Y, or
y, the procedure does not continue execution.
Expressions can be simple or compound.
expression can consist of a single symbol:

For

example,

simple

RESULT
A compound expression can consist of several operations:
(Pl .EQS.

"DISK")

.OR.

(Pl .EQS.

"TAPE")

.AND.

( P 2 • LE.

This expression is true if the symbol Pl is equated to either one of
the character strings DISK or TAPE and the symbol P2 has an integer
value that. is less than or equal to 5.
For complete details on the syntax of expressions and how
each type of operation that is valid, see Section 3.4.

6.1.2

specify

Using Symbols in IF Commands

Expressions in IF commands are automatically evaluated during the
execution of the command.
All character strings beginning with
alphabetic letters that are not enclosed
in quotation marks are
assumed to be symbol names and the IF command replaces them with their
current values.
Symbol substitution in this context is not iterative; that is, each
symbol
is replaced only once.
However,
if you want iterative
substitution, you can precede a symbol name with an apostrophe (')
or
ampersand
(&)
operator so the command interpreter will also perform
substitution during command input or parsing.

6-4

CONTROLLING EXECUTION FLOW IN COMMAND PROCEDURES
The command interpreter does not execute an IF command when it
contains an undefined symbol.
Instead, the command interpreter issues
a warning message and executes the next command in the procedure.
Symbol substitution and iterative substitution are described in detail
in Chapter 4.
The following paragraphs contain some specific examples
of substitution with the IF command.

$ A = "B"
$IF A .EQS.

"B" THEN •••

This IF command compares the value of the symbol A with the literal
value B. Note that if you do not enclose B in quotation marks, the IF
command assumes that B is a symbol name, attempts to replace it, and
issues a warning message if it fails to find the symbol name B.
The next example shows how to construct an IF
iteratively each parameter passed to a procedure:

command

check

$
COUNT
0
$ LOOP:
$
COUNT
COUNT + l
$
IF COUNT .EQ.
9 THEN EXIT
$
IF P'COUNT' .EQS. "" THEN EXIT
$
APPEND/NEW &P'COUNT' SAVE.ALL
$
DELETE &P'COUNT';&
$
GOTO LOOP
In this example, the IF command string is written so that each time
through the loop, the command interpreter replaces the symbol COUNT
with its curr~nt value.
Each time the IF command executes, the
resulting
symbol name
(Pl, then P2, then P3, and so on) is replaced
within the expression. The APPEND and DELETE commands, however, must
use the ampersand
(&)
substitution operator on these parameters,to
force iterative substitution.
Iterative substitution with ampersands
is described in Section 4.5.4.
Note that Pl through PS are never undefined when a procedure begins
execution.
The command
interpreter defines these symbols at each
nested command level;
they are all initially given null values. When
you do specify parameters for procedures, your specifications override
the default values.
The above example also shows how to use the GOTO command to establish
a loop in a command procedure; the GOTO command is described next.

6.2

THE 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:
•

A label must appear as the firit item on a line.

•

A label can have up to 255 characters.

•

No blanks can be embedded within a label.

•

A label must be terminated with a colon (:).

6-5

CONTROLLING EXECUTION FLOW IN COMMAND PROCEDURES
For example:
$ GOTO BYPASS

$ BYPASS:
As the command interprete~ encounters labels,
it enters them
in a
table, space for which is allocated from space available in the local
symbol table.
If a label is encountered that already exists in the
table,
the new definition replaces the existing one. Note that the
amount of space available for labels is limited.
If a command
procedure uses many symbols and con ta ins many 1 abels, the command
interpreter may run out of table space and issue an error message.
Figure 6-2 illustrates how the GOTO
execution in a command procedure.

command

affects

the

flow

The mo·st common uses of GOTO commands are as targets of IF commands
and as a means of establishing loops, as described in Sections 6~2.1
and 6.2.2.
You can also use labels to define se~ments of command
procedures;
to define target statements for error conditions in the
CLOSE, READ, and WRITE commands; and to handle end-of-file conditions
in the READ command.
(See Chapter 8 for more information on the
file-handling commands.)
$

LABELA:

cor1H11and-strins'

GOTO LABELA

cor1H11and-strins'

GOTO LABELB

cor1H11and-strins'

LABLEB

cor1H11and-strins'

GOTO LABELC

E)<IT

0 LABELA is put into the label table for this command level.

•

When a GOTO command is executed, the command interpreter checks the label table for this command level. If the
label is found, control transfers to the command immediately after the label.
If the label is not in the label table when a GOTO command is executed, the command interpreter scans forward
through the procedure to locate the label. If found, the label is placed in the label table and control transfers to the
command immediately following the label.
If the label is not in the label table when the GOTO command is executed, and the command interpreter cannot find
the label, the procedure exits immediately. The EXIT command is not executed.
•
ZK-825-82

Figure 6-2:

The GOTO Command

6-6

CONTROLLING EXECUTION FLOW IN COMMAND PROCEDURES
6.2.1

Using GOTO Within a THEN Clause

The GOTO command is especially useful within a THEN clause to cause a
procedure
to branch forward or backward according
to variable
conditions or according to parameters that you pass to the procedure.
For example, when you use parameters in a
good practice to test the parameters
procedure. A procedure that you execute
with the lines:

command procedure,
it is
at the beginning of the
interactively could begin

$ IF Pl .NES. "" THEN GOTO OKAY
$ INQUIRE Pl "Enter file spec"
$ OKAY:
$ PRINT/HOLD/COPIES=lO/FORMS=B
'Pl'
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.

6.2.2

Using GOTO to Establish Loops

With the GOTO command, you can establish several kinds of loop.
examples follow.

Three

You can use the GOTO command in loops that execute a defined number of
times.
The procedure establishes a counter, increases or decreases
the counter, and tests the counter's value. When the counter reaches
a defined value, the procedure exits from the loop.
For example:

$ COUNT=O
$ LOOP:
$
COUNT=COUNT+l

IF COUNT.LE.10.THEN GOTO LOOP

In this example, the command procedure exits from the
value of COUNT reaches 11.

loop

when

the

You can use the GOTO command in loops that prompt for th~ user to
indicate whether execution should continue. For each iteration of the
loop, the procedure prompts for input data or a value for a variable.
For example:

$ LOOP:
$
INQUIRE FILE "FILE"
$
IF FILE .EQS.
"" THEN GOTO SKIP

$
GOTO LOOP
$ SKIP:

6-7

CONTROLLING EXECUTION FLOW IN COMMAND PROCEDURES
In this example, the
response from the
RETURN) the loop is
iteratively, until a

INQUIRE command requests a
file name.
If the
interactive level is a null value (a CTRL/Z or a
not executed.
Otherwise, the loop executes,
null value is entered.

You can use the GOTO command in loops that make a specific test during
each iteration.
The procedure executes the loop until the test is
satisfied, then branches. The example loop in Section 6.1.2 is such a
test.

6.3

NESTING PROCEDURES: THE EXECUTE PROCEDURE COMMAND

The GOTO command described in the preceding section provides one way
to divide command procedures into more easily read and understood
sections.
In a procedure that is more complex, you may find it useful
to separate procedures into several smaller procedures. Or, you may
find it convenient to deveiop small, generalized procedures that
perform common functions and to invoke these procedures from other
procedures that you write.
Using the Execute Procedure (@)
command to invoke new levels of
command execution is similar to using a CALL statement in a high-level
programming language. Procedures can be nested to a maximum of eight
levels.
At each command level, logical name assignments for process
permanent files can change; these changes are discussed
in Section
2 .1.

Some of the techniques you can use
command level to another involve:

pass

information

from

one

•

Passing parameters.
You can pass up to eight variable
parameters to a procedure you invoke using
the Execute
Procedure (@) command. Techniques for passing parameters to
command procedures are described in Section 3.10.

•

Using global symbols. You can use global symbols to pass
variable data from one procedure to another; a global symbol
defined in a nested command proceoure can be referred
to in
all command procedures.
Global symbols are described in
Section 3.9.2.

The sample procedure CONVERT.COM in Appendix A is a generalized
procedure that can be called by any other pr6cedure.
It accepts a
parameter passed to it and sets a global symbol value for the caller.

6.4

THE EXIT AND STOP COMMANDS

The EXIT and STOP commands both provide a way to terminate the
execution of a procedure. The EXIT command terminates execution of
the current command procedure and
returns control to the calling
command level.
The STOP command also terminates execution of a
procedure; however, when a STOP command is executed, the command
interpreter returns to command level O, regardless of the current
command level. If you execute the STOP command in a batch job, the
batch job terminates.

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

6-8

CONTROLLING EXECUTION FLOW IN COMMAND PROCEDURES
routine at the end of a procedure, you would
before the routine, as follows:

place

EXIT

command

$
EXIT !
End of normal execution path
$ ERROR ROUTINE:

The EXIT command is also useful for writing procedures that have
than one execution path.
For example:

$ START:
$
IF Pl.EQS."TAPE" .OR.Pl.EQS."DISK" THEN GOTO 'Pl'
$
INQUIRE Pl "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 pro~edure.
The EXIT command before the
label DISK ensures that the commands after the label
DISK are not
executed unless the procedure explicitly branches to 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.

6.4.2

Passing Status Values with the EXIT Command

The EXIT command accepts an optional parameter called a status code
value.
When a command procedure has multiple levels of interaction,
you can use the EXIT command to pass status values from nested
levels
back to
their callers.
The exit code defines a value for the global
symbol named $STATUS.
$STATUS is a
special,
reserved symbol
name
maintained by the command interpreter.
For example, suppose the procedure A.COM contains:

$ @B
$ IF $STATUS .EQ. 3 THEN GOTO CONTROL

6-9

CONTROLLING EXECUTION FLOW IN COMMAND PROCEDURES
and the procedure B.COM contains the line:
$ EXIT 3
This EXIT command places the value 3 in the global
which is tested by the calling procedure, A.COM.

symbol

$STATUS,

Note that you can use any numeric value or expression with the EXIT
command:
the EXIT command automatically performs symbol substitution
and expression evaluation. For example:
$ EXIT A+B
The above command is valid if the symbols
currently defined with arithmetic values.

named

and

are

both

If you do not set a value for an EXIT command when a procedure is
terminated, the command interpreter gives it a default valu~, based on
the status value returned from the most recently executed command or
program.
For information on how this value is set and how you can
establish default courses of action for a command procedure based on
its value, see Chapter 7.

6.4.3

Using the STOP Command

You can use the STOP command in a command procedure or batch job to
ensure that all procedures are terminated if a severe error occurs.
You can also use the STOP command to halt the interactive execution of
a procedure after interrupting it.
For example:
$ @TESTALL(Bill
(CTRL/Y)

$ STOPfilIJ
In the above example, the procedure TESTALL is interrupted by CTRL/Y.
The STOP command terminates processing of the procedure and restores
command level O.

6-10

CHAPTER 7
CONTROLLING ERROR CONDITIONS AND CTRL/Y INTERRUPTS

This chapter describes how to control command procedure execution when
an error condition or a CTRL/Y interrupt occurs.
Error conditions are detected by various VAX/VMS
(or applications)
components and are stored in the reserved global symbol $STATUS. The
lowest three bits of this integer value provide the current value of
the reserved global symbol $SEVERITY.
A CTRL/Y interrupt is the result of
procedure execution.

7.1

pressing

CTRL/Y

during

command

ERROR CONDITION HANDLING

If an EXIT command does not explicitly set a value for $STATUS,
the
command interpreter uses the current value of $STATUS. This value is
set implicitly by individual commands and programs that execute in a
procedure.
The· values that are set, called condition codes, provide
information about the termination of a program image. You can provide
action routines and error handling statements in your procedures based
on values in $STATUS as described in the following sections.

7.1.1

Severity Levels

The low-order three bits of the status value contained in $STATUS
represent the severity of the condition. The reserved global symbol
$SEVERITY always contains only this portion of the condition code.
These values, and the severity levels they represent are:
Value

Severity

0
1
2
3

Warning
Success
Error
Information
Severe, or 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 conuands that
perform logical tests on these values, as shown below:
$ IF $SEVERITY THEN
$IF $STATUS THEN •••

7-1

CONTROLLING ERROR CONDITIONS AND CTRL/Y INTERRUPTS
When the current value in $SEVERITY or $STATUS is odd, the command or
program
completed
successfully (the IF expressions are true).
Otherwise, the IF expressions are false, indicating that the command
or program did not complete successfully.
The converse of this test is a logical NOT operation, for example:
$ IF .NOT. $STATUS THEN
The command interpreter also uses the severity level of a condition
code to determine whether to take specific action defined by the ON
command.
If an ON command action exists for a specific severity
level,
for example, for error conditions, that action will be taken.
If a command results in an error, the specified action is taken and
the next statement in the procedure will not be executed.

7.1.2

The ON Command

During the execution of a command procedure, the command
interpreter
checks the condition code returned from each command or program that
executes. With the ON command, you can establish a course of action
for the command interpreter to take based on the result of the check.
The format of the ON command is:
ON severity-level THEN [$] command
By default, the command interpreter executes an EXIT command when an
error or severe error occurs, and continues when warnings o~cur.
You
can override this default with the ON command.
An ON command
establishes a default command action when condition code of a
specified severity level and above occur.
If an ON command action is established for a specific severity level,
when errors of lesser severities occur the command interpreter will
continue processing the file.
Table 7-1 illustrates the ON command
keywords that define command actions and the action taken by the
command interpreter on condition code at other severity levels.
Table 7-1:

Severity Levels for ON Command Actions
Action Taken at Different Severity Levels

ON Command
Severity Level

WARNING

ERROR

SEVERE ERROR

WARNING

Specified
action

ERROR

Continue

Specified
action

SEVERE ERROR
-

Continue

Specified
action

For example, if you want a procedure to exit
and severe errors occur, use the command:

$ ON WARNING THEN EXIT

7-2

when

warnings,

errors,

CONTROLLING ERROR CONDITIONS AND CTRL/Y INTERRUPTS
If you want the procedure to continue if a warning or an error occurs,
but to exit if a severe error occurs, use the command:
$ ON SEVERE ERROR THEN EXIT
This ON command requests that the procedure exit only in the case of a
severe error.
If any command in the procedure incurs a warning or
error condition, execution will continue with the next command in the
procedure.
If a severe error occurs, however, the procedure exits.
An ON command action is executed only once; thus, if you have used
the above command, the command interpreter continues after an error
occurs, but resets the default condition.
If a second error occurs,
and no other ON command has been encountered, the procedure exits.
Figure 7-1 illustrates ON command actions.
The sample procedures FORTUSER.COM and CALC.COM in Appendix
illustrate the use of the ON command to establish error handling.

DBA1 :[HIGGINS]FORT.COM
$

0
8
0

@FORT
$
$

ON ERROR THEN CONTINUE
FORTRAN A

FORTRAN B

ON WARN I NG THEN E)< IT

FORTRAN C

E)<I T

0
8

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.
The default command action is reset if the previous ON command takes effect. Thus, if an error or severe error.
occurs while B.FOR is being compiled, the command procedure exits.
If the command procedure does not exit before this command is executed, this command action takes effect.
If a warning, error, or severe error occurs while C.FOR is being compiled, the command procedure exits.
ZK-826-82

Figure 7-1:

ON Command Actions

The action specified by an ON command applies only within the command
procedure in which the command is executed. Therefore, if you execute
an ON command in a procedure that calls another procedure, the ON
command action does not apply to the nested procedure.
In fact, an ON
command executed at any command procedure level does not affect the
error condition handling of procedures at any other level.

7-3

~ONTROLLING

7.1.3

ERROR CONDITIONS AND CTRL/Y INTERRUPTS

Disabling Error Checking

You can use the SET NOON command to request the command interpreter to
not check the status returned from any commands. When the SET NOON
command is in effect, the command interpreter does not perform any
checking of $STATUS. For example:
$ SET NOON
$ RUN TESTA
$ RUN TESTS
$ SET ON
The SET NOON command preceding these RUN commands ensures that if
either of the programs TESTA or TESTB return error conditions the
procedure will continue. The SET ON command restores error checking
by the command interpreter.
When a procedure disables error checking, it can explicitly check the
value of $STATUS following the execution of each command or program.
Fo r ex am pl e :
$ SET NOON
$ FORTRAN MYFILE
$ IF $STATUS THEN LINK MYFILE
$ IF $STATUS THEN RUN MYFILE
$ SET ON
In the above example, the first rF command checks whether $STATUS has
a true value, that is, an odd numeric value.
If so, the FORTRAN
command was successful and the LINK command will be executed.
After
the LINK command, $STATUS is tested again.
If $STATUS is odd, the RUN
command will be executed; otherwise, the RUN command will not be
executed.
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 will be in
effect within the nested procedure. Note ·that SET NOON has no meaning
at command level O.

7.1.4

System Messages

When a DCL command, user program, or command procedure completes
execution, the command interpreter saves the condition code value in
the global symbol $STATUS.
For example, if an error occurs during a
TYPE command, the value in $STATUS represents the specific error
returned by the TYPE command. When a command or program completes
successfully, $STATUS.has an odd value.
Note that the command interpreter always maintains
current value of $STATUS in hexadecimal.

and

displays

the

When any command procedure exits and returns control to another
command level, the command interpreter tests the current value of
$STATUS.
If $STATUS contains an even numeric value, and if its
high-order digit is O, the command interpreter will display the system
warning or error message associated with that status code, if one
exists.
{Otherwise, the message NOMSG will be displayed.)

CONTROLLING ERROR CONDITIONS AND CTRL/Y INTERRUPTS
However, when a command procedure exits following a warning or error
cQndition, the command
interpreter sets the high-order digit of
$STATUS to 1, leaving the remainder of the value intact. Many system
programs that issue their own messages also set this field to 1 so
that the command interpreter does not redisplay the message associated
with the status value.

7.1.5

Commands That Do Not Set $STATUS

Most DCL commands invoke system utilities that generate unique status
values and error messages based on different results.
However, there
are several commands that do not change the values of $STATUS and
$SEVERITY if they complete successfully. These commands are:
CONTINUE
DEPOSIT
EOD
EXAMINE
GOTO

IF
SHOW
STOP
WAIT

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

7.1.6

Status Codes Returned by Compatibility Mode Commands

RSX-llM programs that execute in compatibility mode do not use the
standard error reporting mechanism of VAX/VMS.
These commands do not
use $STATUS to return explicit values based on different results.
Thus, most compatibility mode commands can test or change only
$SEVERITY.

7.2

CTRL/Y INTERRUPT HANDLING

When CTRL/Y is pressed during command procedure execution, control
is
given to a special command level, the CTRL/Y command level. When you
execute a command procedure, you can use the CTRL/Y command level
in
either of the following ways:
•

To interrupt the execution of the procedure and execute one or
more DCL commands.
Then you can either stop the execution of
the procedure or, depending on the commands you entered,
resume execution of the procedure.

•

To provide a default action for
take when CTRL/Y is pressed
procedure.

interpreter to
the command
during
the execution of the

These techniques are described below.

7.2.1

Interrupting a Command Procedure

You can interrupt a command procedure that is executing
interactively
by pressing
either CTRL/C or CTRL/Y.
The effect is the same:
the
command interpreter establishes a new command level, called the CTRL/Y

7-5

CONTROLLING ERROR CONDITIONS AND CTRL/Y INTERRUPTS
level, and prompts for command input. When the interruption
occurs depends on the command that is executing:

actually

•

If the command currently executing
is a command that 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.

•

If the command or program currently executing
is a
separate
image
(that is, an imag~ not executed by the command
interpreter) , the command 1s 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:
image that
is
Issue a DCL command that does not replace the
• currently
executing. Among these commands are the SET VERIFY,
DEPOSIT,
SPAWN
SHOW TIME, SHOW TRANSLATION, ASSIGN, EXAMINE,
and ATTACH commands.
After you issue one or more of these
commands, you can resume the execution of the procedure with
the CONTINUE command.

•

Issue a DCL command that executes another
issue any command
that invokes a new
interpreter returns to command level 0
command.

•

Issue the EXIT command to terminate the program's execution.

•

Issue the STOP command to terminate the procedure's execution.
This command
restores control to command level O. Note that
because commands that execute new images have the same effect
as the STOP command, you do not normally need to use the STOP
command.

image.
When you
image, the command
and executes the

When you interrupt a command procedure during
the execution of a
command or program that is not executed by the command interpreter,
then the CONTINUE command resumes the execution of the
interrupted
command or program.
If you issue a command that invokes a new image,
exit handlers declared by the previous image, if any, will be allowed
to execute before the new image is initiated.*
You cannot resume the execution of a privileged program after
For more information about
interrupting
it by pressing CTRL/Y.
privileged programs, see the software installation guide for your
VAX-11 processor.
The VAX/VMS Command Language user's Guide lists the DCL commands that
are executed---0V-t11'e command interpreter, that is, the commands you can
issue at the CTRL/Y level without causing
the current image to be
stopped.

1. An exit handler is a
routine that receives control
to perform
image-specific cleanup operations when an image exits.
Exit handlers
are described in detail
in the VAX/VMS System Services Reference
Manual and in various language reference manuals.
7-6

CONTROLLING ERROR CONDITIONS AND CTRL/Y INTERRUPTS
7.2.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 action of the
command interpreter (that is, to prompt for command
input at the
CTRL/Y command level) •
For example:

$ ON CONTROL Y THEN EXIT
If a procedure executes the ON command shown above, a subsequent
CTRL/Y interrupt during the execution of the procedure causes the
procedure to exit. Control is passed to the previous command level.
When you press CTRL/Y to interrupt a procedure that has established
CTRL/Y action, the action is taken as follows:

If the command currently executing is a command executed by
• the
command interpreter, the command completes before the
CTRL/Y action is taken.
•

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

The execution of a CTRL/Y action does not automatically reset the
command procedure default CTRL/Y action. A CTRL/Y action remains in
effect until:
•

The procedure terminates (as a result of an EXIT or
command, or a default error condition handling action)

•

Another ON CONTROL Y command is executed

•

The procedure executes the SET NOCONTROL=Y command

STOP

For example, a procedure can contain the 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
flow of execution following CTRL/Y interruptions.
The sample procedures EDITALL.COM
illustrate CTRL/Y action handling.

7-7

and

FORTUSER.COM

describes
in

Appendix

the
A

CONTROLLING ERROR CONDITIONS AND CTRL/Y INTERRUPTS

DBA 1:[HIGGINS]FILES.COM

$ @FILES
$ ON CONTROL_Y THEN GOTO CLEAN_UP

0
$

$ TYPE STATUS, OUT; 1 f)
$ IF $STATUS THEN DELETE STATUS,OUT;l
@PRil.J
$

E>( IT

$
$
$

CLEAN_UP:
DELETE STATUS.OUT;1
DELETE *•TMP;*

E>(!T

Interruption not allo1.1ed.,,continuins'

DBA1:[HIGGINS] PRIV.COM

ON CDNTROL_Y THEN WRITE SYS$0UTPUT" Inter ruPtion not allo1.1ed.,,continuins"

$
$

TYPE STATUS, OUT i 1
IF $STATUS THEN DELETE STATUS.DUT;1

The CTRL/Y interrupt at
occurs during execution of the TYPE command, at f). 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 at Q occurs during execution of the TYPE commanq, at
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

Figure 7-2:

Flow of Execution Following CTRL/Y Action

A CTRL/Y action can be specified for each active command level;
the
CTRL/Y action specified for the currently executing command level
overrides action(s) specified for previous levels, if any.
Note,
however, that if a CTRL/Y action is established at a command level,
the default action for subsequent command levels is to exit.
Figure
7-3 illustrates what happens when CTRL/Y is pressed during the
execution of a nested command procedure.

7-8

CONTROLLING ERROR CONDITIONS AND CTRL/Y INTERRUPTS
$

@SEARCH

OBA 1:[HIGGINS]SEARCH.COM

ON CONTRdL_Y THEN GOTO CLEAN_UP

@SUBSEARCH
NE>'.T _STEP:

E){ IT

CLEAN-UP:

OBA 1:[HIGGINS] SUBSEARCH.COM

@SUBSUB

OBA 1:[HIGGINS] SUBSUB.COM

0
8

ON CONTROL_Y THEN SHOWTIME

If a CTRL/Y interrupt occurs while SEARCH.COM is executing, control is transferred to the label CLEAN_UP.
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.

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

Figure 7-3:

7.2.3

Default CTRL/Y Action for Nested Procedures

Disabling CTRL/Y Interruptions

The SET NOCONTROL=Y command disables CTRL/Y handling completely: that
is, if a command procedure executes the SET NOCONTROL=Y command,
pressing CTRL/Y will have no effect.
The SET NOCONTROL=Y command also cancels the current CTRL/Y action, if
any, and restores the default.
Thus, the correct way to reestablish.

7-9

CONTROLLING ERROR CONDITIONS AND CTRL/Y INTERRUPTS
the default command interpreter action for CTRL/Y handling is to issue
the two commands:
$ SET NOCONTROL=Y
$ SET CONTROL=Y

The first command disables CTRL/Y handling and cancels a current
CTRL/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 issue the SET NOCONTROL=Y command at any command level;
it
affects all command levels until the SET CONTROL=Y command reenables
CTRL/Y handling.
CAUTION
The ON CONTROL Y and SET NOCONTROL=Y
commands
are
intended
for special
applications. It is not recommended, in
general,
that
you
disable
CTRL/Y
interrupts. For example, if a procedure
that disables CTRL/Y interrupts begins
to loop uncontrollably, you cannot gain
control to stop the procedure from your
terminal; you must use another terminal
to terminate the procedure or you must
request the system operator to terminate
it for you. Termination, in this case,
requires the deletion of your process.
For an example of a system-defined procedure that disables CTRL/Y
interrupts for logged-in users, see the sample procedure FORTUSER.COM
in Appendix A.

7-10

CHAPTER 8
CREATING, READING, AND WRITING FILES

This chapter describes ways you can combine DCL commands with the
programming
and symbolic capabilities of command
procedures to
manipulate sequential and
indexed sequential access method
(ISAM)
files.
Included are techniques for using:
OPEN command to create new files or access existing files
•
READ command to read from files
•
WRITE command to write to files
•
CLOSE command to explicitly close files that have been
• opened
during command procedure execution
~e

~e
~e

The basic steps in reading and writing files from a command
are:

procedure

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 or written.
If you open a nonexistent
file
for writing, a
file will be created.
Otherwise, the
file specified in the OPEN command must be an existing file.

Use the READ or WRITE command to read from or write to
the
file.
The READ and WRITE commands use command symbols to
define buffers for
input and output records;
the READ
command
reads a
record · from a file into a symbol and the
WRITE command writes one or more symbols or literal character
strings from a symbol into a single record of an output file.

Use the CLOSE command to close the file.
After you open a
file with the OPEN command,
it remains open until you
explicitly close it or until you log out.

For example, Figure 8-1 shows a command procedure that reads a
record
from an
input file and copies the record into an output file.
The
OPEN commands in the procedure specify whether the
files are opened
for
input or output, create logical names for the files (for use in
subsequent READ and WRITE commands in this procedure) , and
identify
the files.
The READ and WRITE commands use the logical names to refer
to the files and define a symbol that becomes the input/output buffer
for
file reads and writes.
The CLOSE commands are used to explicitly
close both files when the command procedure completes file processing.
The CLOSE commands also deassign the logical names specified for the
files in the OPEN commands.

8-1

CREATING, READING, AND WRITING FILES
DBA1:[HIGGINS]FILES.COM
$
$

OPEN/READ INFILE DATA.TST
OPEN/WRITE OUTFIL DATA.OUT
OBA 1:[HIGGINS]DATA. TST

$
$
$

READLOOP:
READ INFILE RECORD
WRITE OUTFIL RECORD

$
$

FINISH:
CLOSE INFILE
C.LOSE OUTFIL

DBA1:[HIGGINS]DATA.OUT

I- MAXIMUM OF 255 BYTES - 0

The command procedure, Fi°LES.COM

@ The input file, DATA.TST
C)

The output file, DATA.OUT

Q The contents of this buffer is assigned to the READ and WRITE symbol name, RECORD
ZK-829-82

Figure 8-1:

8.1

Steps in Reading and Writing Files

OPENING FILES

With the OPEN command you can open sequential and indexed sequential
access method (ISAM)
files for either reading or writing. When you
open a file, you specify whether it is to be read or written and
assign it a logical name that is placed in the process logical name
table. This logical name is used by subsequent READ and WRITE
commands to reference the file.
If the output file specification on an OPEN/WRITE command does not
include a file version number and if a file with the specified file
name and file type already exists, the WRITE command creates a new
file with a version number one greater than the existing file, unless
the /APPEND qualifier is specified.
The OPEN/WRITE/APPEND command
opens the file and moves the record pointer to the end-of-file,
allowing new records to be appended to the end of an existing file.
The logical devices SYS$INPUT, SYS$0UTPUT, SYS$COMMAND, and SYS$ERROR
do not have to be explicitly opened before they can be read or written
at the command level. All other files must be explicitly opened.
You can issue more than one OPEN command for the same file and assign
it different logical names. If you specify the same logical name on
more than one OPEN command without first closing the file, the file is
not opened, and no warning message is issued.
The OPEN command also allows you to open a file as a shareable file to
allow other users simultaneous read and/or write access. You can open
a file as shareable using the /SHARE qualifier.

8-2

CREATING, READING, AND WRITING FILES
You should be sure that your command procedure closes any open files
before the procedure terminates.
If you fail to close an open file,
the file remains open, and the logical name assigned to the file is
not deleted from the logical name table.
For a description of the OPEN command, its format, and qualifiers, see
the VAX/VMS Command Language User's Guide.

8.2

READING FILES

With the READ command, you can read sequential or indexed sequential
access method (ISAM) files in which all records are less than or equal
to 1024 characters in length. After a file is opened, the command
interpreter maintains a pointer to a current record in the file.
Each
READ command reads the next record and uses the contents of the record
to assign a value to the symbol name specified by the command. The
following sections discuss four of the factors you must consider when
reading files: how to define symbol names, how to handle end-of-file
conditions, how to read records randomly from ISAM files, and how to
delete records from ISAM files.

8.2.1

Specifying Symbol Names for the READ Command

The rules for specifying symbol names are the
symbols with assignment statements:
an

same

•

A symbol name must start with
sign ($), or underscore ( )

alphabetic

•

A symbol name can have from 1 to 255 characters

for

defining

letter,

dollar

When you specify a symbol name fo.r 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, you can use a loop in a command procedure to read
an entire file, as shown below:

$ READLOOP:
$
READ
INF ILE
$
GOTO READLOOP

RECORD

Each time through this loop, the READ command reads a record from the
input file identified as INFILE and redefines the value of the symbol
RECORD.

8.2.2

Handling End-of-File Conditions

When the READ command attempts to read beyond the last record
in the
file, an error condition indicating the end-of-file is returned by the
VAX-11 Record Management Services (VAX-11 RMS). The completion status
value is %RMS-F-EOF.
Note that because the command interpreter
performs normal error checking and message processing following a READ
command, this condition can result in the termination of the command
procedure, unless the procedure has established
its own
error
handling.

8-3

CREATING, READING, AND WRITING FILES
The READ command allows you to specify, with the /END_OF_FILE
qualifier,
the label of a line in the command procedure to be given
control when this completion value is returned.
For example:
$ LOOP:
$
READ/END OF FILE=DONE
$
GOTO LOOP
$ DONE:
$
CLOSE INFILE

INFILE

RECORD

In this example, the procedure executes the READ command
repeatedly
until
the end-of-file status is returned.
Then, control is given to
the line labeled DONE.
Note that labels you specify for /END OF FILE
qualifiers are subject to
the same rules as labels specified for a
GOTO command and are located in the same way.

8.2.3

Reading Records Randomly from ISAM Files

You can use the READ command with the /INDEX and /KEY qualifiers to
read
records randomly from
indexed sequential access method (ISAM)
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, O, is used.
Once a record is read randomly, you can read the remainder of the file
sequentially from that point by issuing READ commands without the /KEY
or /INDEX qualifiers~
For a description of the READ command and
the /INDEX
qualifiers, see the VAX/VMS Command Language User's Guide.

8.2.4

and

/KEY

Deleting Records from ISAM Files

You can use the READ command with the /DELETE qualifier to delete
records from
indexed
sequential
access method
(ISAM) 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 a description of the READ command and the /DELETE
the VAX/VMS Command Language User's Guide

8.3

qualifier,

see

WRITING FILES

The WRITE command can write records only to sequential
files or
indexed sequential
access method (ISAM) files that have been opened
for writing.
When the WRITE command writes a record, it always positions the record
pointer following the record just written.

8-4

CREATING, READING, AND WRITING FILES
8.3.1

Symbol Substitution in the WRITE Command

As shown in Figure 8-1,
the WRITE command automatically performs
symbol substitution on tokens specified as parameters. This applies
to all tokens that begin with alphabetic letters and are not enclosed
in quotation marks.
To specify more than one symbol name, separate them with commas.
You
can intersperse symbol names and literal character strings within a
WRITE command.
For example:
$WRITE OUTFILE "Count is ",COUNT,"."
This WRITE command writes one data record
into the output file
identified by the logical name OUTFILE.
If the current value of the
symbol COUNT is 4, the data record that is written is:
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
This WRITE command
example.

'COUNT'."

equivalent

the

preceding

The sample procedure LISTER.COM in Appendix A
command.

WRITE

illustrates

command

the

WRITE

If you use apostrophes or ampersands to request symbol substitution in
a parameter specified for the WRITE command, iterative substitution
occurs. For example, if you use a lexical function in a WRITE command
as shown below, an error occurs:
$WRITE SYS$0UTPUT 'F$MODE()'
You must place the function in quotation marks:
$WRITE OUTFILE "' 'F$MODE() '"
Otherwise, the replacement of the function F$MODE would occur during
command input, causing the WRITE command to attempt substitution on
the resulting symbol name.

8.3.2

Updating Records Using the WRITE Command

You can use the WRITE command with the /UPDATE qualifier to
record rather than insert a new one.

8.4

change

APPENDING RECORDS TO EXISTING FILES

The OPEN/WRITE/APPEND command allows you to append records to the end
of an existing
file.
When a
file is opened by this command, the
record pointer is positioned at the end-of-file·.
Thus, any. records
that are written to the file are added to the end of the file.

8-5

CREATING, READING, AND WRITING FILES
Figure 8-2 illustrates different ways of specifying data for the WRITE
command.

OBA 1:[HIGGINS]FIGURE.COM

$ @FIGURE

$ ABC := "the character strins"
$ COUNT = a

$ TYPE DATA.OUT
the character strins

ABC
COUNT IS ll
MODE IS INTERACTIVE
FOURTH PARAMETER

0
8
0
0

:= fourth

ParaMeter

$ OPEN/WRITE OUTFILE DATA.OUT
$ WRITE OUTFILE ABC
$ WRITE OUTFILE "ABC"
$ WR I TE OUTF I LE COUNT Is
tCOUNT
$ WR I TE OUTF I LE MODE Is
F$MODE ( )
$ WRITE OUTFILE P'COUNT'
$ CLOSE OUTFILE
II
II

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

8 If a character string is enclosed in quotation marks, the WRITE command does not perform symbol substitution.
0 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.

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.

e );

ZK-830-82

Figure 8-2:

8.5

Symbol Substitution with the WRITE Command

ERROR HANDLING

The ON command, described in Chapter 7, provides a default course of
action when errors occur during the execution of a command procedure.
You can use an ON condition action to control what happens throughout
a procedure. The OPEN, CLOSE, READ, and WRITE commands also allow you
to specify labels to receive control in case an error occurs during
the processing of the specific command.
For example:
$ OPEN/READ/ERROR=NOT_FOUND INFILE CONTINGEN.DOC
This OPEN command requests that the file named CONTINGEN.DOC be opened
for ~eading.
If the file cannot be opened for any reason, for
example, if it does not exist, the OPEN command returns an error
condition. Control is transferred to the label NOT FOUND.
Any error path specified with the file-handling commands (OPEN, READ,
WRITE, and CLOSE) overrides the current ON condition established for
the command level.
Moreover, an error path, successfully taken,
changes the value of $STATUS to a success code. Thus, the procedure
cannot, in this case, determine the specific reason for the error.
The following examples illustrate this aspect of er~r handling.

CREATING, READING, AND WRITING FILES
$
$

ON ERROR THEN GOTO CHECK
OPEN/READ INFILE 'Pl'

$ CHECK:
$
WRITE
SYS$0UTPUT
'F$MESSAGE($STATUS)'"

opening

"Error

file:

In the above example, if an error occurs during opening of the file
specified by Pl, control goes to the label CHECK. At CHECK, $STATUS
still contains the numeric status value associated with the specific
error that occurred.
$

OPEN/READ/ERROR=CHECK FILE 'Pl'

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

In this example, if an error occurs opening the file, control goes to
the label CHECK as a result of the /ERROR qualifier.
However, at this
label, the value of $STATUS is always a success code;
the procedure
cannot check fo~ or display the specific status value that caused the
error.

8.6

COMMUNICATING WITH PROCESS-PERMANENT FILES

You can also use the READ and WRITE commands to
read data from the
current input device or to write messages on the current output
device.
The
process-permanent
files
SYS$INPUT,
SYS$0UTPUT,
SYS$COMMAND,
and SYS$ERROR do not have to be explicitly opened before
you refer to them in READ or WRITE commands.
For example:
$ READ SYS$COMMAND TESTID
This READ command results in a read to the current device SYS$COMMAND;
thus, when the procedure is executed interactively, the read is issued
to the terminal.
When the READ command executes, the command
interpreter displays the following prompt at the terminal:
Data:
Whatever you type in response to this prompt is then
symbol named TESTID.

equated

the

Similarly, you can write a line of data to the terminal, or whatever
the current output device is, with the.WRITE command.
For example:
$ WRITE SYS$0UTPUT "Count is ''COUNT'...

continuing ••• "

Before this line is displayed on the terminal, the symbol named
is replaced with its current value.

COUNT

Note that the logical name TT the system equates to the current
interactive terminal is not a process permanent file.
To write to TT,
you must explicitly open it.

8-7

CREATING, READING, AND WRITING FILES
8.7

FILE FORMATS

You can use the READ command to read
any existing sequential or
indexed sequential
access method
(ISAM)
file.
The maximum record
length that the READ command accepts is 1024 characters.
When you create a file with the WRITE command, you cannot specify any
attributes for the file:
the command interpreter always creates a
file in print file for~at.
The record format for
the file
is VFC,
with a two-byte header for each record.
These files are therefore not compatible with files created by the sos
editor or with RSX-llM utilities invoked by DCL commands.
If you
create a file with the DCL command WRITE and you want to use the file
as
input
to another program or command, you can perform an
intermediate step to convert the file to a suitable format.
One
simple way to do this is to invoke the SOS editor to edit the file and
then write the file back onto disk.
SOS removes the carriage control
bytes from each record as it writes the output file.
For example:

$ OPEN/WRITE OUTFILE DATA.OUT

$ CLOSE OUTFILE
$ EDIT/SOS/NOLINES DATA.OUT
EB

After a file is closed, you can specify it as an
input file to
the
editor;
the /NOLINES qualifier in this example indicates to SOS that
the file does not have line numbers associated with the records in the
file.
The SOS command EB follows the EDIT command in the input stream
for the procedure:
the EB command writes the file onto disk without
incrementing the version number.

8-8

CHAPTER 9
CONTROLLING BATCH JOBS

This chapter describes techniques for controlling batch jobs.
It
includes information useful both to batch users and to interactive
users who submit command procedures to a batch job queue.
The following topics are discussed in this chapter:

9.1

•

How the system executes batch jobs

•

Batch job output

•

Synchronizing batch job execution

HOW THE SYSTEM EXECUTES BATCH JOBS

When the system executes a command procedure submitted to a batch job
queue,
it creates a detached process to execute the commands. This
process receives your disk and directory defaults and the same
resource quotas and privileges that were given to your interactive
process when you logged in. This process is given a name of the form
JOBnnn where nnn is the job number assigned to the job. The process
executes under your UIC.
Figure 9-1 illustrates how the system
executes a batch job.

9.1.1

The Batch Job Queue

Once a job has been entered in a batch job queue, you can monitor
status with the SHOW QUEUE command.
For example:

its

$ SHOW QUEUE SYS$BATCH
This command would show the current contents of the SYS$BATCH queue.
The following command would show the current contents of all batch
queues:

$ SHOW QUEUE /BATCH/ALL
All jobs in batch queues have job numbers, but no job in a queue has a
process created for its execution until the job becomes a current job.
Thus, jobs identified in batch queue displays as "current"
jobs are
active processes;
jobs identified as "pending" jobs or "holding" jobs
are in the queues, but processes have yet to be created for them.

9-1

CONTROLLING BATCH JOBS

Userna111e:
Pass1.1ord:

HIGGINS

SUBMIT TESTALL
Job 210 entered on ciueue SYS$BATCH

•

DBA 1:[HIGGINS]TEST ALL.COM

Command interpreter
finds TEST ALL.COM
on default device
and directory ...

$
$
$

RUN A
RUN B
RUN C

then requests queue
for the batch job

SYS$BATCH QUEUE

TEST ALL.COM gets a
job number and is
placed in SYS$BATCH
queue

---~
JOB NUMBER
JOB NUMBER
JOB NUMBER

Command interpreter
returns job information (and control)
to interactive
command level

I
I

Input stream is
DBA1 :[HIGGINS]TESTALL.COM

Output stream is
DBA 1:[HIGGINS]TESTALL.LOG
a temporary file that is deleted
after it is printed.

08
09

When Job 210
can be executed,
a process is
created to execute
the job. When
the job is completed,
the process is
deleted

ZK-831-82

Figure 9-1:

9.1.2

How the System Executes a Batch Job

Controlling Jobs in the Batch Job Queue

After a job has been submitted to the queue, there are actions you can
take to control whether the job is executed, when it is executed, and

9-2

CONTROLLING BATCH JOBS
so on. The following paragraphs summarize some of the actions you can
take and the commands you would use to perform particular actions.
To change the name of a job after it has been queued
system begins processing it, use:

but

before

the·

use

one

the

SET QUEUE/ENTRY=nnn/NAME=newname queue-name
To change the processing priority of a
following:

batch

job,

SET QUEUE/ENTRY=nnn/PRIORITY=new-priority queue-name
SET PROCESS/PRIORITY=new-priority JOBnnn
The privilege ALTPRI is required to raise the priority for a job.
To delay processing of a batch job until
a specific
specific time of day, use of one of the following:

date

and/or

SUBMIT/AFTER=date-time file-spec
JOB username /AFTER=date-time
SET QUEUE/ENTRY=nnn/AFTER=date-time queue-name
To delay processing of a batch job for an indefinite period
use:

time,

SUBMIT/HOLD file-spec
To delete an entry from a batch job queue,
processed or while it is being processed, use:

eithei

before

DELETE/ENTRY=nnn queue-name
To delete an entry from a batch job queue while it is being processed,
use:
STOP/ENTRY=nnn queue-name
Entry deletion may require GROUP or WORLD privilege.
To give a batch job a specific processing priority with
other processes in the system, use one of the following:

respect

SUBMIT/PRIORITY=priority file-spec
JOB username /PRIORITY=priority
OPER privilege is required to enter a job at a higher priority.
To release for processing a batch job that is being held in
use:

queue,

SET QUEUE/ENTRY=nnn/release queue-name
To specify a name for a batch job, overriding
the
assigned by the system, use one of the following:
SUBMIT/NAME=new-name file-spec
JOB username /NAME=new-name

9-3

default

job

name

CONTROLLING BATCH JOBS
To name a specific batch job queue in which the.batch
entered, use one of the following:

job

should

SUBMIT/QUEUE=queue-name file-spec
JOB username /QUEUE=queue-name
To specify a lower CPU time limit than that established by the system
manager for jobs in the particular queue, use one of the following:
SUBMIT/CPUTIME=n file-spec
JOB username /CPUTIME=n
To specify a lower working set quota than that established by the
system manager for jobs in the particular queue, use one of the
following:
SUBMIT/WSQUOTA=n file-spec
JOB username /WSQUOTA=n

9.1.3

Concatenating Procedures into a Single Job

When you issue the SUBMIT command, you can specify that more than
command procedure is to be executed in one job. For example:

one

$ SUBMIT ALPHA,BETA
This SUBMIT command concatenates the procedures ALPHA.COM and BETA.COM
and executes them as if they consisted of a single input stream.
ALPHA.COM is executed, and if it completes without an error or severe
error, BETA.COM is executed.
When two or more procedures are submitted this way, the operating
context of the first procedure is preserved for the second procedure;
that is, local symbols defined at command level 0 continue to exist,
the current ON condition action remains in effect, and so on.

9.2

BATCH JOB OUTPUT

When a batch job is executed, its output stream consists of messages
written to SYS$0UTPUT and SYS$ERROR. This output stream i-s equated to
a batch job log file.
The system locates this file
in your default
directory, giving it a file specification of name.LOG, where name is
the job name. By default, the job name is taken from the first eight
characters of the file name of the command procedure. However, you
can use the /NAME qualifier on the SUBMIT command to define an
alternate name for the job. In either case, the system automatically
queues the log file for printing when the batch job is completed and
deletes the file from your directory after it is printed.
The batch job log file includes, by default, all command lines
executed
in the command procedure, system and user-program output to
SYS$0UTPUT and SYS$ERROR, and job termination accounting
information.
The job termination information is equivalent to the long form of the
system logout message.

9-4

CONTROLLING BATCH JOBS
9.2.1

Including All Command Output in the Batch Job Log

Typically, a batch job that compiles, links, and executes a
program
creates additional
printed output:
a compiler listing, for example,
and often a linker map file.
To produce printed copies of these
files, a batch job can contain the PRINT command(s) necessary to print
them, as in the following example:
$ FORTRAN BIGCOMP
$ PRINT BIGCOMP
$ LINK/MAP/FULL BIGCOMP
$ PRINT BIGCOMP.MAP
When this batch job 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
this case, the batch job log.

•

Use qualifiers on appropriate commands to direct the output to
the current output device.

The following example shows the latter 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 batch job log.
Note that if you use this technique, the output file(s) are not saved
on disk.

9.2.2

Saving the Batch Job Log File

Normally, a batch job log file is written as a job is executed.
When
the job has been executed, the system closes the file and queues it
for printing with the delete option, so that the file will be deleted
from your directory after it has printed.
If you are an interactive user, however,
situations will arise
in
which you would like either to save the output from a batch job in a
disk file, or to not print the output but to examine
it from your
terminal.
To suppress the printing
and deleting of the batch job
output, you must assign a dummy equivalence name for the logical
name
SYS$PRINT.
For example:

$ DEFINE SYS$PRINT DUMMY
The name DUMMY is any.name that is not a device or queue name.
The
system always tries to queue the log file to the device queue named
SYS$PRINT.
If SYS$PRINT is equated to an invalid name (or a name that
is not the name of a valid queue), the file cannot be printed.
Note that you can use the same technique
output log
to a specific line printer.

9-5

to direct the batch job
For example, if you want to

CONTROLLING BATCH JOBS
ensure that the log file is printed on the printer named LPBO, you
could include the following logical name assignment in the batch job
log:
$ DEFINE SYS$PRINT LPBO:

9.2.3

Terminating a Batch Job Abnormally

A batch job terminates normally as a result of:
•

The end-of-file or an EXIT command at command level O

•

A STOP or LOGOUT command at any command level

When a job terminates, that is, when there are no more files in the
job to be processed, the system deletes the process that was created
to execute the job. During the termination procedure, the log file is
printed.
Note that the batch job log file is not printed, and is not deleted,
if the job terminates as a result of a DELETE/ENTRY or STOP command;
it remains in your default directory.
To use the DELETE/ENTRY command, specify the job number of the job
be deleted.
For example:

$ DELETE/ENTRY=312 SYS$BATCH
To use the STOP command, you must
assigned to the job.
For example:
$ STOP

specify

the

full

process

name

JOB312

The STOP command requires the user privilege GROUP to control other
processes in the same group or the user privilege WORLD to control
other processes not in the same group.
CAUTION
Terminating jobs using either of these
commands
is
considered
abnormal
termination
because
the
operating
system's normal job termination activity
is preempted. The batch job log does
not,
for example, contain the standard
logout message that summarizes job time
and accounting
information.
However,
termination
that
results
from
an
explicit EXIT or STOP command in the
procedure or the implicit execution of
either of these commands following an
error condition based on the current ON
condition
is
considered
normal
termination, since the operating system
can
perform
proper
run-down
and
accounting procedures.

9.3

SYNCHRONIZING BATCH JOB EXECUTION

The SYNCHRONIZE and WAIT commands both place a job in a wait state:
the SYNCHRONIZE command waits for the completion of another job, while

9-6

CONTROLLING BATCH JOBS
the WAIT command waits for a specified period of time to elapse.
For
example,
if jobs are submitted concurrently to perform cooperative
functions, one job can contain the 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 9-2 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.
OBA 1:[HIGGINS]MAINCOMP.COM

$ SUBMIT MAINCOMP
JOB 31ll entered on ciueue SYS$BATCH
$ SUBMIT MINCOMP
JOB 315 entered on ciueue SYS$BATCH

0
0

$ FORTRAN ALPHA/LIST
$ SYNCHRONIZE MINCOMP
$ LINK/MAP/FULL ALPHAtBETA
$

D(IT

OBA 1:[HIGGINS] MINCOMP.COM

$ FORTRAN BETA/LIST
$

E){ IT

0 Individual SUBMIT commands are required to submit two separate jobs. Two separate processes will be created.

8 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

Figure 9-2:

Synchronizing Batch Job Execution

Job names specified for the SYNCHRONIZE command must be for jobs that
are executing with the same group number in their user identification
codes (UICs). To synchronize with a job that has a different group
number (for example, that was submitted by a different user), you must
use the jobid.
For example:
$ SYNCHRONIZE/ENTRY=454
This SYNCHRONIZE command places the current
wait state until job 454 completes.

command

procedure

The WAIT command is useful
for command procedures that must have
access to a shared system resource, for example, 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 will place 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$LOGICAL("RK") '"

9-7

CONTROLLING BATCH JOBS

The IF command following the ALLOCATE request checks the value of
$STATUS.
If the value of $STATUS indicates successful completion, the
command procedure will continue.
Otherwise, the procedure issues the
WAIT command;
the WAIT command
speGifies 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.

9-8

APPENDIX A
ANNOTATED COMMAND PROCEDURES

This appendix contains complete command procedures that demonstrate
the concepts and techniques discussed in Chapters 1 through 9.
Each
section in this Appendix discusses one command procedure and contains
the following:
•

The name of the procedure

•

A listing of the procedure

•

Notes that
procedure.

•

The results of a sample execution of the procedure

explain

concepts

techniques

used

the

The command procedures are:
Section A.l

CONVERT.COM

This procedure converts an absolute time value (for example, 10:45) to
a delta time value (for example, 01:05). The procedure illustrates
use of the F$TIME and F$EXTRACT lexical
functions and the use of
assignment statements to perform arithmetic calculations and to
concatenate symbol values.
WAKEUP.COM

Section A.2

This procedure places the current interactive user process in a wait
state until a specific time of day. Then, it displays a message on
the terminal indicating the time. The procedure illustrates use of
the INQUIRE and WRITE commands and how command levels communicate
using a global symbol.
Section A.3

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$PARSE,
F$SEARCH,
F$FILE_ATTRIBUTES, and F$FAO lexical functions.
Section A.4

SYS. COM

This procedure returns statistics about processes in the current
process list.
If the current process has GROUP privilege, statistics
for all processes in the group are returned.
Statistics for all
processes on the system are displayed if the current process has WORLD
privilege. 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

This procedure returns the number of parameters that were passed to a
procedure.
Note that this procedure must be defined as a command
synonym;
it can be called from any procedure.
EDITALL.COM

Section A.6

This procedure invokes the SOS 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

This example of a system-defined login file provides a controlled
terminal environment for an interactive user who creates, compiles,
and executes FORTRAN programs.
This procedure 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

This is a procedure that prompts for input data, formats the data
in
columns, and then 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

This procedure performs arithmetic calculations
resulting value to hexadecimal and decimal values.

A-2

and

converts

the

ANNOTATED COMMAND PROCEDURES

A.l

CONVERT.COM
$ ! Check for inquiry
$
$ IF Pl .EQS. "?" .OR. Pl .EQS. "" THEN GOTO TELL
$
$ ! Verify the parameter:
it must be 5 characters long
$
it must contain a colon (:)

fJ ~ IF F$LENGTH(Pl) .NE. 5 .OR. -

F $ LQC ATE ( " : " , P 1 ) • NE • 2 THEN GOTO BADTIME

e ~$ TIME = F$TIME ()

! Get the current time

Extract the hour and minute fields from both the current time
value and the specified absol~te time value

$
$

e $ MINUTES = F$EXTRACT(l5,2,TIME)

$ HOURS = F$EXTRACT(l2,2,TIME)
$ ABS HOURS = F$EXTRACT(0,2,Pl)
$ ABS-MINUTES = F$EXTRACT(3,2,Pl)
$ !
$ ! Verify that the values are in correct
$ !

Current minutes
Current hours
Hours in absolute time
Minutes in absolute time
range of 24-hour clock

$ IF ABS HOURS .GTS. "23" .OR. ABS MINUTES .GTS. "59" -

THEN GOTO BADTIME
$

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

$
$

$ CURRENT TIME

= HOURS*60 + MINUTES

$ ABS TIME = ABS HOURS*60 + ABS MINUTES
$
$ ! Compute difference in hours and minutes
$ !

$
$ MINUTES TO WAIT = ABS TIME - CURRENT TIME
$
$
If the result is <O the time is assumed to be a
$ ! tomorrow time; more calculation is required.
$ !
$ IF MINUTES TO WAIT .LT. 0 THEN -

MINUTES-TO WAIT

= 24*60 - CURRENT TIME + ABS TIME

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:
$
-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 HOU~S TO WAIT LOUP
$ FINISH COMPUTE:
$ !
$ ! Construct the delta time string in the proper format
$

~ $ WAIT TIME

+":00.00"

== F$STRING (HOURS_TO_WAIT)+": "+F$STRING (MINUTES_TO WAIT} -

$ !

$
$
$
$
$

! Examine the second parameter

IF P2 .EQS. "SHOW" THEN SHOW SYMBOL WAIT TIME
!
! Normal exit

A-3

ANNOTATED COMMAND PROCEDURES
$
$
$
$
$

EXIT
!
! Exit taken if first parameter is not formatted correctly
! Error status is returned but not displayed

49 $ BADTIME:

$ WRITE SYS$0UTPUT "Invalid time value: ",Pl,", format must be hh:mm"
$ EXIT %xl0000000
$
$ ! Output message and exit if user enters inquiry

TYPE SYS$INPUT
~~ TELL: Converts
an absolute time value to a delta time value.
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.
The format is:
@CONVERT hh:mm [SHOW]
Notes

t»

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 will
branch to the label TELL (Note 13).

The procedure checks the value of the parameter.
a time value in the format:

It must

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 will branch to the
label BADTIME (Note 12).

The F$TIME lexical function places the current time value
the symbol TIME.

The F$EXTRACT function extracts, from the saved current time
value
and from the absolute time value entered as a
parameter, the minutes and hours fields of each. The string
functions
return character strings representing decimal
values. These values can now be manipulated as strings, or
because of implicit string to integer conversion, integers.

The IF command verifies that the time value entered is a
valid 24-hour clock time. If the value of the hours field is
greater than "23" or if the value of the minutes field is
greater than "59", the procedure will branch to the label
BADTIME (Note 12).

Assignment statements implicitly convert both the current
time string and the entered time string to an integer equal
to the number of minutes by multiplying the hours by the
intger 60 and adding the minutes.

The procedure then subtracts
specified time in minutes.

A-4

the

current

time

from

the

ANNOTATED COMMAND PROCEDURES

If the result is less than o, the time will be after 24:00,
that is, on the next day.
In this case, the procedure
calculates the minutes to wait by subtracting the current
time from 24 hours to find the time remaining in the current
day and then adding the entered 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~ Tt checks whether MINUTES TO WAIT is
greater
than
60.
If so, it will subtract -60 from
MINUTES TO WAIT and add 1 to the accumulator for the number
of hours (HOURS_TO_WAIT).

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' current values and separated
with an intervening colon.
The symbol WAIT TIME has the
delta time value. WAIT TIME is. defined as a global symbol so
that it will not be deleted when the procedure WAIT TIME
exits.

If a second parameter, SHOW, was entered, the procedure will
display the resulting time value. Otherwise, it will exit.

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 with an error status.
The high order digit in the
error status is set to 1 in order to suppress the output of
an error message.

At the label TELL, the procedure displays information about
what the procedure does. The next command in the procedure
(EXIT) is also the end-of-file for the input data stream that
the TYPE command is reading.

Sample Execution
$ SHOW TIME
10-JUN-1982 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-5

ANNOTATED COMMAND PROCEDURES
A.2

WAKEUP.COM

$ SAVE VERIFY = F$VERIFY("NO")
$
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
$
$
8$ INQUIRE WAKE TIME "Enter time to wake"
$
Call the CONVERT.COM procedure to convert the absolute time
$
to a delta time
$
$
8 $ @CONVERT 'WAKE TIME'
$
$ ! Check the return status for success
$ IF .NOT. $STATUS THEN GOTO END
$
Wait the specified delta tim•
$ WAIT 'WAIT TIME'
$
ASCII code for terminal bell
0$ BELL[0,32]= %X07
$
$ WRITE SYS$0UTPUT BELL,"Wake up -- Time is ''F$TIME() '"
$
END:
IF SAVE VERIFY THEN SET VERIFY
Restore verification, if set

Notes

The procedure saves the current verification setting
symbol name SAVE_VERIFY, then sets verification off.

the

The procedure uses the INQUIRE command to prompt for the time
desired to wake up the process.
The value entered in
response to INQUIRE is used
as input to the
CONVERT
procedure.
The CONVERT procedure returns
the
delta
time
value
corresponding to the . interval
from the current time until
wake up time in the global symbol WAIT TIME.
The procedure
uses this symbol to specify the time-parameter for the WAIT
command. At this point the return status for the CONVERT
procedure is checked for success.
If the conversion returns
an error, control is routed to the end of the procedure.
After the specified period elapses, the process awakes and
the
procedure constructs a message to display on the
terminal.
It gives the symbol named BELL the binary value of
the bell character on an ASCII terminal.
The WRITE command
automatically replaces this symbol with its value
and
concatenates the result with a literal character string.
The
terminal's bell rings as the message is displayed.
The IF command tests whether the symbol VERIFY has a
true
value;
if so, verification was in effect before the
procedure was invoked and will be restored.
Otherwise
verification will remain off.
Note that the EXIT command
will be displayed on the terminal
if verification was on
before the command procedure was executed.

A-6

ANNOTATED COMMAND PROCEDURES
Sample Execution
$ SHOW TIME
10-JUN-1982 10:39:12
$ @WAKEUP
Enter time to wake: 11:30
Wake up -- Time is 10-JUN-1982 11:30:00.00
The procedure prompts for a time value.
Then, the terminal
is in a
wait state until the time elapses.
The terminal's bell (if there is
one) sounds when the message is displayed.
Note that if you execute this procedure, you can terminate the wait
state of the terminal at any time by pressing CTRL/Y and issuing any
DCL command.

A-7

ANNOTATED COMMAND PROCEDURES
A. 3

DIR.COM

$
Command procedure implementation of DIRECTORY/SIZE=ALL/DATE
$
command
$
$
$SAVE VERIFY= F$VERIFY((O)
! Turn verification off
$Pl =-F$PARSE(Pl,"*.*;*")
Create directory wild
! card spec
$
Header not printed yet
$ FIRST TIME = "TRUE"
No files found yet
$ FILE COUNT = 0
No blocks allocated yet
$ TOTAL ALLOC = 0
No blocks used yet
$ TOTAL-USED = 0
$

$LOOP:
FILESPEC = F$SEARCH(Pl)
8 $
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 header line
$
FIRST TIME = "FALSE"
$
8$
DIRSPEC = F$PARSE (FILESPEC,, ,"DEVICE") +F$PARSE(FILESPEC,,,"DIRECTORY")
$
WRITE SYS$0UTPUT ""
WRITE SYS$0UTPUT "Directory ",DIRSPEC
$
$
WRITE SYS$0UTPUT ""
LASTDIR = DIRSPEC
$
$
$

Put the file name together, get some of the file attributes, and
type the information out
$
$
Q $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 XTTRIBUTES(FILESPEC,"EOF")
$
TOTAL ALLOC =-TOTAL ALLOC + ALLOC
$
TOTAL-USED = TOTAL USED + USED
$
LINE;;- F$FA0("!19AS !5UL/!5<!UL!> !17AS" ,FILENAME,$
USED, ALLOC, F$FILE(FILESPEC,"RDT"))
WRITE SYS$0UTPUT LINE
$
GOTO LOOP
$
$
$

$
$

Output summary information, reset verification, and exit
$ !
$DONE:
$
WRITE SYS$0UTPUT ""
$
WRITE SYS$0UTPUT "Total of ''file count' files, ",
total used, "/", ~otal_alloc, " blocks."
IF SAVE VERIFY THEN SET VERIFY
$
EXIT
$

A-8

ANNOTATED COMMAND PROCEDURES
Notes

The procedure creates a directory wild card specification
using
the F$PARSE lexical function.
This specification wild
cards any
blank
fields
in
the
user-supplied
file
specification.
If no parameter
is specified when the
procedure is executed, all files
in the current process's
default directory are displayed.

f.)

The F$SEARCH lexical function searches the directory for
the
next file.
If no more files are
found,
the procedure
branches to DONE.
(see note 5).

The F$PARSE
lexical
function
uses
the
first
file
specification found by the search to construct a header for
the directory display.

(»

In this loop, the procedure uses the F$PARSE lexical function
to extract the file name to be diplayed from each file name
in the directory.
The F$FILE ATTRIBUTES lexical
function
then obtains blocks used, blocks allocated, and creation date
information about each file.
Finally, the file name and file
attribute
information are used
as arguments for the F$FAO
lexical
function.
The F$FAO function
formats a
single
display line for each file in the directory.

When no more files are
found by F$SEARCH,
the procedure
branches to DONE and summary information is displayed showing
total number of files the total blocks used,
and
the total
blocks allocated in the directory.

Sample Execution
$ @DIP VERN] • COM
Directory DBAO: [VERN]
BATCH.COM;l
CALC.COM;3
CONVERT.COM; 1

1/3
1/3
5/6

16-JUN-1982 11:43
16-JUN-1982 11:30
16-JUN-1982 15:23

2/3
1/3
1/3

16-JUN-1982 13:17
16-JUN-1982 09:49
16-JUN-1982 11:29

Total of 15 files,

22/48 blocks.

The procedure returns information on all COM files
[VERN].

A-9

the