Digital PDFs

AA-CF03A-TC

June 1985

186 pages

Original

94MB

Document:	RSTS/E V9.0 Guide to Writing Command Procedures
Order Number:	AA-CF03A-TC
Revision:	0
Pages:	186
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsts_e/V10/AA-CF03A-TC_RSTS_E_Guide_to_Writing_Command_Procedures_Jun1985.pdf

OCR Text

RSTS/E
Guide to Writing Command Procedures
Order No. AA-CF03A-TC

\
)

RSTS/E
Guide to Writing Command Procedures
Order No. AA-CF03A-TC

June 1985
This manual presents concepts and techniques for developing command procedures using the RSTS/E DIGITAL Command language (DCl).

OPERATING SYSTEM AND VERSION:

RSTS/E

V9.0

SOFTWARE VERSION:

RSTS/E

V9.0

digital equipment corporation, maynard, massachusetts

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 or its affiliated companies.

The postage-paid READER'S COMMENTS form on the last page of this document requests your critical evaluation to assist us in preparing future documentation.

The following are trademarks of Digital Equipment Corporation:

~DmDDmD ™
DEC
DEC mail
DECmate
DEC net
DECtape
DECUS
DECwriter

DIBOL
FMS-ll
LA
MASS BUS
PDP
P/OS
Professional
Q-BUS
Rainbow

ReGIS
RSTS
RSX
RT
UNIBUS
VAX
VMS
VT
Work Processor

CONTENTS

PREFACE
CHAPTER 1

Introduction
What are Command Procedures? . . . . . . . . . . .
Creating Command Procedures
.........
Formatting Command Procedures . . . .
. ....
Executing Command Procedures. . .
. ....
Executing Command Procedures at Login . . . . .
Executing Command Procedures at Interactive
Level . . . . . . . . . . . . . . . . . .
·
Executing Command Procedures in Batch Mode .
Executing Nested Command Procedures . . . .
·
Executing Command Procedures with the RUN
Command . . . . . . . . . . . . . . . . . . . ·
Chaining to Command Procedures from a Program ·
Executing Command Procedures with CCLs . .
Command Procedures and System Management . . . . ·

CHAPTER 2

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

1-9

Using Symbols in Command Procedures
Symbols in DCL
. . . . . . . . . . 2-1
Symbol Names . . . . . . . . . . . . . . . . . . . 2-2
Symbol Values . . .
. . . . . . . . . . . . . 2-3
Symbol Types. .
. . . . . . . . . . . . . 2-4
Symbol Assignment
. . . . . . . . . . . . . . 2-4
String Assignment . . . . . . .
. . . . . . 2-5
Symbol Tables
. . . . . . . . ..
. 2-6
Symbol Substitution
......
...
. 2-8
Command Synonyms.
......
...
2-8
Apostrophes in Symbol Substitution
. . . . . . 2-9
Automatic Evaluation. . . . . . . .
. . . 2-10
Undefined Symbols . . . . . .
. . . . . . 2-11
Verifying Symbol Substitution
. . . . . . 2-11
Displaying Symbols.
. . ..
. . . . . . 2-12
Deleting Symbols. . . . . . . . .
. . . . . . 2-14

CHAPTER 3

Expressions and Operators
Operands in Expressions
Strings . . .
.
Integers. . . . . . .
DCL Functions
Symbols . . .
Value Type Conversion in
iii

. . . . . ..
. ....
. .
. ....
. . . . . . . . ..
.
. . . . . . . . ..
.
. . . . . ..
. ....
Expressions . . . . . . .

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

Converting Strings to Integers
....
. 3-6
Converting Integers to Strings . . . . . . . . . 3-6
Operators in Expressions . . . . . . . . . . . . . 3-7
Arithmetic Operations . . . . . . . . . . . . . 3-9
Logical Operations . . .
. . . . . . . . . . 3-9
Arithmetic Comparisons. . . . . . . . . . . . 3-10
String Comparisons .
. . . . . . . . . 3-10
String Concatenation . .
. . . . . . . . . 3-11
CHAPTER 4

DCL Functions in Command Procedures
Format of DCL Functions . . . . . . . . . . . . . 4-1
DCL Functions . . . . . . . . . . . . . . . . . . 4-2
F$ACCESS . .
. . . . . . .
. 4-5
F$ASCII
. . . . . . . . . . . . . ..
. 4-6
F$CHR . . . . . .
. . . . . . . . . . . . . 4-7
F$CVTIME
..............
... 4-9
F$EDIT
.....
. . . . . . . . . . . . 4-10
F$INSTR
. . . . . . . . . . . . . . .
4-12
F$INTEGER . . . .
. . . . . . . . . . . . 4-14
F$JOB . . .
. . . . . . . . . . . . . 4-15
F$LEFT
. . . . . . . . . ..
. . . . 4-16
F$LENGTH . . . . . . . . . . . . .
4-17
F$MESSAGE
. . .
. . . . . . . . . 4-18
F$MID
. . . . . . . . . . . . 4-19
F$NODE
......
. . . . .
4-20
F$PARSE . . .
...
. . . . . . . . . 4 - 21
F$PRIVILEGE . . .
. . . . . . 4-30
F$RIGHT . . . . . . . . . . . . . . . . . . . 4-34
F$ SEARCH
. . . . . .
. . . . . . 4 - 35
F$STRING
. . . . . . . . . . . . . . . . 4-37
F$TERMINAL
. . . . . . . . . . . . . . . . 4 - 38
F$TIME
. . . . . . . . . . . . . . . . . 4 - 39
F$TYPE .
. . . . . . . . . . . . . . . . 4-40
F$USER
. . . . . . . . . . . . . . . . . . 4-41
F$VERIFY
. . . . . . . . . . . . . . . . . . 4-42

CHAPTER 5

Interacting with Command Files
Passing Data. . . . . . . . . .
. . . . . . . 5-1
Passing Parameters . . . . . . . . . . . . . . . 5-2
Prompting for Symbol Values . . . . . . . . . . 5-4
Returning Data
. . . . . . . . . . . . . . . . . 5-7
Displaying Data . . . . . . . . . . . . . . . . . 5-8
Supplying Data to a Program . . . . . . . . . . . 5-8
Reading Data in a Program . . . . . .
. . . 5-8
Supplying Data to a Program from a Terminal
5-10
Signaling the End of a Data List . . . . .
5-12
Exiting from a Program in a Command File.
5-12
Detaching Programs in a Command Procedure
5-13
iv

Passing Symbol values to a Program.
CHAPTER 6

5-14

File Input and Output
Opening
Reading
Writing
Closing

CHAPTER 7

· · · · · ·
· · · · · ·
· · · · · ·
· · · · · ·

Files
F'iles
Files
Files

· · · · · · .. 6-2
· · · · · · 6-5
6-8
· · · · · · 6-11
· · · · · ·

Controlling Execution Flow in Command Procedures
The IF Command. . .
...
. . . . . . . 7-1
Command Line Labels
. . . . . . . . . . 7-3
The GOTO Command. .
. . . . . . ..
. 7-4
Nesting Command Procedures. . . . . . . . .
. 7-6
Exiting from a Command Procedure
. . . . . . . 7-8
The EXIT Command. . . . . .
. . . . . . . 7-8
The STOP Command. . . . . . .
. . . . . . 7-10

CHAPTER 8

Controlling Error Conditions and CTRL/C Interrupts
Error Condition Handling. .
. .......
$STATUS and $SEVERITY Symbols
....
..
The ON Command . . . . . . .
....
Enabling and Disabling Error Checking . . . . .
CTRL/C Interrupt Handling . . . . . . . . . . . .
Setting a CTRL/C Action Routine . . . . . . . .
Disabling and Reenabling CTRL/C Interruptions
.

CHAPTER 9

8-1
8-1
8-4
8-6
8-7
8-8
8-9

Controlling Terminal Output
SET [NO)ECHO Command . . . . . . . . . . .
SET [NO)VERIFY Command
...... .
Creating a Log File of a Terminal Session
OPEN/LOG_FILE
. . . . . . . . . . .
CLOSE/LOG_FILE . . . . . . . . . .
·
SET LOG FILE
........... . ·

· . 9-1
• • • • 9 .. 3
9-3
• • 9-4
• • • . 9-6

. . . . 9-6

APPENDIX A

Sample Command Procedures

APPENDIX B

RSTS/E and VAX/VMS Command Processor Differences

APPENDIX C

RSTS/E Error Messages

APPENDIX D

ASCII Character Codes

INDEX

FIGURES

1-1
7-1

Executing a Command Procedure at Interactive Level 1-6
Command Levels in Nested Command Procedures
. . . 7-7

TABLES

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

8-2
Col
D-l

Rules for Determining Expression Types
. . . . 3-5
Summary of Operators in Expressions . . . . . . . 3-8
Summary of DCL Functions..
. . . . . . . . . 4-3
Summary of F$EDIT Functions
. ..
...
4-11
Status Word Values. . .
....
....
4-23
Flag Word Values. . . . . . . . . . . . . . . .
4-25
Summary of Privileges
. . . . . . . . .
4-30
Severity Values
. ..
. . . . . . . . . . . . 8-2
ON Command ' Keywords and Actions . . . . . . . . . 8-5
RSTS/E Error Messages
. . . . . . . . . . . . . Col
ASCII Character Codes . . . . . . . . . . . . . . D-l

Preface

Objectives
This guide presents concepts and techniques for developing command
procedures using the DIGITAL Command Language (DCL) on RSTS/E.
Various examples, including complete command procedures, demonstrate
applications of the concepts and techniques that this guide discusses.
Audience
All RSTS/E users can benefit from using command procedures. For
example, you can place frequently used command sequences into a
command procedure and thereby save keystrokes; you can also write
sophisticated command sequences that pass parameters, test status
values, process files, and perform similar program-like tasks.
Although you do not have to be a computer expert to use this guide,
you will have an easier time if you are familiar with programming
concepts such as loops, logical values, and so forth.
Document Structure
Each chapter in this guide builds on material from earlier chapters.
If command procedures are new to you, study this guide chapter by
chapter beginning with Chapter 1. If you already have some knowledge
of command procedures, you may want to skim the Table of Contents and
Index for the specific topics you need.
This manual contains nine chapters and four appendixes:
Chapter 1

Defines command procedures and describes how to
develop them.

Chapter 2

Describes how to define and manipulate symbols.

Chapter 3

Describes the use of expressions and operators.

Chapter 4

Shows how to use the DCL functions to obtain
information about the status of a process and to
manipulate character strings.

Chapter 5

Describes how to control input to and output from
command procedures.

Chapter 6

Explains how to manipulate files using command
procedures.

vii

Chapter 7

Describes how to control the sequence in which
command procedure lines are executed.

Chapter 8

Shows how to set up error handling routines based
on the severity of errors encountered during
command procedure execution and how to handle
CTRL/C interrupts that occur during command
procedure execution.

Chapter 9

Describes commands for displaying command
procedure output.

Appendix A

contains sample command procedures that illustrate
the techniques described in Chapters 1 through 9.

Appendix B

Lists some of the major differences between the
RSTS/E and VAX/VMS command processors.

Appendix C

Lists the numeric values associated with RSTS/E
error messages.

Appendix D

Lists the ASCII character codes.

Related Documents

This guide refers you to the following manuals for more detailed
information:
o

RSTS/E System User's Guide

RSTS/E System Manager's Guide.

viii

conventions

This manual uses the following symbols and conventions:
Square brackets show the optional parts of a command in
format statements. For example:
DIRECTORY [file-spec[, ... ]]
The square brackets in this example indicate that you
can include a file specification ([file-spec]), or more
than one ([, ... ]), if you choose.
Square brackets also indicate the choice you have in
using a command. For example:
/[NO]DELETE
This means you can type either /DELETE or /NODELETE,
depending on the form of the qualifier you select.
Do not confuse the square brackets in command formats
with the square brackets in Project-Programmer numbers
(PPNs), as in [52,20].
<CTRL/x>

The control key, which you use in combination with
another key. For example, enter CTRL/U by holding down
the CTRL key and pressing the keyboard key labeled "U."
RSTS/E displays, or echoes, CTRL/U at your terminal, as
AU.

<RET>

The key labeled RETURN on your terminal. You press the
RETURN key to complete lines and commands that the
system will process.

color

In examples, black characters are data produced by the
computer.
Red characters indicate information that you type.

Chapter 1
Introduction

This chapter introduces command procedures and tells you how to
develop them.

What are Command Procedures?
Command procedures are files that contain DCL commands. To execute
these commands, you run the procedure. Use command procedures to
execute sequences of commands you use during interactive terminal
sessions or to execute commands you submit for batch processing. As
you become more experienced in creating and using command procedures,
you will find many other applications for them.
Command procedures can range
procedure consists of one or
interpreter to execute. For
deletes all temporary (.TMP)

from simple to complex . A simple command
more command lines for the DCL command
example, the following command procedure
files and then shows a directory listing:
DIRECT. COM

$
Delete .TMP files and show directory
$ DELETE *.TMP
$ DIRECTORY

A more complex command procedure performs program-like functions.
can:
o

Contain loops and error checking routines

Perform arithmetic calculations and input/output (I/O)
operations

Manipulate character string data

Call or pass parameters to other command procedures

1-1

Introduction
For example, the following command procedure edits all occurrences of
files with a .B2S file type in a user's account:
B2S.COM
$
$
$
$
$
$
$
$

Edit all .B2S files
SET NODATA
NEXTFILE = F$SEARCH("SY:*.B2S")
LOOP:
IF NEXTFILE .EQS.
"" THEN EXIT
EDIT/EDT 'NEXTFILE'
NEXTFILE = F$SEARCH()
GOTO LOOP

Creating Command Procedures
To create a command procedure, use a text editor such as EDT or the
DCL CREATE command.
The following example shows how to create a
simple command procedure using EDT:
$ EDIT/EDT RUN.COM <RET>
Input file does not exist
[EOB]
*C <RET>
$ !Run three programs <RET>
$ RUN PROGI <RET>
$ RUN PROG2 <RET>
$ RUN PROG3 <RET>
<CTRL/Z>
*EXIT
RUN
.COM 3 lines
$
The next example shows how to create the same procedure using the DCL
CREATE command:
$ CREATE RUN.COM <RET>
$ !Run three programs <RET>
$ RUN PROGI <RET>
$ RUN PROG2 <RET>
$ RUN PROG3 <RET>
<CTRL/Z>
$
Note that the examples use the file type .COM. When you execute a
command procedure, DCL uses this file type as the default.

1-2

Introduction
Formatting Command Procedures
Follow these format conventions and restrictions when you create a
command procedure:
o

Begin each DCL command line with a dollar sign ($) character
in the first space of the line -- Using this character
ensures that DCL processes the command when you execute the
procedure from another keyboard monitor such as BASIC-PLUS.

Begin each line containing a DCL label with a $ character in
the first space of the line -- Put labels on separate lines
to help make loops and conditional coding easier to
understand.

Do NOT begin the following types of lines with the $
character:
Data lines
Command lines to keyboard monitors other than DCL
DCL continuation lines

Separate command sequences -- Insert lines containing only a
$ character before and after a logical sequence of commands.
This convention makes it easier to see the structure of the
command procedure.

Avoid abbreviating DCL keywords to less than 4 characters -DCL conventions ensure that all qualifiers and keywords are
unique in the first 4 characters.

Use comments -- Comments explain the procedure to anyone who
must maintain it; DCL ignores them during execution. You
begin comments with an exclamation point and place the
comment to the right of the exclamation point. You can place
a comment on a separate command line or at the end of a
command line. If a comment exceeds one line, place an
exclamation point at the start of each line.
Use comments at the beginning of a procedure to describe the
procedure and the parameters you pass to it or use them at
the beginning of each block of commands to describe that
section of the procedure. However, note that excessive use
of comments can decrease performance.

1-3

Introduction
Executing Command Procedures
You can execute command procedures in many different ways on RSTSjE
systems:
o

At login time, RSTS automatically executes the system-wide
LOGIN.COM file and any private LOGIN.COM file

At interactive level, using the at sign (@) command, or from
any other keyboard monitor using the $@ combination

In batch mode, using the SUBMIT command

From inside another command procedure (nesting)

with the RUN command from any keyboard monitor, provided the
command file is executable and includes the DCL run-time
system attribute

with the CHAIN statement from another program, provided the
command file is executable and includes the DCL run-time
system attribute

with a Concise Command Language (CCL) command from any
keyboard monitor, provided the command file is executable and
includes the DCL run-time system attribute

At system start-up time or after a system crash

Note that you can execute a command file that is resident on disk
only.
However, DCL copies a command file from magnetic tape (DOS
format only) to a temporary disk file before executing it.
For
example:
$ @MT1:MYFILE.COM
DCL temporarily copies the command file from magnetic tape to a
temporary disk file, and then executes it.
The following sections describe the methods for executing command
procedures.

Executing Command Procedures at Login
when you log in, RSTSjE executes the system-wide command file
LOGIN.COM, which is located in directory [0,1] on the public
structure.
This file contains commands defined by the system manager
that are executed for all users.
In addition, the system-wide
LOGIN.COM file normally contains a command that invokes a private
LOGIN. COM file located in your account on the public structure.
This
1-4

Introduction
feature lets you tailor the system for your everyday use.
For example, if you enter the same sequence of commands every time you
log in, place these commands in a command procedure named LOGIN.COM.
A typical LOGIN. COM file might contain the following:
$ TYPE $NEWS.TXT
$ RUN DBl:[2,214]COOKIE.EXE
$ US-ERS:== "SHOW USERS"
$ ASSIGN DR3:[2,214] WORK:
$ DIR-ECTORY :== DIRECTORY/DATE

!Display system messages
!Run a program
!Abbreviate a command
!Assign a logical name
!Redefine DIRECTORY command

Note that if a symbol has one or more abbreviations, DCL displays it
with an embedded hyphen indicating the minimum abbreviation point.
If your system manager allows the use of private LOGIN.COM files, the
system automatically executes these commands every time you log in.

Executing Command Procedures at Interactive Level
The @ command executes a command procedure at interactive level.
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Format
@file-spec [PI [P2 [ ... pa]]]
Prompts
Command file: file-spec
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
Command Parameters
file-spec
The file specification of the command file to execute.
not specify a file type, the system uses .COM.
[PI [P2 [...

If you do

pa] ] ]

Optional parameters (one to eight) to pass to the command
procedure.
Separate each parameter with one or more spaces or
tabs.
See Chapter 5 for a complete description of passing
parameters.

1-5

Introduction
For example, to execute the command procedure FILST.COM in your
account on the system disk, enter this command:
$ @FILST
Figure 1-1 shows how the command procedure is executed at interactive
level.
+ - - - - - - - - - - - - - - - - - - - - - - - - - - -+

ICommand interpreter finds
- - - - - - - - ~ FILST. COM in your account

$ @FILST

+ - - - - - - - - - - - - - - - - - - - - - - - - - --+
$

I
I
I
I
I
I
I
I

+ - - - - - - - - - - - - - - - - - - - - - - - - - --+

Ithen executes the FILST.COMI
Icommands sequentially...
I
+- - - - - - - - - - - - - - - - - - - - - - - - - --+
I
I

+- - - - - - - - - - - - - - - - - - - - - - - - - --+

l and returns control to
-------------------- I interactive level after
IFILST.COM completes
+- - - - - - - - - - - - - - - - - - - - - - - - - - -+

Figure I-I:

Executing a Command Procedure at Interactive Level

When you enter the @ command, the command interpreter executes the
file FILST.COM located in your account on the system disk. Each
command string in FILST.COM executes sequentially. After reaching the
end-of-file (EOF) for FILST.COM or after executing an EXIT or STOP
command, the command interpreter returns control to interactive level
and displays the $ prompt at your terminal. You can then resume
interactive work.
Note
You can also use the @ command from other keyboard
monitors. However, you must precede it with the $
character. For example:
Ready
$@FILST

1-6

Introduction
When you enter the @ command at the DCL prompt, the DCL command
interpreter assumes that the the name of a file (with the file type
.COM) follows it.
If you enter the @ command without specifying a
file, DCL prompts you for the file specification.
If a command procedure is not in your account on the system disk or
does not have the file type .COM, give the complete file
specification.
For example:
$ @DB2:RESET.FIL

This command executes a command procedure located on DB2: .
command procedure file name is RESET.FIL.

The

If you execute command procedures frequently, you can define a symbol
name that you can use in place of the entire command line.
For
example:
$ RESET :== @DB2:RESET.FIL

This assignment statement defines the symbol name RESET to be
equivalent to the string "@DB2:RESET.FIL." You can then use this
symbol as a command name during the current terminal session.
If you want to use a symbol every time you log in, include the symbol
definition in your login command file.
See Chapter 2 for more
information about using symbols.

Executing Command Procedures in Batch Mode
To execute a command procedure in batch mode, use the SUBMIT command
followed by the file specification of the procedure.
The file type
defaults to .COM. When you use this method, the batch processor
executes the command procedure while you continue to work at your
terminal.
You should submit procedures that require lengthy
processing time for batch processing.
For example, to execute the command procedure COPY.COM in batch mode,
enter the command:
$ SUBMIT COPY

In this example, the command interpreter finds the file COPY.COM in
your account and submits it to the default batch queue for processing.
After the batch job is queued, your terminal is free for you to
continue interactive work.
See the RSTS/E System User's Guide and RSTS/E System Manager's Guide
for more information on batch processing.

1-7

Introduction
Executing Nested Command Procedures
Executing one command procedure from inside another is called nesting.
To execute one command procedure from inside another, use the @
command followed by the name of the nested procedure.
This process is
similar to using a CALL statement in a high-level language.
When the DCL command interpreter finds a nested command procedure, it
reads input from the second procedure until it reaches the end of the
file or until the procedure exits.
Control then returns to the first
command procedure at the line following the @ command.
Note that you can nest a maximum of 13 command procedures on RSTSjE.
See Chapter 7 for more information about nesting command procedures.

Executing Command Procedures with the RUN Command
You can use the RUN command from any keyboard monitor to execute
command procedures as you would a program on RSTSjE. A command file
that you execute with the RUN command must follow these rules:
o

The file must be on disk

You must set the execute bit (64) in the file's protection
code

The file must have DCL as its run-time system

Note that you cannot pass any parameters to command files that you
execute with RUN.
See Chapter 5 for a complete discussion of
parameter passing.

Chaining to Command Procedures from a Program
You can also execute a command procedure using the CHAIN statement or
the .RUN directive.
Command files you chain to must follow the same
rules as command ~iles you execute using the RUN command.
To pass parameters when you chain to a command procedure, you must
specify a nonzero parameter word and load core common with one or more
parameter values separated by spaces or tabs.
See Chapter 5 for more
information about passing parameters.

1-8

Introduction
Executing Command Procedures with eCLs
The Concise Command Language (CCL) lets you execute command procedures
that are defined as CCLs by your system manager.
When you execute a command procedure with a CCL command, you must
follow the same rules as command files you chain to; that is, to pass
parameters you must specify a nonzero parameter word and load core
common with one or more parameter values separated by spaces or tabs.
For complete information about parameter passing, see Chapter 5.
See the RSTSjE System Managers Guide for more information about
defining or using CCLs.

Command Procedures and System Management
The RSTSjE system manager can create a system-wide LOGIN.COM file
containing commands that are executed for all users.
If you are a
system manager, you also use command files in these ways:
o

When you start timesharing, the system automatically loads
DCL and executes the file [O,I]SYSINI.COM.
SYSINI.COM
performs preliminary startup procedures and then executes
[O,I]START.COM, passing it the parameter "START" in Pl.

When the system restarts after a system crash or power
failure, it automatically loads DCL and executes the file
[O,I]SYSINI.COM.
SYSINI.COM then executes [O,I]START.COM,
passing it the parameter "CRASH" in Pl.

See the RSTSjE System Manager's Guide for complete information about
using command files in system management.

1-9

Chapter 2
Using Symbols in Command Proriedures

This chapter tells you how to define and use symbols in command
procedures.
It describes:
o

The syntax of symbol names

How to define symbol values

How the command interpreter substitutes values for symbols
during command processing

Symbols in DCL
A symbol is a name that represents a number, character, or logical
value.
You define a symbol in an assignment statement.
You use
symbols in command procedures as constants or variables, and
manipulate them in much the same way as you manipulate variables in a
programming language.
This capability, combined with the ability to
control execution flow in command procedures, makes the DCL command
language very much like a programming language.
The following example shows how you can define a symbol to represent a
string:
$ FILE

"SOURCE.CBL"

This assignment statement gives the symbol name FILE the string value
"SOURCE.CBL".
You can then refer to the file SOURCE.CBL symbolically
by using the symbol name FILE.
For example:
$ COBOL 'FILE'

2-1

Using Symbols in Command Procedures
The apostrophes around the symbol name FILE tell the command
interpreter that the enclosed word is a symbol name.
The command
interpreter substitutes the string value "SOURCE.CBL" for FILE before
executing the COBOL command.

Symbol Names
A symbol name is a string from 1 to 255 characters long that can
consist of:
o

Uppercase letters A-Z

Lowercase letters a-z

Numbers 0-9

Dollar signs ($)

Underscores (

Note that the command interpreter always converts lowercase letters in
symbol names to uppercase.
Also note the following restrictions for symbol names:
o

You cannot begin a symbol name with a numeric character, an
underscore, or the characters F$ (reserved for DCL function
names).

Symbols that begin with the $ character are reserved symbols.
You cannot create or assign new values to reserved symbols.
You can, however, use a $ character anywhere else within a
symbol name.

In a symbol name, the underscore (_) character is interpreted
in the same way as any other character.
This differs from
its use with DCL qualifiers, where the underscore is
transparent.
For example, the symbol names MYFILE and
MY_FILE are different symbols.

You cannot begin a symbol name with a hyphen (-) character or
an asterisk (*) character.

When you create symbol names, you can use the hyphen (-) character or
the asterisk (*) character to specify an abbreviation point for the
symbol.
Specifying an abbreviation point lets you reference the
symbol name by anyone of its abbreviations in any DCL command that
allows symbol names.
This feature also lets you create command
synonyms that act like DCL commands.
For example, in DCL you can
specify the PRINT command as PR, PRI, PRIN, or PRINT.
Likewise, you
2-2

Using Symbols in Command Procedures
can create the symbol:
"SHOW USERS"

$ US-ERS

You can then refer to the symbol USERS as US, USE, USER, or USERS (in
command synonym substitution only).
Note that DCL displays an error message if you:
o

Use more than one hyphen or asterisk in a symbol name.

Create a symbol name with an abbreviation that matches any
existing abbreviation of another symbol.
For example:
$ PR-INT = "PRINT/COPIES=2"
$ PR-OTECT = "SET PROTECTION=60"

In this example, DCL displays an error message when you make
the second assignment, because the abbreviations match.

Symbol Values
You can assign values to symbols using any of the following methods:
o

Assigning symbol names to expressions, constant values, DCL
functions, or to other variable symbol names with assignment
statements.

Passing up to eight parameters to a command procedure when
you invoke it, or to a batch job when you submit it to a
batch queue.
(Chapter 5 discusses parameter passing.)

Using the INQUIRE command to prompt for a symbol's value.
(Chapter 5 describes the INQUIRE command.)

Using the READ command to read a record from a file and
assign it as a string value to a specified symbol.
(Chapter
6 describes the READ command.)
Note
RSTS/E restricts the space available for storing
symbols. Whenever insufficient space (less than 100
bytes) remains to define a symbol and its value, an
error message appears.
Therefore, you should delete
symbols you no longer need and avoid excessively long
symbol names.
2-3

Using Symbols in Command Procedures
Symbol Types
A symbol type can be either string or integer, depending on the value
or expression you assign. When you use an expression, DCL evaluates
it to determine the value to assign to the symbol.
If the expression
evaluates to a string, DCL assigns a string value to the symbol.
If
the expression evaluates to an integer, DCL assigns an integer value
to the symbol.
DCL determines the type of expression by the types of values you use
in the expression and by the type of operations you use to manipulate
these values.
Chapter 3 describes the rules that DCL uses to
determine an expression's type.
The following sections describe how you assign values to symbols.

Symbol Assignment
Use an assignment statement to define a symbol and assign it a string
or integer value.
The format of an assignment statement is:
symbol-name =[=] expression
where:
symbol-name

is a name from 1 to 255 characters long that contains
the characters listed in the "Symbol Names" section at
the beginning of this chapter.

assigns the value you specify and places the symbol
name and value in the local symbol table.
assigns the value you specify and places the symbol
name and value in the global symbol table.

expression

is an integer or string expression.
The expression's
value is assigned to the symbol name.

If the symbol name does not exist when you enter the assignment
statement, then DCL creates the symbol and assigns its value.
If the
symbol name already exists, then DCL assigns the new value, replacing
the previous value.
For example:
$ COUNT

This assignment statement assigns the value 0 to the local symbol
COUNT.

2-4

Using Symbols in Comma n d Pro c edures
Use double equal signs (==) to assign a symbol to the global symbol
table.
For example:

$ NEWCOUNT == 10
This assignment statement assigns the value 10 to the global symbol
NEWCOUNT.
You must enclose string literals in quotation marks (").

For example:

$ TERM == "SET TERMINAL"
This assignment statement assigns the string value "SET TERMINAL" to
the global symbol TERM.
If DCL finds unmatched quotation marks in a
command string that you assign to a symbol, it displays an error
message.
If you specify an expression that contains other symbols , DCL u s es the
value of those symbols when evaluating the expression.
For example :
$ TOTAL = NEWCOUNT + 10
$ SHOW SYMBOL TOTAL
TOTAL = 20
In this example, you use an arithmetic assignment statement to assign
a value to the symbol TOTAL.
Note that DCL automatically substitutes
the value 10 for the symbol NEWCOUNT before evaluating the expression .
See the section "Symbol Substitution" for further discussion.

string Assignment
To assign a string to a symbol, you can use a special string
assignment statement.
The format of a string assignment statement is :
symbol-name :=[=] string
where:
symbol-name

is a name from 1 to 255 characters long that contains
the characters listed in the "Symbol Names" section at
the beginning of this chapter .

assigns the string value you specify and places the
symbol name and value in the local symbol table .

2-5

Using Symbols in Command Procedures

:==

assigns the string value you specify and places the
symbol name and value in the global symbol table.

string

specifies the string value to assign to the symbol.
The string can be from 0 to 255 characters long.

If the symbol name does not exist when you enter the assignment
statement, then DCL creates the symbol name and assigns its string
value.
If the symbol name already exists, then DCL assigns the new
string value, replacing the previous value.
When you use the special string assignment statement, you do not have
to enclose the string in quotation marks.
For example:
$ TEMP_STRING :== error

number

This assignment statement assigns the string "ERROR NUMBER 11" to the
global symbol TEMP STRING .
Note that DCL performs the following actions when you use the special
string assignment statement to assign a string not enclosed in
quotation marks:
o

Converts lowercase characters to uppercase

Removes leading and trailing spaces or tabs

Reduces multiple spaces or tabs between characters to a
single space

When you enclose the string in quotation marks, DCL does not perform
case conversion and keeps all spaces and tabs.
For example:
$ TEMP_STRING :== "error

number

11"

This assignment statement assigns the string "error
the global symbol TEMP STRING.

number

11" to

Symbol Tables
The DCL command interpreter stores symbol names and their associated
values in two types of symbol tables:
o

A local symbol table, which contains symbols you can use at
the current command level

A global symbol table, which contains symbols you can use at
all command levels

2-6

Using Symbols in Command Procedures
DeL has a separate local symbol table for each command level except
the interactive level. A command level is the DeL environment from
which you issue commands. When you nest a command procedure, you
increase the command level by one.
For example, when you log in and type commands at your terminal, you
are issuing commands from command level 0 (the interactive level).
If
you execute a command procedure, the commands in the procedure are
executed at command level 1. When the procedure terminates and the
DeL prompt reappears on your screen, you are back at command level O.
To create a local symbol, use a single equal sign (=) in the
assignment statement.
For example:

$ TEMP = 1
When a nested command procedure ends, DeL deletes the local symbol
table current to that command level and makes current the next higher
level local symbol table.
Because each local symbol table is unique,
the same symbol can exist in more than one local symbol table.
This
feature lets each command file use symbols that are separately
defined, thus avoiding conflicts with the use of those symbols
elsewhere.
For example, you can define the local symbol FILE at
several command levels, to have different values at each command
level. When the symbol value is needed, DeL first searches the local
symbol table at the current command level:
if no symbol is found, it
then searches the global symbol table.
Note that no local symbol table exists at the interactive command
level.
DeL places any symbol that you define at the interactive level
in the global symbol table, whether you use a single or double equal
sign (==) in the assignment statement.
DeL maintains only one global symbol table, which is recognized at
every command level including the interactive level.
To create a
global symbol, use a double equal sign in the assignment statement.
For example:

$ VAL == 45
The following sections describe how DeL performs symbol substitution.

2-7

Using Symbols in Command Procedures
Symbol Substitution
DCL performs symbol substitution by replacing symbol names in the
command string with their current values.
To use symbols in commands
and command procedures, you must understand the following mechanics of
symbol substitution:
o

Command synonym substitution

Apostrophe substitution operators

Automatic evaluation

Undefined symbols

Verification of symbol substitution

Command Synonyms
You frequently use global symbols to define command synonyms.
Normally, you place command synonyms in your LOGIN.COM file to make
the synonyms available each time you log in.
For example:

$ KB == "SET TERMINAL/DEVICE="
This assignment defines KB as a new DCL command.

You can now type:

$ KB VT125

DCL executes the command as if you typed:

$ SET TERMINAL/DEVICE= VT125
Note that the DCL command interpreter processes a command string by
examining the first command keyword to determine if it is a defined
symbol.
If it is a defined symbol, DCL automatically substitutes the
value of the symbol for the symbol name before executing the command
string.
You can also use command synonyms to redefine existing DCL commands,
which lets you change a default qualifier or parameter.
For example:

$ PRINT == "PRINT/COPIES=2"
When you later issue the PRINT command, DCL automatically prints two
copies of the file you specify.
You can override automatic command substitution by placing an
underscore
before the first character in the command keyword.
2-8

Using Symbols in Command Procedures
Then, even if the keyword is a defined symbol, no automatic
substitution occurs. For example:
$

PRINT MY.FIL

This command prints one copy of the file MY.FIL, because the preceding
underscore tells DCL not to perform automatic substitution.
Note that you can use symbol name abbreviations in command synonym
substitution only.

Apostrophes in Symbol Substitution
If you use a symbol name in place of a command parameter or qualifier,
you must enclose it in apostrophes (' ... '). When DeL finds a symbol
name enclosed in apostrophes, it replaces 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 tell DeL that FILENAME is a symbol name and not a literal
string.
If you want to include a symbol name within a literal string, place
two apostrophes before the symbol name and one apostrophe after it.
For example:
$ TEXT

"File "FILENAME' deleted"

If the current value of the symbol FILENAME is MYFILE.DAT, then the
symbol TEXT is given the string value:
File MYFILE.DAT deleted
Note that when you use apostrophes to request symbol substitution, DeL
performs iterative substitution from left to right in the command
string. This means that for each symbol name found in the command
line, the string resulting from the substitution is scanned again from
the beginning 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.
For example:
$ FILE := "'A'"
$ A := FILEl.MEM
$ TYPE 'FILE'
2-9

Using Symbols in Command Procedures
DCL processes this example as follows:
1.

DCL assigns the symbol name FILE to the string value 'A'.
The quotation marks prevent DCL from substituting a value for
'A' (which you have not yet defined).

DCL assigns the string value FILEl.MEM to the symbol name A.

DCL substitutes the current value of 'FILE', when it scans
the TYPE command string, resulting in:
TYPE 'A'

Because the current value contains apostrophes, DCL scans the
line again and substitutes the value of 'A'.
Finally, DCL
executes the command string:
TYPE FILEl.MEM

When scanning a command string for apostrophe substitution, DCL
performs a maximum of 100 iterations.
If the command string still
contains apostrophes after 100 iterations, DCL displays an error
message and does not process the command.
DCL performs apostrophe substitution both before and after the command
substitution occurs.
For example:

$ EXEC := "'COMMAND'"
$ COMMAND := "DIRECTORY [1,2)"
$ QUAL .- "/DATE"
$ EXEC 'QUAL'
In this example, when DCL processes the command string EXEC 'QUAL,' it
first performs apostrophe substitution on 'QUAL,' resulting in
EXEC /DATE.
Then command substitution occurs, resulting in
'COMMAND' /DATE.
Finally, DCL performs apostrophe substitution again,
resulting in DIRECTORY [1,2) /DATE.

Automatic Evaluation
When DCL evaluates an expression, it assumes that a keyword beginning
with an alphabetic character is a symbol name.
In this case,
evaluation is automatic and apostrophes are not needed.
In fact, if
you use apostrophes, the results may be quite different because
iterative substitution occurs.

2-10

Using Symbols in Command Procedures
For example, when you use an arithmetic assignment statement, DCL
automatically evaluates the expression on the right hand side of the
statement:
$ TOTAL = COUNT + 1
Note that you do not need apostrophes to request substitution for the
symbol COUNT because DCL automatically substitutes values for symbols
as it executes arithmetic assignments.
Similarly, no apostrophes are necessary in the following IF command:
$ IF A .EQ. B THEN GOTO NEXT
In this example, the IF command assumes that both A and B are symbol
names and uses their current values to test their equality.

undefined Symbols
If a symbol is not defined when you use it in a command string, then
DCL displays an error message and sets the reserved symbols $SEVERITY
and $STATUS to the exit status ERROR.
In addition, DCL does not
process the command that contains the undefined symbol.
See Chapter 8
for more information about $SEVERITY and $STATUS.

Verifying Symbol Substitution
The SET VERIFY and SET NOVERIFY commands control whether DCL displays
lines in a command procedure as it executes them.
Use the SET VERIFY
command when you want to determine the cause of errors that occur
within a command procedure. When verification is in effect, DCL
displays each command line exactly as it appears in the command file,
before any substitution.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Format
SET [NO]VERIFY
Command Qualifiers

Defaults

/NODEBUG
/[NO]DEBUG
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

2-11

Using Symbols in Command Procedures
Command Qualifiers
/[NO]DEBUG
Specifies whether DCL enables command debugging. You can use
this qualifier only with SET VERIFY. When enabled, DCL displays
each command line twice:
once as it appears in the command file,
and again as it appears after apostrophe and command
substitution.
The default is /NODEBUG.
SET NOVERIFY is the default setting. When you use this setting, DCL
does not display command lines read from a command file.
However, DCL
always displays any error messages that occur.
When SET VERIFY is in effect, it is global to all command procedures
and remains in effect until you change it with SET NOVERIFY~ Note
that you can also use the DCL function F$VERIFY to change the current
verification setting.
See Chapter 4 for more information about
F$VERIFY.

Displaying Symbols
The SHOW SYMBOL command lets you display the value of a specified
symbol or of all symbols in a local symbol table, the global symbol
table, or both.
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Format

SHOW SYMBOL [symbol-name]
Command Qualifiers

Defaults

/ALL
/GLOBAL
/LOCAL

/ALL

+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Command Parameters
symbol-name
The name of the symbol to display. DCL returns an error if the
symbol is not found.
If you do not specify a symbol name, /ALL
is assumed.
If you specify both a symbol name and the /ALL
qualifier, the symbol name takes precedence.

2-12

Using Symbols in Command Procedures
Command Qualifiers
/ALL
Tells DCL to display all symbols in the specified symbol table.
It is the default.
/GLOBAL
Tells DCL to display only global symbols.
/LOCAL
Tells DCL to display only local symbols.
within a command file, you can use the /LOCAL or /GLOBAL qualifiers
with a symbol-name to restrict searching to either the local or global
symbol table.
If you do not specify the /LOCAL or /GLOBAL qualifier,
DCL searches both tables.
If DCL finds a symbol name in both tables,
it displays the local symbol definition before the global symbol
definition.
Global symbols are always displayed with a double equal
sign (==), while local symbols are displayed with a single equal sign
( =) .
When you are at the interactive command level, you can only display
global symbols because no local symbol table exists at this level .
DCL displays an error message if you use the /LOCAL qualifier at this
level.
If you want to display a symbol that has an abbreviation point, do not
specify the hyphen character along with the symbol name.
For example:
$ SHOW SYMBOL USERS
US-ERS = "SHOW USERS"

Note that if a symbol has one or more abbreviations, DCL displays it
with an emb~dded hyphen indicating the minimum abbreviation point.
Other examples of the SHOW SYMBOL command follow:
$ SHOW SYMBOL/LOCAL

This command displays all symbols in the local symbol table.
$ SHOW SYMBOL COUNT
COUNT = 4

This command displays the local symbol COUNT.
Because the value 4 is
not in quotation marks, the symbol has a numeric value.
2-13

Using Symbols in Command Procedures
$ SHOW SYMBOL PRINT
PRINT == "PRINT/NOFEED"

This command displays the global symbol PRINT. Because the value
"PRINT/NOFEED" is in quotation marks, the symbol has a string value.

Deleting Symbols
Use the DELETE/SYMBOL command to delete 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.
+ - - - - - -" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Format

DELETE/SYMBOL [symbol-name]
Command Qualifiers

Defaults

/ALL
/GLOBAL
/LOCAL
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Command Parameters
symbol-name
The name of the symbol to delete.
DCL returns an error if the
symbol is not found.
If you specify both a symbol name and the
/ALL qualifier, the symbol name takes precedence.
Command Qualifiers
/ALL
Tells DCL to delete all symbols in the specified symbol table.
/GLOBAL
Tells DCL to delete the global symbol you specify.
By default,
DCL searches the global symbol table when you attempt to delete a
symbol at the interactive level.

2-14

Using Symbols in Command Procedures
/LOCAL
Tells DCL to delete the local symbol you specify.
By default,
DCL searches the local symbol table when you attempt to delete a
symbol a~ command levels other than the interactive level.
Note that DCL automatically deletes the symbols in a local symbol
table whenever the command procedure at that level exits.
In
addition, DCL deletes symbols in the global symbol whenever you log
out.
Remember that because RSTS/E restricts the space available for storing
local and global symbols, you should always delete symbols that you no
longer need.
Examples of the DELETE/SYMBOL command follow:
$ DELETE/SYMBOL/ALL/GLOBAL

This command deletes all user-defined global symbols.
$ DELETE/SYMBOL/LOCAL COUNT

This command deletes the local symbol COUNT.

2-15

Chapter 3
Expressions and Operators

This chapter describes the types of values and operators you can use
in expressions. Chapter 2 described how you can equate a symbol to
either a string or an integer expression. The value that DCL assigns
to the symbol is the result of the expression. For example:
$ C = 4 + F$INTEGER("6") - A
This command assigns a symbol (C) to an expression containing an
integer (4), a DCL function (F$INTEGER("6")), and a symbol (A). The
value that DCL assigns to the symbol C is the result of the operations
in the expression. In this example, the expression evaluates to an
integer value.
DCL also lets you use expressions:
o

As DCL function arguments (see Chapter 4)

With OPEN, CLOSE, READ, and WRITE commands (see Chapter 6)

with IF commands (see Chapter 7)

Operands in Expressions
Expressions can contain strings, integers, DCL functions, symbols, or
combinations of these values. Expressions consist of operands and
operators. Operands are the values on which to perform an operation.
Operators specify the operation for DCL to perform in evaluating the
expression.

3-1

Expressions and Operators
strings
A string can contain any printable characters. When you use strings
in expressions, you must enclose them in quotation marks. To include
quotation marks in a string, type two consecutive sets of quotation
marks. For example:
$ PROMPT = "Type ""YES"" or ""NO"""
$ SHOW SYMBOL PROMPT
.

PROMPT == "Type "YES" or "NO""
When you make the symbol assignment, you must use two sets of
quotation marks around the words YES and NO. Also, you must enclose
the entire string in quotes because the string is used in an
expression. Note that DCL preserves uppercase and lowercase, spaces,
and tabs when you make the symbol assignment in this way. In
addition, DCL places the symbol in the global symbol table because you
defined it at the interactive command level.
You can continue a string over two lines by using a plus sign (+) for
string concatenation, and a hyphen (-), for continuation. For
example:
$ MONTHLY = "MONTHLY REPORT
Continue: "JUNE 1985"

"+-

$ SHOW SYMBOL MONTHLY
MONTHLY == "MONTHLY REPORT -- JUNE 1985"

You can also concatenate several symbols to create a long string.
example:

For

$ FIRST = "If at first you don't succeed,"
$ SECOND = " try, try again."
$ THIRD = FIRST + SECOND
$ SHOW SYMBOL THIRD
THIRD == "If at first you don't succeed, try, try again."

Note that both operands must be strings for string concatenation to
occur. If either operand to the plus sign (+) operator is an integer,
then DCL performs addition, not concatenation.

3-2

Expressions and Operators
Integers
The DCL command interpreter treats all numeric values as decimal
integers.
The following examples show how to use integers in
expressions:
$ COUNT

= 4 + 1

$ DATA = COUNT + 1
$ SHOW SYMBOL COUNT
COUN.T == 5
$ SHOW SYMBOL DATA
DATA == 6
In this example, you define two symbols using integer expressions and
use the SHOW SYMBOL command to display the value of the symbols.
Note that you do not use quotation marks with integers.

DCL Functions
DCL functions let you obtain information about a requested item.
You
invoke a DCL function by typing its name, which always begins with the
characters F$, and its argument list:
F$function-name(argument[, ... ])
You must enclose the argument list in parentheses. Use DCL functions
in expressions in the same way you use strings, integers, and symbols.
The following example uses the F$LENGTH function in an expression .
(The F$LENGTH function returns an integer that specifies the length of
a string.) DCL assigns the returned value to the symbol LEN.
For
example:
$ LEN

F$LENGTH ("Roses are red and violets are blue.")

$ SHOW SYMBOL LEN
LEN == 35
Note that you do not enclose DCL functions in quotation marks.
In
addition, you must specify the arguments for DCL functions as
expressions.
Therefore, if an argument contains a string, you must
enclose the string in quotation marks.
If an argument contains an
integer, a symbol, or another DCL function, do not enclose these
values in quotation marks.
In the previous example, the F$LENGTH
function is not enclosed in quotation marks; however, the argument (a
string) is.

3-3

Expressions and Operators
The value and data type returned by a DCL function depend on the
function.
See Chapter 4 for complete descriptions of each DCL
function.

Symbols
When you use a symbol in an expression, DCL automatically substitutes
the symbol's value. For example:
$ COUNT = 3
$ NEWCOUNT = COUNT + 1
$ SHOW SYMBOL NEWCOUNT
NEWCOUNT == 4
See Chapter 2 for more information about symbol substitution.
The following sections describe the conversion of value types in
expressions; that is, how strings are converted to integers, and how
integers are converted to strings.

Value Type Conversion in Expressions
Expressions can contain both integer and string values as operands,
which are the values on which to perform an operation. DCL
automatically converts such expressions to either a string or integer
type, depending on the types of values used in the expression and on
the types of operations used to manipulate those values.
You can use the F$TYPE function to determine an expression's type.
You can also perform value conversion explicitly using the F$INTEGER
and F$STRING DCL functions. See Chapter 4 for more information on
these functions.
Table 3-1 lists the rules that DCL uses to determine an expression's
type.

3-4

Expressions and Operators
Table 3-1:

Rules for Determining Expression Types

+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - --+

Expression

Type

+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - --+

Integer value

Integer

String value

String

Integer DeL function

Integer

String DeL function

String

Integer symbol

Integer

String symbol

String

-, or .NOT. Any value

Integer

Any value .AND. or .OR. Any value

Integer

Any value +, -,

or / Any value

String + String

String

Any value (string comparison) Any value

Integer

Any value (integer comparison) Any value

Integer

+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - --+

Note that DeL automatically converts the expression to either a string
or integer type before performing further operations.

3-5

Expressions and Operators
Converting Strings to Integers
DCL converts numeric strings, which consist of the numbers 0 through
9, optionally preceded by one or more plus (+) or minus (-)
characters, to their signed 32-bit values.
DCL converts alphabetic strings according to these rules:
o

Strings that begin with the letter T, t, or Y, y, are
converted to the value 1 (true).

All other strings are converted to the value 0 (false).

For example:
String

--~

Integer

"4789"

--~

4789

" -1"

--~

-1

"yes"

--~

1 (true)

"FILE"

--~

0 (false)

Converting Integers to Strings
DCL converts integers to strings by generating a string consisting of
the decimal numbers of the integer. If the integer is negative, then
the minus sign (-) character precedes the numeric characters. Note
that DeL suppresses leading zeros. For example:
Integer

--~

String

1000

- --~

"1000"

-47

"-47"

- --~

"0"

007

"7"

--~

3-6

Expressions and Operators
Operators in Expressions
Use the operators shown in Table 3-2 to form an expression and define
the order of evaluation priority.
Logical and comparison operators
must be preceded by a period (.) with no intervening blanks. You must
terminate an operator with a period.
You can type any number of
blanks or tabs between operators and operands.
For example, the
following expressions are equivalent:

X.EQS.Y
X .EQS.

When you specify more than one operation in an expression, DeL
performs the operations in the order of priority listed in Table 3-2,
where 1 is the highest priority (performed first) and 6 is the lowest
(performed last).
(For example, multiplication is performed before
addition.) You can use parentheses to override the order in which
operators are evaluated, because expressions within parentheses are
evaluated first.
Table 3-2 lists the valid operators in expressions. Operators of the
same priority are performed from left to right, as they appear in the
command.

3-7

Expressions and Operators
Table 3·2:

Summary of Operators in Expressions

+. - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - _. - - - --+
I Type
I Operator I Priority
Operation
+- - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Arithmetic unary plus
Arithmetic unary minus
Arithmetic product
*
Arithmetic division
/
Arithmetic sum
3
+
Arithmetic difference
3
+- - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Arithmetic
Operators

I
I String
I Operator

I
I
I

I
I
2
2

I
I String concatenation
I

I
I
I

+- - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Logical
Operators

.NOT.
I
I Logical Complement
.AND.
I Logical AND
5
.OR.
I Logical OR
6
+- - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Arithmetic equal to
Arithmetic greater than or
equal to
Arithmetic greater than
.GT.
4
Arithmetic less than or equal
.LE.
4
to
Arithmetic less than
.LT.
4
Arithmetic not equal to
.NE.
4
+- - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Arithmetic
Comparison
Operators

.EQ.
.GE.

I
I
I String
I
.EQS.
I Comparison I
.GES.
I Operators I
I
I
.GTS.
I . LES.
I
I
I
.LTS.
I
I
.NES.

4
4

I
I String equal to
I String greater than or equal
I to
I String greater than
I String less than or equal to
I String less than
I String not equal to

4
4

I
I
I
I
I
I
I
I

4
4
4
4
+- - - - - - - - - - - -+- - - - - - -. - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

3-8

Expressions and Operators
Arithmetic Operations
Use arithmetic operations to perform calculations on integer
expressions.
The result of an arithmetic operation is an integer.
Operands in arithmetic operations are integer expressions.
If you
specify a string value as an operand, DCL converts it to an integer
value before performing the operation.
Note that DCL uses the plus sign (+) character for both the arithmetic
sum operator and the string concatenation operator. DCL performs
addition whenever one or both of the operands is an integer. However,
if both operands are strings, then DCL performs string concatenation.
Examples of arithmetic operations follow:
Expression
A

S + 10 /

Value of Symbol
A = 10

B = S

* 3 - 4 * 6 /

* (6 - 4) - 8 /

2
( 2 -1 )

Logical Operations
Use logical operators to perform logical functions on integer values.
The result of a logical operation is an integer.
Operands for logical operations are integer expressions.
If you
specify a string value as an operand, DCL converts it to an integer
value before performing the operation.
Examples of logical operations follow:
Expression

Value of Symbol

A = 3 .OR. S

A = 7

B =

3 .AND. S

B = 1

C = .NOT.3

C = -4

D = 3 + 4 .AND. 2 + 4

D = 6

3-9

Expressions and Operators
Arithmetic Comparisons
Use arithmetic comparison operators to compare integer values. If the
result of an arithmetic comparison is true, the expression has the
value 1. If the result of the comparison is false, the expression has
the value O.
If you specify a string value as an operand, DCL converts it to an
integer before performing the comparison. If a string begins with an
uppercase or lowercase T or Y, DCL converts it to the integer 1. If
the string begins with any other letter, DCL converts it to the
integer O.
Examples of arithmetic comparisons follow:
Expression

Value of Expression

1 .LE. 2

1 (true)

1 .GT. 2

0 (false)

1 + 3 .EQ. 2 + 5

0 (false)

"TRUE" .EQ. 1

1 (true)

"FALSE" .EQ. 0

1 (true)

"123" .EQ. 123

1 (true)

String Comparisons
Use string comparison operators to compare strings. DCL compares
character strings based on the binary values of the characters in the
string. If the result of the string comparison is true, the
expression has the value 1. If the result of the comparison is false,
the expression has the value O.
If you specify an integer value as an operand in a string comparison,
DCL converts the integer to a string before performing the comparison.
In addition, if one string is longer than the other, DCL pads the
shorter string with null characters to match the length of the longer
string before making the comparison.

3-10

Expressions and Operators
Examples of string comparisons follow:
Expression

value of Expression

"ABCD" .LTS. "EFG"

1 (true)

"YES" .GTS.

o (false)

"YESS"

"FALSE" .EQS. 0

o (false)

String Concatenation
Use a plus sign character (+) between strings to link or concatenate
strings.
The result of this operation is a string value.
When you
specify an integer value as an argument to the plus sign (+) operator,
DCL performs addition, not concatenation.
The following example
concatenates two strings to form a single string:
$ A = "MYFILE" + ".MEM"
$ SHOW SYMBOL A
A == "MYFILE.MEM"

3-11

Chapter 4
DCL Functions in Command Procedures

This chapter describes how to use DCL functions to manipulate strings
or integers, or return information about a file, a job, or the system.
You can use DCL functions in the same places you use symbols,
expressions, or literal values.
In command procedures, you can use
DCL functions to perform operations such as:
o

Translate logical names

Manipulate strings

Determine the current processing mode of the procedure

Format of DeL Functions
The general format of a DCL function is:
F$function-name([arg, ... ])
where:
F$

indicates a DCL function.

function-name is the function to be evaluated. You can truncate
function names to any unique abbreviation.
enclose function arguments.
Functions that have no
arguments do not need parentheses.

a rg , ...

specify arguments for the function,

if any.

Function arguments can consist of symbols, integer expressions, string
expressions, or other DeL functions.

4-1

DCL Functions in Command Procedures
DCL performs automatic symbol substitution on all function arguments.
Therefore, when you use a symbol name as a DCL function argument, do
not enclose the symbol name within apostrophes.
Note that in some cases, one or more of a function's arguments are
optional.
If an argument is optional, you can exclude it from the
argument list.
You can also use commas to indicate which argument you
are excluding from the list.
For example, the F$PARSE function has
three arguments defined, all of which are optional.
You can specify
the first argument, as follows:
F$PARSE(ARG1)
In this example, you do not specify the second and third arguments.
You could also use commas to indicate that you are excluding the
second and third arguments:
F$PARSE(ARG1,,)
If you want to specify the first and second arguments, but omit the
third, you can use either:
F$PARSE(ARG1,ARG2)
or
F$PARSE(ARG1,ARG2,)
If you want to specify the first and third arguments, but omit the
second, you must use commas to separate the arguments.
For example:
F$PARSE(ARG1"ARG3)
Note that, in some cases, specifying an argument as a null string or
as the integer ~ero is not the same as excluding the argument from an
argument list.

DCL Functions
Table 4-1 summarizes the DCL functions.
The rest of this chapter
describes DeL functions in greater detail and gives examples of their
use.

4-2

DCL Functions in Command Procedures
Table 4-1:

Summary of DCL Functions

+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Function
Description
+ - - - - - - - - - - - - - - + - - - - - - - - - - - - - - -.- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +

I
I F$ACCESS

I Returns the current job's access mode

+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I F$ASCII

Converts the first character in a string to its I
ASCII
value
I
I
+ - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
I

F$CHR
Converts an integer to its ASCII value
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

I
I F$CVTIME

I
I Converts a date/time string to
I for comparisons

suitable I

string

+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I Edits a string
F$EDIT
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

I
I F$INSTR

I
I Returns the location of a substring

+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I F$INTEGER

I
I Converts a string to an integer

+ - - - - - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

F$JOB
Returns the current job number
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

Extracts a substring from a string, beginning at
position 1, and ending at the position you specify
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

F$LEFT

I
I F$LENGTH

I Returns the length of a string

+ - - - - - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+

I
I

F$MESSAGE

I
I Returns the message text associated with
I error number

RSTS/E I

+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

F$MID

Extracts a substring from a string beginning at the
position you specify
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

F$NODE
Returns the current node name
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

4-3

DCL Functions in Command Procedures
Table 4-1:

Summary of DCL Functions (Cont.)

+- - - - - - -: - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Function
I
Description
I
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

F$PARSE

Returns a complete RSTSjE file specification or a
specified field within the file specification
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

F$PRIVILEGE
Returns the status of a job's privileges
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

F$RIGHT

I
I Extracts a substring from a string, beginning at
I the position you specify, and ending at
the
I rightmost position of the string

I
I
I
I

+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

F$SEARCH

Searches a disk directory for a file and returns I
the complete RSTSjE file specification of the next I
occurrence of the file
I
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

F$STRING
Converts an integer to a string
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

I
I F$TERMINAL

I
I Returns the KB number for the current RSTSjE job

+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I F$TIME

I Returns the current time and date

+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I F$TYPE
I

I
I
I Returns a string indicating the type of a symbol or I
I
I expression

+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I F$USER
I

I
I Returns the project-programmer
I current RSTSjE job

number

for

the I

+ - - - - - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

F$VERIFY
Enables or disables the verification setting
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

The following sections describe the DCL functions in alphabetical
order.

4-4

DCL Functions in Command Procedures
F$ACCESS
F$ACCESS
The F$ACCESS function returns a string that shows the current job's
execution mode.
The format of the F$ACCESS function is:
F$ACCESS ( )
The F$ACCESS function returns one of the following keyword strings:
Keyword

Meaning

BATCH

The job is running on a pseudo keyboard, under the
control of a batch processor.

DIALUP

The job is running over a dial-up line.

LOCAL

The job is running at a local terminal.

NETWORK

The job was created over the network, and is running
on a pseudo keyboard under control of the job on the
remote system.

SERVER

The job is running detached under the control of a
network controller.

Use the F$ACCESS function in command procedures that must act
differently depending on the current job's access mode.
The following example uses the F$ACCESS function:
$ lExit unless in BATCH mode
$ IF F$ACCESS .NES.
"BATCH" THEN EXIT

In this example, the IF command compares the character string returned
by F$ACCESS with the character string BATCH.
If the strings are
equal, processing continues. When the strings are not equal, the
procedure exits.

4-5

DCL Functions in Command Procedures
F$ASCII
F$ASCII
The F$ASCII function converts the first character in a string to its
ASCII value.
This function is similar to the BASIC-PLUS ASCII
function.
The format of the F$ASCII function is:
F$ASCII(string)
where string is a string expression.
The F$ASCII function always returns an integer in the range 0 to 255.
If you pass a null string as an argument to this function, it returns
the value O.
If you pass an integer as an argument to this function,
DCL converts the integer to a string and returns the firs~ character
of the string.
The following example uses the F$ASCII function:
$
$
$
$
$
$

INQUIRE ANSWER "Type Y to continue"
CHAR = F$ASCII(ANSWER)
!Check for 'Y' or 'y' as the first character
IF (CHAR ~EQ.· 89) .OR.
(CHAR .EQ. 121) THEN 'GOTO CONTINUE
EXIT
CONTINUE:

This command procedure uses an INQUIRE command to request user input,
which is assigned to the symbol ANSWER.
The next assignment statement
uses the F$ASCII function to convert the fir·st character of the input
string to its ASCII value and assigns that value to the symbol CHAR.
The IF command then tests the first character of the string and
branches to the label CONTINUE if the first character is Y or y.
If
the string begins with any other character, the procedure exits.

4-6

DCL Functions in Command Procedures
F$CHR
F$CHR
The F$CHR function converts an integer to its ASCII value.
This
function is similar to the BASIC-PLUS CHR$ function.
See Appendix D
for a table of the ASCII character codes and their decimal and octal
values.
The format of the F$CHR function is:
F$CHR(integer)
where integer is an integer value that corresponds to the character to
be returned.
Use this function to assign the ASCII value of a nonprinting character
to a symbol.
DCL treats all arguments as eight-bit unsigned integers
in the range 0 to 255.
If you specify an integer outside this range,
the low byte is returned as the ASCII character.
For example,
F$CHR(257) is equivalent to F$CHR(1), and F$CHR(-1) is equivalent to
F$CHR(255).
The following example uses the F$CHR function:
$
$
$
$
$

!Define the standard report heading
FORM_FEED = F$CHR(12)
HEADING = "INTEROFFICE MEMORANDUM"
NEW LINE = F$CHR(13) + F$CHR(lO)
INDENT = F$CHR(9)

$ !Write out the report heading
$ WRITE/NODELIMITER 1 FORM FEED , HEADING , NEW LINE , INDENT

This example:
o

Assigns the ASCII character 12 to the symbol FORM FEED
indicating a form feed.

Assigns the string "INTEROFFICE MEMORANDUM" to the symbol
HEADING.

Assigns the ASCII characters 13 and 10 to the symbol NEW LINE
indicating a carriage return and line feed.

4-7

DCL Functions in Command Procedures
F$CHR
o

Assigns the ASCII character 9 to the symbol INDENT indicating
a horizontal tab.

Uses the WRITE command along with the symbols to format a
report heading.
Note that because you specified /NODELIMITER, the next write
to channell will be indented to the first tab stop.

4-8

DCL Functions in Command Procedures
F$CVTIME

F$CVTIME
The F$CVTIME function converts a standard DCL date/time string or the
date/time string returned by the F$TIME function to a date/time string
of the form:
yy.mm.dd hh:mm
You can use the resultant string to compare two dates.
The format of the F$CVTIME function is:
F$CVTIME([date/time])
where:
date/time

is the date and time to be converted.
If you do not
supply a date and time, then the current date/time is
returned.
DCL displays an error message if you
specify an illegal date/time argument.

The date/time string can be any valid DCL date/time string, including
relative dates/times.
This function also accepts a string consisting
of a date field, one or more spaces or tabs, and a time field, which
lets you convert a string returned by the F$TIME function.
The function always returns a date/time string that is 14 characters
long, with a single space between the date and time fields.
In
addition, the time field is always returned in 24-hour format,
beginning at position 10 in the string.
The following example converts a system date/time string to a
comparison string:

$ TIME
F$TIME
$ SHOW SYMBOL TIME
TIME = "01-May-85 03:37 PM"
$ TIME = F$CVTIME(TIME)
$ SHOW SYMBOL TIME
TIME = "85.05.01 15:37"
$ TIME = F$CVTIME("+6DAYS")
$ SHOW SYMBOL TIME
TIME = "85.05.07 15:37"
In this example, the F$TIME function assigns the current date/time
string to the symbol TIME.
Then the F$CVTIME function converts the
date/time string to a string that you can use for comparisons.
The
example also shows that you can specify relative dates/times with this
function.
4-9

DeL Functions in Command Procedures
F$EDIT

F$EDIT
The F$EDIT function edits a string.
BASIC-PLUS CVT$$ function.

This function is similar to the

The format of the F$EDIT function is:
F$EDIT(string,integer)
where:
string

is the string to edit.

integer

is a bit-coded value that specifies the editing
function (or functions) to perform.

You can use F$EDIT to edit two strings before performing a comparison
of those strings.
For example, you can convert strings to uppercase,
strip off leading or trailing spaces and tabs, and so forth.
After
you execute this function, DCL returns an edited string. Note that
you can supply an integer argument, which is the sum of individual
function values.
For example, the value 48 performs both edit
functions 16 and 32.
The following example uses the F$EDIT function:
$ INQUIRE COMMAND "Command"
$ !Strip spaces/tabs and convert to uppercase
$ COMMAND = F$EDIT(COMMAND,2+32)

In this example, the INQUIRE command prompts the user for a string to
edit. After the user enters the string, the F$EDIT function removes
any spaces or tabs and converts the string to uppercase characters.
Table 4-2 lists the values for the F$EDIT function.

4-10

DCL Functions in Command Procedures
F$EDIT
Table 4-2:

Summary of F$EDIT Functions

+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Value I
Editing Function
I
+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I 2

I
I Discards all spaces and tabs

I
I

+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

Discards any of the following characters:
I
o Null (ASCII code 0)
I
o Line feed (ASCII code 10)
I
o Form feed (ASCII code 12)
I
o Carriage return (ASCII code 13)
I
o Escape (ASCII code 27)
I
o Delete (ASCII code 127)
I
+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
4

I
I 8

I
I Discards leading spaces and tabs

+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I 16

I
I Converts multiple spaces and tabs to a single space

I
I

+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I 32

I
I Converts lowercase characters to uppercase

I
I

+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I 64
I

I
I Converts left and right square brackets ([]) to
I right parentheses ((»

left

and I

+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I 128

I
I Discards trailing spaces and tabs

I
I

+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I 256

I
I Disables editing of characters within quotation marks

I
I

+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

4-11

DeL Functions in Command Procedures
F$INSTR
F$INSTR
The F$INSTR function locates a substring within a string and returns
the position of the substring as an integer.
This function is similar
to the BASIC-PLUS INSTR function.
The format of the F$INSTR function is:
F$INSTR(position,string,substring)
where:
position

is an integer, expression, or symbol that indicates
the position in the string at which to begin searching
for the substring.
If the position is negative or 0,
then the string is searched starting at position 1.
If the position argument is greater than the length of
the string, the function returns the value O.

string

is the string to search.

substring

is the substring to locate.
If the substring argument
is null, and the position argument is not greater than
the length of the string, the function returns the
specified start position.
If the substring is not
located, the function returns the value O.

You can specify the string and substring as either a string
expression, or as a symbol equated to a string expression.
The following example uses the F$INSTR function to count the number of
spaces in a string:

$ SPACES = 0
$ POS = 0
$ INQUIRE STRING "String"
$ LOOP:
$ POS = F$INSTR(POS + l,STRING," ")
$ IF POS .EQ.
0 THEN GOTO END
$ SPACES = SPACES + 1
$ GO TO LOOP
$ END:
$ WRITE 0 "Number of spaces = ",SPACES

This example uses an INQUIRE command to prompt for a string value.
The first time DCL executes the loop, POS is equal to 1, and STRING is
equal to O.
After DCL locates a space, it assigns a new value to P~S,
which is the integer position of the space within the string.
In

4-12

DCL Functions in Command Procedures
F$INSTR

addition, each time DCL locates a space, it increments SPACE by 1.
Finally, after DCL locates all spaces, the procedure branches to the
label END, and the WRITE command displays a message indicating the
number of spaces in the string.

4-13

DCL Functions in Command Procedures
F$rNTEGER
F$INTEGER
The F$INTEGER function converts a string expression to an integer.
The format of the F$INTEGER function is:
F$INTEGER(string)
where string is a string expression or symbol.
Use the F$INTEGER function to set a symbol to an integer value and
then use the symbol in an operation that requires an integer value.
For example:
$ A = "23"
$ B = F$INTEGER("-9" + A)
$ SHOW SYMBOL B

B = -923
In this example, the F$INTEGER function returns the integer equivalent
of the expression ("-9" + A), which evaluates to the character string
"-923". Because the expression contains two character strings, use
the plus sign (+) character for concatenation. The F$INTEGER function
ignores leading and trailing blank spaces. Note that the symbol A was
assigned the numeric character string "23".

4-14

DeL Functions in Command Procedures
F$JOB
F$JOB

The F$JOB function returns the current job number as an integer.
The format of the F$JOB function is:
F$JOB( )

Use the F$JOB function in command procedures that use their own job
number as input to a task, or that need to extract job information
from a file, such as a SYSTAT listing. For example:
$ JOB NO = F$JOB
$ WRITE 0 "This is job number "JOB NO'."

This command procedure assigns the current job number to the symbol
JOB NO and then displays the job number on your terminal.
Note

Be careful using the F$JOB function in command
procedures that contain programs that are meant to
detach during the procedure's execution. RSTS/E
creates a new job (containing the same command
procedure) when the program detaches. Therefore, the
F$JOB function will return the new job number.

4-15

DCL Functions in Command Procedures
F$LEFT
F$LEFT
The F$LEFT function extracts a substring from a string, starting at
position 1 and ending at the position you specify.
This function is
similar to the BASIC-PLUS LEFT function.
The format of the F$LEFT function is:
F$LEFT(string,position)
where:
string

is the string from which to extract the substring.

position

is an integer that specifies the ending position of
the substring to extract.
If the position argument is
negative or 0, the function returns a null string.
If
the position argument is greater than the length of
the string, the function returns the entire string.

The F$LEFT function returns a string that consists of all characters
from the first or leftmost position in the string through the position
you specify.
For example:
$ CHARS = F$LEFT("ABCDEFGHI",6)
$ SHOW SYMBOL CHARS
CHARS = "ABCDEF"
In this example, the F$LEFT function returns the string starting at
position 1 and ending at position 6.
DCL then assigns the resultant
substring, "ABCDEF", to the symbol CHARS.

4-16

DCL Functions in Command Procedures
F$LENGTH

F$LENGTH
The F$LENGTH function returns the length of the string that you
specify. This function is similar to the BASIC-PLUS LEN function.
The format of the F$LENGTH function is:
F$LENGTH(string)
where string is a string expression or a symbol that equates to a
string expression.
The following example uses the F$LENGTH function:
$
$
$
$

MSG NO=5
MESSAGE = F$MESSAGE(MSG NO)
MSG_LEN = F$LENGTH(MESSAGE)
IF MSG LEN .EQ.
0 THEN GOTO NULMSG

$ NULMSG:
In this example, the F$LENGTH function determines if message text was
returned by the F$MESSAGE function.
If no message was returned, then
the procedure branches to the NULMSG label.

4-17

DeL Functions in Command Procedures
F$MESSAGE
F$MESSAGE

The F$MESSAGE function returns message text corresponding to a RSTS/E
error number.
The format of the F$MESSAGE function is:
F$MESSAGE(error number)
where error number is an integer expression resulting in a value from
o to 255. DCL returns a null string if you specify a number that is
not within this range.
Use F$MESSAGE in command procedures that display either error message
text or the system installation name (error number 0). For example:
$ !Get the error message
$ ERROR TEXT = F$MESSAGE(2)

After you make this assignment, the symbol ERROR TEXT has the string
value:
?Illegal file name
Although each error message in the system error message file has a
numeric value, many numeric values do not have corresponding error
messages. See Appendix C for a complete list of the numeric values
associated with RSTS/E error messages.

4-18

DCL Functions in Command Procedures
F$MID
F$MID
The F$MID function extracts a substring from a string, starting at the
position you specify.
This function is similar to the BASIC-PLUS MID
function.
The format of the F$MID function is:
F$MID(string,position,length)
where:
string

is the string from which to extract the substring.

position

is an integer that specifies the starting position of
the substring.
If the position argument is negative
or 0, the starting position is 1.
If the position
argument is greater than the length of the string, the
function returns a null string.

length

is an integer that specifies the length of the
substring to extract.
If the length argument is
negative or 0, the function returns a null string.

The following example uses the F$MID function:
$ DEF = F$MID("ABCDEFGHI",4,3)
$ SHOW SYMBOL DEF
DEF = "DEF"
In this example, the F$MID function returns a string starting at
position 4.
The resultant substring, "DEF", is 3 characters long.

4-19

DCL Functions in Command Procedures
F$NODE
F$NODE
The F$NODE function returns the node name of the system on which the
job is running.
The format of the F$NODE function is:
F$NODE( )
If DECnet/E is installed and enabled on the system, DCL returns the
node name followed by two colons (::).
If DECnet/E is not installed,
or is not enabled, then DCL returns a null string.
For example:
$ NODE NAME = F$NODE
$ IF F$LENGTH(NODE_NAME) .GT.
0 THEN WRITE 0 "Your node is "NODE NAME'"
In this example, if the job is running on an active DECnet/E node, DCL
assigns the node name to the symbol NODE NAME.
The F$LENGTH function
compares the length of the string to 0 to determine if a node name was
returned.
If so, the WRITE command displays the node name at your
terminal.

4-20

DCL Functions in Command Procedures
F$PARSE
F$PARSE
The F$PARSE function returns one of three values:
o

A full RSTS/E file specification for the file you specify

A specified field within the file specification, when you
include a field keyword

A 32-bit number containing information about the file
specification

This function is similar to the BASIC-PLUS File Name String Scan
system function call.
See the RSTS/E programming Manual for a
description.
The format of the F$PARSE function is:
F$PARSE([file-spec][,default-spec][,field))
where:
file-spec

is a string expression that specifies the name of the
file to be returned.
If any part of the file-spec is
invalid, DCL returns an error.
However, if you
include the FLAGS keyword, DCL returns the value -1.
If you omit the file-spec or supply a null string, DCL
uses the entire default-spec.

default-spec

is a second file specification that defines defaults
for any missing fields in the file-spec string.
If
you omit a field in the file-spec string, DCL returns
the corresponding field in the default-spec string.
If you omit a field in both the file-spec and the
default-spec strings, the corresponding field in the
returned string is null.
If both strings are null,
DCL returns a null string. DCL returns an error if
any part of the default-spec is invalid.

field

is an optional keyword string that returns a specific
portion of the file-spec.
If you do not specify this
argument, F$PARSE returns a complete filespec, based
on the other two arguments.
The valid field keywords
are:
o

DEVICE -- Returns the device name.
The device
name can be either a physical or logical device
name. When you specify a physical device name,
DCL returns the device name preceded by an
underscore (_). When you specify a logical device
name, DCL returns the associated physical device

4-21

DCL Functions in Command Procedures
F$PARSE
name preceded by an underscore.
However, if the
logical name is not found, DeL returns the logical
name with no leading underscore.
DeL returns all
device names followed by a single colon (:). Note
that if you specify a file-spe~ without a device,
DeL returns a null string.
o

PPN -- Returns the project-programmer number
(PPN), in the form [proj,prog). You can specify
the asterisk (*) wildcard character in either
field of the PPN.
If you specify a file-spec
without a PPN, DCL returns a null string.

NAME -- Returns the file name.
If the file name
field consists of six or more question marks
(??????) or an asterisk (*), DeL returns an
asterisk (*).
If you specify a file-spec without
a file name, DeL returns a null string.

TYPE -- Returns the file type, preceded by a
period (.).
If the file type field consists of
three or more question marks (.???) or an asterisk
(.*), DCL returns an asterisk preceded by a period
(.*).
If you specify a file-spec without a file
type, DCL returns a null string.

STATUS -- Returns the device status word value as
a 32-bit integer, which contains information about
the device returned by the F$PARSE function.
If
you specify a file-spec without a device, DeL
returns the value O.
You can test each bit to
determine status.
The status word corresponds to
the BASIC-PLUS STATUS variable.
Table 4-3 shows the information, the tests, and
the meaning of each bit.

FLAGS -- Returns the flag word value as a 32-bit
integer, which contains information about the file
specification returned by the F$PARSE function.
You can test each bit to determine information
about elements found in the file specification.
Note that if you specify a null file-spec, DeL
returns the value 0, which indicates that no file
specification was found.
In addition, if you
supply an invalid file-spec and include this
keyword, DeL returns the value -1.
Thus, anytime
you request FLAGS, you must first check to see if
the value returned is -1.
If it is, then the
file-spec is invalid, and the other bits are
meaningless. Use FLAGS when you want to check for
4-22

DCL Functions in Command Procedures
F$PARSE
an invalid file-spec without having DCL display an
error message. The flag word corresponds to "flag
word 2" in the BASIC-PLUS file name string scan
system function call.
Table 4-4 shows the information, the tests, and
the meaning of each bit.
Table 4-3:

status Word Values

+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Bit I
Test
I
Meaning
I
+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

0-7

(STATUS .AND. 255)

The first eight bits of the
word contain the handler
index. The following values
apply for various devices:
o Disk
2 Terminal
4 DEC tape
6 Line Printer
8 paper Tape Reader
10 paper Tape Punch
12 Card Reader
14 Magnetic Tape
16 PK: device (pseudo
keyboard)
18 ox: device (flexible
diskette)
20 RJ: device (2780
remote job entry)
22 NL: null device
24 DMCll/DMRll/DDCMP
Interface
26 Auto-Dialer
28 X-y Plotter
30 Reserved
32 KMCll
34 IBM Interconnect
38 DMPll/DMVll

(STATUS .AND. 256).NE.0

The device is open for
non-file-structured processing
or is a non-file-structured
device.

(STATUS .AND. 512).NE.0

The job does not have read
access to the device.

4-23

DCL Functions in Command Procedures
F$PARSE
Table 4-3:

Status Word Values (Cont.)

+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Bit I
Test
Meaning
I
+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

(STATUS .AND. 1024).NE.0

The job does not have write
access to the device.

(STATUS .AND. 2048).NE.0

The device maintains its own
horizontal position. Such
devices are keyboards and line
printers.

(STATUS .AND. 4096).NE.0

The device accepts modifiers.
Such devices use the record
number as a modifier word
rather than the physical
position of the device.
Keyboards, line printers, and
card readers are such devices.

(STATUS .AND. 8192).NE.0

Device is a character device.

(STATUS .AND. 16384).NE.0

Device is an interactive
device (keyboard).

(STATUS .AND. 32768).NE.0

Device is a random-access
blocked device, such as disk
and non-file-structured
DECtape.

Reserved; returned as O.
16-31
+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

4-24

DCL Functions in Command Procedures
F$PARSE
Table 4-4 shows the information, the tests, and the meaning of each
bi t.
Table 4-4:

Flag Word Values

+ - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Bit
Test
Meaning
+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

(FLAGS .AND. 1).NE.O

File name was found in the
string.

(FLAGS .AND. 1).EQ.O

No file name was found (and
bits I and 2 of this word are
also 0).

(FLAGS .AND. 2).NE.0

File name was an asterisk (*)
character.

(FLAGS .AND. 2).EQ.0

File name was not an
character.

(FLAGS .AND. 4).NE.0

File name contained at least
one question mark (?)
character.

(FLAGS .AND. 4).EQ.0

File name did not contain any
? characters.

(FLAGS .AND. 8).NE.0

A period (.) was found.

(FLAGS .AND. 8).EQ.0

No period was found, implying
that no file type was
specified (and bits 4, 5, and
6 of this word are also 0).

(FLAGS .AND. l6).NE.0

A file type was found (that
is, the field after the period
was not null).

(FLAGS .AND. l6).EQ.0

No file type was found. (The
field after the period was
null -- and bits 5 and 6 of
this word are also 0.)

(FLAGS .AND. 32).NE.0

File type was an

(FLAGS .AND. 32).EQ.0

File type was not an
character.

4-25

* character.
*

DCL Functions in Command Procedures
F$PARSE
Table

4·4~

Flag Word Values (Cant.)

+- - - - _. -+- - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Bit
Test
Meaning
+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - -+_. - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

(FLAGS .AND. 64).NE.O

File type contained at least
one? character.

(FLAGS .AND. 64) .EQ.O

File type did not contain any
? characters.

(FLAGS .AND. 128).NE.0

A project-programmer number
(PPN) was found.

(FLAGS .AND. 128).EQ.O

No PPN was found (and bits 8
and 9 of this word are also

o) .

(FLAGS .AND. 256).NE.O

Project number was an *
character; that is, the PPN
was of the form [*,PROG].

(FLAGS .AND. 256).EQ.O

Project number was not an
character.

(FLAGS .AND. 512).NE.O

Programmer number was an *
character; that is, the PPN
was of the form [PROJ,*].

(FLAGS .AND. 512).EQ.O

Programmer number was not an
character.

(FLAGS .AND. 1024).NE.O

A protection code was found.

(FLAGS .AND. 1024).EQ.O

No protection code was found.

(FLAGS .AND. 2048).NE.O

The protection code currently
set as default by the current
job was used.

(FLAGS .AND. 2048).EQ.O

The assignable protection code
was not used.

(FLAGS .AND. 4096).NE.O

A colon (:), but not
necessarily a device name, was
found in the string.

4-26

DeL Functions in Command Procedures
F$PARSE
Table 4-4:

Flag word Values (Cont.)

+ - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Bit
Test
Meaning
+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

(FLAGS .AND. 4096).EQ.O

No colon was found (no device
was specified); bits 13, 14,
and 15 of this word are also
O.

(FLAGS .AND. 8192).NE.O

A device name was found.

(FLAGS .AND. 8192).EQ.O

No device name was found; bits
14 and 15 of this word are
also O.

(FLAGS .AND. 16384).NE.O

Device name specified was a
logical device name.

(FLAGS .AND. 16384).EQ.O

Device name specified was an
actual device name; bit 15 of
this word is also O.

(FLAGS .AND. 32768).NE.O

The logical device name
specified was invalid for one
of the following reasons:

(FLAGS .AND. 32768).EQ.O

4-27

The device name contained
an underscore but did not
correspond to any
physical device on the
system.

The device name did not
contain an underscore but
could not be translated
to a physical device
name.

The device name specified, if
any, was either an actual
device name or a logical
device name to which a
physical device has been
assigned.

DeL Functions in Command Procedures
F$PARSE
Table 4-4:

Flag Word Values (Cont.)

+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Bit

Test

Meaning

+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

16-31

Reserved; returned as 0,
except when the file-spec is
invalid, in which case all
bits (0-31) are set and the
value returned is -1.

+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

The following example uses the F$PARSE function to determine if a
device is a disk:
$ !Define default list file
$ DEFAULT = " SY:.LST"
$ !Prompt for output file-spec
$ INQUIRE OUTFIL "Output to"
$ !Build complete file-spec
$ OUTFIL = F$PARSE(OUTFIL,DEFAULT)

$ !Save device status
$ DEV STS = F$PARSE(OUTFIL,,"STATUS")
$ !Ensure device is a disk
$ IF (DEV_STS .AND.
255) .NE.

0 THEN GO TO NOTDSK

$ NOTDSK:
This example:
o

Assigns the default-spec value" SY:.LST" to the symbol
DEFAULT.

Uses the INQUIRE command to prompt for the file-spec to be
parsed and assign the result to the symbol OUTFIL.

Uses the F$PARSE function to return a complete RSTSjE file
specification after parsing both OUTFIL and DEFAULT.
DeL
assigns the new file-spec to the symbol OUTFIL, overriding
the previous assignment.

4-28

DCL Functions in Command Procedures
F$PARSE
o

Uses the F$PARSE function to assign the device status (as a
32-bit integer) to the symbol DEV_STS.

Uses the IF command to test the device status to determine if
the device is a disk.

4-29

DeL Functions in Command Procedures
F$PRIVILEGE
F$PRIVILEGE

The F$PRIVILEGE function returns one of two values:
o

The integer value 1 (true) if your job's current privileges
match those specified in the list of privilege keywords

The integer value
match

a (false) if the job's privileges do not

The format of the F$PRIVILEGE function is:
F$PRIVILEGE( 10 [NO)privilege[ t • • • ] n)
where:
[NO]privilege is a privilege keyword optionally preceded by "NOn.
If you specify several privilege keywords, you must
separate them with commas (,) and you must enclose the
entire list within quotation marks ("). When you
specify [NO]privilege, the function returns the value
1 (true) only if the current job does not have the
specified privilege.
Table 4~5 lists the valid privilege keywords and describes the
function of each.
Table 4-5:

Summary of Privileges

+- - - - - - - - - - -+ _. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Privilege I
Description
+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I

DATES
I Change system clock and file dates.
+ - - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
I

DEVICE

I
I

Access restricted devices.

+- - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
I

EXQTA

I
I
I

Exceed disk quota or memory maximum. (Not usually
given to users; used by privileged programs.)

I
+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
I

I GACNT

I Perform accounting operations on accounts in the

I user's group.
+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

I
I
I

GREAD

I
I
I

Read or execute any file in the user's group,
regardless of protection code.

+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

4-30

DCL Functions in Command Procedures
F$PRIVILEGE
Table 4-5:

Summary of Privileges (Cont.)

+ - ~ - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Privilege I
Description
I
+ - - - - - - - - - - -+- - - - - - - - - - - - _ •..........•.....• _ •...•..• _ •. _ ... - - _. _ .... +

I
I GWRITE
I

I Write or create/rename any file in the user's group,
I regardless of protection code.

I
I
I

+ •.... - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

I HWCFG
I

I
I

Set hardware configuration parameters; for example,
I
I set terminal characteristics.
I
+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _. - - - - - - - --+

I
I HWCTL
I

I
I
I Control devices; for example, disable a device or hang I
I
I up a dial-up line.

+- - - - - - - - - - -+- - _. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I INSTAL
I

I
I Install run-time systems, swap files, and resident
I libraries.

I
I JOBCTL
I

I
I Manipulate other jobs; for example, detach or kill a
I job.

I
I MOUNT

I
I Mount or dismount disks other than /NOSHARE.

+- - - - - - - - - .. +- - - - _. - - - - _. - - - - _. - - - - - - - - - _ .. - - - - - - _. - _. _ .. -. -. - _. - - - --+

+. - - - • - • - - - -+. - - - - - - - - _. - _. - - - - - _•.. - - - - .. - - - - - - - - - _. - - - - - - - - - - - - - - --+
+- - - - - - - - - - -+- - - - - - - - - - - - _•.. - - - - - _. - - - - - - - - - - - - - - - _. - _. - - - - - - - - - - - --+

I servers on or off, change printer forms.

I PBSCTL

I Control print/batch services; for example, turn

+- - - _. - _. - - -+- - - - - - - - _. _. - - - - - _. - _. - - _. - _. - - - - - - - - - - - - - _. - - - - - - - - _. _.+

I privileged programs.)

I RDMEM

I PEEK at memory. (Not usually given to users; used by

+- _. - - - - - -. -+- _. - - - - - - - - _... - - - - _. - _.. _. - - - - - - - - - - - - - - - _. - - - - - - - - - - --+
I
I

I
I SEND
I

I
I SETPAS

I
I Change your own password.

I
I SHUTUP

I
I Shut down the system.

I Read disks non-file·structured.
RDNFS
+- - - - - - _. - - -+- - _ .• - .. - _. _. - _ •. - - - - - _. - - - - - - - - - - - - _. - - - - - - _ .........•• +

Broadcast to terminals and send messages to restricted I
receivers.
I
+ .... _•.••.. + .. _...•..•..•....•..••........ - •....... - .•.••........... +
I
I

+ _.•.....• _.+ ... - ... _..... _.... _. - .. - - _•.. - - _•....•...... _. - . - - .... - .+

I
I

+ •••••••••• -+ .•....... _. _ ...... _.. - .•... - _.. _ .... _ .. - _ •.•.. _ ........ _+

4·31

DCL Functions in Command Procedures
F$PRIVILEGE
Table 4·5:

Summary of Privileges (Cont.)

+- - _. _. - - - - -+ - - - - - - - - - - - _.. _. - - - _. - - - - - - - _. - - - - - - - - - - - - - - - - - - - - - -. - --+
I privilege I
Description
I
+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I SWCFG
I

I
I Set software configuration parameters; for example,
I installation name.

I
I
I

+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I SWCTL
I

I
I Control software components; for example, turn
I DECnet/E on and off.

I
I
I

+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ~ --+

I
I SYSIO
I
I

I
I Perform restricted I/O operations; for example, gain
I write access to files in account [0,*], or set the
I privilege bit on executable files.

I
I
I
I

+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I SYSMOD
I

I
I
I Perform functions that could easily modify the system; I
I for example, poke m e m o r y . ·
I

+ - - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I TUNE
I

I
I
I Control system tuning parameters; for example, caching I
I or job priority.
I

+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

I USERO-7

I Available for customer applications. Not used by

I RSTS/E. .
I
+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I WACNT

I
I Perform accounting operations on any account.

+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I WREAD
I

I Read or execute any file regardless of protection

I code.
+- - - - - - - - - - -+- - - - - - - - - - _. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
I WRTNFS

I
I Read/write a disk non-file-structured.

I
I

+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I WWRITE
I

I write any file regardless of protection code.

I Create/rename any file except in account [0,*].

+ - - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

4-32

DCL Functions in Command Procedures
F$PRIVILEGE
The following example uses the F$PRIVILEGE function to determine if a
user has HWCTL privilege:
$ HWCTL_PRIV = F$PRIVILEGE("HWCTL")
$ IF HWCTL PRIV THEN GOTO CONTINUE
$ WRITE 0 "?Privilege HWCTL required"
$ EXIT
$ CONTINUE:

In this command procedure, if the user has HWCTL privilege, the
procedure continues to execute.
If the user does not have HWCTL
privilege, DCL displays a message on the user's terminal and the
procedure exits.

4-33

DCL Functions in Command Procedures
F$RIGHT
F$RIGHT

The F$RIGHT function extracts a substring from a string starting at
the position you specify and ending at the right-most position of the
string. This function is similar to the BASIC-PLUS RIGHT function.
The format of the F$RIGHT function is:
F$RIGHT(string,position)
where:
string

is the string from which to extract the substring.

position

is an integer that specifies the starting position of
the substring. If the position argument is negative
or 0, the function returns the entire string. If the
position argument is greater than the length of the
string, the function returns a null string .

The following example uses the F$RIGHT function:
$ CHARS = F$RIGHT("ABCDEFGHI",6)
$ SHOW SYMBOL CHARS
CHARS = "FGHI"
In this example, the F$RIGHT function returns the string starting at
position 6. DCL then assigns the resultant substring, "FGHI", to the
symbol CHARS.

4-34

DCL Functions in Command Procedures
F$SEARCH
F$SEARCH
The F$SEARCH function searches a disk directory for the file you
specify and returns its full RSTS/E file specification as a string.
Note
You cannot use the F$SEARCH function at the
interactive level.
The format of the F$SEARCH function is:
F$SEARCH([file-spec])
where:
file-spec

is a string expression that specifies the file to
locate. You must specify a file-spec the first time
you use the F$SEARCH function. A complete RSTS/E
file-spec consists of the fields:
_dev:[proj,prog]filnam.typ
You can use wildcard characters in the proj, prog,
filnam, or .typ fields.
If you specify an invalid
file-spec or a device other than a disk, DCL displays
an error message.
DCL returns a null string when you do not include the
file-spec argument in the initial use of the F$SEARCH
function, or when the F$SEARCH function cannot find
the specified file(s).

Use F$SEARCH to return information about one file, or about a series
of files in your directory.
You can also display information about
files in other directories, if you have read access to those files.
The first example shows how to use the F$SEARCH function to obtain
information about one file:
$ REPORT_FILE = F$SEARCH("REPORT.DAT")
After this command executes, the symbol REPORT FILE is assigned the
string value:
_SY:[4,2l4]REPORT.DAT

4-35

DCL Functions in Command Procedures
F$SEARCH
The second example uses the F$SEARCH function with a loop to obtain
information about all files in your account that have the same file
type:
$ NEXT~FILE = F$SEARCH("_SY:*.B2S")
$ LOOP:
$ IF NEXT_FILE .EQS.
"" THEN EXIT
$ WRITE 0 NEXT FILE
$ NEXT FILE = F$SEARCH()
$ GOTO LOOP
This example uses a wildcard and a loop to locate all occurrences of
files with the file type .B2S. DCL returns a null string, after
displaying all .B2S files in your directory.
If you have read access to other directories, you can also obtain
information about files in those directories.
For example:
$ SYSTEM WIDE = F$SEARCH("_SY:[*,*l*.LST")
$ LOOP:
$ IF SYSTEM_WIDE .EQS.
"" THEN EXIT
$ WRITE 0 SYSTEM WIDE
$ SYSTEM WIDE = F$SEARCH( )
$ GOTO LOOP
This command procedure displays all .LST files (in all directories on
the system) to which you have read access.

4-36

DCL Functions in Command Procedures
F$STRING
F$STRING
The F$STRING function converts an integer expression to a string.
The format of the F$STRING function is:
F$STRING(expression)
where expression is an integer expression or symbol that equates to an
integer expression.
The following example uses the F$STRING function:
$ A = 5
$ B = F$STRING( -2 + A)
$ SHOW SYMBOL B
B = "3"

In this example, the F$STRING function converts the result of the
expression (-2 + A) to the numeric string "3".
Note that the symbol A
has the integer value 5.

4-37

DCL Functions in Command Procedures
F$TERMINAL

F$TERMINAL
The F$TERMINAL function returns the keyboard (KB) number for the
current job, as an integer.
The format of the F$TERMINAL function is:
F$TERMINAL( )
Use the F$TERMINAL function in command procedures that need to
determine a job's keyboard number or determine if a job is currently
detached.
If the job is detached, this function returns a negative
value, which is the two's complement of the terminal from which the
job detached.
The following example shows the use of the F$TERMINAL function:

$ !Broadcast message to my terminal
$ TERM == F$TERNINAL
$ BROADCAST KB'TERM' "Assembly finished"

4-38

DCL Functions in Command Procedures
F$TIME
F$TIME
The F$TIME function returns the current date and time.
The format of the F$TIME function is:
F$TIME( )
This function returns a string of the form:
date time
where:
date

is the current date, in a format defined by your
system manager.
The date can have the format
dd-mmm-yy or yy.mm.dd.

time

is the current time, in a format defined by your
system manager.
Time can be either 24-hour or AM/PM
format.

The F$TIME function always returns a string.
The length of the string
depends on the format of the system date; no trailing blanks are
returned.
However, the time field is always returned starting at
position 11 in the string, regardless of the format of the system date
returned, because one or more spaces are inserted between the date and
time fields to force the time string to begin at position 11.
The followi

example shows the use of the F$TIME function:

$ WRITE 0 "Program started on H, F$TIME
Program started on 12-Jun-85 07:36 AM

4-39

DeL Functions in Command Procedures
F$TYPE
F$TYPE
The F$TYPE function returns a string indicating the type of a symbol
or expression.
The format of the F$TYPE function is:
F$TYPE(symbol)
F$TYPE(expression)
The F$TYPE function returns one of the following keyword strings:
Keyword

Meaning

INTEGER

The symbol has an integer value, or the expression
result is an integer.

STRING

The symbol has a string value, or the expression
result is a string.

null string

The symbol is not defined, or the expression contains
one or more undefined symbols.

The following example uses the F$TYPE function:
$ !Initialize COUNT if not yet defined
$ IF F$TYPE(COUNT) .EQS.
"UNDEFINED" THEN COUNT

== 0

In this example, the F$TYPE function determines the symbol's type.
If
COUNT is an undefined symbol, then the procedure starts counting at O.

4-40

DCL Functions in Command Procedures
F$USER
F$USER
The F$USER function returns the project-programmer number (PPN) for
the current job.
The format of the F$USER function is:
F$USER()
The F$USER function returns a string of the form:
[proj,prog]
where:
proj

is the project number for the current job.

prog

is the programmer number for the current job.

Use this function in command procedures that need to use their own
job's PPN as input to a task or compare and extract information from a
list, such as a DIRECTORY or SYSTAT listing.
For example:
$ ID = F$USER()
$ WRITE 0 "You are account "ID'."
You are account [1,214]

In this example, DCL assigns the PPN returned by F$USER to the symbol
ID.
The WRITE command then displays the PPN at the user's terminal
because you specified channel O.

4-41

DCL Functions in Command Procedures
F$VERIFY
F$VERIFY
The F$VERIFY function returns the current verification status as an
integer, indicating 1 if verification is on, and 2 if verification is
off.
If you specify an argument, this function also turns
verification on or off.
The format of the F$VERIFY function is:
F$VERIFY([value])
where:
value

is an optional argument that you can specify to turn
verification on or off. DeL examines the low-order
bit in the argument and turns verification off if the
value is 0, or on if the value is 1.

Use the F$VERIFY function to enable or disable verification for a
group of commands and then restore verification to its previous state.
For example:
$ !Save verify state and set NOVERIFY
$ SAVE_VERIFY = F$VERIFY()
$ SET NOVERIFY

$ !Restore verify state
$ IF SAVE VERIFY THEN SET VERIFY
In this example, the assignment statement saves the current
verification status in the symbol SAVE_VERIFY.
Then the SET NOVERIFY
command disables verification.
The IF command tests the value of
SAVE VERIFY.
If it is I, showing that verification was previously on,
the SET VERIFY command executes and verification is restored.
If
SAVE_VERIFY has a value other than 1, verification was initially off.
In this case, the SET VERIFY command is not executed, so verification
remains off.

4-42

DCL Functions in Command Procedures
F$VERIFY
When you use an argument, F$VERIFY still returns the current
verificatlon status. However, the command interpreter then examines
the low-order bit in the argument and turns verification off if the
value is 0, or on if the value is 1.
For e~ample:
$ !Save verify state and set NOVERIFY
$ SAVE VERIFY = F$VERIFY(O)

$ !Restore verify state
$ SAVE_VERIFY = F$VERIFY(SAVE_VERIFY)
In this example, the F$VERIFY function turns verification off, and
then restores the previous setting at the end of the procedure.

4-43

Chapter 5
Interacting with Command Files

This chapter describes how to control input to and output from command
procedures.
It tells you how to:
o

Pass data to a command procedure

Return data from a command procedure

Display data from a command procedure

Supply data to a program in a command procedure

Passing Data
When you write a command procedure, you need to be able to pass input
data to the procedure when it executes.
DeL provides the following
ways to do this:
o

You can pass data to a command procedure using parameters

You can issue a prompt to the user at the terminal, and the
user can enter data inter~ctively

The following sections describe these methods in greater detail.

5-1

Interacting with Command Files
Note
You can also read data from a file within a command
procedure. For example, you could design a command
procedure that displays informational records at a
terminal, or that reads the records of an assembly
listing file to search for possible errors.
See Chapter 6 for descriptions of the OPEN, READ, and
CLOSE commands, which you use to read data from a file
within a command procedure.

Passing Parameters
When you invoke a command procedure using the at (@) command, you can
pass it up to eight parameters by placing the values of the parameters
after the file specification of the command procedure. Separate the
parameters with one or more spaces or tabs. You can specify a
parameter value as one of the following:
o

Literal -- Specify the literal with or without quotation
marks ("), depending on whether you want to preserve spaces,
tabs, and lowercase characters. The following example passes
the values "JOHN" and "DOE" to DATA. COM:
$ @DATA John Doe

Use quotation marks to preserve spaces, tabs, or lowercase
characters. The following example passes the single value
"John Doe" to DATA. COM:
$ @DATA "John Doe"

Symbol -- To pass the value of a symbol, place an apostrophe
(') before and after the symbol. The following example
passes the values "JOHN" and "DOE" to DATA. COM:
$ NAME = "John Doe"
$ @DATA 'NAME'

When DCL passes a symbol, it removes quotation marks that
enclose a literal. To preserve spaces, tabs, and lowercase
characters in a symbol value, specify the enclosing quotation
marks as part of the symbol value. To include quotation
marks as part of a literal value, double the quotation marks
inside the literal string. The following example passes the
single value "John "Mr. Average" Doe" to DATA.COM:
$ @DATA "John ""Mr.

Average"" Doe"
5-2

Interacting with Command Files
DCL treats all types of parameters as literal string values and
assigns them to the local symbolsPl through p8: PI is assigned the
first parameter value; p2 the second; P3 the third; and so on. If you
pass more than eight values, DCL returns an error message and does not
execute the procedure. If you pass fewer than eight values, DCL
assigns null values to the remaining symbols. In addition, you can
pass a null parameter explicitly, by using double quotation marks in
the list of parameters.
In the next example, you pass parameters to the procedure DATA. COM:
$ @DATA "John Doe" "" 24 "(603) 555-8003"

When DCL processes this command string, it assigns the following
values to PI through p8:
PI
p2
p3
p4
p5
p6
P7
p8

"John Doe"
"
24"
(603) 555-8003"
"
"

When DCL enters a nested procedure, it assigns the local symbols PI
through P8 the new parameters passed by the invoking procedure . Note
that the local symbols pI through p8 in the nested procedure are not
related to the local symbols PI through p8 in the invoking procedure.
For example, suppose DATA.COM invokes NEWDATA.COM with the command:
$ @NEWDATA 'Pl'

In NEWDATA.COM, PI through p8 are defined as follows:
Pl
p2
p3
P4
p5
P6
P7
p8

=
=
=
=
=
=

"JOHN"
"DOE"
"
"
"
"
"
"

5-3

Interacting with Command Files
Prompting for Symbol Values
When you want a user to enter data interactively at a terminal, you
can use the INQUIRE command to define a value for a symbol while the
procedure is executing.
INQUIRE prompts for a value at a user's
terminal and waits for a response. After the user enters a response,
INQUIRE reads the value from the terminal and assigns it to the
specified symbol name.

+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
Format
I
INQUIRE symbol-name [prompt-string]
Command Qualifiers

Defaults

I
I
I
I
I
I
I
I
I
I
I

/[NO]PUNCTUATION
/PUNCTUATION
/[NO]ECHO
/ECHO
/EXIT[=label]
See discussion
/TIME_OUT=seconds
See discussion
/GLOBAL
/LOCAL
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
Command Parameters
symbol-name
IS a name from 1 to 255 characters long.
value to the symbol name.

DCL assigns a string

prompt-string
IS the prompt to display at the terminal when the INQUIRE command
executes.
If you do not specify a prompt string enclosed in
quotation marks, the command uses the symbol name to prompt for a
value.
Command Qualifiers
/[NO] PUNCTUATION
Indicates whether to append a colon and a space to the prompt
string when INQUIRE displays it.
The default is /PUNCTUATION.
To suppress the colon and space, use the /NOPUNCTUATION
qualifier.

5-4

Interacting with Command Files
/[NO]ECHO
Indicates whether to display the user's response to the prompt at
the terminal.
The default is /ECHO.
To suppress the display of
sensitive information at the terminal, such as passwords, use the
/NOECHO qualifier.
/EXIT[=label]
Specifies the label of the line in the command procedure to be
given control when a CTRL/Z is encountered.
If you do not
specify /EXIT, or if you specify /EXIT without a label, the
command procedure exits on a CTRL/Z.
/TIME_OUT=seconds
Specifies the number of seconds to wait for input.
If no input
is received within the specified time, DCL assigns a null string
to the symbol name.
The number of seconds must be in the range 1
to 32767.
/GLOBAL
places the symbol in the global symbol table.
default at the interactive command level.

/GLOBAL is the

/LOCAL
places the symbol in the local symbol table for the current
command procedure. /LOCAL is the default for all command levels
except the interactive level.
DCL displays an error message when
you specify /LOCAL at the interactive command level.
Examples showing how to use the INQUIRE command follow.

5-5

Interacting with Command Files
Use the /NOPUNCTUATION qualifier to suppress the colon and space that
are normally added after the prompt.
For example:

$ INQUIRE/NOPUNCTUATION IN "Input from?
$ INQUIRE/NOPUNCTUATION OUT "Output to?

"
"

When these commands execute, the following prompts appear at the
terminal:
Input from?
Output to?
To define a global symbol name with the INQUIRE command, use the
/GLOBAL qualifier.
For example:

$ INQUIRE/GLOBAL FILE "Filename"
When this command executes, DCL enters the symbol name FILE and the
response in the global symbol table.
To define a local symbol name with the INQUIRE command, use the /LOCAL
qualifier.
For example:

$ INQUIRE/LOCAL FILE "Filename"
When this command executes, the following prompt appears at the
terminal:
Filename:
After you enter a response, DCL places the symbol name FILE and the
value you enter in the local symbol table for the current command
procedure.
If you press the RETURN key in response to an INQUIRE command, DCL
assigns a null value to the specified symbol name.
For example:

$ INQUIRE FILE "File"
$ IF FILE .EQS.
"" THEN EXIT
.In this example, the INQUIRE command is followed by a test to
determine whether a null value was entered.
If a null value was
entered, the procedure exits.

5-6

Interacting with Command Files
Returning Data
To return a value from a command procedure (either to a calling
procedure or to the interactive level), you must assign the value to a
global symbol.
The global symbol can be read at any command level.
Use comments to explain the use of any global symbols.
To create a global symbol, specify the value to be passed on the right
side of a global assignment statement.
For example:
$ @DATA "John Doe"

DATA. COM
$
PI is a full name
$
NAME.COM returns the last name in the
$
global symbol LAST NAME
$
$ @NAME 'PI'

NAME.COM
$
PI is a first name
$
P2 is a last name
$
return p2 in the global symbol LAST NAME
$ LAST NAME == p2
$ EXIT
$
write LAST NAME to the terminal
$ WRITE 0 "LAST NAME
"""LAST NAME'"''''
LAST NAME = "DOE"

In this example, DATA. COM passes a full name to NAME.COM.
NAME. COM
places the last name in the global symbol LAST_NAME.
DATA. COM reads
the value by referencing the global symbol.

5-7

Interacting with Command Files
Displaying Data
You can display data in a command procedure by using the WRITE
command.
Use the WRITE command to display literal or symbol values, or a
combination of both, at a terminal:
o

Literal -- Enclose the text in quotation marks (").
following example displays the text "Two files were
written.":

$ WRITE
o

The

a "Two files were written."

Symbol Value -- The following example displays the text
"STATUS.DAT":

$ FILE = "STATUS.DAT"
$ WRITE a FILE
o

Combination of literals and symbol values -- Enclose the text
in quotation marks. Where a symbol appears, precede it with
two apostrophes and follow it with one apostrophe.
The
following example displays the text "STATI.DAT and STAT2.DAT
were written.":
$ AFILE = "STATI.DAT"
$ BFILE = "STAT2.DAT"
$ WRITE a ""AFILE' and "BFILE' were written."

See Chapter 6 for a complete description of the WRITE command.

Supplying Data to a Program
The following sections describe how to supply data to a program either
from inside a command procedure or interactively at a terminal while
the procedure executes.

Reading Data in a Program
When a program requiring terminal input runs directly under control of
a keyboard monitor, the program receives its input directly from the
user's keyboard.
However, when the same program runs under control of
a command procedure, all input normally received from the terminal is
read from the current command file.

5-8

Interacting with Command Files
For example, the following program prompts a user for a list of
numbers and prints the average value. In interactive mode, the
program dialogue is:
$ RUN AVRAGE

How many numbers? 4
1st number? 86
2nd number? 91
3rd number? 89
4th number? 90
The average is 89.0
$

You can also run the AVRAGE program from a command procedure using a
predefined set of numbers. The procedure would look like this:
$ RUN AVRAGE
4

86
91
89
90
$ EXIT

When the AVRAGE program requests data from the terminal, the monitor
intercepts the request and reads the data lines from the command file
instead. When you design this type of noninteractive command
procedure, you must eliminate any unexpected prompting that could
cause the procedure to read the wrong data.
You can also use the SET NODATA command (see the next section) to run
a program from a command procedure that supplies the program with
input from the terminal.

5-9

Interacting with Command Files
Supplying Data to a Program from a Terminal
By default, the SET DATA command is in effect when you invoke a
command procedure.
Thus, any data that a program or a keyboard
monitor (other than DCL) requests must be supplied in the command
file.
However, you can redirect data input back to a terminal by
issuing- the SET NODATA command.
The SET NODATA command tells DCL to
read all data required by a program or a command from the terminal
rather than from the command file.
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Format

SET [NO]DATA
Command Qualifiers

Defaults

/END_OF_DATA="char"
/END_OF_DATA=" $ "
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Command Qualifiers

Identifies an alternate prefix character to signal the end of
data. Whenever a line is read from the command file that begins
with the alternate prefix character, control returns to the DCL
keyboard monitor and any command following the alternate prefix
executes.
The alternate prefix character stays in effect until the data
list terminates. After control returns to DCL, the standard $
character is reenabled.
Note that you should never begin a data line with a $ character in the
first space, even if you define an alternate prefix character with the
SET DATA/END_OF_DATA command.
In cases where a program requires its
data to begin with a $ character, insert a leading space or a tab
space before the $ character to distinguish it from a DCL command
line.
(Most programs routinely remove leading spaces and tabs from
its data lines.)
For example, the following command file runs PIP to copy a file from
your account to the system library ($) account:
$ SET DATA
$ RUN $PIP
<TAB>$FOO=BAR
$ EOD

5-10

Interacting with Command Files
Since PIP's data line begins with a tab space, RSTS/E correctly treats
it as a data line.
The tab space does not affect the PIP command,
since PIP strips leading spaces and tab spaces.
Note that if you did
not include the tab space in this example, RSTS/E would handle the
data line as a DCL command line -- in this case, by stopping PIP and
executing the line as a DCL assignment statement.
Use the SET DATA command to supply data to a program from inside a
command procedure, specifying an alternate prefix character that
signals the end of data.
For example:

$ SET DATA/END_OF DATA="<"
$ CREATE LOGIN.COM
$RUN $SYSTAT
$SYSTAT.DAT
(data lines)

<
$ EXIT
In this example, $RUN $SYSTAT and $SYSTAT.DAT are data lines for the
CREATE command. When the alternate prefix character « ) is read,
control returns to the DCL keyboard monitor.
Note that if the prefix
character were a $, the procedure would interpret the first $ in $RUN
$SYSTAT as the end of data signal.
Use the SET NODATA command to supply a program with input from the
terminal.
The SET NODATA command stays in effect until you issue a
SET DATA command or until the current command procedure exits.
In nested command procedures, each level maintains its own [NO]DATA
setting and alternate prefix character. When a command procedure
exits, DCL restores the [NO]DATA setting and alternate prefix
character of the higher-level procedure.
The following example shows the command procedure AVRAGE.COM that runs
the program AVRAGE.TSK, letting you supply data at your terminal:
AVRAGE.COM

$ SET NODATA
$ RUN AVRAGE
$ EXIT

5-11

Interacting with Command Files
Note that this procedure does not include data lines for the AVRAGE
program. The SET NODATA command tells DCL to read data from the
terminal rather than from the command file.
For example, the dialogue
at your terminal would appear as:
$ @AVRAGE
How many numbers? 4
1st number? 91
2nd number? 87
3rd number? 92
4th number? 90
The average is 90.0
$

By using the SET NODATA command, you can supply different sets of data
to a program without modifying the command file.

Signaling the End of a Data List
Use the end-of-data ($EOD) command to signal the end of a data list
and exit from a program within a command procedure.
+-. _. - - - - - - - - - - - - - - - - - - _. - - - - - - - - _. - -. _... _... _. - _.... - - - --+
Format

$EOD
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - _. - - - - - - - - - - - - _ ••..• - _ •..• - - - --+

The only function of the $EOD command is to terminate data lists to a
program or to another DCL command. Although you can use any DCL
command preceded by the $ character to exit from a program, the $EOD
command provides a standard way to end a data list, and return to the
DCL keyboard monitor.

Exiting from a Program in a Command File
The RSTSjE monitor takes the following steps to exit from a program
and return to the DCL keyboard monitor. Whenever the monitor
encounters a $ prefix character, a special prefix character, an $EOD
command, or when it reaches the end of the current command file, it:
o

Forces up to five CTRLjZ characters to the program, as
needed. This step causes most RSTSjE programs to exit
normally.
5-12

Interacting with Command Files
o

Forces up to two CTRLjC exits to the program, as needed.
This step aborts any program that does not perform its own
CTRLjC handling.

Forces a double CTRLjC exit to the program.
This step aborts
any program that uses CTRLjC as a normal way to exit.

Aborts the program immediately, and returns control to the
DCL keyboard monitor.
This step is unconditional, and
specifically guards against CTRLjC trapping.

Detaching Programs in a Command Procedure
When designing command files to run programs that detach, you
generally want the command procedure to continue executing after a
program detaches.
For example, the START.COM start-up command file
must continue processing after the OPSER program detaches.
RSTSjE allows a command procedure to continue executing when it runs
programs that detach.
If a program running within a command procedure
detaches, RSTSjE detaches the current job, creates a new job at your
terminal, and then transfers all of the DCL context from the detached
job to the new job so that the command procedure can continue
executing.
Therefore, you should consider the following points when writing
command files that include programs that detach:
o

RSTSjE does not create a new job if the detach request leaves
the terminal either allocated to the job or open on any
non-zero channels.
In this case, the job detaches, and the
command procedure detaches with it.
You can set the "close"
flag in the detach system call to deallocate the terminal and
close any non-zero channels on which the terminal is open.

RSTSjE does not detach a job if no job slots are available to
create the new job.

When a program detaches, the command procedure continues to
execute, but in the newly created job; therefore, the F$JOB
function will return a different job number than the number
it returned before the program detached.
See Chapter 4 for a
complete description of the F$JOB function.

If you later attach to a job that detached within a command
procedure, it will not contain any DCL symbols, since all DCL
syntax was moved to the newly created job.

5-13

Interacting with Command Files
Passing Symbol Values to a Program
Only applications that run under DCL can perform symbol substitution.
Therefore, you must take a different approach when you need to pass a
symbol value to a program running under control of another run-time
system.
For example, the following incorrect command procedure runs
the PIP program under the RTII run-time system:
MOVE. COM
$ RUN $PIP
LB:*.* = 'PI'
$ EOD
Suppose you execute this procedure with the command:
$ @MOVE TEST.FIL
You might expect the value TEST.FIL to be substituted for the symbol
pI during execution.
However, this does not occur because the RTII
run-time system does not perform symbol substitution.
Only DCL
command lines can include symbol substitution.
To pass the value TEST.FIL to PIP, you must create a temporary command
file and execute it as a nested procedure within MOVE.COM.
For
example:
MOVE.COM
$ OPEN/WRITE/REPLACE I MOVEI.COM
$ WRITE I "$RUN $PIP"
$ WRITE I "LB:*.* = "PI'"
$ WRITE I "$EOD"
$ WRITE I "$EXIT"
$ CLOSE I
$ @MOVEI
$ DELETE MOVEI.COM
You create a temporary command file using a series of OPEN and WRITE
commands that are executed under DCL, which performs the symbol
substitution.
Now execute MOVE.COM with the command:

$ @MOVE TEST.FIL
During execution, DCL substitutes the value TEST.FIL for the symbol
PI, and PIP copies TEST.FIL from SY:
to LB:.

5-14

Chapter 6
File Input and Output

This chapter describes how to combine DCL commands with the
programming and symbolic capabilities of command procedures to
manipulate disk files on RSTS/E systems.
This chapter includes
techniques for using:
o

The OPEN command to create new files or access existing files

The READ command to read from files

The WRITE command to write to files

The CLOSE command to explicitly close files that you open

The basic steps in reading and writing to files from a command
procedure are:
1.

Open the file -- Use the OPEN command to open the file for
reading or writing.
You must also assign a channel number in
the range 1 to 13 so that you can later refer to the file.

Read or write to the file -- Use the READ or WRITE command to
read from or write to the file, specifying the channel number
on which the file is open.

Close the file - - Use the CLOSE command to close the file,
specifying the channel number on which the file is open.
Note that a file stays open until you close it or until you
log out of the system.

You can open, read, write, or close disk files that have the following
file organizations and record formats:
o

RSTS/E stream ASCII (native mode)

RMS sequential

6-1

File Input and Output
o

RMS stream

RMS variable

RMS fixed

RMS carriage control IMPLIED/NONE

RMS span/nospan

Opening Files
The OPEN command opens a file either for reading or writing.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Format
I

OPEN channel-number file-spec
Command Qualifiers

Defaults

/APPEND
/READ
/[NO]REPLACE
/WRITE

/READ
/READ
See discussion
/READ

Prompts

I
I
I
I
I
I
I
I
I
I
I
I
I
I

Channel: channel-number
File: file-spec
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Command Parameters
channel-number

Is a channel number in the range 1 to 13 on which to open the
file.
You can specify channel-number either as a literal or as a
symbol that evaluates to a number.
Subsequent READ, WRITE, and
CLOSE commands refer to the file by using the channel-number.
You get an error message if you specify a channel-number outside
the range of 1 to 13, or when you specify a channel number
already in use.

6-2

File Input and Output
file-spec
Specifies the file to open for input or output. You can use any
valid RSTS/E file specification; however, you cannot use
wildcards in the file specification.
If you omit the file type,
it defaults to .DAT.
Command Qualifiers
/APPEND
Specifies that new records are to be appended to the end of an
existing disk file.
If the file does not exist, RSTS/E creates a
new file.
Note
You can only use the /APPEND qualifier for RSTS/E
stream ASCII (native mode) disk files. An error
message displays if you use /APPEND for non-disk
files or files with RMS attributes.

/READ
Opens a file for reading. /READ is the default when you do not
specify a qualifier with the OPEN command.
/REPLACE
/NOREPLACE
Specifies whether to replace an existing file with a new file.
If the file that you specify already exists:
o

/REPLACE tells RSTS/E to delete the existing file and create
a new file.

/NOREPLACE tells RSTS/E not to replace the file if it exists;
in this case, an error message displays.

If you specify neither qualifier, then RSTS/E issues a warning
message and asks if you want to replace the file.

6-3

File Input and Output
You should always specify this qualifier from within a command
procedure if you are not sure the file exists.
You can use the
F$SEARCH function (see Chapter 4) to check the existence of a
file within a command procedure.
Note that the /[NO]REPLACE qualifier requires the /WRITE
qualifier and conflicts with the /APPEND qualifier.
/WRITE
Opens a file for writing.
If the file already exists, then DCL
deletes it and creates a new file (depending on the /[NO]REPLACE
qualifier).
When you open a file, you specify whether it is to be read from or
written to and assign it a channel number. Use the channel number in
subsequent READ and WRITE commands to refer to the file.
You cannot
use READ or WRITE commands to access an open file either from within a
program, or from keyboard monitors other than DCL.
In addition,
because channel 0 always specifies the user's terminal, you do not
need to use an explicit OPEN command to write to the user's terminal.
The following example uses the OPEN command in a command procedure:
$
$
$
$
$
$

ON ERROR THEN GOTO OPEN ERROR
FILE = "FILE1.DAT"
OPEN/READ 1 'FILE'
FILE = "FILE2.DAT"
OPEN/WRITE 2 'FILE'/REPLACE
ON ERROR THEN EXIT

$ CLOSE 1
$ CLOSE 2
$ EXIT
$ OPEN ERROR:
$ WRITE 0 "Error opening file "FILE'"
$ STOP
In this example, the first assignment statement assigns the string
value "FILE1.DAT" to the symbol FILE, and the OPEN/READ command opens
the file for reading on channell.
The second assignment statement
assigns the string value "FILE2.DAT" to the symbol FILE, and the
OPEN/WRITE command opens the file for writing on channel 2.
If an
error occurs while the system attempts to open either file, the
procedure branches to the OPEN_ERROR routine, displays an error
message, and returns to the interactive level. Otherwise, the
procedure continues executing until it closes the open files and exits
to either the calling command procedure or to the interactive level.
6-4

File Input and Output
Reading Files
The READ command reads the next record from a file that you open for
reading with the OPEN command and assigns the contents of the record
to the symbol name you specify.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Format

I
I

READ channel-number symbol-name

I Command Qualifiers
I
I /[NO]DELIMITER
I /END_OF_FILE=label
I /GLOBAL
I /LOCAL
I
I

I
I

Defaults
/NODELIMITER
None
See discussion
See discussion

Prompts

Channel: channel-number

I Symbol: symbol-name
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Command Parameters
channel-number
A channel-number in the range 1 to 13, that identifies the file
to be read.
You can specify channel-number either as a literal
or as a symbol that evaluates to a number. You get an error
message when:
o

You specify a channel number outside the range 1 to 13.

No file is open on the specified channel.

The file on the specified channel is not open for reading.

symbol-name
Is the symbol name to which DCL assigns the contents of the
record read in the READ command, as a string value.
If you use
the same symbol name for more than one READ command, each READ
command redefines the value of the symbol name.
The /GLOBAL and
/LOCAL qualifiers determine whether the symbol is global or
local.

6-5

File Input and Output
Command Qualifiers
/[NO]DELIMITER
Tells DCL whether to include the record delimiter (such as CR/LF
or FF) in the returned string.
The default is /NODELIMITER.
The
/DELIMITER qualifier tells DCL to append the record delimiter to
the string.
/END_OF FILE=label
Specifies the label of the line in the command procedure to be
given control when DCL detects an end-of-file (EOF) condition on
the read. When this condition occurs, no record is returned.
If
you do not specify an /END OF FILE qualifier, the action taken
depends on the current setting of the ON command.
See Chapter 8
for a complete description of the ON command and error handling
in command procedures.
/GLOBAL
Tells DCL to search the global symbol table for the symbol you
specified.
If DCL finds the symbol, it replaces its value.
If
'DCL does not find the symbol, then it enters the symbol into the
global symbol table.
DCL searches the global symbol table by
default when you execute a READ command at the interactive level.
/LOCAL
Tells DCL to search the local symbol table for the symbol you
specified.
If DCL finds the symbol, it replaces its value.
If
DCL does not find the symbol, then it enters the symbol into the
local symbol table.
DCL searches the local symbol table by
default when you execute a READ command at command levels other
than the interactive level.
In addition, you get an error
message if you specify /LOCAL at the interactive level.
Follow these steps to read data from a file:
1.

Open the file -- The OPEN/READ command opens the file for
read access and associates the file name with a channel
number.

Begin the read loop -- File I/O is usually done in a loop
unless you are reading or writing a single record.

6-6

File Input and Output
3.

Read the data from the file -- Use the READ command with the
/END_OF_FILE qualifier to read the next record in the file
and assign its contents to a symbol.
The /END OF FILE
qualifier causes DCL to pass control to the label-you specify
when you reach the end of the file.
Generally, you specify
the label that marks the end of the read loop.

Process the data -- Because you must read a file
sequentially, process the current record before reading the
next one.

Branch to the beginning of the loop -- You stay in the loop
until you reach the end of the file.

End the loop and close the file -- The CLOSE command
disassociates the file name from the channel number and
closes the file.

When you issue a READ command, DCL returns the next record in the file
as a string value and assigns it to the symbol name you specify. Note
that the returned string does not include any trailing line delimiter
characters.
You can read a record up to 255 characters long. You get an error
message if DCL encounters a record that exceeds this limit.
DCL updates the $STATUS and $SEVERITY symbols whenever an error (other
than an EOF trapped by the /END_OF_FILE qualifier) occurs on a read,
and then bases control on the current ON setting.
See Chapter 8 for
more information.
The following example uses a READ command in a command procedure:
$ OPEN/READ 1 NOTICE. TXT
$ LOOP:
$ READ/END_OF_FILE=END 1 DATA
$ WRITE 0 DATA
$ GOTO LOOP
$ END:
$ CLOSE 1
$ EXIT
In this command procedure, you open the file NOTICE.TXT for reading on
channel 1. The LOOP routine uses a READ command to read a record from
the file opened on channel 1 and assign it, as a string value, to the
symbol DATA.
The WRITE command displays the symbol's value at the
terminal.
Each time the loop is executed, a new record is read and
assigned to the symbol DATA, and written to the terminal, until the
entire file is read and displayed at the terminal. When the procedure
reaches EOF, control branches to the END routine, which closes the
file before the procedure exits.

6-7

File Input and Output
writing Files
The WRITE command writes records to a file that you open for writing
or appending with an OPEN command.
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Format
I

I
I WRITE channel-number data[, ... ]
I
I Command Qualifiers
Defaults
I
/DELIMITER
I /[NO]DELIMITER
I
I Prompts
I

I
I
I
I
I
I
I
I
I

I Data: data[, ... ]

I Channel: channel-number

+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Command Parameters
channel-number
A channel-number in the range 0 to 13 that identifies the file to
be written.
You can specify channel-number either as a literal
or as a symbol that evaluates to a number.
If you specify
channel 0, the data is written to the terminal.
You get an error
message when:
o

You specify a channel number outside the range 0 to 13

No file is open on the specified channel

The file on the specified channel is not open for writing or
appending

data[, ... ]
The data to write to the file.
The data list can contain one or
more string expressions separated by commas.
If you include
integer expressions in the data list, DCL automatically converts
them to string expressions before writing to the file.
DCL writes "each data item to the file as a string with no
intervening characters between each item.
You must include
spaces if you want to separate data strings written to the file.

6-8

File Input and Output
Command Qualifiers
/[NO]DELIMITER
Tells DCL whether or not to write the string with trailing
carriage return/line feed (CR/LF) characters.
The default is
/DELIMITER.
The /NODELIMITER qualifier is useful when you need
several WRITE commands to write a single record, or when you want
a record delimiter other than CR/LF, such as form feed (FF).
Note that you specify an alternate record delimiter in the data
list.
For example:
$ FF = F$CHR(12)
$ WRITE/NODELIMITER 0 TEXT,FF
In this example, you define and use form feed as an alternate record
delimiter.
DCL performs automatic symbol substitution when processing
expressions; therefore, do not use apostrophes (') to enclose symbol
names that you include in the data list of a WRITE command.
Whenever an error occurs on a write, DCL updates the $STATUS and
$SEVERITY symbols accordingly, and then bases control on the current
ON setting.
See Chapter 8 for more information.
The following examples show how to use the WRITE command in command
procedures:
$ LOOP:
$ INQUIRE/EXIT=END VALl "1st number"
$ VALl = F$INTEGER(VALl)
$ INQUIRE VAL2 "2nd number"
$ VAL2 = F$INTEGER(VAL2)
$ WRITE 0 VALl," + ",VAL2,"
",VALl+VAL2
$ WRITE 0 VALl," * ",VAL2,"
" , VALl *VAL2
$ GOTO LOOP
$ END:
$ EXIT
In this command proced~re, the INQUIRE commands prompt for symbol
values.
The WRITE commands perform automatic symbol substitution when
processing the expressions, displaying the result at the terminal.
When the procedure executes, the following appears at the terminal:
1st number: 10
2nd number: 20
10 + 20 = 30
10 * 20 = 200
1st number: <CTRL/Z>
$
6-9

File Input and Output
The next example shows how to read the records from one file and how
to write those records selectively to a new file in a command
procedure:
$ INQUIRE IN_FILE "Specify the file to read"
$ INQUIRE OUT_FILE "Specify the file to write"
$ OPEN 1 'IN FILE'
$ OPEN/WRITE 2 'OUT_FILE'
$ LOOP:
READ/END_OF_FILE=DONE 1 RECORD
$
$
IF RECORD .EQS.
"" THEN GOTO LOOP
WRITE 2 RECORD
$
$ GO TO LOOP
$ DONE:
$ CLOSE 1
$ CLOSE 2
$ EXIT

This command procedure:
o

Uses INQUIRE commands to prompt for a file to read (IN_FILE)
and the new file to write (OUT_FILE)

Uses OPEN commands to open both files

Uses a read/write loop (specifying the label to branch to
when the last record is read) to read the records from a file
and write those records to a new file with blank lines
suppressed

After the last record is read, branches to the DONE routine
and exits

6-10

File Input and Output
Closing Files

The CLOSE command closes a file opened for reading, writing, or
appending with the OPEN command and removes its channel number from
the list of open channels.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Format
CLOSE channel-number
Command Qualifiers

Defaults

/ALL
Prompts
Channel: channel-number
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+

Command Parameters
channel-number
Is a channel-number in the range 1 to 13, on which to close the
file. You can specify channel-number either as a literal or as a
symbol that evaluates to a number. If you specify a channel
number on which no file is currently opened, no error message
appears. However, DCL does return an error if you specify a
channel-number outside the range 1 to 13.
Command Qualifiers
/ALL
Tells DCL to close all open data files.
Any file that you open with an OPEN command stays open until you
explicitly close it using the CLOSE command, or until you log out.
Note
If the system manager deletes your job, or if you
delete a batch entry, and you have files open for
writing or appending, the most recent data written to
the file may be lost.

6-11

File Input and Output
Note that, because channel 0 always specifies the user's terminal, any
attempt to close channel 0 results in an error.
The following example uses the CLOSE command in a command procedure:
$
$
$
$
$
$
$
$
$

!Make sure that channels 1-5 are closed
CHANNEL = 1
LOOP:
CLOSE CHANNEL
IF CHANNEL .EQ.
5 THEN GO TO END
CHANNEL = CHANNEL + 1
GOTO LOOP
END:
EXIT

In this command procedure, you assign the value 1 to the symbol
CHANNEL.
Each time the loop is executed, DCL closes a channel,
increments the channel number, and so forth, until all five channels
are closed.

6-12

Chapter 7
Controlling Execution Flow in Command Procedures

Normal execution flow in a command procedure is sequential:
DCL
executes the commands in the procedure in order, until reaching the
end-of-file (EOF).
However, in some cases you may want to repeat a
series of commands, skip a series of commands, or abort the command
procedure.
The basic commands for controlling execution flow in a command
procedure are:
o

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 label in the
procedure

The at (@) command -- Invokes another command procedure and
begins execution at another command level

The EXIT and STOP commands -- Terminate the current procedure
and restore control to either the calling command procedure
or the interactive command level

The IF Command
The IF command tests the value of an expression and executes the DCL
command after the THEN keyword if the result of the expression is
true. An expression is true if its integer result is odd, otherwise
it is false.
DCL converts string values to integer values before
performing the test.
See Chapter 3 for a description of how DCL
converts strings to integers.

7-1

controlling Execution Flow in Command Procedures
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Format

IF expression THEN command
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Command Parameters
expression
Defines the test to be performed. The test may consist of any
valid DCL expression. An expression is true if the result is odd
and false if the result is even.
See Chapter 3 for a summary of operators and details on how to
specify expressions.
command
Defines the action to take if the result of the expression is
true.
You can specify any valid DCL or CCL command after the
THEN keyword, optionally preceded by a $ character.
If the result of the expression is false, control resumes at the
next line in the command procedure.
The following example uses the IF command:
$ COUNT = 0
$ LOOP:
$
COUNT = COUNT + 1

$
IF COUNT .LE.
$ EXIT

10 THEN GO TO LOOP

In this example, the IF command sets up a loop in a command procedure.
The IF command checks the value of the symbol COUNT and performs an
EXIT command when the value of COUNT is greater than 10.

7-2

Controlling Execution Flow in Command Procedures
The target command of an IF command can be another IF command.
example: .

For

$ IF A .EQ. B THEN IF C .EQ. D THEN IF E .EQ. F THEN RESULT = 1
In this example, the IF command tests each expression 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 the IF command expressions are true, RESULT is assigned a value
of 1; otherwise, the assignment statement is not executed.
You can use the @ command in an IF command to invoke another command
procedure.
For example:
$ IF A .EQ. B THEN @FILE2

If the result of the expression A .EQ. B is true, DCL executes the
nested procedure FILE2.COM. After the nested procedure executes,
control returns to the next line in the calling procedure.

Command Line Labels
Command line labels let you identify lines in a command procedure to
which control passes when a GO TO command executes.
You can precede
any command string in a command procedure with a label.
The rules for
entering labels are:
o

A label must appear as the first item on a command line and
must be preceded by a $ character

A label must end with a colon (:)

You can specify only one label on a command line

Keep the following in mind when you enter labels:
o

Excessive use of labels can exhaust the space available for
local symbols

DCL returns an error when insufficient space exists for
storing a label definition

DCL does not allow symbol substitution (apostrophes) in
labels because it performs label processing before it
performs symbol substitution

7-3

Controlling Execution Flow in Command Procedures
When DCL finds a label at the beginning of a command line, it enters
the label into a local label table that shares space in the local
symbol table.
If the label already exists in the table, DCL displays
an error message and immediately ends the procedure with a STOP
command.
For example:
$ LABELl:

$ GOTO LABEL2

$ LABELl:

$ LABEL2:

In this command procedure, DCL enters LABELl in the local label table
while processing the procedure. When DCL finds the GOTO command,
LABEL2 is not yet in the local label table.
DCL scans forward through
the procedure to locate the label. While scanning forward, however,
DCL finds a duplicate LABELl, displays an error message~ and
terminates the procedure with a STOP cOmmand.
Control immediately
returns to the interactive level.

The GOTO Command
The GOTO command passes control to a labeled line in a command
procedure.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Format

GOTO label
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

7-4

Controlling Execution Flow in Command Procedures
Command Parameters
label
Specifies a 1 to 255 character label that appears as the first
item on a command line. When the GOTO command executes, control
passes to the command following the specified label.
The label can precede or follow the GOTO command in the current
command procedure.
The GOTO command is useful after a THEN clause to cause a procedure to
branch forward or backward according to variable conditions or
parameters that you pass to the procedure.
For example:
$

It PI .EQS.

"" THEN GOTO ERROR

(normal processing)
$ ERROR:
(error processing)
In this example, DCL tests to determine if pl is null.
If it is, then
control passes to the label ERROR, where error processing occurs.
If
PI is not null, then control resumes at the next line after the GOTO
command.
You can also use the GO TO command to set up loops in a command
procedure.
For example:

$ NUM = 0
$ LOOP:
$
NUM = NUM + 1

IF NUM .LT.

11 THEN GOTO LOOP

In this example, you use the GOTO command in a loop that executes a
specified number of times.
The first line in the procedure sets up a
counter named NUM.
The loop increases the value of the counter, does
some processing and then tests the counter's value.
The command
procedure exits from the loop when the value of NUM is greater than or
equal to 11.

7-5

Controlling Execution Flow in Command Procedures
You can use the GOTO command in loops that prompt the user to indicate
whether execution should continue. During each iteration of the loop,
the procedure prompts for input data or a value for a variable.
For
example:
$ LOOP:
$
INQUIRE FILE "Filename"
$
IF FILE .EQS.
"" THEN GOTO SKIP

$
GOTO LOOP
$ SKIP:

In this example, the INQUIRE command requests a file name.
If the
user's response is a null value, the loop does not execute.
Otherwise, the loop executes iteratively until the user enters a null
value by pressing only the RETURN key.

Nesting Command Procedures
The GOTO command described in the previous section provides one way to
divide command procedures into more easily read and understood
sections.
In a more complex procedure, however, you may want to
separate different sections into several smaller procedures. Or you
may find it convenient to develop small, generalized procedures that
perform common functions and then invoke these procedures from other
procedures that you write.
You can call one command procedure from
inside another by using the @ command. Using the @ command to invoke
new levels of command execution is similar to using a CALL statement
in a high-level programming language.
When you enter a procedure, the command level increases by one.
For
instance, if you invoke procedure SUB from interactive command level
(level 0), SUB executes at command level 1.
If SUB then calls SUB1,
which calls SUBSBl, SUBl executes at command level 2 and SUBSB1 at
command level 3. The deepest permissible command level is 13.
By convention, the interactive level is the highest command level; and
command level 13 the lowest. Therefore, if you move from command
level 3 to command level 2, you move to the next higher command level.

7-6

controlling Execution Flow in Command Procedures
Figure 7-1 shows the flow of control when you execute nested command
procedures; the figure also shows how DCL creates new command levels
when you execute nested command procedures.

command
level 0

command
level 1

command
level 2

command
level 3

$ @SUB -----------SUB.COM
$ -.·-----1
$ first command
!
$ second command
$ @SUBl ------------._ SUBl.COM
$
-<--,
$ first command
$
I
$ second command
$
I
$ @SUBSBl - - - - - - -)IIao-SUBSBl. COM
------- $ EXIT
I
$
-.-----1
$ first command
I
$
I
$ second command
I
$
I
$
I
$
- - - - - - - - - - - - $ EX I T
$ EXIT

Figure 7-1:

Command Levels in Nested Command Procedures

If you need to pass information from one command level to another, use
one of the following techniques:
o

Passing parameters -- You can pass up to eight parameters to
a procedure you invoke using the @ command. See Chapter 5
for a description of techniques for passing parameters.

Using global symbols -- You can use global symbols to pass
data from one procedure to another; a global symbol defined
in a nested command procedure can be referred to in all
command procedures. See Chapter 2 for a description of
global symbols.

Using data files -- You can write data to a data file using
the WRITE command, then read the data back in a nested
command procedure using the READ command. See Chapter 6 for
information on writing and reading files.

7-7

controlling Execution Flow in Command Procedures
Exiting from a Command Procedure
A command procedure exits when it reaches the end of the procedure, an
EXIT command, or a STOP command.
If the exit is caused by the end of
the procedure or an EXIT command, control returns to the next higher
command level.
For instance, if you invoke SUB at interactive command
level, and SUB calls SUBI, then:
o

Exiting from SUBI returns you to SUB at the command line
following the call to SUBI.

Exiting from SUB returns you to interactive command level.

When you use the EXIT command to cause an exit, you can return a
status value to the next higher command level by specifying the value
as the parameter of the EXIT command.
This status value is placed in
the global symbols $STATUS and $SEVERITY. Upon returning from the
lower level routine, the higher level procedure performs any error
handling based on its ON ... THEN setting and the value of $SEVERITY.
See Chapter 8 for a description of error handling in command
procedures.
If the STOP command causes the exit, control immediately returns to
interactive command level.
The following sections describe the EXIT and STOP commands in greater
detail.

The EXIT Command
The EXIT command ends a command procedure and returns control to the
next higher command level.
+ - - - - - - - - - - - - - - - - - - - - - - - - - - -. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
Format

EXIT [status-code]
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

7-8

Controlling Execution Flow in Command Procedures
Command Parameters
status-code
A numeric expression that defines a value for the reserved global
symbols $STATUS and $SEVERITY.
Note that the reserved global
symbol $SEVERITY is affected by the value placed in the $STATUS
symbol. You can specify the status-code as an integer or an
expression.
If you do not specify a status-code, DCL does not
change the values of $STATUS and $SEVERITY from the most recently
executed command or program.
See Chapter 8 for a complete
description of the $STATUS and $SEVERITY symbols.
You can use the EXIT command to mak~ sure that a procedure does not
execute certain lines.
For example, if you write an error-handling
routine at the end of a procedure, you can place an EXIT command
before the routine:

$ EXIT
$ ERROR:

End of normal execution path

The EXIT command is also useful in procedures that have more than one
execution path.
For example:
$ START:
Pl .EQS.
"DISK" THEN GO TO 'pl'
$
IF Pl .EQS.
"TAPE" .OR.
$
INQUIRE Pl "Enter device (TAPE or DISK)"
$
GO TO START
Process tape files
$ TAPE:

$ 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 if either of
these strings was entered.
The GO TO command branches appropriately,
using the parameter as the branch label.
If PI is not TAPE or DISK,
the INQUIRE command prompts for a correct parameter; the GO TO START
command establishes a loop.
7-9

Controlling Execution Flow in Command Procedures
The commands after the labels TAPE and DISK provide different paths
through the procedure.
The EXIT command before the label DISK ensures
that the commands after the label DISK are not executed unless the
procedure explicitly branches to DISK.
Note that the EXIT command at the end of the procedure is not required
because an implicit exit occurs when DCL detects the end-of-file
(EOF).
However, DIGITAL recommends that you use the EXIT command at
the end of a command procedure.
When a command procedure has multiple levels of interaction, you can
use the EXIT command to pass status values from nested levels back to
the calling procedure.
The exit code defines values for the reserved
global symbols $STATUS and $SEVERITY.
For example, suppose the procedure A.COM contains these lines:
$ @B
$ IF $STATUS .EQ.

2 THEN GOTO CONTROL

In addition, the procedure B.COM contains the line:
$ EXIT 2
This EXIT command places the value 2 in the global symbols $STATUS and
$SEVERITY.
The calling procedure, A.COM, tests $STATUS.

The STOP Command
The STOP command ends a command procedure and immediately returns
control to the interactive level, thus terminating any intermediate
command procedures.
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Format
I

STOP
I
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

7-10

Controlling Execution Flow in Command Procedures
The following example uses the STOP command:
$ ON ERROR THEN GOTO OPEN ERROR
$ OPEN 2 FILE/READ

$ OPEN ERROR:
$
WRITE 0 "Error opening file"
$
STOP

In this command procedure, if an error occurs while attempting to open
a file, the procedure goes to the label OPEN_ERROR, prints a message,
stops executing, and returns immediately to the interactive level.

7-11

Chapter 8
Controlling Error Conditions and CTRL/C Interrupts

This chapter describes how to control command procedure execution when
an error condition or a CTRL/C interrupt occurs. An error condition
occurs when a command does not terminate successfully. A CTRL/C
interrupt is the result of pressing CTRL/C during command procedure
execution.

Error Condition Handling
Error conditions are stored as codes in the reserved global symbol
$STATUS.
If an EXIT command does not explicitly set a value for
$STATUS, then DCL returns its current value.
This value is set
implicitly by individual commands and programs that execute in a
procedure.
The value that is set, called a condition code, provides
information about the execution of:
o

The most recent command

The most recent program

The most recent procedure

The following sections describe how you can include action routines
and error handling statements in your procedures based on values in
$STATUS.

$STATUS and $SEVERITY Symbols
DCL reserves two global symbols, $STATUS and $SEVERITY, to maintain an
error condition code called "exit status."
The lowest three bits of the $STATUS value represent the severity of
the exit status.
The remaining bits of the $STATUS value are
reserved, and are currently undefined.
The $SEVERITY symbol contains
8-1

Controlling Error Conditions and CTRL/C Interrupts
the same value as the lowest three bits of the $STATUS value.
DIGITAL recommends that you test severity values using the $SEVERITY
symbol instead of the $STATUS symbol. This lets you avoid unnecessary
modifications in the future, if other bits in $STATUS are defined.
Table 8-1 lists the severity values and their meanings.
Table 8·1:

Sever i ty Values

+- - - - - - -+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Value I
Severity
Meaning
+- - - - - - -+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

WARNING

This condition indicates that an operation
completed, but not necessarily as expected.
For example, if you try to mount a disk
initialized read-only using the /WRITE
qualifier, the following warning message
appears:
%Disk is mounted read-only

RSTS/E prefixes all WARNING messages with
the percent sign (%) character.
+- - - - - - -+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
SUCCESS

This condition indicates that an operation
completed successfully, that is, with no
errors or warnings. Informational or action
messages also receive this status value.
+ - - - - - - -+ - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
I

I
I

I
2

I
ERROR

I
This condition indicates that an operation
did not complete. For example, an ERROR
message appears after you enter an illegal
command or after you enter a command using
inval id syntax.

I
I
I
I
I
I

RSTS/E prefixes all ERROR messages with the

I question mark (?) character.

+- - - - - - -+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
I

SEVERE ERROR

This condition indicates that an operation
did not complete, but for more serious
reasons.

I
I
I
I

RSTS/E prefixes all SEVERE_ERROR messages
with double question marks (??).
+- - - - - - -+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

8-2

Controlling Error Conditions and CTRL/C Interrupts
Note that the success code has an odd numeric value, while warning and
error codes have even numeric values.
Because DCL evaluates all odd
values as true (1) and all even values as false (0), you can use the
IF command to test the severity codes and determine if an operation
completed successfully.
For example:
$ IF $SEVERITY THEN ...

This IF command executes the command after the THEN clause when the
severity value is odd, indicating success.
$ IF .NOT. $SEVERITY THEN ...
This IF command executes the command after the THEN clause if the
severity value is even, indicating that a warning, error, or severe
error occurred.
Note
The following DCL commands, if they complete
successfully, do not affect the $STATUS or $SEVERITY
setting:
o

GOTO

STOP

$EOD

SHOW SYMBOL

ON (see the next section for more information)

an assignment statement

8-3

Controlling Error Conditions and CTRL/C Interrupts
The ON Command
By default, DCL performs an EXIT command when an error or severe error
occurs and continues processing when a warning occurs.
You can
override this default with the ON command.
The ON command specifies an action to be performed whenever DCL
detects a warning, error, or severe error in a command procedure.
Whenever a command, program, or command procedure completes, DCL
checks the exit status and takes action based on the current setting
of the ON command.
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Format

ON severity-level THEN command
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Command Parameters
severity-level
Specifies the severity level at which to perform the command
action.
You can specify one of the following severity-level
keywords:
o

WARNING

ERROR

SEVERE ERROR

command
Specifies the CCL or DCL command to be executed if the status
code returned from the last command, program, or command
procedure is greater than or equal to the severity level you
specify.
You can specify any valid CCL or DCL command after the
THEN keyword, optionally prefixed with a $ character.
When DCL finds an ON command, it stores the command following the THEN
keyword in a special area of the local symbol table and executes it
whenever an error greater than or equal to the specified severity
level occurs.

Controlling Error Conditions and CTRL/C Interrupts
If you define an ON command action for a specific severity level, DCL
performs the specified action when errors of the same or worse
severity occur. When less severe errors occur, DCL continues to
process the file.
Table 8-2 summarizes how the ON command controls error handling.
Table 8·2:

ON Command Keywords and Actions

+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I ON Keyword
Action Taken
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
I

Command procedure performs the specified action if I
I
a warning, error, or severe error occurs.
I
I
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
WARNING

ERROR

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

For example, if you want a command procedure to exit whenever a
warning, error, or severe error occurs, use the command:
$ ON WARNING THEN EXIT

If you want the command procedure to continue if a warning or an error
occurs, but to branch to another part of the file if a severe error
occurs, use a command such as:
$ ON SEVERE_ERROR THEN GO TO ERROR TRAP

This ON command requests that the procedure branch to the label
ERROR TRAP only in the case of a severe error.
If any command in the
procedure causes a warning or error condition, execution continues
with the next command in the procedure.
Note that severe errors always cause the command following the THEN
keyword to be executed, regardless of the severity level you specify
in the ON command.
You must disable error checking with the SET NOON
command for processing to continue when a severe error occurs.
When DCL executes the command following the THEN keyword, it resets
the ON setting to its default (ON ERROR THEN EXIT).
For example:
$ ON WARNING THEN GOTO ERROR TRAP
8-5

Controlling Error Conditions and CTRL/C Interrupts
In this example, if a warning occurs in the command procedure then
control passes to the first command following the label ERROR_TRAP,
and the ON setting is reset to ON ERROR THEN EXIT.
If you want to
restore the previous ON setting, you must reissue the ON WARNING THEN
GOTO ERROR TRAP command.
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 invokes another procedure, the ON
command action does not apply to the nested procedure.

Enabling and Disabling Error Checking
The SET NOON command lets you override default error checking. You
can use SET NOON to tell DCL not to check the status code returned
from the last command, program, or command procedure executed.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Format
I
I

SET [NOlON
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
During command procedure execution, DeL normally checks the status
code returned when a command, program, or command procedure completes,
and saves the numeric value of this code in the reserved global symbol
$STATUS.
The low-order three bits of this value are also saved in the
reserved global symbol $SEVERITY.
When SET NOON is in effect, DeL continues to place the status code
value in $STATUS and the severity level in $SEVERITY, but does not
perform any action based on the value. As a result, the command
procedure continues to execute regardless of how many errors are
returned.
Like SET ON, the SET NOON command applies only at the current command
level.
If you use the SET NOON command in a command procedure that
executes another procedure, DeL establishes the default, SET ON, while
the second procedure executes.

8-6

Controlling Error Conditions and CTRL/C Interrupts
The following example uses the SET NOON and SET ON commands:
$ ON WARNING THEN EXIT
$ SET NOON
$ MOUNT MMO:

$ SET ON

In this example, you temporarily disable error checking and attempt to
mount a tape.
If any error occurs, processing continues. The SET ON
command restores the current setting of the ON command; that is, the
procedure exits if later warnings, errors, or severe errors occur.
Note
Whenever an input error other than EOF occurs when
reading from a command file, DCL displays an error
message, generates a SEVERE ERROR, and terminates the
command procedure. DCL takes this action regardless
of the current ON setting or severity level.

CTRL/C Interrupt Handling
You can design a command procedure so that DCL takes a' certain course
of action when the user presses CTRL/C during execution of the
procedure.
When the user presses CTRL/C at a logged-in terminal, the RSTS/E
terminal service routine sets a CTRL/C event flag.
DCL initially
clears this flag when a user logs in to the system. Once the CTRL/C
flag is set, it remains set until examined by a monitor directive,
which clears the flag automatically. This design lets DCL read the
CTRL/C event flag to determine if a CTRL/C interrupt occurs during
command procedure execution.
If you execute a program within a command procedure that is designed
to abort or to perform clean-up operations and then abort when you
press CTRL/C, the CTRL/C event flag remains set and DCL takes action
based on the ON CONTROL C setting.
Some programs (such as MAIL), however, are designed to continue to
operate properly when the user presses CTRL/C.
In this case, DCL will
take CTRL/C action when the program exits. Because this may not be
desirable, make sure that the event flag remains clear by issuing the
8-7

Controlling Error Conditions and CTRL/C Interrupts
SET NOCONTROL=C command to disable CTRL/C checking before you ~xecute
the program.
Then, after the program executes, you can issue the SET
CONTROL=C command to reenable checking.
In addition, you can completely disable a terminal's CTRL/C key by
using the SET TERMINAL/NOCONTROL=C command.
Note
You should use the SET NOCONTROL=C and SET
TERMINAL/NOCONTROL=C commands for special applications
that have been thoroughly tested.
Generally, DIGITAL
does not recommend that you disable CTRL/C interrupts.
For example, if a procedure that disables CTRL/C
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 manager to
terminate it for you.
The following sections describe how to establish a CTRL/C action
routine, and how to enable or disable CTRL/C checking.

Setting a CTRL/C Action Routine
The ON CONTROL C command specifies the action to take when a CTRL/C
interrupt occurs during execution of a command procedure. The
specified action applies only within the command procedure in which
the command is executed.
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Format

ON CONTROL C THEN command
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Command Parameters
command
Specifies the DCL or CCL command to be executed if a CTRL/C
condition occurs.
You can specify any valid DCL or CCL command
after the THEN keyword, optionally prefixed with a $ character.
Using the standard rules of substitution, DCL first performs a syntax
check and substitutes any symbol value following the THEN clause. DCL
8-8

Controlling Error Conditions and CTRLjC Interrupts
then stores the command in a special area of the local symbol table
and executes it whenever a CTRLjC interrupt occurs.
The following example shows the use of ON CONTROL C:
$ ON CONTROL C THEN GO TO CTRL EXIT

$ CTRL EXIT:
$ CLOSE I
$ CLOSE 2
$ EXIT

When a CTRLjC interrupt occurs during execution of
executes the GOTO command, which transfers control
CTRL EXIT:. At this label, the procedure performs
operations.
In this example, clean-up consists of
opened on channels I and 2, and exiting.

this procedure, DCL
to the line labeled
clean-up
closing files

When you do not specify a CTRLjC action routine and a CTRLjC interrupt
occurs, DCL executes an EXIT command by default and returns control to
the next higher-level command procedure.
Because control returns with
the CTRLjC event flag still set, the higher-level procedure takes
whatever action you specify for CTRLjC handling at that level.
When you do specify a CTRLjC action routine, anytime DCL takes a
CTRLjC action, the default setting (ON CONTROL C THEN EXIT) is
reinitialized in the current procedure. Therefore, to establish a
setting other than the default, the procedure must reexecute the ON
CONTROL C command after a CTRLjC interrupt occurs.

Disabling and Reenabling CTRLjC Interruptions
The SET NOCONTROL=C command disables CTRLjC checking by DCL within a
command procedure. That is, if a command procedure executes the SET
NOCONTROL=C command, pressing CTRLjC will not cause the ON CONTROL_C
command to be executed.
Pressing CTRLjC will still have its normal
effect on running programs (unless a SET TERMINALjNOCONTROL=C command
is in effect).
On the other hand, the SET CONTROL=C command reenables CTRL/C
checking. THE SET [NO]CONTROL=C setting applies only at the current
command level.

8-9

Controlling Error Conditions and CTRL/C Interrupts
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Format

SET [NO]CONTROL=C
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -' - - - - - - - - - - - - - - - +
Use the SET NOCONTROL=C command in procedures where you do not want
DCL to take special action if a CTRL/C interrupt occurs.
For example:

$ SET NOCONTROL=C
$ RUN PROGI
$ SET CONTROL=C

In this example, the command procedure executes a program, which could
generate a CTRL/C condition. You issue the SET NOCONTROL=C command,
execute the program, and then reenable CTRL/C checking with the SET
CONTROL=C command.

8-10

Chapter 9
Controlling Terminal Output

RSTSjE provides the following ways to enable and disable command line
display and program output to your terminal during its execution of a
command procedure:
o

SET ECHO command

SET VERIFY command

Terminal logging commands

You can use these commands interactively or within a command
procedure.
However, they only affect output to your terminal when a
command procedure is executing.
By default, RSTSjE displays all output except DCL command lines during
command procedure execution.
However, you may sometimes want to
disable all terminal output for "silent" command procedure processing,
or to enable command line display to help debug a command procedure.

SET [NO]ECHO Command
You use the SET ECHO and SET NOECHO commands when you want to enable
and disable the display of all output from a command procedure on your
terminal.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Format
SET [NOjECHO
Command Qualifiers

Defaults

j[NOjWARNINGS
/WARNINGS
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
9-1

Controlling Terminal Output
Command Qualifiers
/[NO]WARNINGS
Specifies whether warnings and error messages display on the
terminal. You can use this qualifier only with the SET NOECHO
command.
When ECHO is in effect, RSTS/E displays the following during command
procedure execution:
o

All program data written to or echoed on the terminal

warnings and error messages

DCL command lines if SET VERIFY is in effect (see the
following section for a description of the SET [NO]VERIFY
command)

When you first log in to the system, ECHO is in effect. You can issue
the SET ECHO or SET NOECHO command either at the interactive level or
within a command procedure to change its setting.
The [NO)ECHO
setting is global to all command procedures and remains in effect
until you change it.
When NOECHO is in effect, RSTS/E displays only the following:
o

warnings and error messages (unless you specify the
/NOWARNINGS qualifier)

Messages broadcast to your terminal

Prompts from an INQUIRE command

Data output with the WRITE 0 command

RSTS/E suppresses all DCL command lines and other program data written
to the terminal when NOECHO is in effect.
If you specify the
/NOWARNINGS qualifier with the SET NOECHO command, then warnings and
error messages also do not display.
Note that NOECHO overrides the [NO)VERIFY setting, described in the
next section.

9-2

Controlling Terminal Output
SET [NO]VERIFY Command
You use the SET VERIFY and SET NOVERIFY commands when you want to
enable and disable the display of all DCL command lines as they occur
during command procedure execution.
See Chapter 2 for a complete
description of the SET [NO]VERIFY command.
SET [NO]VERIFY also controls whether RSTSjE writes the command lines
to a log file.
See the next section for a complete description of the
terminal logging feature.
If SET VERIFY is in effect, command lines are displayed exactly as
they appear in the procedure, before any substitution has been
performed.
You can specify the jDEBUG qualifier to display the
command line as it appears after substitution.
When you first log in to the system, NOVERIFY is in effect. You can
issue the SET VERIFY or SET NOVERIFY command either at the interactive
level or within a command procedure to change its setting.
The
[NO]VERIFY setting is global to all command procedures and remains in
effect until you change it.
When NOECHO is in effect (see the previous section), command lines are
not displayed at the terminal, regardless of the VERIFY setting.
However, if VERIFY is in effect and a log file is open (see the next
section), RSTSjE continues to write the command lines to the log file.

Creating a Log File of a Terminal Session
The terminal logging feature lets you create and use a terminal log
file to save a copy of the output that appears during the execution of
a command procedure.
See the RSTSjE System User's Guide for a
complete description, with examples, of terminal logging.
Note that if you enable a log file during execution of a command
procedure, the SET NOVERIFY command (see the previous section)
disables output of command lines both to the terminal and to the log
file.
The following sections describe the commands that you use to:
o

Open a terminal log file

Close a terminal log file

Selectively disable and enable output to the log file

9-3

Controlling Terminal Output
OPEN/LOG_FILE
The OPEN/LOG FILE command opens a disk file for terminal logging.
You
can issue the OPEN/LOG_FILE command either interactively or within a
command procedure.
You can only open one log file at any given time.
If a log file is
already open when you attempt to open a second log file, RSTS/E issues
an error message and does not open the second file; instead, the
current log file remains open.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Format

OPEN/LOG_FILE file-spec
Command Qualifiers

Defaults

/APPEND
/DISABLE
/ENABLE
/[NO]REPLACE
/[NO]TIME_STAMP

See discussion
/ENABLE
/ENABLE
See discussion
/NOTIME_STAMP

Prompts
File: file-spec
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Command Parameters
file-spec
Specifies the disk file to open for logging terminal output.
RSTS/E di splays an error message if you speci fy a nondi sk fi Ie.,
or if the file-spec is invalid. RSTS/E also displays an error
message if a log file is already open.
If you do not specify a
file type, RSTS/E assumes a file type of .LOG. Unless you
include the /APPEND qualifier, RSTS/E opens the file for output,
and deletes any existing file of the same name.
Command Qualifiers
/APPEND
Tells RSTS/E to add
This qualifier lets
existing log file.
RSTS/E ignores this

data to the end of the file you specify.
you append terminal output to the end of an
If the file you specify does not exist, then
qualifier and opens a new file.
Note that
9-4

Controlling Terminal Output
only RSTS/E stream ASCII files can be appended: if you specify a
file that has RMS attributes, an error message displays.
/DISABLE
Indicates that terminal output should not be logged to the file
until you issue the SET LOG_FILE/ENABLE command to enable
terminal logging.
/ENABLE
Indicates that output should be logged to the file.
This
qualifier is the default when you issue the OPEN/LOG_FILE
command.
/[NO)REPLACE
Specifies whether to replace an existing file with a new file.
If the log file that you specify already exists:
o

/REPLACE tells RSTS/E to delete the existing file and create
a new file.

/NOREPLACE tells RSTS/E not to replace the file if it exists;
in this case, an error message displays.

If you specify neither qualifier, then RSTS/E issues a warning
message and asks if you want to replace the file.
Note that the /[NO)REPLACE qualifier conflicts with the /APPEND
qualifier.
/[NO) TIME_STAMP
Indicates whether to prefix each line in the log file with a
date/time stamp.
The default is /NOTIME_STAMP.
However, if you
specify /TIME STAMP, RSTS/E prefixes ,each line in the log file
with a date/time stamp specifying the date and time that the line
was copied to the log file.
Note that the date and time format
is based on the system defaults that your system manager
establishes.
The date/time fields occupy the first 22 characters
of each line.

9-5

Controlling Terminal Output
CLOSE/LOG_FILE
The CLOSE/LOG FILE command closes a log file that you opened with the
OPEN/LOG_FILE-command.
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Format

CLOSE/LOG_FILE
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Use the CLOSE/LOG_FILE command to close an open log file either during
a session at your terminal or within a command procedure.
If logging is enabled when you issue the CLOSE/LOG_FILE command, then
RSTS/E writes the command itself to the log file before closing it.
If no log file is open when you issue this command, then RSTS/E
displays an error message.

After you open a log file, you can use the SET LOG_FILE command to
selectively enable and disable logging to the file.
You can also use
this command to enable or disable the time stamp feature in the log.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Format

SET LOG FILE
Command Qualifiers

Defaults

/DISABLE
/ENABLE
/[NO]TIME_STAMP
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
Command Qualifiers
/DISABLE
Indicates
logged to
disabled,
conflicts

that terminal or command file output should not be
the current log file.
If logging is currently
This qualifier
then RSTS/E ignores this qualifier.
with /ENABLE.

9-6

Controlling Terminal Output
/ENABLE
Indicates that terminal or command file output to the log file
should be enabled.
If logging is currently enabled, then RSTS/E
ignores this qualifier. This qualifier conflicts with /DISABLE.
/[NO]TIME_STAMP
Enables or disables the time stamp feature, which prefixes each
line in the log file with a date/time stamp in a format that the
system manager has defined.

9-7

Appendix A
Sample Command Procedures

The following sample command procedures demonstrate some of the
concepts and techniques that this manual discusses.
In the following example, the command procedure remembers the most
recent file you edited, and automatically places it in the editor when
you type the EDIT command:
$
$
$
$
$
$
$
$
$
$

EDIT. COM - Command file to "remember" last file edited
Parameters:
PI - file to edit, or null to edit last file edited
To take full advantage of this command file, add the
following global command to your LOGIN.COM file
$ EDIT == "@EDIT"

$ , Then, you edit a file in the usual way:
$
$
$
$
$
$
$
$
$

$ EDIT filespec
To edit the file you last edited, simply type:
$ EDIT
The last file edited is maintained in the global
symbol LAST EDIT.

$
$

IF F$TYPE(LAST EDIT) .EQS. "UNDEFINED" THEN LAST EDIT
IF F$LENGTH(Pl) .EQ . 0 THEN PI = LAST EDIT

$GETFIL:
$
$

IF F$LENGTH(PI) .EQ. 0 THEN
IF F$LENGTH(PI) .EQ. 0 THEN

LAST EDIT == PI
A-I

INQUIRE/EXIT=GETFIL PI "File"
GOTO GETFIL

Sample Command Procedures
SET NODATA
_WRITE 0 "Editing file ",LAST_EDIT," ... "
EDIT 'LAST EDIT'
SET DATA

$
$
$
$

In the following example, the command procedure searches for and reads
files specified with wildcards:
$

READ. COM - Command file to EDIT/READ wildcard file-specs

$
$

Parameters:
PI - wildcard filespec (prompt if null)

$
$
$
$
$

SET NODATA
IF PI .EQS. "" THEN INQUIRE/EXIT=END PI "Filespec to read"
PI = F$EDIT(Pl,-l)
NEXT FILE = F$SEARCH(Pl)

$LOOP:
$
$
$
$
$
$
$

IF NEXT_FILE .EQS. "" THEN EXIT
_INQUIRE/EXIT=END PI "Read "NEXT FILE' <yes>"
IF PI .EQS. "" THEN PI = "YES"
PI = F$EDIT(Pl,-l)
IF F$INSTR(l,"YES",Pl) .EQ. 1 THEN _EDIT/READ 'NEXT FILE'
NEXT_FILE = F$SEARCH()
GOTO LOOP

$END:

In the following example, the command procedure remembers command
arguments:
$1+
$1 MEMCOM - Remember previous arguments for commands
$1
$ 1 Parameters:
$1
PI Name of command to use
$1
p2 - P8 Arguments of command to be remembered
$1
$ ! Description:
$1
This procedure remembers its arguments and allows them
$!
to be used again if desired. It also understands wild cards
$!
if they are the first argument to the command (i.e. P2).
$!
$!
Parameter PI is the name of a DCL or CCL command such as EDT.

A- 2

Sample Command Procedures

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

This procedure uses a DCL global variable of the form
'Command'_Memory where 'Command' is the name of the command
to remember the arguments for each command.
If p2 is a wildcard filespec then MEMCOM will find the first
(or next) occurrence and prompt with the file found as the
default.
To accept the file type RETURN.
To see the next
file type CONTROL/Z. To quit type CONTROL/C.

$ ! Examples:

$!
$!

$ E-DT :== @MEMCOM EDT
$ EDT *.COM

$! or
$!
$!

$ TY-PE := @MEMCOM TYPE
$ TYPE *.B?S

$! .
$START:
WILD = 0 ! Initialize wild flag
$
$
$! Set command name. If no command is present then write an error
$! message (which will trigger default ON ERROR THEN EXIT action).
$
COMIlAND == pI
$
IF COMMAND .EQS. "" THEN WRITE 0 "?MEMCOM - No command present"
$
$
$! If command memory is undefined then set it to ""
$
IF F$TYPE('COMMAND'_MEMORY) .EQS. "UNDEFINED" THEN $
'COMMAND' MEMORY""
$
$! Assume second argument is a file name and save it.
If a file name
$! was specified then go process it.
$
FILE = p2
$
IF FILE .NES. "" THEN GO TO PARSE FILE
$
$
If something was saved in command memory
$ ! No file name was given.
$ ! then ask if it is to be used again; otherwise, just ask for
a file name.
$!
$
MEMORY = 'COMMAND' MEMORY
$
IF MEMORY .EQS. "" THEN GOTO ASK
$
INQUIRE/EXIT=NEXT FILE "FILE ("MEMORY')"
$
IF FILE .EQS. "" THEN FILE = MEMORY
$
GOTO PARSE FILE
$
$
$ ! Ask for a file spec if none was given on the command line and none
$ ! was saved in command memory
$
$ ASK:
INQUIRE/EXIT=EXIT FILE "FILE"
$
IF FILE .EQS. "" THEN GOTO ASK
$

A- 3

Sample Command Procedures
$
$1 This section parses the file spec. It separates any switches,
$1 constructs an argument list, and checks the file spec for wildcards.
$1 After the argument list is constructed it is saved in the
$1 command memory.
$
$ PARSE FILE:
POS = F$INSTR(I,FILE,"/")
$
$
SWITCH = ""
IF POS .NE. 0 THEN SWITCH
F$RIGHT(FILE,POS)
$
FILE = F$PARSE(FILE)
$
ARGS := 'FILE' 'SWITCH' 'p3' 'p4' 'pS' 'p6' 'P7' 'p8'
$
IF ARGS .NES. "" THEN 'COMMAND' MEMORY == ARGS
$
WILD = (F$PARSE(FILE,,"FLAGS") .AND. 870) .NE. 0
$
IF .NOT. WILD THEN GO TO DOlT
$
NEXT FILE = F$SEARCH(FILE)
$
$
$1 If the file spec was wildcard then ask for confirmation of any
If the user accepted the default
$ 1 file that matches the wild card.
$ 1 then construct the arg list with the next file.
$
$ ASK WILD:
INQUIRE/EXIT=NEXT FILE "FILE ("NEXT FILE')"
$
IF FILE .NES. "" THEN GOTO PARSE FILE
$
FILE = NEXT FILE
$
ARGS := 'FILE' 'SWITCH' 'P3' 'p4' 'pS' 'p6' , P7 ' 'p8'
$
$
$ 1 At last. Invoke the command on the constructed arg list
$
$ DOlT:
SET NODATA
$
'COMMAND' 'ARGS'
$
$
SET DATA
$
$ 1 If it was a wildcard file spec then get the next file and

$1 process it too.
$
$ NEXT:
$
NEXT FILE = ""
IF WILD THEN NEXT FILE = F$SEARCH()
$
IF NEXT FILE .NES. "" THEN GOTO ASK WILD
$
$
'"
$ 1 All done. Clean up and exit
$
$ EXIT:
VERIFY = F$VERIFY(VERIFY)
$
EXIT
$

A- 4

Appendix B
RSTS/E and VAX/VMS Command Processor Differences

Chapter 2 notes that it is desirable, where possible, to provide
compatibility between RSTS/E and VAX/VMS.
This helps customers who
use both operating systems, as well as those who will migrate to VAX
systems in the future.
Since RSTS/E and VMS have many inherent
differences, complete compatibility between the two systems is neither
desirable nor possible.
This appendix lists some of the major differences between the RSTS/E
and VMS command processors:
o

Character substring replacement -- RSTS/E does not support
the VMS substring assignment feature:
symbol-name[offset,size) :=[=) string-value

Arithmetic overlays -- RSTS/E does not support the VMS binary
overlay feature:
symbol-name[bit-position,size) = expression
o

Exit status values -- RSTS/E recognizes only the following
exit status values:

o (Warning)
1 (Success)
2 (Error)
4 (Severe error)
Note that RSTS/E does not support the VMS exit status value 3
(information).
o

Symbol substitution -- RSTS/E only supports the apostrophe
character as a substitution operator.
RSTS/E does not
support the VMS ampersand substitution operator. Users who
need the 'multi-level' substitution feature provided by the
ampersand operator can issue multiple assignments to produce
the same result.
B-1

RSTS/E and VAX/VMS Command Processor Differences
o

Symbol name abbreviations -- In order to maintain
compatibility with other commands, RSTS/E uses the hyphen (-)
character to identify a symbol name's minimum abbreviation.
RSTS/E also accepts the VMS abbreviation character (*).

RSTS/E accepts abbreviations for all command synonyms and
functions.

String operators -- RSTS/E only supports the string
concatenation operator, not the string reduction operator.

Symbol tables -- RSTS/E does not define local symbols at the
interactive level.
If a local symbol assignment is attempted
at the interactive level, DCL places the symbol in the global
symbol table.
If a command that accepts the /GLOBAL and
/LOCAL qualifiers is issued with /LOCAL at the interactive
level, DCL issues an error message.

Symbol table searching -- VMS performs symbol searching by
first searching the local symbol table at the current command
level, then searching each higher command level's local
symbol table, and then finally searching the global symbol
table.
RSTS/E first searches the local symbol table at the
current command level, then the global symbol table.
No
higher-level local symbol tables are searched.

VMS String Functions -- Since many RSTS/E users make use of
BASIC-PLUS as a programming language, the DCL string handling
functions on RSTS/E are compatible with BASIC-PLUS string
functions.
Use of the VMS string functions would cause
unnecessary confusion for RSTS/E users, since the VMS
functions use (O-based) offset arguments, rather than
(I-based) position arguments.
The following list outlines the RSTS/E string handling
functions and the corresponding VMS function:

RSTS/E Function

VMS Function

F$ASCII
F$CHR
F$CVTIME
F$EDIT
F$INSTR
F$LEFT
F$LENGTH
F$MID
F$RIGHT

(none)
(none)
F$CVTIME
(none)
F$LOCATE
(none)
F$LENGTH
F$EXTRACT
(none)

B-2

RSTS/E and VAXjVMS Command Processor Differences
o

DCL Files -- VMS uses a logical name as the means for
referencing an open file with the READ, WRITE and CLOSE
commands.
Furthermore, VMS makes use of standard logicals to
refer to the input, command and output devices (SYS$INPUT,
SYS$COMMAND, and SYS$OUTPUT). RSTS/E uses a channel number
to reference files opened with the OPEN command. This
technique lends itself more naturally to the file access
mechanisms used in BASIC-PLUS.

B-3

Appendix C
RSTS/E Error Messages

Table Col lists RSTS / E error messages and their corresponding numeric
values.

Table Col:

RSTS/ E Error Messages

+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

Decimal

I Value

Full Error Text

+ - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
1
2
3
4
5
6
7

8
9
10
11
12
13
14
15

16
17
18
19
20
21
22
23
24

??Bad directory for device
?Illegal file name
?Account or device in use
?No room for user on device
?Can't find file or account
?Not a valid device
?I/O channel already open
?Device not available
?I/O channel not open
?Protection violation
?End of file on device
??Fatal system I / O failure
?Data error on device
?Device hung or write locked
?Keyboard wait exhausted
?Name or account now exists
?Too many open files on unit
?Illegal SYS () usage
?Disk block is interlocked
?Pack IDs don't match
?Disk pack is not mounted
?Disk pack is locked out
?Illegal cluster size
?Disk pack is private
%Disk pack needs REBuILDing
C-l

RSTS/E Error Messages
Table Col:

RSTS/E Error Messages (Cont.)

+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I Decimal

I Value

I
Full Error Text

+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
26
27
28
29
30

31
32
33

34
35
36
37

38
39

40
41
42
43
44
45
46
47
48
49
50

51
52
53

54
55
56

57
58
59
60
61
62
63

64
65
66
67

68
69
70

??Disk pack mount error
?I/O to detached keyboard
Programmable AC trap
??Unused error message 29
?Device not file-structured
?Illegal byte count for I/O
?No buffer space available
??Odd address trap
??Reserved instruction trap
??Memory management trap
??SP stack overflow
??Disk error during swap
??Memory parity failure
?Maptape select error
?Maptape record length error
??Non-res run-time system
?Virtual buffer too large
?Virtual array not on disk
?Matrix or array too big
?Virtual array not yet open
?Illegal I/O Channel
?Line too long
%Floating point error
%Argument too large in EXP
%Data format error
%Integer error
?Illegal number
I %Illegal argument in LOG
I %Imaginary square roots
I ?Subscript out of range
I ?Can't invert matrix
I ?Out of data
I ?ON statement out of range
'I ?Not enough data in record
I ?Integer overflow, FOR loop
I %Division by 0
I ?No run-time system
I ?FIELD overflows buffer
I ?Not a random access device
I ?Illegal MAGTAPE ( ) usage
I ?Missing special feature
I ?Illegal switch usage
I ?End of volume
I ?Quota exceeded
I ??Unused error message 70
C-2

I
I

I
I
I
I

I
I
I

I
I
I
I
I

I
I
I

I
I

RSTS/E Error Messages
Table Col:

RSTS/E Error Messages (Cont.)

+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Decimal
I Value
Full Error Text
+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
III
112
113
114
115

?Statement not found
?RETURN without GOSUB
?FNEND without function call
?Undefined function called
?Illegal symbol
?Illegal verb
?Illegal expression
?Illegal mode mixing
?Illegal IF statement
?Illegal conditional clause
?Illegal function name
?Illegal dummy variable
?Illegal FN redefinition
?Illegal line number(s)
?Modifier error
??Unused error message 86
?Expression too complicated
?Arguments don't match
?Too many arguments
%Inconsistent function usage
?Illegal DEF nesting
?FOR without NEXT
?NEXT without FOR
?DEF without FNEND
?FNEND without DEF
?Literal string needed
?Too few arguments
?Syntax error
?String is needed
?Number is needed
?Data type error
?1 or 2 dimensions only
??Program lost-Sorry
?RESUME and no error
?Redimensioned array
%Inconsistent subscript use
?ON statement needs GO TO
?End of statement not seen
?What?
?Bad line number pair
?Not enough available memory
?Execute only file
?Please use the RUN command
?Can't CONTinue
?File exists-RENAME/REPLACE
C-3

RSTS/E Error Messages
Table Col:

RSTS/E Error Messages (Conte)

+- _. - -. - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Decimal
I Value
Full Error Text
+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

?PRINT-USING format error
?Matrix or array without DIM
?Bad number in PRINT-USING
?I11ega1 in immediate mode
?PRINT-USING buffer overflow
?I11ega1 statement
?Illega1 FIELD variable
stop
?Matrix dimension error
?Wrong math package
??Maximum memory exceeded
%SCALE factor interlock
?Tape records not ANSI
?Tape BOT detected
?Key not changeable
?No current record
?Record has been deleted
?Illegal usage for device
?Duplicate key detected
?Illegal usage
?Illega1 or illogical access
?Illegal key attributes
?File is locked
?Invalid file options
?Index not initialized
?Illegal operation
?I11ega1 record on file
?Bad record identifier
?Invalid key of reference
?Key size too large
?Tape not ansi labeled
?RECORD number exceeds max
?Bad RECORDSIZE on OPEN
?Not at end of file
?No primary key specified
?Key field beyond record end
?Illogical record accessing
?Record already exists
?Record/bucket locked
?Record not found
?Size of record invalid
?Record on file too big
?Primary key out of sequence
?Key larger than record
?File attributes not matched
C-4

RSTS/E Error Messages
Table Col:

RSTS/E Error Messages (Cant.)

+ - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

Decimal

I Value

Full Error Text
+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205

?Move overflows buffer
?Cannot open file
?No file name
?Terminal fmt file required
?Cannot position to EOF
?Negative fill or string len
?Illegal record format
?Illegal ALLOW clause
??Unused ERROR message 169
?Indexed not fully optimized
?RRV not fully updated
?Record LOCK failed
?Invalid RFA field
?Unexpired file date
?Node name error
?Negative TAB not allowed
?Too much data in record
?OPEN Error - file corrupted
??Unused ERROR message 179
?No support for op in task
%Decimal overflow
?Network operation rejected
?REMAP overflows buffer
?Unaligned REMAP variable
%RECORDSIZE overflows MAP
?Improper error handling
?Illegal record lock clause
??Unused ERROR message 188
??Unused ERROR message 189
??Unused ERROR message 190
??Unused ERROR message 191
??Unused ERROR message 192
??Unused ERROR message 193
??unused ERROR message 194
??Unused ERROR message 195
??Unused ERROR message 196
??Unused ERROR message 197
??Unused ERROR message 198
??Unused ERROR message 199
??Unused ERROR message 200
??Unused ERROR message 201
??Unused ERROR message 202
??Unused ERROR message 203
??Unused ERROR message 204
??Unused ERROR message 205

c-5

RSTS/E Error Messages
Table Col:

RSTS/E Error Messages (Cont.)

206
??Unused ERROR message 206
207
??Unused ERROR message 207
208
??Unused ERROR message 208
209
??Unused ERROR message 209
210
??Unused ERROR message 210
211
??Unused ERROR message 211
212
??Unused ERROR message 212
213
??Unused ERROR message 213
214
??Unused ERROR message 214
215
??Unused ERROR message 215
216
??Unused ERROR message 216
217??Unused ERROR message 217
218
??Unused ERROR message 218
219
??Unused ERROR message 219
220
??Unused ERROR message 220
221
??Unused ERROR message 221
222
??Unused ERROR message 222
223
??Unused ERROR message 223
224
??Unused ERROR message 224
225
??Unused ERROR message 225
226
??Unused ERROR message 226
227
?String too long
228
?RECORDTYPES not matched
229
??Unused ERROR message 229
230
?No fields in image
231
?Illegal string image
232
?Null image
233
?Illegal numeric image
234
?Numeric image for string
235
?String image for numeric
236
?TIME limit exceeded
237
?lst arg to SEQ$ > 2nd
238
?Arrays must be same dim
239
?Arrays must be square
240
?Cannot change array dims
241
?Floating overflow
242
?Floating underflow
243
?CHAIN to non-existent line
244
?Exponentiation error
245
?Illega1 exit from DEF*
246
?Error trap needs RESUME
247
?Illegal RESUME to SUBR
248
?Illegal subroutine return
249
?Argument out of bounds
250
?Not implemented
C-6

RSTS/E Error Messages
Table Col:

RSTS/E Error Messages (Cont.)

251
?Recursive subroutine call
252
?FILE ACP failure
253
?Directive error
254
??Unused ERROR message 254
255
??Unused ERROR message 255
+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

C-7

Appendix D
ASCII Character Codes

Table D-l lists all ASCII character codes.

Table D·l:

ASCII Character Codes

+ _. - - - _. _. - - - _. _ .• - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
ASCII
I
+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Decimal I Octal I
Character I
Remarks
+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

o
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

18
19
20
21
22
23

000
001
002
003
004
005
006
007
010
011
012
013
014
015
016
017
020
021
022
023
024
025
026
027

NUL
SOH
STX
ETX
EOT
ENQ
ACK
BEL
BS
HT
LF
VT
FF
CR
SO
SI
DLE
DCl
DC2
DC3
DC4
NAK
SYN
ETB

Null, FILL character
CTRL/A
CTRL/B
CTRL/C
End of transmission, CTRL/D
CTRL/E
CTRL/F
Bell, CTRL/G
Backspace, CTRL/H
Horizontal tab, CTRL/I
Line feed, CTRL/J
vertical tab, CTRL/K
Form feed, page, CTRL/L
Carriage return, CTRL/M
CTRL/N
CTRL/O
CTRL/P
CTRL/Q*, XON
CTRL/R
CTRL/S**, XOFF
CTRL/T
CTRL/U
CTRL/V
CTRL/W
D-l

ASCII Character Codes

Table 0-1:

ASCII Character Codes (Cont.)

+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
ASCII
I
+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Decimal I Octal I Character I
Remarks
+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

030
031
032
033
034
035
036
037
040
041
042
043
044
045
046
047
050
051
052
053
054
055
056
057
060
061
062
063
064
065
066
067
070
071
072
073
074

CAN
EM
SUB
ESC
FS
GS
RS
US
SP

61
62

075
076

=
>

63
64

077
100

?
@

"
#
$
%
&

1
2

3
4
5
6
7
8
9

CTRL/X
CTRL/Y
CTRL/Z, end of file
Escape***
File Separator
Group Separator
Record Separator
unit Separator
Space or blank
Exclamation point
Quotation mark
Number sign
Dollar sign
Percent sign
Ampersand
Apostrophe
Left parenthesis
Right parenthesis
Asterisk
plus
Comma
Hyphen or minus
Period or decimal point
Slash
Zero
One
Two
Three
Four
Five
Six
Seven
Eight
Nine
Colon
Semicolon
Left angle bracket, "less than"
sign
Equal sign
Right angle bracket, "greater than"
sign
Question mark
At sign
D-2

ASCII Character Codes

ASCII Character Codes (Cont.)

Table D-l :

+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+

ASCII
+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

Decimal

Octal

Character

Remarks

+ - - - - - - - - -+ - - - - - - -+ - - - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
I
I
I
I
I
I

65
66
67

68
69
70

73
74
75
76
77
78
79
80
81
82

84
85
86
87
88
89
90
91

92
93
94
95
96
97

98
99
100
101
102
103
104

105
106
107

101
102
103
104
105
106
107
110
111

112

113
114
115

K
L
M
N

116
117
120
121
122
123
124
125
126
127
130

131
132
133
134
135
136
137
140
141
142
143
144
145
146
147
150
151
152
153

C
D
E
F

G
H
I

0
p
Q
R

S
T

U
V
W
X

y
Z
[

\
]
A

a
b

c
d

e
f

h
i
j

Uppercase A
Uppercase B
Uppercase C
Uppercase D
Uppercase E
Uppercase F
Uppercase G
Uppercase H
Uppercase I
Uppercase J
Uppercase K
Uppercase L
Uppercase M
Uppercase N
Uppercase 0
Uppercase P
Uppercase Q
Uppercase R
Uppercase S
Uppercase T
Uppercase U
Uppercase V
Uppercase W
Uppercase X
Uppercase y
Uppercase Z
Left square bracket
Backs1ash
Right square bracket
Circumflex
Underscore
Grave accent
Lowercase a
Lowercase b
Lowercase c
Lowercase d
Lowercase e
Lowercase f
Lowercase g
Lowercase h
Lowercase i
Lowercase j
Lowercase k
D-3

ASCII Character Codes

Table 0·1:

ASCII Character Codes (Cont.)

+ .....••.••. - - _... _•..•. - - - - - - _.• - -. - - - - - - -. _. _. - - - - - ••. - - - - - - - _. _. --+
ASCII
+- •. - - _ .. -+_. _ ..• -+ •• _. _ .••• _. -+- - - - - - - - - - - - - - - - - - - - _. - - - - - _. - - - - - - --+
I Decimal I Octal I Character I
Remarks
+- - - - - - - - -+- - - - _. -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

154
155
156
157
160
161
162
163
164
165
166
167
170
171
172
173
174
175
176
177
200
201
202
203
204
205
206
207
210
211
212
213
214
215
216
217
220
221
222
223
224
225
226

1
m

n
o
p

q
r

s
t
u
v

w
x
y

z
{

I
}

DEL

IND
NEL
SSA
ESA
HTS
HTJ
VTS
PLD
PLU
RI
SS2
SS3
DeS
PUl
PU2
STS
eCH
MW
SPA

Lowercase 1
Lowercase m
Lowercase n
Lowercase 0
Lowercase p
Lowercase q
Lowercase r
Lowercase s
Lowercase t
Lowercase u
Lowercase v
Lowercase w
Lowercase x
Lowercase y
Lowercase z
Left brace
Vertical line
Right brace ***
Tilde ***
Delete
Reserved
Reserved
Reserved
Reserved
Index
New line
Horizontal tab set
Vertical tab set
Partial line down
Partial line up
Reverse Index
Single shift 2
Single shift 3
Device control string

0-4

ASCII Character Codes

Table 0-1:

ASCII Character Codes

(Cont~)

+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
ASCII
+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Decimal I Octal I
Character I
Remarks
+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
!

151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193

227
230
231
232
233
234
235
236
237
240
241
242
243
244
245
246
247
250
251
252
253
254
255
256
257
260
261
262
263
264
265
266
267
270
271
272
273
274
275
276
277
300
301

EPA
Reserved
Reserved
Reserved
control sequence introducer
String terminator

CSI
ST

OSC
PM
APC
¢

£
¥
§
©

I
i

±
2

.Q.

Reserved
Inverted exclamation point
Cent sign
Pound sign
Reserved
Yen sign
Reserved
Section sign
General currency sign
Copyright sign
Feminine ordinal indicator
Angle quotation mark left
Reserved
Reserved
Reserved
Reserved
Degree sign
Plus/minus sign
Superscript 2
Superscript 3
Reserved
Micro sign
paragraph sign, pilcrow
Middle dot
Reserved
Superscript 1
Masculine ordinal indicator
Angle quotation mark right
Fraction one quarter
Fraction one half
Reserved
Inverted question mark
Uppercase A with grave accent
Uppercase A with acute accent
D-5

I
I
I
I

I
I
I
I
I

I
I
I
I

I
I
I
I
I
I
I
I

I
I
I

I
I
I
I
I

I
I
I
I

ASCII Character Codes

Table 0-1 :

ASCII Character Codes (Cant. )

+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
ASCII
I
+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Remarks
I Decimal I Octal I Character I
I
+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I
I
I
I

I
I

I
I
I
I
I
I

I
I

I
I
I
I

I
I
I

I
I
I
I
I
I
I

I
I

A
A
A

194
195
196

302
303
304

197
198
199
200
201
202
203

305
306
307
310
311
312
313

204
205
206
207

314
315
316
317

208
209
210
211
212
213
214

320
321
322
323
324
325
326

215
216
217
218
219
220

327
330
331
332
333
334

221

335

222
223
224
225
226
227
228

336
337
340
341
342
343
344

a
a
a
a

229

345

A
IE

9
E
E
E
E
i
i
I
I

N
0
6
6

a
(E

U
U
(j

Uppercase A with circumflex accent
Uppercase A with tilde
Uppercase A with diaeresis or
umlaut mark
Uppercase A with ring
Uppercase A with dipthong
Uppercase C with cedilla
Uppercase E with grave accent
Uppercase E with acute accent
i
Uppercase E with circumflex accent
Uppercase E with diaeresis or
umlaut mark
Uppercase I with grave accent
I Uppercase I with acute accent
Uppercase I with circumflex accent
Uppercase I with diaeresis or
umlaut mark
Reserved
Uppercase N with tilde
Uppercase 0 with grave accent
Uppercase 0 with acute accent
Uppercase 0 with circumflex accent
Uppercase 0 with tilde
Uppercase 0 with diaeresis or
umlaut mark
Uppercase OE ligature
Uppercase 0 with slash
i Uppercase U with grave accent
i Uppercase U with acute accent
Uppercase U with circumflex accent
Uppercase U with diaeresis or
umlaut mark
Uppercase Y with diaeresis or
umlaut mark
Reserved
German lowercase sharp s
Lowercase a with grave accent
Lowercase a with acute accent
Lowercase a with circumflex accent
Lowercase a with tilde
Lowercase a with diaeresis or
umlaut mark
Lowercase a with ring
0-6

ASCII Character Codes

Table 0-1:

ASCII Character Codes (Cont.)

+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
ASCII
+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Decimal I Octal I Character I
Remarks
+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

230
231
232
233
234
235

346
347
350
351
352
353

Lowercase ae dipthong
Lowercase c with cedilla
9
e
Lowercase e with grave accent
e
Lowercase e with acute accent
e
Lowercase e with circumflex accent
Lowercase e with diaeresis or
e
umlaut mark
236
Lowercase i with grave accent
354
237
355
1
Lowercase i with acute accent
238
356
1
Lowercase i with circumflex accent
239
357
1
Lowercase i with diaeresis or
umlaut mark
240
360
Reserved
241
361
fi
Lowercase n with tilde
242
362
Lowercase 0 with grave accent
o
243
Lowercase 0 with acute accent
6
363
244
o
Lowercase 0 with circumflex accent
364
245
Lowercase 0 with tilde
5
I 365
246
Lowercase 0 with diaeresis or
366
I
umlaut
mark
I
247
Lowercase
oe ligature
367
I
248
o
Lowercase 0 with slash
I 370
249
Lowercase u with grave accent
U
I 371
372
250
Lowercase u with acute accent
I
251
373
Lowercase u with circumflex accent
I
252
374
i.i
I
I Lowercase u with diaeresis or
I
I umlaut mark
253
I Lowercase y with diaeresis or
I 375
I umlaut mark
I
254
I 376
I Reserved
255
I
377
I Reserved
* CTRL/Q, or XON, resumes output if the TTSYNC terminal
characteristic is set.
** CTRL/S, or XOFF, stops output if the TTSYNC terminal
characteristic is set.
*** ALTMODE(ASCII 125) or PREFIX (ASCII 126) keys, which appear on
some terminals, are translated internally into ESCAPE if the
ALT MODE terminal characteristic is set.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

0-7

INDEX

-A-

Alternate prefix character, 5-10
Apostrophe substitution, 2-9 to
2-10
Arithmetic
comparison operators, 3-10
logical operators, 3-9
operations, 3-9
ASCII character codes, D-lt
ASCII value conversion, 4-6
Assignment statement, 2-4
At sign (@) command, 1-5
Automatic evaluation of symbols,
2-10
-B-

Batch job execution, 1 - 7
-C-

CCL
see Concise Command Language
CHAIN statement, 1-8
CLOSE command, 6-11
CLOSE/LOG_FILE command, 9-6
@ command, 1-2, 1-5
Command levels, 2-6
Command levels in nested command
procedures, 7-7f
Command line labels, 7-3
Command procedure
command levels in nested, 7-7f
complex, 1-1
controlling
CTRL/C interrupts, 8-1
error conditions, 8-1
execution flow, 7-1
input., 5-1
output, 5-1
creating
CREATE, 1-2
EDT, 1 - 2
temporary, 5-14
DCL functions, 4-1
definition, 1-1
displaying data, 5-8

Command procedure (Cont.)
executing, 1-4
batch mode, 1-7
CHAIN statement, 1-8
interactive level, 1-5
login, 1-4
RUN command, 1-8
executing at interactive level,
1-6f
exiting, 7 - 8
expressions, 3-1
for system managers, 1-9
formatting, 1- 3
interacting with, 5-1
nesting, 1 - 8, 7-6
passing
control, 7-5
da ta, 5-1
parameters, 5-2
returning data, 5-7
samples, A-I
simple, 1-1
system crashes, 1-9
system startup, 1-9
uses, 1-1
using comments in, 1-3
using loops, 7-2
Command synonyms, 2-8
Commands
at sign (@), 1 - 5
CLOSE, 6-11
CLOSE/LOG_FILE, 9-6
DELETE/SYMBOL, 2-14
$EOD, 5 -12
EXI T, 7 - 8
GOTO, 7-4
IF, 7-1
INQUIRE, 5-4
ON, 8 - 4
ON CONTROL_C, 8-8
ON keywords and actions, 8-5t
OPEN, 6-2
OPEN/LOG_FILE, 9-4
READ, 6-5
RUN, 1-8
SET CONTROL=C, 8-9
SET DATA, 5-10, 5-11
SET ECHO, 9-1

Index-l

Commands (Con t. )
SET NOCONTROL=C, 8-9
SET NOON, 8-6
SET ON, 8-6
SET VERIFY, 2-11, 9-3
SET/LOG_FILE, 9-6
SHOW SYMBOL, 2-12
STOP, 7-10
SUBMIT, 1-7
WRITE, 6-8
Comparing integer values, 3-10
Comparing strings, 3-10
Concatenating strings, 3-11
Concatenating symbols, 3-2
Concise Command Language (CCL),
1-9
Converting values in expressions,
3-4
CRASH.COM, 1-9
CTRL/C
event flag, 8-7
interrupt handling, 8-7
-D-

Date/time string conversion, 4-9
DCL functions
arguments, 4-2
command procedures, 4-1
expressions, 3-3
F$ACCESS, 4-5
F$ASCII, 4-6
F$CHR, 4-7
F$CVTIME, 4-9
F$EDIT, 4-10
F$EDIT values, 4-11t
F$INSTR, 4-12
F$INTEGER, 4-14
F$JOB, 4-15
F$LEFT, 4-16
F$LENGTH, 4-17
F$MESSAGE, 4-18
F$MID, 4-19
F$NODE, 4-20
F$PARSE, 4-21
F$PRIVILEGE, 4-30
F$PRIVILEGE keywords, 4-30t
F$RIGHT, 4-34
F$SEARCH, 4-35
F$STRING, 4-37
F$TERMINAL, 4-38
F$TIME, 4-39

DCL functions (Cont.)
F$TYPE, 4-40
F$USER, 4-41
F$VERIFY, 4-42
format, 4-1
optional arguments, 4-2
summary, 4-3t
DELETE/SYMBOL command, 2-14
Deleting symbols, 2-14
Detached programs, 5-13
Disabling CTRL/C interrupts, 8-9
Displaying command procedures,
9-1 to 9-7
Displaying symbols, 2-12
-E-

Editing a string, 4-10
Enabling CTRL/C interrupts, 8-9
$EOD command, 5-12
Error checking
disabling with SET NOON command,
8-6
enabling with SET ON command,
8-6
Error conditions
controlling with ON command,
8-5
error codes, 8-3t
handling, 8-1
severity values, 8-2t
stored as codes in $STATUS, 8-1
success codes, 8-3t
Error messages, C-lt
Evaluating symbols, 2-10
Executing a command procedure at
interactive level, 1-6f
Executing command procedures, 1-4
EXIT command, 7-8
Exit status, 8-4
Exiting from a command procedure,
7-8
Expressions
command procedures, 3-1
converting
integers to strings, 3-6
strings to integers, 3-6
DCL functions, 3-3
determining types, 4-40
integers, 3-3
operators, 3-1, 3-7, 3-8t
quotation marks, 3-2

Index-2

Expressions (Cont.)
rules for determining type,
3-5t
string, 3-2
symbols, 3-4
types of values, 3-1
value conversion, 3-4

Global symbols
assigning, 2-4
assigning strings, 2-6
command synonyms, 2-8
creating, 2-7
GOTO command, 7-4
·1·

-F-

F$ACCESS, 4-5
F$ASCI I, 4 - 6
F$CHR, 4-7
F$CVTIME, 4 - 9
F$EDIT, 4-10
values, 4-11t
F$INSTR,4-12
F$INTEGER, 4-14
F$JOB, 4-15
F$LEFT, 4-16
F$LENGTH, 4-17
F$MESSAGE, 4-18
F$MID, 4-19
F$NODE , 4-20
F$PARSE, 4-21
flag word values, 4-25t
status word values, 4-23t
F$PRIVILEGE, 4-30
keywords, 4-30t
F$RIGHT, 4-34
F$SEARCH, 4-35
F$STRING, 4-37
F$TERMINAL, 4-38
F$TIME, 4 - 39
F$TYPE, 4-40
F$USER, 4-41
F$VERIFY, 4-42
Files
closing, 6-11
manipulating, 6-1
opening, 6-2
reading records, 6-5
returning information, 4-35
writing records, 6-8
Flag word values for F$PARSE,
4-25t
Formatting command procedures,

IF command, 7-1
INQUIRE command, 5-4
Integers
comparing, 3-10
converting
to ASCII values, 4-7
to strings, 3-6
converting to strings, 4-37
-J-

Job access modes, 4-5
Job number, 4-15
-L·

Labels
rules for entering, 7-3
storage, 7-4
Local label table, 7-4
Local symbol table, 2-6
Local symbols
assigning, 2-4
strings, 2-5
creating, 2-7
Log file
terminal session, 9-3 to 9-7
Logical operations, 3-9
LOGIN.COM file, 1-4
Loops, 7-2
-N-

Nested command procedure, 7-6
Nested command procedures, 1-8,
7-7f
-0-

1-3
-G-

Global symbol table, 2-6

ON command, 8-4
keywords and actions, 8-5t
ON CONTROL_C command, 8-8
OPEN command, 6-2

Index-3

OPEN/LOG_FILE command, 9-4
Operators
a r i thme tic, 3 - 9
arithmetic comparison, 3-10
expressions, 3-1, 3-7, 3-8t
logical, 3-9
priority in expressions, 3-7
.p.

Parameters
passing to a command procedure,
5-2
rules for passing, 5 - 2
Privilege keywords, 4-30t
Program
detached within command
procedure, 5-13
exiting , 5 - 12
passing symbol values, 5 - 14
reading data , 5-8
supplying input
command file, 5-9
terminal, 5-10
Project-programmer number, 4-41
Prompt-string, 5-4
Prompting for symbol values, 5-4
·R·

READ command, 6-5
Reserved global symbols
$SEVERITY, 8-1
$STATUS, 8-1
RSTS/E and VAX/VMS command
processor differences, B-1
Rules for determining expression
types, 3-5t
RUN command, 1-8

·s·
SET CONTROL=C command, 8-9
SET DATA command, 5-10, 5-11
SET ECHO command, 9-1
SET NOCONTROL=C command, 8-9
SET NOON command, 8-6
SET NOVERIFY command, 2-11
SET ON command, 8-6
SET TERMINAL/NOCONTROL=C command,
8-8
SET VERIFY command, 2-11, 9-3

SET/LOG_FILE command, 9-6
$SEVERITY symbol, 8-1
Severity values, 8-2t
Severity-level keywords, 8-4
SHOW SYMBOL command, 2·12
Signalling the end of data list,
5-12
START.COM, 1-9
$STATUS symbol, 8-1
Status word values for F$PARSE,
4-23t
STOP command, 7-10
String assignment statement, 2-6
Strings
compa ring, 3 - 10
concatenating, 3-2, 3-11
converting to integers, 4-14
determining length, 4 - 17
editing , 4-10
extracting substrings, 4 - 16,
4-19 , 4-34
locating substrings, 4-12
using in expressions, 3-2
SUBMIT command , 1-7
Summary of privileges, 4-30t
Supplying data to program, 5-11
Symbol
assigning null value, 5-6
assignment statement, 2-1
defining, 2-1
definition, 2-1
deleting a, 2-14
displaying a, 2-12
passing values to a program,
5-14
$SEVERITY, 8-1
$STATUS, 8-1
storing, 2-6
string assignment, 2-5
undefined, 2-11
use in expressions, 3-4
Symbol assignment, 2-4
Symbol names, 2-2
abbreviating, 2-2
case conversion, 2-2
characters, 2-2
length, 2-2
restrictions, 2-2
Symbol substitution, 2-8
automatic evaluation, 2-10
command synonyms, 2-8
iterative substitution, 2-10

Index-4

(- ,

Symbol substitution (Cont.)
overriding with an
underscore( ), 2-8
using apostrophes in, 2-9
verifying, 2-11
Symbol tables, 2-6
Symbol types, 2-4
determining, 4-40
expressions, 2-4
integer, 2-4
string, 2-4
Symbol values
methods for assigning, 2-3
prompting, 5-4

Terminal logging (Cont.)
OPEN/LOG_FILE, 9-4
SET/LOG_FILE, 9-6
THEN keyword, 7-1

-uUndefined symbols, 2-11, 4-40

-vVAX/VMS and RSTS/E command
processor differences, B-1
Verification status, 4-42
Verifying symbol substitution,
2-11

-T-W-

Terminal logging, 9-3 to 9-7
CLOSE/LOG_FILE, 9-6

WRITE command, 6-8

Index-5

HOW TO ORDER ADDITIONAL DOCUMENTATION
DIRECT TELEPHONE ORDERS
In Continental USA
and Puerto Rico
call 800-258-1710

In Canada
call 800-267-6146

In New Hampshire,
Alaska or Hawaii
cali 603-884-6660

DIRECT MAil ORDERS (U.S. and 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, Canada K1G 4C2
Attn: A&SG Business Manager

INTERNATIONAL
DIGITAL EQUIPMENT CORPORATION
A&SG Business Manager
c/o Digital's local subsidiary
or approved distributor

Internal orders should be placed through the Software Distribution Center (SDC), Digital
Equipment Corporation, Northboro, Massachusetts 01532
•Any prepaid order from Puerto Rico must be placed
with the Local Digital Subsidiary:

809-754-7575

RSTS/E
Guide to Writing Command Procedures
M-CF03A-TC

Reader's Comments
Note: This form is for document comments only. DIGITAL will use comments submitted on this form at
the company's discretion. If you require a written reply and are eligible to receive one under
Software Performance Report (SPR) service, submit your comments on an SPR form.
Did you find this manual understandable, usable, and well-organized? Please make suggestions for
improvement. _________________________________________________________________

Did you find errors in this manual? If so, specify the error and the page number. _ _ _ _ _ _ _ __

Please indicate the type of user/reader that you most nearly represent.

o
o
o
o
o
o
Name

Assembly language programmer
Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
Other (please specify) _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
Date _______________________________

Organization __________________________________________________________________
Street _______________________________________________________________________
Code _ _ _ __
City _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ State _ _ _ _ _ Zipor
Country

i
I
I
I
I
- - - - - - - D o Not Tear - Fold Here and Tape ------------------------------~------I
I

IIIIII

No Postage
Necessary

if Mailed in the
United States

!
I
I
I
I
I
I

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

!
I
I
I
I
I
I
I

ATIN: Office Systems Publications MK01-2/E02
RSTS/E Documentation
DIGITAL EQUIPMENT CORPORATION
CONTINENTAL BOULEVARD
MERRIMACK, N.H. 03054
i
I
I
I
I
I
!
I
- - - - - - - Do Not Tear - Fold Here and Tape - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ~ ~ ~ - -,
!
I
!
I
I

I
I
I
I
i
I il.l
I .5

I,..;)
1'e1

12
...,
I 0

1'QiJ
, s::
i

1<
I"'"

18
i
I
I
I
I
i
I
i
I
I
!

Printed in U.S.A.