Digital PDFs

AA-L335A-TK

February 1984

270 pages

Original

10MB

Document:	VAX BASIC PDP-11 BASIC-PLUS-2 V2 Users Guide 198402
Order Number:	AA-L335A-TK
Revision:	0
Pages:	270
Original Filename:	AA-L335A-TK_VAX_BASIC_PDP-11_BASIC-PLUS-2_V2_Users_Guide_198402.pdf

OCR Text

BASIC
User's Guide
Order No. AA-L335A-TK
Including AD-L335A-T1

February 1984
This manual describes the use of BASIC-PLUS--2 on PDP-ll systems and
VAX BASIC on VAX/VMS systems.

OPERATING SYSTEM AND VERSION:

SOFTWARE VERSION:

VAX/VMS
RSTS/E
RSX/ll M
RSX-ll M-PLUS

.V3
VB
V4

VAX BASIC
V2
PDP-ll BASIC-PLUS--2 V2

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:

mDmDomo ™
DEC
DECmate
DECsystem-10
DECSYSTEM-20
DECUS

DECwriter
DIBOL
MASSBUS
PDP

P/OS
Professional
Rainbow

RSTS
RSX
UNIBUS
VAX
VMS
VT
Work Processor

Commercial Engineering Publications typeset this manual using DIGITAL's TMS-11 Text
Management System.

Contents
Page

To the Reader
Chapter 1 Elements of a BASIC Program
1.1
1.2
1.3
1.4

Line Numbers and Alphanumeric Labels
BASIC Character Set. .
Keywords . . . . . . . .
Program Documentation .
REM Statements.
Comment Fields.

· 1-5
.1-6

Constants . . . . . . . .

· 1-6

1.5.1
1.5.2
1.5.3
1.5.4

.1-6
· 1-7
· 1-8
· 1-9

1.4.1
1.4.2
1.5

1.6

1.7

· 1-1
· 1-3
.1-4
· 1-5

Floating-point Constants
Integer Constants . .
String Constants. . .
Predefi ned Constants.

Variables . . . . . . . . . .

1-10

1.6.1
1.6.2
1.6.3
1.6.4
1.6.5

1-10
1-11
1-11
1-12
1-12

Floating-point Variables
Integer Variables . .
String Variables. . . .
Subscripted Variables .
Initialization of Variables.

Expressions. . . . . . . . .

1-13

1.7.1
1.7.2
1.7.3

Numeric Expressions.
String Expressions. .
Conditional Expressions

1-13
1-14
1-14

1.7.3.1
1.7.3.2

1-15
1-16

1.7.4
1.7.5

Numeric Relational Expressions
String Relational Expressions

Logical Expressions . .
Evaluating Expressions. . . . . . . .

1-17
1-19

Chapter 2 Simple Input and Output
2.1

Program Input. . . . .

.2-1

2.1.1

Providing Input Interactively

.2-1

2.1.1.1
2.1.1.2

.2-1
.2-3

2.1.2

I N PUT Statement
IN PUT LI N E and LI N PUT Statements .

Providing Input from the Source Program.

.2-4

2. 1 .2.1
2.1.2.2
2.1.2.3

.2-4
.2-5
.2-6

READ Statement. .
DATA Statement . .
RESTORE Statement

;;i

2.2

2.3

Program Output. . . . . . . . . . . . . . . .

.2-7

2.2.1
2.2.2

.2-8
2-10

Terminal-Format Files
2.3.1
2.3.2

Chapter 3

Opening and Closing a Terminal-Format File
Writing Records to a Terminal-Format File

Loops
3.1.1
3.1.2
3.1.3
3.1.4
3.1.5

3.2
3.3

3.4

3.5

2-11

2-12
2-12

FOR-NEXT Loops.
WHILE-NEXT Loops.
UNTIL-NEXT Loops.
Nested Loops .
Explicit Loop Control (ITERATE and EXIT Statements).

.3-2
.3-5
.3-6
.3-7
.3-8
.3-9
3-10

3.3.1
3.3.2
3.3.3

3-10
3-12
3-14

ON-COTO-OTHERWISE Statement.
IF-THEN-ELSE and END IF Statements.
SELECT-CASE Statement .

Executing Local Subroutines.

3-17

3.4.1
3.4.2

3-17
3-18

COSUB and RETURN Statements .
ON-COSUB-OTHERWISE Statement

Suspending and Halting Program Execution.

3-19

SLEEP Statement.
WAIT Statement.
STOP Statement.
END Statement .

3-21

Executing Statements Conditionally

3-21

IF Modifier.
UNLESS Modifier
FOR Modifier.
WHILE Modifier.
UNTIL Modifier.
Nested Modifiers

3-22
3-22
3-22
3-23
3-23
3-24

Using Dynamic Strings. . . . . .
Using Fixed-Length Strings . . . .
Assigning and Justifying String Data
LET Statement. . . . .

.4-2
.4-3

LSET Statement
RSET . . . . .

.4-5
.4-5

3.5.3
3.5.4
3.6

.3-1

Branching Unconditionally (COTO Statement).
Branching Conditionally

3.5.1
3.5.2

3.6.1
3.6.2
3.6.3
3.6.4
3.6.5
3.6.6

3-19
3-20

3-20

Strings
4.1
4.2
4.3
4.4

4.4.1
4.4.2

. . . . . . . . . . . . .

Program Control
3.1

Chapter 4

Print Zones - The Comma and Semicolon
Output Format for Numbers and Strings .

.4-4
.4-4

4.5

4.6
4.7
4.8

Chapter 5

Manipulating String Data with String Functions

.4-6

4.5.1
4.5.2
4.5.3
4.5.4
4.5.5
4.5.6
4.5.7
4.5.8
4.5.9
4.5.10

.4-7
.4-7
.4-9
4-11
4-12
4-13
4-13
4-14
4-14
4-15

Manipulating String Data with Multiple MAPs.
Manipulating Strings with the CHANGE Statement.
String Virtual Arrays

4-16
4-18
4-19

Data Definition
5.1
5.2
5.3
5.4
5.5

5.6
5.7

Declarative Statements. . . . . . . .
Data Types . . . . . . . . . . . . .
Setting the Default Data Type and Size.
Explicitly Declaring Variables (DECLARE Statement)
Explicitly Named Constants. . . . . . . . . . .

. 5-1
.5-1
.5-3
.5-5
.5-7

5.5.1
5.5.2
5.5.3

.5-7
,5-8
.5-8

5.8

Declaring Constants Within a Program Unit.
Declaring Constants External to the Program Unit
Explicitly Formed Literals. . .

Operations Using Multiple Data Types.
Allocating Static Storage . . .

5-11
5-13

5.7.1
5.7.2

COMMON Statement .
MAP Statement . . . .

5-14
5-15

5.7.2.1
5.7.2.2

5-16
5-17

Single MAPs
Multiple MAPs

J.t .J

FILL Items . . . . . . .

5-18

5.7.4

Using COMMON and MAP in Subprograms

5-19

Chapter 6

Finding a String's Length (LEN Function)
Position Functions (pOS and INSTR) .
SEG$ Function
MID$ Function .
LEFT$ Function .
RIGHT$ Function
STRING$ Function
SPACE$ Function
TRM$ .
EDIT$ .

Dynamic Mapping.

5-20

Functions
6.1

BASIC Built-in Functions

.6-1

6.1.1

Using Numeric Functions.

.6-2

6.1.1.1
ABS Function .
6.1.1.2
SGN Function.
INT and FIX Functions
6.1.1.3
6.1.1.4
SIN, COS, and TAN Functions.
LOG 10 Function.
6.1.1.5
6.1.1.6
LOG Function.
6.1.1.7
EXP Function .
6.1.1.8
ATN Function.
6.1.1.9
RND Function.
6.1.1.10 SQR Function.

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

6.2

Using Data Conversion Functions
6.2.1
6.2.2
6.2.3
6.2.4

ASCII Function
CHR$ Function .
XLA TE Function.
Using Numeric String Functions.
6.2.4.1
6.2.4.2
6.2.4.3
6.2.4.4

6.2.5

6.2.6

6.2.5.1
6.2.5.2
6.2.5.3
6.2.5.4
6.2.5.5

6-15
6-16
6-16
6-16
6-16

6.4

Using Date and Time Functions.

Using Terminal Control Functions.
CTRLC and RCTRLC Functions
ECHO and NOECHO Functions.
TAS Function

6-17
6-17
6-18
6-18
6-19
6-19
6-20
6-20
6-21

Single-Line DEFs
Multi-Line DEFs .

6-21
6-23
6-26

FUNCTION, EXIT FUNCTION, and END FUNCTION Statements
EXTERNAL Statement . . . . . . . . . . . . . . . . . . .

6-26
6-27

Arrays
7.1

Creating Arrays Explicitly. . . . . . . . . . . . . .

. 7-1

7.1.1
7.1.2

Creating Arrays with the DECLARE Statement.
Creating Arrays with the DIM Statement

.7-2
.7-3

Declarative DIM Statements. . . .
Executable DIM Statements . . . .

.7-4
.7-4

Creating Arrays with the COMMON Statement
Creating Arrays with the MAP Statement

.7-5
.7-6

7.1.2.1
7.1.2.2
7.1.3
7.1.4
7.2
7.3

Creating Arrays Implicitly. . . . . . . . .
MA T Statements. . . . . . . . . . . . .

.7-6

Assigning Values to Array Elements

.7-9

7.3.1.1
7.3.1.2
7.3.1.3

.7-9
.7-9
7-11

7.3.1

DATE$ Function.
TIME$ Function .
TIME Function.

External Functions.
6.4.1
6.4.2

Chapter 7

PLACE$ Function
SUM$ Function
DIF$ Function.
PROD$ Function
QUO$ Function .

The DEF Statement.
6.3.1
6.3.2

6-10
6-11
6-12
6-12
6-13

6.2.7.1
6.2.7.2
6.2.7.3
6.3

.6-9
.6-9
.6-9
6-10

Using String Arithmetic Functions

6.2.6.1
6.2.6.2
6.2.6.3
6.2.7

FORMAT$ Function
NUM$ and NUM1 $ Functions.
STR$ Function.
VAL % and VAL Functions.

.6-8

Assigning Values with the LET Statement
Assigning Values with the MAT Statement.
Assigning Values with the MAT READ Statement.

.7-7

7.3.2

7.3.3

Assigning Values from the Terminal

7-11

7.3.2.1
7.3.2.2

MATIN PUT Statement .
MAT LlNPUT Statement

7-12
7-13

Assigning Values from Terminal-Format Files

7-13

7.3.3.1
7.3.3.2
7.4

7.5

7-14
7-14

Array Output .

7-14

7.4.1
7.4.2
7.4.3
7.4.4

7-15
7-15
7-16
7-16

PRI NT Statement
MAT PRI NT Statement .
MAT PRI NT # Statement.
Matrix I/O Functions (NUM and NUM2) .

Matrix Operators

7-17

7.5.1

Arithmetic Matrix Operations .

7-17

7.5.1.1
7.5.1.2
7.5.1.3

7-17
7-18
7-18

7.5.2

Chapter 8

MAT INPUT # Statement.
MAT LI N PUT # Statement

Assignment.
Addition and Subtraction
Multiplication.

Matrix Functions

7-19

7.5.2.1
7.5.2.2
7.5.2.3

7-19
7-20
7-20

TRN Function.
INV Function
DET Function .

Formatting Output with the PRINT USING Statement
8.1

PRINT USING.
8.1.1
8.1.2

8.2

.8-2
.8-3

.8-4
0
A
• u-"T

Specifying the Number of DigiiS.
Specifying Decimal Point Location.
Printing Numbers with Special Symbols

.8-5
.8-6

8.2.3.1
8.2.3.2
8.2.3.3
8.2.3.4
8.2.3.5
8.2.3.6
8.2.3.7
8.2.3.8

.8-7
.8-7
.8-8
.8-8
.8-9
.8-9
8-10
8-10

Commas
Asterisk Fill Fields
Currency Symbols
Negative Fields
E (Exponential) Format
Leading Zeros.
Blank-If-Zero Fields
Debits and Credits.

Printing Strings

8-10

Left-Justified Format .
Right-Justified Format
Centered Fields .
Extended Fields .

8-11
8-12
8-12
8-13

PRINT USING Statement Error Conditions.

8-13

8.3.1
8.3.2
8.3.3
8.3.4
8.4

Creating a Format String .
Reusi ng the Format Stri ng

Printing Numbers
8.2.1
8.2.2
8.2.3

8.3

.8-2

vii

Chapter 9

RMS Files
9.1
9.2
9.3
9.4
9.5

9.6

Record Formats
File Organizations.
Record Access and Record Context
1/0 and Record Buffers.
Opening Files (OPEN Statement).

.9-1
.9-2
.9-3
.9-6
.9-6

9.5.1
9.5.2
9.5.3
9.5.4
9.5.5
9.5.6

.9-8
.9-9
.9-9
9-11
9-11
9-11

Record Operations.

9-12

9.6.1
9.6.2

Locating Records (FIND Statement)
Reading Records (GET Statement) .

9-13
9-15

9.6.2.1
9.6.2.2
9.6.2.3
9.6.2.4
9.6.2.5

9-15
9-16
9-17
9-20
9-21

9.6.3

9.6.4
9.6.5

9.6.6
9.7
9.8
9.9
9.10

9.11

viii

Opening Sequential Files.
Opening Relative Files.
Opening Indexed Files.
Opening Block 1/0 Files.
Opening Terminal-Format Files
Opening Undefined Files.

Reading Records from Sequential Files
Reading Records from Relative Files
Reading Records from Block 1/0 Files
Reading Records from Indexed Files
Accessing Records by Record File Address

Writing Records (PUT Statement)

9-23

9.6.3.1
9.6.3.2
9.6.3.3
9.6.3.4

9-24
9-24
9-25
9-25

Writing Records to Sequential Files.
Writing Records to Relative Files.
Writing Records to Block 1/0 Files.
Writing Records to Indexed Files.

Deleting Records (DELETE Statement)
Updating Records (UPDATE Statement).

9-25
9-26

9.6.5.1
9.6.5.2
9.6.5.3

9-26
9-27
9-28

Updating Records in Sequential Files.
Updating Records in Relative Files.
Updating Records in Indexed Files.

Restoring Files

9-28

Truncating a File (SCRATCH Statement).
Unlocking Records (FREE and UNLOCK Statements)
Virtual Array Files .
File Operations

9-29
9-29
9-30
9-30

9.10.1
9.10.2
9.10.3

9-30
9-31
9-31

Renaming Files .
Closing Files and Ending 1/0 .
Deleting Files.

File-Related Functions

9-32

9.11.1
9.11.2
9.11.3
9.11.4

9-32
9-32
9-33
9-33

CCPOS
RECOUNT.
STATUS
MAR% (VAX-ll BASIC Only).

9.12

OPTIMIZING 1/0 . . .
9.12.1
9.12.2
9.12.3
9.12.4
9.12.5
9.12.6
9.12.7
9.12.8
9.12.9
9.12.10
9.12.11
9.12.12

Chapter 10

9-33
9-37
9-37
9-37
9-37
9-38
9-38
9-39
9-39
9-40
9-40
9-44

Compiler Directives
10.1

10.2
10.3

Controlling the Compilation Listing

10-2

10.1.1
10.1.2
10.1.3
10.1.4
10.1.5

%TITLE and %SBTTL
%IDENT . . . . . .
%PAGE . . . . . .
%LlST and %NOLIST
%CROSS and %NOCROSS .

10-2
10-3
10-4
10-4
10-5

Accessing External Source Files (%INCLUDE)
Controlling Compilation . . . . . . . . .

10-6
10-7

10.3.1
10.3.2
10.3.3
10.3.4

Chapter 11

BUCKETSIZE .
TEMPORARY.
FILESIZE . . .
NOSPAN . . .
CONTIGUOUS.
EXTENDSIZE .
CONNECT . .
WINDOWSIZE
BUFFER . . .
RECORDTYPE
USEROPEN . .
DEFAULTNAME.

9-33

Lexical Constants and Expressions (%LET)
%VARIANT . . . . . . . . . . .
%ABORT . . . . . . . . . . . .
%IF-% THEN-%ELSE-%END-%IF .

10-8
10-8
10-9
10-9

Handling Run-Time Errors
11 . 1
11.2
11.3

Errors . . . . . . . . . .
Error Handlers. . . . . . .
User-Written Error Hand!ers.
11.3.1
11.3.2
11.3.3
11.3.4
11.3.5

11.4
11.5
11.6
11.7
11.8
11.9

Transferring Control to an Error Handler (ON ERROR Statement).
Determining the Error Number (ERR). . . . .
Determining the Error Line Number (ERL). . .
Determining Where the Error Occurred (ERN$)
Determining the Error Message Text (ERT$) .

Returning to BASIC Error Handling. . . . . . . . . .
Leaving an Error Handler. . . . . . . . . . . . . .
Handling Errors in Subprograms and Function Definitions.
CTRL IC Trapping . . . . .
The BASIC Error Handler. .
Handling Non-BASIC Errors

11-1
11-1
11-2
11-3
11-4
11-4
11-6
11-6
11-6
11-7
.11-11
.11-13
.11-15
.11-17

Appendix A Reserved BASIC Keywords
Appendix B Program and Subprogram Coding Conventions

Index
Figures
5-1
5-2
11-1
11-2
11-3
11-4
11-5

Mixed-mode Expression Results
Multiple MAPs . . . . . . .
Error Handling Conditions . .
VAX-11 BASIC Error Handling Output.
BASIC-PLUS-2 Error Handling Output.
VAX-11 BASIC Environment Error Handling Output
BASIC-PLUS-2 Environment Error Handling Output

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

Keyword Space Requirements.
Numbers in E Notation.
Predefi ned Constants.
Arithmetic Operators.
Numeric Relational Operators.
String Relational Operators
Logical Operators .
Truth Tables
Numeric Operator Precedence
String Modification.
BASIC Data Types .
Result Data Types in BASIC Expressions
FILL Item Formats, Representations, and Default Allocations.
String Arithmetic Functions .
Precision of String Arithmetic Functions.
MAT Statements.
MAT Statement Keywords.
Format Characters for Numeric Fields
Format Characters for String Fields.
I /0 Statements and Record Context
Relative File Default Bucket Size.
Indexed File Default Bucket Size.
BUFFER Values and Allocations in VAX-ll BASIC.
VAX-11 RMS Control Structures Set by USEROPEN

· 5-13
· 5-17
· 11-12
· 11-15
.11-16
.11-16
.11-17

Tables

.1-4
. 1-7
. 1-9
1-13
1-16
1-17
1-17
1-18
1-20
.4-2
.5-2
5-11
5-18
6-13
6-14
.7-8
7-10

.8--6
8--11
.9-5
9-35
9-36
9-40
9-41

To the Reader
This manual is part of the BASIC documentation set. This set of manuals was designed to let you learn
and use BASIC regardless of your prior experience with computers. The documentation set includes:
For the beginner:
• Introduction to BASIC
• BASIC for Beginners
• More BASIC for Beginners

For all systems:
• BASIC User's Guide
• BASIC Reference Manual
• BASIC Pocket Reference Guide

For specific systems:
• BASIC on RSTSIE Systems
• BASIC on RSX-ll M I M-PLUS Systems
• BASIC on VAX/VMS Systems

For the system manager:
• BASIC-PLUS-2 RSTS/E Installation Guide and Release Notes

e BASIC-PLUS-2 RSX-l LV. ft'v1-PLUS Installation Guide and Release /'-fotes
• VAX-II BASIC Installation Guide and Release Notes

For the beginner, Introduction to BASIC explains the fundamentals of the BASIC language and shows
how to use BASIC to solve programming problems. BASIC for Beginners and More BASIC for
Beginners lead the reader step-by-step through planning and writing several practical programs that
teach BASIC programming techniques. In addition, the first chapter of the system-specific user's guide
tells you how to log on to your computer system, create and execute programs, and do simple file
operations such as printing, typing, and deleting files.
For programmers who are more familiar with BASIC, the BASIC User's Guide and the system-specific
user's guides include a complete explanation of BASIC and how to use it on your system. If you need
information on a particular feature or statement, the BASIC Reference Manual describes the format of
each BASIC command or keyword individually.
The BASIC documentation set has several new features that let you find information quickly and
easily. Each manual has its own index (with instructions on its use) and the BASIC Reference Manual
has a master index to the entire documentation set. For quick reference the BASIC Pocket Reference
Guide provides a brief explanation of all BASIC commands and functions. Similar information is also
available at the computer terminal from the BASIC HELP facility.

The following pages describe the function of this particular manual. We welcome your comments
and encourage you to use the Reader's Comments Form provided at the back of this book.

Document Objectives
This manual describes the features and use of the BASIC language on VAX /VMS, RSTS / E, and
RSX-based systems. It is intended to be used with the BASIC Reference Manual, BASIC on VAX/VMS
Systems, BASIC on RSTS/E Systems, and BASIC on RSX-ll M / M-PLUS Systems.

Intended Audience
This manual is intended for programmers familiar with computer concepts and the BASIC language.

Document Structure
This manual has eleven chapters and two appendixes.
Chapter 1

Describes BASIC language elements and writing BASIC programs.

Chapter 2

Describes simple BASIC input and output.

Chapter 3

Describes ways to control the execution of BASIC programs.

Chapter 4

Describes strings and how to modify them.

Chapter 5

Describes how to define data with declarative statements.

Chapter 6

Describes BASIC library functions and user-defined functions.

Chapter 7

Explains how to create and use arrays.

Chapter 8

Explains how to format program output with the PRINT USING statement.

Chapter 9

Describes file I/O.

Chapter 10

Explains how to use compiler directives.

Chapter 11

Explains how to handle errors.

Appendix A

Lists the BASIC reserved keywords.

Appendix B

Contains a programming template.

Conventions
Formats present the correct syntax for writing BASIC source code. You must order syntax elements as
shown in the format unless the syntax rules indicate otherwise.
Syntax formats consist of BASIC keywords, metalanguage mnemonics, and punctuation symbols.
Metalanguage mnemonics are symbolic derivations of BASIC objects or structures.

Note
BASIC keywords are always capitalized in this manual and must be spelled exactly as
shown. Mnemonics are in lowercase letters in formats and are italicized in the syntax
and general rules.

xii

Some metalanguage mnemonics are derived directly from BASIC keywords. For example:
• MAP (m~p)
• COMMON (com)
• FUNCTION (func)
• DEF (def)
• SUB (sub)

Others are abbreviated forms of words. For example:
• Variable (vb!)
• Unsubscripted (unsubs)
• Subscripted (subs)
• String (str)
• Constant (const)
• Expression (exp)
• Name (nam)
• Conditional (cond)
• Integer (int)
• Fi Ie-specification (fi Ie-spec)
• Data-type (data-type)
Most mnemonics used in formats are combinations of mnemonics:
• Const-nam

Is a constant name.

• Sub-nam

Is the name of a SUB subprogram.

• Unsubs-vbl

Is an unsubscripted variable.

• Int-exp

Is an integer expression.

• Cond-exp

Is a conditional expression.

• Str-unsubs-vbl

Is a string unsubscripted variable.

Mnemonics are combined in this way to indicate exactly what type of object or structure BASIC
expects. Some BASIC statements, for example, allow you to specify any type of variable (string or
numeric) in the format, while others allow only a numeric variable (integer or floating-point), a string
variable, an integer variable, or a floating-point variable.
Thus, the uncombined form of the variable mnemonic (vbl) in a format means that you can use any
type of variable (string or numeric). A combined variable mnemonic (such as str-vbl, num-vbl, or
int-vbl) in a format means that you can specify only a particular type of variable.

xii i

Within formats, mnemonics are either simple or complex. Simple mnemonics identify a format
element (such as an expression, a variable, or a name) that needs no further definition. For example:
EXTERNAL data-type CONSTANT const-nam, ...

The mnemonics in this format need no further definition. The EXTERNAL keyword must be followed
by a data-type, the CONSTANT keyword, and then a const-nam. The comma and eliipsis, as defined
in the Punctuation Symbols Table, indicate that you can specify more than one const-nam. The
data-type mnemonic is defined in the Mnemonics Table as a BASIC data-type keyword, and
const-nam is defined as a constant name. Restrictions to the use of data-type keywords in the
EXTERNAL statement are specified in the syntax rules.
Complex mnemonics identify a format element (such as a parameter passing mechanism or a statement clause) that has more than one component. Complex mnemonics are further defined in the
lower portion of the format box by simple mnemonics. For example:
DECLARE data-type decl-item [, [data-type] decl-item ], ...

When you look at this format, you can see that a data-type keyword must follow the' DECLARE
statement and that a dec/-item must follow the data-type keyword. Dec/-item is a complex mnemonic
that is further defined in the lower portion of the box, like this:
decl-item:

f unsubs-vbl-nam
l
l array-nam ( int-const, ... ) f

From this portion of the format, you can see that the data-type keyword must be followed by an array
name or a simple variable name. The portion of the format in brackets indicates that you can specify
another data-type keyword and another array name or simple variable name. The comma and ellipsis
(. .. ) indicate that you can continue adding data-type keywords and array names or simple variable
names.
This type of format unfolds the syntax of BASIC language elements and indicates the type of element
BASIC expects to receive. In most cases, BASIC signals an error if the element does not exactly match
the indicated format. In other instances, particularly with numeric elements, BASIC converts the
numeric element you specify to the type of numeric element it expects to receive. These instances are
noted in the syntax rules.
Multiple occurrences of mnemonics in a format are numbered to prevent confusion. Vb13, for example, is the third unique variable in a general format and is referred to as vbl3 in the syntax and general
rules.
The most frequently used punctuation symbols and metalanguage mnemonics are listed and
described in the following two tables. Less frequently used mnemonics and most complex mnemonics are defined as they occur in syntax formats.

XIV

Syntax Mnemonics

Mnemonic

Definition

exp

An expression

vbl

A variable

unsubs

Unsubscripted; used with the variable mnemonic to indicate a simple variable, as opposed to an array
element

subs

Subscripted; used with the variable mnemonic to indicate an array element; the element's position in the
array is specified by subscripts enclosed in parentheses and separated by commas

array

An array; syntax formats indicate whether you can specify bounds and dimensions, or just dimensions

const

A constant value

lit

A literal value, in quotation marks; a literal is always a constant, but a constant may be named, so
constants are not always literals

num

A numeric value

real

A floating-point value

int

An integer value

str

A character stri ng

cond

Conditional; used with the expression mnemonic to indicate that an expression can be either logical or
relational

log

Logical; used with the expression mnemonic to indicate a logical expression

rei

Relational; used with the expression mnemonic to indicate a relational expression

lex

Lexical; used to indicate a component of a compiler directive

target

The target point of a branch statement; used to indicate that the target point can be either a program line
number or a statement label

lin-num

A program line number

item

Allowable BASIC objects, such as variables, data types, and parameters; allowable objects are defined in
formats as they occur

nam

Name; indicates the declaration of a name or the name of a BASIC structure, such as a SUB subprogram

com

Specific to a COMMON

def

Specific to a DEF

func

Specific to a FUNCTION subprogram

map

Specific to a MAP

sub

Specific to a SUB subprogram

chnl

An I/O channel associated with a file

data-type

A data-type keyword; Table 5-1 in this manual lists and describes BASIC data-type keywords

fi Ie-spec

A fi Ie-specification

file-nam

A file name

Punctuation Symbols

Symbols

Definition

[ 1

Brackets enclose an optional portion of a format. Brackets around vertically stacked entries indicate that
you can select one of the enclosed elements. You must include all punctuation as it appears in the
brackets.

{ }

Braces enclose a mandatory portion of a general format. Braces around vertically stacked entries indicate
that you must choose one of the enclosed elements. Braces also group portions of a format as a unit. You
must include all punctuation as it appears in the braces.
An ellipsis indicates that the immediately preceding language element can be repeated. An ellipsis following a format unit enclosed in brackets or braces means that you can repeat the entire unit. If repeated
elements or format units must be separated by commas, the ellipsis is preceded by a comma C... ).

Definitions
In this manual, the following definitions apply:
BASIC

The term BASIC refers to Version 2 of both VAX-II BASIC and PDP-II
BASIC-PLUS-2.

BASIC-PLUS-2

The term BASIC-PLUS-2 refers to Version 2 of PDP-II BASIC-PLUS-2 as implemented on RSTS/E, RSX-l1 M, and RSX-l1 M-PLUS systems.

Cannot

Cannot indicates that an operation cannot be performed and that an attempt to
perform the operation causes BASIC to signal an error.

Cursor
or
Cursor position

Cursor or cursor position refers to a terminal's print mechanism. It can be the
flashing cursor on a video display terminal or the print head on a hard-copy
terminal.

Must

Must indicates that an operation must be performed and that failure to perform the
specified operation causes BASIC to signal an error.

Program module

A program module is a BASIC main program, a SUB subprogram, or a FUNCTION
subprogram.

Subprogram

A subprogram is a separately compiled program module that must be linked or
task-built with the main program.

Subroutine

A subroutine is a block of code accessed by a COSUB or ON COSUB statement.
It is always in the same program module as the statement that accesses it.

VAX-11 BASIC

The term VAX-II BASIC refers specifically to Version 2 of VAX-II BASIC as
implemented on VAX/VMS systems.

Please use the Reader's Comments Form in the back of this book to report errors or to make suggestions for future documentation releases.

XVI

Chapter 1
Elements of a BASIC Program

This chapter describes the elements that make up a BASIC program.

1.1 Line Numbers and Alphanumeric Labels
A BASIC program is a series of instructions for the BASIC compiler. These instructions are in the form
of BASIC statements. BASIC programs require at least one line number at the first statement of the
program.
BASIC uses line numbers to:
• Indicate the order of statement execution
• Provide control points for branching
• Help in debugging and updating programs
• Find the location of run-time errors and to resume processing after an error has been handled
Therefore, each line number must be unique. BASIC ignores leading spaces, tabs, and zeros in line
numbers. Embedded spaces, tabs, and commas are invalid.
The first line in a BASIC program must begin with a line number. The program lines that may follow
contain:
• Line numbers
• Statements (optionally preceded with alphanumeric labels)
• Comment fields
• Line terminators (carriage return)
A program line can contain any number of text lines; however, a text line cannot exceed 255
characters in VAX-II BASIC and BASIC-PLUS-2 on RSTS / E systems, or 132 characters in
BASIC-PLUS-2 on RSX-II M / M-PLUS systems.

February 1984

1-1

Program lines contain the BASIC keywords, operators, and operands that make up a BASIC program.

If the line you type in response to the prompt starts with a number in the first column, BASIC treats it
as a program line - that is, as part of the current source program. BASIC stores this text in ascending
line-number order, and if the line you type has the same number as an existing line, the new line
replaces the old one.
If a program line is too long for one line of text, you can continue the line by typing an ampersand (&)
as the last character before the carriage return (~).
Several statements can be associated with a single line number. If these statements are on one line,
they must be separated by backslashes (\). For example:

400 PRINT A \ PRINT V \ PRINT G
Because all statements are on the same program line, any reference to this line number refers to all
three statements. In the preceding example, BASIC cannot execute just one of the statements without
executing the other two.
You can extend a multi-statement program line onto several lines by ending each continued line with
an ampersand (&) and beginning each continuation line with a backslash. For example:

400

PRINT A &
\ PRINT V &
\ PRINT G

However, programs written in this format tend to be cluttered and hard to read: BASIC now allows
you to identify a continued line by placing a space or tab at the beginning of each continuation line.
BASIC assumes such a line is a continuation of the preceding line, and, unless it is part of an
IF-THEN-ELSE statement, assumes it begins a new statement. For example:

400

PRINT A
PRINT V
PRINT G

A single statement that spans several text lines still requires an ampersand at the end of each continued line. For example:
100

OPEN "SAMPLE.DAT" AT FILE #2%,
SEQUENTIAL VARIABLE,
RECORDSIZE 80%

&
&

The ampersand must come immediately before the carriage return.
The IF-THEN-ELSE construction requires that BASIC interpret this new format somewhat differently.
If a continuation line begins with THEN or ELSE, no statement separator is assumed. Similarly, in a
line following a THEN or ELSE, there is no implied statement separator. For example:
100

1-2

IF (A$ = "YES") OR (A$ = "Y" )
THEN
PRINT "The IJS e r g a \.1 e a positi\.le response"
ELSE
PRINT "The IJS e r gave a negati\.Ie response"
END IF

Elements of a BASIC Program

Because a leading space or tab implies a continuation line, compiler commands and immediate
mode statements must begin in column one with no leading spaces or tabs. If you enter a compiler
command or immediate mode statement, no further continuation lines can be added to that program
line.
Note
You can continue any BASIC statement. However, a statement following a REM or
DATA statement must have a new line number. This is because all text between the
keyword REM and the next line number is ignored. Similarly, all text between the
keyword DATA and the next line number is treated as data.
The EDIT command treats the new format continuation lines as normal continuation lines. Thus, you
can edit these continuation lines by using the sub-line clause of the EDIT command.
A label is a 1- to 31-character identifier used to logically identify a statement or block of statements.
You can reference a label anywhere you can reference a line number, with two exceptions: 1) you
cannot compare the ERL variable (the line on which the last error occurred) with a label, and 2) you
cannot use a label as the argument to the RESUME statement. A label cannot begin in the first
character position on a line; only line numbers and immediate mode statements can begin in the first
column.
When used to define a block of statements, the label must end with a colon. However, when you use
a label to refer to a block of statements (for example, in a GOSUB or GOTO statement), you do not
specify a colon. For example:
100

RANDOMIZE
NUMBER% = INT(S%

* RND) + 1%

AsK:
INPUT IIA nUfTlber between 1 and
GOTO Win IF A% = NUMBER%
PRINT IITr}' againll
GO TO AsK

10 please ll ;

Ai..

Win:
PRINT
END

lIyOU WIN!!! II

Note that the labels themselves end with a colon, but the references to them do not. Any BASIC
statement can be preceded by one or more labels.

1.2 BASIC Character Set
BASIC uses the full ASCII character set. This includes:
• The letters A through Z, in both upper- and lowercase
• The digits 0 through 9
• Special characters
Appendix C of BASIC on VAX/VMS Systems, BASIC on RSX-IIM/M-PLUS Systems, and BASIC on
RSTS / E Systems contains the full ASCII character set and character values.

Elements of a BASIC Program

1-3

The compiler:
• Does not distinguish between upper- and lowercase letters (except letters within quotation marks or
within a DATA statement)
• Does not process characters in REMARK statements or comment fields
You can use nonprinting characters in your program, for example, in string constants, but to do so
you must either: 1) use a predefined constant such as ESC and DEL or 2) use the CHR$ function to
specify an ASCII value. See Section 1.5.4 for more information on predefined constants. See Chapter
6 for more information on the CH R$ function.
For user-supplied names, BASIC makes no distinction between upper- and lowercase letters. This
means that MY _ VBL and my_vbl always refer to the same variable.

1.3 Keywords
A keyword is an element of the BASIC language. Keywords are reserved words because the program
uses them to:
• Define data
• Perform operations
• Invoke functions
Therefore, keywords cannot be used as variable names, nor as names for MAP or COMMON areas.
Appendix A contains a list of BASIC reserved words.
Keywords determine whether the statement is executable or nonexecutable:
• Executable statements perform operations (for example, PRINT, GOTO, and READ).
• Nonexecutahle statements describe the characteristics and arrangement of data, usage information,
and comments (for example, DATA, DECLARE, and REM).
Every statement except LET and null statements must begin with a keyword. A BASIC keyword cannot
have embedded spaces or be split across lines of text. There must be a space or tab between the
keyword and any other variables or operators.
Some keywords use two words. In this case, their spacing requirements vary, as shown in Table 1-1.
Table 1-1: Keyword Space Requirements

Optional Space

Mandatory Space

No Space

GO TO
GO SUB
ON ERROR

BY DESC
BY REF
BY VALUE
END DEF
END FUNCTION

FNEND
FNEXIT
FUNCTIONEND
FUNCTIONEXIT
NOECHO

(continued on next page)

1-4

Elements of a BASIC Program

Table 1-1: Keywork Space Requirements (Cont.)

co
vpIiona.I ;,pace

/ylaiiUalory .:)paCe

END GROUP
END IF
END RECORD
END SELECT
END SUB
EXIT DEF
EXIT FUNCTION
EXIT SUB

"-.1
C
1,0
Jpace

NOMARGIN
SUBEND
SUBEXIT

INPUT L!t'-~E
MAT INPUT
MAT LlNPUT
MAT PRINT
MAT READ

1.4 Program Documentation
Documentation clarifies and explains source program structure. In BASIC, there are two ways to
include comments in a program: the REM statement and the comment field.

1.4.1 REM Statements
The REM statement has the format:
REM text

where:
tex1

Is a comment.

REM statements do not affect program execution; BASIC ignores all characters between the keyword
REM and the next line number. Therefore, a REM statement should be either the only statement on a
line, or the last statement on a multi-statement line. For example:

10 REM THIS IS AN EXAMPLE
20

A=S
B=10
REM A EQUALS Sf B EQUALS 10

You can use the line number of a REM statement in a reference from another statement (for example,
GOTO). However, because REM is nonexecutable, BASIC transfers control to the next executable
statement following the referenced line. Because BASIC treats all text between the REM keyword and
the next line number as a comment, DIGITAL recommends using comment fields for program
documentation.

Elements of a BASIC Program

1-5

1.4.2 Comment Fields
A comment field is similar to the REM statement; it does not affect program compilation or execution.
A comment field begins with an exclamation point (!) and ends with a carriage return. For example:
10
20

A = B + C ! This is a test.®m
!Assign values to variables(@')
A
3! A e qua 1 s 3(@')
B
ll!B equals ll(@')
C = 5 ! Ceq u a 1 s 5(@')

The advantage to using comment fields is that you can mix program documentation with executable
statements in the same block of code. Note that comment fields in DATA statements are invalid; the
compiler treats the comments as additional data.
Note
You can also use an exclamation point to terminate a comment field, although this
practice is not recommended. Therefore, you should make sure that there are no
exclamation points in the comment text itself; otherwise, BASIC treats the text remaining on the line as source code.

1.5 Constants
A constant is a quantity with a fixed value.
BASIC constants are:
• Floating-point numbers
• Integers
• Strings (ASCII characters enclosed in quotation marks)
• Packed decimal numbers (VAX-11 BASIC only)
BASIC also supplies predefined constants for ease in representing some ASCII characters and
mathematic values. See Section 1.5.4 for more information on predefined constants. See Chapter 5
for more information on packed decimal numbers.

In addition, BASIC provides a special form of constant called an explicitly formed literal. See Section
5.5.3 for more information on explicitly formed literals.

1.5.1 Floating-point Constants
A floating-point constant is one or more decimal digits, optionally preceded by a plus sign or minus
sign, with an optional decimal point. For example:

6.64

-377
.005

-9.4177

6562

123.84103

-12345
8.0003
25

38
BASIC accepts floating-point constants in the approximate range 1 * 10-38 to 1 * 10 . A floating-point
constant outside this range returns a fatal error message. (VAX-l1 BASIC lets you use floating-point
4932
constants in the range .84 * 10-4932 through .59 * 10 . See Chapter 5 for information about GFLOAT
and HFLOAT numbers.)

1-6

Elements of a BASIC Program

Very large and very small numbers in this range can be represented in E (exponential) notation. This
method of mathematical shorthand uses the format:
± number E ± n

where:

+ or -

Is the number's sign. The plus sign is optional, but the minus sign is mandatory for
negative numbers.

number

Is the number carried to a maximum of: 1) 6 decimal places for SINGLE numbers, 2) 16
decimal places for DOUBLE numbers, 3) 15 decimal places for GFLOAT numbers
(VAX-11 BASIC only), and 4) 33 decimal places for HFLOAT numbers (VAX-11 BASIC
only).

Represents the words "times 10 to the power of."

+ or -

Is the exponent's sign. The plus sign is optional, but the minus sign is mandatory for
negative exponents.

Is an integer constant (the power of 10). It can be 0, but not blank.

Table 1-2 compares numbers in standard and E notation.

Table 1-2: Numbers in E Notation

Standard Notation

E Notation

.0000001
1,000,000
-10,000,000
100,000,000
1,000, 000, 000, 000

.1 E-06
.1 E+ 07
-.1 E+08
.1 E+09
.1E+13

1.5.2 Integer Constants
In BASIC, an integer constant is one or more decimal digits (a whole number) followed by a percent
sign. For example:
29%
3432%
12345%

-8%
1%
205%

Allowable values for integer constants depend on the default data type. See Chapter 5 for more
information.

Note
Unless you change the default data type, BASIC assumes that numeric constants are
floating-point numbers. Thus, BASIC must convert numeric constants when assigning
them to integer variables. This means your program takes slightly longer to compile.
You can prevent this conversion step by using percent signs for integer constants. Note
that you cannot use percent signs in integer constants that appear in DATA statements.
An attempt to do so causes BASIC to signal "Data format error" (ERR = 50).
Elements of a BASIC Program

1-7

1.5.3 String Constants
A string constant, also called a string literal, is a series of ASCII characters enclosed in string delimiters. Valid string delimiters are:
• Double quotation marks ("text")
• Single quotation marks ('text')
You can embed double quotation marks within single quotation marks ('''text''') and vice versa
("'text"'). BASIC does not accept incorrectly paired quotation marks, however. For example, these
are valid strings:
"THE RECORD NUMBER DOES NOT EXIST."
"'The terminating condition has been reached.'"
"Report 543"
These are not:
"QUOTATION MARKS DO NOT MATCH'
"NO DELIMITER
BASIC does not print the delimiting quotation marks when executing the program. For example:
10
20

PRINT
END

"End-of-file

reached"

RUNNH
End-of-file

reached

BASIC prints quotation marks when they are enclosed in a second paired set, either double or single:
10
20

PRINT
END

'Failure condition:

"Record Len9th'"

RUNNH
Failure condition:

"Record Len9th"

Characters in string constants can be letters, numbers, spaces, tabs, or any ASCII character except the
string delimiter, nulls (ASCII code 0) and NAKs (ASCII code 21). BASIC determines the string constant's value by scanning all its characters.
For example, because of the number of spaces between the delimiters and the characters, these two
string constants are not the same:

End-of-fi Ie reached

"End-of-fi Ie reached"

1-8

Elements of a BASIC Program

VVhen processing text between string delimiters, BASIC stoies the following characters exactly as you
type them:
• Lowercase letters
• Leading, trailing, and embedded spaces
• Tabs
• Special characters
However, a string literal cannot contain a null (ASCII code 0) or a NAK (ASCII code 21). If you need
to create a string containing a null, you should use the CHR$ function or an explicitly formed literal
with the concatenation operator. See Chapter 5 for more information about explicitly formed literals.
See Chapter 6 for more information about the CHR$ function.

1.5.4 Predefined Constants
Predefined constants are symbolic representations of either: 1) ASCII characters or 2) mathematic
values. They:
• Format program output to improve clarity
• Make source code easier to understand
• Let you use nonprinting characters without having to look up the ASCII values
Table 1-3 lists the predefined constants, their decimal ASCII values and purposes.

Table 1-3: Predefined Constants

Decimal
ASCII
Constant

Vaiue

Purpose

BEL (Bell)

Sounds the terminal bell

BS (Backspace)

Moves the cursor one position to the left

HT (Horizontal Tab)

Moves the cursor to the next horizontal tab stop

LF (Line Feed)

Moves the cursor to the next line

VT (Vertical Tab)

Moves the cursor to the next vertical tab stop

FF (Form Feed)

Moves the cursor to the start of the next page

CR (Carriage Return)

Moves the cursor to the beginning of the current line

SO (Sh ift Out)

Shifts out for communications networking, screen formatting, and alternate graphics

SI (Shift In)

Shifts in for communications networking, screen formatting, and alternate graphics

ESC (Escape)

Marks the beginning of an escape sequence

SP (Space)

Inserts one blank space in program output

DEL (Delete)

127

Deletes the last character entered

None

Represents the number PI (3.14159 in single precision)

Elements of a BASIC Program

1-9

The effect of these characters depends on the device to which they are sent. For example:
110 PRINT "NAME:"
120 END

" _____ ";

RUNNH

If you run the following program on a hardcopy terminal, BASIC prints "NAME:", backspaces to the
beginning of the line, and prints five underscore"S.
You can also create your own named constants with the DECLARE statement. See Chapter 5 for more
information about DECLARE.

1.6 Variables
A variable is a named quantity whose value can change during program execution. Each variable
name refers to a unique location in the program's storage. Each location can hold only one value at a
time. When using variables for calculations, BASIC always uses the most recently assigned value.
This section describes the use of implicit variables, that is, variables that are not explicitly named in
declarative statements such as DECLARE, MAP, and COMMON. You can use the ITYPE = EXPLICIT
qualifier to specify that all variables in the program must be explicitly declared. For more information
on ITYPE = EXPLICIT and on explicit variables in general, see Chapter 5.
.
BASIC accepts these general types of variables:
• Floating-point
• integer
• String
• RFA
• Packed Decimal (VAX-ll BASIC only)
See Chapter 9 for more information about RFA variables. See Chapter 5 for more information about
packed decimal variables.
All variables can have subscripts that indicate their position in an array. The variable types described
in the next three sections are implicit; that is, the variable name defines its data type. Integer variables
end with a percent sign, string variables end with a dollar sign, and floating-point variables end with
neither a percent nor dollar sign.
For new program development, DIGITAL recommends using BASIC's explicit data-typing features.
See Chapter 5 for more information.

1.6.1 Floating-point Variables
A floating-point variable is a named location that stores a single floating-point value. The names of
floating-point variables have a single letter followed by up to 30 letters, digits, underscores, and

1-10

Elements of a BASIC Program

periods. Variable names cannot contain embedded spaces. Therefore, the maximum length of a
floating-point variable name is 31 characters:
1 letter

30 optional characters
For example:

L. .. 5

C
M1

BIG47

F67T.J

Z2.

ID_NUMBER
STORAGE.LOCATION.FOR.XX
STRESS_ VALUE

If an integer value is assigned to a floating-point variable, BASIC converts the value to a floating-point
number.

1.6.2 Integer Variables
An integer variable is a named location that stores a whole number.
Integer variable names have a single letter followed by up to 29 optional letters, digits, underscores,
and periods. Unless the variable is explicitly declared, the name ends with a percent sign (%).
Therefore, the maximum length of an integer variable name is 31 characters:

1 letter
29 optional characters
1 percent sign (%)
For example:
ABCDEFG%
B%

RECORD.NUMBER%
THE.VALUE.I.WANT%

Variable names cannot contain embedded spaces.
If you assign a floating-point value to an integer variable, BASIC truncates the fractional portion of the
value. It does not round to the nearest integer. In this example:
10 57.. = -5.7

BASIC assigns the value -5 to the integer variable, not -6.
For new program development, DIGITAL recommends using BASIC's explicit data-typing features.
See Chapter 5 for more information.

1.6.3 String Variables
A string variable is a named area that stores strings. String variable names have a letter followed by up
to 29 optional letters, digits, underscores, and periods. The name ends with a dollar sign ($). Therefore, the 'maximum length of a string variable name is 31 characters:
1 letter
29 optional characters
1 dollar sign ($)

Elements of a BASIC Program

1-11

For example:
C1$
L.6$
ABC1$

M$
F34G$
T .. $

EMPLOYEE_NAME$
TARGET.RECORD$
STORAGE_SHELF _IDENTIFIER$

Variable names cannot contain embedded spaces.
Strings have both value and length. BASIC sets all string variables to a default length of zero before
execution, except those in a COMMON, MAP, or virtual array. During execution, the length of a
character string associated with a string variable can vary from zero (signifying a null or empty string)
to 65535 characters (in VAX-11 BASIC) or 32767 characters (in PDP-11 BASIC-PLUS-2).
For new program development, DIGITAL recommends using BASIC's explicit data-typing features.
See Chapter 5 for more information.

1.6.4 Subscripted Variables
A subscripted variable is a floating-point, integer, packed decimal (VAX-11 BASIC only), RFA or
string variable that is part of an array. Subscripts define the variable's position in the array. When an
array is first declared (in a DIMENSION, MAP, COMMON, or DECLARE statement), the bounds
determine the size of the entire array. Thus, the bounds of the array define the maximum value for a
subscript of that array.
On VAX IVMS systems, subscripts can be any positive integer value from a to 32767 in WORD
mode, or a to 2147483647 in LONG mode. On PDP-11 systems, subscripts can be any positive
integer value from a to 32767.

Note
The compiler signals an error if a subscript is bigger than the allowable range. Also,
the amount of storage the system can allocate depends on available memory. Therefore, very large arrays may cause an internal allocation error.
In BASIC, arrays are zero-based. That is, the number of elements in any dimension always includes
element number zero. For example, if you dimension an array with (5,5), the array contains 36
elements. This is because BASIC always allocates row and column zero. See Chapter 7 for more
information on arrays.

1.6.5 Initialization of Variables
BASIC sets variables to zero or null values at the start of program execution. Variables initialized by
BASIC include:
• Numeric variables and in-storage array elements (except those in MAP or COMMON statements).
• String variables (except those in MAP or COMMON statements).
• Local variables in function definitions. In addition, BASIC sets these values to zero each time the
program calls the function.
• Variables in subprograms. Subprogram variables are initialized to zero or the null string each time
the subprogram is called.

1-12

Elements of a BASIC Program

Note
In PDP-ll BASIC-PLUS-2, variables in a MAP statement that is referenced in an
OPEN statement are initialized to zero or the null string when the file is opened. In

VAX-ll BAS!C, these variables are not initialized. Also, in POP-ll BAS!C-PLUS-2,
you can use MACRO-ll routines to initialize MAP and COMMON areas. See BASIC
on RSTS / E Systems or BASIC on RSX-ll M / fv1-PLUS Systems for more information.

1.7 Expressions
Expressions are operands (numbers, strings, constants, variables, functions, or array elements) separated by:
• Arithmetic operators
• Stri ng operators
• Relational operators
• Logical operators
Parentheses can appear in expressions to group operands and operators, thus changing the order of
evaluation.
These operators can produce:
• Numeric expressions
• String expressions
• Conditional expressions
The following sections explain these types of expressions.

1.7.1 Numeric Expressions
Numeric expressions are floating-point or integer operands separated by arithmetic operators and
optional iy grouped by parentheses. See Tabie 1-4.

Table 1-4: Arithmetic Operators

Use

Operator

Example

A + B

Add B to A

A-B

Subtract B from A

A*B

Multiply A by B

A / B

Divide A by B

Raise A to the power B

A**B

Raise A to the power B

Elements of a BASIC Program

1-13

An operation on two numeric operands of the same data type yields a result of that type. For example:
A% + B% is an integer expression.
G3 * M5 is a floating-point expression.
An operation on an integer and a floating-point quantity generates a floating-point value:
B% * A is a floating-point expression.
6.8 * 5% is a floating-point expression.
Assigning a vaiue of one data type to a variable of a different data type changes the value to the
variable's data type. The following example assigns the value 32 to the integer variable A%:
10 At = 5.1

* 8.3

This is called numeric conversion. See Chapter 5 for a more complete discussion of this topic.
In general, two arithmetic operators cannot occur consecutively in the same expression. The exceptions are the unary plus and unary minus. For example:
A* + B is valid.
A*-B is valid.
A*(-B) is valid.
A * + -

+ - B is valid.

A-*B is not valid.

1 .7.2 String Expressions
String expressions are strings separated by the plus sign (+) or combinations of string functions. When
it appears in a string expression, the plus sign is the string concatenation operator, not the numeric
addition operator.
For example:
10 C$ = THE RECORD FORMAT I S
20 PRINT C$
30 END
II

SEQUENT I AL I.JAR I ABLE

RUNNH
THE RECORD FORMAT IS SEQUENTIAL VARIABLE
See Chapter 4 for more information on strings.

1.7.3 Conditional Expressions
Conditional expressions are useful for coding decision points in your program. Program control
structures such as IF-THEN-ELSE, UNTIL, and WHILE all use conditional expressions to determine
the points to which control is transferred.

1-14

Elements of a BASIC Program

A conditional expression contains operands and relational or logical operators. A conditional expression can contain relational expressions, logical expressions, or a combination of these. However, no
matter how many operands and operators a conditional expression contains, the value it returns is
either zero (false) or minus one (true).
Relational operators express comparisons between two numbers or two strings. You can compare
numeric values with numeric values, and string values with string values, but you cannot compare
numeric values with string values.
Logical operators express logical or Boolean relationships. A logical operator performs its operation
bit-by-bit between two integer values. You can use a logical expression to test a condition, for
example:

IF (AX. AND B%) THEN PRINT "TRUE" ELSE PRINT "FALSE"

When using logical expressions to test conditions, the logical expression is false if zero and true for all
other values.
The following sections describe types of conditional expressions.
1.7.3.1 Numeric Relational Expressions

Numeric relational operators compare the values of two operands and return an integer: 1) minus
one if the relation is true, or 2) zero if the relation is false. For example:
Example 1

10
10

PRINT "RELATIONSHIP IS TRUE" IF (A <> C)
PRINT "RELATIONSHIP IS FALSE" IF NOT (A <> C)
END
RUNNH
RELATIONSHIP IS TRUE

Example 2

A
B
C

10
10
15

PRINT "RELATIONSHIP IS TRUE" IF (A = C)
PRINT "RELATIONSHIP IS FALSE" IF NOT (A
END

RUNNH
RELATIONSHIP IS FALSE

Elements of a BASIC Program

1-15

Table 1-5 Iists numeric relational operators.

Table 1-5: Numeric Relational Operators

Example

Operator

Meaning

A = B

A is equal to B.

A < B

A is less than B.

A > B

A is greater than B.

<= or =<

A <= B

A is less than or equal to B.

>= or =>

A >= B

A is greater than or equal to B.

<> or ><

A <> B

A is not equal to B.

A == B

A and B will PRINT the same because they are equal to six significant digits.

1.7.3.2 String Relational Expressions
String relational operators compare string values. BASIC uses the ASCII character collating sequence
to determine the relative character values. It compares the strings character by character, left to right,
until it finds a difference in ASCII value. Note that the relational operator = = has a different meaning
when applied to strings than when applied to numbers. For example:
10

A$ = IIABC II
B$ = II ABZ II
PRINT IIABC is less than ABZ II IF A$ < B$
PRINT IIStrings are identical.
IF A$ == B$
PRINT IIABC is greater than ABZ II IF A$ :> B$
END
1I

RUNNH
ABC is less than ABZ
BASIC compares A$ and B$ character by character. The strings are identical up to the third character.
Because the ASCII value of "Z" is greater than that of "C", A$ is less than B$.
If two strings are identical up to the last character in the shorter string, BASIC pads the shorter string
with spaces (ASCII value 32) to generate strings of equal length. It then compares the remaining
characters in the longer string against these spaces. For example:
10

A$ = II ABCDE II
B$ = IIABC II
PRINT IIB$ COMES BEFORE A$II IF B$ <: A$
PRINT IIA$ COMES BEFORE B$II IF A$ < B$
END

RUNNH
B$ COMES BEFORE A$

1-16

Elements of a BASIC Program

In this program; BASIC compares "ABCDE" to "ABC
collating sequence.

"to determine which string comes first in the

Table 1-6 lists string relational operators and their meanings.

Table 1-6: String Relational Operators

Operator

Example

Meaning

A$ = B$

Strings A$ and B$ are identical after the shorter string has been padded with spaces to
equal the length of the longer string.

A$ < B$

String A$ occurs before string B$ in ASCII sequence.

A$ > B$

String A$ occurs after string B$ in ASCII sequence.

<= or =<

A$ <= B$

String A$ is identical to or precedes string B$ in ASCII sequence.

>= or =>

A$ >= B$

String A$ is identical to or follows string B$ in ASCII sequence.

<> or ><

A$ <> B$

String A$ is not identical to string B$.

A$ = = B$

Strings A$ and B$ are identical in composition and length, without padding.

1.7.4 Logical Expressions
A logical expression contains either: 1) an optional unary logical operator and one operand or
2) two operands separated by a logical operator. Logical expressions are valid only when the
operands are integers.
BASIC determines whether the logical expression is true or false as shown in Table 1-7.

Table 1-7: Logical Operators

Operator

Example

NOT

NOTA%

AND

A% AND B%

The logical product of A% and B%. A% AND B% is true only if both A% and B% are
true.

A% OR B%

The logical sum of A% and B%. A% OR B% is false only if both A% and B% are false;
otherwise, A% OR B% is true.

XOR

A% XOR B%

The logical exclusive OR of A% and B%. A% XOR B% is true if either A% or B% is true
but not if both are true.

EQV

A% EQV B%

The logical equivalence of A% and B%. A% EQV B% is true if A% and B% are both true
or both false; otherwise the value is false.

IMP

A%IMPB%

The logical implication of A% and B%. A% IMP B% is false only if A% is true and B% is
false; otherwise, the value is true.

Meaning
The bit-by-bit complement of A%. If A% is true (-1), NOT A% is false (0).

Elements of a BASIC Program

1-17

The truth tables in Table 1-8 summarize the results of these logical operations; zero is false, minus
one is true:

Table 1-8 : Truth Tables

NOTA%

A% OR B%

-1

0
0

-1

-0

-1

-1
-1
-1

A% AND B%

A% EQV B%

0
0

-1

-1
-1

0
0
0,

-1

0
0

-1
-1

0
0

-1

-1
-1

-1

A% XOR B%

A%IMPB%

-1

-1
-1

0
0

-1

-1
0

-1

-1
-1

The operators XOR and EQV are logical complements.
BASIC generally accepts any nonzero value as true. However, logical operators return valid results
only when minus one is specified for true values and zero for false. For example:
Example 1
10

A'X. = 2%
5% = a%
PRINT "A'X. is true" IF A'X.
PRINT "5% is true" IF 5'7..
IF (A% AND 5%)
THEN
PRINT "A'X AND 5 'X. is true"
ELSE
PRINT A'X. AND 5% is false"
END IF
END
II

RUNNH
A'X is true
5 'X. is true
A% AND 5% is false

1-18

Elements of a BASIC Program

Example 2

= -1%

Bi.. = -1 %
PRINT II Ai.. is true IF Ai..
PRINT II Bi.. is true" IF B%
IF ( Ai.. AND B%)
THEN
PRINT IIA% AND B% is true
ELSE
PRINT IIA% AND B% is false
END IF
ll

GO END

RUNNH
AX. is

+'" '1'10 I'
'"'
' .. Lit;

B% is true
Al AND B% is true
In the first program, the values of A% and B% test as true. However, the logical AND of these two
variables returns an unexpected result. In the second program, variables A%, B%, and the logical
expression A% AND B% test as true.
The first program returns this seemingly contradictory result because logical operators work on the
individual bits of the operands. The 8-bit binary representation of 2% is:

o 0 0 0 0 0

The 8-bit binary representation of 4% is:

o 0 000

0 0

Each of these values tests as true because they are nonzero. However, the result of an AND operation
'
on these two values is zero:

o 0 0 0

0 0 0 0

This is because the AND operation sets a bit in the result only if the corresponding bit is set in both
operands. This value tests as false. The binary representation of minus one is:

(The leftmost bit is a sign bit.) The result of -1 % AND -1 % is -1 %, and this value tests as true,

1.7.5 Evaluating Expressions
BASIC evaluates expressions according to operator precedence. Each arithmetic, relational, and string
operator in an expression has a position in the hierarchy of operators. The operator's position tells
BASIC when to perform the operation. Parentheses can change the order of evaluation.
BASIC evaluates nested parenthetical expressions from the inside out. For example:

B = (25 * (16 A(3/2)))

Elements of a BASIC Program

1-19

This expression is evaluated to 1600. Because (3/2) is the innermost parenthetical expression, BASIC
evaluates it first, then (16"1.5), and finally (25 * 64).
Table 1-9 lists all operators as BASIC evaluates them. Note that:
• Operators on the same line in the table are evaluated left-ta-right.
• The operators + and * are evaluated in algebraically correct order.
• BASIC evaluates A"B"C as (A"B)"C.
• BASIC evaluates expressions enclosed in parentheses first, even when the operator in parentheses
has a lower precedence than operators outside the parentheses.

Table 1-9: Numeric Operator Precedence

Highest

** or
- (unary minus) and
+ (unary plus)

* or /

+ or+ (concatenation)
all relational operators

NOT
AND
OR, XOR
IMP

EQV

Lowest

BASIC evaluates the following expression in five steps:
A = 15" 2 + 12" 2-(35 * 8)
1.

35 * 8 = 280

Multipl ication

15"2

225

Exponentiation (left-most expression)

12"2

144

Exponentiation

225 + 144 = 369

Addition

369 - 280 = 89

Subtraction

1-20

Elements of a BASIC Program

Chapter 2
..... ~I~ I~~ •• + ~~~ n .. +~ •• +
S =IIIItJlC
IIltJU" GIIU VU .. tJU ..

This chapter explains how to use the BASIC statements that move data to and from your program.

2.1 Program Input
BASIC programs receive data in three ways:
• You can enter data interactively while the program runs. You do this with INPUT, INPUT LINE, and
LlNPUT statements .
• If you know all the information your program will require, you can enter it as you write the
program. You do this with READ, DATA, and RESTORE statements.
• You can read data from files outside the program. You do this with INPUT #, INPUT LINE #, and
LlNPUT # statements.
The following sections describe the first two types of program in9ut. See Section 2.3 for more
information about simple I/O to and from files.

2.1.1 Providing Input Interactively
The INPUT, INPUT LINE, and LlNPUT statements prompt you for data while the program runs.
2.1.1.1 INPUT Statement

The INPUT statement has the format:
INPUT [prompt

{;}

] vbl [,[prompt

{ ;}

] vbl] ...

where:
prompt

Is a string literal that clarifies the request for data. Enclose string literals in quotation
marks. You can specify a separate prompt for each variable in the list.

February 1984

2-1

,and;

Are punctuation marks that determine the cursor position after BASIC prints the
prompt.

vbl, vbl

Is a list of variables assigned values by the INPUT statement. Separate the variables
with commas or semicolons.

The prompi can clarify ihe inpui request by specifying the type and number of data eiements required
by the program. This is especially useful when: 1) the program contains many variables or 2) someone else is running your program. For example:
10

INPUT "PLEASE TYPE 3 INTEGERS"
A% = B% + C% + D%
PRINT "THEIR SUM IS"; Ai;',
END

Hrx.

ICi;',

ID%

RUN
PLEASE TYPE 3 INTEGERS? 25,50,75m
THEIR SUM IS 150

When your program runs, BASIC stops at each INPUT, L1NPUT, or INPUT LINE statement and:
• Prints a string prompt, if specified, and a question mark (?) followed by a space.
If you have a semicolon separating the input prompt from the variable, BASIC prints the question
mark and space immediately after the input prompt.
If you have a comma separating the input prompt from the variable, BASIC prints the input
prompt, skips to the next print zone, and then prints the question mark and space .
• Waits for you to type a value for the variable named in the INPUT statement.
See Section 2.2.1 for more information about print zones.
You must provide one value for each variable in the INPUT request. If you do not, BASIC prompts
again:
10 INPUT A,B
20 END
RUN

? 8

BASIC interprets a carriage return (null input) as a zero value for numeric variables and as a null string
for string variables. For example:

?OO)

These responses assign the value five to variable A and zero to variable B. In contrast, if you provide
more values than there are variables, BASIC ignores the excess. In this example:
10 INPUT A,B,C
15 PRINT A,B,C
20 END
RUN
? 5,8,7,800)
5

2-2

Simple Input and Output

BASIC ignores the extra value (8). Note that you can type multiple values if they are separated by
commas. Because commas separate variables in line 15, BASIC prints each variabie at the start of a
print zone.
If you name a numeric variable in an !NPUT statement, you must supply numeric datao If you supply
string data to a numeric variable, BASIC signals "Illegal number" (ERR = 52). If you supply a floatingpoint number for an integer variable, BASIC signals "Data format error" (ERR = 50).
If you name a string variable in an INPUT statement, you can supply either numbers or letters, but
BASIC treats the data you supply as a string. It is important to note that digits and a decimal point are
also valid ASCII characters. For example:
10

INPUT "Please type a nUMber"; A$
PRINT A$

RUNNH
Please type a nUMber? 25.5
25.5

BASIC interprets the response as a 4-character string.
You can type strings with or without quotation marks. However, if you want to input a string containing a comma, you should enclose the string in quotation marks. If you do not, BASIC treats the
comma as a delimiter and assigns only part of the string to the variable. If you use quotation marks,
be sure to type both beginning and ending marks. If you forget the end quotation mark, BASIC signals
"Data format error" (ERR = 50).
2.1.1.2 INPUT LINE and LIN PUT Statements

The INPUT LINE and L1NPUT statements prompt you for string data while your program runs. You
can respond with strings that contain commas, semicolons, and quotation marks - characters the
INPUT statement interprets as delimiters. The formats of these statements are:
INPUT LINE [prompt

LlNPUT [prompt

{ ;}

{ :}

] str-vbl [,[prompt

1str-vbl (,[prompt

{ ;}

{ : }

] str-vbl] ...

] str-vbi] ...

where:
prompt

Is a string literal that clarifies the request for data.

and;

Are punctuation marks that determine the cursor position after BASIC prints the prompt.

str-vbl

Is a string variable.

When your program runs, BASIC stops at each L1NPUT or INPUT LINE statement and:
• Prints a string prompt, if specified, and a question mark (?) followed by a space.
-

If you have a semicolon separating the input prompt from the variable, BASIC prints the question
mark and space immediately after the input prompt.

If you have a comma separating the input prompt from the variable, BASIC prints the input
prompt, skips to the next print zone, and then prints the question mark and space.

• Waits for you to type the value for the variable named in the L1NPUT or INPUT LINE statement.

February 1984

Simple Input and Output

2-3

The INPUT LINE statement accepts and stores all characters, including quotation marks, semicolons,
and commas, up to and including the line terminator or terminators. LlNPUT accepts all characters
up to (but not including) the line terminator or terminators. For example:

INPUT LINE A$
LINPUT B$
PRINT A$
PRINT B$
PRINT IIDONEII
END

RUN
? IINOW, LOOK HERE! II , HE SAID.(Bffi
? II NOT THERE, HERE! 1I(Bffi

IINOW, LOOK HERE!II t HE SAID.
IINOT THEREt HERE! II
DONE
In this example, both INPUT LINE and LlNPUT treat your input as a string literal. Therefore, BASIC
interprets quotation marks as characters, not as string delimiters.
Note that the INPUT LINE statement includes the line terminator(s) ((8D)) as part of the string literal.
This carriage return / line feed pair causes double spacing in the printed output.
INPUT, INPUT LINE, and LlNPUT statements can accept data from a terminal or a terminal-format
file. See Section 2.3 for I/O to terminal format files.

2.1.2 Providing Input from the Source Program
The following sections describe the READ, DATA, and RESTORE statements. In order to use READ
and DATA statements, you must know what data is required when writing the program. These
statements do not stop to request data while the program runs. Therefore, your program runs faster
than with the INPUT statements.
The RESTORE statement lets you use the same data items more than once.

2.1.2.1 READ Statement
The READ statement reads values from a data block. Its format is:
READ vbl [,vbl] ...

where:
vbl [,vbl]

Is one or more numeric or string variables, either simple or subscripted. Separate all
variables with commas.

For example:

10 READ At BX., C$, D(5) t E
A data pointer keeps track of data read. Each time the READ statement requests data, BASIC retrieves
the next available constant from a DATA statement.

2-4

Simple Input and Output

You can place a READ statement anywhere in a multi-statement line. However, a READ statement is
not valid without at least one DATA statement. if your program contains a READ statement but no
DATA statement, BASIC signals the compile-time error "READ without DATA".

2.1.2.2 DATA Statement
The DATA statement contains values that the READ statement supplies to the program. Its format is:
DATA const [,const] ...
where:
const [,const]

Is one or more floating-point, integer, or string constants (quoted or unquoted).
Constants must be separated by commas and listed in the same order by data type
as the variables requested in the READ statement.

In a DATA statement, integer constants are whole numbers; they cannot be followed by a percent
sign. For example:

10
20
30
40
50
400

500

ON ERROR GO TO 400
READ A%t B%t C%
DATA l%t 2%t 3%
PRINT A% + B% + C%
GOTO 500
PRINT "ERROR NUMBER IS "; ERR
PRINT "ERROR AT LINE "; ERL
PRINT "ERROR MESSAGE IS "; ERT$(ERR)
RESUME 500
END

RUNNH
ERROR NUMBER IS 50
ERROR AT LINE 100
ERROR MESSAGE IS %Data forMat error
Because the integer constants in the DATA statement contain percent signs, BASIC signals an error.
You can use an ampersand (&) to continue a DATA statement. For example:

10 DATA "ABRAMS" t BAKER t CHR I STENSON t 8.:
DOBSON t "EISENSTADT" t FOLEY
You can have more than one DATA statement in a program. DATA statements are ignored without at
least one READ statement.
Note
BASIC treats all characters between the keyword DATA and the next line number as
data. Therefore, a DATA statement must be the last or only statement on a line and the
first statement following a DATA statement must be on a numbered line.
Comment fields are not allowed in DATA statements. For example:

10 READ A$
20 DATA ABC!COMMENT
These statements cause A$ to contain "ABC!COMMENT".

Simple Input and Output

2-5

When you compile a program, BASIC creates one data block for each program unit. Each data block
is local to the program or subprogram containing it; this means that you cannot share DATA statements between program modules.
The data block contains the values in all DATA statements in that program unit. These values are
stored in line number order. Each time BASIC executes a READ statement, it retrieves the next value
in the DATA block.
BASIC signals an error if:
• You assign alphabetic characters to a numeric variable. BASIC signals "Data format error"
(ERR= 50).
• You try to read values into more variables than there are values in DATA statements. BASIC signals
"Out of data" (ERR = 57).
BASIC ignores excess data in DATA statements.
This example of READ and DATA mixes string and floating-point da'ia types:

10 READ TEXT$
20 READ RADIUS
30 DIAMETER = PI * RADIUS
40 DATA "THE DIAMETER IS"
50 DATA 40.5
60 PRINT TEXT$; DIAMETER
70 END

* 2

RUN
THE DIAMETER IS 254.468
Line 10 reads the first data item in the program: "THE DIAIY1ETER IS". Line 20 reads the second data
item: 40.5.
2.1.2.3 RESTORE Statement

The RESTORE statement lets you read the same data more than once. It has no effect without READ
and DATA statements. Its format is:
RESTORE

RESTORE resets the data pointer to the beginning of the first DATA statement in the program unit. You
can then reread data values. Consider this program:

10 READ BtCtD
20 RESTORE
30 READ EtFtG
40 DATA 6t3t4t7t8t2
50 END
The READ statement in line 10 reads the first three values in the DATA statement:
B=6
C=3
0=4

2-6

Simple Input and Output

The RESTORE statement resets the pointer to the beginning of line 40. During the second READ (line
30), the first three values are read again:

E=6
r=3
G=4
Without the RESTORE statement, line 30 would assign the values:

E=7
F=9

G=2

2.2 Program Output
The PRINT statement displays data on your terminal during program execution. BASIC evaluates
expressions before displaying results.
You can also print and format data with the PRINT USING statement (see Chapter 8).
The PRI NT statement has the format:
PRINT exp [

t~ I

exp] ...

where:
exp

Can be any valid expression.

, and;

Are punctuation marks that determine the cursor position after BASIC prints the
expression.

When you use the PRI NT statement:
• BASIC precedes positive numbers with a space and negative numbers with a minus sign.
• BASIC prints a space after every number.
• BASIC prints strings with no leading or trailing spaces.
When an element in a list is not a simple variable or constant, BASIC evaluates the expression before
printing the value. For example:
10

A = as

6 = 55

20
30

PRINT A + 6
END

RUN
100

However, BASIC interprets text inside quotation marks as a string literal. For example:
10

A = as

6 = 55

20
30

PRINT
END

IIA +

Simple Input and Output

2-7

In this case, the output is:

A + B
The PRINT statement without an expression prints a blank line. For example:

10 PRINT "THIS E}{AMPLE LEAl,lES A BLANK LINE"
20 PRINT
30 PRINT "BETWEEN TWO LINES."
40 END
RUN
THIS EXAMPLE LEAVES A BLANK LINE
BETWEEN TWO LINES.
You can place PRINT statements anywhere on a multi-statement line.

2.2.1 Print Zones -

The Comma and Semicolon

A terminal line contains zones that are 14 character positions wide. The number of zones in a line
depends on the width of your terminal: a 72-character line contains 5 zones, which start in columns
1, 15, 29, 43, and 57. A 132-character line has additional print zones starting at columns 71, 85, 99,
and 113.
The PRINT statement formats program output into these zones in different ways, depending on the
character that separates the elements to be printed.
If a comma precedes the PRINT item, BASIC prints the item at the beginning of the next print zone. If
the last print zone on a line is filled, BASIC continues output at the first print zone on the next line:

5
10

INPUT A tB tC tD tE tF
tC tD tE tF
END
PRINT A d3

RUN
? 5t10t15t20t25t30ru
5
10
30

BASIC skips one print zone for each extra comma between list elements. For example, this program
prints the value of A in the first zone and the value of B in the third:

A = 5

10
15 PRINT "FIRST ZONE" t t"THIRD ZONE"
20 PRINT At tB
30 END
B =

RUN
FIRST ZONE
5

2-8

Simple Input and Output

THIRD ZONE
10

If you separate print elements with a semicolon, BASIC does not move to the next print zone. For
example:
10
20
30

PRINT 10; 20
PRINT "ABC"; II}{'{Z"
END

RUNNH
10 20
ABCXYZ

In this example, line 10 prints two numbers. (Printed numbers are preceded by a space or a minus
sign and followed by one space.) Line 20 prints two strings.
Placing a comma or semicolon after the last item in a PRINT statement leaves the cursor at the same
line:
• A comma specifies that the cursor moves to the next print zone.
• A semicolon specifies that the cursor does not move.
In either case, BASIC waits at that line for another PRINT or INPUT statement.
For example:
10
20
30

ao END

INPUT }{ t Y tZ
PRINT X tY t
PRINT Z

RUNNH
? 5t10t15

BASIC prints the current values of X, Y, and Z on one line because a comma follows the last item in
line 20.
The following example shows PRINT statements using a comma, a semicolon, and no formatting
character after the last pri nt item.
10

!No COMMa after I%t so each eleMent
!Prints on its own line
!

PRINT 1% FOR 1% = 1% TO 10%
PRINT
PRINT
PRINT
!A COMMa follows J%t so each
!eleMent prints in a separate zone
PRINT J%t FOR J% = 1% TO 10%
PRINT
PRINT
PRINT
(continued on next page)

Simple Input and Output

2-9

!A sefTlicolon follows K%, so print
!elefTlents are pacKed together
PRINT K%; FOR K%
END

1I.. TO 10%

RUNNH
2
3
LI

5
G

7
8
9

10
1

3
8

2
7

Commas and semicolons also let you control the placement of string output:
10 PRINT "FIRST ZONE" t ,"THIRD ZONE" t ,"FIFTH ZONE"
20 END
RUN
FIRST ZONE

THIRD ZONE

FIFTH ZONE

The extra comma between strings causes BASIC to skip every other print zone.

2.2.2 Output Format for Numbers and Strings
BASIC prints strings exactly as you type them, with no leading or trailing spaces. It does not print
quotation marks unless they are delimited by another matching pair. For example:
10 PRINT 'PRINTING "QUOTATION" MARKS'
20 END
RUN
PRINTING "QUOTATION" MARKS
BASIC follows these rules for printing numbers:
• When you print numeric fields, BASIC precedes each number with a space or a minus sign and
follows it with a space. If a number can be represented exactly by six decimal digits (or fewer) and,
optionally, a decimal point, BASIC prints it that way.
• When you print a number whose integer portion is six decimal digits or less (for example,
1234.567), BASIC rounds the number to six digits (1234.57). If the integer portion of a number is
seven decimal digits or larger, BASIC rounds the number to six digits and prints it in E format. See
Section 1.5.1 for more information about E format.
2-10

Simple Input and Output

• When you print a number with magnitude between .1 and 1, BASIC rounds it to six digits. When
you print a number having more than six digits, and with magnitude smaller than .1, BASIC rounds
it to six digits and prints it in E format.
• BASiC does not print trailing zeros to the right of the decimal point. If all digits to the right of the
decimal point are zeros, BASIC omits the decimal point as well.
• When you print LONG integers, BASIC prints up to 10 significant digits.
The PRINT statement only displays up to six digits of precision for floating-point numbers. This
corresponds to the precision of the SINGLE data type. To display the extra digits in DOUBLE,
GFLOAT (VAX-11 BASIC only), and HFLOAT numbers (VAX-11 BASIC only), you must use the
PRINT USING statement. See Chapter 8 for more information on PRINT USING.
This example sho'vvs how BASIC prints various numbers vvith single precision:
10 FOR I = 1 TO 20
20
PRINT 2···(-1) tI ,2···1
30 NE}{T I
40 END
RUN
.5
.25
.125
.0825
.03125
.015825
.78125E-02
.380825E-02
.185313E-02
.878583E-03
.488281E-03
.244141E-03
.12207E-03
.810352E-04
.305178E-04
.152588E-04
.787838E-05
.38147E-05
.180735E-05
.853874E-08

5
8
7
8
8
10
11
12
13
14
15
16
17
18
18
20

2
4
8

18
32
G4
128
258
512
1024
2048
4088
8182
18384
32788
65536

131072
282144
524288
.104858E+07

2.3 Terminal-Format Files
Terminal-format files let you perform simple I/O to disk files. The records in a terminal-format file
must be accessed sequentially. That is, you must access the records in the file one by one, from the
first to the last. You can add new records only at the end of the file.
Just as the INPUT, L1NPUT, and INPUT LINE statements receive information from a terminal, the
INPUT #, L1NPUT #, and INPUT LINE # statements receive information from a terminal-format file.
And, as the PRINT statement sends information to the terminal, the PRINT # statement sends information to a terminal-format file.
Terminal-format files are very useful for creating files to be printed on a line printer (for example,
reports) or for supplying a program with moderate amounts of input. However, if you want to use the
same file for both input and output, you should not use terminal-format files. Instead, use sequential,
relative, or indexed files (see Chapter 9).

Simple Input and Output

2-11

Note that you do not have to use a program to create a terminal-format file. You can use a text editor
to create a file and insert data, then use a BASIC program to open the file and retrieve the data.

2.3.1 Opening and Closing a Terminal-Format File
You use the OPEN statement to create a file, or to gain access to an existing file. For terminal-format
files, the OPEN statement format is:
OPEN "file-spec" [FOR INPUT] AS [FILE] #chnl-exp
[FOR OUTPUT]
where:
file-spec

Is the file specification.

FOR INPUT

Specifies that the file already exists.

FOR OUTPUT

Specifies that a new file is being created.

#chnl-exp

Specifies the channel on which I/O is performed. The channel number must be
between 1 and 12 for PDP-11 BASIC-PLUS-2 and between 1 and 99 for
VAX-11 BASIC.

If you do not specify either FOR INPUT or FOR OUTPUT, BASIC tries to open an existing file. If the
file does not exist, BASIC creates a new one.
The channel specification lets you associate a number with the file for as long as the file is open. All
I/O operations to or from the file use this number.
When you are finished accessing a file, you close it with the CLOSE statement. Its format is:
CLOSE [#]chnl-exp
where:
[#]chnl-exp

Is the channel number of an open file. The pound sign is optional.

2.3.2 Writing Records to a Terminal-Format File
The following example receives information from a terminal, then writes the information to a
terminal-format file as a report:
100
200
300
400
500

PRINT "This pr09rafrl creates a dail}' sales report file nafTled SALES.DAT"
OPEN "SALES.DAT" FOR OUTPUT AS FILE #4%
PRINT #4·X.t "Salesperson"t"Sales Area"t"ItefTls Sold"
PRINT
INPUT "Hol.\l fTlany salespersons for today's report"; SALES_PERSONS/..
FOR 1% = 1% TO SALES_PERSONS%
INPUT "Salesperson's nafTle"; S_NAME$
INPUT JlSal es area Jl ; AREA$
INPUT JlNl.lfTlber of itefTls sold Jl ; ITEMS_SOLD%
PRINT #4%t S_NAME$t AREA$t ITEMS_SOLD%

600
700

CLOSE #4%
END

2-12

Simple Input and Output

NE>n I ·X.

RUNNH
This pro~raM creates a daily sales report file naMed SALES.DAT
How Many salespersons for today's report? 3
Salesperson's naMe? JONES
Sales area? NJ
ItelTls sold? 5
Salesperson's naMe? SMITH
Sales area? NH
ItelTls sold? 6
Salesperson's naMe? BAINES
Sales area? I.'T
ItelTls sold? 8
$TYPE SALES.DAT
Salesperson

Sales Area

IteIT1S Sold

JONES
SMITH
BAINES

NJ
NH
l.lT

6
8

This program first prints a header explaining its purpose, then opens a terminal-format file on channel
4. Line 300 uses the PRINT # statement to place an explanatory header in the file, then prints a b!ank
line.
The program then prompts you for the number of salespersons for which data is to be entered. Line
500 contains a FOR-NEXT loop that prompts for the name, sales area, and items sold for each
salesperson. Note that the FOR-NEXT loop executes only as many times as there are salespersons.
(See Chapter 3 for more information about FOR-NEXT loops.)
After the data has been entered for each salesperson, the program writes this information to the
terminal-format file. Because the response to the first question was three, the FOR-NEXT loop executes three times.
After the last item has been printed to the file, the program closes the file and ends. When you display
the file with the $TYPE command, you see that the information is printed under the proper headers.
You can also print the file on a line printer. Notice that the PRINT # statement formats the output in
print zones as does the PRINT statement.

Simple Input and Output

2-13

Chapter 3
Program Control

In a BASIC program, statements are normally executed consecutively, in line number order. Within a
program line, statements are executed from left to right. Control statements let you change this
sequence of execution by:
• Executing a block of statements repeatedly (looping)
• Executing subroutines
• Suspending or stopping the program
• Executing a block of statements conditionally
• Executing a singie statemeni condiiionally
• Executing a single statement repeatedly
• Branching conditionally to another program line or label
• Branching unconditionally to another program line or label
The following sections describe the BASIC statements that let you perform these operations.

3.1 Loops
A program loop is a construct that allows the repeated execution of a set of statements. There are
three types of BASIC program loops:
• FOR-NEXT
• WHILE-NEXT
• UNTIL-NEXT

3-1

Each type of loop controls the repeated execution of a set of statements. The loop control statements,
plus the set of statements in the loop, are called the loop block. You control the number of loop
iterations in several ways:
• By specifying starting and ending values for a loop control variable (FOR-NEXT)
• By using a loop construct that performs a logical test (UNTIL-NEXT and WHILE-NEXT)
• By performing a test within the loop block and either explicitly exiting from the loop with the EXIT
statement, or explicitly transferring control to the loop control statement (FOR, WHILE, or UNTIL)
with the ITERATE statement
Note that the EXIT and ITERATE statements accept label names as arguments. If you intend to use
these statements for explicit loop control, you should label your loops.
The following sections describe these loop constructs and when to use them.

3.1.1 FOR-NEXT Loops
FOR-NEXT loops let you specify how many times to repeat a block of statements. If you want to
execute a single statement a specified number of times, you should use the FOR modifier. See Section
3.6.3 for more information about the FOR modifier.
In a FOR-NEXT loop, you specify a loop control variable that determines the number of times the
loop executes (the number of loop iterations). In a FOR-NEXT loop, the starting and ending values of
the loop control variable are known when the loop begins execution. The format of a FOR-NEXT
loop is:
FOR ctrl-vbl = num-exp1 TO num-exp2 [STEP num-exp3]

NEXT ctrl-vbl

where:
ctrl-vbl

Is the control or index variable that is incremented or decremented each time the
loop executes. Ctrl-vbl must be a simple (unsubscripted) variable.

num-exp1

Is the starting value for the control variable.

num-exp2

Is the ending value for the control variable.

num-exp3

Is the amount added to the control variable each time the loop executes.

The FOR statement assigns the control variable a starting value, num-expl, and a terminating value,
num-exp2. The optional STEP clause lets you specify the amount, num-exp3, added to the loop
control variable after each loop iteration. If you do not specify a STEP clause, the default increment is
+ 1. For example:
100

FOR I% = 1% TO 10%
NEW_ARRAY%(I%)
NE}{T I i..

= I%

This example assigns values to array elements 1 through 10, inclusive.

3-2

Program Control

When the FOR loop block executes, BASIC:
• Evaluates num-expl (the starting value) and assigns the result to the control variable.
• Evaluates num-exp2 (the ending value) and num-exp3 (the STEP value) and assigns these results to
temporary storage locations.
• Tests to see whether the ending value has been exceeded. If the ending value has already been
exceeded, BASIC executes the line following the NEXT statement. If the ending value has not been
exceeded, BASIC executes the statements in the loop.
• Adds the STEP value to the control variable and transfers control to the FOR statement, which tests
whether the ending value has been exceeded.
Note that BASIC performs the test at the top of the loop. When the control variable exceeds the
ending value, BASIC exits the loop, then subtracts the STEP value from the control variable. This
means that after loop execution, the value of the control variable is that last used in the loop, not the
vaiue that caused loop termination.
Because the starting, ending, and STEP values can be numeric expressions, they are not evaluated
until the program runs. Therefore, it is possible to code a FOR-NEXT loop that does not execute. For
example:

100
200
300

aoo

COUNTER% = 0%
INPUT "START"; START';!,
INPUT "FINISH"; FINISHi.,
INPUT "STEP l.IALUE"; STEP_l)ALi.,
FOR 1% = START% TO FINISH% STEP STEP_VALZ
COUNTER% = COUNTER% + 1%
NE}-{T Ii.,
PRINT "This loop executed"; COUNTERi.,; "tiltles."

RUNNH
START? 0
FINISH? 5
STEP VALUE? -1
This loop executed 0 times.
However, if the FOR statement contains integer constants, BASIC can check to see whether the loop
will execute when the program is compiled. For example:

100

FOR 1% = 0% TO 5% STEP -1%
COUNTER%
COUNTER% + 1%
NEXT I 'X

When you compile this program, BASIC diagnoses the problem and reports: "Loop will not execute."
Whenever possible, you should use integer variables to control the execution of FOR-NEXT loops.
This is because some decimal fractions cannot be represented exactly in a binary computer and the
calculation of floating-point control variables is subject to this inherent precision limitation.

Program Control

3-3

The following program uses the DECLARE statement to explicitly declare its variables. See Chapter 5
for more information on DECLARE. The program 'shows you the different behavior of integer and
floating-point control variables:
DECLARE
INTEGER

&:
&:
&:
&:
&

Inte~er_loop_index,

LooP_collnt_l f
Loop_count_2f
REAL
Real_loop_index

FOR

Inte~er_loop_index = 0 TO 100 STEP
LooP_collnt_l = Loop_count_l + 1

Inte~er_loop_index

FOR Real_loop_index = 0 TO 10 STEP 0.1
Loop_count_2 = LooP_collnt_2 + 1
NEXT Real_loop_index
PRINT
PRINT
PRINT
PRINT
END

"Integer
"Integer
"Real
"Real

loop
loop
loop
loop

count:
end
count:
end

loop
loop
loop
loop

count:";
: .. ;
end
count:";
end
:

;

LooP_collnt_l
Integer_looP_index
Loop_count_2
Real_loop_index

RUNNH
Inte~er
Inte~er

Real
Real

101
100
100
8.8

The first loop uses an integer control variable while the second uses a floating-point control variable.
The first loop executes 101 times and the second 100 times. After the hundredth iteration of the
second loop, the internal representation of the value of Real_loop_index exceeds 10 and BASIC exits
the loop. Because the first loop uses integer values to control execution, BASIC does not exit the loop
until Integer_loop_index equals 101.
Although it is not recommended programming practice, you can change the value of the control
variable inside the loop. For example:
10 FOR 1%

= 1% TO 10% STEP 1%
1% = I 'x. * 2'X.

LOOP_COUNT%
LOOP_COUNT% + 1%
NEXT 1%
PRINT "1% EQUALS" ; Ii.,
PRINT "LOOP_COUNT EQUALS"; LOOP_COUNT%
END
RUNNH
IX EQUALS 14
LOOP_COUNT EQUALS 3

3-4

Program Control

BASIC makes only three passes through this loop:
• On the first iteration, 1% is assigned a value of one. Line 20 assigns 1% a value of two.
• On the second iteration, BASIC increments 1% by one (1% now equals three). Line 20 assigns 1% a
value of six.
• On the third iteration, BASIC increments 1% by one (1% now equals seven). Line 20 assigns 1% a
value of 14, and when BASIC executes the FOR statement a fourth time, the terminating value has
already been reached.
Although changing the value of the control variable affects loop execution, changing the STEP value
or the terminating value does not. This is because BASIC makes a temporary copy of these values,
and these copies are not accessible to you. For example:
10

DECLARE
INTEGER
Loop_indext
LooP_liMitt
Loop_step
PRINT iiLoop index
LooP_lirnit = 10
Loop_step = 1

&:
&:
&:

t "Loop lirTlit!! t "Loop step"

FDR Loop_index = 0 TO LOOP_liMit STEP Loop_step
PRINT Loop_indext LooP_liMitt Loop_step
Loop_step = 2 * Loop_step
LOOP_liMit = LOOP_liMit - 1
NEXT Loop_index
END
RUNNH
Loop index
0
1
2
3

Loop 1 i ITI it
10

8
5

5
8
7

Loop step
1
2

8
18
32

3
2

128
258
512
102a

Because BASIC compares the control variable to the temporary copy of the terminating value, changing variables Loop_step and Loop_limit has no effect on loop execution.

3.1.2 WHILE-NEXT Loops
WHILE-NEXT loops let you repeatedly execute a block of statements for as long as a given condition
is true. If you want to repeat the execution of a single statement for as long as a given condition is
true, you should use the WHILE modifier. See Section 3.6.4 for more information about the WHILE
modifier.

Program Control

3-5

You can use the keywords WHILE and NEXT to create a multi-line loop. The general format for
WHILE loops is:
WH ILE cond-exp
statement( s)
NEXT

where:
cond-exp

Is a conditional expression.

The loop executes repeatedly for as long as the conditional expression is true. For example:
5 A = 0
10 WHILE A < 10
20
PRINT A
A = A + 1

40 NEXT
50 END

BASIC executes lines 20 and 30 as long as variable A is less than 10. Thus the program prints
numbers 0 through 9.
A WHILE-NEXT loop, unlike a FOR-NEXT loop, has no explicit control variable. Unless the conditional expression is initially false, your program must either: 1) change a variable in the conditional
expression (as in line 30 of the previous example) or 2) transfer control out of the loop. Otherwise, the
loop executes indefinitely. For example:
READ A$
WH I LE A$ <)- II END II
PRINT A$
READ A$
NEXT
DATA ONE t II TWO II t THREE t

100
200

500
GOO

"END II

This loop executes until A$ is assigned the value "END" (the final value in the DATA statement).

3.1.3 UNTIL-NEXT Loops
UNTIL-NEXT loops let you repeat the execution of a block of statements until a given condition is
true. If you want to repeat the execution of a single statement until a given condition is true, you
should use the UNTIL modifier. See Section 3.6.5 for more information about the UNTIL modifier.
You can use the keywords UNTIL and NEXT to create a multi-line loop. The general format for
UNTIL-NEXT loops is:
UNTIL cond-exp
statement( s)
NEXT

where:
cond-exp

3-6

Is a conditional expression.

Program Control

The loop executes repeatedly for as long as the conditional expression is false. For example:
10

UNTIL AI = 10%
PRINT Ai.,
A:~

A'Z + 1 'Z

NE}{T
END

The NEXT statement does not increment a control variable: your program must change a variable in
the conditional expression or the loop executes indefinitely.
UNTIL and FOR loops differ because BASIC exits UNTIL loops as soon as the test for the terminating
condition is met. This test occurs after BASIC executes the NEXT statement and before it executes the
UNTIL statement. For example, this loop executes 10 times:
10

FOR 1% = 1% TO 10%

A = A + 1
PRINT A
50

NEXT 1%
END

When BASIC leaves the FOR loop, 1% equals 10. However, the following UNTIL loop executes only
nine times:
5

I 'X = 1 %

UNTIL Ii., = 10%
PRINT I'X
Ii., = 1% + 1%
END

After the ninth iteration, the conditional expression in line lOis true; control then passes to line 50.

3.1.4 Nested Loops
When a loop block is entirely contained in another loop block, it is called a nested loop. For
example:
10

DECLARE
INTEGER
Row_nuMbert

REAL

&
&:
&
&:
&

Two_diM_arrav (15%t 15%)
FOR Row_nuMber = 0% TO 15%
FOR ColUMn_nuMber = 0% TO 15%

NE}n Row_nulTlber
END
This program declares a two-dimensional array and uses nested FOR-NEXT loops to initialize array
elements. The inner loop executes 16 times for each iteration of the outer loop. The program assigns
zero to each of the 256 elements in the array.

Program Control

3-7

Note that the inner loop is entirely contained in the outer loop. Nested loops cannot "overlap." For
example, this nested loop is invalid:
DIM X_ARRAY(10tl0)
FOR 1% = 0% TO 10%
FOR J% = 0% TO 10%
}·LARRAY (Ii.. tJ%)
NE}-{T 1%
NEXT J%

100
200
300
400
500
600

When it encounters inval id nested loops, BASIC signals the compile-time error "Illegal loop nesting".

3.1.5 Explicit Loop Control (ITERATE and EXIT Statements)
The ITERATE and EXIT statements let you explicitly control loop execution. These statements can be
used only within FOR, WHILE, or UNTIL loops. EXIT can be used only when these loops have been
labeled. The format for ITERATE is:
ITERATE [label-name]
where:
label-name

Is the label of the first statement of a loop. If you supply a label name, ITERATE
transfers control to the specified loop's NEXT statement. If you omit the label name,
ITERATE transfers control to the NEXT of the innermost loop that is currently
executing.

ITERATE is equivalent to an unconditional branch to the loop's NEXT statement. The format for
EXIT is:
EXIT label-name
where:
label-name

Is the label of the current loop. Note that unlike ITERATE, EXIT requires that you
supply a label name.

EXIT transfers control to the first statement following the specified loop.
This example shows the use of the EXIT statement:
10

DECLARE
REAL
Operation_result(3) t
l.)alue_lt
l.)alue_2
PRINT
PRINT

X * Y

Be
Be

l!.:
Be

}.{ /

}{ + y

WHILE 1 i..
1 i..
READ Value_l t Value_2
EXIT Process_value IF Value_2

3-8

Program Control

}{ -

y II

PRINT USING "##.## ##.##
t
\.lalue_l t \.Jalue_2;
Operation_result(O)
Value_l * Value_2
Operation_result(l)
Value_l / Value_2
Oper~~ion_re~ult(2)
Value_l + Value_2
Operation_result(3)
Value_l
Value_2
FOR II = 0% TO 3%
PRINT USING "####.#### l i t Operation_result(II);
NE}{T II
PRINT
II

32767

NE}-{T
DATA
o • 50 to. 50 to. 50 t
1 .00 to. 50 t
1 .00 t
0.00, 0.00
END

1 .00 t
1 .00 t

RUNNH

0.50
0.50
1.00
1.00

0.50
1.00
0.50
1.00

0.2500
0.5000
0.5000
1.0000

}.{

1.0000
0.5000
2.0000
1.0000

}-{

+ y

1.0000
1.5000
1.5000
2.0000

}-{

- y

0.0000
-0.5000
0.5000
0.0000

The WHILE loop in this program executes until Value_2 is equal to zero. At this point, the EXIT
Process_value statement explicitly transfers control out of the loop. Note that the EXIT statement
contains an IF modifier to test whether Value_2 is equal to zero.
This example shows the use of both the EXIT and ITERATE statements.
100

32767

DECLARE STRING User_strinf
Read_loop:
WHILE 1 'X, = 1 i.,
LINPUT "Please t}'pe a strinf"; User_strinf
IF User_strinf == 1111
THEN EXIT Read_loop
ELSE PRINT "Lenfth is ";LEN(User_strinf)
ITERATE Read_loop
END IF
NEXT
END

This program explicitly exits the loop if you type a carriage return in response to the prompt. If you
type a string, the program prints the length of the string and explicitly reexecutes the loop.

3.2 Branching Unconditionally (GOTO Statement)
The GOTO statement specifies the next line that BASIC is to execute, regardless of that line's position
in the program. Its format is:
GOTO

lin-num
}
{ label-name

If you specify a line number or label, it must exist in your program.
If the statement at the target line number or label is nonexecutable (for example, a REM statement),
BASIC transfers control to the next executable statement.

Program Control

3-9

You can use a GOTO statement to exit from a loop; however, it is better programming practice to use
the EXIT statement to do this. You cannot use the GOTO statement to exit from a DEF function
definition. If you try to transfer control into or out of a DEF, BASIC signals either "Jump into DEF" or
"Jump out of DEF" when the program is compiled. The only valid way to exit from a DEF is with an
END DEF, FNEND, EXIT DEF, or FNEXIT statement.
The GOTO statement must be either: 1) the only statement in a block of statements or 2) the last
statement in a block of statements. If you place a GOTO statement in the middle of a block, BASIC
cannot execute the statements remaining in that block.
Modular programming standards dictate that the number of GOTO statements be held to a minimum.
Fewer GOTO statements also make the program easier to read. Use control structures - FOR,
UNTIL, and WHILE loops, and the IF-THEN-ELSE and SELECT-CASE constructions - wherever
possible.

3.3 Branching Conditionally
Conditional branching is the transfer of program control only when specified conditions are met.
Three BASIC statements let you conditionally transfer control to a target statement in your program:
• The ON-GOTO-OTHERWISE statement
• The IF-THEN-ELSE statement
• The SELECT-CASE statement
The ON-GOTO-OTHERWISE statement uses the value of a control variable to determine the target
statement. The IF-THEN-ELSE construction uses conditional expressions to determine which program
branch to take. The SELECT-CASE allows for the execution of anyone of a number of alternative
statement blocks depending on the value of the expression you supply.

3.3.1 ON-GOTO-OTHERWISE Statement
The ON GOTO statement transfers control to one of several target statements, depending on the
value of a control variable. Its format is:
ON int-vbl GOTO target, ... [OTHERWISE target]

where:
target

Is a line number or label. Note that a comma cannot appear between the last target and
the OTHERWISE keyword.

BASIC tests the value of the control variable, int-vbl. If the value is one, BASIC transfers control to the
first target in the list; if the value is two, to the second target, and so on. If the control variable's value
is less than one, or greater than the number of targets in the list, BASIC transfers control to the target
specified in the OTHERWISE clause. For example:

100
200
300
1000
1050

PRINT "WOULD YOU LIKE TO CHANGE:"
PRINT "1. FIRST NAME"
PRINT "2. LAST NAME"
INPUT CHOICE%
ON CHOICE% GOTO 1000, 1100 OTHERWISE 32766
INPUT "FIRST NAME"; FIRSTNAME$
GOTO 32767

3-10

Program Control

1100

INPUT "LAST NAME"; LASTNAME$

32788
32787

PRINT IIINt.IALID CHOICE"
END

This program prompts for changes to one of two variables. If you enter "1", BASIC transfers control to
line 1000; if you enter "2", BASIC transfers control to line 1100. If you enter any other value, BASIC
transfers control to line 32766.
If you do not supply an OTHERWISE clause and the control variable's value is less than one or greater
than the number of targets, BASIC signals "ON statement out of range" (ERR = 58).
This example shows the use of labels in ON-GOTO-OTHERWISE:
100

AsK:
PRINT
PRINT
PR'INT
PRINT
PRINT
INPUT
ON N%

"Would YOU li~\e to:1I
"Change first nafTle (1)"
IIChange last nalTle (2)"
"Change fTliddle initial (3)11
"Exit froM the prograM (4)"
IIT}'pe a nUlTlber ll ; N%
GOTO Firstt Lastt Middlet Done OTHERWISE Bad_input

First:
PRINT
INPUT "Fi rst nalTle" ;Fi rst_nafTle$

PRINT
GOTO Done
Last:
PRINT
INPUT IILast nalTle" ;Last_naITle$

PRINT
GDTO Done
Middle:
PRINT
INPUT "Middle initial";Middle_I$

PRINT
GOTO Done

PRINT
PRINT "Inl}alid I}aluet please tr}' again"
PRINT
GOTO AsK
Done:
END

Program Control

3-11

3.3.2 IF-THEN-ELSE and END IF Statements
The IF-THEN-ELSE statement evaluates a conditional expression and uses the resulting value to
determine which block of statements to execute next. Its format is:

~tatement"'1

THEN
IF cond-exp

GOTO

IIn-num

target

[ I
ELSE

lin-num
statement...

[ END IF]

where:
target

Is either a line number or a label.

The END IF keywords terminate the IF statement. All statements between the ELSE keyword and the
next line number or END IF are part of the ELSE clause.
Note that IF-THEN-ELSE is most useful for executing blocks of statements. If you want to conditionally execute a single statement, you should use the IF modifier. See Section 3.6.1 for more information on the IF modifier.
In the IF-THEN-ELSE statement, BASIC first evaluates the conditional expression. If it is true, BASIC
executes the statements in the THEN clause and skips the statements in the ELSE clause. If the
conditional expression is false, BASIC skips the statements in the THEN clause and executes the
statements in the ELSE clause. For example:

10 REM THIS PROGRAM FINDS A NUMBER'S SQUARE ROOl
20 INPUT "INPUT NUMBER"; NUMBER
30
IF (NUMBER < 0)
THEN
NUMBER = NUMBER * (-1)
PRINT "THAT SQUARE ROOT IS IMAGINARY"
PR I NT "THE SQUARE ROOT OF I TS ABSOLUTE I.JALUE IS";
PRINT SQR(NUMBER)
ELSE
PRINT "THE SQUARE ROOT IS"; SQR(NUMBER)
END IF
40 END
RUNNH
INPUT NUMBER? -8
THAT SQUARE ROOT IS IMAGINARY
THE SQUARE ROOT OF ITS ABSOLUTE VALUE IS 3
BASIC evaluates the conditional expression "NUMBER < 0" in line 30. If the input value of variable
NUMBER is less than zero:
• The conditional expression is true.

3-12

Program Control

• BASIC executes the four statements in the THEN clause and skips the statement in the ELSE clause.
BASIC transfers control to the statement following the END IF, or, if there is no END IF statement, to
the next line number.
If the value of NUMBER is greater than or equal to zero:
• The conditional expression is false .
• BASIC skips the statements in the THEN clause and executes the statement in the ELSE clause.

The THEN and ELSE clauses can contain line numbers instead of statements. For example:

100 INPUT "TYPE A l.JALUE FOR l.JARIABLE 'A '''; A
110 IF A = 0 THEN 120 ELSE 140
120 PRINT "A EQUALS ZERO"
130 GOTO 150
140 PRINT "A DOES NOT EQUAL ZERO"
150 END

However, recommended programming practice is to include the GOTO keyword for readability and
ease of program maintenance.
If you do not specify an ELSE clause and the conditional expression is false, BASIC executes the first
numbered line following the IF statement. For example:

10 INPUT "TYPE A l.JALUE FOR l.JARIABLE 'A ''';A
20 IF A=O THEN PRINT "A EQUALS ZERO"\GOTO 40
30 PRINT "A DOES NOT EQUAL ZERO"
40 END
RUNNH

TYPE A VALUE FOR VARIABLE 'A'? 5
A DOES NOT EQUAL ZERO

The END IF statement lets you explicitly end an IF-THEN-ELSE block. Its format is:
END IF

The END IF statement is useful because it is not always easy to tell where the IF-THEN-ELSE block
ends. For example:

100

IF (A% =) 50%)
THEN PRINT "Ai.. is greater than or equal to 50"
ELSE PRINT "Ai.. is less than 50"
GOTO 1000

Program Control

3-13

In this example, the GOTO statement is part of the ELSE clause. However, the indentation makes it
look as though the GOTO should be executed whether the conditional expression is true or false.
With the END IF statement, you can explicitly end the IF-THEN-ELSE:
100

IF (A% =) 50%)
THEN PRINT "Al. is greater than or equal to 50;;
ELSE PRINT "A% is less than 50"
END IF
GOTO 1000

In this example, the END IF statement explicitly ends the IF block; therefore, BASIC does not treat the
GOTO statement as part of the ELSE clause. If there is no END IF statement, the next numbered line
marks the end of the IF-THEN-ELSE block. Note that while line numbers terminate IF-THEN-ELSE
blocks, labels do not.
If an IF-THEN-ELSE block is preceded by a label, you can use the EXIT statement to transfer control
out of the IF-THEN-ELSE block. For example:
100
200

DECLARE LONG CONDITION
ASK_BLOCK:
PRINT "Please type a TRUE/FALSE value"
INPUT "Zero for FALSE, Minus one for TRUE"; CONDITION
IF_BLOCK:
IF CONDITION = 0%
THEN
PRINT "False"
GOTO DONE
ELSE
PRINT "True"
EXIT IF_BLOCK IF CONDITION = -1%
PRINT "But value is not equal to Minl.ls"
PRINT "one. Please t f ' t again"
GOTO ASK_BLOCK
END IF
DONE:

END

In this program, if the CONDITION variable is anything other than zero, control is transferred to the
ELSE clause and the first statement in the ELSE clause is always executed. The second statement in the
ELSE clause transfers control out of the IF block if the CONDITION variable is minus one. The
remaining statements in the ELSE clause are executed only if the value of CONDITION is other than
minus one.
The EXIT statement transfers control to the statement immediately following the END IF statement. If
there is no END IF statement, EXIT transfers control to the next line-numbered statement.

3.3.3 SELECT-CASE Statement
The SELECT-CASE construction lets you specify an expression, the possible values the expression
may have, and a list of statements to be executed for each possible value. The END SELECT statement
terminates the SELECT-CASE construction. The code between SELECT and END SELECT is called a

3-14

Program Control

SELECT block, and the code between CASE statements is called a CASE block. Each statement in a
SELECT block can have its own line number. The SELECT-CASE format is:
SELECT seleet-exp
CASE [relation] case-item

statement( s)
CASE case-item [, ... ]

statement( s)
CASE case-item TO case-item [,ease-item TO ease-item][, ... ]

statement( s)
[CASE ELSE

statement( s)]
END SELECT

where:
seleet-exp

Is the expression to be tested. Select-exp can be numeric or string.

relation

Is a relational operator specifying the test to be performed.

case-item

Is either an expression to be compared with the select expression or a range of values
separated with the keyword TO. Multiple ranges are valid and can be separated with
commas.

ELSE

Specifies the statements to be executed if no match is found in the previous CASE
statements.

When a match is found between the select-expression and a case-item, all the statements in the
following CASE block are executed. Control is then transferred to the statement following the END
SELECT statement.
You can specify case-items whose values overlap. If there are overlapping values, the statements
associated with the first matching CASE statement are executed. For example:
1000

SELECT X% + Y% + Z%
CASE = OX.
PRINT "}{X. + Y% +
CASE 1 % TO 100X.
PRINT "X% + Yi.. +
CASE SO'x, TO 200%
PRINT II }{X. + Y% +
CASE ELSE
PRINT II}{ 7.. + Y% +
END SELECT

ZX.

equals

Zi..

betiAleen

1 and

Zi..

betiAleen

101

not

100"

an d 200"

selected

ran ~e"

In this example, values between 90 and 100 are always handled by the first case block.
Note that if you do not supply a CASE ELSE and no matches are found, control is transferred to the
statement following the END SELECT statement.
Specifying a list of CASE items is also very useful, for example, when coding an error handler:
ON ERROR GoTo Err_routine

!•
!•
!•
(continued on next page)

Program Control

3-15

100

Get_file_spec:
! t
!+
!+

200

Input_nuMber:
! +
! +
! +

lS000

GOTO 32767

SELECT ERR
CASE 1 t2,5 t6

2
5
6

?Bad directory for device
?Ille~al file naMe
?Can't find file or account
?Not a valid device

PRINT IIProbleM with file specification
RESUME 100

CASE 4St51 t52
4S
51
52

?Floatin~

?Inte~er

= ?Ille~al

point error or overflow
error or overflow
number

PRINT IIBad number
RESUME 200

CASE ELSE
PRINT IIUnexpected error -ON ERROR GOTO 0

exitin~1I

END SELECT
32767

END

The first CASE block traps errors that might be encountered when tryin'g to open a file. The second
CASE block traps errors that might be encountered when assigning numeric values from the terminal.
The CASE ELSE block tells BASIC to handle any other errors.
If a SELECT block is preceded by a label, you can use the EXIT statement to transfer control out of the
SELECT block. For example:
100
200
300

DECLARE LONG S_NUM
INPUT "Please t}'pe a value betlAleen 1 and 8
SELECT_BLOCK:
SELECT S_NUM
CASE 1 TO 3
PRINT IIValue is It 2t or 3
EXIT SELECT_BLOCK IF S_NUM
PRINT "Value is 2 or 3"
EXIT SELECT_BLOCK IF S_NUM
PRINT "1.JaIIJe is 3"

3-16

Program Control

;

S_NUM

CASE

aoo
32787

a TO 8

PRINT III)alue is at 5t or 8"
EXIT SELECT_BLOCK IF S_NUM
a
PRINT III)alue is 5 0 r 8"
EXIT SELECT_BLOCK IF S_NUM = 5
PRINT III.lalue is 8"
CASE 7 TO 8
PRINT III.Jalue is 7t St or 8"
EXIT SELECT_BLOCK IF S_NUM
7
PRINT "l.lalue is S or 8"
EXIT SELECT_BLOCK IF S_NUM
S
PRINT "I.,lalue is 8"
CASE ELSE
PRINT "Value out of range"
END SELECT
GOTO 200
END

This program transfers control out of the labeled SELECT block if S_NUM contains certain values.
The EXIT statement transfers control to the statement immediately following the END SELECT
statement.

3.4 Executing Local Subroutines
In BASIC, a subroutine is a block of code accessed by a GOSUB or ON GOSUB statement. It is
always in the same program unit as the statement that calls it. The RETURN statement in the subroutine returns control to the statement immediately following the GOSUB.
The first line of a subroutine can be any valid BASIC statement, including a REM statement. You need
not transfer control to the first line of the subroutine. Instead, you can include several entry points into
the same subroutine. Similarly, you can nest subroutines by using a GOSUB or ON GOSUB statement in a subroutine.
Variables and data in a subroutine are global to the program unit in which the subroutine resides.

3.4.1 GOSUB and RETURN Statements
The GOSUB statement unconditionally transfers control to a line in a subroutine. The last statement
in a subroutine is a RETURN statement, which returns control to the first statement after the calling
GOSUB. A subroutine can contain more than one RETURN statement so you can return control to the
calling if a specified condition is true. The GOSUB statement's format is:
GOSUB target

where:
target

Is a line number or label entry point to the subroutine. The line number or label must
exist in the current program.

The RETURN statement's format is:
RETURN

For example:
100

A=5

GOSUB TJ,..lo_tilrles
PRINT A

(continued on next page)

Program Control

3-17

A=15
GOSUB Two_tiMes
PRINT A
A=25
GOSUB T. . 'o_tiMes
PRINT A
GO TO Done

! This is the subroutine entrY point
A=A*2
RETURN

Done:
END
RUNNH
10
30
50

The program first assigns a value of five to the variable A, then transfers control to the subroutine
labeled Two_times. The subroutine replaces the value of A with A multiplied by two. The subroutine's RETURN statement transfers control to the first PRINT statement, which displays the
changed value. The program calls the subroutine twice more, with different values for A. Each time,
the RETURN transfers control to the statement immediately following the corresponding GOSUB.
Note that BASIC signals "RETURN without GOSUB" if it encounters a RETURN statement without
having encountered a previous GOSUB or ON GOSUB statement.

3.4.2 ON-GOSUB-OTHERWISE Statement
The ON-GOSUB-OTHERWISE statement transfers control to one of several target subroutines
depending on the value of a numeric expression. A RETURN statement returns control to the first
statement after the calling ON GOSUB. A subroutine can contain more than one RETURN statement so you can return control to the calling statement if a specified condition is true. The
ON-GOSUB-OTHERWISE statement's format is:
ON int-exp GOSUB target, target. .. [OTHERWISE target]

BASIC tests the value of the integer expression. If the value is one, control transfers to the first line
number or label in the list; if two, to the second line number or label, and so on. If the control
variable's value is less than one or greater than the number of targets in the list, BASIC transfers
control to the line number or label specified in the OTHERWISE clause. If you do not supply an
OTHERWISE clause and the control variable's value is less than one or greater than the number of
targets, BASIC signals liON statement out of range" (ERR = 58). For example:
100
200
1000
1100

INPUT "Please enter 1 t 2 or 3"; AI..
ON Al GOSUB 1000, 2000, 3000, OTHERWISE ERR_ROUTINE
GOTO Done
PRINT "That . . Ias a I"
RETURN

3-18

Program Control

2000
2100
3000
3100

PRINT "That IAlas a 2"
RETURN
PRINT "That ",las a 3"
RETURN
ERR_ROUTINE:
PRINT "Out of range"
GOTO 100
Done:
END

If a GOSUB or ON GOSUB statement occurs in a DEF, its target statement must also be in that DEF.
This means that you cannot share a subroutine among DEFs. However, you can code this as a DEF
with no arguments instead of as a subroutine. This DEF can be invoked by other DEFs.
12
r:: Sll~pondinn
..
~.~
"'~
"". • i.::t ~n'"
_ •• - •I-I~ltinn
.- ••••• ~ Prnnr~rn
• • -~. _... ~_X~_r.
-- __ I_lt.. !· n_n

Two statements suspend program execution:
• SLEEP
-WAIT
A BASIC program automatically halts and closes all fi les after execution of its last statement. However, you can explicitly halt program execution by using:
• The STOP statement
• The END statement
The STOP statement does not close files. It can appear anywhere in a program. The END statement
closes files and must be the last statement in a main program.

3.5.1 SLEEP Statement
The SLEEP statement suspends program execution for a specified number of seconds. Its format is:
SLEEP int-exp

where:
int-exp

Is the number of seconds BASIC waits before resuming execution.

For example:
10 INPUT "TYPE A STRING OF CHARACTERS";C$
20 SLEEP 1201.
30 PRINT C$
40 ENO

This program waits two minutes after receiving the input string, then prints it.
The SLEEP statement is useful if you have a program that depends on another program for data.
Instead of constantly checking for a condition, the SLEEP statement lets you check at specified
intervals.

Program Control

3-19

3.5.2 WAIT Statement
You use the WAIT statement only with terminal input statements such as INPUT, INPUT LINE, and
LlNPUT. Its format is:
WAIT int-exp
where:
int-exp

Specifies the number of seconds BASIC waits for response to an input statement. This
number must be between zero and 255, inclusive.

For example:
10 WAIT 30%
20 INPUT "YOU HAI.lE THIRTY SECONDS TO TYPE YOUR PASSWORD"; PSW$
30 END
This program prompts for input, then waits 30 seconds for your response. If the program does not
receive input in the specified time, BASIC signals "Keyboard wait exhausted" (ERR = 15).
The WAIT statement affects all subsequent INPUT, INPUT LINE, LlNPUT, MAT INPUT, and MAT
LlNPUT statements. To disable a previously specified WAIT, use WAIT 0%. For example:
10 WAIT 307..
20 INPUT "YOU HAI.lE 30 SECONDS TO TYPE YOUR PASSWORD"; PSW$
30 WAIT 0%
40 PRINT "DO YOU WANT TO USE:"
50 PRINT "ORDER ENTRY SYSTEM?"
60 PRINT "ACCOUNTS RECE I I)ABLE?"
70 PRINT "OR ACCOUNTS PAYABLE?"
80 INPUT APPLICATION_PACKAGE$
The INPUT statement in line 20 requires a response within 30 seconds. The WAIT 0% statement in
line 30 disables this 3D-second requirement for subsequent INPUT statements.

3.5.3 STOP Statement
The STOP statement is a debugging tool that lets you check the flow of program logic. STOP suspends
program execution but does not close files. Its format is:
STOP

When BASIC executes a STOP statement, it prints "STOP at line lin-num". If the program executes in
the BASIC environment, BASIC then prompts with the command level prompt. In response, you can
type:
• Immediate mode statements
• CONT (to continue program execution)
You use the STOP statement when debugging in immediate mode in the BASIC environment. Refer to
Chapter 1 in BASIC on VAX/VMS Systems, BASIC on RSX-llM/M-PLUS Systems, or BASIC on
RSTS / E Systems for more information on immediate mode.

3-20

Program Control

If a program containing a STOP statement is compiled, linked or task-built, and executed, you see a
pound sign (#) prompt when the STOP statement is encountered. In response to the pound sign
prompt, you can type:
• CONT (to continue program execuiion)
• EXIT (to return to system command level)
The features of the BASIC environment are not available if you execute the program outside of the
BASIC environment.

3.5.4 END Statement
The END statement marks the end of a main program. Execution of the END statement closes all files
and halts execution. Its format is:
END

The END statement is optional. However, you should include it for good programming practice. The
END statement must be the last statement in the main program.
If you run your program in the BASIC environment, the END statement returns your terminal to BASIC
command level. If you execute the program outside of the BASIC environment, the END statement
returns your terminal to system command level.

3.6 Executing Statements Conditionally
Statement modifiers are keywords that qualify or restrict a statement. They let you: 1) execute a
statement conditionally or 2) create an implied loop.
BASIC has five statement modifiers:
• IF
• UNLESS
• FOR
• UNTIL
• WHILE
A statement modifier affects only the statement immediately preceding it. You can modify only
executable statements. Declarative statements are not modifiable. For example, these statements are
not modifiable:
• COMMON
• DECLARE
• EXTERNAL
• FUNCTION
• MAP
• SUB

Program Control

3-21

3.6.1 IF Modifier
The IF modifier tests a conditional expression. If the conditional expression is true, BASIC executes
the statement. If false, BASIC executes the next statement. The format is:
statement IF cond-exp
where:
cond-exp

Is any conditional expression.

For example:

10 PRINT X IF X <> 0
This takes less space than the equivalent IF-THEN-ELSE statement:

IF X <> 0
THEN
PRINT >{
END IF

No THEN or ELSE clause can follow an IF modifier. However, a statement in a THEN or ELSE clause
can be followed by a modifier. In this case, IF applies only to the preceding statement. For example:

IF A = B
THEN
PRINT A IF A
3
ELSE
PRINT B IF B > 0
END IF

3.6.2 UNLESS Modifier
The UNLESS modifier tests a conditional expression. BASIC executes the modified statement only if
the conditional expression is false. Its format is:
statement UNLESS cond-exp
where:
cond-exp

Can be any cond itional expression.

For example:

10 PRINT A UNLESS A

This is equivalent to:

10 PRINT A IF A <> 0

3.6.3 FOR Modifier
The FOR modifier creates a loop on a single line. Its format is:
statement FOR ctrl-vbl = num-exp1 TO num-exp2 [STEP num-exp3}
3-22

Program Control

where:
ctrl-vbl

Is the control or index variable that is incremented or decremented each time the
loop executes. Ctrl-vbl must be a simple (unsubscripted) variable.

num-exp1

Is the starting value for the control variable.

num-exp2

Is the ending value for the control variable.

num-exp3

Is the amount added to the control variable each time the loop executes.

For example:
10 A = A + 1 FOR 1% = 1% TO 10%

This single-line loop is equivalent to:
10 FOR 1%
20
A
30 NEXT 17..

= 1% TO 10%
=A + 1

3.6.4 WHILE Modifier
The WHILE modifier repeats a statement as long as a conditional expression is true. Like the UNTIL
and FOR modifiers, it lets you create single line loops. Its format is:
statement WHILE cond-exp
where:
cond-exp

Can be any conditional expression.

For example:
10 A = A / 2 WHILE ABS(A)

> .1

BASIC replaces the value of A with A/2 as long as the absolute value of A is greater than 1/10.
The WHILE modifier may create an infinite loop if its parts are logically unrelated. For example:
10 A
20 }-{

X + 1 WHILE A < 1000

The statement in line 20 never reaches a terminating condition.

3.6.5 UNTIL Modifier
The UNTIL modifier, like the FOR modifier, creates a single-line loop. However, instead of using a
formal loop variable, you specify the terminating condition with a conditional expression. Its format is:
statement UNTIL cond-exp
where:
cond-exp

February 1984

Can be any conditional expression.
Program Control

3-23

The modified statement executes repeatedly as long as the condition is false. For example:
lOB = B + 1 UNT I L (A - B) -: :

0001

Because of inherent precision limitations, you should not use UNTIL loops of the form:
10 Z = Z + 1 UNTIL Z/5 = 100
Because Z / 5 may never exactly equal 100, this loop could execute indefinitely.

3.6.6 Nested Modifiers
You can append more than one modifier to a statement. This is called "nesting" modifiers. BASIC
evaluates nested modifiers from right to left. If the test of the rightmost modifier fails, control passes to
the next statement, not to the preceding modifier on the same line. For example:
10
20
30
40
50

A = 5
B = 10

C = 15
PRINT A IF A = 5 UNLESS C = 15
10
PRINT B UNLESS C = 15 IF B
PRINT C IF B = 10 UNLESS C = 5
END

RUNNH
15
In this example:
• Line 10 assigns values to variables A, B, and C.
• BASIC tests the rightmost modifier in line 20 (UNLESS C = 15). Because C equals 15, the test fails.
BASIC passes control to line 30 without testing the !F modifier in line 20.
• BASIC tests the rightmost modifier in line 30 (IF B = 10). Because B equals 10, this condition is met.
BASIC then tests the UNLESS modifier in line 30. Because C equals 15, this test fails, and control
passes to line 40.
• BASIC tests the rightmost modifier in line 40 (UNLESS C = 5). Because C does not equalS, this
condition is met. BASIC then tests the IF modifier in line 40. Because B equals 10, this condition is
also met. BASIC prints the variable C.
• BASIC passes control to line 50, and the program ends.

3-24

Program Control

Chapter 4
Strings

This chapter defines fixed-length and dynamic strings, explains which you should choose for your
application, and shows you how to use them.
A string is a sequence of ASCII characters. BASIC allows three types of strings:
• Dynamic strings
• Fixed-length strings
• Virtual array strings
A string whose length never changes is a fixed-iength, or static, string. A string whose iength can
change during program execution is a dynamic string. Strings in virtual arrays have both fixed-length
and dynamic attributes. That is, string virtual arrays have a specified maximum length between zero
and 512 characters. During program execution, the length of an element in a string virtual array can
change; however, the length is always between zero and the maximum string size specified when the
array was created. See Section 4.8 and Chapter 9 for more information about virtual arrays.
String constants are always fixed-length. String variables can be either fixed-length or dynamic. A
string variable is fixed-length if it is named in a COMMON, MAP, or RECORD (VAX-11 BASIC only)
statement. If a string variable is not part of a MAP, COMMON, RECORD, or virtual array, it is a
dynamic string.
If a string variable is fixed-length, its length does not change, regardless of the statement you use to
modify it. The length of a dynamic string variable mayor may not change, depending on the
statement used to modify it. See Table 4-1.

4-1

Table 4-1: String Modification

For Fixed-Length
Strings, Changes

For Dynamic
Strings, Changes

LET

Value

Value and Length

LSET

Value

RSET

Value

Terminal I/O
Statements*

Value

Value and Length

Statement

* Terminal 1/0 statements include INPUT, INPUT LINE, LNPUT, MAT INPUT, and so on.

It is more efficient to change a fixed-length string than a dynamic string. Creating or modifying a
dynamic string often causes BASIC to create new storage, and this increases processor overhead.
Modifying fixed-length strings involves less overhead because BASIC simply reuses existing storage.
Although dynamic strings are less efficient, they are often more flexible than fixed-length strings. For
example, to concatenate strings, you just use the LET statement to assign the concatenated value to a
dynamic string variable. You do not have to worry about BASIC truncating the string or adding trailing
spaces to it. However, if this destination variable is fixed-length, you must make sure that it is long
enough to receive the concatenated string, or BASIC truncates the new value to fit the destination
string. Similarly, if you use LSET or RSET to concatenate strings, you must ensure that the destination
variable is long enough to receive the data.

4.1 Using Dynamic Strings
The LET, LSET, and RSET statements all operate on dynamic strings as well as fixed-length strings.
However, LSET and RSET do not change the length of a dynamic string. For example:

LET A$ = ABC
LET B$ = "}{YZ"
LET C$ =
LSET A$ = A$ + B$
LSET C$ = A$ + B$
PRINT A$
PRINT C$
END
II

20
30
40
40

RUNNH
ABC
ABCXYZ
Line 10 assigns the value ABC to A$, XYZ to B$, and six spaces to C$. At line 20, LSET assigns A$ the
value of A$ concatenated with B$. Because the LSET statement does not change the length of the
destination string variable, only the first three characters of the expression A$ + B$ are assigned to
A$. Line 30 uses LSET to assign C$ the value of A$ concatenated with B$. Because C$ already has a
length of six, this statement assigns the value ABCXYZ to it.

4-2

Strings

Like the LET statement, the INPUT, INPUT LINE, and LlNPUT statements can change the length of a
dynamic string, but they cannot change the length of a fixed-length string. For example:

10
20
30
llO
50
GO

LET A$ = ""
PRINT LEN(A$)
INPUT A$
PRINT A$
PRINT LEN(A$)
END

RUNNH

o
? THIS IS A TEST
THIS IS A TEST
14
Line 10 assigns the null string to variable A$. Line 20 uses the LEN function to show that the null
string has a length of zero. Line 30 uses the INPUT statement to assign a new value to A$, and lines
40 and 50 pri nt the new val ue and its length.
You shouid not confuse the null string with a null character. A nuli character is one whose ASCII
numeric code is zero. The null string is a string whose length is zero.

4.2 Using Fixed-Length Strings
If a string variable is part of a MAP, COMMON, or virtual array, a LET, INPUT, LlNPUT, or INPUT
LINE statement changes its value, but not its length. For example:

30
40
50

MAP (FIELDS) STRING FULL_NAME = lOt
ADDRESS = lOt
CITY_STATE = lOt
ZIP = 10
LINPUT "NAME"; FULL_NAME
LINPUT "ADDRESS"; ADDRESS
LINPUT "CITY AND STATE" CIT'r'_STATE
LINPUT "ZIP CODE"; ZIP
EMPLOYEE_RECORD$ = FULL_NAME + HT + ADDRESS + HT &
+ CITY_STATE + HT + ZIP
PRINT EMPLOYEE_RECORDS
END

RUNNH
NAME? JOE SMITH
ADDRESS? GG GRANT AVENUE
CITY AND STATE? NEW YORK NY
ZIP? 01001
JOE SMITH

GG GRANT A

NEW YORK N 01001

The MAP statement at line 10 explicitly assigns a length to each string variable. Because the LlNPUT
statements cannot change this length, BASIC truncates values to fit the ADDRESS and CITY_STATE
variables. Because the ZIP variable is longer than the assigned value, BASIC left-justifies the assigned
value and pads it with spaces. Line 30 uses the compile-time constant HT (horizontal tab) to separate
fields in the employee record.

Strings

4-3

4.3 Assigning and Justifying String Data
The LSET and RSET statements, unlike LET, do not change a dynamic string variable's length. LSET
left-justifies string data, that is, the value you assign with LSET is always in the leftmost position(s) of
the destination variable. Similarly, RSET right-justifies string data; the value you assign with RSET is
always in the rightmost position(s) of the destination variable.
If the value you assign is longer than the destination variable, LSET and RSET truncate the value to the
size of the destination variable. LSET truncates on the right, and RSET truncates on the left.
Similarly, if the value you assign is shorter than the destination variable, LSET and RSET pad the value
to match the size of the destination variable. Padding consists of the spaces required to make the
length of the value match the length of the destination variable. LSET pads on the right, and RSET
pads on the left.

4.4 LET Statement
The LET statement assigns string data to a string variable. The keyword LET is optional. Its format is:
[LET] str-vbl = str-exp

where:
str-vbl

Is a string variable.

str-exp

Is a string expression.

The LET statement changes the length of dynamic strings but does not change the length of fixedlength strings. For example:
10
20

MAP (TEST) STRING ABC
DECLARE STRING ){YZ
MUI."
= "ABC"
){YZ = 1\1':"
PRINT ABCt LEN(ABC)
PRINT }{YZ t LEN (){YZ)
ABC = "A"
}{YZ = II}{ II
PRINT ABCt LEN (ABC)
PRINT }{YZ t LEN (}{YZ)

I\I:~ "

II\I\/~II

RUNNH
ABC

10
3
10
1

\/"'"7

"I':"

A
}{

This program first creates a fixed-length string named ABC by declaring the string in a MAP statement.
The program then creates a dynamic string named XYZ by declaring it in a DECLARE statement. Line
20 assigns a 3-character value to both variable ABC and XYZ, then prints the value and the length of
the string variables. Variable ABC continues to have a length of 10: the three characters assigned,
plus seven spaces for padding. The length of the dynamic variable changes with the values assigned
to it.

4-4

Strings

4.4.1 LSEl Statement
The LSET statement left-justifies data and assigns it to a string variable, without changing th€ vadable's length. Its format is:
LSET str-vbl = str-exp

where:
str-vbl

Is a string variable.

str-exp

Is a string expression.

If the string expression's value is shorter than the string variable's current length, LSET left-justifies the
expression and pads the string variable with spaces. For example:

LET TEST$ = "ABCDE"
LSET TEST$ = "}{YZ"
PR I NT '" II; TEST$; "'"
END

20
30
40

RUNNH

The LET statement in line 10 creates the 5-character string variable TEST$. The LSET statement in line
20 assigns the string XYZ to the variable TEST$ but does not change the length of TEST$. Because
TEST$ has a length of five, the LSET statement pads the string XYZ with two spaces when assigning
the value. The PRINT statement in line 30 shows that TEST$ includes these two spaces.
LSET left-justifies a string expression longer than the string variable and truncates it on the right. For
example:

LET TEST$ = IIABCDE II
LSET TEST$ = 1112345678 11
PRINT TEST$
END

10
20
30

RUNNH
12345

The LET statement in line 10 creates the 5-character string variable TEST$. The LSET statement in line
20 assigns the characters 1/12345" to TEST$. Because LSET does not change the string variable's
length, it truncates the last three characters (678).

4.4.2 RSEl
The RSET statement right-justifies data and assigns it to a string variable without changing the variable's length. Its format is:
RSET str-vbl = str-exp

where:
str-vbl

Is a string variable.

str-exp

Is any string expression.

Strings

4-5

RSET right-justifies a string expression shorter than the string variable and pads it with spaces on the
left. For example:

10
20
30
40

LET TEST$ = "ABCDE"
RSET TEST$ = "}{YZ
PRINT "}{" + TEST$
END
II

RUNNH

XYZ

The LET statement in line 10 creates the 5-character string variable TEST$. The RSET statement in line
20 assigns the string XYZ to TEST$ but does not change the length of TEST$. Because TEST$ is five
characters long, the RSET statement pads XYZ with two spaces when assigning the value. The PRINT
statement in line 30 shows that the concatenation of "X" and TEST$ includes these two spaces.
If the string expression's value is longer than the string variable, RSET right-justifies the string expression and truncates characters on the left to fit the string variable. For example:

10
20
30
40

LET TEST$ = "ABCDE"
RSET TEST$ = "887654321"
PRINT TEST$
END

RUNNH
54321
The LET statement in line 10 creates a 5-character string variable, TEST$. The RSET statement assigns
"54321" to TEST$. RSET, which does not change the variable's length, truncates "9876" from the left
side of the string expression.
Note that, when using LSET and RSET, padding can become part of the data:

100

LET A$ = '12345'
LSET A$ = 'ABC'
LET B$ = '12345678'
RSET B$ = A$
PRINT B$

RUNNH
ABC
In this example, the final value of B$ is "

ABC

4.5 Manipulating String Data with String Functions
When used with the LET statement, BASIC string functions let you manipulate and modify strings.
These functions let you:
• Determine the length of a string (LEN)
• Search for the position of a set of characters in a string (POS, INSTR)
• Extract segments from a string (SEG$, MID$, LEFT$, and RIGHT$)

4-6

Strings

• Create a string of any length, made up of any single character (STRING$)
• Create a string of spaces (SPACE$)
• Remove trailing spaces and tabs from a string (TRM$)
• Edit a string (EDIT$)

4.5.1 Finding a String's Length (LEN Function)
The LEN function returns the number of characters in a string as an integer value. Its format is:
LEN(str-exp)
where:
Is any string expression.

str-exp

The length of the string expression includes leading and trailing blanks. For example:
ALPHA$ = "ABCDEFGHIJKLMNOPQRSTUt.JW}{YZ"
PRINT LEN(ALPHA$)
Z$ = "ABC" +"
"+ "}{YZ"
PRINT LEN(Z$)
END

10
20
30
40
50
RUNNH

The variable Z$ is set equal to "ABC

XYZ", which has a length of eight.

4.5.2 Position Functions (POS and INSTR)

pas and INSTR both search a string for a group of characters (a substring). Their formats are:
POS(str-exp1, str-exp2, int-exp)
and
INSTR(int-exp, str-exp1, str-exp2)
where:
str-exp1

Is the string to be searched.

str-exp2

Is the substring for which you are searching.

int-exp

Is the character position where BASIC starts the search.

pas

The position returned by
and INSTR is relative to the beginning of the string, not the starting
position of the search. For example, if you search the string" ABC DE" for the substring "E", it does
not matter whether you specify a starting position of one, two, three, four, or five; BASIC still returns
the value five as the position where the substring was found.

Strings

4-7

If the function finds the substring, it returns the position of the substring's first character. Otherwise, it
returns zero. For example:

ALPHA$ = ABCDEFGH I JK LMNoPQRSTUI.JWHYZ
Z$ = "DEFG"
H% = PoS(ALPHA$tZ$tl%)
PRINT X%
Q$ = TEST
Y% = PoS(ALPHA$t Q$t 1%)
PRINT Y'Y..
END
II

RUNNH

a
o
If you specify a starting position other than one, BASIC still returns the position of the substring
relative to the beginning of the string. For example:

ALPHA$ = IABCDEFGHIJKLMNoP"
Z$ = "HIJ"
PRINT PoS(ALPHA$t Z$t 7%)
END

RUNNH
8

If you know that the substring is not near the string's beginning, specifying a starting position greater
than one speeds program execution by reducing the number of characters BASIC must search.
You can use the POS function to associate a character string with an integer that you can then use in
calculations. This technique is called a table look-up. For example:

100 DECLARE STRING CONSTANT TABLE =
&
JANFEBMARAPRMAY JUNJULAUGSEPoCTNol.JDEC
DECLARE STRING MoNTHt UPPER_CASE_MoNTHt MESSAGE
DECLARE INTEGER MONTH_LENGTH
DECLARE REAL MoNTH_PoS
II

200 PRINT "Please type the first three letters of a fTlonth"
PRINT liTo end the pr05lrafTlt t}'pe only <RET>";

WHILE 1'Y.. = 1%
INPUT MONTH
UPPER_CASE_MONTH = EDIT$(MoNTHt 32%)
MONTH_LENGTH = LEN(UPPER_CASE_MONTH)
EHIT LooP_l IF MONTH_LENGTH = 0%
IF MONTH_LENGTH = 3%
THEN MONTH_PoS = (PoS(TABLEt UPPER_CASE_MoNTHt 1) + 2) / 3
IF (MoNTH_PoS = 0%) OR (MoNTH_PoS <> FIX(MoNTH_PoS»
THEN MESSAGE =
Inl,lalid abbrel,liationt trY a5lain"
ELSE MESSAGE =
is fTlonth nl.lfTlber" + NUM$(MoNTH_PoS)
END IF
ELSE MESSAGE =
Abbreviation not three characters, trY a5lain"
END IF
II

4-8

Strings

PRINT MONTH; MESSAGE
NEXT
32767 END
RUNNH
Please type the first three letters of a Month
To end the proSraMt type only (RET)? Nov
Nov is Month nUMber 11

This program prompts for a 3-character string, changes the string to uppercase letters and searches
the table string to find a match. The WHILE loop executes indefinitely until a carriage return is typed
in response to the prompt.
Keep these considerations in mind when you use pas and! NSTR:
• If you specify a starting position less than one, pas and INSTR assume a starting position of one.

• If you specify a starting position greater than the searched string's length, pas and INSTR return
zero (unless the substring is nul\).
• When searching for a null string:
If you specify a starting position greater than the string's length, pas and INSTR return the
string's length plus one.
If the string to be searched is also null, pas and INSTR return a value of one.
If the specified starting position is less than or equal to one, pas and INSTR return a value of
one.
If the specified starting position is 1) greater than one and 2) less than or equal to the string's
length plus one, pas and INSTR return the specified starting position.
Note that searching for a null string is not the same as searching for the null character. A null string
has a length of zero, while the null character has a length of one. The null character is an ASCII
character whose value is zero.

4.5.3 SEG$ Function
The SEG$ function extracts a segment (substring) from a string. The original string remains
unchanged. Its format is:
SEG$(str-exp, int-exp1, int-exp2)
where:
str-exp

Is the input string.

int-exp1

Is the position of the first character extracted.

int-exp2

Is the position of the last character extracted.

Strings

4-9

SEG$ extracts from the input string the substring that starts at character position int-exp1, up to and
including character position int-exp2. It returns the extracted segment. For example:
10
20

PR I NT SEG$ ( II ABCDEFG II, 37.., 57..)
END

RUNNH
CDE
If you specify character positions that exist in the string, the length of the returned substring always
equals:
(int-exp2 - int-exp1

+ 1)

Keep these considerations in mind when you use SEG$:
• If int-exp1 is less than one, BASIC assumes a value of one.
• If int-exp1 is greater than int-exp2 or the length of the string, SEG$ returns a null string.
• If int-exp2 is greater than the length of the string, SEG$ returns all characters from int-exp1 to the
end of the string.
• If int-exp1 equals int-exp2, SEG$ returns the character at position int-exp1.
Using the SEG$ function with the string concatenation operator (+), you can replace part of a string.
For example:
A$ = IIABCDEFG II
C$ = SEG$ (A$, 17.., 21.)
PRINT C$
PRINT A$
END

XYZ II

SEG$ (A$, 81., 7%)

RUNNH
AB}{YZFG
ABCDEFG
In this example, when BASIC creates C$, it concatenates the first two characters of A$, the 3-letter
string XYZ, and the last two characters of A$. The original contents of A$ do not change.
You can use similar string expressions to replace characters in any string. A general formula to
replace characters in positions n through m of string A$ with characters in B$ is:
C$ = SEG$(A$,l %,n-1) + B$ + SEG$(A$,m + 1,LEN(A$))
For example, to replace the sixth through ninth characters of the string "ABCDEFGHUK" with
"123456", enter:
10

A$ = IIABCDEFGHIJK II
B$ = 11123458 11
C$ = SEG$(A$,1%,5%) + B$ + SEG$(A$,10%,LEN(A$»
PRINT C$
PRINT A$
PRINT B$
END

4-10

Stri ngs

RUNNH
ABCDE123458JK
ABCDEFGHIJK
123458
The following formulas are more specific applications of the genera! formula.
• To replace the first n characters of A$ with B$:
($ = B$ + SEG$(A$,n + 1,LEN(A$))
• To replace all but the first n characters of A$ with B$:
($ = SEG$(A$,l ,n) + B$
• To replace all but the last n characters of A$ with B$:
($ = B$ + SEG$(A$,(LEN(A$)-n) + 1, LEN(A$))
• To replace the last n characters of A$ with B$:
($ = SEG$(A$,l ,LEN(A$)-n) + B$
• To insert B$ in A$ after the nth character in A$:
($ = SEG$(A$,l ,n) + B$ + SEG$(A$,n + 1,LEN(A$))

4.5.4 MID$ Function
The MID$ function extracts a substring from a string by specifying the substring's starting position and
length. The original string remains unchanged. The format for MID$ is:
MID$(str-exp, int-exp1, int-exp2)
where:
str-exp

Is the input string.

int-exp1

!s the first character position of the substring.

int-exp2

Is the number of characters in the substring.

MID$ extracts from the input string the substring that starts at character position int-expl, and
includes a total of int-exp2 characters. It returns the extracted segment. For example:

10
20
30
40

ALPHA$ = "ABCDEFGH I JKLMNOPQRSTUI.JWXYZ"
PRINT MID$(ALPHA$t 151t 51)
PRINT MID$( "ENCYCLOPEDIA" t 37.. t 87..)
END

RUNNH
OPQRS
CYCLOP
Keep these considerations in mind when you use MID$:
• If int-expl (the substring's first character position) is greater than the string expression's length,
MID$ returns a null string.

Strings

4-11

• If int-expl is less than one, BASIC assumes a starting position of one.
• If int-exp2 (the length of the substring) is less than or equal to zero, MID$ returns a null string.
• If int-exp2 is greater than the number of characters remaining in the string, MID$ returns all the
characters remaining in the string.
Instead of using MID$, you can perform the same operation with SEG$:
MID$(A$, B%, C%)
This is equivalent to:
SEG$(A$, B%, B% + C% - 1%)

4.5.5 LEFT$ Function
The LEFT$ function lets you extract substrings from the left side of a character string. Its format is:
LEFT$(str-exp, int-exp)
where:
str-exp

Is the input string.

int-exp

Is the position of last character extracted, counting from the left side of the input string.

For example:
100

LINPUT IIFile specification? (Do not type a networK node)"; FILESPEC$
COLONPOS = POS(FILESPEC$ t
t 1)
IF COLONPOS = I)
THEN
PRINT "No disK in that file spec."
ELSE
PRINT "That file is on ";LEFT$(FILESPEC$t COLONPOS)
END IF
I:

This program accepts a file specification as an input string and uses the
extract the disk device.

pas and LEFT$ functions to

These restrictions apply to the LEFT$ function:
• If the integer expression is greater than the string's length, LEFT$ returns the entire string .
• If the integer expression is less than or equal to zero, LEFT$ returns a null string.
Instead of using LEFT$, you can use SEG$ to perform the same operation:
LEFT$(A$, B%)
This is equivalent to:
SEG$(A$, 1 %, B%)

4-12

Strings

4.5.6 RIGHTS Function
The'RIGHT$ function extracts a substring from the right side of a string. Its format is:
RIGHT$(sti-exp, int-exp)

where:
str-exp

Is the input string.

int-exp

Is the position of the first character extracted, counting from the left side of the input
string.

BASIC extracts from str-exp the character at the specified position and all characters to the right. For
example:
PR I NT R I GHT$ ( II ABCDEFG II t 3 i.. )
END

10
20
RUNNH
CDEFG

RIGHT$ starts at the third character position of "ABCDEFG" and extracts this character and all others
to the end of the string.
These restrictions apply to the RIGHT$ function:
• If int-exp (the substring's first character position) is greater than the string's length, RIGHT$ returns a
null string.
• If int-exp is less than or equal to zero, RIGHT$ returns the entire string.
Instead of using RIGHT$, you can use SEG$ to perform the same operation:
RIGHT$(A$, B%)
This is equivalent to:
SEG$(A$, B%, LEN(A$))

4.5.7 STRING$ Function
The STRING$ function creates a character string containing multiple occurrences of a single character. Its format is:
STRING$(int-exp1, int-exp2)
where:
int-exp1

Is the length of the returned string.

int-exp2

Is the ASCII value of the character that makes up the string. This value is treated
modulo 256.

Strings

4-13

For example:
10
20
30

OUTS = STRINGS(10%, 65%)
PRINT OUTS
END

RUNNH

AAAAAAAAAA
This program creates a 10-character string containing uppercase As, which have ASCII value 65.
Keep these considerations in mind when you use the STRING$ function:
• If int-expl (the length of the returned string) is less than or equal to zero, STRING$ returns a null
string.
• If int-expl is greater than 65535 (in VAX-ll BASIC) or 32767 (in PDP-ll BASIC-PLUS-2), BASIC
signals an error.

4.5.8 SPACES Function
The SPACE$ function creates a character string containing spaces. Its format is:
SPACE$(int-exp)
where:
Is the number of spaces in the string.

int-exp
For example:

AS = IIABC II
BS = II}{YZ II
PRINT AS + SPACES(3%) + BS
END

RUNNH
ABC

}{YZ

4.5.9 TRM$
The TRM$ function removes trailing blanks and tabs from a string. The input string remains
unchanged. The format for TRM$ is:
TRM$( str-exp)
where:
str-exp

Is any string expression.

For example:

50
60
70

AS = IIABCDE
BS = 1\ I ..:..
FIRSTS = AS + BS
SECONDS = TRMS(AS) + BS
PRINT FIRSTS
PRINT SECONDS
END

4-14

Strings

10
20
30

II \ / \ / -, ..

RUNNH
ABCDE
XYZ
ABCDE}{YZ

The TRM$ function is especially useful for extracting the nonblank characters from a fixed-length
string (for example, a COMMON or MAP, or a parameter passed from a program written in another
language).

4.5.10 EDIT$
The EDIT$ function performs one or more string editing functions, depending on the value of an
argument you supply. The input string remains unchanged. The format for EDIT$ is:
EDiT$(str-exp, int-exp)

where:
str-exp

Is any string expression.

int-exp

Determines the editing function performed.

Table 4-2 shows the action BASIC takes for a given value of int-exp.

Table 4-2: EDIT$ Options

Value of
int-exp

Effect

Discards each character's parity bit (bit 7). Note that you should not use this value for characters in the
DEC Multinational Character Set.

Discards all spaces and tabs.

Discards all carriage returns, line feeds, form feeds, deletes, escapes, and nulls.

Discards leading spaces and tabs.

Converts multiple spaces and tabs to a single space.

Converts lowercase letters to uppercase.

Converts left brackets ([) to left parentheses [(], and right brackets (]) to right parentheses [)].

128

Discards trailing spaces and tabs. (Same as TRM$ function.)

256

Suppresses all editing for characters within quotation marks. If the string has only one quotation mark,
BASIC suppresses all editing for the characters following the quotation mark.

All values are additive; for example, by specifying 168, you can:
• Discard leading spaces and tabs (value 8)
• Convert lowercase letters to uppercase (value 32)
• Discard trailing spaces and tabs (value 128)

Strings

4-15

The following program requests an input string, discards all spaces and tabs, converts lowercase
letters to uppercase, and converts brackets to parentheses:

LINPUT "PLEASE TYPE A STRING";INPUT_STRING$
NEW_STRING$ = EDIT$(INPUT_STRING$, 2% + 32% + sax)
PRINT NEW_STRING$
END

RUNNH
PLEASE TYPE A STRING? 88
88ABC(StS)

abc<TAB)[S,Sl

4.6 Manipulating String Data with Multiple MAPs
Mapping a string storage area in more than one way lets you: 1) extract a substring from a string or
2) concatenate strings. For example:

10 MAP (EMPREC) FIRST_NAME$ = 10,
LAST_NAME$ = 20,
STREET_NUMBER$ = S,
STREET$ = lS,
CITY$ = 20,
STATE$ = 2,
ZIP$ = S,
WAGE_CLASS$ = 2t
DATE_OF_REVIEW$ = 8t
SALARY_YTD$ = 10,
TAX_YTD$ = 10
MAP (EMPREC) FULL_NAME$ = 30t
ADDRESS$ = a8t
SALARY_INFO$ = 30
MAP (EMPREC) EMPLOYEE_RECORD$ = 108

&
&
&:
&
&
&
&
&
&
&
&

These three MAP statements reference the same 108 bytes of data. You can move data into this MAP
in different ways. For example, you can use READ and DATA statements:

100 READ EMPLOYEE_RECORD$
110 DATA "WILLIAM
DA!.JIDSDN
22al
MADISON BL!)D
"SCRANTON
PAla22SAS12/10/78$13t32S.77$S2S.31"

Because all the MAP statements in this example reference the same storage area (EMPREC), you can
access parts of this area through the mapped variables. Consider these examples:

200 PRINT FULL_NAME$
210 PRINT WAGE_CLASS$
220 PRINT SALARY_YTD$
This produces:

WILLIAM
DAVIDSON
AS
$13,32S.77
300 PRINT LAST_NAME$
310 PRINT TAX_YTD$

4-16

Strings

This produces:

DAVIDSON
$925.31
You can assign a new value to any of the mapped variables. For example:

500

Loop_1:
WHILE 1% = lX.
INPUT "Changes? (please t}'pe YES or NO)"; CH$
E}{IT LooP_l IF CH$ = "NO"
PR I NT "1. FIRST NAME"
PR I NT "2. LAST NAME"
PR I NT "3. STREET NUMBER"
PR I NT "a. STREET"
PRINT "5. CITY"
PRINT "B. STATE"
PRINT "7. ZIP"
PR I NT "8. WAGE CLASS"
PRINT "9. DATE OF REVIEW"
PRINT "10. SALARY YTD"
PRINT 1111. TA}{ '(TO"
I NPUT "CHANGE NUMBER"; NUMBERX.
SELECT NUMBERX.
CASE 1 X.
INPUT "FIRST NAME"; FIRST_NAME$
CASE 2%
INPUT "LAST NAME"; LAST_NAME$
CASE 3%
INPUT "STREET NUMBER"; STREET_NUMBER$
CASE ax.
INPUT "STREET"; STREET$
CASE 5%
INPUT "CITY"; CITY$
CASE BX.
INPUT "STATE"; STATE$
CASE 7%
INPUT "ZIP CODE"; ZIP$
rAC!::'

\..tn ..... L-

0''1

\,JI••

INPUT "WAGE CLASS"; WAGE_CLASS$
CASE 9X.
INPUT "DATE OF RElnEW"; DATE_OF_RElnEW$
CASE lOX.
INPUT "SALARY YTD"; SALARY_YTD$
CASE 11 x.
INPUT "TAX YTD"; TA}{_YTD$
CASE ELSE
PRINT "Invalid choice"
END SELECT
327B7

NEXT
END

This produces:

Changes? (please type YES or NO)? YES
1. FIRST NAME
2. LAST NAME
3. STREET NUMBER
4. STREET
5. CITY
B. STATE
7. ZIP CODE
8. WAGE CLASS

(continued on next page)

Strings

4-17

9. DATE OF REVIEW
10. SALARY YTD
11.

TAj.{ YTO

CHANGE NUMBER? 10
SALARY YTD? 14t277.08
Chan!es? (please type YES or NO)? YES
CHANGE NUMBER? 11
TA~< YTD? 998.32
Chan~es? (please type YES or NO)? NO

When you modify a mapped variable, you modify all other variables that overlay the same storage.
For example, after changing the variables SALARY _ YTD$ and TAX_ YTD$, the statement:
10000 PRINT EMPLOYEE_RECORD$

produces:
WILLIAM
DAVIDSON
2241
PA14225A912/10/78$14t277.08$998.32

MADISON BLVD

SCRANTON

You can also move data into a MAP using terminal input, arrays, and files. See Chapter 5 for more
information on the MAP statement.

4.7 Manipulating Strings with the CHANGE Statement
The CHANGE statement: 1) converts a string of characters to an array containing their numeric ASCII
values or 2) converts a list of numbers to a string of ASCII characters. Its format is:
CHANGE str-exp TO num-array
CHANGE num-array TO str-vbl

where:

str-exp

Is any string expression.

num-array

Is a one- or two-dimensional numeric array.

In the first case, when the CHANGE statement is executed, BASIC stores the length of the string
expression in element zero of the array. In the second case, element zero of the array must contain
the length of the string. If the value in element zero is zero, BASIC creates a zero-length, or null,
string.
You should use one-dimensional integer arrays when using the CHANGE statement. If you use arrays
of more than one dimension, BASIC accesses only the array's first row.
The CHANGE statement lets you associate a character position with an array subscript. This is useful
in searching a string for a particular character. For example:
100
200

300
400

DIM INTEGER SEARCH(80%)
PRINT "This prO~ralTl accepts a strin~ of"
PRINT "uP to 80 characters and returns"
PRINT "the character position of the first"
PRINT "occurrence of the character If'."
INPUT "Strin~"; A$
CHANGE A$ TO SEARCH

4-18

Strings

FOR 1% = 1% TO SEARCH(O%)
!SEARCH(O) contains len~th of
IF SEARCHeI'X,) = 102%
!102 is the ASCII value of "fll
THEN PRINT IIlf' 1"las found at position" ;1%

strin~

END IF
GOO
700
1000

NE>n I'X.

IF (1% = SEARCH(O%»
AND (SEARCH(I%) <> 102%)
THEN PRINT IIlf' 1"las not found in input strin~"
END

The CHANGE statement also makes it easy to change characters within a string. For example:
100
200
300
400
500
GOO
700

INPUT "Strin~"; A$
DIM INTEGER ARRAY(SO%)
CHANGE A$ TO ARRAY
FOR Il = 1% TO ARRAY(O%)
IF (97% <= ARRAY(I%»
AND (ARRAY(I%)
THEN ARRAY(I%) = ARRAY(I%) - 32%
NE}'{T 1%
CHANGE ARRAY TO A$
PRINT A$

<= 122%)

This program changes lowercase letters to uppercase. It first accepts an input string and changes it to
an integer array. The FOR statement specifies a starting value of 1 (the first array element) and an
ending value of ARRA Y(O) (because this element contains the length of the string).
In the FOR/NEXT loop, the program tests each array element for values between 97 and 122,
inclusive (these are the ASCII values for lowercase letters). When an array element with one of these
values is found, 32 is subtracted from it. Thus, the value 97 (lowercase " a") is changed to 65
(uppercase II A").
When the entire string has been processed, the CHANGE statement in line 600 converts the array
back to a string. Note that ARRAY(O) still contains the string length assigned by the CHANGE statement in line 300; therefore, the string length does not change.

4.8 Stri ng Vi rtual Arrays
Virtual arrays are stored on disk. You create a virtual array by opening a disk file and then using the
DIM # statement to dimension the array on the open channel. This section describes only string
virtual arrays. See Chapter 9 for more information on virtual arrays.
Elements of string virtual arrays behave much like dynamic strings, except that:
• When you create the virtual string array, you specify a maximum length for the array's elements.
The length of an array element can never exceed this maximum. If you do not supply a length, the
default is 16 characters.
• A string virtual array element cannot contain trailing nulls.
When you assign a value to a string virtual array element, BASIC pads the value with nulls, if
necessary, to fit the length of the virtual array element. However, when you retrieve the virtual array

Strings

4-19

element, BASIC strips all trailing nulls from the string. Therefore, when you access an element in a
virtual string array, the string never has trailing nulls. For example:

10
20
30

40
50

DIM #1%, STRING TEST(5)
DPEN "TEST" AS FILE #1%, ORGANIZATION VIRTUAL
A$ f TEST ( 1 %) = ABCDE + STR I NG$ ( 5i:'. f Oi:'.)
PR I NT
LENGTH OF A$ IS: !!; LEN ( A$ )
PR I NT LENGTH OF TEST ( 1) IS: "; LEN (TEST ( 1 i:'.) )
END
II

II
II

RUNNH
LENGTH OF A$ IS: 10
LENGTH OF TEST(l) IS: 5
Lines 10 and 20 dimension a virtual string array and open a file on channel 1. Line 30 assigns a
10-character string to the first element of this string array, and to the variable A$. This 1O-character
string consists of "ABCDE" plus five null characters. The PRINT statements in lines 40 and 50 show
that the length of A$ is 10, while the length of TEST(1) is only five because BASIC strips trailing nulls
from string array elements.
Although the storage for virtual string array elements is fixed, the length of a string array element can
change because BASIC strips the trailing nulls whenever it retrieves a value from the array.

4-20

Stri ngs

Chapter 5
Data Definition

This chapter describes how you explicitly assign data types to program variables and how to allocate
and use data storage.

5.1 Declarative Statements
Declarative statements are those that define objects in a BASIC program. Objects can be variables,
arrays, constants, and user-defined functions within a program module. They can also be routines,
variables, and constants external to the program module. Declarative statements always assign names
to the objects declared and usually assign other attributes such as a data type to them.
On VAX-11 systems, declarative statements can also be used with user-defined data types (RECORD
statements). See BASIC on VAX/VMS Systems for more information on the RECORD statement.
You use declarative statements to assign data types to: 1) variables, arrays, and named constants and
2) the values returned by functions. By declaring the objects used in your program, you make the
program much easier to understand, modify; and debug.

5.2 Data Types
At its most fundamental level, a data type is a format for information storage. All information is stored
in the computer as bit patterns (groups of ones and zeros). Data types specify that the computer
should interpret these patterns in a certain way.
BASIC programs allow four general data types: integer, floating-point, string, and packed decimal
(VAX-11 BASIC only). Each of these general data types has unique characteristics that determine the
way you use it. For example, integers are useful for numeric computations involving whole numbers,
and strings provide a way to manipulate alphanumeric characters.
Within integer and floating-point data types there are further subdivisions. For example, integers can
be classed as BYTE, WORD, and LONG. Choosing one of these integer subdivisions lets you control
two things: 1) the amount of storage required for the integer and 2) the range of values that the integer
can accept. See Table 5-1 for more information on the range and storage requirements of these
integer subtypes.

5-1

Similarly, floating-point data can be classed as SINGLE, DOUBLE, GFLOAT (VAX-11 BASIC only),
and HFLOAT (VAX-11 BASIC only). See Table 5-1 for more information on the range and storage
requirements of these floating-point subtypes. The choice you make when assigning numeric data
types always involves a tradeoff between storage requirements and precision or range.
In addition to numeric and string data types, BASIC also provides a unique data type called RFA.
Variables of the RFA data type require six bytes of storage and can contain only a Record File
Address. RFA variables are used with RMS file 110 and the operations that can be performed on them
are strictly limited. See Chapter 9 for more information on the RFA data type.
Traditionally, BASIC programs have had just three data types: integer, string, and floating-point. You
assigned a data type to a variable by adding a suffix to the variable names; a dollar sign ($) denoted a
string variable, a percent sign (%) denoted an integer variable, and variable names without suffixes
denoted floating-point variables.
BASIC now lets you explicitly assign data types to variables, parameters, and functions. This feature
gives you more control over the storage and precision used by your program. You can still use
implicit data typing in your programs; however, you should not mix explicit and implicit data typing
in the same statement. You can ensure that all program variables are explicitly declared by using the
ITYPE = EXPLICIT qualifier when you compile your programs, or by specifying explicit data typing
with the OPTION statement. See Section 5.3 for more information on the OPTION statement.
Table 5-1 lists the keywords you use to assign data types and their meanings.

Table 5-1: BASIC Data Types

Data Type
Keyword*

Precision
(decimal
digits)

Range**

Size

INTEGER - specifies integer data
DVTC
U IlL

8 bits

-128 to + i 27

WORD

16 bits

-32768 to + 32767

LONG

32 bits

-2147483648 to
+ 2147483647

REAL - specifies floating-point data
SINGLE
DOUBLE

CHOAT
HHOAT

32 bits
64 bits
64 bits
128 bits

308

.29 * 10- to 1.7 * 10
.29 * 10- to 1.7 * 10
.56 * 10-

4932

.84 * 10-

to .9 * 10

to .59 * 10

15
4932

DEC/MAUd,s)

o to 16 bytes

STRING

One character
per byte

6 bytes

RFA

1 * 10-

* VAX-TT BASIC only data types are italicized.
** Approximate for REAL and DECIMAL data types.

5-2

Data Definition

to 1 * 10

This chapter describes the BASIC statements that explicitly type data (DECLARE, EXTERNAL,
FUNCTION, COMMON, DEF, DIMENSiON, MAP, SUB, and RECORD (in VAX-ll BASiC)) and aiso
descri~es the syntax for explicitly typed constants.
As shown in the table, there are four data-type keywords that specify integer datao Data-type
INTEGER is a general data-type because it specifies only that a variable contains integer data. Datatypes BYTE, WORD, and LONG specify exactly how much storage is allocated to an integer variable.
If you specify data-type INTEGER, the subtype of integer variables depends on the default integer
data-type in effect when the program is compiled. This default is determined by:
• The qualifier you use to compile the program.
• The program's OPTION statement, if present. See Section 5.3 for more information on the OPTION
statement.
Similarly, there are five data-type keywords that specify floating-point data. Data-type REAL is a
general data type because it specifies only that a variable contains floating-point data. Data-types
SINGLE, DOUBLE, GFLOAT, and HFLOAT specify exactly how much storage is allocated to a
floating-point variable. If you specify data-type REAL, the subtype of floating-point variables depends
on the default floating-point subtype in effect when the program is compiled. This default is determined by:
• The qualifier you use to compile the program.
• The OPTION statement, if present. See Section 5.3 for more information on the OPTION statement.
In this manual, BYTE, WORD, and LONG are referred to as subtypes of the INTEGER data type.
SINGLE, DOUBLE, GFLOAT, and HFLOAT are referred to as subtypes of the REAL data type.
It is important to note that choosing a numeric subtype always involves a tradeoff between storage
requirements and range or precision. You can reduce the size of an executable image by choosing the
smallest numeric subtype that is large enough to meet your needs.

5.3 Setting the Default Data Type and Size
There are two ways to set the default data type and size for your program. These are:
• With qualifiers:
-

ITYPE_DEFAULT

IBYTE, IWORD, or ILONG

ISINGLE, IDOUBLE, IGFLOAT (VAX-ll BASIC only), or IHFLOAT (VAX-ll BASIC only)

IDECIMAL_SIZE (VAX-ll BASIC only)

• With the OPTION statement
See BASIC on VAXIVMS Systems, BASIC on RSX-IIMIM-PLUS Systems, or BASIC on RSTSIE
Systems for more information on qualifiers.

Data Definition

5-3

The OPTION statement also sets the default data type and size and can override the defaults set with
qualifiers. When using OPTION to set the default type and size, its format is:
OPTION option-clause, ...
TYPE = type-ciause
SIZE = size-clause
option-clause:

SCALE = int-const

ACTIVE
l
INACTIVE)

= active-clause

(VAX-11 BASIC only)
(VAX-11 BASIC only)

INTEGER
REAL
type-clause:

size-clause:

EXPLICIT
DECIMAL

(VAX-11 BASIC only)

size-item

(size-item, ... )
INTEGER int-clause

size-item:

REAL real-clause
DECIMAL (d,s)

(VAX-11 BASIC only)

BYTE
int-clause:

WORD
LONG
SINGLE
DOUBLE

real-clause:

active-clause:

GFLOAT

(VAX-11 BASIC only)

HFLOAT

(VAX-11 BASIC only)

active-item

(active-item, ... )
INTEGER OVERFLOW
DECIMAL OVERFLOW

active-item:

SETUP

(all VAX-11 BASIC only)

DECIMAL ROUNDING
SUBSCRIPT CHECKING

You can have more than one OPTION statement in a program module; however, OPTION statements
can be preceded only by a SUB, FUNCTION, REM, or another OPTION statement.

5-4

Data Definition

Note that VAX-11 BASIC, the OPTION statement can also specify:
• Integer and packed decimal overflow checking
_

n _____

___ L! __ : __ .a.: __

• rrugr dIll U(JUIIIILdllUII

• Rounding or truncation of packed decimal numbers
• Subscript checking
See the BASIC Reference Manual for more information about OPTION.
This is an example of the OPTION statement:

I OPTION TYPE
SIZE
SIZE

EXPLICIT,
INTEGER WORDt
REAL DOUBLE

Variables Must be declared
&
IS-bit integers
&
Sa-bit floating-point nUMbers &
by default

This statement specifies that:
• All program variables must be explicitly typed
• Any variable typed as INTEGER is a WORD integer
• Any variable typed as REAL is a DOUBLE floating-point number
You can create variables of other data types by explicitly declaring them with the DECLARE
statement.

5.4 Explicitly Declaring Variables (DECLARE Statement)
The DECLARE statement expiicitiy assigns a data type or subtype to a variable, function, or constant.
The format for declaring variables is:
DECLARE data-type vbl [, [data-type] vbl] ...

where:
data-type

Is a subtype optionally preceded by a general data type or a general data type.

vbl

Is a variable or array name that does not end in a percent or dollar sign.

See Table 5-1 for data-type keywords.
The subtype you specify overrides any defaults specified in the BASIC environment or with the
IINTEGER_SIZE, IREAL_SIZE, and IDECIMAL_SIZE qualifiers. For example, if you compile your
program with the IINTEGER_SIZE = WORD qualifier and DECLARE an integer variable to be LONG,
the variable is LONG rather than WORD. In this format of the DECLARE statement, data-type STRING
specifies a dynamic string variable.

Data Definition

5-5

Note
To avoid confusion and to retain BASIC's implicit data typing feature, variable names
ending with a dollar sign or percent sign are invalid in a statement that explicitly
names a data type.
You can define a variable only once in a program. For exampie, if a variabie name appears in a
DECLARE statement, it cannot also appear in a COMMON or MAP statement.
For example:

DECLARE INTEGER

200

ALPHA t ~:
BETA t ~:
GAMMA
DECLARE LONG

300

LAMBDAt &:
EPSILONt &:
CHI
DECLARE REAL

400

DELTAt &:
IOTA t ~:
RHO
DECLARE GFLOAT

500

OMICRONt &:
XIt&:
TAU
The DECLARE statement in line 200 specifies only that variables ALPHA, BETA, and GAMMA are
integers of the default INTEGER subtype. The integer subtype can be specified with the
IINTEGER_SIZE qualifier or with the OPTION statement.
The DECLARE statement in line 300 specifies that variables LAMBDA, EPSILON, and CHI are LONG
integers, overriding any default integer subtype.
Similarly, the DECLARE statement in line 400 specifies only that variables DELTA; IOTA, and RHO
are floating-point numbers of the default REAL subtype. The REAL subtype can be specified with the
I REAL_SIZE qual ifier or with the OPTION statement.
The DECLARE statement in line 500 specifies that variables OMICRON, XI, and TAU are GFLOAT
floating-point variables, overriding any default REAL subtype.
You should use unique variable names to avoid confusion and make program documentation easier.
For example, if you DECLARE variable B to be LONG, there cannot also be a floating-point variable B
in your program. It is possible to have both an implicit integer variable B% and an explicit INTEGER
variable B in the same program; however, this is poor programming practice.
You can also use the DECLARE statement to assign a data type and value to DEF functions and
constants. See Section 5.5 for an explanation of declaring named constants. The format for declaring
DEF functions is:
DECLARE data-type FUNCTION {def-nam [ ( [ def-parm ], ... ) ]}, ...

where:
def-nam

5-6

Is the name of the DEF function. Function names conform to the same rules as variable names; however, the DECLARE statement does not allow names ending with a
percent or dollar sign.

Data Definition

def-parm

Is a BASIC data-type keyword. When you actually invoke the DEF function, BASIC
changes the actual arguments to match the specified data type, if necessary.

DECLARE FUNCTION lets you: 1) assign a data type to parameters and to the value a function returns
and 2) name the function without using the usual convention (beginning the function name with FN
and ending the function name with a percent or dollar sign suffix). For example:
100 DECLARE STRING FUNCTION CONCAT (STRINGt STRING) !Declare the function

1000 DEF CONCAT (STRING Yt STRING Z)
1100 CONCAT = Y + Z
1200 END DEF

!Define the function

20000 NEW_STRING$

!Invoke the function

CONCAT(A$t B$)

32767 END

This format allows only one data type in a single statement. Declaring more than one type of function
requires more than one DECLARE statement.
These new data typing features give you more control over storage allocation. Compiling a program
with ITYPE_DEFAULT = EXPLICIT is particularly useful because it causes BASIC to signal an error
when an implicit variable is encountered. This prevents a typing mistake from being interpreted as a
new variable. DIGITAL supports implicit variables for compatibility with other BASICs and also
because they are useful for beginning programmers. However, DIGITAL recommends that you use
explicit declarations for new program development.

5.5 ExpUcitiy Named Constants
Constants are values that do not change during program execution. You can declare named constants
within a program unit with the DECLARE statement. You can also refer to constants outside the
program unit with the EXTERNAL statement. In addition, VAX-11 BASIC provides notation for binary,
octal, decimal, and hexadecimal constants.
Named constants are useful because:
1.

If a commonly-used constant must be changed, you can make the change in a single place.

They make the program easier to understand.

5.5.1 Declaring Constants Within a Program Unit
The format for declaring constants within a program unit is:
DECLARE data-type CONSTANT {const-nam = value} ,...

Data Defi n ition

5-7

where:
data-type

Is any valid BASIC data type.

const-nam

Is the name of the constant.

value

Is a literal, a previously declared constant, a predefined constant, or an expression
containing literals and previously defined constants.

In PDP-ll BASIC-PLUS-2, you can specify only a single value for floating-point named constants.
That is, the value assigned to named floating-point constants cannot be an expression.
Note that the value assigned to the named constant need not be in the allowable range of the default
data type; however, it must be in the valid range of the data type being declared. For example:

DECLARE LONG CONSTANT XYZ = 1000%

Line 10 declares a LONG constant named XYZ and assigns it a value of 1000. In DECLARE
CONSTANT statements, BASIC signals an overflow error only if the value is outside the range of the
data type being declared.
This example declares a double-precision constant:

100 DECLARE DOUBLE CONSTANT PLANCKS = G.G237E-27
200 INPUT "FREQUENCY"; FREQ
300 PRINT "ENERGY EQUALS"; PLANCKS / FREQ
400 END
A DECLARE CONSTANT statement allows only one data type. To declare a constant of a different
data type, use a second DECLARE CONSTANT statement.

5.5.2 Declaring Constants External to the Program Unit
To declare constants external to the program unit, use the EXTERNAL statement. Its format is:
EXTERNAL data-type CONSTANT const-nam ,...

where:

data-type

Is a data-type keyword. VAX-ll BASIC allows external constants of data-type
BYTE, WORD, LONG, INTEGER, SINGLE, or REAL (if the default size is SINGLE).
BASIC-PLUS-2 allows external constants of data-type WORD or INTEGER (if the
default size is WORD).

const-nam

Is the name of the constant. On VAX /VMS systems, this might be a system status
code, or a global constant declared in a VAX-ll MACRO or VAX-ll BLISS program. On PDP-ll systems, this can be an RMS symbol or a global constant
declared in a MACRO-l1 or FORTRAN program.

The linker or task builder automatically supplies the values for constants specified in EXTERNAL
statements.

5.5.3 Explicitly Formed Literals
By using a special notation, BASIC lets you specify the value and data type of numeric and string
literals. These explicitly formed literals are useful when:
• Passing numeric literals as parameters
• Specifying a numeric literal whose value is outside the allowable range of the default data type

5-8

Data Definition

February 1984

The format of this notation is:
<quote>numeric-string<quote>subtype-abbr
where:
quote

Is either a single or double quotation mark.

numeric-string

Is a string composed of digits, and an optional decimal point. Numeric-string can
also be a number in E format. However, a leading minus sign cannot appear
inside the quotes.

subtype-abbr

Is an abbreviation for a data-type keyword. You cannot use general numeric data
types INTEGER and REAL; you must use a specific subtype abbreviation.

Subtype abbreviations are:
BYTE
WORD
LONGWORD
SINGLE
DOUBLE
GFLOAT (VAX-11 BASIC only)
HFLOAT (VAX-l1 BASIC only)
DECIMAL (VAX-11 BASIC only)

B
W
L
F

o
G
H
P

These are examples or numeric literals:
1/40000"L

Specifies a LONG constant with a value of 40000.

1/32767"W

Specifies a WORD constant with a value of 32767.

1/.000000000001"0

Specifies a DOUBLE constant with a value of 10-12 •

"10ES"F

Specifies a SINGLE constant with a value of 100000.

The value of a numeric literal must be within the allowable range of the default data type, unless you
use this notation. For example:
100
200

DECLARE WORD At Bt C
A = 500

If this program is compiled with / INTEGER_SIZE = BYTE, VAX-11 BASIC reports "Integer error or
overflow" at line 200 because the value 500 is outside the range of the default container size. To
obtain the desired effect, you should use explicit numeric literal notation:
100
200

DECLARE WORD At Bt C
A = 1500"W

Note that this constant notation lets you specify values outside the range of the default data type.
In VAX-11 BASIC, you can also specify a radix for integer literals. The radix can be base 10 (decima!), base 2 (binary), base 8 (octal), and base 16 (hexadecimal). This feature is useful in forming
conditional expressions and in using logical operations, because it provides a means to set or clear
individual bits in the representation of an integer.
Data Definition

5-9

The format for specifying these radices is:
radix"numeric-string"subtype-abbr
where:
radix

Is: 0 (decimal), B (binary), 0 (octai), or X (hexadecimai).

numeric-string

Is a string composed of digits. For binary numbers, numeric-string can contain
the digits a and 1. For octal numbers, numeric-string can contain the digits a
through 7. For hexadecimal numbers, numeric-string can contain the digits a
through 9 and letters A through F.

subtype-abbr

Is an abbreviation for an integer subtype: B (BYTE), W (WORD), or L (LONG).
Note

In VAX-11 BASIC, a "0" can appear in both the radix position and the subtype
position. The "0" that precedes the numeric string specifies decimal radix, not
packed decimal data type. You specify a double-precision floating-point constant with
a 0 in the subtype position. You specify a packed decimal constant with a P in the
subtype position.
It is important to understand that, when you specify a radix other than decimal, BASIC treats the
numeric string as an unsigned integer. However, if this value is assigned to a variable or used in an
expression, BASIC treats the variable as a signed integer. For example:
100

DECLARE WORD A
A = 6'1111111111111111 'W

PRINT A
RUNNH
-1

In this example, BASIC assigns a value to the 16-bit storage location of variable A by setting all the
bits in that location. While the value of 1111111111111111 in base 2 is actually 65535, this number
is not representable in a WORD integer because integers are represented in two's complement
notation. Thus, when BASIC executes the PRINT statement, variable A is displayed as a signed
integer. Because the two's complement representation of -1 is 1111111111111111, BASIC prints a

-1.
BASIC also lets you represent a single-character string in terms of its 8-bit ASCII value. The format is:
radix"numeric-string"C
where:

a (octa!), or X (hexadecimal).

radix

Is: 0 (decimal), B (binary),

numeric-string

Is a subtype abbreviation meaning CHARACTER.

5-10

Data Definition

This feature lets you create your own compile-time string constants containing nonprinting characters. For example:
100 DECLARE STRING CONSTANT CTRL_S = X'13'Ct CTRl_Q = X'll'C
This program declares two string constants named CTRL_S (ASCII hexadecimal value 13) and
CTRL_Q (ASCII hexadecimal value 11).

5.6 Operations Using Multiple Data Types
When an expression contains operands of different data types, it is called a mixed-mode expression.
Before a mixed-mode expression can be evaluated, the operands must be converted, or promoted, to
a common data type. The result of the evaluation may also be converted depending on the data type
of the variable to which it is assigned.
When evaluating mixed-mode expressions, BASIC performs these promotions such that no operand
loses any range or precision. When assigning values to variables, BASIC converts the result of the
expression to the data type of the variable. If the value of the expression is outside the allowable
range of the variable's data type, BASIC signals "Integer error or overflow", "Floating-point error or
overflow", or "DECIMAL error or overflow".
In general, BASIC promotes operands with different data-types to the lowest data type that can hold
the largest and most precise possible value of either operand's data type. BASIC then performs the
operation in that data-type, and yields a result of that data type. If the result of the expression is
assigned to a variable, BASIC converts the result to the data-type of the variable. Table 5-2 lists
the resulting data type for all combinations except those involving DECIMAL (VAX-11 BASIC only)
data types.

Table 5-2: Result Data Types in BASIC Expressions
Operand 2

Operand 1

VAX-ll BASIC

BYTE

WORD

LONG

SINGLE

DOUBLE

GFLOAT

HFLOAT

BYTE

WORD

LONG

SINGLE

DOUBLE

GFLOAT

HFLOAT

WORD

LONG

SINGLE

DOUBLE

GFLOAT

HFLOAT

LONG

SINGLE

DOUBLE

GFLOAT

HFLOAT

SINGLE

DOUBLE

GFLOAT

HFLOAT

DOUBLE

HFLOAT

GFLOAT

HFLOAT

GFLOAT

HFLOAT

Note
GFLOAT and HFLOAT are VAX-l1 BASIC data types only.
As Table 5-2 shows, if one operand is SINGLE and one operand is DOUBLE, BASIC promotes the
SINGLE value to DOUBLE, performs the specified operation, and returns the result as a DOUBLE

Data Definition

5-11

value. This promotion is necessary because the SINGLE data type has less precIsion than the
DOUBLE value, whereas the DOUBLE data type can hold the largest and most precise possible
SINGLE value. If BASIC did not promote the SINGLE value and the operation yielded a more precise
result than was representable in SINGLE, loss of precision would occur.
With one exception, the resulting data type is the same as that of the operand with the higher data
type. The exception is when the operands are DOUBLE and GFLOAT. When an expression contains
a DOUBLE and a GFLOAT operand, BASIC promotes both values to HFLOAT, and returns an
HFLOAT value. This is necessary because a DOUBLE value is more precise than a GFLOAT value,
but cannot contain the largest possible GFLOAT value. Consequently, BASIC promotes these data
types to a data type that can hold the largest and most precise value of either operand.
If all operands in an expression are BYTE, WORD, or SINGLE, all promotions remain within that set
of data types. If all operands in an expression are BYTE, WORD, LONG, or DOUBLE, all promotions
remain within that set of data types.
VAX-11 BASIC also allows the DECIMAL(d,s) data type. DECIMAL values are converted to REAL
before exponentiation. For all other operations involving a DECIMAL value, the number of digits (d)
and the scale or position of the decimal point (s) in the result depend on the data type of the other
operand. If one operand is DECIMAL and the other is DECIMAL or INTEGER, the d and s values of the
result are determined as follows:
• If both operands are typed DECIMAL, and if both operands have the same digit (d) and scale (s)
values, no conversions occur and the result of the operation has exactly the same d and s values as
the operands. Note, however, that overflow can occur if the result exceeds the range specified by
the d value.
• If both operands are DECIMAL, but have different digit and scale values, BASIC always uses the
larger number of specified digits for the result.
For example:
100

DECLARE DECIMAL(S,2) A
DECLARE DECIMAL(4,3) B

Variable A allows three digits to the left of the decimal point and two digits to the right. Variable B
allows one digit to the left of the decimal point and three digits to the right. Therefore, the result
allows three digits to the left of the decimal point and three digits to the right:

A
B
Result
If one operand is typed DECIMAL and one is typed INTEGER, the INTEGER value is converted to a
DECIMAL(d,s) data type as follows:
BYTE is converted to DECIMAL(3,0).
WORD is converted to DECIMAL(S,O).
LONG is converted to DECIMAL(10,0).
BASIC then determines the d and s values of the result by evaluating the d and s values of the
operands as described above.

5-12

Data Definition

February 1984

Note that only INTEGER data types are converted to the DECIMAL data type. If one operand is
DECIMAL and one is floating-point, the DECIMAL value is converted to a fioating-point vaiue. The
total number of digits (d) in the DECIMAL value determines its new data type:
Range of d

Converted to:

< = 1 through < = 6

SINGLE

< = 7 through < = 15

DOUBLE
GFLOAT
HFLOAT

= 16

DOUBLE

< 17 through < = 31

HFLOAT

If the value of d is between 7 and 15, the operand is converted to DOUBLE if the floating-point
operand is DOUBLE,Oto GFLOAT if the floating-point operand is GFLOAT, and to HFLOAT if the
floating-point operand is HFLOAT. Thus, a DECIMAL(8,5) operand is converted to DOUBLE if the
other operand is SINGLE or DOUBLE, to GFLOAT if the other operand is GFLOAT, and to HFLOAT if
the other operand is HFLOAT.
Figure 5-1 shows a mixed-mode expression, and the data types of the intermediate and final results.

Figure 5-1: Mixed-mode Expression Results
WORD

LONG

DECIMAL(6,2)

( DOUBLE ;, GFLOAT

LONG

HFLOAT

DEC!MAL(12,2)

HFLOAT

MK-00891-00

Note that the LONG integer is first converted to DECIMAL(10,0). When BASIC performs the division,
both operands are converted to DECIMAL(12,2).
You can convert any numeric variable or expression to a specified data type with the REAL,
INTEGER, and DECIMAL functions. See the BASIC Reference Manual for more information.

5.7 Allocating Static Storage
BASIC programs allocate both static and dynamic storage. The size of static storage does not change
during program execution. Variables and arrays appearing in MAP or COMMON statements use
static storage. Because this storage is static, all string variables appearing in MAPs or COMMONs are
fixed-length strings.

Data Definition

5-13

Dynamic storage is allocated when the program executes. Variables and arrays declared in the
following statements use dynamic storage:
• DECLARE statements
• DIMENSION statements
• Implicitly declared variables
Normally, string variables and arrays deuared in this way are dynamic strings, and their length can
change during program execution. However, if you declare or dimension an array of a user-defined
data type (a RECORD name), then all string variables and arrays are fixed-length strings. See BASIC
on VAX /VMS Systems for more information about the RECORD statement.
MAP and COMMON statements create a named storage area called a program section (PSECT). MAP
statements require a map name, but in COMMON statements the name is optional. The PSECT name
is the same as the MAP or COMMON name. If you do not specify a COMMON name, BASIC
supplies a default PSECT name of $BLANK on VAX/VMS systems and .$$$$. on PDP-11 systems.
The following sections explain how to use static storage.

5.7.1 COMMON Statement
The COMMON statement defines a named area of storage (called a PSECT). Any BASIC subprogram
can access the values in a COMMON by specifying a COMMON with the same name. The
COMMON statement has the format:
{ gg~MON

I [(

com-nam ) ] { [ data-type] com-item }, ...

where:
com-nam

Is the name of the COMMON block.

data-type

Is a data-type keyword.

com-item

Can be:
• A numeric variable
• A numeric array
• A fixed-length string variable
• An array of fixed-length strings
• A RECORD instance (VAX-11 BASIC only)
• A FILL item

The amount of storage reserved for a variable depends on its data type.
You can specify a length for string variables and string array elements that appear in a COMMON
statement. If you do not specify a length, the default is 16. The format for specifying strings in a
COMMON is:
COMMON (com-nam)

5-14

Data Definition

{:~~~~~~ I [=

int-cnstJ

where:
int-cnst

Is the length of the string variable or string array element.

10 COMMON (CODE) STRING EMP.CODE=2%t WAGE.CODE=3%t DEP.CODE=22%

This statement specifies 2 bytes for EMP.CODE, 3 bytes for WAGE.CODE, and 22 bytes for
DEP.CODE.
In a single program module, multiple COMMONs with the same name allocate storage end-to-end in
a single PSECT. That is, BASIC concatenates all COMMONs with the same name in the same
program module, in the order they appear. For example:
100
200

COMMON (INTS) LONG CALL_COUNTt SUB1_COUNTt SUB2_COUNT
COMMON (INTS) LONG SUB3_COUNTt SUB4_COUNT

These two COMMONs allocate storage for five LONG integers in a single PSECT named INTS.

5.7.2 MAP Statement
The MAP statement, like the COMMON statement, creates a named area of static storage. However,
if a program module contains multiple MAPs with the same name, the MAPs are overlaid on the same
area of storage, rather than being concatenated.
When used with the MAP clause of the OPEN statement, the storage allocated by the MAP statement
becomes the record buffer for that file. Variables in the MAP statement correspond to fields in the
file's records.
See Chapter 4 to use the MAP statement to manipulate strings.
The MAP statement format is:
MAP (map-nam) { [ data-type] map-item }, ...

where:
map-nam

Is the name of the MAP block.

data-type

Is a data-type keyword.

map-item

Can be one of the following:
• A numeric variable
• A numeric array
• A fixed-length string variable
• An array of fixed-length strings
• A RECORD instance (VAX-ll BASIC only)
• A FILL item

Data Definition

5-15

5.7.2.1 Single MAPs

You associate a MAP with a record buffer by referencing the MAP in the OPEN statement.
Note

PDP-ll BAS!C-PLUS-2 initializes variables named in ,\I\AP statements. Howevei,
V AX-ll BASIC does not.
The MAP statement must have a lower line number than any reference to MAP variables. For
example:

10
20

ON ERROR GOTO 5000
DECLARE INTEGER CONSTANT EOF = 11

2000 MAP (PAYROL) STRING EMP_NAMEt LONG WAGE_CLASSt
&
STRING SAL_REV_DATEt SINGLE TAX_YTD
2100 OPEN "PAYROL. DAT" FOR I NPUT AS FILE #a1,
tORGANIZATION SEQUENTIAL
tACCESS READ
tMAP PAYROL

&
&
&

2200 0 PEN "PAYROL. NEW" FOR OUT PUT AS FILE #51,
tORGANIZATION SEQUENTIAL
tACCESS WRITE
tMAP PAYROL

&
&
&

3000 PRINT "PAYROLL VERIFICATION"
GET_LOOP:
WHILE 11. = 1'1.
GET #a
PRINT EMP_NAMEt WAGE_CLASS1.t SAL_REV_DATEt TAX_YTD
PRINT "YOU CAN CHANGE:"
PRINT "1. EMPLOYEE NAME"
PRINT 112 .. WAGE CLASS"
PRINT "3. REVIEW DATE"
PRINT "a. TA}{ YEAR-TO-DATE"
PRINT "5. DONE"
READ_LOOP:
WHILE 11. = 1'X,
INPUT "CHANGES? ANSWER WITH YES OR NO"
IF CHNG$ = "NO" THEN ITERATE GET_LOOP
ELSE I NPUT "NUMBER" ; NUMBER'X,
END IF

CHNG$

SELECT NUMBER'X,
CASE 1
INPUT "EMPLOYEE NAME"; EMP_NAME
CASE 2
INPUT "WAGE CLASS"; WAGE_CLASS
CASE 3
INPUT "REI)lEW DATE" ;SAL_REIJ_DATE
CASE a
INPUT "TA}{ YEAR-TO-DATE"; TA}-{_YTD
CASE 5
EXIT READ_LOOP
CASE ELSE
PRINT "Invalid response -- please tr}' again"
END SELECT

5-16

Data Definition

NEXT
PUT :(:1:5

5000

NEXT
IF ERR
THEN

= EOF
nr-.Tkl"T"

i i , .L 1'1 I

1Ir- ... .J
C. II I.J

_J:I.

U I

,c.':'-.II

I J. J. t:

ELSE
ON ERROR GOTO 0
END IF
32767 END
This program uses MAP variables to access fields in payroll records. Changes to MAP variables do not
change the actual records in the file. To transfer the changed variables to the file, you must use the
PUT statement (see Chapter 9).

S.i.2.2 iviuitipie MAPs
When a program contains more than one MAP with the same name, the storage allocated by these
MAP statements is overlaid. This technique is useful for manipulating strings (as described in Chapter
4) and for accessing a record buffer in different ways. See Figure 5-2.

Figure 5-2: Multiple MAPs
MAP (MAP01)

ADDRESS$ = 44 BYTES

NA.MES ~ 40 BYTES

(

FIRST.NAME$

LAST.NAME$

15 BYTES

25 BYTES

y
STREET.
NUMBER$
5 BYTES

)

STREET$

CITY$

16 BYTES

23 BYTES

MAP (MAP01)

MK-00892-00

When you use more than one MAP to access a record buffer, BASIC uses the size of the largest MAP
to determine the size of the record. (The RECORDSIZE clause of the OPEN statement can override
this MAP-clefined recordsize. See Chapter 9.)
You can also use multiple MAPs to interpret numeric data in more than one way. For example:

100
110
120
130

MAP (BARRAY) BYTE ALPHABET(25)
MAP (BARRAY) STRING ABC = 26
FOR 1% = 0% TO 25%
ALPHABET(I%) = 1% + 65%
NE}{T IX.
PRINT ABC

RUNNH
ABCDEFGHIJKLMNOPQRSTUVWXYZ
This example creates a MAP area named BARRAY. The first MAP statement allocates 26 bytes of
storage in the form of an integer BYTE array. The second MAP statement defines this same storage as a
26-byte string named ABC. When the FOR-NEXT loop executes, it assigns values corresponding to
the ASCII values for the uppercase letters A through Z.
Data Definition

5-17

5.7.3 FILL Items
FILL items reserve space in MAP and COMMON blocks and in record buffers accessed by MOVE
statements. Thus, FILL items mask parts of the record buffer and let you: 1) skip over fields and
2) reserve space in or between data elements.
FILLs are available for all data types. Tabie 5-3 summarizes FILL formats and default allocations if no
data type is specified.

Table 5-3: FILL Item Formats, Representations, and Default Allocations

FILL Format

Representation

Bytes Used

FILL

Floating-point

4, 8, or 16

FILL(n)

n floating-point elements

4n, 8n, or 16n

FILL%

Integer (BYTE, WORD, or LONG)

1, 2, or 4

FILL %(n)

n integer elements

1n, 2n, or 4n

FILL$

String

FILL$(n)

n string elements

16n

FILL$ = m

String

FILL$(n) = m

n string elements, m bytes each

m *n

Note
In the applicable formats of FILL, n represents a repeat count, not an array subscript.
FILL(n), for example, represents n real elements, not n + 1 .
You can also use data-type keywords with FILL. If you do, the only valid form is FILL. The data-type
and storage requirements are those of the last data type specified. For example:

100 MAP (QED) STRING A, FILL=24t LONG SSN, FILLt REAL SALt FILL(S)
This MAP statement uses data-type keywords to reserve space for:
• A 16-character string variable A
• Twenty-four bytes of padding
• One LONG variable, SSN
• Four bytes of padding
• One REAL variable, SAL
• Space for five floating-point numbers. This requires 10, 20, or 80 bytes of padding, depending on
the default size for floating-point numbers.

5-18

Data Definition

In VAX-11 BASIC, you can specify user-defined data types (RECORD names) for FILL items. For
example:
100
200

RECORD >{
REAL y 1 , Y2 (10)
END RECORD X
MAP (QED) X FILL

Line 100 defines a RECORD of data-type X. The MAP statement in line 200 contains a fill item of this
data type, thus reserving space in the buffer for one RECORD of type X. See BASIC on VAX/VMS
Systems for more information on the RECORD statement.

5.7.4 Using COMMON and MAP in Subprograms
The COMMON and MAP statements create a block of storage called a PSECT (program section). This
COMMON or MAP storage block is accessible to any subprogram. Thus, a BASIC main and subprogram can share such an area by referencing the same COMMON or MAP name. For example:
Main Program
10

COMMON (Al) STRING At B

lOt LONG C

Subprogram
10

COMMON (Al) STRING Xt Z

lOt LONG Y

This COMMON block contains:
• A 16-character string field called A by the main program and X by the subprogram
• A 10-character string field called B by the main program and Z by the subprogram
• A 4-byte integer field called C by the main program and Y by the subprogram
If a subprogram defines a COMMON or MAP area with the same name as a COMMON or MAP in
the main program; it overlays the COMMON or MAP defined in the main program.
It is important to note that multiple COMMON statements with the same name behave differently
depending on whether these statements are in the same program module. If they are in the same
program module, then the storage for each COMMON area is concatenated. However, if they are in
different program units, then the COMMON areas overlay the same storage. For example:
100
200

COMMON (XYZ) STRING A
COMMON (XYZ) STRING 5

32
32

Because these COMMON statements are in the same program module, they are concatenated in a
single PSECT. Thus, the PSECT contains two 32-byte strings. In contrast:
Main Program
100

COMMON (XYZ) STRING A

Subprogram
100

COMMON (XYZ) STRING 5

Data Definition

5-19

Because these COMMON statements are in different program modules, they overlay the same storage. Thus, the PSECT contains one 32-byte string, called A in the main program and B in the
subprogram.
Although you can redefine the storage in a COMMON section when you access it from a subprogram, you should not do so. COMMON areas should contain exactly the same variables in all
program modules. To make sure of this, you should use the %INCLUDE directive. For example:
COMMON.BAS (%INCLUDE file)

COMMON (SHARE) WORD EMP_NUM,
DECIMAL (8,0) SALARY,
STRING WAGE_CLASS = 2

&
&

Main Program

100

1. I NCLUDE II COMMON. BAS"

Subprogram

200

IINCLUDE IICOMMON.BAS"

Using the %INCLUDE directive to include the COMMON area definition means that there is much
less chance of a typographical error. See Chapter 11 for more information on the %INCLUDE
directive.
If you must redefine the variables in a PSECT, you should use the MAP statement. It is best to do this
by using the %INCLUDE directive to create identical MAPs before redefining them. For example:
MAP.BAS (OkINCLUDE file)

MAP (REDEF) STRING FULL_NAME

Main Program

100

'.tINCLUDE !!j''iAP.oAS!!

Subprogram

200 IINCLUDE IIMAP.BAS"
110 MAP (REDEF) STRING FIRST_NAME=15t MI=l t LAST_NAME=24
The MAP defined in MAP.BAS is included in both program modules as a 40-byte string. This MAP is
redefined in the subprogram, allowing the subprogram to access parts of this string.

5.8 Dynamic Mapping
Dynamic mapping lets you redefine the position of variables in a MAP at run time. Dynamic mapping
requires three BASIC statements:
• A MAP statement, which determines the total size of the storage area
• A MAP DYNAMIC statement, which names the variables whose positions can change at run time
• A REMAP statement, which specifies the new positions of the variables named in the MAP
DYNAMIC statement

5-20

Data Definition

The MAP DYNAMIC statement is non-executable. Its format is:
MAP DYNAMIC (map-name) { [data-type] map-item} ,...
where:
map-name Is the storage area named in a previous MAP statement.
data-type

Is any valid BASIC data-type keyword. In VAX-11 BASIC, data-type can also be a
RECORD name.

map-item

Can be an unsubscripted variable or an array.

Note that you cannot specify a string length in a MAP DYNAMIC statement. All string items have a
length of zero until the program executes a REMAP statement.
The MAP DYNAivliC statement causes BASiC to create internal pointers to the variables and array
elements. The MAP DYNAMIC statement does not affect the amount of storage allocated. Until your
program executes the REMAP statement, the storage for each variable and each array element starts at
the beginning of the MAP storage area.
The REMAP statement specifies the new positions of variables named in the MAP DYNAI\'1IC statement. That is, it causes BASIC to change the internal pointers to the data. The format of REMAP is:
REMAP (map-name) [data-type] remap-item [= int-exp] ,...
where:
map-name

Is the name of the MAP storage area.

data-type

Is any valid BASIC data-type keyword. In VAX-ll BASIC, data-type can also be a
RECORD name. In the REMAP statement, data-type can be specified only for FILL
items.

remap-item

Any variable, array, or array element named in the MAP DYNAMIC statement, or a
FILL item.

int-exp

Specifies the length of string variables, string array elements or string FILL items.

For example:
100

MAP (MAP01) STRING DUMMY = 116
MAP DYNAMIC (MAP01) LONG At STRING Bt DOUBLE C(10)
REMAP (MAP01) B = 24t At C()

In this example, the MAP statement creates a storage area of 116 bytes and names it MAP01. The
MAP DYNAMIC statement specifies that the position of variables A and B, and each of the elements
of array C, can be dynamically redefined with the REMAP statement.
At the start of program execution, the storage for A is the first four bytes of MAP01, and the storage for
each element of array C is the first eight bytes of MAP01. The storage for string variable B begins at
the first byte of MAP01; however, string variables have a length of zero until the REMAP statement
executes. The REMAP statement redefines these pointers so that:
• STRING variable B occupies the first 24 bytes of MAP01
• LONG variable A occupies the next 4 bytes of MAP01

February 1984

Data Definition

5-21

• Array element C(O) occupies the next 8 bytes of MAP01, C(l) occupies the next 8 bytes, and so on.
Array C uses a total of 88 bytes.
Because the REMAP statement is executable, it can redefine the pointer for a variable or array
element more than once in a single REMAP statement. For example:

100

MAP (MAP01) STRING DUMMY = 116
MAP DYNAMIC (MAP01) LONG At STRING Bt DOUBLE C(10)
REMAP (MAP01) C() t C(O)

In this example, REMAP first causes array C to occupy the first 88 bytes of MAP01, then redefines C(O)
to occupy the next 8 bytes in MAP01. Any reference to C(O) will affect bytes 89 through 96.
Note that DYNAMIC MAP variables are local to the program module in which they reside. Thus,
REMAP only affects how that module views the buffer.

5-22

Data Definition

February 1984

Chapter 6

Functions

Functions perform numeric or string operations on operands and return the result to your program.
BASIC has built-in functions that perform numeric, string, conversion, date, and time operations. This
chapter demonstrates the use of a selected group of built-in functions. Chapter 4 also describes some
built-in string functions. For a complete list of BASIC built-in functions, see the BASIC Language
Reference Manual.

This chapter also describes user-defined functions. BASIC lets you define your own functions in two
ways:
• With the DEF statement
• As separately compiled subprograms (external functions)
DEF function definitions are local to a program module, while external functions can be accessed by
any program module. You create iocai functions with the DEF statement and optionally declare ihem
with the DECLARE statement. You create external functions with the FUNCTION statement and
declare them with the EXTERNAL statement.
Once a function has been created and declared, you call the function just as you would a built-in
function.
Note
For compatibility with BASIC-PLUS, BASIC-PLUS-2 and VAX-11 BASIC also support
the DEF* function definition statement. DEF* statements are not recommended for
new program development.

6.1 BASIC Built-in Functions
The functions described in this section let you perform sophisticated manipulation of string and
numeric data. A function performs a numeric or string operation on a specified argument and returns
the result to your program. There are numeric, string, conversion, date, and time functions in the
BASIC Jibrary.

6-1

BASIC also provides algebraic, exponential, trigonometric, and randomizing mathematic functions.
BASIC converts numeric arguments to the proper data type when you invoke a built-in function.
Thus, if you supply an integer argument to a function that expects a floating-point number, BASIC
converts the argument to floating-point. Note that floating-point arguments to integer functions are
tru ncated, not rou nded .

6.1.1 Using Numeric Functions
Numeric functions generally return a result of the same data type as the function's parameter. Of
course, this is not true for functions that are designed to return a result of a particular data type. For
example, if you pass a DOU BLE argument to any of the trigonometric functions, they return a
DOUBLE result.
On the other hand, the ABS function returns a floating-point number equivalent to the absolute value
of the argument. Thus, ABS always returns a result of the default floating-point data type.
Also, if the format of a BASIC built-in function specifies an argument of a particular data type, this
implies that BASIC converts the actual argument you supply to the specified data type.
6.1.1.1 ABS Function

The ABS function returns a floating-point number that equals the absolute value of a specified
numeric expression. Its format is:
ABS(num-exp)
where:
num-exp

Is any numeric expression.

For example:
10 READ A,B,CtD,E
20 DATA 10,-35.3,800,-8,0
30 PRINT ABS(A); ABS(B); ABS(C); ABS(D); ABS(E)
40 END
RUNNH
10

35.3

800

ABS always returns a number of the default floating-point data type.
6.1.1.2 SGN Function

The SGN function determines whether a number is positive, negative, or zero. Its format is:
SGN(num-exp)
where:
num-exp

6-2

Is any numeric expression.

Functions

If the expression is positive, SGN returns a positive 1; if negative, a negative 1. If the expression
equals zero, SGN returns zero. For example:
10 A = -7.32
20 B = .44
30 C = 0
ao PRINT "A = A t"B = ;B t"C
50 PRINT "SGN(A)="; SGN(A) t
60 PRINT "SGN(B)="; SGN(B) t
70 PRINT IISGN(C)="; SGN(C)
80 END
II

;

RUNNH
B= .44
SGN(B)= 1

A=-7.32
SGN(A)=-l

C= 0
SGN(C)= 0

The SGN function always returns a number of the default integer type.
6.1.1.3 INT and FIX Functions

The INT function returns the floating-point value of the largest integer less than or equal to a specified
expression. Its format is:
INT(exp)
where:
exp

Is any numeric expression.

INT always returns a number of the default floating-point type.
The FIX function truncates the value of a floating-point number at the decimal point. Its format is:
FIX(num-exp)
where:
num-exp

Is any numeric expression.

FIX always returns a number of the default floating-point type.
This is an example of INT:
10 PRINT
20 PRINT
30 PRINT
40 PRINT
50 END

INT(23.553)
INT(3.1)
INT(-45.3)
INT(-ll)

RUNNH
23
3

-46
-11

Functions

6-3

This is an example of FIX:
10
20
30
40

PRINT
PRINT
PRINT
PRINT

E~~D

FIX(23.553)
FIX(3.1)
FIX(-45.3)
FIX(-ll)

RUNNH
23
3

-45
-11
Note that the value returned by FIX(-4S.3) differs from the value returned by INT(-4S.3).
6.1.1.4 SIN, COS, and TAN Functions

'The SIN, COS, and TAN functions return the sine, cosine, and tangents of an angle. Their formats are:
SIN(num-exp)
COS(num-exp)
TAN(num-exp)
where:
num-exp

Is an angle in radians.

If you supply a floating-point argument to the SIN, COS, and TAN functions, they return a number of
the same floating-point type. However, if you supply an integer argument, they convert the argument
to the default floating-point data type and return a floating-point number of that type.
This program accepts an angle in degrees, converis ihe angie to radians, and prints the angle's sine,
cosine, and tangent:
REM - CONVERT ANGLE (X) TO RADIANS, AND
REM - FIND SIN, COS AND TAN
PRINT "DEGREES", "RADIANS", "SINE", "COSINE" ,"TANGENT!!
FOR 11 = 01 TO 51
READ }{
LET Y
x * 2 * PI / 360
PRINT
PRINT }{ ,Y ,SIN(Y) ,COS(Y) ,TAN(Y)
NE}{T 11
DATA 0,10,20,30,380,45
END

10
20
30
40

50
80
RUNNH

6-4

COSINE

TANGENT

DEGREES

RADIANS

SINE

.174533

.173848

.884808

.167327

.348066

.34202

.838883

.38387

Functions

.523588

380

8.28318

.785388

.707107

.888025

.57735

o
.707107

Note

As an angle approaches 90 degrees (P1/2 radians), 270 degrees (3*PI 12 radians), 450
degrees (5*PI/2 radians) and so on, the tangent of that angle approaches infinity. If
your program tries to find the tangent of such an angle, BASIC signals "Division by 0"
(ERR = 61).
6.1.1.5 LOG10 Function

A logarithm is the exponent of another number (called a base). Common logarithms use the base 10.
The common logarithm of a number N, therefore, is the power to which 10 must be raised to equal
N. For example, the common logarithm of 100 is 2, because 10 raised to the power 2 equals 100.
The LOG10 function returns a number's common logarithm. Its format is:
LOG 1O( num-exp)
where:
num-exp

Is any numeric expression.

For example:
10

FOR 1% = 10% TO 100% STEP 10%
PRINT LOG10(I%)
NE}{T 1%

40 END
RUNNH
1.30103
1.47712
1.80208
1.88887
1.77815
1.8451
1.80308
1.85424
2

If you supply a floating-point argument to LOG1 0, the function returns a floating-point number of the
same data type. However, if you supply an integer argument, LOG10 converts it to the default
floating-point data type and returns a value of that type.
6.1.1.6 LOG Function

Natural logarithms are exponents of the base "e", where "e" is a mathematical constant approximately equal to 2.71828. That is, the natural logarithm of a number N is the power to which "e"
must be raised to equal N: the natural logarithm of 100 is 4.60517, because "e" raised to the power
4.60517 equals 100.

Functions

6-5

The LOG function returns the natural (base "e") logarithm of a number. Its format is:
LOG(num-exp)

where:
num-exp

Is any numeric expression.

For example:

10 READ At B
20 DATA 2.71828t 100
30 PRINT liTHE NATURAL LDG OF";A;"IS";LOG(A)
40 PRINT liTHE NATURAL LOG OF";B;"IS";LOG(B)
50 END
RUNNH
THE NATURAL LOG OF 2.71828 IS 1
THE NATURAL LOG OF 100 IS 4.60517
If you supply a floating-point argument to LOG, the function returns a floating-point number of the
same data type. However, if you supply an integer argument, LOG converts it to the default floatingpoint data type and returns a value of that type.
6.1.1.7 EXP Function

The EXP function returns the value of "e" raised to a specified power. Its format is:
EXP(exp)

where:
exp

Is the power to which BASIC raises "e".

For example:

10 READ AtB
20 DATA 1 t2
e
30 PRINT
e
40 PRINT
50 END
I

RAISED TO THE POWER
RAISED TO THE POWER

;

A; "EQUALS"; EXP(A)
B; "EQUALS"; E~{P(B)

RUNNH
lie
lie

RAISED TO THE POWER 1 EQUALS 2.71828
RAISED TO THE POWER 2 EQUALS 7.38806

II
II

If you supply a floating-point argument to EXP, the function returns a floating-point number of the
same data type. However, if you supply an integer argument, EXP converts it to the default floatingpoint data type and returns a value of that type.
6.1.1.8 ATN Function

The ATN function returns the angle, in radians, of a specified tangent. Its format is:
ATN(tangent-value)

6-6

Functions

The ATN function returns a value between PII2 and -P1/2, inclusive. For example:
10 INPUT lITANGENT VALUE"; T
20 ATN.OF.T = ATN(T)
30 PR I NT

sr'IALLEST ANGLE WITH THAT TANGENT";

40 PRINT illS"; ATN.OF.T; "RADIANS"
50 ANG.IN.DEG = ATN+OF.T I (PI I 180)
60 PR I NT II AND II; ANG. IN. DEG; "DEGREES"
70 END
If you supply a floating-point argument to ATN, the function returns a floating-point number of the
same data type. However, if you supply an integer argument, ATN converts it to the default floatingpoint data type and returns a value of that type.
6.1.1.9 RND Function
The RND function returns a number greater than or equal to zero and less than one. Its format is:
RND

The RND function always returns a floating-point number of the default floating-point data type. The
RND function generates seemingly unrelated numbers. However, given the same starting conditions,
a computer always gives the same results. Each time you execute a program with the RND function,
you receive the same results. For example:
10 PRINT RND.RNDtRNDtRND
20 END
RUNNH
.76308

.178878

.802878

.88884

.178878

.802878

.88884

RUNNH
.76308

With the RANDOMIZE statement, you can change the RND function's starting condition and generate truly random numbers. To do this, place a RANDOMIZE statement before the line invoking the
RND function. Note that the RANDOMIZE statement should be used only once in a program. With
the RANDOMIZE statement, each invocation of RND returns a new and unpredictable number. For
example:
10 RANDOMIZE
20 PRINT RNDtRNDtRNDtRND
30 END
RUNNH
.403732

.34871

• 15302

.82462

.272388

.261667

.10208

RUNNH
.404165

The RND function can generate a series of random numbers over any open range. To produce
random numbers in the open range A to B, use the formula:
(B-A)*RND + A

Functions

6-7

This program produces 10 numbers in the open range 4 to 6:

FOR 1% = 1% TO 10%
PRINT (6%-4%) * RNO
NE}{T 1%
END

10
40

RUNNH
5.52616
4.35886
5.80576
5.77868
4.77402
4.85188
5.76438
4.37156
5.2776
4.53843

6.1.1.10 SQR Function

The SQR function returns a positive number's square root. Its format is:
SQR(num-exp)
For example:

FOR 1% = 1% TO 2%
READ A
PRINT SQR(A)
NEXT IX.
DATA 10,4
END

RUNNH
3.16228
2

If the argument to the SQR function is less than zero, BASIC signals "Imaginary square root"
(ERR = 54).
The SQR function always returns a number of the default floating-point data type.

6.2 Using Data Conversion Functions
BASIC provides the means to:
• Convert a l-character string to the character's ASCII value and vice versa (ASCII and CHR$
functions)
• Translate strings from one data format to another, for example, EBCDIC to ASCII (XLATE function)
The following sections describe these functions.

6-8

Functions

6.2.1 ASCII Function
The ASCII function returns the numeric ASCII value of a string's first character. Its format is:
ASCI I(str-exp)
The ASCII function returns an integer value between 0 and 255, inclusive. For example:

10 TEST.STRINGS = "BAT"
20 PRINT ASCII(TEST.STRINGS)
30 END
RUNNH
66
Line 20 prints 66 because this is the ASCii value of an uppercase S, the first character in the string.
The ASCII value of a null string is zero.

6.2.2 CHR$ Function
The CHR$ function returns the character whose ASCII value you supply. Its format is:
CHR$(num-exp)
where:
num-exp

Is a numeric expression. If num-exp is less than zero or greater than 255, it is treated
modulo 256; thus, CHR$(325) is equivalent to CHR$(69) and CHR$(-l) is equivalent
to CHR$(255).

For example:

10 PRINT "THIS PROGRAM FINDS THE CHARACTER WHOSE"
20 PRINT "VALUE (MODULO 256) YOU TYPE"
30 INPUT VALUEi.'.
40 PRINT CHR$(VALUE%)
50 END
RUNNH
THIS PROGRAM FINDS THE CHARACTER WHOSE
VALUE (MODULO 256) YOU TYPE
? 69
E

6.2.3 XLATE Function
The XLATE function translates one string to another by referencing a table you provide. Its format is:
XLATE(str-exp1, str-exp2)
where:
str-exp1

Is the input string.

str-exp2

Is the table string.

Functions

6-9

The table string can contain up to 256 ASCII characters; the position of each character in the table
string corresponds to an ASCII value. Because zero is a valid ASCII value (null), the first position in
the table string is position zero.
XLATE scans the input string character by character, from left to right. It finds the ASCII value n of the
input character and extracts the character it finds at position n in the table string. XLATE then appends
the table string character to the returned string and goes on to the next character in the input string.
For example, this program uses XLATE to convert uppercase letters to lowercase:

10 A$ = lIabcdefghijKl'TlnOP9fstU\jI,.IXYZIl
TABLE$ = STRING$(G5ItOI) + A$
LINPUT IITYPE A STRING OF UPPERCASE LETTERSII; SOURCE$
PRINT XLATE(SOURCE$t TABLE$)
END

20
30
40
50

RUNNH
TYPE A STRING OF UPPERCASE LETTERS? XYZZY
XYZZY

The table string contains 65 nulls and the 26 lowercase letters. In line 40, XLATE takes the ASCII
value of X (88) and extracts the character at position 88 in the table string (the first character in the
table string is position zero). This character is a lowercase x. BASIC appends it to the output string,
and proceeds in this way until there are no more characters in the input string.
These restrictions apply to XLATE:
• XLATE does not translate nulls. Therefore, the output string may be smaller than the input string.
• If the character at position n in the table string is a null, XLATE does not translate the character
whose ASCII value is n.
• If the ASCII value of the input character is outside the range of positions in the table string, XLATE
does not translate that input character.

6.2.4 Using Numeric String Functions
Numeric strings are numbers represented by ASCII characters. A numeric string consists of an
optional sign, a string of digits, and an optional decimal point. You can use E notation in the numeric
string for floating-poi nt constants.
The following sections describe functions for printing, converting, and evaluating numeric strings.
6.2.4.1 FORMAT$ Function

The FORMAT$ function converts a numeric value to a string. The output string is formatted according
to a string you provide. Its format is:
FORMAT$(exp, format-string)

where:
exp

Is any string or numeric expression.

format-string

Is a string expression containing at least one PRINT USING format field.

6-10

Functions

The formatting rules are the same as those for printing numbers with PRINT USING. See Chapter 8 for
more information on formatting rules. For example:
10 A = 5
20 B$ = n##+##"
30 Z$ = FORMAT$(Af 5$)
40 PRINT Z$
50 END
RUNNH
5.00

6.2.4.2 NUM$ and NUM1$ Functions

The NUM$ function evaluates a numeric expression and returns a string of characters formatted as the
PRINT statement would format it. The NUM$ format is:
NUM$(num-exp)
The returned numeric string is preceded by one space for positive numbers and by a minus sign for
negative numbers. The numeric string is always followed by a space. For example:
10 PRINT NUM$(7465087802134)
20 PRINT NUM$(-50)
30 END
RUNNH
.74651E+13
-50

The NUM1 $ function translates a number into a string of numeric characters. NUMl $ does not return
leading or trailing spaces or E format. The NUM1 $ format is:
NUM1 $(num-exp)

For example:
10
20
30
40

PRINT NUM1$(PI)
PRINT NUM1$(87.5 * 30456.23 + 30385.1)
PRINT NUM1$(1E-38)
END

RUNNH
3.14158
2888870
.00000000000000000000000000000000000001

NUM1 $ returns up to 6 digits of accuracy for single-precision real numbers, up to 16 digits
of accuracy for double-precision numbers, and up to 10 digits of accuracy for LONG integers. On
VAX/VMS systems, NUM1 $ returns up to 15 digits of accuracy for GFLOAT numbers and up to 33
digits of accuracy for HFLOAT numbers.

Functions

6-11

This example shows the difference between NUM$ and NUMl $:
10
20
30
40
50

A$ = NUM$(1000000)
B$ = NUM1$(1000000)
PRINT LEN (A$) ; " / " ; A$; "/ "
PRINT LEN (B$) ; " / " ; B$; "/ "
END

RUNNH
8 / .lE+07 /
7 /1000000/

Note that A$ has a leading and trailing space.
6.2.4.3 STR$ Function

The STR$ function converts a numeric expression to a string of ASCII digits. STR$ is identical to
NUM$ except that the returned string has no leading or trailing spaces. Its format is:
STR$( num-exp)

For example:
10
20
30
40
50

A = 10
B$ = STR$(A)
PRINT B$
PRINT A
END

RUNNH
10
10

in line 20, B$ contains the ASCii characters "j" and "0". BASiC prints B$ with no ieading space
because it is a string, but it prints A with a leading and trailing space because it is a number.
6.2.4.4 VAL% and VAL Functions

The VAL % function returns the integer value of a numeric string. Its format is:
VAL%(num-str-exp)
where:
num-str-exp

Must be an integer's string representation. It can contain:
• The ASCII digits 0 through 9
• The symbols" +" and "-"

The VAL function returns the floating-point value of a numeric string. Its format is:
VAL(num-str-exp)

6-12

Functions

where:
num-str-exp

Must be a number's string representation. It can contain:
• The ASCII digits 0 through 9
• The symbols" +", "-", and"."
• An uppercase E

VAL returns a number of the default floating-point data type. BASIC signals "Illegal number" (ERR =
52) if the argument is outside the range of the default floating-point data type.
This is an example of VAL and VAL %:

20 B$ = "100"
30 C'l. = VAL 1. (B$ )

40 PRINT A
40 PRINT C1.
GO END
RUNNH
922
100

6.2.5 Using String Arithmetic Functions
String arithmetic functions process numeric strings as arithmetic operands. This lets you add (SUM$),
subtract (DIF$), multiply (PROD$), or divide (QUO$) numeric strings or express them at a specified
level of precision (PLACE$).
String arithmetic offers greater precision than floating-point arithmetic or longword integers and
eliminates the need for scaling. However, string arithmetic executes much more slowly than integer
or floating-point operations.
The operands for the functions can be numeric strings representing any integer or floating-point value
(E notation is not valid). Table 6-1 shows the string arithmetic functions and their formats, and gives
brief descriptions of what they do. Later sections give more detailed descriptions of each string
function.

Table 6-1: String Arithmetic Functions
Description

Format

Function
SUM$

SUM$(A$,B$)

B$ is added to A$.

DIF$

DIF$(A$,B$)

B$ is subtracted from A$.

PROD$

PROD$(A$,B$,P%)

A$ is multiplied by B$. The product is expressed with precision P%.

QUO$

QUO$(A$,B$,P%)

A$ is divided by B$. The quotient is expressed with precision P%.

PLACE$

PLACE$(A$,P%)

A$ is expressed with precision P%.

SUM$ and DIF$ take the precision of the more precise argument in the function, unless padded zeros
generate that precision. SUM$ and DIF$ omit trailing zeros to the right of the decimal point.

February 1984

Functions

6-13

String arithmetic computations permit 56 significant digits. The functions QUO$, PLACE$, and
PROD$, however, permit up to 60 significant digits. Table 6-2 shows how BASIC determines the
precision permitted by each function and if that precision is implicit or explicit.

Table 6-2: Precision of String Arithmetic Functions

Function

How Determined

How Stated

SUM$

Precision of argument

Implicitly

DIF$

Precision of argument

Implicitly

PROD$

Value of argument

Explicitly

QUO$

Value of argument

Explicitly

PLACE$

Value of argument

Explicitly

The size and precision of results returned by the SUM$ and DIF$ functions depend on the size and
precision of the arguments involved:
• The sum or difference of two integers takes the precision of the larger integer.
• The sum or difference of two decimal fractions takes the precision of the more precise fraction.
• The sum or difference of two real numbers takes precision as follows:
The sum or difference of the integer parts takes the precision of the larger part.
The sum or difference of the decimal fraction parts takes the precision of the more precise part.
• BASIC truncates trailing zeros.
In the PLACE$, PROD$, and QUO$ functions, the value of the integer expression explicitly determines numeric precision. That is, the integer expression determines the point at which the number is
rounded or truncated.
If the integer expression is between -5000 and 5000, rounding occurs according to the following
rules:
• For positive integer expressions, rounding occurs to the right of the decimal place. For example, if
the integer expression is 1, rounding occurs one digit to the right of the decimal place (the number
is rounded to the nearest tenth). If 2, rounding occurs two digits to the right of the decimal place
(the number is rounded to the nearest hundredth), and so on.
• For zero, BASIC rounds to the nearest unit.
• For negative integer expressions, rounding occurs to the left of the decimal place. For example, if
the integer expression is -1, rounding occurs one place to the left of the decimal point. In this case,
BASIC moves the decimal point one place to the left, then rounds to units. If the integer expression
is -2, rounding occurs two places to the left of the decimal point; BASIC moves the decimal point
two places to the left, then rounds to units.
Note that when rounding numeric strings, BASIC returns only part of the number. See Section 6.2.5.1
for an example of this behavior.

6-14

Functions

If the integer expression is between 5001 and 15000, truncation occurs:
• If the integer expression is 10000, BASIC truncates the number at the decimal point.
• If the integer expressi-on is greater than 10000 (10000 plus n) BASIC truncates the numeric string n
places to the right of the decimal point. For example, if the integer expression is 10001 (10000 plus
1), BASIC truncates the number starting one place to the right of the decimal point. If 10002 (10000
plus 2), BASIC truncates the number starting two places to the right of the decimal point, and so on .
• If the integer expression is less than 10000 (10000 minus n) BASIC truncates the numeric string n
places to the left of the decimal point. For example, if the integer expression is 9999 (10000 minus
1), BASIC truncates the number starting one place to the left of the decimal point. If 9998 (10000
minus 2), BASIC truncates starting two places to the left of the decimal point, and so on.
For examples of this rounding and truncation behavior, see the following explanation of the PLACE$
function.
6.2.5.1 PLACE$ Function

The PLACE$ function returns a numeric string, truncated or rounded according to an integer argument
you supply. Its format is:
PLACE$(num-str, int-exp)

For example:
10
20

NUMBER$ = 11123456.654321 11
FOR II = -5I TO 5I

30
40

NEXT II
PRINT
FOR II = 8885 TO 10005

PRINT PLACE$(NUMBER$t II)

PRINT PLACE$(NUMBER$t II)
NEXT II
RUNNH
12
123
1235
12346
123457
123456.7
123456.65
123456.654
123456.6543
123456.65432
1

12
123
1234
12345
123456
123456.6
123456.65
123456.654
123456.6543
123456.65432

Functions

6-15

6.2.5.2 SUMS Function
The SUM$ function returns the sum of two numeric strings. Its format is:
SUM$(num-str1, num-str2)
For example:
10 A$ = 1156 11
20 S I GMA$ = SUM$ ( A$,
30 PRINT SIGMA$
40 END

II )

RUNNH
100

6.2.5.3 DIF$ Function
The DIF$ returns the arithmetic difference of two numeric strings. Its format is:
DIF$(num-str1, num-str2)
The first numeric string is the minuend and the second is the subtrahend. For example:
10
20
30
40

A$ = 1188888 11
ANSWER$ = DIF$(A$, "11111")
PRINT ANSWER$
END

RUNNH
88888

6.2.5.4 PRODS Function
The PROD$ function returns ihe product of two numeric strings. Its format is:
PROD$(num-str1, num-str2, int-exp)
The returned string's precision depends on the value of the integer expression. (See Section 6.2.5 for
allowable values of int-exp.) For example:
10 A$ = 11-4.333 11
20 B$ = 117.23326"
30 S.PRODUCT$ = PROD$(A$, B$, 10005%)
40 PRINT S.PRODUCT$
50 END
RUNNH
-31.34171

6.2.5.5 QUO$ Function
The QUO$ function returns the quotient of two numeric strings. Its format is:
QUO$(num-str1, num-str2, int-exp)

6-16

Functions

where:
num-str1

Is the numerator.

num-str2

Is the denominator.

int-exp

Determines rounding and truncation. (See Section 6.2.5 for allowable values of
int-exp.)

For example:
10 NUMER$ = "32767"
20 DENOM$ = "65535"
30 PRECISION% = 10004%
40 QUOTIENT$ = QUO$(NUMER$, DENOM$, PRECISION%)
50 PRINT QUOTIENTS
60 END
RUNNH
.4999

6.2.6 Using Date and Time Functions
BASIC supplies functions to return the date and time in numeric or string format. The following
sections discuss these functions.
On VAX/VMS systems you can use system services and Run-Time Library routines for more sophisticated date and time functions. See the VAX/VMS System Services Reference Manual and the
VAX/VMS Run-Time Library Reference Manual.

6.2.6.1 DATE$ Function

The DATE$ function returns a string containing a day, month, and year in the form: DD-MMM-YY.
(On RSTS/E systems, the form of the DATE$ function's output can be changed to ISO format,
YY.MM.DD, during the installation procedure.) The format of the DATE$ function is:
DATE$(num-exp)
The numeric expression's thousands digit represents the number of years since 1970. The remaining
digits specify the day of that year. If the numeric expression is zero, DATE$ returns the current date.
For example:
10 PRINT DATE$(O)
20 PRINT DATE$(126)
30 PRINT DATE$(6168)
50 END
RUNNH
16-May-82
06-May-70
16-Jun-76

If you supply an invalid date (for example, day 370 of 1973), results are undefined.

February 1984

Functions

6-17

6.2.6.2 TIMES Function
The TIME$ function returns a string displaying the time of day in the form HH:MM AM or HH:MM
PM. Its format is:
TIME$(num-exp)
TIME$ returns the time of day at a specified number of minutes before midnight. If you specify zero in
the numeric expression, TIME$ returns the current time of day. For example:

10 PRINT
20 PRINT
30 PRINT
40 PRINT
50 END

TIME$(O)
TIME$(l)
TIME$(1440)
TIME$(721)

RUNNH
01:53 PM
11:58 PM
12:00 AM
11:58 AM

6.2.6.3 TIME Function
The TIME function requests time and usage information from the operating system and returns it
to your program. Because of this, TIME works differently on RSTS IE, RSX-ll M 1M-PLUS, and
VAX IVMS systems. On VAX IVMS systems, its format is:
TIME(int-exp)
Where int-exp is a integer expression. If int-exp is:

TIME returns the number of seconds elapsed since midnight.
TIME returns the current job's CPU time in tenths of a second.

TIME returns the current job's connect time in seconds.

TIME returns a zero.

All other arguments to TIME are undefined and cause VAX-ll BASIC to signal "Not implemented"
(ERR= 250).
On RSX-ll M I M-PLUS systems, TIME accepts an argument of zero only. TIME(O%) returns a
floating-point number that is the number of seconds that have elapsed since midnight.
On RSTS/E systems, the format is:
TIME(int-exp)
Where int-exp is an integer expression. If int-exp is:

TIME returns the number of seconds elapsed since midnight.
TIME returns the current job's CPU time in tenths of a second.

6-18

Functions

TIME returns the current job's connect time in seconds.

TIME returns the number of kilo-core ticks (KCTs) that your job used. See the RSTS I E System
User's Guide for an explanation of KCTs.

TIME returns the device time for the job in minutes.

This example prints the number of seconds elapsed since midnight:
10 PRINT TIME(O)
20 END
RUNNH
50755

6.2.7 Using Terminal Control Functions
Terminal control functions let you:
• Enable and disable CTRL IC trapping
• Enable and disable terminal echoing
• Remove the effect of a CTRL/O
• Tab to a specified character position
6.2.7.1 CTRLC and RCTRLC Functions

The CTRLC function enables CTRL IC trapping. The RCTRLC function disables CTRL IC trapping.
When CTRL IC trapping is enabled, control is transferred to the program's error handler when a
CTRL/C is detected at the controlling terminal. The format for CTRLC is:
int-vbl = CTRLC

The format for RCTRLC is:
int-vbl = RCTRLC

CTRL/C trapping is asynchronous. The trap can occur in the middle of an executing statement, and a
statement so interrupted leaves variables in an undefined state. For example, the statement A$ =
"ABC", if interrupted by CTRL/C, could leave the variable A$ partially set to "ABC" and partially left
with its old contents. Therefore, you should use the CTRLC function only when doing a final cleanup
before exiting a program. For example:
100 ON ERROR GOTO 18000
200 Y'X. = CTRLC
!•
!•
! •

18000 REM ERROR HANDLER
18100 IF ERR = 28% THEN GOTO 20000
! •
!•
!•

20000
20100
20200
20300
201100

REM CONTROL C--CLEANUP AND EXIT
RESUME 20200
PRINT #1 t "ABORT"
CLOSE #1
END

Functions

6-19

If you type a CTRL IC to this program when CTRL IC trapping is enabled, an "ABORT" message prints
to the file open on channel #1. This lets you know that the program did not end correctly.
6.2.7.2 ECHO and NOECHO Functions

The NOECHO function disables echoing on a specified channel, Echoing is the process by \vhich
characters typed at the terminal keyboard appear on the terminal screen or paper. The format of
NOECHO is:
NOECHO( chnl-exp)

If you specify channel zero (your terminal) the characters typed on the keyboard are still accepted as
input; however, they do not appear on the screen.
The ECHO function enables echoing on a specified channel and cancels the effect of the NOECHO
function on that channel. Its format is:
ECHO( chnl-exp)

If you do not use these functions., ECHO is the default. This program shows a password routine in
wh ich the password does not echo:

10
20
30
ao
50

Y% = NOECHO(O%)
INPUT "PASSWORD"; PWORO$
IF PWORD$=="PLUGH" THEN PRINT "THAT IS CORRECT"
Yi.. = ECHO (O'x,)
END

6.2.7.3 TAB Function

You use the TAB function with the PRINT statement. TAB moves the cursor or print mechanism to a
specified column. Its format is:
PRINT TAB(int-exp)

where:
int-exp

Specifies the column number of the cursor or print mechanism. The first column position on your terminal is position zero.

The TAB function can move the cursor to the right only. If the cursor is to the right of the specified
column, TAB has no effect. For example:

10 PRINT "TEST"; TAB(2i..); "TEST"
20 END
RUNNH
TEST TEST
Because the cursor is at position five when BASIC executes TAB(2%), it has no effect.

6-20

Functions

When using the TAB function, you should not use commas to separate PRINT elements. If you do,
BASIC moves the cursor to the next print zone before executing the TAB. Instead, use semicolons. For
example:

10 PRINT IINAMEII; TAB( 151.); "ADDRESS", TAB(30i.);
20 END

HPHONE NO."

RUNNH
NAME

ADDRESS

PHONE NO.

6.3 The DEF Statement
The DEF statement lets you create your own single-line or multi-line functions.
In the traditional BASIC usage, a function name consists of:
• The letters FN
• 1 to 28 letters, digits, underscores, or periods
• An optional percent sign or dollar sign
Integer function names must end with a percent sign and string function names must end with a dollar
sign. Therefore, the function name can have up to 31 characters. If the function name ends with
neither a percent sign nor a dollar sign, the function returns a real number.
You can still create user-defined functions using these function names. However, DIGITAL recommends that you use explicit data typing when defining functions for new program development. Refer
to Section 6.3.2 for an example of an explicitly declared function. Note that the function name must
start with FN only if the function is not explicitly declared and a function reference lexically precedes
the function definition.
DEF functions can be either single-line or multi-line. Whether you use the single-line or multi-line
format for function definitions depends on the complexity of the function you create. In general,
multi-line DEFs are for more complex functions than single-line DEFs. However, the important distinction between single- and multi-line DEFs is that multi-line DEFs can be invoked recursively, and
single-line DEFs cannot.
If you want to pass values to a function, the function definition requires a formal parameter list. These
formal parameters are the variables used to calculate the value returned by the function. When you
invoke a function, you supply an actual parameter list; the values in the actual parameter list are
copied into the formal parameter at this time. DEF functions allow up to eight formal parameters. You
can specify variables, constants, or array elements as formal parameters, but you cannot specify an
entire array as a parameter to a DEF function.

6.3.1 Single-Line DEFs
In a single-line DEF, the function name, the formal parameter list and the defining expression all
appear on the same line. The format of a single-line DEF is:
DEF [data-type] func-nam [(formal-list)] = exp

February 1984

Functions

6-21

where:
data-type

Is any val id BASIC data-type keyword or a user-defined RECORD name (VAX-ll
BASIC only).

func-nam

Is the function name.

formal-list

Is a list of zero to eight arguments to the function. These parameters are variables
local to the function definition. Each formal parameter can be preceded by a datatype keyword.

exp

Is the defining expression. This expression specifies the calculations the function
performs.

For example:
100
200
300

DEF FNRATIO (NUMERt DENOMIN)
PRINT FNRATIO(5.Gt 7.8)
END

NUMER

DENOMIN

Line 100 contains the function name; FN RATIO, the formal parameter Iist containing two variables,
NUMER and DENOMIN; and the defining expression, NUMER / DENOMIN. The defining expression
specifies the operations the function performs. In line 200, the function is invoked with two actual
parameters: 5.6 and 7.8. These values are assigned to the corresponding formal parameters. The
actual parameters you supply must agree in number and data type with those in the formal parameter
list; that is, you must supply numeric values for numeric variables, and string values for string
variables.
In the previous example, when the function is invoked in line 200, BASIC:
• Copies the values 5.6 and 7.8 into the formal parameters NUMER and DENOMIN
• Evaluates the expression to the right of the equal sign
• Returns the value to the statement that invoked the function (line 200)
The PRINT statement then prints the returned value.
The defining expression for a single-line function definition can contain any constant, variable, BASIC
Library function, or user-defined function, except the function being defined. The following are valid
function definitions:
10 DEF FN.A(}{)

20 DEF FN.B(}{)
30 DEF FN. C (}{)

ao DEF CUBE (}{)

v·"r:>

>{ + a
" "- + 3
FN.A(X) *
I 2 + FN. A(}{)
SQR (}{+a) + 1
}-{

.'.

Note that the name of the function defined on line 40 does not begin with FN. This is valid as long as
no reference to the function lexically precedes the function definition.
You can also define a function that has no formal parameters. For example:
1000

DEF FNDAY _NUMBER% = t.JAL% (SEG$ (DATE$ (0%) t 17.. t 27..»

6-22

Functions

This function definition uses three BASIC built-in functions to return an integer corresponding to the
day of the month. DATE$(O) returns a date string in the form dd-Mmm-yy. The SEG$ function strips
nut of this value the characters starting at character position one up to and including the character at
position two (the day number). The VAL % function converts this resulting numeric string to an
integer. Thus, FNDAY _NUMBER% returns the day of the month as an integer.

6.3.2 Multi-Line DEFs
The DEF statement can also define multi-line functions. Multi-line DEFs are useful for expressing
complicated functions. The format is:
DEF [data-type] func-nam [(formal-parameter-list)]
statement( s)
END DEF
Note that multi-line DEFs do not have the equal sign and defining expression on the first line. Instead,
this expression appears in the function block, assigned to the function name.
Note

If a multi-line DEF contains DATA statements, they are global to the program.
Multi-line function definitions can contain any constant, variable, BASIC Library function, or userdefined function. In VAX-ll BASIC, the function definition can contain a reference to the function
you are defining. This means that in VAX-ll BASIC, a multi-line DEF can be recursive, or can invoke
itself.
You signal the end of the function definition with the END DEF statement. Its format is:
END DEF
FNEND is a synonym for END DEF, but END DEF is preferred.
The EXIT DEF statement lets you exit from a user-defined function. It is equivalent to an unconditional
transfer to the END DEF statement. Its format is:
EXIT DEF
FNEXIT is a synonym for EXIT DEF but EXIT DEF is preferred. This is an example of a multi-line DEF:

DEF FN.DISCONT(A)
IF A :> 10
THEN
PRINT IIOUT OF RANGE II
E}{ I T DEF
ELSE
FN.DISCONT = AAA
END IF
END DEF
50 INPUT Z
60 PRINT FN.DISCONT(Z)
70 END
RUNNH
12

OUT OF RANGE

Functions

6-23

In this example, the defining expression is in the ELSE clause. This assigns a value to the function if A
is less than 10. Because A is greater than 10, BASIC prints "OUT OF RANGE" and executes the EXIT
DEF statement. The function returns zero because control is transferred to the END DEF statement
before a value was assigned. Thus this example tests the arguments before the function is evaluated.
If you do not explicitly declare the function with the DECLARE statement, the restrictions for naming a
multi-line DEF are the same as those for the single-line DEF. However, explicitly declaring a DEF
function can make a program easier to read and understand. For example:
100

DECLARE STRING FUNCTION CONCAT (STRINGt STRING)

1000
1100
1200

DEF STRING CONCAT (STRING Yt STRING Z)
CONCAT = Y + Z !Define the function
FNEND

CONCAT(A$t B$)

20000

32767

!Declare the function

!Invoke the function

END

This example merely concatenates two strings. The following example returns a number in a specified
modulus:
100
200

DECLARE REAL FUNCTION MDLO (REALt INTEGER)
DEF MDLO( REAL ARGUMENT, INTEGER MODULUS)
!Check for

ar~UMent

EXIT DEF IF ARGUMENT

equal to zero

!Check for Modulus equal to zerOt Modulus equal to absolute
!value of ar~UMentt and Modulus ~reater than absolute
!value of ar~UMent.
SELECT MODULUS
CASE
0%
EXIT DEF
CASE> ABS( ARGUMENT
E}{ I T DEF
CASE
ABS( ARGUMENT )
MDLO = ARGUMENT
E~n T DEF
END SELECT
300

!If ar~UMent is ne~ativet set
!to its absolute value.
IF ARGUMENT < 0
THEN ARGUMENT
NEGAT I I.JEi.',

6-24

Functions

fla~

NEGATIVE% and set ARGUMENT

ABS( ARGUMENT
= -l'y',

aoo

UNTIL ARGUMENT < MODULUS
ARGUMENT

= ARGUMENT - MODULUS

!If this calculation ever results in zerOt MDLo returns zero
IF ARGUMENT = MODULUS
THEN MDLo = 0
E}'{ I T DEF
END IF
500

!ARGUMENT now contains the right nUMbert but the sign May be wrong.
!If the negative arguMent flag was sett Make the result negative.
IF NEGAT I t.IEi.'.
THEN MDLo
ELSE MDLo

600

END DEF

32767

!•
!•
END

- ARGUMENT
ARGUMENT

!•

Because these functions are declared in DECLARE statements, the function names need not conform
to traditional BASIC usage.

The following is an example of a recursive function:
100 DECLARE INTEGER FUNCTION FACTOR ( INTEGER
200 DEF INTEGER FACTOR ( INTEGER F )
IF F <= O'x,
THEN FACTOR
Ii.',
ELSE FACTOR = FACToR(F - 1%) * F
END IF
END DEF
This example defines a function that returns a number's factorial value.
Any variable accessed or declared in the DEF and not in the formal parameter list is global to the
program unit. When BASIC evaluates the user-defined function, these global variables contain the
values last assigned to them in the surrounding program module.
To prevent confusion, variables declared in the formal parameter list should not appear elsewhere in
the program. Note that, if your function definition actually uses global variables, these variables
cannot appear in the formal parameter list.
You cannot transfer control into a multi-line DEF except by invoking it. You should not transfer
control out of a DEF except by way of an EXIT DEF or END DEF statement. This means that:
• If the DEF contains an ON ERROR GOTO, GOTO, ON GOTO, GOSUB, ON GOSUB, or RESUME
statement, that statement's target line number must also be in that DEF .
• An ON ERROR GO BACK statement can transfer control out of a DEF; however, a RESUME
statement in an error handler outside the DEF cannot transfer control back into the DEF .
• A subroutine cannot be shared by more than one DEF. However, you can rewrite the subroutine as
a DEF with no parameters. Other function definitions can share this type of DEF.

February 1984

Functions

6-25

A DEF function never changes the value of a parameter passed to it. Further, because formal parameters are local to the function definition, a reference to one of these variables outside of the DEF
statement creates a new variable. For example:

DEF FN.SUM%(FIRST%,SECOND%) = FIRST%
A% = 50%

PRINT FN.SUM%(A%, B%)
PRINT FIRST%
END

50
60

SECOND%

= 25'X,

RUNNH
75

o
Because it is outside the function definition, line 50 creates a new variable (initialized to zero), and
BASIC prints this value.

6.4 External Functions
An external function is a separately compiled program module that returns a value. To create the
function subprogram, you use the FUNCTION, END FUNCTION, and EXIT FUNCTION statements.
The difference between a FUNCTION subprogram and a SUB subprogram is that the FUNCTION
subprogram returns a value.
External functions are useful because they:
• Can be invoked by any program module
• Allow up to 255 parameters in VAX-11 BASIC, and up to 8 parameters in BASIC-PLUS-2
• Allow arrays to be passed as parameters
e Allo'vv more than one value to be returned by modifiable parameters

You use the EXTERNAL statement to name and explicitly declare:
• The data type returned by the external function
• The data type of the formal parameters
• The parameter passing mechanism of the formal parameters (VAX-11 BASIC only)
After you've created an external function, you compile it and link (or task-build) it with the program
modules that invoke it. The syntax for invoking an external function is the same as for invoking a
built-in or DEF function.

6.4.1 FUNCTION, EXIT FUNCTION, and END FUNCTION Statements
The FUNCTION statement marks the beginning of a FUNCTION subprogram. Its format is:
FUNCTION data-type func-nam [(formal-list))

where:
data-type

6-26

Is a data-type keyword specifying the data type of the return value. In VAX-11
BASIC, data-type can also be a RECORD name.

Functions

func-nam

Is the name of the function. This name can be up to 6 characters for BASIC-PLUS-2
and up to 30 characters for VAX-ll BASIC.

formal-list

Is an optional Iist of formal parameters. These parameters are variables used to calculate the value the function returns. Each forma! parameter can be preceded by a datatype keyword. In VAX-ll BASIC, each formal parameter can be followed by a
parameter passing mechanism.

The END FUNCTION statement: 1) marks the end of a function subprogram, 2) returns a value, and
3) returns program control to the statement that invoked the function. Its format is:
END FUNCTION
FUNCTIONEND is a synonym for END FUNCTION, but END FUNCTION is preferred.
The EXiT FUNCTiON statement immediateiy returns program controi to the statement that invoked
the function. It is equivalent to an unconditional transfer to the FUNCTIONEND statement. Its format is:
EXIT FUNCTION
FUNCTIONEXIT is a synonym for EXIT FUNCTION, but EXIT FUNCTION is preferred. Here is an
example of an external function:

100
200
300
400

FUNCTION REAL SPHERE_VOLUME (REAL R)
IF R (= 0 THEN EXIT FUNCTION
SPHERE_VOLUME = 4/3 * PI * R ** 3
END FUNCTION

This function returns the volume of a sphere of radius R. If this function is invoked with an actual
parameter value less than or equal to zero, the function returns zero.
Because external functions are subprograms, you can pass modifiable parameters (including entire
arrays) to them. See BASIC on VAX/VMS Systems, BASIC on RSX-IIM/M-PLUS Systems or BASIC
on RSTS / E Systems for more information on subprograms and modifiable parameters.

6.4.2 EXTERNAL Statement
Function subprograms must be declared with the EXTERNAL statement. When used in this way, the
EXTERNAL statement's format is:
EXTERNAL data-type FUNCTION {func-nam[([external-param], ... )]}, ...

pass-mech:

BY DESC }
BY REF
{
BY VALUE

external-param: [data-type] [DIM([,] ... )] [= int-const] [pass-mech]
where:
data-type

Is a BASIC data-type keyword. In VAX-ll BASIC, data-type can also be a RECORD
name.

func-nam

Is the name of the function. This name can be up to 6 characters for BASIC-PLUS-2
and up to 30 characters for VAX-ll BASIC.
Functions

6-27

DIM ([,] ... )

Specifies that the parameter is an array. You specify the number of dimensions in the
array with commas; no commas specifies a one-dimensional array, one comma
specifies a two-dimensional array, and so on.

int-const

Specifies the length of a string parameter, or the length of each element in a string
array parameter. Specifying string lengths for parameters is valid only in VAX-ll
BASIC.

In VAX-11 BASIC, each parameter can be followed by a BY clause, specifying a parameter passing
mechanism. The following example shows the declaration and invocation of the external function
defined in the previous example:

1000
1100
1200

EXTERNAL REAL FUNCTION SPHERE_VOLUME (REAL)
TEMP_VOLUME = SPHERE_VOLUME(5.825)
PRINT TEMP_VOLUME

Note that the EXTERNAL statement specifies only the data type of the parameter; it does not specify a
formal or actual parameter. Whenever you invoke an external function, BASIC converts the actual
parameter to the data type specified in the EXTERNAL statement.
Note that this module is compiled separately from the FUNCTION subprogram. You can link or taskbuild these modules together to run the program from monitor level. To run the program in the BASIC
environment, you: 1) compile the function subprogram, 2) load the resulting object module with the
LOAD command, 3) read in the main program with the OLD command, and 4) type RUN.
See BASIC on VAX /VMS Systems, BASIC on RSX-ll M / M-PLUS Systems, or BASIC on RSTS / E
Systems for more information on linking subprograms
Caution

Ensure that the parameter data types specified in the EXTERNAL statement agree with
those specified in the FUNCTION statement, or the function will produce unexpected

resu!ts.

6-28

Functions

Chapter 7
Arrays

This chapter describes how to create and use arrays. Arrays can have up to 8 dimensions in PDP-ll
BASIC-PLUS-2 and up to 32 dimensions in VAX-ll BASIC. Arrays can be redimensioned at run
time. In addition, you can use data-type keywords to specify the type of data the array contains.
An array is a set of data ordered in any number of dimensions. A one-dimensional array is called a list
or vector. A two-dimensional array is called a matrix. Subscripts define the position of an element in
an array. When you create an array, you specify the number of dimensions and the maximum
subscript value, or bounds, in each dimension. Thus, the bounds specified when the array is created
determine the size of the array.
BASIC arrays are zero-based; when calculating the number of elements in a dimension, you count
from zero to the number of elements specified.
You can create arrays either implicitly or explicitly. You implicitly create arrays having any number of
dimensions by referencing an element of the array. You create arrays explicitly by declaring them in a
DIM, DECLARE, COMMON, or MAP statement.
You can use MAT statements to create and manipulate arrays. However, you can use MAT statements
only on arrays of one or two dimensions.

7.1 Creating Arrays Explicitly
You can create arrays explicitly with four BASIC statements:
- DECLARE
- DIM[ENSION] [#]
-COMMON
- MAP

7-1

Normally, you can use the DECLARE statement to create arrays. However, in certain cases, you may
want to create the array with another statement:
• You use the DIM statement to create virtual arrays and arrays that can be redimensioned at run
time.
• You use the COtv1MON statement to create arrays that can be shared among program modules or to
create arrays of fixed-length strings.
• You use the MAP statement to create an array and associate it with a record buffer, or to overlay the
storage for an array, thus accessing the same storage in different ways.
When you create an array, bounds determine the array's size. The maximum value allowed for a
bound can be as large as 32767 (on PDP-11 systems) or 2147483467 (on VAX /VMS systems).
However, it is important to note that there is a limit to the amount of storage your system can
allocate. Although BASIC allows bound values within these ranges, very large arrays can cause an
internal allocation error. Also, arrays of more than two dimensions require a surprising amount of
storage. For example, an array with bounds of (1,1, 1,1,1,1,1,1) contains 256 elements.
The following sections explain the use of arrays with these statements.

7.1.1 Creating Arrays with the DECLARE Statement
The DECLARE statement creates and names variables and arrays. When used to create an array, its
format is:
DECLARE data-type array-nam(b1 [,b2 ... ,bnD ...

where:
data-type

Is a val id BASIC data-type keyword or a RECORD name (VAX-11 BASIC on Iy).

array-nam

Is the name of the array.

b1 ... bn

Are bounds. Arrays defined in DECLARE statements can have only constant values
as bounds. The number of bounds determines the number of dimensions the array
has; the value of each bound determines the maximum subscript value in that
dimension.
Note that the DECLARE statement does not allow implicit data typing; you must
specify a data-type keyword when creating arrays with DECLARE.

All elements of arrays created with the DECLARE statement are initiali'zed to zero or the null string.
For example:
100

DECLARE LONG FIRST_ARRAY(10)

This statement creates a longword integer array with 11 elements. Each element has an initial value of
zero.
Although BASIC initializes array elements to zero or the null string, it is good programming practice
to initialize all array elements by assigning them values in your program. For example, this program
creates a three-dimensional string array and initializes each element to the null string.

7-2

Arrays

100
200
300

DECLARE STRING SECOND_ARRAY(10tl0tl0)
DECLARE LONG LOOP_l t LOOP_2t LOOP_3
FOR LOOP_l = 0% TO 10%
FOR LOOP_2 = 0% TO 10%
FOR LOOP_3 = 0% TO 10%
NEXT LOOP_3
NEXT LOOP_2
NEXT LOOP_l

This program creates a 1331-element array of dynamic strings and initializes each element to the null
string.
Note data type STRING causes the creation of an array of dynamic strings. To create an array of fixedlength strings, declare the array in a COMMON or MAP statement.

7.1.2 Creating Arrays with the DIM Statement
The DIM statement creates and names an array or arrays·. You should use the DIM statement to create
an array only when you want to: 1) redimension the array at run time or 2) create a virtual array.
When creating arrays with DIM, you specify the type of data the array holds by either: 1) a data-type
keyword or 2) a speciai suffix on the array name. The DIM statement format is:
DIM[ENSION] [#int-const,] data-type array-nam(b1 [,b2 ... ,bn]) ...

where:
#int-const

Is the channel number of an open file on which you want to create a virtual array.

data-type

Is any valid BASIC data-type keyword or RECORD name (VAX-l1 BASIC only).

array-nam

Is the name of the array.

b1 ... bn

Are bounds. Arrays in DIM statements can have either constants or variables as
bounds. The number of bounds determines the number of dimensions the array has;
the value of each bound determines the maximum subscript value in that
dimension.

The array name can be any valid variable name. If you do not supply a data-type keyword, the data
type is determined by the suffix of the array name:
• If the array name ends in a dollar sign, the array stores string data.
• If the array name ends in a percent sign, the array stores integer data.
• If the array name ends in neither a percent sign nor a dollar sign, the array stores data of the default
type. The default type is single-precision floating-point unless you change the default. See Chapter 5
for more information on default data types.
If the DIM statement contains a data-type keyword, the array name cannot end in a dollar sign or
percent sign.
The DIM statement can be either executable or declarative. If the specified bounds are constants, the
DIM statement is declarative. This means that the storage is allocated at compile time, and the array
cannot appear in any other DIM statement.

Arrays

7-3

However, if any of the specified bounds are variables (simple or subscripted) the DIM statement is
executable. This means that the storage for the array is allocated at run time, and the array can be
redimensioned with a DIM statement any number of times.
Note
in the DiM statement, bounds can be either constants or variables (simple or subscripted), but not expressions.

When an array is redimensioned with the executable DIM statement, the array can become larger or
smaller than it was. However, redimensioning an array in this way causes it to be reinitialized, and all
data in the array is lost. In contrast, MAT statements let you redimension an array to be the same size
or smaller than it was. However, MAT statements redimension arrays only when assigning values or
performing matrix I/O; therefore, the fact that MAT reinitializes the array does not matter. See
Section 7.3 for more information on MAT statements.
These restrictions apply to arrays:
• When referencing an array, you must use the same number of subscripts as was specified in the
DIM statement.
• You can use identical names for a simple variable and an array; for example, A% and A%(5,5).
However, this is not recommended programming practice. If you use identical names for arrays
with a different number of subscripts, for example, A(5), and A(l 0,10), BASIC prints the warning
error "Inconsistent subscript usage" at compile time.
• If you reference an array element whose subscripts are larger than the subscripts specified in the last
execution of the DIM, or less than zero, BASIC signals the error "Subscript out of range" (ERR = 55).

7.1.2.1 Declarative DIM Statements
Declarative DIM statements are those with positive integer constants as bounds. The percent sign is
optional for bounds; however, BASIC signals "Integer constant required" if a constant bound contains
a decimal point. This is an example of a declarative DIM:
100

DIM #l%t STRING VIRT_ARRAY(100)

= 256%

This statement creates a 101-element virtual array containing string data. The elements of this array
can have a maximum length of 256 characters. These restrictions apply to the use of declarative DIM
statements:
• A declarative DIM statement must lexically precede any reference to the array it dimensions.
• For declarative DIM statements, if you reference an array element whose subscripts are larger than
the subscripts specified in the DIM statement, BASIC signals the error "Subscript out of range"
(ERR= 55).
• Because a declarative DIM allocates storage at compile time, an array of this type cannot appear in
any other declarative statement such as COMMON, MAP, DECLARE, or a later DIM statement.

7.1.2.2 Executable DIM Statements
Executable DIM statements are those with at least one variable bound. Bounds can be constants or
simple variables, but at least one bound must be a variable. Executable DIM statements let you
7-4

Arrays

redimension an array at run time. The array can become larger or smaller, but the number of bounds
cannot change. That is, you cannot redimension a four-dimensional array to be five-dimensional.
The executable DIM statement cannot be used on arrays in COMMON, MAP, DECLARE or declarative DiN\ statements, nor on virtual arrays or arrays received as formal parameters.
An executable DIM statement always reinitializes the array to zero (for numeric arrays) or the null
string (for string arrays), thus destroying any data that was in the array. For example:
}C>': = 10
DIM REAL_ARRAY(X1)
REAL_ARRAY(11) = 100
PRINT REAL_ARRAY(11)
DIM REAL_ARRAY(X1)
PRINT REAL_ARRAY(11)

100
200
300
400
500
GOO
RUNNH
100

o
The 011\1\ statement in line 500 reinitializes REAL_ARRAY; thus, REAL_ARRAY(l %) equals zero in
line 600.
You cannot reference any array element until the array has been dimensioned with the executable
DIM statement. An attempt to do so causes BASIC to signal "Subscript out of range" (ERR = 55).

7.1.3 Creating Arrays with the COMMON Statement
You should create arrays with COMMON when you need an array of fixed-length strings, or when
you want to share an array among program modules. When used to create arrays, the COMMON
statement format is:
COM[MON] [(com-nam)] [data-type] array-nam(b1 [,b2 ... ,bn]) [= int-const]

where:
com-nam

Is the name of the COMMON block.

data-type

Is any valid BASIC data-type keyword or RECORD name (VAX-ll BASIC only).

array-nam

Is the name of the array.

b1 ... bn

Are bounds. Arrays in COMMON statements can have only constants as bounds.
The number of bounds determines the number of dimensions the array has; the
value of each bound determines the maximum subscript value in that dimension.

int-const

Specifies the length of each element in a string array.

Program modules can share arrays in COMMON statements by defining a COMMON block with the
same name. For example:
Main Program

100

1 oi..

COMMON (ABC) STRING ACCESS_LIST(100)

Subprogram

100
200

SUB SUBl
COMMON (ABC) STRING NEW_LIST(100)

101
Arrays

7-5

The COMMON statements in these programs create a 101-element array of fixed-length strings, each
element 10 characters long. Because the main and subprograms use the same COMMON name, the
storage for these arrays is overlaid when the programs are linked or task-built. Thus, both programs
can read and write data to the array.

7.1.4 Creating Arrays with the MAP Statement
You should create arrays with MAP only when you want the array to be part of a record buffer, or
when you want to overlay the storage containing the array. Note that string arrays in MAPs are always
fixed-length. When used to create arrays, the MAP statement format is:
map (map-nam) [data-type] array-nam(b1 [,b2 ... ,bn)) [= int-const]
where:
map-nam

Is ~he name of the MAP. MAP statements require a map-nam.

data-type

Is any valid BASIC data-type keyword or RECORD name (VAX-ll BASIC only).

array-nam

Is the name of the array.

b1 ... bn

Are bounds. Arrays in MAP statements can have only constants as bounds. The
number of bounds determines the number of dimensions the array has; the value of
each bound determines the maximum subscript value in that dimension.

int-const

Specifies the length of each element in a string array.

You associate the array with a record buffer by naming the MAP in the MAP clause of the OPEN
statement. For example:
100
200

MAP (ABC) STRING TEAM(10) = 20t WORD BOWLING_SCORES(32)
OPEN "BOWLING.DAT" AS FILE #l%t SEQUENTIAL !..lARIABLEt &:
MAP ABC

The MAP statement creates two arrays: an ll-element fixed-length string array named TEAM and a
33-element array of WORD integers named BOWLING_SCORES. Because the OPEN statement
specifies MAP ABC, the storage for these arrays is used as the record buffer for the open file.

7.2 Creating Arrays Implicitly
There are two ways to create implicit arrays: 1) by referencing an element of an array that has not
been explicitly declared and 2) with MAT statements. When BASIC first creates an implicit array, the
maximum subscript value is 10, although you can redimension implicit arrays with an executable
DIM statement.
An array created by referencing an element can have up to 8 dimensions in PDP-ll BASIC-PLUS-2
and up to 32 dimensions in VAX-ll BASIC. An array created with a MAT statement can have only
one or two dimensions.
Note
The ability to create arrays implicitly exists for compatibility with previous implementations of BASIC. However, it fs much better programming practice to explicitly
declare all arrays before using them.

7-6

Arrays

If you reference an element of an array that has not been explicitly declared, BASIC creates a new
array with the name you specify. Arrays created by reference have default subscripts of (10), (10,10),
(10,10,10) and so on, depending on the number of dimensions specified in the array reference. For
example:
10
20
30
40

LET A(5t5t5) = 3.14158
LET 5%(3) = 33
LET C$(2t2) = "Shirley MerKel"
END

This program implicitly creates three arrays by reference and assigns a value to one element of each.
• Line 10 creates an ll-by-ll-by-ll array that stores floating-point numbers and assigns the value
3.14159 to element (5,5,5).
• Line 20 creates an ll-element I-ist that stores integers and assigns the value 33 to element (3).
• Line 30 creates an ll-by-ll string array and assigns the value "Shirley Merkel" to element (2,2).
When you create an implicit numeric array by referencing an element, BASIC initializes all elements
(except the one assigned a value) to zero. For implicit string arrays, BASIC initializes all elements
(except the one assigned a value) to a null string. When you create an array by reference, you cannot
specify a subscript greater than 10. An attempt to do so causes BASIC to signal "subscript out of
range" (ERR = 55).
Note that you cannot create an array implicitly, then redimension the array with a executable DIM
statement. The DIM statement must execute before any reference to the array.
An implicit array cannot appear in a declarative DIM statement. For example, the first program is
valid while the second is not:
Example 1

100
200

DIM NEW_ARRAY(15tl0t5)
NEW_ARRAY(5t5t5) = 1

Example 2

100
200

NEW_ARRAY(5t5t5) = 1
DIM NEW_ARRAY(15tl0t5)

In the first program, line 100 dimensions an array with a declarative DIM statement. Line 200 assigns
a value to an element of that array. In the second program, line 100 creates an implicit array. The
program fails because the DIM statement on line 200 is declarative (it contains only constant
subscripts).

7.3 MAT Statements
MAT statements let you assign values to or display entire arrays with a single statement. They also:
• Implicitly create arrays
• Assign names to arrays
• Specify array dimensions

Arrays

7-7

• Redimension existing arrays (to equal or smaller sizes)
• Assign element values
• Print the contents of arrays
• Perform matrix arithmetic

Note
MAT statements cannot be used on arrays of more than two dimensions, on DECIMAL
arrays, nor on arrays appearing in RECORD instances (the DECIMAL data-type and
RECORD statements are available only in VAX-ll BASIC). Further, when MAT statements execute, they use row and column zero to store intermediate calculations. This
means that MAT statements can overwrite data stored in row and column zero, and
you should not depend on data in these elements if your program uses MAT
statements.
The default subscripts for arrays created implicitly with MAT statements are (10) or (10,10). The
default is two dimensions. This means that, if you create an array with a MAT statement and do not
specify any subscripts, BASIC creates a two-dimensional, ll-by-ll array. If you specify a single
subscript, BASIC creates a one-dimensional array with 11 elements.
Table 7-1 lists MAT statements and explains their function.

Table 7-1: MAT Statements

Function

Statements
MAT

Assigns values of zero, one, or a null string to array elements. Also copies the values of one array
to another and performs matrix arithmetic.

MAT INPUT [#]

Assigns values to array elements from your terminal or a terminal-format file.

MAT LlNPUT [#]

Assigns string values to string array elements from your terminal or from a terminal-format file.

MAT PRINT [#]

Displays the contents of an array on your terminal, or writes array element values to a terminalformat file.

MAT READ

Assigns DATA statement values to array elements.

For example:

10 MAT Z.ARRAY$
20 MAT Z.ARRAY$
30 MAT A = B + C

NUL$(7,7)
NUL$(5,5)

40 END

Line 10 creates the string array Z.ARRAY$ with eight rows and eight columns and assigns a null string
to all elements. Line 20 redimensions the array to six rows and six columns. Line 30 adds the values
in each corresponding element of arrays Band C and stores the values in the corresponding elements
of array A.

7-8

Arrays

7.3.1 Assigning Values to Array Elements
You can assign values to array elements: 1) from within your program, 2) from an external source,
such as the terminal or files, or 3) with MAT statements.
You can assign values within your program with:
• The LET statement
~ The MAT statement

• The MAT READ statement
7.3.1.1 Assigning Values with the LET Statement

The LET statement assigns values to individual array elements:
100 DIM VOUCHER.NUM%(100)
+

3520 LET VOUCHER.NUM%(20)
t

3253'X,

32767 END

You can also assign values to a portion of an array with the LET statement and a FOR-NEXT loop:
100 DIM PO.NUMBER%(100tl00)
+

2040 FOR 1% = 1% TO 3%
2050
FOR J% = 5% TO 10%
2060
LET PO.NUMBER%(I%tJ%)
2070
NEXT J%
2080 NE}-{T 17.,

32767 END

The FOR/NEXT loop in lines 2040 through 2080 assigns zero to array elements (1,5) through (1,10),
to (2,5) through (2,10), and to (3,5) through (3,10).
7.3.1.2 Assigning Values with the MAT Statement

The MAT statement can create an array and optionally assign values to all elements. Its format is:

MAT array-name = mat-keyword [(subscript[,subscript])]
The array name can specify an existing array. MAT statements do not assign values to row and
column zero.
Table 7-2 lists MAT statement keywords and their functions.

Arrays

7-9

Table 7-2: MAT Statement Keywords

MAT Keyword

Function

ZER

Sets the value of all elements in a numeric array to zero.

CON

Sets the value of all elements in a numeric array to one.

IDN

Sets the array to the identity matrix, that is, it sets the value of all elements in real or integer arrays to
zero, except for those elements on the diagonal from element (1,1) to element (n,n), where n is the
largest subscript in the array. The elements on the diagonal are set to one. IDN applies to square arrays
only.

NUL$

Sets the value of all elements in a string array to a null string.

The MAT statement does not require subscripts. For existing arrays:
• If you do not specify subscripts, BASIC does not change the current subscripts.
• If you specify subscripts, BASIC redimensions the array to the specified subscripts. When redimensioning arrays with MAT, you cannot increase the total number of array elements (including those in
row and column zero).
When creating arrays with MAT:
• If you do not supply subscripts, BASIC assigns two subscripts, each with a value of 10 .
• If you specify subscripts, they define the dimensions of the array being implicitly created. Subscript
values cannot exceed 10.
For example:
10

DHI A(10tlO), 5(15), C(20,20)

20
30
40
50

MAT A
ZER
!Sets all eleMents of A to 0
MAT 5 = CON(lO) !Sets eleMents of 5 to 1; rediMensions 5
MAT C = IDN(lO,lO) !RediMensions C to 10xlO identity Matrix
MAT PRINT A;
PRINT
PRINT
MAT PRINT 5;
PRINT
PRINT
MAT PRINT C;

60
70
RUNNH
0
0
0
0
0
0

0
0
0
0

0
0

0
0
0
0
0
0
0
0

0
0

0
0
0

0
0
0
0
0

0
0
0
0

0
0
0

0
0

0
0
0

0
0
0
0
0
0
0

0
0
0
0
0
0
0
0
0
0

(ARRAY A)

(ARRAY 5)

7-10

Arrays

0
1
0
0
0
0
0
0
0
0

1
(I

(I
(I

0
0
0
0
0
0

0
1
0

0
0
1
0

0
0
0
0
0

0
0
0
0

0
0
0
(I

1
0
0
0
0
0

0
0
0
0
0
1
(I

0
0
(I

0
0
0
0
0
1
0
0

0
0
0

0
0
0
0
0
0
0

0
0
1
0
0
0

0
0
1
0

(ARRAY

7.3.1.3 Assigning Values with the MAT READ Statement

The MAT READ statement assigns values from DATA statements to array elements. Its format is:
MAT READ array-name [(subscript [,subscript])] ...

Subscripts are optional. They define: 1) the dimensions of the array being created or 2) the new
dimensions of an existing array.
If you do not provide enough data in DATA statements to fill the specified array, BASIC leaves the
remaining array elements unchanged. If you provide more data values than there are array elements,
BASIC assigns enough values to fill the array and leaves the DATA pointer at the next value. For
example:

10
20
30

MAT READ 5(2t2)
MAT READ C(2t2)
PRINT
PRINT "MATRIX 5"
PRINT
PRINT
MAT PRINT 5;
PRINT
PRINT "MATRIX C"
PRINT
PRINT
MAT PRINT C;
DATA 1 t2 t3 t4 t5 t8 t7 tB t8 dO
END

50
80
RUNNH
MATRIX 5
1

MATRIX C
5
7

8
B

BASIC fills matrix B with the first four DATA items, fills matrix C with the next four DATA values, and
leaves the DATA pointer at the ninth value in the DATA list.

7.3.2 Assigning yalues from the Terminal
You can assign values to array elements while your program is executing with:
• MAT INPUT
• MAT LlNPUT

Arrays

7-11

7.3.2.1 MAT INPUT Statement
The ,\I\AT INPUT statement assigns values from your terminal to array elements. Its format is:
MAT INPUT array-name [(subscript [,subscript])] ...

The optional subscripts define: 1) the dimensions of the array being created implicitly or 2) the new
dimensions of an existing array. If you are creating the array, the value of a subscript cannot exceed
10.
The MAT INPUT statement requests data from your terminal, as does the INPUT statement; it prints a
question mark (?) prompt. However, you cannot include a string prompt with the MAT INPUT
statement.
In response to the question mark, enter a series of values separated by commas. BASIC enters the
values you type into successive array elements by row, starting with element (1,1) and filling row 1
before starting row 2. If you provide fewer data items than there are elements, the remaining elements
are unchanged.
For example:

MAT INPUT
PRINT
MAT PRINT
MAT INPUT
PRINT
PRINT
MAT PRINT

10
20
30

A
A;
B (2 t2)

RUNNH
1 t2 t3 ta t5 tG t7 tB t9 tiO til ti2 ti3

3
1 2
11 12 13
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
I)
I)
0
I)
I)
0

a
I)

5
0
0
0
0
0
0
0

0
0
0
0
0
0
0

G
0
0
0

0
0

0
0
0
0
0
0
0

0
0

10
0
I)

0
0
0
0

1 t2 t3 ta

1
3

BASIC creates a 10-by-1 0 matrix for Array A by default. The values supplied by the MAT INPUT
statement fill the first 13 elements, filling row 1 before beginning row 2. The remainder of the matrix
elements contain zeros. Lines 30 and 40 redimension array B to 9 elements, provide values for its
elements, and display the results. If you provide more items than there are elements, BASIC ignores
the excess.

7-12

Arrays

The MAT INPUT statement can also redimension an existing array. For example:

10 DIM NEW+ARRAY%(5f5)
20 MAT INPUT NEW.ARRAY%(2,4)
30 MAT PRINT NEW;ARRAY%;
40 END
RUNNH

1 234
567 8
When entering values in response to MAT INPUT, you can enter an ampersand as the last character
on the line and continue on the next line.

7.3.2.2 MAT LINPUT Statement
The MAT LlNPUT statement assigns string values to string array elements. Its format is:
MAT LlNPUT {array-name [(subscript [, subscript])]} ,...

The optional subscripts define: 1) the dimensions of the array being created or 2) the new dimensions
of an existing array. If you are creating the array, subscript values cannot exceed 10.
The MAT LlNPUT statement prompts for individual array elements. It fills the array by rows, starting
with element (1,1). It assigns the line you type (including commas, semicolons, and quotation marks)
to an array element; however, the line terminator is not included. For example:

10
20
30
40
50
60
70

DIM EMP.NAM$(5,5)
MAT LINPUT EMP.NAM$(2,2)
PRINT EMP.NAM$( 1 t1)
PRINT EMP.NAM$(1 ,2)
PRINT EMP.NAM$(2,1)
PRINT EMP.NAM$(2,2)
END

RUNNH
? HODGES
? LAFFERTY
? ELDON

? HOPKINS

HODGES
LAFFERTY
ELDON
HOPKINS
By specifying the subscripts (2,2) in line 20, MAT LlNPUT redimensions the array to four elements
and then prompts for these elements.

7.3.3 Assigning Values from Terminal-Format Files
Two statements transfer data from a terminal-format file to an array:
• MAT INPUT #
• MAT LlNPUT #

Arrays

7-13

7.3.3.1 MAT INPUT # Statement
The tv,\AT INPUT # statement reads data from a terminal-format file and writes it to an array. Its
format is:
MAT INPUT #chnl-exp, array-name [(int-exp [,int-exp])]

The channel expression specifies an open terminal-format file. The array name specifies the array to
which the values are assigned.
The MAT INPUT # statement takes values from the file and assigns them to the matrix elements by
rows, starting with element (1) or (1,1). It fills the elements in row 1 before starting row 2. The file can
have one or more values in each record, however, if multiple values must be separated with commas.
If there is more data in the file than there are array elements, BASIC ignores the excess. If there is less,
the remaining elements are unchanged.

7.3.3.2 MAT LlNPUT # Statement
The MAT LlNPUT statement reads string values from a terminal-format file and writes them to a string
array. Its format is:
MAT LlNPUT #chnl-exp, {str-arr-nam [(subs [,subs)))}, ...

where:
#chnl-exp

Is the channel number of an open terminal-format file.

str-arr-nam

Is the name of the string array to receive the data.

subs

Is a subscript. The subscripts determine how much data is assigned to the array.

MAT LlNPUT excludes line terminators when assigning values to string array elements.
If there are more values in the file than there are array elements, BASIC ignores the excess. If there are
fewer, BASIC assigns a null string to the remaining elements. For example:

10 OPEN "PARTS.DAT" FOR INPUT AS FILE #17..
20 DIM PART_NAME$(50)
30 MAT LINPUT #l%t PART_NAME$

This program reads 50 records from the disk fi Ie PARTS. OAT to the array named PART _NAME$.

7.4 Array Output
You can write data from an array with:
• The PRI NT statement
• The MAT PRI NT statement
• The MAT PRI NT # statement

7-14

Arrays

7.4.1 PRINT Statement
You print individual array elements by naming those elements in the PRINT statement. For example:
"

•

i i i

310 PRINT PARTS.LIST$(35)
•

••

•

With a FOR-NEXT loop, you can print all or part of an array:
100 DIM CAPTURE.RATIO(10tl0)
•

•

10030 FOR Y% = 7% TO 10%
FOR X% = 7% TO 10%
10040
PRINT CAPTURE.RATIO(X%tY%)
10050
10(iGO

klr\/.,..

1'11:.1\ 1

\1"/

1,10,

10070 NE}{T Y'Y.,
•

••

32767 END

7.4.2 MAT PRINT Statement
The MAT PRINT statement prints some or all of an array's elements, excluding row and column zero.
Its format is:
MAT PRINT array-name [(subs [,subs])]

where:
array-name

Is the name of the array.

subs

Is a subscript.

Subscripts are optional. If you do not specify subscripts, MAT PRINT displays the entire array,
excluding row and column zero. If you specify subscripts, MAT PRINT displays that subset of the
array. The MAT PR!NT statement does not redimension an existing array.
If the last character in the MAT PRINT array list is a:
Semicolon

BASIC begins each array on a separate line. Data values on each line are packed
together.

Comma

BASIC begins each array row on a separate line and each data value in a separate
print zone.

If there is neither a comma nor semicolon after the array name, BASIC prints each array element on a
separate line. For example:
10 MAT INPUT A(5)
15 PRINT
20 MAT PRINT A
25 PRINT
30 MAT PRINT At A;
60 END
(continued on next page)

Arrays

7-15

RUNNH
? 5

0
0
r•
.....

5
(I

(I
(I

7.4.3 MAT PRINT # Statement
The MAT PRINT # statement reads values from an array and writes them to a terminal-format file. Its
format is:
MAT PRINT #chnl-exp, {array-name [(subs [,subsD]}, ...

where:
#chnl-exp

Is the channel number of an open terminal-format file.

array-name

Is the name of the array that holds the data.

subs

Is a subscript. The subscripts determine how many array elements are written to the
file.

MAT PRINT # takes values by row, starting with element (1) or (1,1), and writes each element to a
sequential record in the terminal-format file.

7.4.4 Matrix I/O Functions (NUM and NUM2)
MAT statements do not signal error messages when:
• There are more data items than array elements to contain them .
• There are fewer data items than array elements to contain them.
BASIC provides two functions that let you determine how much data these statements transfer.
For two-dimensional arrays, the NUM function returns an integer value specifying the row number of
the last data item transferred. For one-dimensional arrays, the NUM function returns the number of
items entered. Its format is:
NUM

The NUM2 function returns: 1) for two-dimensional arrays, an integer value specifying the column
number of the last data item transferred, and 2) for one-dimensional arrays, a zero. Its format is:
NUM2

7-16

Arrays

With these functions, you can determine the number of items transferred from a terminal-format file.
For example:

10 OPEN EMP. OAT FOR I NPUT AS FILE
20 DIM EMP.NAME$(StS)
30 MAT INPUT #3%t EMP.NAME$
40 PRINT NUMt NUM2
50 END
II

#37..

7.5 Matrix Operators
BASIC provides a special set of MAT statements for array computations. These statements enable you
to add, subtract, and multiply matrices, and to assign values to elements. If you specify an array
without subscripts (for example, MAT A), the default is two dimensions.
BASIC also provides matrix functions to transpose and invert matrices, and to find the determinant of
a matrix you invert.

Note
MAT operators do not operate on elements in row or column zero.

7.5.1 Arithmetic Matrix Operations
MAT operators perform matrix:
• Assignment
• Addition
• Subtraction
• Multiplication
All of these operations use the keyword MAT followed by an expression. If the array has not been
previously dimensioned, these operations create an array. (The created output array's dimensions
depend on the operation performed, but must be (10,10) or smaller.)

Note
You can use the MAT operators on arrays larger than (10,10) if the input and output
arrays are explicitly created or received as a formal parameter.

7.5.1.1 Assignment

You can assign all values in one array to another array with the keyword MAT. For example:

10 MAT NEW.ARRAY = OLD.ARRAY
This example sets each element of NEW.ARRAY to the corresponding element in OLD.ARRAY. It also
redimensions NEW.ARRAY to the dimensions of OLD.ARRAY.

Arrays

7-17

7.5.1.2 Addition and Subtraction
To add the elements of two arrays, use the format:
MAT output-array = input-arraY1 + input-array2
To subtract the eiements of two arrays, use the format:
MAT output-array = input-arraY1 - input-array2
For example:

10 MAT SUM.LIST% = FIRST.LIST% + SECOND.LIST%
The two input lists, FIRST.LlST% and SECOND.LlST%, must have identical dimensions. The elements
of the new list, SUM.LlST%, equal the sum of the corresponding elements in the input lists.
This program subtracts one array from another:

10
ZO
30
•

DIM FIRST.ARRAY(30,30)
DIM SECOND.ARRAY(30,30)
DIM DIFFERENCE.ARRAY(30,30)
t

100
f

•

MAT DIFFERENCE.ARRAY = FIRST.ARRAY - SECOND.ARRAY
t

•••

3Z767 END
Each element of DIFFERENCE.ARRAY is the arithmetic difference of the corresponding elements of
the input arrays.

7.5.1.3 Multiplication
The format for matrix multiplication is:
MAT output-array = input-arraY1 * input-array2
The number of columns in input-arrayl must equal the number of rows in input-array2. The output
array contains the dot product of the two input arrays. For example:

100
ZOO

DIM A(Z,Z), 6(Z,Z), C(Z,Z)
A( 1 ,1 )
1
A(l,Z)
Z
A(Z,1)
3
A(Z,Z)
a
6 ( 1 ,1 )
5
6(1,Z) = 6
6(Z,1) = 7
6(Z ,Z)
8
MAT C = A * 6
MAT PRINT C

300

aoo

500

You can also multiply a matrix by a scalar quantity. The format is:
MAT output-array = (num-exp) * input-array

7-18

Arrays

BASIC multiplies each element of the input array by the scalar quantity you supply. The output array
has the same dimensions as the input array. Enclose the scalar quantity in parentheses. For example:

10 DIM INCH.ARRAY(5) t CM.ARRAY(5)
20 MAT READ INCH. ARRAY
30 DATA 1,12,36,100t38.37
40 MAT CM.ARRAY = (2.54) * INCH.ARRAY
50 MAT PRINT CM.ARRAY,
60 END
RUNNH
2.54

30.48

81.44

254

88.8888

Line 40 multiplies the elements of INCH.ARRAY by the inch-to~centimeter conversion factor and
places these values in CM.ARRA Y.

7.5.2 Matrix Functions
BASIC provides three matrix functions:
• TRN

-INY

• DET
With these functions, you can: 1) transpose matrices, 2) invert matrices, or 3) find the determinant of
an inverted matrix.

7.5.2.1 TRN Function

The TRN function transposes a matrix. Its format is:
MAT output-array = TRN(input-array)

When you transpose a matrix, BASIC interchanges the array's dimensions. For example, a matrix with
N rows and M columns is transposed to a matrix with M rows and N columns. The elements in the·
first row of the input matrix become the elements in the first column of the output matrix. You cannot
transpose a matrix to itself; MAT A = TRN(A) is invalid.
This example creates a three-by-five matrix, transposes it, and prints the results:

10 DIM 6(3,5)
20 MAT READ 6
30 MAT A = TRN(6)
40 DATA 1,2t3,4,5
50 DATA 6,7,8,8t10
60 DATA 11,12,13,14,15
70 MAT PRINT 6;
80 MAT PRINT A;
80 END
(continued on next page)

Arrays

7-19

RUNNH
1 2 3 4 5
6 7 8 9 10
11 12 13 14 15
2
3
4
5

6
7
8
9
10

11
12
13
14
15

7.5.2.2 INV Function
The INV function inverts a matrix. Its format is:
MAT output-matrix = INV(input-matrix)
BASIC can invert a matrix only when: 1) its subscripts are identical, and 2) it can be reduced to the
identity matrix by elementary row operations.

7.5.2.3 DET Function
The DET function returns the determinant of a matrix. Its format is:
DET

The DET function returns a floating-point number that is the determinant of the last matrix inverted. If
you use the DET function before inverting a matrix, the value of DET is zero.

7-20

Arrays

Chapter 8
Formatting Output with the PRINT USI~~G Statement

The PRINT USING statement controls the appearance and location of data on a line of output. With
it, you can create formatted lists, tables, reports, and forms.
The ability to format data is useful because the way BASIC internally represents data may not be the
best way to display that data in a report or table. For example, a program may use floating-point
numbers to represent dollars and cents. The PRINT statement displays floating-point numbers with up
to six digits of accuracy and can place the decimal point anywhere in that 6-digit field. In contrast,
PRINT USING lets you display floating-point numbers:
• Rounded to two decimal places
• Vertically aligned on the decimal point
• Preceded by a doiiar sign
• With commas every third digit to the ieft of the decimal point
Formatting monetary values in this way makes a much more readable report. Another use for formatted numeric values might be to print checks on the computer's line printer. To do this, PRINT USING
lets you print numbers with a dollar sign and an asterisk-filled field preceding the first digit.
PRINT USING also formats string data. With it you can left- and right-justify string expressions or
center a string expression over a specified column position. Further, the PRINT USING statement can
contain string literals. These are strings that do not control the format of a print item but instead are
printed exactly as they appear in the format string.
The PRINT USING statement requires a format string. This format string determines the way in which
the items to be printed are formatted. You specify the format string in the PRINT USING statement; it
can be a literal, a variable, a named string constant, or a combination of these.
This chapter explains how to create a format string and then how to use a format string to display
numeric and string data.

8-1

8.1 PRINT USING
The format of the PRINT USING statement is:
PRINT USING {str-exp}, exp [, expo .. J

where:
str-exp

Contains one or more PRINT USING format fields. Str-exp can be a string variable or
a string literal. If it is a string literal, you must enclose it in double quotation marks.

exp [,exp]

Is a list of items to be printed.

The specification of the format string immediately follows the USING keyword and can be:
• A string literal
• A string variable
• A named stri ng constant
• Any combination of these
You must separate print items with commas or semicolons. Separators between print items do not
affect output format as they do with the PRINT statement. However, if a comma or semicolon follows
the last print item, BASIC does not return the cursor or print head to the beginning of the next line
after it prints the last item in the list.

8.1.1 Creating a Format String
The PRINT USING statement requires a format string to control the appearance of the output line. The
format string is made up of format fields; each format field controls the output of one print item.
You can think of the format string as an image of the PRINT USING output line. Each format field in
the format string controls the appearance of one print item. Thus, BASIC scans the format string and
uses the first format field to control the appearance of the first print item, the second format field to
control the appearance of the second item, and so on. If all the format fields in the format string have
been used and there are still items to be printed, BASIC moves the cursor or print head to the
beginning of the next line and reuses the format string starting at the first format field.
You need not delimit format fields within a format string. Each format field can contain only certain
characters (as described in the following sections). BASIC scans the format string character by character; as soon as it encounters a character that is invalid for the current format field, BASIC ends the
current format field. The character that terminates the previous field can begin either: 1) a new format
field or 2) a string literal. For example:
100

PRINT USING II###ABC###II t

123 t 345

RUNNH
123ABC345

The first three characters in the format string (###) make up a valid numeric format field. The fourth
character (A) is invalid in a numeric format field; therefore, BASIC ends the first format field after the
third character. BASIC continues to scan the format string, searching for a character that begins a
format field. The first such character is the pound sign at character position seven. Therefore, the

8-2

Formatting Output with the PRINT USING Statement

characters at positions four, five, and six are stored as a string literal. The characters at positions
seven, eight, and nine make up a second valid numeric format field.
When the statement executes, BASIC prints the first number in the list using the first format field, then
prints the string literal ABC, and finally prints the second number in the list using the second format
field.
Because any character not part of a format field is printed just as it appears in the format field, you
can use a space or multiple spaces to separate format fields in the format string. For example:
100
200
300

DECLARE STRING CONSTANT FORMAT_STRING = 11###.##
DECLARE SINGLE AtB
A = 2.565
B = 100.350
PRINT USING FORMAT_STRINGt At Bt At B

###.##11

RUNNH
2.57
2.57

100.35
100.35

vVhen line 300 executes, BASIC prints the value of A (rounded according to PRINT USING rules),
three spaces, then the value of B. BASIC prints the three spaces because they are treated as a string
literal in the format string. Notice that when BASIC reuses a format string, it begins on a new line.
Any of these format string specifications can contain multiple format fields. BASIC reuses the format
string as many times as necessary to print all the items in the list. Whenever BASIC reuses a format
string, it starts a new line of output.

8.1.2 Reusing the Format String
The process of reusing the PRINT USING format string is called format reversion. If BASIC reaches the
end of the format string and items remain to be printed, BASIC starts again at the beginning of the
format string and continues printing on the next line. The following example uses and reuses both
numeric and string format fields:
10 PRINT USING ITEM: 'LLLLLLLLLL PRICE: $$## t###.##11 t &:
CANOE t 425.99 t BACK PACK t 52.80 t CAMERA t 325.89
II

RUNNH
ITEM: CANOE
ITEM: BACKPACK
ITEM: CAMERA

PRICE:
PRICE:
PRICE:

$425.99
$52.80
$325.89

This example shows how PRINT USING displays multiple numbers using a single format field:
100
200

PR I NT US I NG
END

#####. ### t 2.0 t - 1 (1.6 t 110.43 t 9862.36 t 126.32
II

RUNNH
2.000
-10.600
110.430
9862.360
126.320

Because the format string is reused for each print item, each print item appears on a new line.

Formatting Output with the PRINT USING Statement

8-3

8.2 Printing Numbers
With the PRINT USING statement, you can specify:
• The number of digits to print, thus rounding the number to a given place
• The decimal point location, thus vertically aligning numbers at the decimal point
• Special symbols, including trailing minus signs, asterisk-filled number fields, floating currency symbols, embedded commas, and E notation
• Debits and credits
• Leading zeros or leading spaces
• Blank-if-equal-to-zero fields
• That a special character is to be printed as a literal
Unlike the PRINT statement, PRINT USING does not automatically print a space before and after a
number. Unless you reserve enough digit positions to contain the integer portion of the number (and
a minus sign, if necessary), BASIC prints a percent sign (%) and displays the number in PRINT format.

8.2.1 Specifying the Number of Digits
You reserve places for digits by including a pound sign (#) for each digit position. If you print
negative numbers, you must also reserve a place for the minus sign. For example:
10 PRINT USING
20 PRINT USING
30 PRINT USING
40 END

t123
!Three places reserl)ed
t12345 !Five places reserved
ii####" t-678
!Four places reserl)ed

"###"

"#####"

RUNNH
123
12345
-678

If there are not enough digits to fill the field, BASIC prints spaces before the first digit:
10
20
30
40
50
60

FDRMAT_STRING$ = "#####"
PRINT USING FORMAT_STRING$t
PRINT USING FORMAT_STRING$t 10
PRINT USING FORMAT_STRING$t -1708
PRINT USING FORMAT_STRING$t 12345
END

RUNNH
1

10
-1708
12345

8-4

Formatting Output with the PRINT USING Statement

If you have not reserved enough digits to print the fractional part of a number, BASIC rounds the
number to fit the field:
10 PRINT USING "###" .126.7
20 PRINT USING "#" 15.8
30 PRINT USING "#"t5.4

40 END
RUNNH
127
6
5

If you have not reserved enough places to print a number's integer portion, BASIC prints a warning
message followed by the number in PRINT statement format. After BASIC prints the number, it
completes the rest of the list in PRINT USING format. For example:
10 PRINT USING
20 PRINT USING

"###" t

256
256

"##" 1

40 END
RUNNH
256
% 256

PRINT USING displays the number in line 10. In line 20, there are not enough places to the left of the
decimal point to display a 3-digit number; therefore, BASIC prints the number in PRINT statement
format, with a space before and after, but includes a warning sign (%).

8.2.2 Specifying Decimal Point Location
The decimal point's position in the format string determines the number of reserved places on either
side of it. If the print item's fractional part does not use all of the reserved places to the right of the
decimal point, BASIC fills with zeros. For example:

10
20
30

DECLARE STRING CONSTANT FM
PRINT USING FMt 15.72
PRINT USING FMI 38.3758
PRINT USING FMI 26

= "##.###"

RUNNH
15.720
38.376
26.000

The following example shows how PRINT USING rounds numbers when specifying decimal point
location:
10
20
30

PR I NT US I NG
PRINT USING
PR I NT US I NG
END

## • ## II 1

25. 788

"##.###" 1

100.2

# • ## II t .888

RUNNH
25.78
1. 100.2
1. 00

Formatting Output with the PRINT USING Statement

8-5

If there are more fractional digits than reserved places to the right of the decimal point, BASIC rounds
the number to fit the reserved places. Note that there must be enough places reserved to the left of the
decimal point for the integer portion of the number. Otherwise, BASIC prints the number in PRINT
format preceded by a warning sign.
BASIC always fills all reserved spaces to the left of the decimal point with specified digits, spaces, or
the minus sign:
10
20
30

PRINT USING
PRINT USING
PRINT USING

END

5.25
-5.25
1I###.##lI t -5.25

1I##.##lIt
11##.##11 t

RUNNH
5.25
-5.25
-5.25

8.2.3 Printing Numbers with Special Symbols
Special symbols let you print numbers with trailing minus signs, asterisk-fill fields, floating currency
symbols, commas, or E notation. You can also specify debits, credits, leading zeros, leading blanks,
and blank-if-zero fields. Table 8-1 summarizes these special characters.

Table 8-1: Format Characters for Numeric Fields

Character

Effect on Format

pound sign

Reserves place for one digit.

decimai point (period)

Determines decimai point iocation.

comma

Prints a comma between every third digit to the left of the decimal point and
reserves a place for one digit or comma.

**
$$

two asterisks

Print leading asterisks before the first digit and reserve places for two digits.

two dollar signs

Print a currency symbol before the first digit. They also reserve places for the
currency symbol and one digit. By default, the currency symbol is a dollar sign.
To change the currency symbol, refer to Section 8.2.3.3.

"AAA

four carets

Print a number in E (exponential) format and reserve four places for E notation.

minus sign

Prints a trailing minus sign for negative numbers. Printing a negative number in an
asterisk fill or a currency field requires that the field also have a trailing minus sign
or credit/debit character.

<0>

Zero in angle brackets

Prints leading zeros instead of leading spaces.

<%>

Percent sign in angle
brackets

Prints all spaces in the field if the value of the print item, when rounded to fit the
numeric field, is zero.

<CD>

CD in angle brackets

Prints credit and debit characters immediately following the number. BASIC prints
CR for negative numbers and zero, and DR for positive numbers.

Underscore

Specifies that the next character is a literal, not a formatting character.

8-6

Formatting Output with the PRINT USING Statement

February 1984

8.2.3.1 Commas

You can place a comma anywhere in a number field to the left of the decimal point and to the right of
the field's first character. A comma cannot start a format field. BASIC then prints a comma to the left
~(. ~"~ ..,, +1,.,.: .. ,..1

,..1:,...:+ f .. ,.,....,., +hn. ,..In.,...;...,., .... 1 ..... ,.,.i ... t-

VI C::VC::IY 1I111U U'51l IIUIII

UIC:

UC:~lIl1al

p V I I I l.•

1+ t-horo -,.ro +ou/or t-h'") ... trt.llr rlinitc trt. tho loft rt.f tho rlorirYl-:l1
II

l.1I\....1\....

UI\....

I\.... VV \....1

UIUII

IVUI

\ ....

5"..::> l.V UI\.... 1\....1l. VI l.1I\.... U\....\....IIII"'"

point, BASIC omits the comma. For example:
10
20
30
40
50
60

PRINT
PRINT
PRINT
PRINT
PRINT
END

USING
USING
USING
USING
USING

U##t###U tl0000
U##t###U t759
U$$#t###.##u t25694.3
u**#t###u t 7259
u####t#.##u t25239

RUNNH
10tOOO
759
$25t694.30
**7t259
25t239.00

8.2.3.2 Asterisk Fill Fields

To print asterisks (*) before the first digit of a number, start the field with two asterisks. For example:
5
10
20
30
40
50

DECLARE STRING CONSTANT FM
PRINT USING FMt 1.2
PRINT USING FMf 27.95
PRINT USING FMt 107
PRINT USING FMt 1007.5
END

= u**##.##u

RUNNH
***1.20
**27.95
*107.00
1007.50

Note that asterisks reserve two places as wei! as cause asterisk fi!1.
Specify a negative number in an asterisk-fill field by using a trailing minus sign in the field. The
trailing minus sign must be the last character in the format string. For example:
10
20
30
40
50

DECLARE STRING CONSTANT FM = u**##.##_u
PRINT USING FMt 27.95
PRINT USING FMt -107
PRINT USING FMt -1007.5
END

RUNNH
**27.95
*107.001007.50-

BASIC signals "PRINT USING format error" (ERR= 116) if you try to print a negative number in an
asterisk-fill field that does not include a trailing minus sign.
--... /

Formatting Output with the PRINT USING Statement

8-7

Note that you cannot specify both asterisk-fill and zero-fill for the same numeric field.
8.2.3.3 Currency Symbols
To print a currency symbol before the first digit of a number, start the field with two dollar signs. If the
data contains both positive and negative numbers, end the field with a trailing minus sign:
10
20
30
40
50
80
70

DECLARE STRING CONSTANT FM = "$$##.##-"
PRINT USING FM t 77.44
PRINT USING FM t 304.55
PRINT USING FM t 2211.42
PRINT USING FMt -125.8
PRINT USING FMt 127.82
END

RUNNH
$77.44
$304.55
% 2211.42
$125.80$127.82

Note that $$ reserves places for the currency symbol and only one digit; the $ is always printed.
(Hence the warning indicator (%) when line 40 executes.) Contrast this with the asterisk-fill field,
where BASIC prints asterisks only when there are leading spaces.

Note
By default, the currency symbol is a dollar sign. On VAX/VMS systems, you can
change the currency symbol, radix point, and digit separator by assigning the logical
names SYS$CURRENCY, SYS$RADIX, and SYS$ DIGIT _SEP.

BASIC signals "PRINT USING Format error" (ERR = 116) if you try to print a negative number in a
dollar sign field that does not include either a trailing minus sign or the CR/DR formatting character.
8.2.3.4 Negative Fields
To allow for a field containing negative values, specify a trailing minus sign in the format field. A
negative format field causes the value to be printed with a trailing minus sign. Note that you can also
denote negative fields with CR and DR. See Section 8.2.3.8.

You must use a trailing minus or the CR/DR formatting character to indicate a negative number in an
asterisk fill or floating dollar sign field.
For fields with trailing minus signs, BASIC prints a minus sign after negative numbers and a space after
positive numbers:
Standard Field

Fields with Trailing Minus Signs

10 PRINT USING "###.##" t-10.54
20 PRINT USING "###.##" tl0.54
30 END

10 PRINT USING "##.##-" t -l0.54
20 PRINT USING "##.##-" tl0.54
30 END

RUNNH

-10.54
10.54

10.5410.54

8-8

Formatting Output with the PRINT USING Statement

February 1984

8.2.3.5 E (Exponential) Format
To print a number in E format, place four carets
space for:

MA
)

at the end of the field. The carets reserve

• The capital letter E
• A plus or minus sign (which indicates a positive or negative exponent)
• A 2-digit exponent
In exponential format, BASIC does not pad the digits to the left of the decimal point. Instead, the most
significant digit shifts to the leftmost place of the format field, and the exponent compensates for this
adjustment:
10
20
30
40

PRINT USING "###.## .......' ... ",5
PR I NT US I NG II ### • ## ... ,.., II II ,1000
PRINT USING ".##············",5

END

RUNNH

500.00E-02
100.00E+Ol
.50E+Ol

If you use fewer than four carets, the number does not print in E format; the carets print as literal
characters. if you use more than four carets, BASIC prints the number in E format and includes the
extra carets as a string literal:
10 PRINT USING "###.## ...... '." t5
20 PRINT USING "###.##·,·,·········",5
30 END
RUNNH
5.00'· ......
500. 00E-02·'

You must reserve a place for a minus sign to the left of the decimal point to display negative numbers
in exponential format. If you do not, BASIC signals a warning error.
You cannot use exponential format with asterisk-fill, floating dollar sign, or trailing minus formats.

8.2.3.6 Leading Zeros
To print leading zeros in a numeric field, start the format field with a zero (0) enclosed in angle
brackets. These characters also reserve one place for a digit. For example:
100
200

FM$ = "<O}####.##"
PR I NT US I NG FM$, 1.23, 12.34 t

123.45, 1234.58, 12345.87

RUNNH
00001.23
00012.34
00123.45
01234.58
12345.87

Formatting Output with the PRINT USING Statement

8-9

When you specify zero-fill, you cannot specify asterisk-fill nor floating dollar sign format for the same
field.
8.2.3.7 Blank-If-Zero Fields

To make BASIC print a blank field for values which round to zero, start the numeric field with a
percent sign (%) enclosed in angle brackets. For example:
100
200

FM$ = < 7.. >##### , ##
PR I NT US I NG FM$ t 1000 tOt .001 t - 5000
II

RUNNH
1000.00
-5000

PRINT USING displays spaces in each reserved position for the second and third items in the list. The
value of the second item is zero, while the value of the third item becomes zero when rounded to fit
the numeric field.
8.2.3.8 Debits and Credits

You can have BASIC use credit and debit notation to differentiate positive and negative numbers. To
do this, you place <CD> (Credit! Debit) at the end of the numeric format string. This causes BASIC to
print CR (Credit Record) after negative numbers and zero, and DR (Debit Record) after positive
numbers. For example:
100
200

FM$ = "$$####.##<CD>"
PRINT USING FM$t -552.35t 200t -5

RUNNH

$552.35CR
$200.00DR
$5.00CR

Note that you cannot use trailing minus sign and Credit/Debit formatting in the same numeric field.

8.3 Printing Strings
The PRINT USING statement lets you format strings by specifying:
• The number of characters
• Left-justified format
• Right-justified format
• Centered format
• Extended field format
Table 8-2 summarizes the format characters and their effects.

8-10

Formatting Output with the PRINT USING Statement

February 1984

Table 8-2: Format Characters for String Fields

Character

Effect on Format

, single quotation mark

Starts the string field and reserves place for one character.

L (upper- or lowercase)

Left-justifies the string and reserves place for one character.

R (upper- or lowercase)

Right-justifies the string and reserves place for one character.

C (upper- or lowercase)

Centers the string in the field and reserves place for one character.

E (upper- or lowercase)

Left-justifies the string; expands the field, as necessary, to print the entire string; reserves
place for one character.

\ two backslashes

Reserves n + 2 character positions, where n is the number of spaces between the two backslashes. PRINT USING left-justifies the string in this field. This formatting character is
included for compatibility with BASIC-PLUS. DIGITAL recommends that you do not use this
type of field for new program development.

! exclamation point

Creates a 1-character field. The exclamation point both starts and ends the field. This formatting character is included for compatibility with BASIC-PLUS. DIGITAL recommends that
you do not use this type of field for new program development. Instead, use a single quotation mark to create a 1-character field.

String format fields start with a single quotation mark (') that reserves a space in the print field,
followed by:
• A contiguous series of upper- or lowercase Ls for left-justified output
• A contiguous series of upper- or lowercase Rs for right-justified output
• A conti~uous series of upper- or lowercase Cs for centered output
• A contiguous series of upper- or lowercase Es for extended field output
BASIC ignores the overflow of strings larger than the string format field except for extended fields. For
extended fields, BASIC extends the field to print the entire string. If a string to be printed is shorter
than the format field, BASIC pads the string field with spaces.
A string field containing only a single quotation mark is a l-character string field. BASIC prints the
first character of the string expression corresponding to a l-character string field and ignores all
following characters:
10 PRINT USING

11/11

tIABCDE"

20 END
RUNNH

8.3.1 Left-Justified Format
BASIC prints strings in a left-justified field starting with the leftmost character. BASIC pads shorter
strings with spaces and truncates longer strings on the right to fit the field.

Formatting Output with the PRINT USING Statement

8-11

A left-justified field contains a single quotation mark followed by a series of Ls:
10
20
30
40

PRINT USING "'LLLLLL" ,"ABCD"
PRINT USING "'LLLL" ,"ABC"
PRINT USING "'LLLLL" ,"12345878"
END

RUNNH
ABCD
ABC
123458

8.3.2 Right-Justified Format
BASIC prints strings in a right-justified field starting with the rightmost character. BASIC pads the left
side of shorter strings with spaces. If a string is longer than the field, BASIC left-justifies and truncates
the right side of the stri ng.
A right-justified field contains a single quote mark (') followed by a series of Rs:

DECLARE STRING CONSTANT RIGHT_JUSTIFY = "'RRRRR"
PRINT USING RIGHT_JUSTIFY,"ABCD"
PRINT USING RIGHT_JUSTIFYtIA"
PRINT USING RIGHT_JUSTIFYtISTUI.JWXYZ"
END

10
20
30
40

RUNNH
ABCD
A

STUIJWX

8.3.3 Centered Fields
BASIC prints strings in a centered field with the center of the string in the center of the fieid. If BASIC
cannot exactly center the string - as is the case for a 2-character string in a 5-character field, for
example - BASIC prints the string one character off center to the left.
A centered field contains a single quotation mark followed by a series of Cs:

DECLARE STRING CONSTANT CENTER = "'CCCC"
PRINT USING CENTER t "A"
PRINT USING CENTER t "AB"
PRINT USING CENTER t "ABC"
PR I NT US I NG CENTER t ABCD
PR I NT US I NG CENTER t ABCDE
END

10
20
30
40
50
80
70

II
II

RUNNH
A

AB
ABC
ABCD
ABCDE
If there are more characters than places in the field, BASIC left-justifies and truncates the string on the
right.

8-12

Formatting Output with the PRINT USING Statement

8.3.4 Extended Fields
An extended field contains a single quotation mark followed by one or more Es. The extended field is
the only field that automatically prints the entire string. In addition:
• If the string is smaller than the format field, BASIC left-justifies the string as in a left-justified field .
• If the string is longer than the format field, BASIC extends the field and prints the entire string.
For example:

10 PRINT USING 'E" t "THE QUICK BROWN"
20 PRINT USING "'EEEEEEE' t "Fo}-{"
30 END
II

RUNNH
THE QUICK BROWN
Fo}-{
This example uses extended, left-justified, right-justified, and centered fields.

PRINT USING
PRINT USING
PRINT USING
PRINT USING
PRINT USING
PRINT USING
PRINT USING
PRINT USING
PRINT USING
PRINT USING
PRINT USING
PRINT USING
PRINT USING
PRINT USING
END

10
20
30
40
50
60
70

80
80
100
110
120
130
140
150

"'LLLLLLLLL" t"THIS TE}-n
"'LLLLLLLLLLLLLL" t"SHOULD PRINT"
"'LLLLLLLLLLLLLL" t'AT LEFT MARGIN'
"'RRRR" till t2t3t4"
'RRRRII t '1 t2 t3'
"'RRRR" till t2"
"'RRRR" t l"
'CCCCCCCCC" t "All
'CCCCCCCCC t ABC
I'CCCCCCCCC t I ABCDE"
"'CCCCCCCCC" tIABCDEFG"
'CCCCCCCCC til ABCDEFGH I
I'LLLLLLLLLLLLLLLLL't"YOU ONLY SEE PART OF THIS"
'E" ,lIyOU CAN SEE ALL OF THE LINE WHEN EXTENDED"
II

RUNNH

TH I S TE}-n
SHOULD PRINT
AT LEFT MARGIN
1 ,2 t3
1 t2 t3
1 t2
1
A

ABC
ABCDE
ABCDEFG
ABCDEFGHI
YOU ONLY SEE PART
YOU CAN SEE ALL OF THE LINE WHEN EXTENDED

8.4 PRINT USING Statement Error Conditions
There are two types of PRINT USING error conditions: fatal and warning. BASIC prints warning
messages in the format (%text) and continues execution. However, warnings mean that the output
might not be in the intended format.

Formatting Output with the PRINT USING Statement

8-13

BASIC signals a fatal error if:
• The format string is not a valid string expression
• There are no valid fields in the format string
• You specify a string for a numeric field
• You specify a number for a string field
• You separate the items to be printed with characters other than commas or semicolons
• A format field contains an invalid combination of characters
• You print a negative number in a floating dollar sign or asterisk-fill field without a trailing minus sign
BASIC issues a warning if a number does not fit in the field. If a number is larger than the field allows,
BASIC prints a percent sign (%) followed by the number in the standard PRINT format.
If a string is larger than any field other than an extended field, BASIC truncates the string and does not
print the excess characters.
If a field contains an invalid combination of characters, BASIC does not recognize the first invalid
character or any character to its right as part of the field. They may form another valid field or be
considered text. If the invalid characters form a new valid field, this, like any field, can cause a fatal
error condition if the item to be printed does not match the field.
Consider the following examples of invalid character combinations in numeric fields.

Explanation:
$$ forms a complete field and **##.## forms a second valid field. The first number (5.41) is
formatted by the first valid field ($$). It prints as 1/$5". The second number (16.30) is formatted
by the second field (**##.##) and prints as "**16.30".
The output is:

10 PRINT USING

"##.# ...... ,." ,5.l13EOS

Explanation:
The field has only three carets instead of four. BASIC prints a percent sign and the number,
followed by the """.
The output is:
'.t • 5113E+1,O'" ......

10 PRINT USING" 'LLEEE" , "1.liAl}<YZ"

Explanation:
You cannot combine two letters in one field. BASIC interprets EEE as a string literal.
The output is:

8-14

Formatting Output with the PRINT USING Statement

Note
Any future formatting characters will be implemented with the special character
enclosed in angle brackets. Therefore, you should not include angle brackets as literals in a format stiing unless they are preceded by an underscore.

Formatting Output with the PRINT USING Statement

8-15

Chapter 9
RrviS Fiies

This chapter explains the BASIC file organizations and record operations that are implemented
through DIGITAL's Record Management Services (RMS-11 on PDP-11 systems and VAX-11 RMS on
VAXIVMS systems). For a thorough understanding of file organization and file and record operations,
see the RMS user's guide for your system.
BASIC also supports system-specific 1/0 such as native-mode files on RSTS IE systems, mailbox 1/0
on VAX IVMS systems, and 110 to hardware devices. See BASIC on VAX I VMS Systems, BASIC on
RSTS I E Systems, or BASIC on RSX-ll M I M-PLUS Systems for details.
RMS stores data in physical records, or blocks. A block is the smallest number of bytes BASIC
transfers in a read or write operation. On disk, a block is 512 bytes. On magnetic tape, it is between
18 and 8192 bytes.
RMS stores one or more data records in each block. A data record may also be divided into smaller
units, called fields. A data record can be smaller than, equal to, or larger than a disk block.
From your program's point of view, a data record is the information contained in a record buffer. A
record buffer is an area in the program's storage that is treated as a unit. You can declare static record
buffers (with MAP statements) or dynamic record buffers (with MOVE statements). You can redefine
static record buffers with the REMAP statement.
Before reading further in this chapter, you should become familiar with MAP, MAP DYNAMIC,
REMAP, and MOVE statements. See Chapter 5 for an explanation of MAP, MAP DYNAMIC, and
REMAP statements. See Section 9.6.2.3 for information about MOVE statements.

9.1 Record Formats
The record format determines how RMS stores a record in the block. You specify record format in the
OPEN statement. You can select either fixed-length or variable-length records.
Fixed-length records are all the same length. RMS stores fixed-length records as they appear in the
record buffer, including any spaces or null characters following the data in the record buffer (this is
called padding). Processing these records involves less overhead than other record formats. However,
this format can use disk storage space less efficiently than variable-length records.

9-1

Variable-length records can have different lengths, but no record can exceed a maximum size you set
for the file. When the record is written to a file, RMS adds a 2-byte binary record length header to
each record. This count gives the length of the record (excluding the header) in bytes. When your
program retrieves a record, this header is not included in the record buffer.
While variable-length records usually make more efficient use of storage space, manipulation of the
record length headers generates processor overhead.
Specifying variable-length format for relative files does not save disk space. RMS always uses a fixedlength cell for each record in the file and fills any remaining space in the cell with null characters.
However, specifying variable-length will prevent the padding from appearing when you access a
record.

9.2 File Organizations
RMS provides sequential, relative, indexed, and block 110 files. If you specify no organization clause
when creating the file, the default is a terminal-format file.

Note
On RSTS/E systems, only files opened with ORGANIZATION SEQUENTIAL,
RELATIVE, or INDEXED are RMS files. Files opened with ORGANIZATION VIRTUAL
or with no ORGANIZATION clause are RSTS/E native-mode files. See BASIC on
RSTS 1E Systems for more information.
• Sequential
A sequential file contains records stored in the order that they were written. Your program specifies
the record format (fixed- or variable-length), and accesses data with GET and PUT statements. You
read a sequential file from beginning to end; therefore sequential files are most useful when you
access the data in the file sequentially each time you use it. Sequential files can reside on both disk
and magnetic tape devices.
• Relative
A relative file contains a series of cells. Each cell can contain only a single record. For fixed-length
records, the length of each cell equals the record length plus one byte. For variable-length records,
the length of the cell equals the maximum record size plus three bytes. Your program specifies:
1) the record format and 2) the divisions or fields within the record. You access data with GETs and
PUTs, either randomly by cell number or sequentially by omitting cell numbers. Relative files reside
on disk devices only.
Relative files are most useful when: 1) randomly accessed and 2) record contents correspond to cell
numbers (for example, when inventory numbers correspond to cell numbers).
• Indexed
Indexed files contain data records sorted in ascending order by primary index key value. An index
key is a record field by which the records are ordered. For example, the primary index key for
personnel records might be the employee number. Indexed files must have a primary index key and
can also contain one or more alternate index keys. Your program specifies the format of data
records and accesses the data with GET and PUT statements. Because records are ordered by key
values, the data can be accessed randomly by specific key value, or sequentially according to
ascending key value. Indexed files reside on disk devices only.

9-2

RMS Files

Indexed files are most useful when: 1) randomly accessed and 2) you may want to access the
records in more than one way. You can specify index keys to access a fiie by one of severai record
fields.
• Biock i/O
Block 110 fi les are random access fi les that store one or more data records in each 51 2-byte disk
block. You specify the location and format of the data by blocking and deblocking records with
MAP, REMAP, and MOVE statements. Block 1/0 files are more efficient than other types of files
because they do not use RMS bufferi ng. All data transfers are between the fi Ie and the program's
record buffer.
You open the file with ORGANIZATION VIRTUAL and access data with GET and PUT statements,
either randomly by block number or sequentially by omitting the block numbers. Each GET or PUT
moves an integral number of 512-byte data blocks.
• Terminal-Format
On all systems except RSTS/E, terminal format files are RMS sequential files of variable-length
records. Each record is less than or equal to the specified record size. You create a terminal-format
file by omitting the ORGANIZATION clause in the OPEN statement. You write records with the
PRINT # and PRINT # USING statements, and read them with INPUT #, INPUT LINE #, and
LlNPUT # statements. See Chapter 2 for more information about simple 1/0 to terminal-format
files. You can also use MAT statements to move data between terminal-format files and arrays. See
Chapter 7. On RSTS/E systems, terminal-format files are RSTS/E native mode stream files. See
BASIC on RSTS I E Systems for more information.
• Vi rtual Arrays
On PDP-11 systems, virtual array files let you use disk files for arrays too big to fit in memory. You
open virtual array files with ORGANIZATION VIRTUAL and dimension an array on the file with the
DIM # statement. You perform operations on virtual arrays just as you do on in-memory arrays.
Virtual arrays can contain integer, floating-point, or string data.
Because VAX IVMS is a virtual memory system, conserving memory is not as important a consideration. Virtual arrays are supported for compatibility with PDP-11 BASIC-PLUS-2.
• Undefined
Undefined files are files with unknown characteristics. You open them FOR INPUT only. Specifying
UNDEFINED causes BASIC to ignore the file attribute checking normally done on files. After you
have opened the file, you use the STATUS keyword to find out what the file attributes are. This
usage should be reserved for special applications only.

9.3 Record Access and Record Context
Record access modes affect the order in which your program retrieves records from a file. They
determine the record context, that is, the Current Record and the Next Record to be processed.
RMS allows three methods of record access:
• Sequential
• Random by key
• Random by RFA (Record File Address)

RMS Files

9-3

Sequential access is valid on files of any organization. Random-by-key access is valid on relative and
indexed files. Random-by-RFA access is valid on any RMS file.
Thus, it is possible to access relative and indexed files sequentially. This means that your program can
open a relative or indexed file and perform a series of GET statements that do not specify a record
number or key value. Each GET statement retrieves the next logical record.
In the case of relative files, the next logical record is that with the next higher record number (or cell
number). In the case of indexed files, the next logical record is that with the next higher value in the
current key of reference.
You can also access relative and indexed files randomly by key. This means that a GET statement
specifies a particular record to be retrieved. For RELATIVE fi les, the key specification is the record (or
cell) number. For indexed files, the key specification is a record (a primary or alternate key) and an
integer or string value.
You can access files of any organization by Record File Address (RFA). This means that you specify
the disk address of a record, and RMS retrieves the record at that address. The RFA requires six bytes
of information: four bytes for the address of a disk block, and two bytes for the offset into the disk
block. See Section 9.6.2.5 for more detail.
Your program can change access modes while reading and writing records. For example, if a relative
file contains both master and detail records for each employee, you might randomly access the
master record for a particular employee, then perform sequential GETs to retrieve the associated
detail records.
After your program opens a file, you can use the following statements to perform 1/0:
• GET
• PUT
• FIND
• DELETE
• UPDATE
• SCRATCH
• FREE
• UNLOCK
• RESTORE
The record context is the state of the Current Record Pointer and Next Record Pointer. When your
program successfully executes one of the listed statements, the record context can change. If an I/O
statement is unsuccessful, the record pointers do not change. Table 9-1 shows how each statement
affects record context.
Note that successfully executing a GET statement mayor may not change the record context. If the
last I/O operation before the GET was a FIND, GET operates on the Current Record. Otherwise, GET
operates on the Next Record. This behavior improves program performance for the following reason:
FIND statements execute faster than GET statements because FIND does not move any data; it merely
locates the specified record and makes it the Current Record. Thus, your program can move through
an indexed file with FIND statements, testing each record's key. When the desired record has been
located, a GET statement actually moves the Current Record from the file into the record buffer.

9-4

RMS Files

Table 9-1: I/O Statements and Record Context

Record Operation

Record
Access
Mode

Lurrem
Record

NeXI
Record

GET (Last operation
not a FIND)

Sequential

New

New Current Record + 1

GET (Last operation
was a FIND)

Sequential

Unchanged

Current Record + 1

GET

Random

New

New Current Record + 1

PUT

Sequential

None

1. Sequential file - end of file
2. Reiative fiie - next record position
3. Indexed file - undefined

PUT

Random

None

Unchanged

FIND

Sequential

New

New Current Record + 1

FIND

Random

New

Unchanged

UPDATE

N/A

None

Unchanged

DELETE

N/A

None

Unchanged

SCRATCH

N/A

None

End of file

UNLOCK

N/A

None

Unchanged

FREE

N/A

None

Unchanged

RESTORE #

N/A

None

First Logical Record

Notes:
1.

Except for SCRATCH, RMS establishes the Current Record before establishing the
identity of the Next Record.

The notation "+ 1" indicates the next sequential record as determined by the file
organization. For indexed files, the current key of reference is part of the determination of the next sequentiai record.

When you execute the RESTORE # statement, the Next Record Pointer points to the
first logical record in the file. For sequential and relative files, this is the first record
in the file. For indexed files, it is the first record in the specified key of reference.

The alternate behavior is as follows: If the last I/O operation before a GET statement was not a FIND,
GET operates on the Next Record. This lets you perform a series of GET statements (for example, in a
loop), with each GET retrieving a new record.
When you first open a file, the Current Record is undefined, and (with one exception) the Next
Record is always the first logical record, namely:
1.

The first record in a sequential file

The record with the lowest cell number for a relative file

The first record in the current key of reference for an index file

The exception to this rule occurs when opening a sequential file with ACCESS APPEND. In this case,
the Next Record is also undefined.

RMS Fi les

9-5

9.4 I /0 and Record Buffers
The 1/0 buffer is an area in your program that is used by RMS to store data for 1/0 operations. You
do not have direct access to the 1/0 buffer because it is controlled entirely by RMS. The 1/0 buffer
holds the minimum amount of data that can be tiansfeiied to or from a device, and its size is always
greater than or equal to that of the record buffer. For more information on the amount of storage
allocated for the 1/0 buffer, see the RMS user's guide for your system.
A record buffer is also a storage area in your program; the difference between the 1/0 buffer and the
program's record buffer is that you have direct access to and control of the record buffer. When your
program reads a record from a file, the record is transferred from the file to the 1/0 buffer and then to
the record buffer. When your program writes a record, data is transferred from the record buffer to the
1/0 buffer and then to the file.
Normally, you need not be concerned with the allocation of the 1/0 buffer; this "double-buffering" is
transparent to your program. However, the 1/0 buffer does increase the size of your program and can
be manipulated to optimize 1/0 performance.
MAP statements let you create static record buffers and associate program variables with areas (fields)
of this buffer. Static means the size of the record buffer does not change during program execution
and that program variables are always associated with the same fields in the buffer.
There are two ways to create dynamic record buffers. After specifying a MAP, you can use
MAP DYNAMIC and REMAP statements to associate a particular program variable with a different area
of the record buffer. However, the total size of a record buffer does not change during program
execution.
If you do not specify a MAP in the OPEN statement, the size of the record buffer is determined by the
OPEN statement RECORDSIZE clause, or the record size associated with the file. If you don't specify
a MAP, you must use MOVE TO and MOVE FROM statements to transfer data back and forth from
the record buffer to program variables. MOVE statements do not transfer data to or from a file.
Note that you can specify both a MAP clause and a RECORDSIZE clause in the OPEN statement. In
this case, the specified RECORDSIZE must be less than or equal to the size of the MAP and overrides
the size specified by the MAP clause.

9.5 Opening Files (OPEN Statement)
The OPEN statement opens a file for processing, specifies the characteristics of the file to RMS, and
verifies the result. Its format is:

OPEN file-spec1

FOR INPUT ]
[ FOR OUTPUT

AS [ FILE ] chnl-exp1 [, open-Clause ]. ..

open-clause:

VIRTUAL
UNDEFINED
[ ORGANIZATION]

INDEXED

STREAM
VARIABLE

SEQUENTIAL
RELATIVE

9-6

RMS Files

[

FIXED

(

NONE
READ

ALLOW

WRITE
( MODIFY'

~
J

APPEND
READ
ACCESS

WRITE
MODIFY
SCRATCH

LIST
RECORDTYPE

FORTRAN
NONE
ANY

RECORDSIZE int-exp1
FILESIZE int-exp2
WINDOWSIZE int-exp3

} (Except on RSTS/E)

TEMPORARY
CONTIGUOUS
MAP map-nam
CONNECT chnl-exp2
BUFFER int-exp4
USEROPEN sUb-nam
DEFAULTNAME file-spec2
EXTENDSIZE int-exp5

} (Except on RSTS/E)

MODE int-exp6

} (BASIC-PLUS-2 only)

CLUSTERSIZE int-exp7

} (BASIC-PLUS-2 on RSTS/E only)

BLOCKSIZE int-exp8

} (Sequential files)

NOREWIND

} (Sequential files)

NOSPAN

} (Sequential files)

SPAN

} (Sequential files)
(continued on next page)

RMS Files

9-7

BUCKETSIZE int-exp9

} (Relative and Indexed files)

PRIMARY [ KEY] key [ DUPLICATES]

} (Indexed files)

ALTERNATE [ KEY] key [ DUPLICATES] [ CHANGES]

} (Indexed files)

UNLOCK EXPLICIT

} (VAX-11 BASIC only)

str-unsubs-vbl
key-clause:

int-unsubs-vbl
decimal-unsubs-vbl
( str-unsubs-vbI1 ,... str-unsubs-vbI8 )

where:
file-spec

Is the file specification. File-spec must be a valid file specification on your system. It
can be a string constant, literal, or variable.

chnl-exp

Is a channel number associated with the file for as long as it is open. The channel
number identifies the file in I/O statements such as GET, PUT, and so on.

Note that BASIC-PLUS-2 on RSTS / E systems also allows a CLUSTERSIZE clause and a STREAM
record format. See BASIC on RSTS / E Systems for more information.
Opening a file FOR INPUT specifies that you want to use an existing file. Opening a file
FOR OUTPUT specifies that you want to create a new file. If you specify neither FOR INPUT nor
FOR OUTPUT, BASIC tries to open an existing file; if no such file exists, BASIC creates a new file.
The following sections show examples of using the OPEN statement on sequential, relative, indexed,
and block I/O (virtual) files. See the BASIC Reference Manual for complete explanations of each of
the OPEN clauses. To perform I/O to devices and I/O optimization, see the user's guide for your
system.

9.5.1 Opening Sequential Files
The following program opens a sequential file and associates it with a static record buffer. The
ACCESS APPEND clause sets the record pointers to the end of the file:
20

MAP (MAP 1) STRING NA.ME = 327.. ,
LONG DEPT.NUM,
DOUBLE BUDGET
OPEN "CASE.DAT" FOR INPUT AS FILE :(:1:57..
,ORGANIZATION SEQUENTIAL F I }{ED
,ACCESS APPEND, ALLOW NONE
,MAP MAPl

&:
&:

&
&:
&:

The MAP statement in line 20 defines the record buffer's total size and the data types of its variables.
The MAP clause in line 30 references this MAP and associates it with the file on channel number 5.
The data record contains one 32-byte string, one LONG integer, and one double-precision floatingpoint number. The record size is the total of these fields, or 44 bytes. BASIC statically allocates a
record buffer 44 bytes long; all record operations use this buffer for I/O to the file.

9-8

RMS Files

The following program opens a sequential file for reading only (ACCESS READ), with a dynamic
record buffer:
10

OPEN "CASE.DAT" AS FILE #l7../n
r-.
rtORGANIZATION SEQUENTIAL ','HI" .LHUL..I:.
tACCESS READ
tRECORDS I ZE 1007..
11/\ 1""". T

Because the OPEN statement contains no MAP clause, BASIC allocates an area for the record buffer
out qf the program's free space. This dynamic record buffer is 100 bytes long. Your program must use
MOVE TO and MOVE FROM statements to move data between the record buffer and a Iist of
variables.

9.5.2 Opening Relative Files
This program opens a relative file and uses static buffering:
110

120

MAP (TEST) LONG PART_NUMBERt
&
STR I NG I Nt.I_NAME = 1G t
~:
DOUBLE UNIT_PRICE
OPEN IRELATIJ.FIL" FOR OUTPUT AS FILE #17..
~:
tORGANIZATION RELATIVE FIXEDt ACCESS MODIFYt &
tALLOW READt MAP TEST

The MAP statement in line 110 defines the record buffer's total size and the data types of its variables.
When the program is compiled, BASIC allocates space in the record buffer for one integer, one
16-byte string (the default if you do not specify a length), and one floating-point number: The record
size is the total of these fields or 24 bytes. All record operations use this buffer for I/O to the file.
This program opens a relative file with a dynamic record buffer:
110

OPEN "RELATV.FIL" FOR OUTPUT AS FILE #17.. ~:
tORGANIZATION RELATIVE FIXEDt ACCESS MODIFYt &
tALLOW READt RECORDSIZE 220%

Your program must use MOVE TO and MOVE FROM statements to move data between the record
buffer and a list of variables.

9.5.3 Opening Indexed Files
Indexed files let you store records in a predefined sorted order. The keys (record fields) you specify
determine the order in which the records are logically stored. Keys must be variables declared in a
MAP statement; they can be: 1) strings, 2) WORD integers, 3) LONG integers, or 4) packed decimal
numbers (VAX-l1 BASIC only). String keys can also be segmented, that is, the key can be composed
of up to eight string variables in the MAP.
When you create an indexed file, you must specify a primary key, and you can specify up to 254
additional alternate keys. RMS creates one index for each key you specify. These indexes are part of
the file and contain pointers to the records. Each key you specify corresponds to a sorted list of record
pointers. Thus, it does not matter where the physical records are located; multiple keys mean only
that there are multiple lists of record pointers, each sorted in a different order.

RMS Fi les

9-9

The OPEN statement for indexed files must have a MAP clause (which references a MAP statement)
and, if you are creating the file, a PRIMARY KEY clause. The MAP statement defines the record buffer
and associates program variables with parts of that buffer. The MAP statement should lexically
precede the OPEN statement that references it.
The PRIt-AARY KEY clause names one of the mapped variables as the field by 'vvhich the file is sorted.
In addition, the OPEN statement can contain ALTERNATE KEY clauses that correspond to alternate
access paths. When creating an indexed file, you must specify a primary key. For example:

MAP (REC) STRING RECNOt
LONG INV_NUMt
STRING PROJECT_NUM = Bkt
STRING JOB_SUPERVISOR = 32k
OPEN "INDEX.DAT" FOR OUTPUT AS FILE #Bk
tORGANIZATION INDEXED FIXED
tPRIMARY KEY RECNO
jALTERNATE KEY INV_NUM
tALTERNATE KEY PROJECT_NUM
tALTERNATE KEY JOB_SUPERVISOR
tMAP REC

&
&
&

&
&
&
&
&
&

This OPEN statement specifies four index keys. When this file is created, RMS includes four record
pointer lists, each one ordered by the values of its associated key variable.
You can also create an index key containing more than one string variable by separating the variables
with commas and enclosing them in parentheses. All the string variables must be part of the associated MAP. For example:

100
200

MAP (SEGKEY) STRING LAST_NAME = 15, FIRST_NAME = 1St MI
OPEN "NAMES.IND" FOR OUTPUT AS FILE #1 t
&
ORGANIZATION INDEXED,
&
PR I MARY KEY (LAST _NAME t FIRST _NAME t MI ) t &:
MAP SEGKEY

In this example, the primary key is made up of three string variables.
By default, BASIC assumes that key values are unique for each record and that no changes can be
made to key values. To allow duplicate key values or changes to key values, you must specify those
attributes in the OPEN statement. For example.

tPRIMARY KEY RECNO DUPLICATES
tALTERNATE KEY JOB_SUPERVISOR DUPLICATES CHANGES
You cannot specify CHANGES for the primary key. If you do not allow duplicates on a particular key
and attempt to insert a record whose key values match one already in the file, BASIC signals "Duplicate key detected" (ERR = 134). Also, if you do not allow changes on an alternate key and that key
value would be changed by the execution of an UPDATE statement, BASIC signals "Key not changeable" (ERR = 130).
Although you cannot create an indexed file without at least one key clause, you can open an existing
indexed file without specifying a key clause.

9-10

RMS Files

9.5.4 Opening Block I/O Files
Block 1/0 files contain a series of 512-byte blocks. You open the file with a record size of 512 or
multiple of 512. For any record size that is not a multiple of 512, BASIC rounds the value to the next
higher multiple. For example:
50
100

MAP (VIRT) STRING V = 512%
OPEN "VIRT.DAT" FOR OUTPUT AS FILE #l%t
I.J I RTUAL t
MAP InRT

This OPEN statement creates a file with a fixed-length, 512-byte record size.

9.5.5 Opening Terminal-Format Files
On all systems except RSTS/E, terminal-format files are RMS sequential files with variable-length
records. On RSTS/E systems, terminal-format files are RSTS/E native-mode stream files. See BASIC on
RSTSIE Systems for more information about stream files. You create a terminal-format file by not
specifying an ORGANIZATION clause in the OPEN statement. For example:
100

OPEN "TERM.DAT" FOR OUTPUT AS FILE
RECORDSIZE BOlt
ALLOW READ

l%t

This OPEN statement creates an RMS sequential file with variable-length records and a record size of
80. The ALLOW clause specifies that other users can read the file.

9.5.6 Opening Undefined Files
If you do not know what a file's organization is, you can find out by opening the file for input with
ORGANIZATiON UNDEFiNED and RECORDTYPE ANY. Your program can then use the FSP$ function to determine the characteristics of that file. Your program must execute FSP$ immediately after
the OPEN FOR INPUT statement. The syntax of the FSP$ function is:

str-vbl = FSP$(channel-number)
where:
str-vbl

Is a string variable.

For example:
10
20
30
40

MAP (A) A$ = 32
MAP (A) WORD ORG_RATt MRSt LONG ALQt
WORD BKS_BLSt NUM_KEYSt LONG MRN
OPEN "FIL.DAT" FOR INPUT AS FILE #l'X.t
ORGANIZATION UNDEFINEDt
RECORDTYPE ANYt ACCESS READ
A$ = FSP$(ll)

February 1984

&
&

RMS Files

9-11

In this program, FSP$ generates the following values:
• ORG_RAT, which returns file characteristics:
-

High Byte is the RMS organization (ORG) field.

Lo\v byte is the Rtv1S record attributes (RAT) field.

• MRS returns the RMS maximum record size (MRS) field.
• ALQ returns the RMS allocation quantity (ALQ) field.
• BKS_BLS returns the RMS bucket size (BKS) field for disk files or the RMS block size (BLS) field for
magnetic tape files.
• NUM_KEYS returns the number of keys.
• MRN returns the RMS maximum record number (MRN) if the file is relative.
See your RMS user's guide for more information.

Note
On PDP-11 systems, bytes 9 and 10 return the RMS bucket size (BKS) or RMS block
size (BLS) for magnetic tape. On VAX IVMS systems, FSP$ returns zeros in bytes 9
through 12. Note that you can also find this information with a user-supplied program
specified in the USEROPEN clause. See Section 9.12.11 for more information about
USEROPEN.

9.6 Record Operations
The following sections describe the BASIC 110 statements and the operations they perform. BASIC
110 statements are:

PUT

Moves data from the record buffer to a file.

GET

Moves data from the fi Ie to the record buffer.

FIND

Makes a specified record the Current Record for a GET, UPDATE, or DELETE
operation.

DELETE

Removes a record from a fi Ie.

UPDATE

Replaces the Current Record in a file with the data in the record buffer.

SCRATCH

Truncates a sequential file. Deletes all records from the Current Record to the end of
the file, inclusive.

LOCK

Prevents other users from accessing a specified record or bucket.

UNLOCK

Unlocks a specified record or bucket locked by a FIND, GET, or LOCK statement.

FREE

(VAX-11 BASIC only) Unlocks all records and buckets for a specified channel.

RESTORE #

Resets the Next Record Pointer to the first logical record. For relative and sequential
files the first logical record is the first record in the file. For indexed files, the first
logical record is the first record in the specified key of reference.

9-12

RMS Files

February 1984

9.6.1 Locating Records (FIND Statement)
The FIND statement locates a specified record and makes it the Current Record. Using FIND to locate
records has the following advantages:
• FIND does not transfer any data; therefore, it executes faster than a GET statement.
• If the RMS index lists are in memory, a FIND on an indexed file does not initiate any disk
operations.
FIND sets the Current Record Pointer to the record just found, thus making it the target for a GET,
PUT, UPDATE, or DELETE statement.
For sequential access! the FIND statement format is:
FIND #chnl-exp

where:
chnl-exp

Is a channel associated with an open file.

Sequential access is valid on RMS sequential, relative, indexed and block I/O files. A successful
sequential access FIND updates both the Current Record and Next Record pointers.
A sequential FIND operates in the following ways:
• For sequential files, it locates the Next Record in the file, makes this the Current Record, and
changes the Next Record to the Current Record plus one.
• For relative files, it locates the record with the next higher record number (or cell number), makes
this the Current Record, and changes the Next Record to the Current Record plus one.
• For indexed files, it locates the next logical record in the current key of reference, makes this the
Current Record, and changes the Next Record to the Current Record plus one.
• For block ! /0 files, it locates the next disk block (for files with RECORDS!ZE 512) or the next record
(for files with RECORDSIZE greater than 512), makes this the Current Record, and changes the Next
Record to the Current Record pius one.
For example:
100
200

OPEN "SEQ.DAT" FOR INPUT AS FILE #l'X, t
&:
ORGANIZATION SEQUENTIAL VARIABLEt &
RECORDSIZE 132
FIND #1% FOR I% = 1% TO 20%

Line 200 performs 20 FIND operations. The twentieth record in the file is now the Current Record.
For relative and block I/O files, you can find a particular record by specifying a RECORD clause. This
is called a random access FIND. A random access FIND updates the Current Record pointer but
leaves the Next Record pointer unchanged. The FIND format for random access on relative and block
I/O files is:
FIND #chnl-exp, RECORD int-exp

RMS Files

9-13

where:
chnl~exp

Is a channel associated with an open relative or block I/O file.

int-exp

Is an integer expression specifying the record you want to retrieve.

For example:

100

OPEN "BLOCK.DAT" FOR INPUT AS FILE
RECORDS I ZE 512'X.
FIND #l%t RECORD 20%

200

#l'X.t

VIRTUALt

This example makes the twentieth record in the file the Current Record.
For indexed files, you can locate a record by specifying a key of reference, a relational test, and a key
value. The FIND format for random access on indexed files is:

FIND #chnl-exp ,KEY#int-exp1

l, ~EO~' }

{

~~;~:~~2}
dec-exp

(VAX-11 BASIC only)

where:
chnl-exp

Is a channel associated with an open indexed file.

int-exp1

Is the key of reference. The primary key is key number zero, the first alternate key is
key number one, the second alternate key is key number two, and so on.

EO
GE

Are relational tests that specify "equal to," "greater than or equal to," and "greater
than," respectively.

GT
str-exp
int-exp2
dec-exp

Specify values to be compared with the key value of a record. This value can be a
string expression, a WORD or LONG integer expression, and, in VAX-ll BASIC, a
packed decimal expression.

For example:

100
200

£100
500

MAP (EMP) STRING EMP_NAMt LONG EMP_NUMBERt SSN
OPEN "EMP.DAT" AS FILE #1'X. t INDE}{ED t
&:
ACCESS READt
&
MAP EMPt
&
PRIMARY KEY EMP_NAM
FIND #5%t KEY #0% GE "JONES"
FIND #5'X. t KEY #0% GT "ABRAMSON"

Assume the file contains these names:

• ABELL
• ABRAMSON
• ADAMS
• HOTCHKISS
• JONES

9-14

RMS Files

• KNIGHT
• SMITH
Lines 400 and 500 find the records JONES and ADAMS. Line 400 identifies the key as the primary key
(key number 0) and searches for the first record whose primary key is equal to or greater than JONES.
JONES is the first record to meet this condition. Line 500 also uses the primary key and searches for a
record whose key value is greater than ABRAMSON. ADAMS is the first record to meet this
condition.
The string expression can contain fewer characters than the key of the record you hope to find. The
statements on lines 400 or 500 could have specified values of fewer characters, such as "jO" in line
400 or "ABR" in line 500. Note, however, that if line 500 specified "AB", ABELL is the target record,
because it is the first to meet the condition.
If you want to locate a record whose string key field exactly matches the string expression you
provide, you must pad the string expression with spaces to the exact length of the key of reference.
For example:

100
200

FIND #5%1 KEY #0% EQ "TOM
FIND #5%t KEY #0% EQ "TOM"

Line 100 locates a record whose primary key field contains "TOM
the first record whose primary key field begins with "TOM".

". In contrast, line 200 locates

9.6.2 Reading Records (GET Statement)
The GET statement moves a record from a file to a record buffer and makes the data available for
processing. GET statements are valid on RMS sequential, relative, indexed, and block I/O files. You
should not use GET statements on terminal-format files, virtual array files, or files opened with
ORGANIZATION UNDEFINED. For sequential access, the GET statement format is:
GET #chnl-exp

where:
chnl-exp

Is the channel number of an open file.

Sequential access is valid on RMS sequential, relative, indexed, and block I/O files. GET retrieves the
Next Record unless the last I/O statement was a FIND. In this case, GET retrieves the Current Record.

9.6.2.1 Reading Records from Sequential Files
For sequential files, a sequential GET retrieves the next record in the file. For relative and block I/O
files, a sequential GET retrieves the record with the next higher cell number. For indexed files, a
sequential GET retrieves the record with the next higher value in the current key of reference. For
example:

10
20
30
40
50
GO

ON ERROR GOTO 19000
MAP (OAT) STRING PROD.NAM = 30%t LONG CALL.NUMt STRING REQ.CODE
OPEN "RST.DAT" AS FILE #11.
&
tORGANIZATION SEQUENTIALt MAP OAT
GET #11.
PRINT "THE PRODUCT NAME IS" t PROD.NAM
PRINT "THE CALL NUMBER IS" t CALL.NUM
PR I NT "THE REQU I SIT I ON CODE IS" t REQ. CODE
(continued on next page)
RMS Files

9-15

70
18000
18010
18020
32767

GO TO 30
IF (ERR = 11%) AND (ERL = 30%)
THEN RESUME 18010
ELSE ON ERROR GOTO 0
PRINT "END OF FILE"
CLOSE # 1'X.
END

&
&

This example opens a sequential file and performs sequential GETs until it reaches end-of-file. At this
point, the ON ERROR statement transfers control to line 19000.

9.6.2.2 Reading Records from Relative Files
Relative files allow you to retrieve records both sequentially and randomly. This example opens a
relative file and performs sequential GETs until it reaches end-of-file:

ON ERROR GOTO 300
MAP (IMP) STRING STATE, MAIN.OFF, LONG NUM.SPL, SINGLE SCODE
OPEN "REC.DAT" FOR INPUT AS FILE #l'Xot
&:
ORGANIZATION RELATIVE,
&
MAP IMP, ACCESS READ
WHILE 1'X. = 1%
GET #1 'X.
PRINT "REPORT FOR", STATE
PRINT "THE OFFICE FOR"; STATE; "IS", MAIN.OFF
PRINT MAIN.OFF; "HAS", NUM.SPL; "EMPLOYEES"
PRINT "THE SALES AREA CODE IS", SCODE
NE}{T
IF (ERR = 11%) AND (ERL = 50%)
&
THEN RESUME 400 ELSE ON ERROR GOTO 0
PRINT "END OF FILE"
CLOSE # 1'X.
END

10
20
30
40
50
GO
70
80
80
100
300
400
500
GOO

You perform random GETs by specifying a record number. The format for a random access GET is:
GET #chnl-exp, RECORD num-exp

where:
chnl-exp

Specifies an open relative file.

num-exp

Specifies the record to be retrieved.

For example:

10
20
30
40
50
GO
70

MA P (BEC) LONG VEH_NUM,
&
STRING SERIAL_NUM = 2Z%t
&
OWNER = 3 o'X.
OPEN "VEH. ION" FOR INPUT AS FILE #2'X..
&
ORGANIZATION RELATIVE FIXED.
&
MAP BEC, ACCESS READ
INPUT "WHICH RECORD DO YOU WANT";A%
GET #2%, RECORD A%
PRINT "THE VEHICLE NUMBER IS", VEH_NUM
PRINT "THE SERIAL NUMBER IS", SERIAL_NUM
PR I NT "THE OWNER OF VEH I CLE"; t.IEH_NUM; "I S" tOWNER
(continued on next page)

9-16

RMS Files

February 1984

80
80
100
110

200
32767

I NPUT NE){T RECORD A%
IF A% <> 0% THEN GOTO 40
CLOSE #2%
GOTO 32787
PRINT "Record Loc.'ed -- retr}'in~"
SLEEP 27..
RESUME 40
END
II

;

Random GETs set the value of the Current Record pointer to the record just read. The Next Record
pointer is set to the Current Record plus one. Consider this program:
1000
1010

GET #2%t RECORD 10%
GET #27..

Line 1000 retrieves record 10, and line 1010 retrieves record 11.

Note
Record number zero and record number 1 both refer to the first record in a relative or
block I/O file.
9.6.2.3 Reading Records from Block 110 Files

Block I/O files allow you to retrieve records both sequentially and randomly. Because a GET statement on a block I/O file always transfers an integral number of 512-byte disk blocks, your program
must perform record blocki ng and deblocki ng.
Because each GET on block I/O files retrieves a record starting on a block boundary, you can reduce
disk accessing by filling disk blocks completely. This also makes more records available for processing at one time.
For example, when using 128-byte records, you can store four records in each disk block. One disk
access makes four records available for processing because RMS always moves at least one disk block
during every disk access. In this case, the first GET causes RMS to move one 512-byte disk block into
the I/O buffer. You can then access the first four 128-byte records, using the MOVE statement and
FILL to deblock each record. In contrast, a file with a separate block for each record requires four
times as much disk activity.
Through RMS, BASIC performs all blocking and deblocking on sequential, relative, and indexed files.
However, on RMS block I/O files, your program must perform all blocking and deblocking. You can
do this in one of three ways:
• With MAP statements
• With MAP, MAP DYNAMIC, and REMAP statements (dynamic mapping)
• With MOVE statements
If each logical record in the block I/O file is 512 bytes or a multiple of 512 bytes, you can use MAP
statements to define the record fields. However, if the logical records are not exactly equal to a block
or some integral number of blocks, you must use either dynamic mapping or MOVE statements to
deblock the record.

February 1984

RMS Files

9-17

See Chapter 5 for more information on dynamic mapping.
The MOVE statement defines data fields and moves them to and from the dynamic record buffer. The
format of the MOVE statement is:

fl TFOROM 1l .. . chm-exp
.
. .• "J

"-'v'-t:
Mu

l~J

,VOl l,VOI ...

where:
FROM

Moves the data from the record buffer associated with the channel number and
places it in the variables in the list.

Moves the data from the variables in the list and places it in the record buffer associated with the channel number.

chnl-exp

Is the channel number associated with the opened file.

vbl [,vbl]

Is a list of the variables you move.

For example:
50

MOVE FROM #9%t A$t COSTt NA.ME$, IO.NUM%

This statement moves a record with four data fields from the record buffer to the variables in the list.
This includes: a string field with a default length of 16 characters (A$), a floating-point number field
(COST), a second 16-character string field (NA.ME$), and an integer field (lD.NUM%).
You can input values to the variable list in your program. For example:
20
30

INPUT "NAME"; A$
INPUT "COST PER UNIT"; COST

Valid variables in the MOVE list are:
• Scalar variables
• Arrays
• Array elements
• FILL items
You can also specify string length in the variable list. For example:
NA. ME$

= 307..

Because BASIC dynamically assigns space for string variables, the default string length during a
MOVE TO is the length of the string; the default for MOVE FROM is 16 characters.
An entire array specified in a MOVE statement must include the array name, followed by an open
parenthesis, followed by (n minus one) commas, where n is the number of dimensions in the array,
followed by a close parenthesis. For example:
60

9-18

MOVE TO #5%, A$ ( ) t C ( t ) , 07.. ( f t)

RMS Files

This statement moves three arrays from the program to the record buffer. A$() specifies a onedimensional string array, C(,) specifies a two-dimensional floating-point array, and D%(,,) specifies a
three-dimensional integer array.

Note
The MOVE statement moves the contents of row zero and column zero.
You specify a single array element by naming the array and the subscripts of that element, for
example, A$(25) or B(3,2).
Successive MOVE statements to or from the buffer start at the beginning of the record buffer. If a
MOVE TO only partially fills the buffer, the rest of the buffer is unchanged.
Thus you use the GET statement to read a record from the file. You then move the data from the buffer
to variables in the list and reference the variables in your program.
A MOVE TO moves data from the variables into the I/O buffer. A PUT or UPDATE statement then
moves the data from the buffer to the file.
For example:

5
10

DIM B%(3,3)
OPEN IIMOI.J.DATII AS FILE # 1'X. &:
,RELATIVE VARIABLE &
,ACCESS MODIFY, ALLOW NONE &
,RECORDSIZE 100%
GET # 17"
Q = Q + 1

MOI.JE FROM #1%, A, B%(,), C$

10%

A = A + Q
B%(3,3) = 128'X.
C$ = IINEW RECORD II

MOt.JE TO #1%, A, B%( t>, C$
UPDATE #1%
CLOSE #1%
END

10%

This program opens file MOV. DAT, reads the first record into the buffer, modifies part of the buffer,
and moves the data from the buffer into the variables specified in the MOVE FROM statement. The
string length of C$ is set to 10 characters.
The MOVE TO statement moves the data from the named variables into the buffer. The UPDATE
statement writes the record back into file 1 (MOV. DAT).
Note that when accessing block I/O files, you can specify a RECORD clause for the GET statement.
For example:

10
100
200
300
350

ON ERROR GO TO 19000
DECLARE WORD RECORD_NUMBER
MAP (VIRT) STRING FILL = 512
MAP DYNAMIC (VIRT) STRING FIRST_NAME,
&
LAST_NAME,
&
COMPANY
OPEN 1I1..JIRT.DATII FOR INPUT AS FILE #5, InRTUAL, MAP I.JIRT
RECORD_NUMBER = 1%
(continued on next page)

February 1984

RMS Files

9-19

WHILE 1% = 1%
GET #5t RECORD RECORD_NUMBER

aoo

FOR 1% = 0% TO 3%

REMAP (VIRT) STRING FILL
( I 'X. * 1281..
FIRST_NAME = 20t
LAST_NAME = aat
COMPANY = 8a
PRINT FIRST_NAMEt LAST_NAMEt COMPANY
NEi-{T I 'X.
RECORD_NUMBER = RECORD_NUMBER + 1%

) t

NE}<T
I F ERR = 11 'X.
THEN
PRINT "Finished"
RESUME 32787
ELSE ON ERROR GOTO 0
END IF
END

19000

32787

This program opens a block I/O file with each physical record containing 512 bytes. However, each
logical record is 128 bytes long, and consists of a 20-character first name field, a 44-character last
name field, and a 64-character company name field. The RECORD_NUMBER variable is initially set
to 1, and the GET statement uses this variable to retrieve the specified record. This variable is
incremented within the WHILE loop so that the next 512-byte record is retrieved in each WHILE loop
iteration.
The FOR/NEXT loop within the WHILE loop deblocks the 512-byte physical records into 128-byte
logical records. At each iteration of the FOR / NEXT loop, the REMAP statement uses the loop variable
to mask off 128-byte sections of the record. Thus, in the first FOR / NEXT loop iteration, 1% equals
zero; therefore, the number of bytes specified by the FILL expression also equals zero. Because of
this, FIRST_NAME points to the first 20 bytes of the record buffer, LAST_NAME points to the next 44
bytes, and so on.
In the second FOR/NEXT loop iteration, 1% equals one; therefore, the number of bytes specified by
the fill expression equals 128. In this iteration, FIRST_NAME points to bytes 129 through 148,
LAST_NAME points to bytes 149 through 192, and COMPANY points to bytes 193 to 256. Thus,
each FOR/NEXT loop iteration causes the remapped variables to point to the next logical record. The
PRINT statement displays this information at each iteration.
9.6.2.4 Reading Records from Indexed Files
On indexed files you can access records randomly by specifying a key of reference and a key value.
The format for a random access GET is:
GET #chnl-exp ,KEY #int-exp1

1l ~EO~ lf 1~~;~:~~2l
l dec-exp f (VAX-11 BASIC only)

where:
chnl-exp

Is a channel associated with an open indexed file.

int-exp1

Is the key of reference. The primary key is key number 0, the first alternate key is key
number 1, the second alternate key is key number 2, and so on.

Are relational tests that specify "equal to," "greater than or equal to," and "greater
than," respectively.

GE
GT

9-20

RMS Files

February 1984

str-exp
int-exp2
dec-exp

Specify values to be compared with the key value of a record. Dec-exp is a packed
decimai number. Packed decimai key vaiues are vaiid oniy in VAX-II BASiC.

You can read records randomly by specifying the target value as a constant:

580

GET #41. t KEY #(l% GT "COLUMBUS"

You can also specify the target value as a variable to read a number of different records:

10
20
30

50
80
70
80
90
100
110

MAP (BEC) STRING OWNER = 30%t
&
LONG VEH_NUMt
&
STRING SERIAL_NUM = 22%
OPEN "I.JEH. I ON FOR I NPUT AS FILE #2% t
&:
ORGANIZATION INOEXEOt
&
MAP BECt ACCESS READ
INPUT "WHICH RECORD DO YOU WANT";A$
GET #2%t KEY #0% EQ A$
PR I NT "THE I)EH I CLE NUMBER IS" t I.JEH_NUM
PRINT "THE SERIAL NUMBER IS" t SERIAL_NUM
PR I NT THE OWNER OF t.JEH I CLE"; VEH_NUM; "I S" tOWNER
INPUT "NEXT RECORO";A$
IF A$ <> ''~ONE'' THEN GOTO ao
CLOSE #2%
END
II

Note that the OPEN statement in this example does not need a KEY clause because the file already
exists.
A random GET sets the Current Record pointer to the record just read. The Next Record pointer is set
to the record logically following the Current Record in the key of reference.
Indexed files also let you access records sequentially by key value. For example:

10
20

MAP (BEC) STRING OWNER = 30%t LONG VEH_NUMt &
STRING SERIAL_NUM = 22%
OPEN "I)EH. ION" FOR INPUT AS FILE #21. t
&:
ORGANIZATION INDEXEDt MAP BEC; ACCESS DC'An
FOR 1% = 1% TO 25%
GET #2%
PRINT "I.,Jehicle NUITlber = ";I.JEH_NUM
PR I NT "0",11"1 e r is: "; OWNER
PRINT
NE}{T I Z
1"\ L.nLJ

This example opens an indexed file and displays the first 25 records in ascending primary key value
order.
9.6.2.5 Accessing Records by Record File Address

A Record File Address consists of a block number within a file and an offset into that block. This
information requires six bytes of storage. The Record File Address uniquely specifies a record in a file,
and accessing records by Record File Address is more efficient and faster than other forms of random
record access.
Because a Record File Address requires six bytes of storage, BASIC uses a special data-type keyword
to denote variables that contain Record File Address information. The data-type keyword is RFA. Note
that variables of data-type RFA can be used on Iy with the I/O statements and functions that use

RMS Files

9-21

Record File Address information. You cannot print these variables or use them in any arithmetic
operation, except in comparisons to other RFA variables using the equal to (=) or not equal to
relational operators. Also, you cannot create named constants of the RFA data type.

«»

You can assign values from one RFA variable to another, and you can use RFA variables as
parameters.
Accessing a record by Record File Address requires three steps:
• Explicitly declaring the variable of data-type RFA to hold the Record File Address
• Assigning the Record File Address to the variable with the GETRFA function
• Specifying the variable in the RFA clause of a GET or FIND statement
The GETRFA function returns the RFA of the last record accessed on a channel. Its format is:
rfa-vbl = GETRFA(chnl-exp)
where:
rfa-vbl

Is a variable of the RFA data type.

chnl-exp

Is the channel number of an open file. Note that you cannot include a pound sign in
the channel expression.
Note

You must access a record in the file with a GET, FIND, or PUT statement before using
the GETRFA function. Otherwise, GETRFA returns a zero, which is an invalid RFA.
You can use the GETRFA function only after performing a GET, FIND, or PUT. For example:
100

DECLARE RFA R_ARRAY(99)
DECLARE LONG I
MAP (XYZ) STRING A = 80
OPEN "TEST. OAT" FOR OUTPUT AS FILE #1 t
SEQUENT I AL t
~:
MAP }{YZ
FOR I = 0 TO 99

200
300
400

!•
!•
!•

PUT #1
R_ARRAY(I)
NEXT I

= GETRFA(l)

This program fragment declares an array of type RFA containing 100 elements. After each PUT, the
RFA of that record is assigned to an element of the array. Once the Record File Address information is
assigned to a program variable or array element, you can use the RFA clause on a GET or FIND
statement to retrieve the record. The format for a GET or FIND with an RFA clause is:

GET
{ FINOj

#chnl-exp, RFA rfa-exp

where:
chnl-exp

Is the channel number of an open file.

rfa-exp

Is a variable or array element of type RFA.

9-22

RMS Files

February 1984

You can use the RFA clause on GET statements for any file organization. However, the file must
reside on disk. To continue the previous example:

100
200
300
400

DECLARE RFA R_ARRAY(99)
DECLARE LONG I
MAP (XYZ) STRING A = 80
OPEN IITEST.DAT II FOR OUTPUT AS FILE #1 t SEQUENTIAL t MAP }{YZ
FOR I = 0 TO 99
!•
!•
!•

1000

PUT #1
R_ARRAY(I)
GETRFA(l)
NEXT I
WHILE Ii.. = Ii..
PRINT "Which record IAlould YOU lit~e to see";
INPUT lI(t}'pe a carriage return to exit)II;REC_NUMi..
GOTO 327GG IF REC_NUM% = 0
GET #1 t RFA R~ARRAY( REC_NUM% - 1)
PRINT A

This program randomly retrieves the records in a sequential file by using the RFAs stored in the array.

9.6.3 Writing Records (PUT Statement)
The PUT statement moves data from the record buffer to a file. PUT statements are valid on RMS
sequential, relative, indexed and block I/O files. You cannot use PUT statements on terminal-format
files, virtual array files, or files opened with ORGANIZATION UNDEFINED. For sequential access,
the PUT statement format is:
PUT #chnl-exp

where:
chnl-exp

Is the channel number of an open file.

Sequential access is valid on RMS sequential, relative, indexed, and block I/O files. PUT transfers the
data in the record buffer to a record in the file.
For relative and block I/O files, a sequential PUT creates a record with the next higher cell number.
When you PUT to an indexed file, RMS always stores the record in key value order and updates all
index keys. This means that you do not specify sequential or random PUTs.
You can specify a RECORD clause on PUTs to relative and block I/O files. However:
• RMS allocates disk space for n records, where n is the highest cell number specified in a RECORD
clause. Thus, if you OPEN a relative file and PUT record number 100, RMS allocates enough disk
space for 100 records.
• If you PUT a record that already exists, BASIC signals "Record already exists" (ERR = 153).

RMS Files

9-23

9.6.3.1 Writing Records to Sequential Files

For sequential files, a sequential PUT adds a record at the end of the file. This example opens a
sequential file with ACCESS APPEND:
1000
1010
1020
1030
1040

1050
lOGO
1070

MAP (BUFF) STRING COOE = 4%t EXP.DATEt TYPE.DESIG
OPEN "INt.J.DAT" FOR INPUT AS FILE #2%t
3:
ORGANIZATION SEQUENTIALt ACCESS APPEND
FOR 1% = 1% TO 5GO%
INPUT "WHAT IS THE SPECIFICATION CODE"; CODE
INPUT "WHAT IS THE E;-{PIRATION DATE"; EXP.DATE
INPUT "WHAT IS THE DESIGNATOR"; TYPE.DESIG
PUT #27..
NEXT 1%

321..

If you are not at the end of the file when attempting a PUT to a sequential file, BASIC signals "Not at
end of file" (ERR = 149). After a PUT operation, there is no Current Record. The Next Record pointer
is set to the end-of-file.
When processing variable-length records, you can use the COUNT clause to specify the number of
bytes written. For example:
110

PUT #3%t COUNT GO%

This statement writes a 60-byte record to the file opened on channel 3. Without the COUNT clause,
BASIC writes a record equal to the MAP or RECORDSIZE clause. If you have not completely filled the
record buffer before executing a PUT, BASIC pads the record with nulls. If the specified COUNT is
less than the buffer size, the record is truncated.
9.6.3.2 Writing Records to Relative Files

For relative files, PUT writes records sequentially or randomly. For sequential PUTs, type PUT with
the file's channel number:
80

PUT #10%

RMS writes the new record in the location specified by the Next Record pointer. When setting the
Next Record pointer, RMS skips over occupied cells and points to the first free cell.
A sequential PUT destroys the Current Record pointer. The Next Record pointer is set to the Next
Record plus one. A random PUT destroys the Current Record pointer and leaves the Next Record
pointer unchanged. For example
310
320

PUT #1%
PUT #l%t RECORD 20%

The PUT in line 320 does not change the Next Record pointer set in line 310.
When processing variable-length records, you must use the COUNT clause to specify the number of
bytes written to the file. Otherwise, all records will have the record size established at OPEN time.
For example:
80

PUT #10%t RECORD 134%t COUNT 58%

9-24

RMS Files

This statement writes a 56-byte data record into record 134. Setting the record length this way
prevents unwanted data (padding) from appearing at the end of the record. The RECORD clause must
specify an empty cell or BASIC signals "Record already exists" (ERR = 153). The number specified in
the COUNT must not exceed the size in the MAP or RECORDSIZE clause or BASIC signals "Size of
rnrnrri in":::Iliri"
(I=RR
=
IIIYUII'"-A
\L..I""

I\""'--VIU

1I r:;:h\

J'\J,.

Note that RMS also allocates disk space for empty cells. Thus, if line 90 is the first PUT statement after
the file is created, RMS allocates disk space for 134 records.
9.6.3.3 Writing Records to Block I/O Files
Although block I/O files are implemented through RMS, when you write a record to a block I/O file,
RMS does not perform the same error checking as with relative files. For example:

100
200
300
400

OPEN "BLOCK.DAT" AS FILE #47.., I.JIRTUAL, RECORDSIZE 512%
BLANK_RECORD$ = SPACE$(512%)
MOVE TO #4%, BLANK_RECORD$
PUT #4%, RECORD 5%

This program writes a record containing 512 spaces to the fifth disk block in the file, regardless of
whether the block already contains a record. Note that you must use a MOVE statement to fill the
record buffer before exec uti ng the PUT statement.
9.6.3.4 Writing Records to Indexed Files
For indexed files, RMS stores records in order of ascending primary key value. Therefore, you do not
specify a random or sequential PUT. For example:

20
30
40
50
60

MAP (XXX) STRING R_NUMt DEPT_NAME, PUR_DAT
INPUT "REQUISITION NUMBER"; R_NUM
INPUT "DEPARTMENT NAME"; DEPT_NAME
INPUT "DATE OF PURCHASE"; PUR_DAT
PUT #27..

When writing records to an existing file, the error message "Duplicate key detected" (ERR = 134)
indicates that: 1) a record \vith a matching key field already exists, and 2) you did not allow duplicates on that key. If you allow duplicates, RMS stores the records in a first-in, first-out sequence.
For variable-length records, you can specify a COUNT value when writing the record. This prevents
unwanted data left in the buffer from printing out when a program retrieves the record. You specify
COU NT as part of the PUT. For example:

550

PUT #2%, COUNT 124%

If you do not specify a COUNT, the size of the record written is the length specified by the MAP or
RECORDSIZE clause in the OPEN statement (RECORDSIZE overrides MAP). When writing variablelength records, you must ensure that the record is long enough to include the primary key, or else
BASIC signals "Size of record invalid" (ERR = 156).

9.6.4 Deleting Records (DELETE Statement)
The DELETE statement logically removes a record from a file. After you have deleted a record you can
no longer retrieve it. DELETE works with relative and indexed files only.

February 1984

RMS Files

9-25

A successful FIND or GET must precede the DELETE operation. These operations make the target
record available for deletion. For example:

ao
50

FIND #l%t RECORD 87%
DELETE #1%

The Fil~D statement locates record 67 and the DELETE statement removes this record from the file.
Because the cell itself is not deleted, you can PUT a new record after deleting an old one. For
example:
80

PUT #l%t RECORD 87%

This example writes a new record in place of the old one.
There is no Current Record after a deletion. The Next Record pointer is unchanged.
This example shows the deletion of a record from an indexed file:
30

FIND #2%t KEY #0% EQ la21-58-8012"
DELETE #2%

These statements delete the record with the primary key value equal to "421-56-9012".
If a DELETE statement executes while there is no current record, BASIC signals "No current record"
(ERR = 131). This indicates that the previous FIND or GET was unsuccessful. When deleting or
updating records, include error trapping in your program to make sure you complete FINDs and GETs
successfu II y .

9.6.5 Updating Records (UPDATE Statement)
UPDATE writes a new record at the location indicated by the Current Record Pointer. UPDATE is
valid only on RMS sequential, relative, and indexed files.
The UPDATE statement operates on the Current Record. In order to successfully update a record, you
must know the exact size of the record being updated. BASIC has this information after a successful
GET. Therefore, you can update a record without specifying a COUNT clause after a successful GET.
Note that FIND statements update the Current Record pointer, but because FIND statements do not
move any data, BASIC does not have the record size information needed for an update operation.
However, you can use the UPDATE statement after a FIND, if you specify a COUNT clause. If the
value in the COUNT clause does not match the actual size of the record, BASIC signals "size of
record invalid".
The error message "No current record" (ERR = 131) indicates that the GET was unsuccessful. When
updating records, include error trapping in your program to make sure you complete GETs
successfully.
9.6.5.1 Updating Records in Sequential Files

An UPDATE operation on a sequential file is valid only when:
• The file containing the record is on disk
• The new record is the same size as the one it is replacing

9-26

RMS Files

• You have either executed a successful GET on the channel or specified a COUNT clause to the
UPDATE statement
The following program reads the third record into the buffer and updates it with a new record field,
L.NAME:

10
30
40
50
70
80
100
110
19000
18010
18020
32767

ON ERROR GOTO 18000
MAP (AAA) STRING L.NAME = 60%t F.NAME
20%t RM.NUM
OPEN "STU.DAT" FOR INPUT AS FILE #8% t 8:
ORGANIZATION SEQUENTIALt MAP AAA
INPUT "LAST NAME"; SEARCH.NAME$
GET #8% WHILE SEARCH.NAME$ <> L.NAME
INPUT "ROOM NUMBER"; RM.NUM
UPDATE #8%
GOTO 50
RESUME 18010
CLOSE #8""
PRINT "UPDATE COMPLETE"
END

In the absence of a COUNT clause, UPDATE uses the record size set by the last valid GET on that
channel. This behavior ensures that the record written out by UPDATE is the same size as the record
being replaced. If you specify a COUNT clause, the value must exactly match the size of the record
just retrieved.
An UPDATE operation destroys the Current Record pointer. The Next Record pointer is unchanged.
9.6.5.2 Updating Records in Relative Files

When you UPDATE a record in a relative file, the new record can be larger or smaller than the record
it replaces. However, it must be smaller than the maximum record size set when the file was opened.
For example, this program updates a specified record on a relative file:

10
20
30
35
40
50
60
70
80
80
100

MAP (UPD) STRING ENRDAT = 8%t LONG INVOCt SH.NUMt REAL COST
OPEN "REC.ING" FOR INPUT AS FILE #8'1.. t ·8:
RELATIVE FIXEDt MAP UPD
INPUT "WHICH RECORD TO UPDATE" ; Ai.',
WHILE A% <= 5000%
GET #8%t RECORD A%
INPUT "REVISED COST IS";COST
UPDATE #8%
INPUT "NE}{T RECORD"; A'I..
NE}{T
CLOSE #8'1.,
END

You must use the COUNT clause to specify the size of the new record if it is different from that of the
record last accessed by a GET on that channel. For example:

UPDATE #3%t COUNT 80%

This statement writes a record with a length of 80 bytes. You can specify a length equal to the latest
input operation with the RECOUNT variable. However, if you use RECOUNT after an INPUT LINE
statement, the number of bytes transferred includes the line terminators. For example:

50
60
70

GET #8%t RECORD 404%
INPUT LINE "NEW DATA"; NEW.DATA$
UPDATE #8%t COUNT (RECOUNT - 2%)

RMS Fi les

9-27

This program writes a record exactly equal to the length of NEW.DATA$.
You can also specify a length equal to the last GET. For example:

50
GO
70

INPUT "TYPE IN NEW NAME"; EMP.NAME$
GET #8%, RECORD 581%
UPDATE #8%, COUNT RECOUNT

The RECOUNT variable is set to the length of record 591. (Because the last I/O operation was from a
file and not a terminal, the value of RECOUNT does not include line terminators.) The UPDATE
operation writes EMP.NAME$ with a length equal to that record. For variable-length records, GETs
(not FINDs) must be used to locate the record for updating because a FIND operation does not set the
size of the record.
9.6.5.3 Updating Records in Indexed Files

When you UPDATE a record in an indexed file, the new record can be larger or smaller than the
record it replaces. However, when an indexed file permits duplicate primary keys, an updated record
must be the same length as the old one. When the program does not permit duplicate primary keys,
the updated record:
• Can be no longer than the maximum record size
• Must include at least the primary key field
If the new record: 1) omits one of the old record's alternate key fields or 2) changes one of them, the
OPEN statement must specify CHANGES for that key field. Otherwise, BASIC signals the error "Key
not changeable" (ERR = 130).
For example, this program updates a specified record on an indexed file:

MAP (UPD) STRING ENRDAT = 8%, LONG PART.NUM, SH.NUM, REAL COST
OPEN "REC. ING" FOR INPUT AS FILE #8'1." &
INDEXED, MAP UPD,
&
PRIMARY KEY PART,NUM
INPUT "PART NUMBER TO UPDATE";A%
GET #8%, KEY #0%, EQ A%
INPUT "REVISED COST IS";COST
UPDATE #8%
INPUT "NE}{T RECORD" ; Ai.,
IF A% <= 5000% THEN GOTO 40
CLOSE #8%
END

10
20
30
40
50
GO
70
80
80
100

9.6.6 Restoring Files
The RESTORE # statement returns the Current Record Pointer to the beginning of the file. RESTORE
does not change the file. The RESTORE # statement has the format:
RESTORE #chnl-exp [,KEY #num-exp]

where:
chnl-exp

Is the channel number of the file you want to restore.

,KEY #num-exp

Resets an RMS indexed file by key of reference. KEY number 0 is the primary
key, KEY number 1 is the first alternate, and so forth. When you restore an
indexed file, specify the key you want restored. The default is the current key of
reference.

9-28

RMS Files

For example:
70
80

RESTORE #3%t KEY #2%
RESTORE #3%

Line 70 restores the file in terms of the second aiternate key. Line 90 restores the file in terms of the
pri mary key.
All RMS file organizations can use the RESTORE # statement. RESTORE without a channel number
resets the data poi nter for READ and DATA statements and does not affect any fi les.

9.7 Truncating a File (SCRATCH Statement)
The SCRATCH statement is valid only on sequential files. Although you cannot delete single records
from a sequential file; you can delete all records starting with the Current Record through to the end
of the file. To do this, you must first specify ACCESS SCRATCH when you open the file.
To truncate the file, you first position the Current Record pointer by executing a FIND or GET after
locating the last desired record. Then you execute the SCRATCH statement:

10
30
50

60
70

OPEN uMMM.DAT" AS FILE #2%
&
tSEQUENTIAL FIXEDt ACCESS SCRATCH
FIND #2% FOR 1% = 1% TO 33%
SCRATCH #2%
CLOSE #21.
END

This program locates the thirty-third record and truncates the file beginning with that record.
SCRATCH does not change the physical size of the file. You can write records with the PUT statement
immediately after a SCRATCH.

9.8 Unlocking Records (FREE and UNLOCK Statements)
When you retrieve a record from an RMS file opened with ALLOW WRITE or ALLOW MODIFY, RMS
protects the integrity of the file by preventing other users from accessing that record. Note that in
VAX-ll RMS, only the retrieved record is locked, while in RMS-l1, the entire bucket containing the
record is locked. For RMS block I/O files, this means that other users cannot access the disk biock
retrieved by your program.
If: 1) the same file is open in another program or on another channel in the same program and
2) another user attempts to access the record or block, BASIC signals the error "Record is locked"
(ERR = 154). RMS unlocks a record or bucket when:
• Your program performs another record operation
• Your program explicitly unlocks it
For example:

60
80

FREE #8I
UNLOCK #61

FREE unlocks all previously locked records. UNLOCK unlocks only the last record accessed. FREE
and UNLOCK let two or more programs use the file at the same time.

RMS Files

9-29

VAX-ll BASIC allows both FREE and UNLOCK; however, BASIC-PLUS--2 supports only the
UNLOCK statement. In addition, VAX-ll BASIC provides the UNLOCK EXPLICIT clause to the
OPEN statement for specifying that all accessed records remain locked until explicitly unlocked with
the UNLOCK or FREE statement. See BASIC on VAX/VMS Systems for more information.

9.9 Virtual Array Files
You create a virtual array by dimensioning an array with the DIM # statement, then opening a
VIRTUAL file on that channel. You access virtual arrays just as you do normal arrays. For example:

100

DIM #1%, LONG INT_ARRAY(10,10,10)

1000

OPEN III)IRT.DAT" FOR OUTPUT AS FILE #l%t lJIRTUAL

5000

INT_ARRAY(5t5,5)

= 100%

Line 100 dimensions a virtual array on channell. Line 1000 opens a virtual file to contain the array.
Line 5000 assigns a value to one array element.
You cannot redimension virtual arrays with an executable DIM statement. See Chapters 4 and 7 for
more information on virtual arrays.

9.10 File Operations
This section describes how to rename, close, delete, and share files within a BASIC program.

9.10.1 Renaming Files
If the protection code permits, you can change the name or directory of a file with the NAME AS
statement. The format is:
NAME str-exp1 AS str-exp2

where:
str-exp1

Is the old file name.

str-exp2

Is the new file name.

For example:

NAME "MONEY.DAT" AS "ACCNTS.DAT"

This statement changes the name of the file named MONEY.DAT to ACCNTS.DAT. NAME AS does
not change the fi Ie's protection.
You must always include an output file type because there is no default. If you use the NAME AS
statement on an open file, the new name does not take effect until you close the file.

9-30

RMS Files

February 1984

9.10.2 Closing Files and Ending I/O
All programs should close files before the program terminates. However, BASIC automatically closes
files:
• While executing a CHAIN statement
• At an EN D statement
• When it completes the highest numbered line in the program
BASIC does not close files after executing a STOP, SUBEND, or FUNCTIONEND statement.
The CLOSE statement has the format:
CLOSE [#]chnl-exp [,[#]chnl-exp] ...
where:
chnl-exp

Is a channel number. If you do not specify a channel, BASIC issues an error.

This is an example of CLOSE:
10
20
30
40

CLOSE#11
BI = 4%
CLOSE#2It BIt 61. + 1%
CLOSE 1% FOR 1% = 12% TO 1% STEP -1%

The CLOSE statement closes files and disassociates these files and their buffers from the file numbers.
If the file was a magnetic tape device, CLOSE writes trailer labels at the end of the file.

9.10.3 Deleting Files
If the file protection code permits, you can delete a file with the KILL statement. The KILL statement
has the format:
KILL file-spec
where:
file-spec

Is the fi Ie specification of the fi Ie you want deleted.

For example:
610

KILL ITEST.BP2"

This program deletes the file named TEST.BP2. Note that on VAX/VMS and RSX-llM/M-PLUS
systems, this statement deletes only the most current version of the file. You can delete only one file
at a time. Do not omit file extensions; there is no default.
You can delete a file that is currently being accessed by other users; however, the file is not deleted
until all users have closed it. You cannot open or access a file after you have deleted it.

RMS Files

9-31

9.11 File-Related Functions
BASIC provides built-in functions for finding:
• The current cursor position (CCPOS).
• The number of bytes moved in the last I/O operation (RECOUNT).
• The file status (STATUS).
• The margin size (MAR%). MAR% is available only in VAX-11 BASIC.
The following sections describe these functions.

9.11.1 CCPOS
The CCPOS function returns the output record's current character position on a specified channel
number. Its format is:
returned-integer = CCPOS(chnl-exp)
If the channel expression is zero, CCPOS returns your terminal's current cursor position. For example:
INPUT
PRINT
PRINT
PRINT
END

10
20
30
40
50

A$ f B$ f C$
A$; B$;
IF CCPOS(O) > 14
C$

This program accepts three string values and prints them. However, the program checks whether the
cursor is past character position 14 in the output line. If it is, BASIC prints C$ on a new line.

9.11.2 RECOUNT
Input operations can transfer varying amounts of data. The system variable RECOUNT contains the
number of characters (bytes) read after each input operation. Its format is:
integer-variable = RECOUNT
After an input operation from your terminal, RECOUNT contains the number of characters transferred, including the line terminator. After accessing a file record, RECOUNT contains the number of
characters in the record only.
RECOUNT is reset by every input operation on any channel, including the controlling terminal. This
means that INPUT, L1NPUT, and INPUT LINE statements also affect RECOUNT. Therefore, if you
need to use the value of RECOUNT, copy it to a different storage location before executing another
input operation. RECOUNT is not properly set if an error occurs during an input operation.
RECOUNT is often used as the argument to the COUNT clause in the PUT statement. For example:
1000

GET

1100

PUT #5%, COUNT RECOUNT

9-32

RMS Fi les

#4'X.

This ensures that the output record on channel five is the same length as the input record on channel
four.

9.11.3 STATUS
The STATUS function accesses the status word containing characteristics of the last opened file. See
the BASIC Reference Manual for more information on the STATUS function.

9.11.4 MARO/o (VAX-11 BASIC Only)
The MAR% function returns the margin width of a specified channel. Its format is:
integer-variable = MAR[%](chnl-exp)

If the channel is 0, MAR% returns the margin width of your terminal. If the channel expression
specifies a file, then MAR% returns the record size of the file.

9. 12 Optimizing I/O
This section explains the OPEN statement keywords that enable you to structure your file more
efficiently. These keywords are: BUCKETSIZE, TEMPORARY, FILESIZE, SPAN, CONTIGUOUS,
EXTENDSIZE, CONNECT, USEROPEN, WINDOWSIZE, BUFFER, and RECORDTYPE.

9.12.1 BUCKETSIZE
The BUCKETSIZE clause applies only to relative and indexed files. A bucket is a logical storage
structure that RMS uses to build and maintain relative and indexed files on disk devices. A bucket
contains between 1 and 31 disk blocks, inclusive. The default bucket size is one block. Although
RMS defines the bucket size in terms of disk blocks, the BASIC BUCKETSIZE clause specifies the
number of records a bucket contains. For example:

,BUCKETSIZE 12%
This example specifies a bucket containing 12 records. RMS allocates enough storage from your
program's address space for one bucket. A GET statement transfers one record from this storage to
your program's record buffer. Thus, RMS initiates an I/O operation from the disk only when a new
bucket is required.
When you open an existing relative or indexed file, and specify a BUCKETSIZE other than that
originally assigned to the file, BASIC signals "File attributes not matched" (ERR = 160).
Records cannot span bucket boundaries. Therefore, when you specify bucket size in your program,
you must consider the size of the largest record in the file. A bucket must contain at least one record.
There are two ways to establish the number of blocks in a bucket. The first is to use the BASIC default.
The second is to specify the number of records you want in each bucket. BASIC then calculates a
bucket size based on that number.
The default bucket size assigned to relative and indexed files is as small as possible. A small bucket
minimizes the number of records locked when a file is shared. However, it also forces more disk
transfers, especially when you are accessing records sequentially.

February 1984

RMS Files

9-33

BASIC selects a default bucket size depending on:
• The record length
• The file organization (relative or indexed)
• The record format (fixed or variable)
If you do not define the BUCKETSIZE clause in the OPEN statement, BASIC:
• Assumes that there is a minimum of one record in the bucket
• Calcu lates a size
• Assigns the number of blocks
If you supply a BUCKETSIZE clause and specify the number of records, BASIC uses formulas to derive
the necessary number of blocks, as follows:
Fixed-length records without BUCKETSIZE specification:
Bnum = (1 + Rlen)/512
Fixed-length records with BUCKETSIZE specified:
Bnum = ((1 + Rlen)*Rnum)/512
Variable-length records without BUCKETSIZE specification:
Bnum = (3 + Rmax)/512
Variable-length records with BUCKETSIZE specified:
Bnum = ((3 + Rmax)*Rnum)/512
where:
Bnum

Is the minimum number of blocks for each bucket, rounded up to an integer.

Rlen

Is the length in bytes of the file's fixed-length records, as defined in the RECORDSIZE
clause.

Rmax

Is the length in bytes of the largest variable-length record in the file, as defined in the
RECORDSIZE clause.

Rnum

Is the number of records you want in each bucket, as defined in the BUCKETSIZE
clause.
Is the byte RMS uses to flag deleted records in the file.

9-34

Represents the "record deleted" byte plus two bytes that indicate the count field.

RMS Files

Table 9-2 shows the default bucket sizes selected by BASIC when the bucket contains the default of
one record.

Table 9-2: Relative File Default Bucket Size

Number
of Blocks

1
2
3
4
5
6
7
8
9
10
11

12
13
14
15

Record Length,
Fixed-Length
Records

Maximum Record Size,
Variable-Length
Records

1-511
512-1023
1024-1535
1536-2047
2048-2559
2560-3071
3072-3583
3584-4095
4096-4607
4608-5119
5120-5631
5632-6143
6144-6655
6656-7167
7168-7679

1-509
510-1021
1022-1533
1534-2045
2046-2557
2558-3069
3070-3581
3582-4093
4094-4605
4606-5117
5118-5629
5630-6141
6142-6653
6654-7165
7166-7677

BASIC derives the default bucket size for indexed files from the following formulas:
Fixed-length records without BUCKETSIZE specified:
Bnum = (22 + Rlen)/512
Fixed-length records with BUCKETSIZE specified:
Bnum = (((7 + Rlen)*Rnum) + 15)/512
Variable-length records without BUCKETSIZE specified:
Bnum = (24 + Rmax)/512
Variable-length records with BUCKETSIZE specified:
Bnum = (((9 + Rmax)*Rnum) + 15)/512
where:
Bnum

Is the number of biocks for each bucket.

Rlen

Is the length in bytes of the file's fixed-length records, as defined in the RECORDSIZE
clause.

Rmax

Is the length in bytes of the largest variable-length record in the file, as defined in the
RECORDSIZE clause.

Rnum

Is the number of records you want in each bucket, as defined in the BUCKETSIZE
clause.

RMS Files

9-35

Is the 15-byte RMS bucket overhead plus 7 bytes for the fixed-format record header
length. When you define BUCKETSIZE, BASIC allocates 7 bytes to each record in the
bucket and 1 5 bytes to the complete bucket.

Is the 15-byte RMS bucket overhead plus 9 bytes for the variable-format record header
length. When you define BUCKETSIZE, BASIC allocates 9 bytes to each record in the
bucket and 15 bytes to the complete bucket.

Table 9-3 shows the bucket sizes selected by BASIC when the number of records is undefined.

Table 9-3: Indexed File Default Bucket Size

Number
of Blocks

Record Length,
Fixed-Length
Records

Maximum Record Size,
Variable-Length
Records

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

1-490
491-1002
1003-1514
1515-2026
2027-2538
2539-3050
3051-3562
3563-4074
4075-4586
4587-5098
5099-5610
5611-6122
6123-6634
6635-7146
7147-7658

1-488
489-1000
1001-1512
1513-2024
2025-2536
2537-3048
3049-3560
3561-4072
4073-4584
4585-5096
5097-5608
5609-6120
6121-6632
6633-7144
7145-7656

If a BASIC program opens an indexed file with fixed-length records of 100 bytes and a bucket size of
5, the run-time system makes these calculations when creating the file:
• 100 bytes for the data, for example, MAP (ABC) A$ = 100 + 7 bytes for the record header
• 107 bytes for the complete record
• 535 bytes for the records in a bucket (5*107

535) + 15 bytes for the bucket overhead

• 550 bytes specified for each bucket
RMS requires that buckets be an integral number of blocks; therefore, the bucket size for this file is
two blocks instead of one. This means that each bucket can hold at least five records. RMS continues
to fill the bucket with as many records as possible.

Note
When you specify a bucket size for files in your program, keep in mind the space
versus speed trade-offs. A large bucket size increases file processing speed because a
greater amount of data is available in memory at one time. However, it also increases
the memory space needed for buffer allocation. Likewise, a small bucket size minimizes buffer requirements, but can also decrease the speed of operations.

9-36

RMS Fi les

9.12.2 TEMPORARY
If you specify TEMPORARY in the OPEN statement, BASIC deletes the file: 1) when you close it,
2) vvhen you log out, Oi 3) when the piogiam aborts. ~..jo entry is made in any directory.

9.12.3 FILESIZE
With the FILESIZE attribute, you can allocate disk space for a file when you create it. For example:
100

0 PEN

VALUES II

FOR OUT PUT AS FILE #37.. t

FILES I ZE 50%

This statement allocates 50 blocks of disk space for the fi Ie "VALU ES."
Preextending a file has several advantages. First, the system can create a complete directory structure
for the file, instead of allocating and mapping additional disk blocks when needed. Second, you
reserve the needed disk space for your application. This ensures that you will not run out of space
when the program is running. Third, preextension can make some of the file's disk blocks contiguous,
especially when used with the CONTIGUOUS keyword.
Preextension can be a disadvantage if it allocates disk space needed by other users, however.

9.12.4 NOSPAN
Normally, sequential files allow records to cross (span) block boundaries. If records cross block
boundaries, RMS packs records into the file end-to-end throughout the file, plus space for control
information and padding.
NOSPAN overrides this default, forcing records to fit in individual blocks, plus space for control
information and padding. This wastes space if your records (plus RMS overhead) do not exactly fit
into a block.
When block boundaries restrict records, fixed-length records must be less than 512 bytes, and
variable-length records less than 510 bytes. This can waste extra bytes at the end of the file. When
records span block boundaries; however, RMS can write:
• More than one record in each block (for records shorter than 512 bytes)
• A partial record in each block (for records longer than 512 bytes)
• Records end-to-end without regard to block boundaries
For example, by specifying NOSPAN, only four 120-byte records fit into a disk block. If you do not
specify NOSPAN, BASIC begins writing the fifth record in the block, and continues that record in the
next block. This minimizes wasted disk space and improves the file's capacity, at the expense of
increased processing overhead.

9.12.5 CONTIGUOUS
A contiguous file with physically adjoining blocks minimizes disk searching and decreases file access
time. Once the system knows where a contiguous file starts on the disk, it need not use as many
retrieval pointers to locate the pieces of that file. Rather, it can access data by calculating the distance
from the beginning of the file to the desired data. On PDP-11 systems, if there is not enough
contiguous disk space, BASIC signals an error. On VAX /VMS systems, BASIC allocates as much

RMS Files

9-37

contiguous space as possible - this is called contiguous-best-try in VAX-11 RMS. For truly contiguous records on VAX /VMS systems, you must use the USEROPEN clause.
Opening the file with FILESIZE and CONTIGUOUS clauses preextends the file with enough contiguous space for the entire file, if the contiguous space is available.

9.12.6 EXTENDSIZE
The EXTENDSIZE attribute determines how many disk blocks RMS adds to the file when the current
allocation is exhausted. You specify EXTENDSIZE as a number of blocks. For example:

1000

OPEN "TSK.ORN" FOR OUTPUT AS FILE #2%# &
ORGANIZATION RELATIVE, EXTENDSIZE 128%

The EXTENDSIZE clause causes RMS to add 128 disk blocks whenever the current space allocation is
exhausted and the file must be extended.
The value you specify: 1) must be included when you create the file, 2) cannot exceed 65,535 disk
blocks, and 3) is rounded to the next cluster boundary. If you specify zero, the extension size equals
the RMS default value. The EXTENDSIZE value is a permanent file attribute.

9.12.7 CONNECT
The CONNECT clause can be used only on indexed files. CONNECT lets you process different
streams of records on different indexed keys without incurring all the RMS overhead of opening the
same file more than once. For example, a program can read records in an indexed file sequentially by
one key and randomly by another. Each stream is an independent, active series of record operations.
For example:

100

200

MAP (INDMAP)

OPEN

WORD EMP_NUM,
STRING EMP_LAST_NAME
SINGLE SALARY,
STRING WAGE_CODE = 2

IND.DAT" FOR INPUT AS FILE #1 #
ORGANIZATION INDEXED,
PRIMARY KEY EMP_NUMt
MAP INDMAP

! •
!•
! •

OPEN "IND.DAT" FOR INPUT AS FILE #2,
ORGANIZATION INDEXED,
PRIMARY KEY EMP_NUMt
MAP INDMAP,
ALTERNATE KEY EMP_LAST_NAMEt
CONNECT 1
! •
! •
! •

9-38

RMS Files

20 t

OPEN IIINO.OAT FOR INPUT AS FILE #3t
ORGANIZATION INDEXEDt
PRIMARY KEY EMP_NUMt
MAP INDMAPt
ALTERNATE KEY WAGE_CODEt
Il

'''''101'''''111•. 1110..

r-,....""

I... U 1\1 1\lC, I... 1

0:
&:
&:
&:

The channel on which you open the file for the first time is called the parent. The CONNECT clause
specifies another channel on which you access the same file. These connected channels are called
children. More than one OPEN statement can connect to the parent channel. You cannot connect to
a channel that has been already been connected to another channel.

9.12.8 WINDOWSIZE
The WINDOWSIZE attribute specifies the number of block retrieval pointers in memory for the
file. WINDOWSIZE is valid only in VAX-11 BASIC and in BASIC-PLUS-2 on RSX-11M/M-PLUS
systems.
Retrieval pointers are associated with the file header and point to contiguous blocks on disk. By
keeping retrieval pointers in memory, you can reduce the 1/0 associated with locating a record, as
the operating system does not have to access the file header for pointers as frequently. The number of
retrieval pointers in memory at anyone time is determined by the system default or by the value
you supply in the WINDOWSIZE clause. The usual default number of retrieval pointers on
RSX-11M/M-PLUS and VAX/VMS systems is seven.
On VAX /VMS systems, a value of 0 specifies the default number of retrieval pointers. A value of 255
means to map the entire file, if possible. Values between 128 and 254, inclusive, are reserved. On
RSX-11 M 1M-PLUS systems, you can specify up to 127 retrieval pointers.
On RSTS/E systems the number of pointers in a window block is fixed at seven. Thus, you cannot use
the WINDOWSIZE clause. You can, however, use the CLUSTERSIZE clause to increase the number of
contiguous blocks mapped by one retrieval pointer.

9.12.9 BUFFER
The BUFFER keyword applies to disk files of any organization. By default, RMS allocates enough
space in your task to hold one bucket (for relative and indexed files) or one disk block (for sequential
files). When the program executes the first GET statement, one bucket or one block is transferred to
this RMS buffer and one record is transferred to the program's record buffer. Subsequent GETs move
one record from the RMS buffer to the program's record buffer. When the OPEN statement specifies a
BUFFER value, RMS multiplies its buffer by the specified value. BUFFER does not affect the size of the
program's record buffer.
Thus, specifying a BUFFER value of two causes RMS to allocate enough space to hold two buckets (or
two disk blocks for sequential files). Multiple buffers can speed access because more data is transferred during each disk access. However, this requires more memory.
For example:

1000

OPEN IIRTFG.DAT II FOR INPUT AS FILE #2%t
ORGANIZATION INDEXEDt BUFFER 5

RMS Files

9-39

This OPEN statement sets up an RMS buffer big enough to hold five buckets for the file RTFG.DAT. In
BASIC-PLUS-2, you can specify up to 255 buffers. In VAX-11 BASIC, you can specify up to 127
buffers as either a positive or negative number. Table 9-4 summarizes the effects of BUFFER values in
VAX-11 BASIC.

Table 9-4: BUFFER Values and Allocations in VAX-ll BASIC
Value

Allocation

0< BUFFER < 127

RMS allocates enough space for the specified number of buckets. On VAX /VMS systems, this
locks those buffers in the working set of the process.

-128 < BUFFER < 0

BASIC allocates the absolute value of the specified number of buffers. On VAX/VMS systems,
this does not lock those buffers into the working set of the program.

BUFFER = a

BASIC allocates the process default for the particular file organization and device.

If there is no process default, BASIC uses the system default for the file organization and device. If the
system default is zero, BASIC allocates one buffer.

9.12.10 RECORDTYPE
The RECORDTYPE attribute lets you specify record formats compatible with files created by other
language processors. You can choose one of four qualifiers: LIST, FORTRAN, ANY, or NONE. The
default for BASIC is LIST, which specifies carriage return format. This is standard for ASCII text files
and means that carriage control is performed by the output device.
If your program accesses a file created with a FORTRAN language processor, use the FORTRAN
qualifier. For example:
1000

OPEN "FIL.DAT" FOR INPUT AS FILE #lX.t B:
ORGANIZATION SEQUENTIAL, RECORDTYPE FORTRAN

The FORTRAN qualifier sets the FORTRAN carriage control attribute in the RAT field in the FAB. The
first byte of the record is still assumed to be the carriage control information.
If your program accesses a file created by an unknown language processor, use the ANY qualifier. For
example:
1000

OPEN "FIL.DAT" FOR INPUT AS FILE #1%, B:
ORGANIZATION INDEXED, RECORDTYPE ANY

The ANY qualifier causes BASIC to ignore any attribute except a record attribute. If you create a file
with the ANY qualifier, BASIC uses the default of LIST.
For compatibility with BASIC-PLUS-2 virt~al files, use the NONE qualifier. NONE lets VAX-11
BASIC read virtual array files (created with ORGANIZATION VIRTUAL).

9.12.11 USEROPEN
The USEROPEN keyword specifies a user-created external procedure that BASIC executes when you
open or create a file. The procedure can specify additional file OPEN parameters. For example:
1000

9-40

OPEN "FILE.DAT" FOR INPUT AS FILE #2X., B:
ORGANIZATION INDEXED, USEROPEN MYOPEN

RMS Files

The code in MYOPEN determines how the file FILE.DAT opens. On VAX/VMS systems, the RunTime Library sets up six RMS control structures before calling the USEROPEN procedure. Table 9-5
summarizes these structures and their meanings.

Table 9-5: VAX-ll R,\1S Control Structures Set by USEROPE~"J

Name

Meaning

FAB

File Access Block

RAB

Record Access Block

NAM

Name Block

XAB

FHC Extended Attributes Block

ESA

Expanded Name String

RSA

Resultant Name String

On PDP-11 systems, a USEROPEN routine sets only the FAB and RAB.
A USEROPEN procedure should not alter the allocation of these structures, although it can modify the
contents of many of the fields. However, you should not modify fields set by other OPEN statement
keywords. For example, use RECORDSIZE to set the record length; do not use USEROPEN.
The allocation of the RMS control structures (except for RAB on VAX /VMS systems) lasts only for the
duration of the OPEN statement. Therefore, your USEROPEN can retain only the RAB address for use
after the OPEN.
During execution of the USEROPEN clause:
1.

BASIC performs normal OPEN statement processing up to the point where it would call the
Rtv\S OPEN /CREATE and COI~NECT routines.

BASIC passes control to the USEROPEN routine.

BASIC passes the address of the FAB as the first parameter, the address of the RAB as the
second parameter, and, in VAX-11 BASIC, the address of the user-specified channel number
as the third parameter.

The USEROPEN routine calls RMS OPEN /CREATE and CONNECT routines and returns the
status in RD.

For example, the following OPEN statement calls the VAX-11 MACRO routine OPEN FILL contained
in the MARS source module OPENFILL.MAR.

100
110

120
130 END

MAP (REC.l) SURNAME$ = 20%t REST$ = 60%
OPEN IIUOPNTST.ID}{II FDR OUTPUT AS FILE #l%t
ORGANIZATION INDEXEDt &
MAP REC.l t &:
PRIMARY KEY SURNAME$t &:
USEROPEN OPEN_FILL
CLOSE #1%

RMS Files

9-41

The MACRO program OPEN_FILL is:
.TITLE OPEN_FILL
$FABDEF
$RABDEF
$;{ABDEF
$;{ABKEYDEF
.ENTRY OPEN_FILLt AM<>

Define all
Define all
Define all
Define all
Routine to
Percentafe

FAB bits and offsets
RAB bits and offsets
;{AB bits and offsets
;{ABKEY bits an d offsets
open f i 1 e . . 11 th bucKet fill
set to 256 bytes / bucKet

; Set bucKet fill percentafe
MOt.,lL
MOVL
CMPB
BEQL
MOVL
BNEQ

10$:

a (AP) tRO
FAB$L_XAB(RO) tRO
#XAB$C_KEYtXAB$B_COD(RO)
20$
XAB$L_NXT(RO) tRO
10$

Get address of FAB into RO
Get address of XAB into RO
Is this the KEY XAB?
YeSt fo store fill size
Get address of next XAB into RO
If not zerOt loop bacK for next XAB

; Here if no XABKEY was foundt

return illegal orfanization

MOVL #RMS$_ORGtRO
RET
;+

; Here when XABKEY is foundt set DFL
; Store data bucKet fill size (bytes)

20$:
; +

; Set bit in RAB ROP indicatinf RMS should use XABKEY DFL
MOI.JL 8 (AP) tRO
INSV #1 t #RAB$V_LOAt
RAB$L_ROP(RO)

#It-

Get address of RAB into RO
Set LOA bit in
RAB ROP

; Now create and connect to the file
$CREATE FAB = @a(AP)
BLBC
ROt30$
$CONNECT RAB = @8(AP)
30$:

RET

Create file
Branch if error
Connect streaM to file
Return with RO set to status

.END

In PDP-ll BASIC-PLUS-2, the USEROPEN routine is called with the FAB address as the first parameter and the RAB address as the second parameter, using the standard RS passing sequence.
On PDP-ll systems, the USEROPEN routine may use any register; however, the stack must be in the
same state at routine exit as it was at routine entrance. The RMS STS status value must be passed back
to the OTS in RO.
You cannot use a USEROPEN routine to fill the RBF, UBF, BKS, or CTX fields in the RAB. These fields
are filled in after the USEROPEN routine returns; thus, any values placed there by the USEROPEN
routi ne wi II be overwritten.
Note
You must not set Locate mode when using a USEROPEN routine on sequential files.

9-42

RMS Files

February 1984

The following is an example of the USEROPEN clause for PDP-l1 systems. This USEROPEN routine
sets the protection of the file:
.TITLE

USR

This routine will link a protection XAB to
the end of a linked list of XABs so that the
file will be created with a protection code different
froM the default protection code for the disk it is on.
INPUT:
2(R5)
a(R5)

Address to the FAB
Address to the RAB

OUTPUT:
RO - the STS field of either the FAB or RAB
EFFECT:
The file is created and a connect is done if no errors occurred
R1 - R3 are destroyed.
EXTERNALS:
.MCALL
$GNCAL
$FBCAL
$RBCAL

$GNCALfFAB$BfRAB$BfXAB$BtNAM$Bt$FBCALf$RBCAL

MOl.!

2 (R5) fR2

USR: :
Get fab pointer

Walk down throu~h the linked list of XABs ( if any)
insert the PRO XAB at the end.

1$ ~

2$:
3$:

5$:

and

$FETCH
BEQ

R3 t>{AB tR2
2$

Get the first XAB addr if any
BR if none

$FETCH

R 1 ~N}{T ~R3

BEQ
MOl.!
BR

3$
Rl tR3
1$

Get the next XAB on the list
If none left BR
R3 = current XAB address
Cont until done

$STORE
BR

#PROCOO f}{AB fR2
a$

Store our XAB address in the FAB
Cont

$STORE

#PROCOD fN}{T fR3

Store our XAB address in the last XAB on list

$CREATE R2

Create the file

MOl,!
BLE

O$STS (R2) fRO
5$

Get error status
Quit on error

MOl.J

a(R5) fR1

Get rab RAB pointer

$CONNECT R1

Connect the RAB-FAB

MOl,!
RETURN

Get error status
RETURN

O$STS (R 1) fRO

(continued on next page)

RMS Files

9-43

Set the protection code for the XAB

PROCOD:
+

XAB$B

}-{B$ PRO

RS}-{

}-{$PRO

60842

(RtRWEDtRtR)

}-{$PRO

Set protection

.IFF
iENDC
}-{AB$E
.END

9.12.12 DEFAULTNAME
The DEFAULTNAME clause in the OPEN statement lets you specify a default file specification for the
file to be opened. BASIC uses the DEFAULTNAME clause for any part of the file specification that is
not explicitly supplied. For example:

10 LINPUT "Next data file"; FIL$
20 OPEN FIL$ FOR INPUT AS FILE #5%, &
ORGANIZATION SEQUENTIAL, DEFAULTNAME "DB2:.DAT"

The DEFAULTNAME clause supplies default values for the device, account, and file type portions of
the file specification. Thus, typing ABC in response to the "Next data file?" prompt causes BASIC to
try to open DB2:ABC.DAT.
Note that BASIC uses the DEFAUL TNAME values only if you do not supply those parts of the file
specification appearing in the DEFAULTNAME clause. For example, if you type DB3:ABC in
response to the prompt, BASIC tries to open DB3:ABC.DAT. In this case DB3: overrides the device
default in the DEFAULTNAME clause. Also note that any system defaults for device and account
remain in effect unless DEFAULTNAtv\E overrides them as well.

In VAX-11 BASIC and BASIC-PLUS-2 on RSX-11M/M-PLUS systems you can use the
DEFAULTNAME clause with all file organizations. However, in BASIC-PLUS-2 on RSTS IE systems,
you cannot use the DEFAULTNAME clause with block 1/0 files; that is, files with ORGANIZATION
VIRTUAL.

9-44

RMS Files

February 1984

Chapter 10
Compiler Directives

Compiler directives are instructions telling BASIC to perform certain operations as it translates a
source program. With compiler directives, you can:
• Place program titles and subtitles in the header that appears on each page of the listing file
• Place a program version identification string in both the listing file and object module
• Start or stop the inclusion of listing information for selected parts of a program
• Start or stop the inclusion of cross-reference information for selected parts of a program
• Include BASIC code from another source file
• !nclude COD record definitions in a BASIC program (VAX-ll BASIC only)
• Conditionally compile parts of a program
• Terminate compilation
All compiler directives:
• Must begin with a percent sign
• Can be preceded by an optional line number
• Must be the only text on the line (except for %IF-% THEN-%ELSE-%END-%IF)
• Cannot begin in the first column
• Cannot appear within a quoted string
This chapter describes the use of these directives.

10-1

10.1 Controlling the Compilation Listing
Listing directives let you control the content and appearance of the compilation listing. There are
eight compiler listing directives:
• %TITLE (places a title string on the first line of the listing header)
• %SBTTL (Places a subtitle string on the second line of the listing header)
• %IDENT (Places an identification string on the second line of the listing header and within the
object modu Ie)
• %PAGE (Causes BASIC to skip to top-of-form in the output listing)
• %NOLIST (Causes BASIC to stop accumulating information for the output listing)
• %LlST (Causes BASIC to resume accumulating information for the output listing)
• %NOCROSS (Causes BASIC to stop accumulating cross-reference information for the output listing)
• %CROSS (Causes BASIC to resume accumulating cross-reference information for the output listing)
Note that these listing control directives have no effect if no source program listing is being produced.
Similarly, the %CROSS and %NOCROSS directives have no effect if no cross-reference listing is
being produced. However, the %IDENT directive places the specified text in the object module
whether or not a listing is produced. These directives are described in the following sections.

10.1.1 % TITLE and %SBTTL
The %TITLE directive lets you specify a line of text that appears on the first line of every page in the
compilation listing. This text line normally contains the source program title and other information.
The format of %TITLE is:
%TITLE text

where:
text

Is a quoted string of up to 48 characters.

If the %TITLE directive is the first source text in a module, then the quoted string appears in the first
line of every page of the compilation listing. Otherwise, the quoted string appears in the first line of
every subsequent page in the compilation listing. That is, if BASIC encounters a %TITLE directive after
it has begun creating a page in the output listing, the title information will not appear on that page.
Rather, it appears on all of the following pages until it encounters another %TITLE directive.
The quoted string appears in character positions 33 to 81 in the first line of the listing header. %TITLE
must appear on its own line. For example:
10

%TITLE 'File OPEN Subpro~raM -- Author
SUB FILSUB (STRING F_NAME)

Hu~h

Ristics'

The %SBTTL directive lets you specify a line of text that appears on the second line of every page in
the compilation listing (beneath the title). If BASIC encounters a %SBTTL directive after it has begun
creating a page in the output listing, the subtitle information will not appear on that page. Rather, it
appears on all following pages until it encounters another %SBTTL or % TITLE directive.

10-2

Compiler Directives

Any number of %SBTTL directives can appear in a source file; thus, you can use subtitle text to
identify parts of the source program. The format of %SBTTL is:
%SBTTL text
where:
text

Is a quoted string of up to 48 characters.

The quoted string appears in the second line of the listing header, in character positions 33 to 81. This
example shows the use of both %TITLE and %SBTTL directives:
'X.TITLE 'Payroll Program'
'X.SB TTL 'Constant Declarations'

!•
!i
! •

2000

'X.SBTTL 'Subroutines'
! •
! •
!•

19000

%SBTTL 'Error Handler'
! •

! •
!•

The first line of the listing's first page contains "Payroll Program" and the second line contains
"Constant Declarations". When BASIC encounters the %SBTTL directive on line 2000, the second
line on each subsequent page becomes "Subroutines". When BASIC encounters the %SBTTL directive on line 19000, the second line on each subsequent page becomes "Error Handler".
Note
You can use multiple %TITLE directives in a single source file; however, whenever
BASIC encounters a %TITLE directive, the %SBTTL information is set to the null string.
Therefore, if you want to display subtitle information, each new %TITLE directive
should be accompanied by a new %SBTTL directive.

10.1.2 %IDENT
The %IDENT directive identifies the version of a program module. The %IDENT information appears
in the listing file and the object module. Thus, the map file created by the Task Builder (on PDP-11
systems) or the VAX-l1 Linker also contains this information. The format of %IDENT is:
%IDENT text
where:
text

Is a quoted string of up to 6 characters in PDP-11 BASIC-PLUS-2 and up to 31 characters
in VAX-11 BASIC.

The identification text appears in the first 6 to 31 character positions of the second line on each
subsequent listing page. For example:
100

%IDENT 'V5.3'
SUB PAY
!•
!•
!•

Compiler Directives

10-3

The %IDENT information appears as the first entry on the second line of the listing. The information is
also included in the object module if the compilation produces one. If the Task Builder or Linker
generates a map iisting, this information also appears there.
On VAX/VMS systems, the information supplied by %IDENT can control certain operations of the
VAX-ll Linker. See the VAX-II Linker Reference Manual and the BASIC on VAX/VMS Systems
manual for more information.
If your source module contains multiple %IDENT directives, BASIC signals a warning and uses the
version specified in the first %IDENT directive.

10.1.3 %PAGE
The %PAGE directive causes BASIC to begin a new page in the listing file. Its format is:

%PAGE
For example:
%TITLE 'Payroll Pr09'rafTl'
'X,PAGE
'X,SBTTL 'Constant Declarations'

!•
!•
! •

2000

'X,PAGE
%SBTTL 'Subroutines'
! •
!•
!•

18000

%PAGE
%SBTTL 'Error Handler'
! •
!•

! •

The %PAGE directives cause BASIC to skip to a new page in the listing file just before each new
subtitle. Note that, in order to have title and subtitle information appear in the heading of this page,
you cannot place a line number between the %PAGE, %TITLE, and %SBTTL directives.

10.1.4 %LIST and %NOLIST
%NOLIST causes BASIC to stop adding information to the output listing file while %LlST causes
BASIC to resume adding information to the listing file. %LlST and %NOLIST are complementary
directives. Thus, you can control which parts of the source program are to be listed. The format of
%LlST is:
%LlST

The format of %NOLIST is:
%NOLIST

10-4

Compiler Directives

For example:
%TITlE 'Payroll Pro~raM'
1. PAGE
%S5TTl 'Constant Declarations'

! •
!•
!•

kNOlIST

100

!•
!•
!•

1800

1.l I ST
! •
! •
! •

2000

%PAGE
%S5TTl 'Subroutines'
! •
!•
! •

18000

1. PAGE
1.S5TTl 'Error Handler'
! •
!•
!•

The %NOLIST directive in line 100 causes BASIC to stop adding new information to the listing file.
The %LlST directive in line 1900 causes BASIC to resume adding this information, and the directive
itself appears as the next line in the listing file. Thus, BASIC produces no listing information for lines
100 to 1900.
Note

If you have not requested the creation of a compilation listing, the %LlST and
%NOLIST directives have no effect.
If a program line contains a syntax error, BASIC overrides the %NOLIST directive for that line and
produces the normal error diagnostics in the listing file.

10.1.5 %CROSS and %NOCROSS
%NOCROSS causes BASIC to stop adding cross-reference information to the output listing file while
%CROSS causes BASIC to resume adding cross-reference information. Thus you can specify that only
certain parts of the source program are to be cross-referenced. The format of %CROSS is:

%CROSS
The format of %NOCROSS is:

%NOCROSS
For example:
10

lTITlE 'Payroll Pro~raM'
'X.PAGE
lS5TTl 'Constant Declarations'
! •
!•
! •

February 1984

(continued on next page)

Compiler Directives

10-5

l'.NOCROSS

100

!•
!•
I

! •

1800

X.CROSS
!•
!•
!+

2000

IPAGE
'XSBTTL 'Subroutines'
! •
!•
!•

18000

IPAGE
ISBTTL 'Error Handler'
!•
!•
!•

The %NOCROSS directive in line 100 causes BASIC to stop adding new cross-reference information
to the listing file. The %CROSS directive in line 1900 causes BASIC to resume adding this information. Thus, BASIC produces no listing information for lines 100 to 1900, inclusive.
Note
If you have not requested the creation of a cross-reference listing, the %CROSS and
%NOCROSS directives have no effect.

10.2 Accessing External Source Files (%INCLUDE)
The %INCLUDE directive lets you copy BASIC source text from a file into the source program. On
VAX/VMS systems, %INCLUDE also lets you access record definitions in the VAX-11 Common Data
Dictionary (COD). The line on which a %INCLUDE resides can be continued but cannot contain any
other directives or statements. The format of %INCLUDE is:
%INCLUDE

( file-spec

)

l %FROM O/oCDD cdd-path-spec f

where:
file-spec

Is any valid file specification. BASIC uses the default device and directory if you
do not supply these parts of the file specification. If you do not supply a file type,
the default is BAS in VAX-11 BASIC and B2S in BASIC-PLUS-2.

cdd-path-spec

Is valid only in VAX-11 BASIC and specifies a VAX-11 COD path specification.
This lets you extract a RECORD definition from the COD. See the BASIC on
VAX/VMS Systems manual and the VAX-IT Common Data Dictionary Utilities
Reference Manual for more information.

File specifications and COD path specifications must be string literals enclosed in quotes.
The source files accessed with %INCLUDE cannot contain line numbers. Also, each line in the file
must begin with a space or a tab. These requirements mean that all statements in the accessed file are
associated with the BASIC line containing the %INCLUDE directive. Thus, a %INCLUDE directive
cannot appear before the first line number in a source program. A file accessed by %INCLUDE can
itself contain a %INCLUDE directive.

10-6

Compiler Directives

%INCLUDE is useful when you want to share code among multiple program modules. When you
insert code into a file and then include the file in all the modules that require it, you reduce the
chance of a typographical error. For example, this code might be contained in a file named
SHRVAL. BAS:

COMMON (SHARED) LONG FLAG_ARRAY(100) t
BYTE BYTE_ARRAY( 10) t
STRING ERR_MSGt
SUCCESS_MSG

&
&:

Each program module that requires this common area can access it with the %INCLUDE directive:
Main Program

1000

%INCLUDE 'SHRVAL.BAS'

Subprogram

2000

%INCLUDE 'SHRVAL.BAS'

When these programs are compiled; BASIC places the text from SHRVAL.BAS into each source
program at the point of the %INCLUDE directive. The compilation listing identifies any text obtained
from an included file by placing a mnemonic in the first character position of the line in which the
text appears. The mnemonic is of the form:
In
where:
Tells you that the text was accessed with a %INCLUDE directive.
n

Tells you the nesting level of the included text.

You can prevent the %INCLUDE file code from appearing in the compilation listing by preceding the
%INCLUDE directive with a %NOLIST directive.

10.3 Controlling Compilation
BASIC lets you control the compilation of a program by creating and testing lexical constants. You
create and assign values to lexical constants with the %LET directive. These constants are always
integers, LONG integers in VAX-ll BASIC and WORD integers in PDP-ll BASIC-PLUS-2.
You control the compilation by using the %IF-% THEN-%ELSE-%END-%IF directive to test these
lexical constants. Thus, you can conditionally:
• Supply different values for program variables and constants
• Skip over part of a program
• Abort a compilation
• Include BASIC source code from another file
BASIC also supplies the lexical built-in function %VARIANT, which can be used to conditionally
control compilation. See Section 10.3.2.

Compiler Directives

10-7

%IF-% THEN-%ELSE-%END-%IF uses lexical expressions to determine whether to execute directives in the %THEN clause or the %ELSE clause. The following sections describe the use of:
• Lexical constants and expressions (% LET)
• %ABORT
• %VARIANT
• %IF-% THEN-%ELSE-%END-%IF

10.3.1 Lexical Constants and Expressions (%LET)
The %LET directive creates and assigns values to lexical constants. Lexical constants are always
integers, LONG integers in VAX-ll BASIC, and WORD integers in PDP-ll BASIC-PLUS-2. These
constants control the execution of the %IF-% THEN-%ELSE-%END-%IF directive. Lexical constants
must be created with %LET before they can be used in a %IF-% THEN-%ELSE-%END-%IF, and each
lexical constant must be created with a separate %LET directive. The format of %LET is:
%LET %Iex-const-nam = lex-exp
where:
%Iex-const-nam

Is the name of a lexical constant. Lexical constant names must be preceded by
a percent sign and cannot end with a dollar sign or percent sign. Each lexical
constant must be declared with its own %LET directive, and a %LET directive
can name only one lexical constant.

lex-exp

Is a lexical expression.

A lexical expression can be:
• A lexical constant
• An integer literal
• A lexical built-in function (%VARIANT)
• Any combination of these, separated by logical, relational, or arithmetic operators
The %LET directive lets you create constants that control conditional compilation. For example:
100

%LET %DEBUG_ON = 0%

See Section 10.3.4 for an example of using %LET with %IF-% THEN-%ELSE.

10.3.2 %VARIANT
% VARIANT is a built-in lexical function that returns an integer. The value of this returned integer is
determined by:
• The SET VARIANT command when compiling in the BASIC environment
• The IVARIANT qualifier when compiling from the system command level (VAX-l1 BASIC only)

10-8

Compiler Directives

The %VARIANT function returns the variant value set with either of these methods. Its format is:
%VARIANT
The default value for the %VARIANT function is zero. See Section 10.3.4 for an example of controlling compilation with %VARIANT.

10.3.3 %ABORT
The %ABORT directive terminates the compilation and displays a message you provide. Its format is:
%ABORT text
where:
text

Is a quoted string literaL

The text is displayed on the terminal screen and in the compilation listing if one is being created.
Note that BASIC stops the compilation and terminates the listing file as soon as it encounters a
%ABORT directive. This means that BASIC does not perform syntax checking on the remainder of the
program. See the following section for an example of using %ABORT.

The %IF-% THEN-%ELSE-%END-%IF directive lets you conditionally: 1) place text in a source
program or 2) execute another compiler directive. Its format is:
%IF lex-exp %THEN source-code [%ELSE source-code] %END %IF
where:
lex-exp

Is a lexical expression.

source-code

Is BASIC source text. Note that compiler directives are also BASIC source code.

This diiective differs from all others in that it can appear anywhere in a program where a space is
allowed, except in column one or within a quoted string.
You must include %END %IF. Otherwise, the rest of the source program becomes part of the %THEN
or %ELSE clause.
The truth or falsity of the lexical expression determines whether BASIC compiles the source code in
the -% THEN clause or the %ELSE clause. If the lexical expression is true, BASIC neither compiles nor
checks the syntax of source code in the %ELSE clause. If the lexical expression is false, BASIC neither
compiles nor checks the syntax of source code in the %THEN clause.
The following example also uses the %VARIANT directive, which returns the value set by the SET
VARIANT command or /VARIANT qualifier.

100

%IF (%VARIANT = 2%) %THEN DECLARE LONG INT_ARRAY(100)
%ELSE DECLARE WORD INT_ARRAY(100)
X.END %IF

This directive allows for two possibilities: If you compile this program with a/VARIANT = 2 qualifier,
then BASIC creates an array of longword integers. If you compile this program with any other variant
value, BASIC creates an array of word integers.

Compiler Directives

10-9

Because %IF can appear within a program line, you can express the same directive this way:
10 DECLARE %IF (%VARIANT=2%) %THEN LONG %ELSE WORD %END %IF INT_ARRAY(10)
A %THEN or %ELSE clause can also contain another compiler directive. For example:
100

%LET %MY_Constant = 8%
_ %IF ( (%MY_Constant + %VARIANT) >= 10% )
%THEN lABORT 'Cannot cOMPile with VARIANT >= 2'
XEND i.'. I F

This example creates the lexical constant %my_constant and assigns it a value of eight. The %IF
directive evaluates the conditional expression (%my_constant + %VARIANT) = > 10%. If this
expression is true, BASIC executes the %THEN clause, aborting the compilation and issuing an
error message. If false, the compilation continues.
The compilation listing shows you which clause was actually compiled.

10-10

Compiler Directives

Chapter 11
Handling Run-Time Errors

This chapter describes how to handle run-time errors.

11.1 Errors
If an error occurs when your program is running (at "run-time"), BASIC provides two ways to help
you correct or circumvent the condition causing the error.
• BASIC error handling: BASIC diagnoses the error and displays a message telling the nature and
severity of the error, and the program line and module that caused it. This information lets you
correct whatever caused the error before you try running the program again .
• User error handling: For most errors, BASIC lets you handle the error in your own routine. This error
routine can test the error condition and take appropriate action.
There are three general error categories: 1) informational or warning errors, 2) trappable errors, and 3)
fatal errors.
The severity of an error determines whether or not the program aborts when the error occurs. Informational and warning errors let the program keep running; fatal errors always terminate program
execution. Trappable errors can have either result, depending on the error handler in effect: the
BASIC error handler terminates program execution, but a user-written error handler may let your
program keep running.
.

11.2 Error Handlers
An error handler is a block of code that receives program control in the event of an error or unexpected event. If you do not supply an error handler, the BASIC error handler usually gets program
control when an error occurs (there are some types of errors that are handled only by the operating
system).
Depending on the severity of the error, the BASIC error handler either: 1) reexecutes the statement in
which the error occurred, 2) issues a warning and continues execution, or 3) terminates the program.

11-1

In a BASIC program, there are many possible levels of error handling. These software components
and program modules can each have an error handler:
• Mainline code
• User-written subprograms or external functions
• User-defined functions (DEFs)
• The BASIC system
You can supply your own error handler for each of the first three components. The BASIC error
handler is the default if you do not supply one. When an error occurs, BASIC stops executing the
program and transfers control to the BASIC error handler. If your program includes a user-written
error handler, and the error is trappable, the BASIC error handler transfers control to the user error
handler. If your program does not include a user error handler, or the error is a nontrappable or fatal
error, the BASIC error handler retains control.
Any program module can contain one or more user-written error handlers. A user-written error
handler normally performs these functions:
• Determines the BASIC error number associated with the error
• Determines the program module in which the error was detected
• Determines the program line in which the error was detected
• Takes appropriate action based on the above information
• Clears the error condition and resumes program execution
In BASIC, only one error can be handled at a time. If an error is pending and a second error occurs,
program execution always terminates immediately. Therefore, one of the most important functions of
a user-written error handier is to dear the error condition so that subsequent errors can also be
handled.

11.3 User-Written Error Handlers
The only way to prevent a trappable error from aborting your program is to provide a user error
handler. When an error occurs during the execution of a program for which you have written an error
handler, BASIC branches to your error-handling routine, which processes the error. After processing
the error, the error handler can:
• Resume execution at a specified line (RESUME with line number)
• Resume execution at the point where the error was detected (RESUME with no line number)
• Pass the error to the BASIC error handler (ON ERROR GOTO 0)
• Pass the error to the calling program (ON ERROR GO BACK)
You can provide error handlers in your main program, subprogram (SUB or FUNCTION), or userwritten function (DEF).

11-2

Handling Run-Time Errors

11.3.1 Transferring Control to an Error Handler (ON ERROR Statement)
If no error has occurred, the ON ERROR statement specifies the branch to be taken in the event of an
error. If an error has occurred, the ON ERROR statement immediately transfers control to the specified eiiOi handler. O!'-~ ERROR has the fo!!o\ving formats:
ON ERROR GOTO

1llabel
~ne-number }

or
ON ERROR GO BACK

Note that, if an error has occurred and has not been handled, the ON ERROR statement immediately
transfers control to the specified line number or label, or to the BASIC error handler,
ON ERROR GOTO 0 specifies that the BASIC error handler receives control when an error occurs.
ON ERROR GOTO line number or label specifies that the block of code at the target line number or
label is to get control when an error occurs. ON ERROR GO BACK is normally executed in subprograms or DEFs and specifies that the error handler in the calling program receives control when an
error occurs. If you use ON ERROR GO BACK in a main program (outside of a DEF), it is equivalent
to ON ERROR GOTO O.
Customarily, the ON ERROR GOTO statement occurs before any other executable statements, and
the error handling routines usually start at line 19000. For example:
5 ON ERROR GOTO 19000

When your program generates an error, control transfers to the specified line. If your error handler
routine generates a second error, control returns to BASIC error handling and program execution
ends, usually with the first error only partly processed. To avoid the possibility of your error handler
causing a second error, make it as simple as possible.
The ON ERROR GOTO statement remains in effect after your program successfully handles an error.
Vv'hen the system signals another error, control once again transfers to the specified line.
Your routine can use conditional expressions to test the error and branch accordingly. For example:
5

ON ERROR GOTO 19000
!•
!•
! •

19000

SELECT ERR
CASE 181
PRINT "Record too long"
RESUME 850
CASE 11
PRINT "End of file"
RESUME 32000
CASE ELSE
ON ERROR GOTO 0
END SELECT

32000
32787

CLOSE *" 1'1.,
END

Handling Run-Time Errors

11-3

This routine tests for two errors: 1) records longer than the buffer length and 2) end of file.
For some conditions that generate errors, for example, "End of File", you can keep the program from
aborting by writing a user error handler that traps the error. That is, the routine provides BASIC
statements that deal with the error and then instructs BASIC to resume execution at a certain program
line. For "End of File" you can display a message indicating that the task is finished and then transfer
control to the EN D statement.
It is good programming practice to anticipate certain errors and provide error handlers for them. Your
error handler can first test whether or not the error is the one you expect and then execute the
appropriate BASIC statements.
Two common errors you can trap with error handlers are "Division by 0" and "Data format error". If
your program is reading data from a file when one of these errors occurs, you can have it print an
error message and skip to the next item; if the program is reading data the user types in, you can
display a "Try again" message and reexecute the program lines requesting input.
Normally, you cannot trap fatal errors in an error handler, nor can you trap errors occurring in
non-BASIC modules. However, in BASIC-PLUS-2 you can trap certain errors (for example, CTRL/C
interrupts) occurring in a MACRO-11 subprogram. See BASIC on RSTSIE Systems and BASIC on
RSX-l1 M I M-PLUS Systems for more information about MACRO-11 subprograms.

11.3.2 Determining the Error Number (ERR)
The ERR function returns the number of the last error that occurred. Accessing the ERR function is a
valid operation only inside an error handler. For example:

19000
19010

PRINT IIERROR NUMBER II;ERR
SELECT ERR
CASE 153
PRINT IIChoose new record
RESUME a20
CASE ELSE
ON ERROR GO BACK
END SELECT

This routine transfers control to line 420 when the program generates error 153, "Record already
exists". Line 19000 prints the value of ERR each time BASIC traps an error. See Appendix B for the
number of each BASIC run-time error.
The results of ERR remain undefined until an error occurs. Although ERR remains defined as the
number of the last error after control leaves the error handler, it is poor programming practice to refer
to this variable outside the scope of an error handler because it can be changed at any time by an
asynchronous error.

11.3.3 Determining the Error Line Number (ERL)
After your program generates an error, the ERL function returns the line number of the signaled error.
The ERL func;tion, like ERR, lets you set up branching to one of several routines. For example:

ON ERROR GOTO 18000
DECLARE INTEGER CONSTANT TRUE
!•
!•
!•

11-4

Handling Run-Time Errors

-1

19000

32000
32767

SELECT TRUE
CASE (ERR = 11) AND (ERL = 790)
!Is error end-of file at line 790?
PRINT "CoMPleted"
RESUME 32000
CASE (ERR = 149) AND (ERL = 80)
!Is error not-at-end-of-file on line 80?
PRINT "CHECK ACCESS MODE"
RESUME 32000
CASE ELSE
!Let BASIC handle any other errors
ON ERROR GOTO 0
END SELECT
CLOSE #5
END

Thic
rr" ,tina no...tAr ........ c throo toctc·
I I I I J (VULt. 1'-- p ' - I I V I I I I J LIII\.....'-' L\.......:Jl.J.

If the error is "End of file" (ERR = 11), it closes the file and exits.

If the error is "Not at end of file" (ERR = 149), it returns control to line 50.

If the error is anything else, it passes control to the BASIC error handler.

The results of ERL are undefined: 1) until an error occurs and 2) if the error occurred in a subprogram
not written in BASIC. Although ERL remains defined as the line number of the last error after control
leaves the error handler, it is poor programming practice to refer to this variable outside the scope of
an error handler.
Also, if your program references ERL and you compile the program with the INOLINE switch, BASIC
signals "ERL overrides INOLlNE," and the compilation continues.
If an error occurs in a subprogram, BASIC sets the ERL variable to the subprogram line number where
the error was detected. Thus, if the subprogram executes an ON ERROR GO BACK statement, the
error handler in the calling program cannot execute a RESUME without specifying a line number
because you cannot resume execution at a line outside the current program module. Instead, the
program should resume execution at the line containing the CALL to the subprogram. For example:
Main Program

1 ON ERROR GOTO 19000
!+
!+
!+

5000

CALL SUBl
!+
!+
!+

19000

IF (ERN$ = SUB1) AND (ERR
THEN
SLEEP 5
RESUME 5000
ELSE
ON ERROR GOTO (I
END IF

138) !Is file locKed?

This error handler checks for a locked file condition. If the error number is 138, the error handler
waits 5 seconds and then resumes execution. The RESUME transfers control to the line 5000, which
calls SUB1 again.

Handling Run-Time Errors

11-5

11.3.4 Determining Where the Error Occurred (ERN$)

The ERN$ function returns the name of the program unit in which the error was detected. In
BASIC-PLUS-2, ERN$ returns the name of a main program or subprogram, whereas, in VAX-11
BASIC, ERN$ returns the name of a main program, subprogram, or DEF function. The results of ERN$
are undefined until the program generates an error. For example:

18000

IF ERN$

= "SUBARC" THEN PRINT "ERROR IS ";ERR

PRINT "RETURNING TO MAIN PROGRAM FOR ERROR HANDLING"
ON ERROR GO BACK
PRINT "PROGRAM MODULE GENERATING ERROR IS ";ERN$
18010
IF ERR = 153% THEN RESUME 32000
18020
ELSE ON ERROR GO TO 0
32000 CLOSE #2'X.
32767 END
In this example:
1.

Control passes to the main program for error handling if the error occurs in the module
SUBARC.

Execution resumes at line 32000 if the error is number 153, I/?Record already exists".

Control passes to BASIC error handling for all other errors.

11.3.5 Determining the Error Message Text (ERT$)
The ERT$ function returns the message text associated with a specified error number. For example:

18000

IF ERN$ = "TSLFE"
THEN PRINT ERT$(ERR)
RESUME

This statement tests whether the error occured in a DEF module named TSLFE, and if so, prints the
text of the signaled error and resumes execution. Note that if an error occurs in a DEF, a RESUME
with no line number causes execution to resume at the statement that invoked the function. Use of
the ERT$ function is not limited to the scope of the error handler; you can access ERT$ at any time.

11.4 Returning to BASIC Error Handling
The ON ERROR GOTO 0 statement disables program error trapping and returns control to BASIC
error handling. The BASIC error handler displays error messages, stops program execution, and prints
a fatal error message.
ON ERROR GOTO 0 returns control to BASIC error handling in one of two ways:
• If an error is pending, execution of the ON ERROR GOTO 0 statement returns control to BASIC
error handling immediately .
• If no error is pending, an ON ERROR GOTO 0 statement disables your error handler. The BASIC
error handler handles all subsequent errors until another ON ERROR statement is executed.

11--6

Handling Run-Time Errors

February 1984

For example:
ON ERROR GOTO 19000
OPEN 'FILE.LIS' FOR INPUT AS FILE #21
30
LINPUT #2It A$
40
PRINT A$
50
GOTO 30
19000 IF (ERR = III) AND (ERL
30I)
THEN
RESUME 32000
ELSE
ON ERROR GOTO 0
END IF
32000 CLOSE #21
32767 END
10
20

In this program, iine 10 estabiishes the error routine. Lines 30, 40, and 50 retrieve and print iines.
When an error occurs, BASIC transfers control to line 19000. If the error is end-of-file, the error
handler resumes to line 32000, which closes the file. If any other error occurs, the ELSE clause
transfers control to the BASIC error handler, which prints information about the error.
You can use a mix of ON ERROR GOTO and ON ERROR GOTO 0 statements to turn your program's
error handler on and off. In this way, your program can handle certain errors, and BASIC can handle
the rest.

11.5 Leaving an Error Handler
The RESUME statement clears the error condition and returns control to the specified line number or
to the program block in which the error occurred. An error handler must end with a RESUME or an
ON ERROR GOTO 0 or ON ERROR GO BACK statement. If it does not, the BASIC error handler
aborts your program with the fatal error "Error trap needs RESUME" as soon as an END, END SUB,
END DEF, or END FUNCTION is encountered. In this example, all paths out of the error handler are
through either an ON ERROR or RESUME statement:
19000

IF (ERR = III) AND (ERL = 301)
THEN

CLOSE #21
RESUME 32767
ELSE
32000
32767

ON ERROR GOTO 0
END IF
CLOSE #2'X.
END

You can resume execution at any line number that i-s in the same module as the RESUME statement,
unless that line is inside a DEF. Note that the RESUME statement does not accept a label as an
argument. Therefore, you should number lines that receive control from the error handler.
In general, RESUME without a line number transfers control to the beginning of the program block
where the error occurred. A program block can begin with either a line number or a label. Thus, if
you resume execution at a multi-statement line, execution begins at the the first statement after the
line number or label - not necessarily at the statement that generated the error.

February 1984

Handling Run-Time Errors

11-7

However, if an entire loop block is associated with a single line number or label and an error occurs
within the loop, RESUME with no line number transfers control to the statement immediately after the
FOR, WHILE, or UNTIL statement, not to the line number or label. For example:
1

100

18000

ON ERROR GO TO 18000
FOR 1% = 1% TO 10%
PRINT IIPlease type a nUlTlber"
INPUT A
NEXT 1%
IF (ERR = 50)
THEN
RESUME
ELSE
ON ERROR GOTO 0
END IF

In this example, if 'ABC' is typed in response to the INPUT prompt, control is transferred to line
19000, which traps error number 50 and executes a RESUME statement with no line number. The
RESUME statement transfers control to the first statement following the FOR statement. In the case of
a FOR loop, the loop control variables (the starting, ending, and STEP values) are not reinitialized
when the loop resumes execution. Similarly, if an entire WHILE or UNTIL loop is associated with a
single line number, RESUME with no line number transfers control to the first statement following a
WHILE or UNTIL statement.
If a SELECT block is associated with a single line number or label and an error occurs within the
SELECT block, RESUME with no line number transfers control to the start of the CASE block in which
the error occurred. For example:

10
100

ON ERROR GOTO 18000
INPUT IIWhich paraMeter do YOU ""Iant to change"; PARM'X.
SELECT PARM%
CASE = 1
PRINT "What is the new paraMeter lJallJe
INPUT PARM_l
CASE = 2
PRINT IIWhat is the new parafTleter l)alue"
INPUT PARM_2
END SELECT
GOTO 32787
IF (ERR = 50)
THEN
RESUME
ELSE
ON ERROR GOTO 0
END IF
END
li

200
18000

32787

In this example, if 'ABC' is typed in response to one of the INPUT prompts within the SELECT block,
control is transferred to line 19000. The error handler traps error number 50 and executes a RESUME
statement with no line number. The RESUME statement transfers control to the first statement in the
CASE block in which the error occurred.

Finally, if an error occurs after a loop or SELECT block in a multi-statement line, RESUME without a
line number transfers control to the next statement after the NEXT or END SELECT statement.

11-8

Handling Run-Time Errors

February 1984

If you use RESUME without a line number, you must take care to supply a separate line number for
every statement that may generate an error. This is especially important for loop and SELECT blocks.
If you number every statement in the loop or SELECT block, you can be sure RESUME with no line
number transfers control to the statement that caused the error.
If you use INOLINE to compile a program containing a RESUME without a line number, you receive
the warning message, "RESUME overrides I NOLlNE".
If you use GOTO from an error handler, you leave the error condition pending and the next error
aborts the program. To prevent this, use a RESUME, an ON ERROR GO BACK, or an ON ERROR
GOTO 0 statement instead of GOTO.
Similarly, even though the line at which you want to resume program execution directly follows the
error handler in the program, you cannot "fall through" the error handler to a END SUB, END DEF,
END FUNCTION, or END statement. For example, these error handlers are invalid:
18000

32767
18000

32767

IF (ERR = 11%) AND (ERL = 550%)
THEN
PRINT "WRITING COMPLETE"
CLOSE #5X.
PRINT "FILE CLOSED"
PRINT "RETURNING TO MAIN PROGRAM"
END IF
END SUB
IF (ERR = 132%)
THEN
AX. = A% + lX.
GET #2%. RECORD A%
PRINT NA.ME.CODE$, ACTION.CATE%
ELSE
PRINT "NEXT RECORD INVALID"
END IF
END

February 1984

Handling Run-Time Errors

11-9

I
_

These error handlers are invalid because they pass control to the END SUB or END statements
without handling the error (that is, without resuming to a line number or returning to system error
handling). In both cases, the error condition is still pending as the module ends.
You must also make sure that your error handler does not return control without correcting or
removing the condition that caused the error. Othervvise, the program generates the error and handles
it unsuccessfully over and over. For example:
5

ON ERROR GOTO 18000
!•
!•
!•

340

18000

18010

FIND #12%t KEY #3% EO TARGET.NAME$

IF (ERR
THEN

! •
!•
!•
= 153X.)

PRINT "NAME INVALID"
END IF
RESUME 340
!•
!•
!•

32787

END

This program searches again and again for the record with a field equal to the variable
TARGET.NAME$. Each time, the error handler returns control to the statement that generated the
error. The error handler must: 1) handle the error in the routine or 2) return control to another
program line. For example:
5

ON ERROR GO TO 18000
!•
!•
! •

330
340

18000
18010

INPUT "WHAT RECORD DO YOU WANT"; TARGET.NAME$
FIND #12~t KEY #3% EO TARGET.NAME$
!•
! •
! •
= 1531)

IF (ERR
RESUME 330

THEN PRINT "NAME INVALID"

! •
!•
!•

32787

END

This program searches for a target name, notes when the name is not in the file, and returns control to
line 330 to prompt for a new name.
Note
In VAX-ll BASIC, a RESUME statement that branches to the end of the program
always returns a STATUS of success to command level - even if your handler did not
trap the error successfully. In some cases, (for example, controlling events in a batch
stream), this is not desirable. If the error handler must return the true error handling
STATUS, end the handler with ON ERROR GOTO 0 or ON ERROR GO BACK.

11-10

Handling Run-Time Errors

11.6 Handling Errors in Subprograms and Function Definitions
You can write error handlers for subprograms and function definitions (both FUNCTION subprograms
and DEFfunction definitions) just as you do for main programs. In these error handlers, the ON
ERROR GOTO and ON ERROR GOTO 0 statements behave just as they do in main programs. in
addition, the ON ERROR GO BACK statement lets you transfer control to the calling program's error
handler if an error occurs in the subprogram or DEF. For example:
10
20
30
40
50
GO
18000

32000
32787

SUB LIST(A$)
ON ERROR GO TO 18000
OPEN A$ FOR INPUT AS FILE #12%
LINPUT #127.. t B$
PRINT B$
GO TO 40
IF (ERR = 117..) AND (ERL
407.. ) ! END OF FILE
THEN
RESUME 32000
ELSE
ON ERROR GO BACK
END IF
CLOSE #127..
END SUB

Note
Although you can CALL a subprogram while an error is pending, if you do, the
subprogram cannot execute an ON ERROR GO BACK or an ON ERROR GOTO 0
statement. If the subprogram tries to execute one of these statements, BASIC signals
"Improper error handling" and program execution terminates.

The default error handler for functions is ON ERROR GO BACK. This means that, if an error occurs in
the execution of the function, the error is passed to either: 1) the error handler of the surrounding
program module (in the case of a DEF function definition) or 2) the error handler of the calling
program (in the case of a separately compiled subprogram). In either case, you can use the ON
ERROR GOTO statement to set up an explicit error handler for the function. The subprogram can
have an error handler similar to:
18000

IF ERR = 11
THEN
RESUME 1000
ELSE
ON ERROR GO BACK
END IF

In this subprogram, the user error routine handles end-of-file conditions. Control passes to the main
program for all other errors.
When your program executes an ON ERROR GO BACK, BASIC returns to the BASIC error handler or
to another user error handler depending on the location of the ON ERROR GO BACK. Figure 11-1
shows three sets of error handling conditions.

Handling Run-Time Errors

11-11

Figure 11-1: Error Handling Conditions
MAIN MODULE
BASIC
HANDLING

ON ERROR GOTO
0

SUB1

SUB3

SUB2

ON ERROR
GO BACK

ON ERROR
GO TO 0

SUB11

I
SUB121

SUB31

SUB21

SUB12
ON ERROR
GO BACK

ON ERROR
GO BACK

SUB122

SUB311

ON ERROR
GO BACK

SUB32

SUB33
ERROR TRAPPED
AND
PROCESSED

I
SUB312

SUB331
ON ERROR
GO BACK

SB3311
ON ERROR
GO BACK

MK-00893-00

The first error occurs in module SUB122. That module has an ON ERROR GO BACK in effect, so
control returns to the calling module, SUB12. This module also has ON ERROR GO BACK in effect,
so control returns to its calling module, SUB1. SUB1 also has an ON ERROR GO BACK that returns
control to the main module, which contains an ON ERROR GOTO o. At this point, the BASIC error
handler operates and, if the error is fatal, stops the program. The error message identifies SUB122 as
the error location. The traceback shows that control was in the main module when it found an ON
ERROR GOTO O.
The second error occurs in module SUB311. That module has an ON ERROR GO BACK in effect, so
control returns to the calling module, SUB31. SUB31 also has an ON ERROR GO BACK, so control
returns to its calling module, SUB3. SUB3 contains an ON ERROR GOTO 0, and the BASIC error
handler comes into play. The error message identifies SUB311 as the location of the error, and the
traceback shows the main module called SUB3. BASIC executed no statements in the main module.
The third error occurs in SB3311. SB3311 contains an ON ERROR GO BACK. BASIC returns to
SUB331, which also contains an ON ERROR GO BACK. This returns control to SUB33. SUB33
contains an error trap for this error and successfully processes it. The program can continue execution. The execution continues in SUB33, where the error was processed, and not in SUB331 or
SB3311.

11-12

Handling Run-Time Errors

For error handling in function definitions, these rules apply:

An error handler outside the definition cannot return control to a line inside the DEF.

To trap errors while the DEF is active, include error handiers inside the OEF. They remain in
effect until your program leaves the DEF.

An error handler in the DEF does not permanently override an error handler in the main
program. BASIC saves the error handler in the main program when you transfer into a DEF,
and restores it when you return.
.

For example:

ON ERROR GoTo 19000
!•
!•
!•

1000

AX.
! •
!•
!•

15000
15010
15020
15090

DEF FNIN_PUT%(P%)
ON ERROR GoTo 15090
PRINT P$
INPUT LINE_IN$
FNIN_PUT% = VAL%(LINE_IN$)
FNE}{ IT
IF ERL = 15010
THEN
PRINT "RETRY"
RESUME 15010
ELSE
ON ERROR GO BACK
! •
!•
!•

18000
18000

32787

END DEF
PR I NT "ERROR"; ERT$ ( ERR) ;
IF ERN$ = "FNIN_PUT" THEN
PRINT "IN FUNCTION"
RESUME 1200
ELSE PRINT "IN MAIN"
RESUME 1000
END

11.7 CTRL/C Trapping
With control C trapping enabled, control is transferred to an error handler when you type "c
(CTRL/C) during program execution. You enable CTRL/C trapping in your program by invoking the
CTRLC function. For example:

5
10

ON ERROR GoTo 19000
Y% = CTRLC

After invoking CTRLC, all CTRL IC errors transfer control to the error handler.

Handling Run-Time Errors

11-13

After trapping the error, you can then include routines to interact with the program. For example:
5
10

480
470
480
480
500
510

18000

18010
18020

ON ERROR GOT!) 18000
Y'Y..
CTRLC
!+
!+
:I +
OPEN 'FIL+DAT' FOR INPUT AS FILE #1%
I NPUT "HOW MANY RECORDS"; REC +READ'Y..
FOR I% = 1% TO REC+READ%
GET #1%
PRINT NA+ME$t ADDRE+SS$t EMP+CODE%
PRINT
NE}-{T I'Y..

IF (ERR

!+
!+
! +
= 28'%)

THEN
Y'Y.. = CTRLC
PR I NT "CURRENT RECORD IS"; I 'Y.
ELSE ON ERROR GOTO 0
INPUT "DO YOU WISH TO END PROCESSING"; ANSWER$
IF ANSWER$ = "YES"
THEN RESUME 32000
ELSE RESUME
!+
!+
!+

32000
32788
32787

CLOSE # 1 'Y.
PRINT "END OF PROCESSING"
END

RUN
SMITHt DEXTER 231 COLUMBUS ST

08341

TRAVISt JOHN

84118

PO BOX 80

THE CURRENT RECORD IS 3
DO YOU WISH TO END PROCESSING? YES
Note that the error condition is still pending until the error handler executes the RESUME statement.
Therefore, if you type a second CTRL/C while the error handler is executing, control returns to the
BASIC error handler, which terminates the program.
RESUME with no line number returns control to the line where the error occurred. Your program can
then re-execute statements interrupted by the CTRL/C. In contrast, RESUME with a specified line
number can generate unpredictable results. For example, in this program, a CTRL/C at line 550 can
leave the value of STRINGA$ partially changed. Because control resumes at line 560, this value
remains unpredictable:
550
580

STRINGA$ = "ABC"
PRINT #2%t STRINGA$
!+
! +
!t

18000
18010

PRINT "BUFFER POSITION IS ";CCPOS(2·X.)
RESUME 580

11-14

Handling Run-Time Errors

To disable control IC trapping, use the RCTRLC function. For example:
800

YI = CTRLC
! •
!•
!•

1200

RCTRLC
!•
!•
!•

18000

18010
18020

32000

IF (ERR = 281.)
THEN
PR I NT "CURRENT RECORD IS"; I %
Yi.. = CTRLC
ELSE
ON ERROR GOTO 0
END IF
INPUT "DO YOU WISH TO END PROCESSING"; ANSWER$
IF ANSWER$ = "YES"
THEN
RESUME 32000
ELSE RESUME
END IF
CLOSE # 1·y'.

Note that the RCTRLC function only disables CTRL IC trapping, not the CTRL IC interrupts
themselves.

11.8 The BASIC Error Handler
If a program that you compile, link, and run generates an error and has no routine to process it,
BASIC handles the error. For most errors:
1.

Execution halts.

The exit handler closes all files.

BASIC prints a message describing the nature of the error and optional system traceback
information.

Control returns to monitor levei.

Figure 11-2 shows the error messages and traceback generated by a VAX-11 BASIC program that has
been compiled, linked, and run.

Figure 11-2: VAX-11 BASIC Error Handling Output
100
200
400
500
32787

GOSUB 400
GOTO 32787
Ai.. = A%/Bi..
RETURN
END

$ RUN NONAME
XBAS-F-DIVBY_ZERt Division by 0
-BAS-I-USEPC_PSLt at user PC=00000438t PSL=03C00028
-BAS-I-FROLINGSBt froM line 400 in GOSUB 400 in Module NONAME
-BAS-I-FROLINMODt froM line 100 in Module NONAME
-SYSTEM-F-INTDIVt arithMetic traPt inte~er divide by zero at
PC=00004833t PSL=03COOOOO
XTRACE-F-TRACEBACKt SYMbolic stack. dUMP follo . . ls

(continued on next page)

Handling Run-Time Errors

11-15

lin e

Module naMe routine naMe

NONAME

aoo

NONAME$MAIN

relative PC

absolute PC

ooooa933

8000001a

00000025

oooooa25

Figure 11-3 shows the error messages and traceback generated by a VAX-11 BASIC program that has
been compiled, linked, and run.
Figure 11-3: BASIC-PLUS-2 Error Handling Output
GOSUB aoo
100
GOTO 32767
200
AI = AX./BI
aoo
RETURN
500
END
32767
$ RUN NONAME
IDivision by 0 at line

aoo

in "NONAME"

If a program you run in the BASIC environment generates an error and includes no routine to process
it, BASIC handles the error by performing these slightly different steps:
1.

Execution halts.

The exit handler closes all files and disconnects all devices.

BASIC prints a message describing the nature of the error.

Control returns to BASiC, which displays its prompt.

Figure 11-4 shows the error messages generated by a program run in the BASIC environment on
VAX/VMS systems.
Figure 11-4: VAX-11 BASIC Environment Error Handling Output
100 GOSUB aoo
200 GOTO 32767
aoo AX. = AI I BI
500 RETURN
32767 END
RUN
NONAME
3-APR-1981 11:03
IBAS-F-DIVBY_ZER, Division by 0
-BAS-I-USEPC_PSL, at user PC=00116506, PSL=03C00026
-BAS-I-FROLINGSB, froM line aoo in GOSUB aoo in Module NONAME
-BAS-I-FROLINMOD, froM line 100 in Module NONAME
-SYSTEM-F-INTDIV, arithMetic trap, inte~er divide by zero at
PC=0009017E, PSL=03COOOOO
Ready

Figure 11-5 shows the error messages generated by a program run in the BASIC environment on
PDP-11 systems.

11-16

Handling Run-Time Errors

Figure 11-5: BASIC-PLUS-2 Environment Error Handling Output
100
200
400
500

GOSUB 400
GOTO 32767
Ai..

= Ai..fBi..

RETURN
END

32767
RUNNH
%Division by 0 at line

400 in "NONAME"

11.9 Handling Non-BASIC Errors
A user-written BASIC error handler cannot trap errors occurring in a non-BASIC subprogram. If a
non-BASIC error reaches a BASIC main program, then the BASIC error handler terminates the programo However; if the main program is written in VAX-ll MACRO or VAX-ll BLISS, then a userwritten error handler in the main program can get control and handle the error.
For example, suppose you have a VAX-ll MACRO main program that calls a BASIC subprogram that
then calls a VAX-ll FORTRAN subprogram. Further, all error handling is done in the VAX-ll
MACRO main program. An error in the VAX-ll FORTRAN subprogram is signaled to the BASIC
subprogram. Because the BASIC subprogram cannot handle non-BASIC errors, it resignals the error
to the VAX-ll MACRO main program. To handle the error without terminating the program, the
VAX-ll MACRO main program must have a user-written error handler. See the Guide to Creating
Modular Library Procedures Manual for more information.

Handling Run-Time Errors

11-17

Appendix A
Reserved BASiC Keywords

%ABORT
%CDD
%CROSS
%ELSE
%END
%FROM
%IDENT
%IF
%INCLUDE
%LET
%LlST
%NOCROSS
%NOLIST
%PAGE
%SBTTL
%THEN
%TITLE
%VARIANT
ABORT
ABS
ABS%
ACCESS
ACCESS%'
ACTIVE
ALIGNED
ALLOW
ALTERNATE
AND
ANY
APPEND
AS
ASC
ASCII
ATN
ATN2

BACK
BASE
BEL
BINARY
BIT
BLOCK
BLOCKSIZE
BS
BUCKETSIZE
BUFFER
BUFSIZ
BY
BYTE
CALL
CASE
CCPOS
CHAIN
CHANGE
CHANGES
CHECKING
CHR$
CLK$
CLOSE
CLUSTERSIZE
COM
COMMON
COMP%
CON
CONNECT
CONSTANT
CONTIGUOUS
COS
COT
COUNT
CR

CTRLC
CVT$$
CVT$%
CVT$F
CVT%$
CVTF$
OAT
DAT$
DATA
DATE$
DECIMAL
DECLARE
DEF
DEFAUL TNAME
DEL
DELETE
DESC
DET
DIF$
DIM
DIMENSION
DOUBLE
DOUBLEBUF
DUPLICATES
DYNAMIC
ECHO
EDIT$
ELSE
END
EQ
EQV
ERL
ERN$
ERR
ERROR

ERT$
ESC
EXIT
EXP
EXPLICIT
EXTEND
EXTENDSIZE
EXTERNAL
FF
FIELD
FILE
FILESIZE
FILL
FILL$
FiLL%
FIND
FIX
FIXED
FLUSH
FNAME$
FNEND
FNEXIT
FOR
FORMAT$
FORTRAN
FREE
FROM
FSP$
FSS$
FUNCTION
FUNCTIONEND
FUNCTIONEXIT
GE
GET
GETRFA

A-l

GFLOAT
GO
GOBACK
GOSUB
GOTO
GROUP

GT
HFLOAT
HT
IDN
IF
IFEND
IFMORE
IMAGE
IMP
INACTIVE
INDEXED
INPUT
INSTR
INT
INTEGER
INV
INVALID
ITERATE
KEY
KILL
LEFT
LEFT$
LEN
LET
LF
LINE
LlNO
LlNPUT
LIST
LOC
LOCKED
LOG
LOG1O
LONG
LSET
MAG
MAGTAPE
MAP
MAR
MAR%
MARGIN
MAT
MAX
MID
MID$
MIN
MOD
MOD%
MODE
MODIFY
MOVE
NAME

A-2

NEXT
NOCHANGES
NODATA
NODUPLICATES
NOECHO
NOEXTEND
NOMARGIN
NONE
NOPAGE
NOREWIND
NOSPAN
NOT
NUL$
NUM
NUM$
NUM1$
NUM2
ON
ONECHR
ONERROR
OPEN
OPTION
OR
ORGANIZATION
OTHERWISE
OUTPUT
OVERFLOW
PAGE
PEEK
PI
PLACE$
POS
POS%
PPS%
PRIMARY
PRINT
PROD$
PUT
QUO$
RAD$
RANDOM
RANDOMIZE
RCTRLC
RCTRLO
READ
REAL
RECORD
RECORDSIZE
RECORDTYPE
RECOUNT
REF
REGARDLESS
RELATIVE
REM
REMAP
RESET
RESTORE
RESUME

Reserved BASIC Keywords

RETURN
RFA
RIGHT
RIGHT$
RND
ROUNDING
RSET
SCALE
SCRATCH
SEG$
SELECT
SEQUENTIAL
SETUP
SGN
SI
SIN
SINGLE
SIZE
SLEEP
SO
SP
SPACE$
SPAN
SPEC-Yo
SQR
SQRT
STATUS
STEP
STOP
STR$
STREAM
STRING
STRING$
SUB
SUBEND
SUBEXIT
SUBSCRIPT
SUM$
SWAP%
SYS
TAB
TAN
TEMPORARY
TERMINAL
THEN
TIM
TIME
TIME$
TO
TRM$
TRN
TYP
TYPE
TYPE$
UNALIGNED
UNDEFINED
UNLESS
UNLOCK

UNTIL
UPDATE
USAGE$
USEROPEN
USING
USR$
VAL
VAL%
VALUE
VARIABLE
VARIANT
VFC
VIRTUAL
VPS%
VT
WAIT
WHILE
WINDOWSIZE
WORD
WRITE
XLATE
XOR
ZER

Appendix B
Program and subprogram Coding Conventions

This appendix presents a suggested format for coding BASIC programs. The recommended program
order and documenting procedures clarify the program's history, purpose, and logical development.
This organization also helps the program to run faster and with fewer errors.
This format is by no means intended to represent the only way of coding BASIC programs. It is a
sample format that can be adapted and modified to suit individual applications.

7..TITLE "{lTlodule-nalTle> - <terse functional description>"
7..SBTTL "o!.lerall description and fTlodification history"
%I DENT "}-{OO. 00"
COPYRIGHT (c) 1882 BY
DIGITAL EQUIPMENT CoRPoRATIoNt MAYNARDt MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND
COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH
THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY
OTHER COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY TRANSFERRED.
THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT CORPORATION.
DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.

8-1

FACILITY:
<Facilit}' nalrte>
ABSTRACT:
A short 3-8 line abstract of the function of the module.
If a
full functional specification can be ~iven in 3-8 linest replace
IIABSTRACT" abo!.Je by IIFUNCTIONAL DESCRIPTIONt"
and delete
the
"FUNCTIONAL DESCRIPTION II section below.
[mar~ins and tabs]
EN 1,1 IRONMENT:
[Pic., one:]
PDP-11 user mode [with <Operatin~ sYstem> dependencies]
VAX-11 user mode.
PDP-11 and VAX-11 user mode.
AUTHOR: <Your name>t CREATION DATE: <dd Mmmmmmmmm YYYY>
MODIFIED BY:
<Your name>t <dd-Mmm-yy>: VERSION XOO.OO
000 - Original version of module.
!
!--

%SBTTL IIFull description

[Pick at most one of FUNCTION or SUB below.
Include parameters on
either.
For main pro~ramSt omit FUNCTION or SUB statement and
parameters.]
FUNCTION <datatype> <name>
SUB <nalrte>
«datatype> (param>t
<Description>
<datatype> <param»
<Description>
!++

FUNCTIONAL DESCRIPTION:
A detailed functional description of the routine.
This should
detail
the steps of the proceSSt the use of external functions
and subpro~ralTls (inclljdin~ sYstem ser!.Jices t RTL routines t SYSLIB
routines) t and so forth.
[mar~ins and tabs]
FORMAL PARAMETERS:
<name>.<access type><data type>.<ar~ mech><ar~ form>
A description of the meaning of the
parametert its
valuest etc.
Repeat for each parameter.
If a ITla in p ro ~ ralTI
rather than
a function
or subroutinet use
the COMMAND
STRUCTURE section.
<access type> is mt rt or w for modifYt readt or write.
<datat}'pe> is b t dt gt ht It Pt St tt or "" for BYTEt DOUBLEt
GFLOAT t HFLOAT t LONG t
packed
(DECIMAL) t SINGLE t text
( STR I NG) tor WORD.
<ar~ mech> is dt
rt or v for BY DESCt BY REFt or BY VALUE.
<ar~ form> is <null> or a for scalar or array.
[mar~ins and tabs]

8-2

Program and Subprogram Coding Conventions

IMPLICIT INPUTS:
Describe all uses of the values of global storage
by the routine.
[Margins and tabs]

objects

used

storage

ob-

IMPLICIT OUTPUTS:
Describe all Modifications to the values of global
Jects used by the routine.
[Margins and tabs]
FUNCTION VALUE:
COMPLETION CODES:
If a functiont describe the value returned.
If
the
value
returned
is a status
indicatort use COMPLETION CODE and delete
FUNCTION VALUE;
if the result of SOMe cOMPutationt use FUNCTION
VALUE and delete COMPLETION CODE.
If a SUBt delete FUNCTION t.lALUE and enter "None."
[Margins and tabs]
SIDE EFFECTS:
Describe all functional side effects that are not evident froM
the
invocation interface.
This includes changes in storage allocationt process statuSt file operations (including the cOMMand
terrTlinal) t errors signalled t etc.
[Margins and tabs]
! _.

i..SBTTL "Declarations"
! ENVIRONMENT SPECIFICATION:

OPTION
<oPtion clause>t
<option clause>
DATATYPE SPECIFICATION:
RECORD <naMe>
<record declaration>
END RECORD
!
!
!

INCLUDE FILES:

i..INCLUDE "<Filespec>"
! EQUATED SYMBOLS:
!

DECLARE <datatype> CONSTANT
{l,lalue>t
<nafTle>
{narTle> = <l.lalue>

<Description>
<Description)

LOCAL STORAGE:
DECLARE
{datatype}
<narTle> t
{narTle>t
<datatype>
<naMe>t
(naMe>

<Description>
<Description>
{Description>
<Description>

Program and Subprogram Coding Conventions

8-3

! GLOBAL STORAGE:

COMMON «naMe»
<datatype)
<naMe),
<naMe),
<datat}'pe)
<naMe),
<naMe)
MAP «naMe»
<datatype)
<naMe),
<naMe),
(datatype)
(naMe>,
<naMe>

Be
Be
Be
Be
Be

<Description>
<DescriPtion)
(Description>
<DescriPtion)
(DescriPtion)

&
Be
Be
Be
Be
Be
Be

<Description>
<Description>
<DescriPtion)
(Description)

EXTERNAL REFERENCES:
EXTERNAL <datatype) CONSTANT
(naMe)
EXTERNAL (datatype)
(naMe)
EXTERNAL <datat}'pe) FUNCTION
(naMe)
«datatype) BY (Mech),
(datatype) BY <Mech»
EXTERNAL SUB
(naMe)
«datatype) BY (Mech),
<datatype) BY <Mech»

<DescriPtion)
Be

<Description>
<Function descriPtion)
(ArgUMent descriPtion)
<ArguMent description>
<Function description)
<ArguMent description)
<ArgUMent descriPtion)

Be
Be
Be
Be
Be
Be

INTERNAL REFERENCES:
DECLARE <datatype) FUNCTION
<naMe)
<Function description>
«datatype) ,
(ArguMent description>
<datatype»
! (ArguMent descriPtion)
ISBTTL "EnvironMent initialization"
!+
!
!-

Set UP global error handler

ON ERROR GO TO 31000
[Alternately, local error handlers can be set
ISBTTL "<Major section naMe)"
<Major section naMe):
!+

<Section description)

[Repeat once for each Major section.]
ISBTTL "Internal subroutine: <SYMbolic nafTle)"
[Access via GOSUB <SYMbolic naMe)]
<SYMbolic naMe>:
+

FUNCTIONAL DESCRIPTION:
IMPLICIT INPUTS:
IMPLICIT OUTPUTS:

Program and Subprogram Coding Conventions

where needed.]

Be
Be

! SIDE
!
!-

EFFECTS:

RETURN

.. ! n t ern a !
T I.! n C 1.1 0 n - -: : fI a hi e >,I
[Access via (naMe) «paraMs»]
DEF <datatype) (naMe)
«datatype) (naMe)t
(Description)
(datatype) (naMe»
(Description)
k b 0 I I L

FUNCTIONAL DESCRIPTION:
FORMAL PARAMETERS:
IMPLICIT INPUTS:
IMPLICIT OUTPUTS:
FUNCT I ON l..IAlUE:
SIDE EFFECTS:
END DEF
%SBTTl "RSTS/E CCl entn' point"
[This section is for RSTS/E CCl's only]
30000

CCl entrY point:
!-

X.SBTTl "CO/llllion error handlin!1"
31000

32787

!+
!
!-

COMMon error handlin!1:

%SBTTl "Module end"
END (FUNCTIONt null t or SUB)

Program and Subprogram Coding Conventions

8-5

INDEX
This index provides a complete cross-reference to the information in this manual. In the index the following conventions are used:

Explanation

Example
1-8t

A page number followed by a t indicates a table.

4-36f

A page number followed by an f indicates a figure.

For material not covered in this manual, see the Master Index in the back of the BASIC Reference Manual.
The Master Index contains a list of the major references to information throughout the BASIC documentation set.

A
%ABORT, 10-9
example of, 10-10
ABS, 6-2
Absolute value, 6-2
Access
record, 9-3
Addition
of matrixes, 7-18
of numeric strings, 6-16
Alphanumeric labels, 1-3
ALTERNATE KEY, 9-10
Ampersand, 1-2
AND, 1-17
Arc tangent, 6-6
Arithmetic operators, 1-13, 1-13t
Array output, 7-14 to 7-17
Arrays, 7-1 to 7-20
assigning values to, 7-9
bounds, 7-2
converti ng to stri ngs, 4-1 8
creating by reference, 7-7
creating explicitly, 7-1 to 7-6
creating implicitly, 7-6
creating with COMMON, 7-5
creating with DECLARE, 7-2
creating with DIMENSION, 7-3
creating with MAP, 7-6
default bounds, 7-7
explicit, 7-1 to 7-6
finding the determinant, 7-20

Arrays (Cont.)
implicit, 7-6
in MOVE statement, 9-1 8
initialization of, 7-2
inverting, 7-20
naming conventions, 7-3
redimensioning, 7-5, 7-7
sharing among program modules, 7-5
size limits, 1-12,7-2
transposing, 7-19
virtual, 9-3, 9-30
ASCII, 6-9
character set, 1-3
values, 5-10
Assigning string data
with LET, 4-4
with LSET, 4-5
with RSET, 4-5
Assigning values
to array elements, 7-9
to lexical constants, 10-8
to string variables, 2-2 to 2-3, 4-2 to
4-6
with INPUT, 2-1
with INPUT LINE, 2-2
with L1NPUT, 2-2
with READ and DATA, 2-3
Assigning values to arrays
from terminal-format files, 7-13
with MAT INPUT, 7-12
with MAT L1NPUT, 7-13
with MAT READ, 7-11

Index-l

Assigning values to arrays (Cont.)
with MAT statements, 7-9
Assignment
of matrixes, 7-17
Asterisk
in PR!!'~T US!!,~G format field, 8-6, 8-7
Asterisk-fi lied fields, 8-7
ATN,6-6

B
Backslash, 1-2
BASIC character set, 1-3
BASIC error handler, 11-1, 11-15
returning control to, 11-6
BASIC program
elements of, 1-1 to 1-20
BEL, 1-9
Binary radix, 5-9
Blank-if-zero fields
in PRINT USING, 8-10
Block 110 files, 9-3
GET, 9-17 to 9-20
opening, 9-11
PUT, 9-25
reading records from, 9-17 to 9-20
writing records to, 9-25
Block of statements, 1-3
Bounds
default for implicit arrays, 7-7
of an array, 7-2
Branching
conditional, 3-11
unconditional, 3-10
BS, 1-9
BUCKETSIZE, 9-33
BUFFER, 9-39
Buffer
1/0,9-17
Buffers
1/0,9-6
record, 9-6
redefining at run time, 5-20
Built-in functions, 6-1 to 6-21
BYTE, 5-2

c
Caret
in PRINT USING format field, 8-6, 8-9
CASE clause, 3-15
Case conversion
with EDIT$, 4-15
CCPOS,9-32

Index-2

CD
credit/debit format in PRINT USING,
8-10
in PRINT USING format field, 8-6
Centered fields
in PR!NT USING, 8-12
CHANGE statement, 4-18
CHANGES clause, 9-10
Character set
ASCII, 1-3
BASIC, 1-3
Characters
continuation, 1-2
format in PRINT USING, 8-11
nonprinting, 1-3, 1-9
translating with XLATE, 6-9
CHR$,6-9
Circumflex
in PRINT USING, 8-9
in PRINT USING format field, 8-6
CLOSE, 2-12, 9-31
Closing files, 9-31
terminal-format, 2-12
Commas
formatting, 2-8
in numeric output, 8-7
in PRINT, 2-8
in PRINT USING format field, 8-6
Comment fields, 1-6
COMMON, 5-14
creating arrays with, 7-5
default name, 5-14
in subprograms, 5-19
Comparison
of strings, 1-16
Compilation
conditional, 10-9
terminating with %ABORT, 10-9
Compiler directives, 10-1 to 10-10
compilation control, 10-7 to 10-10
listing control, 10-2 to 10-6
CON, 7-10
Concatenation
of COMMON areas, 5-15
of strings, 1-14,4-2
Conditional branching, 3-11
Conditional compilation, 10-9
Conditional expressions, 1-14, 3-14
CONNECT, 9-38
Constants, 1-6 to 1-10
declaring, 5-7
external, 5-8
floating-point, 1-6
integer, 1-7

Constants (Cont.)
lexical, 10-8
named, 5-7
numeric literals, 5-8
predefi ned, 1-9
string, 1-8
CONT, 3-20
Context
record, 9-3
CONTIGUOUS, 9-37
Continuation character, 1-2
Continued lines, 1-2
Continued statements, 1-2
Control variable
in ON-GOTO-OTHERWISE, 3-11
Control variables, 3-2
Controlling loop execution, 3-8
Conversion functions, 6-8 to 6-13
Converting
arrays to strings, 4-18
numbers to strings, 6-8 to 6-13
strings to numbers, 6-8 to 6-13
upper and lower case, 4-15
Copying BASIC source text, 10-6
COS, 6-4
Cosine, 6-4
COUNT clause
in PUT, 9-24
CR, 1-9
Creati ng arrays
by reference, 7-7
explicitly, 7-1 to 7-6
implicitly, 7-6
with COMMON, 7-5
with DECLARE, 7-2
with DIMENSION, 7-3
with MAP, 7-6
Creating strings, 4-13
Credits
in PRINT USING, 8-10
%CROSS, 10-5
Cross-reference listing
controlling, 10-5
CTRL IC trapping, 6-19, 11-13
CTRLC, 6-19, 11-13
(See also RCTRLC)
Currency symbol
in PRINT USING, 8-8
Current Record (See Record context)
Current Record Pointer, 9-4
Cursor position
finding, 9-32

D
DATA, 2-4
in function definitions, 6-23
Data
definition, 5-1 to 5-22
displaying, 2-6
Data pointer, 2-4
resetting, 2-5
Data types, 5-1
default, 5-3
floating-point, 5-3
integer, 5-3
keywords, 5-2t
muitipie, 5-11 to 5-13
packed decimal, 5-12
promotion of, 5-11 to 5-13
real, 5-3
Date functions, 6-17 to 6-19
DATE$, 6-17
Debits
in PRINT USING, 8-10
DECIMAL, 5-2
DECIMAL data type, 5-12
Decimal point
in PRINT USING format field, 8-5, 8-6
Decimal radix, 5-9
Declarative DIMENSION, 7-4
Declarative statements, 5-1
DECLARE
constants, 5-7
creating arrays with, 7-2
DEF functions, 5-6
variables, 5-5
Dec!aring
constants, 5-7
DEF functions, 5-6, 6-24
external constants, 5-8
variables, 5-5
DEF, 6-21 to 6-26
declaring, 6-24
error handling in, 6-25, 11-11
multi-line, 6-23
single-line, 6-21
transfer of control, 6-25
DEF functions
declaration of, 5-6
Default
bounds for implicit arrays, 7-7
data type, 5-3
name for COMMON, 5-14
name for MAP, 5-14
overriding data type, 5-5
DEFAUL TNAME, 9-44

Index-3

Definition
of data, 5-1 to 5-22
DEL, 1-9
DELETE, 9-12, 9-25
Deleting
files, 9-31
records, 9-25
DET, 7-20
Determ i nant
of a matrix, 7-20
DIF$, 6-13, 6-16
Digits
reserving with PRINT USING, 8-4
DIMENSION, 7-3
declarative, 7-4
executable, 7-4
for virtual arrays, 9-30
Directives (See Compiler directives)
Displaying data, 2-6
Division
of numeric strings, 6-16
Docu mentation
of a program, 1-5
Dollar sign
in PRINT USING format field, 8-6, 8-8
DOUBLE, 5-2
DUPLICATES, 9-10
Dynamic mapping, 5-20
Dynamic strings
definition of, 4-1
modifying, 4-2

E
E, 6-5, 6-6
E format
in PRINT USING, 8-9
E notation, 1-7
ECHO, 6-20
(See also NOECHO)
EDIT$,4-15
options, 4-15t
Editing strings
with EDIT$, 4-15
with TRM$, 4-14
ELSE clause, 3-13
END, 3-21
END DEF, 6-23
END FUNCTION, 6-26
END IF, 3-13
Entry points
to subroutines, 3-17
EQV, 1-17
ERL, 11-4

Index-4

ERN$, 11-6
ERR, 11-4
Error
fatal, 11-1, 11-4
in PRINT USING, 8-13
line, 11-4
messages, 11-6
module, 11-6
non-BASIC, 11-4, 11-17
number, 11-4
severity level, 11-1
untrappable, 11-4
warning, 11-1
Error handlers, 11-1 to 11-17
BASIC, 11-1, 11-15
exiting from, 11-7 to 11-10
functions performed by, 11-1
in DEFs, 6-25, 11-11
in subprograms, 11-11
transferring control to, 11-3
trapping CTRL/C, 11-13
user-supplied, 11-2
Error handling, 11-1 to 11-17
functions, 11-4 to 11-6
ERT$,11-6
Evaluation expressions, 1-19
Executable DIMENSION, 7-4
Executable statements, 1-4
Executing statements conditionally, 3-21
to 3-24
Execution
halting of, 3-20
suspension of, 3-19
EXIT, 3-8
EXIT DEF, 6-23
EXIT FUNCTION, 6-26
EXP, 6-6
Explicit loop control, 3-8
Explicit numeric literal notation, 5-8
Explicit variable declaration, 5-5
Exponential format
in PRINT USING, 8-9
Exponential notation, 1-7
Exponentiation, 6-6
Expressions, 1-13 to 1-20
conditional, 1-14,3-14
evaluation of, 1-19
evaluation of in PRINT, 2-6
lexical, 10-8
logical, 1-17
mixed-mode, 5-11 to 5-13
multiple data types, 5-11 to 5-13
numeric, 1-13
numeric relational, 1-15

Expressions (Cant.)

FII'-~D (Cant.)

relational, 3-14
string, 1-14
string relational, 1-16
Extended fields
in PRINT USING, 8-13
EXTEN DSIZE, 9-38
EXTERNAL, 5-8, 6-27 to 6-28
External functions, 6-1, 6-26 to 6-28
Extracting substrings, 4-9 to 4-15
with LEFT$, 4-12
with MID$, 4-11
with RIGHT$, 4-13
with SEG$, 4-9

sequential access, 9-13
FIX, 6-3
Fixed-length records, 9-1
Fixed-length strings, 4-3
definition of, 4-1
Floating dollar sign fields, 8-8
Floating-point constants, 1-6
precision of, 1-6
range of, 1-6
Floating-point data types, 5-3
Floating-point variables, 1-10
FNEND, 6-23
FNEXIT, 6-23
FOR
as statement modifier, 3-22
FOR INPUT, 9-8
FOR OUTPUT, 9-8
FOR-NEXT loops, 3-2 to 3-5
Format
of a program line, 1-1
PRINT,2-8
record, 9-1
Format characters
for numeric fields, 8-6t
for string fields, 8-11 t
in PRINT USING, 8-6, 8-11
Format reversion, 8-3
Format stri ng
definition of, 8-2
in PRINT USING, 8-2 to 8-3
reusing, 8-3
FORMAT$,6-10
Formatting output, 2-7
with PRii...JT USiNG, 8-1 to 8-15
FREE, 9-12, 9-29
FSP$, 9-11
FUNCTION, 6-26
FUNCTIONEND,6-26
FUNCTIONEXIT, 6-26
Functions, 6-1 to 6-28
built-in, 6-1 to 6-21
conversion, 6-8 to 6-13
date, 6-17 to 6-19
error handling, 11-4 to 11-6
external, 6-1, 6-26 to 6-28
file-related, 9-32 to 9-33
numeric, 6-2 to 6-8
recursive, 6-21, 6-25
string, 4-6 to 4-16
string arithmetic, 6-13 to 6-17
terminal control, 6-19 to 6-21
time, 6-17 to 6-19
trigonometric, 6-4

F
FF, 1-9
Fields
asterisk-filled, 8-7
centered with PRINT USING, 8-12
comment, 1-6
extended with PRINT USING, 8-13
floating dollar sign, 8-8
left-justified in PRINT USiNG, 8-11
right-justified with PRINT USING, 8-12
trailing minus sign, 8-8
File operations, 9-30 to 9-31
File organization, 9-2
File-related functions, 9-32 to 9-33
Files, 9-1 to 9-44
block I/O, 9-3
closing, 9-31
deleting, 9-31
indexed, 9-2
open i ng, 9-6 to 9-1 2
preextending, 9-37
relative, 9-2
renaming, 9-30
restoring, 9-28
sequential, 9-2
temporary, 9-37
terminal-format, 2-11 to 2-13,9-3
truncating, 9-29
undefined, 9-3
virtual arrays, 9-3
FILESIZE, 9-37
FILL, 5-18
FILL$, 5-18
FILL%,5-18
FIND, 9-5, 9-12, 9-13
compared with GET, 9-13
random access, 9-13
RFA clause, 9-22

Index-5

Functions (Cont.)
user-defined, 6-21 to 6-28

G
GET, 9-5, 9-12, 9-15 to 9-23
compared with FIND, 9-13
for block I/O files, 9-17 to 9-20
for indexed files, 9-20
for rei ative fi les, 9-1 6
for sequential fi les, 9-15
RFA clause, 9-22
GETRFA, 9-22
GFLOAT, 5-2
GOSUB, 3-17
GOTO, 3-10

H
Halting program execution, 3-20
Handling errors, 11-1 to 11-17
Hexadecimal radix, 5-9
HFLOAT, 5-2
HT, 1-9

Initialization
of arrays, 7-2
of variables, 1-12
INPUT, 2-1 to 2-2
Input, 2-1 to 2-6
from source program, 2-3
interactive, 2-1
null, 2-1
INPUT LINE, 2-2 to 2-3
INSTR, 4-7 to 4-9
INT, 6-3
INTEGER, 5-2
Integer constants, 1-7
Integer data types, 5-3
Integer variables, 1-11
Interactive input, 2-1
INV, 7-20
Inverting matrixes, 7-20
ITERATE, 3-8

J
Justifying strings
with LSET, 4-5
with RSET, 4-5

K
I/O
buffers, 9-6, 9-17, 9-39
optimization, 9-33 to 9-44
simple, 2-1 to 2-13
statements and record context, 9-':'t
to arrays, 7-7 to 7-17
%IDENT, 10-3
Identifying module version, 10-3
IF
as statement modifier, 3-22
%IF-% THEN-%ELSE-%END-%IF, 10-9
IF-THEN-ELSE, 3-13
Immediate mode, 3-20
IMP, 1-17
Implicit variables, 1-10
%INCLUDE, 5-20, 10-6
IND, 7-10
Indexed files, 9-2
GET, 9-20
keys, 9-10
open i ng, 9-9
PUT, 9-25
reading records from, 9-20
UPDATE, 9-28
updating records in, 9-28
writing records to, 9-25

Index-6

KEY clause
in FIND, 9-14
in GET, 9-20
in RESTORE, 9-28
Keys
changing, 9-10
duplicates, 9-10
in indexed files, 9-10
Keyword space requirements, 1-4t
Keywords, 1-4
KILL, 9-31

L
Labels, 1-3
in GOTO, 3-10
Leading zeros
in PRINT USING output, 8-9
Left justification
with PRINT USING, 8-11
LEFT$, 4-12
LEN, 4-7
Length of a stri ng, 4-7
%LET, 10-8
Lexical constants, 10-8
Lexical directives (See Compiler directives)

Lexical expressions, 10-8
LF, 1-9
Line format, 1-1
Line numbers, 1~1
in GOTO, 3-10
Lines
continued, 1-2
multi-statement, 1-2
UNPUT, 2-2 to 2-3
%UST,l0-4
Listing
compiler directives, 10-2
formatting with %PAGE, 10-4
Literals
character, 5-10
numeric constant, 5-8
string, 1-8
Local subroutines, 3-17
Locating records, 9-13
LOCK, 9-12
LOG, 6-5
LOG10, 6-5
Logarithm
common, 6-5
natural, 6-5
Logical expressions, 1-1 7, 3-14
Logical operators, 1-15, 1-17t
LONG,5-2
Loops, 3-1 to 3-9
controlling explicitly, 3-8
FOR-NEXT, 3-2 to 3-5
nested, 3-7
single-line, 3-22 to 3-24
UNTIL-NEXT, 3-6 to 3-7
'vVHiLE-NEXT, 3-5 to 3-6
LSET,4-5

M
MAP, 5-15, 9-6
creating arrays with, 7-6
default name, 5-14
in subprograms, 5-19
multiple, 4-16,5-17
overlaid, 4-16, 5-17
single, 5-16
used in string manipulation, 4-16
MAP DYNAMIC, 5-21, 9-6
Mapping
dynamic, 5-20
MAR%,9-33
MAT, 7-7 to 7-20
MAT INPUT, 7-8, 7-12, 7-14
MAT UNPUT, 7-8, 7-13, 7-14

MAT PRINT, 7-8, 7-15, 7-16
MAT READ, 7-8, 7-11
MAT statements, 7-8t
keywords, 7-10t
Matrix
addition, 7-18
assignment, 7-17
finding the determinant of, 7-20
functions, 7-19 to 7-20
I/O functions, 7-16
inverting, 7-20
multiplication, 7-18
operators, 7-17 to 7-19
subtraction, 7-18
transposing, 7-20
MID$,4-11
Minus sign
in PRINT USING format field, 8-6, 8-8
Mixed-mode expressions, 5-11 to 5-13
results, 5-13f
Modifiers, 3-21 to 3-24
FOR, 3-22
IF, 3-22
nested, 3-24
UNLESS, 3-22
UNTIL, 3-23
WHILE, 3-23
Modifying dynamic strings, 4-2
Module version
identifying with %IDENT, 10-3
MOVE, 9-6, 9-18 to 9-20
used with arrays, 9-18
Multi-line DEF, 6-23
Multi-line statements, 1-2
Multi-statement lines, 1-2
Multiple data types, 5-11 to 5-13
Multiple MAPs, 4-16, 5-17
Multiplication
of matrixes, 7-18
of numeric strings, 6-16

N
NAME AS, 9-30
Named constants, 5-7
Naming conventions
floating-point variables, 1-10
integer variables, 1-11
labels, 1-3
of arrays, 7-3
string variables, 1-11
Nested loops, 3-7
Nested modifiers, 3-24
Next Record (See Record context)

Index-7

Next Record Pointer, 9-4
%NOCROSS, 10-5
NOECHO, 6-20
(See also ECHO)
%NOLlST, 10-4
Nonexecutable statements,l-4
Nonmodifiable statements, 3-21
Nonprinting characters, 1-3, 1-9
NOSPAN, 9-37
NOT,l-17
Notation
explicit numeric literals, 5-8
exponential, 1-7
scientific, 1-7
NUL$,7-10
Null input, 2-1
Nulls
trailing, 4-20
NUM, 7-16
NUM$, 6-11
NUM1$,6-11
NUM2, 7-16
Number Notations, 1-7t
Numbers
converting to string, 6-8 to 6-13
printing, 2-10
printing with PRINT USING, 8-4 to

8-10
random, 6-7 to 6-8
Numeric expressions, 1-13
Numeric functions, 6-2 to 6-8
Numeric literals, 5-8
Nurneric ofJerator precedence, 1-20t
Numeric output, 2-10
asterisk-filled, 8-7
blank-if-zero in PRINT using, 8-10
commas in, 8-7
credit/debit in PRINT USING, 8-10
E format in PRINT USING, 8-9
leading zeros in PRINT USING, 8-9
with floating dollar sign, 8-8
with PRINT USING, 8-4 to 8-10
with trailing minus sign, 8-8
Numeric relational expressions, 1-15,
1-16t
Numeric strings, 6-10 to 6-17
addition of, 6-16
division of, 6-16
multiplication of, 6-16
subtraction of, 6-16

o
Octal radix, 5-9

Index-8

ON ERROR GO BACK, 11-11
ON ERROR GOTO, 11-3
ON ERROR GOTO 0, 11-6
ON-GOSUB-OTHERWISE, 3-18
ON-GOTO-OTHERWISE, 3-11
OPEN, 2-12, 9-6 to 9-12
for block I/O files, 9-11
for indexed files, 9-9
for relative files, 9-9
for sequential files, 9-8
for terminal-format files, 9-11
for undefined files, 9-11
Opening a terminal-format file, 2-12
Opening files, 9-6 to 9-12
block I/O, 9-11
indexed, 9-9
relative, 9-9
sequential, 9-8
terminal-format, 9-11
undefined, 9-11
Operator precedence, 1-20
Operators
arithmetic, 1-13
logical, 1-15
matrix, 7-17 to 7-19
precedence of, 1-20
relational, 1-15
string relational, 1-17
Optimizing I/O, 9-33 to 9-44
OPTION,5-4
OR, 1-17
Organization of a file, 9-2
OTHERWISE clause, 3-11, 3-18
Output
centered with PRINT USING, 8-12
formatting, 2-7
left-justified with PRINT USING, 8-11
numeric, 2-10
right-justified with PRINT USING, 8-12
strings, with PRINT USING, 8-10 to
8-15
Output listing
compiler directives, 10-2
formatting with %PAGE, 10-4
Output, numeric
asterisk-filled, 8-7
E format in PRINT USING, 8-9
floating dollar sign, 8-8
leading zeros in PRINT USING, 8-9
with commas, 8-7
with PRINT USING, 8-4 to 8-10
with trailing minus sign, 8-8
Overlaid MAPs, 4-16, 5-17
Overriding the default data type, 5-5

p
Packed decimal numbers, 5-12
Padding
in string comparisons, 1-16
in string virtual arrays, 4-20
%PAGE, 10-4
Parameters
actual, 6-21
formal, 6-21
Parity bit
removi ng, 4-1 5
Percent sign
in integer constants, 1-7
in PRINT USING format field, 8-6
PI, 1-9
PLACE$, 6-13, 6-15
Plus sign, (+), in string concatenation,
1-14
POS, 4-7 to 4-9
Pound sign
in PRINT USING, 8-6
Pound sign (# )
in PRINT USING, 8-4
Precedence
of operators, 1-20
Precision
in string arithmetic, 6-14
of floating-point constants, 1-6
of string arithmetic functions, 6-14t
Predefi ned constants, 1-9t, 1-9
Preextending files, 9-37
PRIMARY KEY, 9-10
PRINT, 2-6
used with arrays, 7-15
PRINT format, 2-8
PRI NT format characters
comma, 2-8
semicolon, 2-8
PRINT USING, 8-1 to 8-15
errors, 8-13
format characters, 8-6
specifying decimal point location, 8-5
Print zones, 2-7
Printing numbers, 2-10
asterisk-filled, 8-7
with commas, 8-7
with floating dollar sign, 8-8
with PRINT USING, 8-4 to 8-10
with trailing minus sign, 8-8
Printing strings, 2-10
with PRINT USING, 8-10 to 8-15
PROD$, 6-13, 6-16
Program control, 3-1 to 3-24

Program documentation, 1-5
Program execution
halting of, 3-20
suspension of, 3-19
Program input, 2-1 to 2-6
Program line
elements of, 1-1
format of, 1-1
Program listing
control I i ng, 10-2
Program module
error handler in, 11-2
Program output, 2-6 to 2-11
Program section, 5-13
Promotion
of data types, 5-11 to 5-13
Prompts, 2-1
PSECT, 5-13
PUT, 9-12, 9-23 to 9-25
COUNT clause, 9-24
for block I/O files, 9-25
for indexed files, 9-25
for relative files, 9-24
for sequential files, 9-24

Q
QUO$, 6-13, 6-16
Quotation marks, 2-10

R
Radix
binary, 5-9
decimal, 5-9
hexadecimal, 5-9
octal, 5-9
Random numbers, 6-7 to 6-8
RAN DOMIZE, 6-7
Range
of floating-point constants, 1-6
RCTRLC, 6-19,11-13
(See also CTRLC)
READ, 2-3
Reading records, 9-15 to 9-23
from block I/O files, 9-17 to 9-20
from indexed files, 9-20
from relative files, 9-16
from sequential files, 9-15
REAL, 5-2
Real data types, 5-3
Record access, 9-3
random-by-key, 9-3
random-by-RFA, 9-3

Index-9

Record access (Cont.)
sequential, 9-3
Record buffers, 9-6
RECORD clause
in FIND, 9-13
in PUT, 9-24, 9-25
Record context, 9-3
Current Record Pointer, 9-4
Next Record Pointer, 9-4
Record format, 9-1
Record Management Services (RMS), 9-1
Record operations, 9-12 to 9-30
Records, 2-11
deleting, 9-25
fixed-length, 9-1
locating, 9-13
reading, 9-15 to 9-23
unlocking, 9-29
updating, 9-26 to 9-28
variable-length, 9-1
writing, 9-23 to 9-25
RECORDSIZE, 9-6
RECORDTYPE, 9-40
RECOUNT, 9-32
Recursive functions, 6-21, 6-25
Redefining buffers, 5-20
Redimensioning arrays, 7-:-5
Relational expressions, 3-14
numeric, 1-15
string, 1-16
Relational operators, 1-15
Relative files, 9-2
GET, 9-16
opening, 9-9
PUT, 9-24
reading records from, 9-16
UPDATE, 9-27
updating records in, 9-27
writing records to, 9-24
REM, 1-5
REMAP, 5-21, 9-6
Renaming files, 9-30
Rereading DATA, 2-5
Reserved words (See Keywords)
Reserving places for digits
in PRINT USING, 8-4
Resetting the data pointer, 2-5
RESTORE, 2-5, 9-12, 9-28
Restoring files, 9-28
Restoring the data pointer, 2-5
Result data types in BASIC expressions,
5-11t
RESUME, 11-7 to 11-10, 11-14
RETURN, 3-17

Index-l0

Returning from subroutines, 3-17
Reversion
format, 8-3
RFA, 5-2, 9-3
definition of, 9-21
RFA clause
in GET and FIND, 9-22
Right justification
with PRINT USING, 8-12
RIGHT$,4-13
RMS, 9-1
RND, 6-7
Rounding numeric strings, 6-14

s
%SBTTL, 10-2
SCRATCH, 9-12, 9-29
Searching strings, 4-7
Section
program, 5-1 3
SEG$, 4-9 to 4-11
SELECT-CASE, 3-15 to 3-17
Semicolon
formatting, 2-8
in PRINT, 2-8
Sequential files, 9-2
GET, 9-15
opening, 9-8
PUT, 9-24
reading records from, 9-15
UPDATE, 9-26
updating records in, 9-26
writing records to, 9-24
Severity level of errors, 11-1
SGN, 6-2
SI, 1-9
SIN, 6-4
Sine, 6-4
SINGLE, 5-2
Single MAP, 5-16
Single-line DEF, 6-21
Single-line loops, 3-22 to 3-24
SLEEP, 3-19
SO, 1-9
SP, 1-9
SPACE$, 4-14
Spaces
creating with SPACE$, 4-14
Special symbols
in PRINT USING, 8-6
SQR, 6-8
Square roots, 6-8

Statements
block of, 1-3
continued, 1-2
declarative, 5-1
executable, 1-4
multi-line, 1-2
nonexecutable, 1-4
nonmodifiable, 3-21
Static storage, 5-13
STATUS, 9-33
STEP, 3-2
STOP, 3-20
Storage
static, 5-13
STR$,6-12
STRING, 5-2
String arithmetic, 6-13 to 6-17
String arithmetic functions, 6-13t, 6-13 to
6-17
String comparisons, 1-16
String concatenation, 1-14,4-2
String constants, 1-8
printing, 2-10
String expressions, 1-14
String functions, 4-6 to 4-16
String length
finding, 4-7
String literals, 1-8
String modification, 4-2t
String relational expressions, 1-16
String relational operators, 1-1 7t
String truncation, 4-4
String variables, 1-11
assigning values to, 2-2
String virtuai arrays, 4- i 9
STRING$, 4-13
Strings, 4-1 to 4-20
converting to arrays, 4-18
converting to numbers, 6-8 to 6-13
creating with STRING$, 4-13
fixed-length, 4-3
in virtual arrays, 4-19
left-justifying, 4-5
printing, 2-10
printing with PRINT USING, 8-10 to
8-15
right-justifying, 4-5
Subprograms
COMMONs in, 5-19
error handlers in, 11-11
MAPs in, 5-19
Subroutine entry points, 3-17
Subroutines, 3-17
Subscripted variables, 1-12

Substrings
extracting, 4-9 to 4-15
searching for, 4-7
Subtraction
of matrixes, 7-18
of numeric strings, 6-16
SUM$, 6-13, 6-16
Suspending program execution, 3-19
Symbols
in PRINT USING, 8-6

T
TAB, 6-20
TAN, 6-4
Tangent, 6-4
Target, 3-11
TEMPORARY, 9-37
Terminal control functions, 6-19 to 6-21
Terminal-format files, 2-11 to 2-13, 9-3
closing, 2-12
opening, 2-12, 9-11
used with arrays, 7-13
writing to, 2-12
THEN clause, 3-13
TIME, 6-18
Time functions, 6-17 to 6-19
TIME$, 6-18
% TITLE, 10-2
Trailing blanks
discarding, 4-14
Trailing minus sign fields, 8-8
Trailing nulls
in virtual arrays, 4-20
Trailing tabs
discarding, 4-14
Transposing matrixes, 7-20
Trapping CTRL/C, 6-19
Trigonometric functions, 6-4
TRM$,4-14
TRN, 7-19
Truncating
a number, 6-3
numeric strings, 6-14
Truncating a file, 9-29
Truncation, 4-4
Truth tables, 1-18t
Truth tests, 1-18

u
Unconditional branching, 3-10
Undefined files, 9-3
opening, 9-11

Index-ll

Underscore
in PRINT USING format field, 8-6
UNLESS
as statement modifier, 3-22
UNLOCK, 9-12, 9-29
Unlocking records, 9-29
UNTIL
as statement modifier, 3-23
UNTIL-NEXT loops, 3-6 to 3-7
UPDATE, 9-12, 9-26 to 9-28
for indexed files, 9-28
for relative files, 9-27
for sequential files, 9-26
Updating records, 9-26 to 9-28
in indexed files, 9-28
in relative files, 9-27
in sequential files, 9-26
User-defined functions, 6-21 to 6-28
USEROPEN, 9-40

v
VAL, 6-12
VAL %, 6-12
Variable-length records, 9-1
Variables, 1-10 to 1-13
control, 3-2
expl icit declaration of, 5-5
floati ng-poi nt, 1-1 0
implicit, 1-10
initialization of, 1-12
integer, 1-11
string, 1-11
subscri pted, 1-1 2

Index-12

%VARIANT, 10-8
example of, 10-10
Virtual array files, 9-3
Virtual arrays, 9-30
DIMENSION, 9-30
stri ng, 4-1 9
VT, 1-9

w
WAIT, 3-20
WHILE
as statement modifier, 3-23
WHILE-NEXT loops, 3-5 to 3-6
WINDOWSIZE, 9-39
WORD, 5-2
Writing records, 9-23 to 9-25
to block I/O files, 9-25
to indexed files, 9-25
to relative files, 9-24
to sequential files, 9-24
Writing to a terminal-format file, 2-12

x
XLATE, 6-9
XOR, 1-17

z
ZER,7-10
Zero
in PRINT USING format field, 8-6, 8-9

BASIC
User's Guide
AD-L335A-T1

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
P€rtoimanC€ 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.

Name

Assembly language programmer

o
o

Occasional programmer (experienced)

User with little programming experience

Student programmer

O~er(ple~esp&iM----------------------------------------------~

Higher-level language programmer

Date___________________

Organization _________________________________________________________
Street~

______________________________________________________________________

City__________________________________.State_______

Zip Code
or
Country

·
-------Do Not Tear - Fold Here and Tape ____________________________________ J

111111

No Postage
Necessary

if Mailed in the
United States

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

ATTN: BSSG Publications ZK01-3/J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, N.H. 03062

-------Do Not Tear - Fold Here and Tape - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

I
I
I
I
I
I