Digital PDFs

AA-HY16B-TE

February 1990

672 pages

Original

32MB

view download

OCR Version

27MB

view download

Document:	VAX BASIC Reference Manual
Order Number:	AA-HY16B-TE
Revision:	000
Pages:	672
Original Filename:

OCR Text

VAX BASIC Reference Manual
Order Number: AA-HY16B—-TE

February 1990

This manual provides reference material and syntax for VAX BASIC language elements.

Revision/Update Information:

This revised manual supersedes the VAX BASIC
Reference Manual, Version 3.3

Operating System and Version: VMS Version 5.0 or higher

Software Version:

digital equipment corporation
maynard, massachusetts

VAX BASIC Version 3.4

First Printing, August 1986
Revised, July 1988
Revised, February 1990
The information in this document is subject to change without notice and should not
be construed as a commitment by Digital Equipment Corporation. Digital Equipment
Corporation assumes no responsibility for any errors that may appear in this document.

The software described in this document is furnished under a license and may be used
or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is
not supplied by Digital Equipment Corporation or its affiliated companies.

Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to
restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and
Computer Software clause at DFARS 252.227-7013.

Printed in U.S.A.
The postpaid Reader’s Comments forms at the end of this document request your
critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
CDA

MASSBUS

VAX RMS

DDIF

PrintServer 40

VAXstation

DEC

Q-bus

VMS

DECnet
DECUS
DECwindows
DIGITAL

ReGIS
ULTRIX
UNIBUS
VAX

VT
XUl

LNO3

VAXcluster

Hflflflfln

The following is a third-party trademark:

PostScript is a registered trademark of Adobe Systems, Inc.
ZK5433

Contents
Preface . . ...
e,

Summary of Technical Changes

XiX

Chapter 1
1.1

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

Program Elements and Structure
Components of Program Lines ............................
1.1.1
Line Numbers . .. ....... ... . ... . . ...
1.1.1.1

Programs With Line Numbers

1.1.1.2

Programs Without Line Numbers

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

1-1
1-2
1-2

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

1-2

1.1.2

Labels . ...... ... . e

1-3

1.1.3

Statements . . ......
... . .. ....
..

1—4

1.1.3.1

Keywords . .......
.00 iiiinn...
....

1-5

1.1.3.2

Identifying Program Units . ................
Single-Statement Lines and Continued

1-6

1.1.3.3
1.1.3.4

Statements . .. ........
... . ... ..
...,

1-7

Multi-Statement Lines . . .. ................

1-8

1.1.4

Compiler Directives

. .......... ...,

1-9

1.1.5

Line Terminators . .......
...
.....
...,

1-10

1.1.6

Lexical Order

.. ....... ...ttt

1-10

1.2

VAXBASICCharacter Set . . ... .............0ciruunnn..

1-10

1.3

VAX BASIC Data Types . . . . .. ...

1.4

ittt it et

e e

e e e

1-11

1-14

Explict Data Typing .. ........
... ... .. ... .....

1-15

1.3.1

Implicit Data Typing . . .......... .00t

1.3.2

Variables . . . . ...

.. ... . ..

1-16

1.4.1

Variable Names . . .. ......
... ... ... . ...
. .
...

1-17

1.4.2

Implicitly Declared Variables

1-17

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

Explicitly Declared Variables . ......................
... ...
Subscripted Variables and Arrays . . . ...........
...
.....
Initialization of Variables . .. .............

1-19
1-19
1-22

CoNStants . . . ... .. e

1-23

1.4.3
1.4.4
1.4.5

1.5

NumericConstants . . .. ... ... ... ...
Floating-Point Constants . . . ...............
1.5.1.1
IntegerConstants. . . . ...................
1.5.1.2
Packed Decimal Constants . . ..............
1.5.1.3
...
... . ....
StringConstants .. ........
Named Constants . .. ........ ...
Naming Constants Within a Program Unit .. .. ..
1.5.3.1
Naming Constants External to a Program Unit . . .
1.56.3.2

Explicit Literal Notation . . .........................
0.,
.....
...
Predefined Constants . . ........

1-24
1-24
1-26
1-27
1-27
1-29
1-29
1-31
1-31
1-34

1.6

EXPresSSiONS . . . . . ... e
Numeric Expressions . ... . ... ... .. i
1.6.1
Floating-Point and Integer Promotion Rules . . ...
1.6.1.1
DECIMAL PromotionRules . ...............
1.6.1.2
i i
i
String Expressions . .. . ... ...
1.6.2
Conditional Expressions . . ... ... ...,
1.6.3
Numeric Relational Expressions . ............
1.6.3.1
String Relational Expressions . . . .. ..........
1.6.3.2
Logical Expressions . . ...................
1.6.3.3
o
Evaluating Expressions . . . . ....... ... ..o
1.6.4

1-36
1-36
1-38
1-39
1-41
142
142
143
1-45
1-50

1.7

..
...
....
... ...
Program Documentation . . . . .. .....
..
. ......
.
CommentFields ......
1.7.1
REM Statements . . .... ...ttt iiieennnn.
1.7.2

1-62
1-52
1-54

Chapter 2

Environment Commands
i i e e e aee e
e
I YOUR-COMMENT . . . .
i iee
$ SYSTEM-COMMAND . . . . ... et
e
e e
e
e
e
APPEND . . ittt
e
e
e e
e e e
ASSIGN . . .. ot
e
i e e
i e et e e e e e
COMPILE . . . ..ot
e i e et et ettt i i ittt aeaaeeees
CONTINUE . . .o
e
e
et
DELETE . . . .ttt e ittt e e e
e e e
e e e
T . o
ED

1.5.1

1.5.2
1.5.3

1.5.4
1.5.5

1
=
e
e e
e e e e e e e e e
e
HELP . . . .
e
e
e e e e e e e e e et
IDENTIFY . . o it
e
e e e e e e et e e e e t
et e ett
INQUIRE . . ..

22
24
2—6
2-8
2-10
2—21
2-22
2—-24
2-27
2-29
2-31
2-32

2—-33

2-35
2-37
2-38
2-40

2-41
2—43
2—-45

RUN

.
e
e

2-48

2-51
2-53

2-55
-----------------------------------------

2-56

2-58
2-60
2—62

Chapter 3

Compiler Directives
%ABORT .

-------------------------------------------

%DECLARED .. ... ...

3-2

3-3

%CROSS .
.

3—4

3-6

%IDENT. .
%lF-%THEN-%ELSE-%END %IF . ... ..... .. ...

...

%INCLUDE

3—-10

)

3-15

3-17

BNOCROSS . . . ..
e e
e

3-18

%NOLIST .

3-20

%PAGE . .

3-21

%PRINT . .

322

%REPORT

3-23

3-25

%TITLE . .

3-27

%VARIANT

3-29

%SBTTL

Chapter 4

Statements and Functions

LITLE

ABS

4-10

4-16

CCPOS . .
e e e
e

4-18

CHAIN . ..
e
e

4-20
4-22

CHRS

. ...
e e e e

...
e e
e

4-25
4-27

4-29
4-35
4-37
4-39

DATES . . ..o

------------------------------------------------

DIF$

FIELD . ... e

FNEND

4-121

FNEXIT

4-122

FOR

4-123

FORMAT$S

4-127

FREE

4-129

FSP$ .

llllllllllllllllllllllllllllllllllllllllllllll

4-131

FUNCTION . . . .
e e e e

4-133

FUNCTIONEND . . . . . ...

4-137

FUNCTIONEXIT
GET

e e

---------------------------------------

4-138

4-139

GETRFA

4-147

GOSUB

4-149

GOTO

4-151

HANDLER

4-153

IF ...

4-155

INKEY$

4-158

INPUT

4-162

INPUT LINE

4-166

INSTR

4-169

INT ..

llllllllllllllllllllllllllllllllllllllllllllll

INTEGER . . . ...

e i

4-171
4173

ITERATE

4-175

KILL

4-177

4-178

4-180
4-182

4-184

4-186

LOC

4-189

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

4-191
4-193

IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII

4-195
4-197

-------------------------------------------

4-199

4-201

MAP .

4-205

4-209

MAR .

4-210

MAT

4-212

MAT INPUT

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

MAT LINPUT . ... et
i i
ee e e

4-217

4-220

MAT PRINT

4-223

MAT READ .. ... . ittt
e e

4-226

MAX .

4-229

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

vii

4-231
4-234
4-236

4-238

4-242
NEXT

4-244

4-246
4-248

NUM

4-250
4-252

4-254
4-256

4-258
4-260

4-263
4-265
4-267

OPEN

llllllllllllllllllllllllllllll

llllllllllllllll

4—-269
4-283
4-288

------------------------------

-----------------

4-292

4-294
4-298

PRODS

. ...

. e

4-305
4-308

4-310
4-314

4-317
4-319

RCTRLC

. .. .

RCTRLO

. ... e
e

4-321

READ

4-322
4-324

4-326
4-328
4-333
4-335
4-337

RESET

. ...

4-342
4-343

4-345

RETRY

. .

4-348

4-350
4-352
4-354

viii

4-357
4-359

RSET

SCRATCH

4-361

SEG$

4-363

SELECT . . . .
e
e

4-365

SET PROMPT . . ...

4-368

4-370
4-371

4-373
4-375

SQR

4-376

4-378
4-380
----------------------------------------------

4-382
4-384

SUB

4-386

SUBEND

4-390

SUBEXIT

4-391

SUM$

4-392

4-394
4-396

4-398
----------------------------------------------

4-399

4-401
..............................................

4-403

4-404
4-406

4-407
4-409

UNTIL

4-411
----------------------------------------------

VAL%

4-413

4-415
4-417

4-419
4-421
4-426

4-428

Appendix A

Transporting Programs Between VAX BASIC and BASIC-PLUS-2

A.1

OVeIVIeW . . . . .

A-1

A.2

Language-Specific Functionality .........
.. e
e e e e

A-2

VO Differences . . . ...

A.6

Appendix B

A-3

The MAGTAPE Function . . .. ........
...
uu....
..

A-3

A.3.2

The OPEN Statement . . . ... ........
... ..........
.
The PUT Statement . .. ..........
.. ...
.....
. ....

A-6

A.3.3
A4

...

A.3.1

Procedure Calling.

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

A—4

nn...

A-6

A.4.1

The CALL Statement . .........
... ....
uuun...

A—6

A.4.2

The CHAIN Statement . . .. .......................

A-7

A.4.3

SYSandFIPSYSCalls . ...........co

...

A-7

Generated Errors . .......
0 it
.......
e

A-8

Miscellaneous Differences.

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

A-9
A-10

A.6.1

Data Types . . . . ...ttt
e
e
e

A.6.2

The DEF and DEF* Statements . ....................

A-10

A.6.3

Default Integer Size . .. ........
... .. ... ... . ... ...

A-10

A.6.4

IntegerOverflow

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

A-10

A.6.5

Line Numbersand Labels . ........................

A-10

A.6.6

The MAP and COMMON Statements

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

A-11

A.6.7

The MAP DYNAMIC Statement ... ..................

A-11

A-12

A.6.8

The PRINT Statement

A.6.9

The PRINT USING Statement . .....................

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

A-12

A.6.10

The REPLACECommand ... ..........¢cvvemunnn..

A—12

A.6.11

The SPEC% and PEEK Functions

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

A—12

A.6.12

String Comparisons . . ............
... . .
...

A-12

A.6.13

AssigningSymbols . . . . ...

A-13

A.6.14

The TIME Function

. ..........
.00
nnnn..

A-13

A.6.15

The TIMES Function.

. . ........ ...,

A-13

...

ANSI Minimal BASIC

B.1

Introduction . . . ......... . . . . . . .

B-1

B.2

The /ANSI_STANDARD Qualifier

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

B-2

Extensions To ANSI Minimal BASIC Standard X3.60-1978 .. .......

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

B-2

B.3.1

Program Format

B.3.2

Statements . .. .. ...

B.3.3

Delimiters . ... ...

B.3.4

Variables

B.3.5

NumericConstants . . . .. ... ...
Datalnput ......... ... 0.0 i,
Unquoted StringData . . . .................
B.3.6.1
...
....
...
Nulllnput . ........
B.3.6.2

B.3.6

B.3.7

B.4

e e e
e e
e
e
i it e et

B-3

i e

B-3

ittt

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

B-3

B-5
B-5

User-Defined Functions (the DEF Statement) .. ... .......

B.3.8

Built-in Functions . . . . . ... ...

B.3.9

AITAYS . ottt it

e e

B—7

Implementation-Defined Features . . . . ... ....................
Initial Values for Variables . . . . ... ..................
B.4.1

B-7

B.4.2

B.4.3
B.4.4
B.4.5

B.4.6

Retention of Long Strings . . ... ...... ...

... ...

B-8

Accuracy of Evaluation of Numeric Expressions ..........
...
.
......
...
Machine Infinitesimal ..........
.,
...
..
Machine Infinity . . .. .......
....
..................
Values
Numeric
For
Precision

B-9

Exrad-Width For Printing Numeric Representations . .......
Significance-Width For Printing Numeric Representations . . . .

B-9

i,
....
...
PrintZonelength . .......
... ...,
....
...
...
.......
QutputLine
Margin for

B-9

Pseudorandom Number Sequence . ..................
..
... ... it
Unique Line Numbers . . . . ......

B-10
B-10

B.4.14

.
e
i e
i
....
i
Input Prompt . . ....
i
i
...
.......
.
.
.
EndofinputReply

B.4.15

Endof PrintLine . ........ ...,

B-10

B.4.16

...
...
...
Exponentiation Operator . .. .........

B-10

B.4.7

B.4.8
B.4.9

B.4.10
B.4.11
B.4.12
B.4.13

Appendix C

ASCII Character Codes

Appendix D

VAX BASIC Keywords

B-9
B-9
B-10

B-10

Index

Examples
1—1

Referencing Label Names in VAX BASIC Programs . . ... ........... |

1-2

Using the DECLARE Statement to Set Array Boundaries . ...........

1-20

1-3

Naming Constants Within a Program Unit

1-29

Associating Values with Named Constants . . ....................

1-30

1-5

Naming Constants as Expressions . .. .. e

e e

1-30

1—6

Declaring Constants Outside the Program Unit . .. ................

1-31
1-53

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

e e

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

1-4

1-7

Specifyinga Comment Field

1-8

Using Comments Fields to Formata Program

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

1-53

1-9

Using Empty Statements in a VAX BASIC Program . ... ............

1-54

1-10

Using REM Statements in VAX BASIC Programs

1-55

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

Figures

|
1—1

Representation of the Subscript Variable A%(4%,6%)

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

1-22

1-2

Truth Tables . .. ... ... e
e e

1-48

1—1

Keyword Space Requirements . .. ................
...
...

1-5

Tables

Xii

1-2

VAX BASIC Data Types

1-3

Valid Floating-Point Variable Names

. .. .. oo ittt i

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

1-18

Specifying Floating-Point Constants

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

1-25

1-5

Numbersin ENotation . . ............
... . . ... .
...

1-25

Specifying Integer Constants . . ... .............
... ... .......

1-26

1-7

Predefined Constants . .. ......... ... ... ..

1-34

1-8

Arithmetic Operators . . . . . .. ..o

1-37

1-9

Result Data Types in VAX BASIC Expressions .. .................

1-39

1-10

VAXBASIC Result Data Types

. ..........ottiiiiinnnnnnn..

1-39

1-11

Result Data Types for DECIMAL Data.........................

1—40

1-12

Numeric Relational Operators

1-13

String Relational Operators . .. ..............

1-14

Logical Operators.

e e e e e e e e

...

e e e

. ........
... . ...,
....

1-13

143

i enenn..

145

. . . ... ittt
e e
e e e

1-46

1-15

Numeric Operator Precedence . . ... .. ........
.. ... .. ......

1-51

2-1

Multiplying a Numeric Value with the SCALE Command .. ...........

2-54

4-2

VAX BASIC Parameter-Passing Mechanisms ... .................
FILL tem Formats and Storage Allocations . ....................

4—11

4-31

4-84

... ....... ...
MAGTAPE Functionality in VAXBASIC .. ... ......

4-200
4-290

Rounding and Truncation of 123456.654321 . . . . . ... .............
eei
tt
i i i
VAX BASIC STATUS Bits . . ... ...t

4-7

TIME Function Values . . . ... ..

e e aen e

4400

...
......
MAGTAPE Functionality in VAXBASIC ... .......
RSTS/E Disk MODE Values and Corresponding BASIC Statements . . . ..

A—4

EDITE Values . . ..o o
4-4

4-5

A1
A2

e e et e e e et e

it ittt

4-379

A-5

..
... .. .....
VAX BASIC Subset of RSTS/ESYS Calls .. ........
VAX BASIC Subset of RSTS/EFIPSYS Calls .. .................

A-7

A-9

A-6

Fatal Errors in VAX BASIC that are Warnings in BASIC-PLUS-2 .. ... ..
VAX BASIC and BASIC-PLUS-2 TIME Function Differences ..........

A—13

C-2

ASCIl Characters Reserved for NationalUse . .. .................
e e e e e e
e e
ASCH CodeS . . . ottt e e

C-2

A-3

A—4
A-5

A—-8

C-1

Xiii

Preface

Intended Audience
This manual describes the language elements and syntax of VAX BASIC.

Readers are presumed to be familiar with VAX BASIC programming techniques. This manual provides reference material to be used in conjunction

with the other two manuals in the documentation set.

Associated Documents
This manual is one of three manuals that form the VAX BASIC document

set. The other two manuals are as follows:
VAX BASIC User Manual

Provides tutorial material for VAX BASIC
language constructs and information pertaining
to programming with VAX BASIC on VMS
systems

Programming with VAX BASIC

Provides tutorial and reference material on

Graphics

VAX BASIC graphics capabilities

You may also be interested in the following supplementary manuals:
o

VAX BASIC Syntax Summary

Introduction to BASIC

BASIC for Beginners

More BASIC for Beginners

Document Structure
This manual consists of four chapters and four appendixes.
Chapter 1

Summarizes VAX BASIC program elements and structure

Chapter 2

Describes VAX BASIC environment commands

Chapter 3

Describes VAX BASIC compiler directives

Chapter 4

Describes VAX BASIC statements and functions

Appendix A

Summarizes transportability issues between BASIC-PLUS-2 and
VAX BASIC

Appendix B

Explains how VAX BASIC conforms to the ANSI Minimal

Standard for BASIC
Appendix C

Lists the ASCII codes

Appendix D

Lists VAX BASIC keywords

In Chapters 2, 3, and 4, the VAX BASIC language elements are arranged
in alphabetical order within each part; each language element begins on
a separate page. These chapters provide reference material on each VAX

BASIC language element. The descriptions are arranged in alphabetical
order and include the following sections:
Overview

An overview of what the statement or command does.

Format

The required syntax for the language element.

Syntax
Rules

Any rules governing the use of parameters, separators, or other syntax items, effect of the statement or command on program execution,
and any restrictions governing its use.

Example

One or more examples of the statement in a partial program. Where
appropriate, explanatory text and program output are included.

Conventions
This manual uses case of text, symbols, and mnemonics in syntactical diagrams. This symbology aids in providing more concise and exact descriptions
of syntatic variables, rules, and format.
Convention

$ BASIC

Meaning

In command-line examples, the user’s response to a system
prompt is printed in red; system prompts are printed in black.

Xvi

Convention

Meaning

UPPERCASE

Uppercase letters are used for VAX BASIC keywords and must
be coded exactly as shown.

letters
lowercase letters

Lowercase letters are used to indicate user-supplied names or
characters.

[]

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

A vertical ellipsis indicates that code which would normally be
present is not shown.

An ellipsis indicates that the immediately preceding item
can be repeated. An ellipsis following a format unit enclosed
in brackets or braces means that you can repeat the entire
unit. If repeated items or format units must be separated by
commas, the ellipsis is preceded by a comma (, ... ).

The following mnemonics are used in the syntax diagrams:
Mnemonic

Meaning

angle

An angle in radians or degrees

array

An array; syntax rules specify whether the bounds or dimensions

chnl

An 1/0 channel associated with a file

com

Specific to a COMMON block

can be specified

cond

Conditional expression; indicates that an expression can be either
logical or relational

const

A constant value

data-type

A data type keyword

def

Specific to a DEF function

exp

An expression

file-spec

A file specification

func

Specific to a FUNCTION subprogram

XVii

Mnemonic

Meaning

int

An integer value

int-exp

An expression that represents an integer value

int-var

A variable that contains an integer value

label

An alphanumeric statement label

lex

Lexical; used to indicate a component of a compiler directive

line

A statement line; may or may not be numbered

line-num

A statement line number

lit

A literal value, in quotation marks

log-exp

Logical expression

map

Specific to a MAP statement

matrix

A two-dimensional array

name

A name or identifier; indicates the declaration of a name or the
name of a VAX BASIC structure, such as a SUB subprogram

num

A numeric value

param-list

A parameter list, such as for a SUB subprogram

pass-mech

A valid VAX BASIC passing mechanism

real

A floating-point value

rel-exp

Relational expression

str

A character string

str-exp

An expression that represents a character string

str-var

A variable that contains a character string

sub

Specific to a SUB subprogram

target

The target point of a branch statement; either a line number or a

label

unsubs-var

Unsubscripted variable, as opposed to an array element

var

A variable

Summary of Technical Changes

Summary of New and Changed Features for Version 3.4
Version 3.4 of VAX BASIC includes support for the Program Design Facility
(PDF). This new functionality can be implemented by appending the
/DESIGN qualifier to the DCL command BASIC. See the VAX BASIC User
Manual for more information on the /DESIGN qualifier.

This documentation update also contains numerous corrections and
clarifications to Version 3.3 documentation. These documentation changes
do not reflect new features.

Xix

Chapter

Program Elements and Structure

The building blocks of a VAX BASIC program are as follows:
Program lines and their components
The VAX BASIC character set
VAX BASIC data types

Variables and constants
Expressions

Program documentation

These building blocks are described in the following sections.

1.1

Components of Program Lines
A VAX BASIC program is a series of program lines that contain instructions
for the VAX BASIC compiler. These instructions are in the form of
statements that contain keywords, operators, and operands.
All VAX BASIC program lines can contain the following:
Statements

Line numbers or labels
Compiler directives

Comment fields

A line terminator (carriage return)

Only a line terminator is required in a program line. The other elements
are optional.

Program Elements and Structure

1-1

1.1.1

Line Numbers
Line numbers are no longer required in VAX BASIC programs; you can

compile, link, and execute a program with or without line numbers. There
are, however, different rules for writing programs with line numbers and for
writing programs without line numbers. These differences are described in
the following sections.

1.1.1.1

Programs With Line Numbers

If you are entering program lines directly into the BASIC environment in
line mode, then only those statements with line numbers are allowed to start

in the first column. Also, any programs entered in line mode must have an
initial line number associated with the first program line.

A VAX BASIC line number must be a unique integer from 1 through 32767,

and must be terminated by a space or tab. VAX BASIC ignores leading
spaces, tabs, and zeros in line numbers. Embedded spaces, tabs, and com-

mas cause VAX BASIC to signal an error.

In line mode, a line number followed by a carriage return does not constitute

a VAX BASIC program line. A program line entered in line mode must
contain a statement or a comment field. (Comment fields are discussed in

Section 1.7.1). A new line number or a carriage return terminates a VAX
BASIC program line.

A program line can contain any number of text lines; however, a text line
cannot exceed 255 characters.

1.1.1.2

Programs Without Line Numbers
VAX BASIC searches for a line number on the first line of program text
when you
*

Load a program into the BASIC environment with the OLD command.

Edit a program in the BASIC environment.

If no line number is found, then the following rules apply:

1-2

No line numbers are allowed in that program module.

References to the ERL function and a RESUME statement to a line
number are not allowed.

Program Elements and Structure

A subroutine will signal the same errors as it would if it were compiled
with the /NOLINES qualifier. If an error is resignaled back to the caller,

ERL gives the line number of the calling site, rather than the line number of the actual error in the subprogram.
¢

The REM statement is not allowed.

If your program contains multiple units, the point at which VAX BASIC

breaks each program unit is determined by the placement of the statement

that terminates each program unit. Any text that follows the program

terminator becomes associated with the the following program unit. A
program terminator can be any END statement, such as an END PROGRAM

statement followed by any valid expression.
You cannot use the APPEND command in the BASIC environment, or a plus

sign (+) at DCL level, to concatenate programs without line numbers.
Note that when you compile a program from DCL, or when you copy a
program into the BASIC environment with the OLD command, program

statements can begin in the first column.
Instead of line numbers, you can use labels to identify and reference pro-

gram lines.

1.1.2

Labels
A label is a 1- to 31-character name that identifies a statement or block
of statements. The label name must begin with a letter; the remaining
characters, if any, can be any combination of letters, digits, dollar signs ($),
underscores (_), or periods (.). If the program is being entered in line mode,
and therefore contains line numbers, then only line numbers and immediate
mode statements can begin in the first character position.
A label name must be separated from the statement it identifies with a colon
(:). For example:
Yes_routine:

"Your

answer

YES."

The colon is not part of the label name. It informs VAX BASIC that the

label is being defined rather than referenced. Consequently, the colon is not

allowed when you use a label to reference a statement. For example:
200

GOTO Yes_routine

Program Elements and Structure

1-3

You can reference a label almost anywhere you can reference a line number.
However, there are the following exceptions:

You cannot compare a label with the value returned by the ERL function.

You cannot reference a label in an IF... THEN... ELSE statement without
using the keyword GOTO or GO TO. You can use the implied GOTO
form only to reference a line number. In Example 1-1, the GOTO
keyword is not required in statement 100 because the reference is to a
line number. However, the GOTO keyword is required in statement 200

because the references are to labels.
Example 1-1:
100

200

1.1.3

IF A%

Referencing Label Names in VAX BASIC Programs

= B%

THEN

1000

ELSE

1050

IF A$

THEN

GOTO

"YES"

ELSE

GOTO No

Yes

Statements
A VAX BASIC statement consists of a statement keyword and optional
operators and operands. For example, both of the following statements are

valid:
LET A%

534%

(SUM%

DIF%)

PRINT A%

VAX BASIC statements can be either executable or nonexecutable:
*

Executable statements perform operations (for example, PRINT, GOTO,

and READ).
*

Nonexecutable statements describe the characteristics and arrangement

of data, specify usage information, and serve as comments in the source
program (for example, DATA, DECLARE, and REM).

VAX BASIC can accept and process one statement on a line of text, several
statements on a line of text, multiple statements on multiple lines of text,

and single statements continued over several lines of text. Each line of
program text is associated with the last specified line number, and each

must contain a keyword.

1-4

Program Elements and Structure

1.1.3.1

Keywords

Every VAX BASIC statement except LET and empty statements must
begin with a keyword. A keyword is a reserved element of the VAX BASIC
language. Keywords are used to
¢

Define data and user identifiers.

Perform operations.

Invoke built-in functions.
NOTE

Keywords are reserved words and cannot be used as user identifiers, such as variable names, labels, or names for MAP or
COMMUON areas.

Keywords cannot be used in any context other than as VAX BASIC keywords. The assignment STRING$ = “YES”, for example, is invalid because
STRINGS is a reserved VAX BASIC keyword and therefore cannot be used
as a variable. Appendix D in this manual contains a list of the VAX BASIC
keywords.

A VAX BASIC keyword cannot have embedded spaces and cannot be split
across lines of text. There must be a space, tab, or special character such as
a comma between the keyword and any other variable or operator.
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

Required Space

No Space

GO TO

BY DESC

FNEND

GO SUB

BY REF

FNEXIT

ON ERROR

BY VALUE

FUNCTIONEND

END DEF

FUNCTIONEXIT

END FUNCTION

NOECHO

END GROUP

NOMARGIN

(continued on next page)

Program Elements and Structure

1-5

Table 1-1 (Cont.):

Keyword Space Requirements

Optional
Space

Required Space

No Space

END IF

SUBEND

END PROGRAM

SUBEXIT

END RECORD
END SELECT

END SUB
EXIT DEF

EXIT FUNCTION
EXIT SUB
INPUT LINE

MAP DYNAMIC
MAT INPUT

MAT LINPUT
MAT PRINT
MAT READ

Identifying Program Units

You can delimit a main program compilation unit with the PROGRAM and
END PROGRAM statements, as shown in the following example:
PROGRAM

END

Sort_ out

PROGRAM

This allows you to identify a program with a name other than the file
name. The PROGRAM name must not be the same as that of any SUB,

FUNCTION, or PICTURE subprogram.
If you include the PROGRAM statement in your program, the name you

specify becomes the module name of the compiled source. This feature is
useful when you use object libraries, because the librarian stores modules
by their module names rather than by their file names. Similarly, module
names are used by the VMS Debugger and the VMS Linker.
For more information about program units, see the VAX BASIC User

Manual.

1-6

Program Elements and Structure

Single-Statement Lines and Continued Statements

red line, or
A single-statement line consists of one statement on one numbe
e:
exampl
one statement continued over two or more text lines. For
30 PRINT B * C / 12

This single-statement line has a line number, the keyword (PRINT), the
operators (¥, /), and the operands (B, C, 12).

typing an amYou can have a single statement span several text lines by or
tabs are valid
spaces
only
that
Note
key.
persand (&) and the RETURN
le:
examp
For
.
return
ge
carria
between the ampersand and the
OPEN "SAMPLE.DAT" AS FILE 2%, &|RET
SEQUENTIAL VARIABLE, & [RET]
MAP ABC

is not required for
The ampersand continuation character may be used but
valid:
continued REM statements. The following example is
REM This is a remark

And this is also a remark

continue a
You can continue any VAX BASIC statement, but you cannot
le generates the

string literal or VAX BASIC keyword. The following examp
error message “Unterminated string litera ”,
PRINT "IF-THEN-ELSE- &
END-IF"

PRINT "IF-";
"THEN-";

"ELSE-";
IIEND_ " ;

R
R

This example is valid:

" IF "

A more efficient way to continue string literals 1s to use the string concat
nation operator (+) as follows:
PRINT

"IF-"

"THEN-"

"ELSE-"

"END- "

" IF"

- I s
g

.1.3.3

ation and stores
VAX BASIC concatenates the four string literals at compil
es, VAX BASIC
them as one string. When the PRINT statement rexecut
than four separate string
displays the one concatenated string literal rathee faster
and more efficiently.
literals, thereby causing your program to execut
Program Elements and Structure

1-7

1.1.3.4

Multi-Statement Lines

Multi-statement lines contain several state
ments on one line of text or
multiple statements on separate lines
of text. All the statements on a
multi-statement line are associated with
a single line of code.
Multiple statements on one line of text

must be separated by backslashes

(\). For example:
40

PRINT A

PRINT V

\ PRINT

Because all statements are on the same

number 40 refers to all three statements

program line, any reference to line

and execution begins with the first
statement on the line. For example,
VAX BASIC cannot execute the secon
d
statement without executing the first
statement.

You can also write a multi-statement progr
ments with a single line number by

am line that associates all state-

placing each statement on a separ

ate

line. VAX BASIC assumes that such an

new statement or an IF statement

unnumbered line of text is either a

clause.

In the following example, each line of text

ment and each statement is associ

begins with a VAX BASIC state-

ated with line number 400.

400

PRINT A
PRINT B
PRINT

"FINISHED"

VAX BASIC also recognizes IF statement
associates such keywords with the prece

keywords on a new line of text and

ding IF statement. For example:

100

REM

Determine
was

200

(A$

"YES")

if the user’s

YES

(AS

response

NO.

THEN

"You

typed

ELSE

"You

typed NO"

"Yy")

YES"

STOP

END

The VAX BASIC compiler assigns listin
g line numbers to the statements as
they occur physically in the program. For
example:

1-8

100

REM

Determine
was

200

(A$

YES

"YES")

if the

NO.

(A$

user’s

"y")

THEN PRINT

"You

typed YES"

ELSE

"You

typed NO"

STOP
END

Program Elements and Structure

response

You cannot use listing line numbers as targets of branch statements. The
target of a branch statement such as GOTO must be a line number or a
label. See the VAX BASIC User Manual for more information on listing file
formats.

You can use any VAX BASIC statement in a multi-statement line. Since
the VAX BASIC compiler ignores all text following a REM keyword until it
reaches a new line number, a REM statement must be the last statement on
q multi-statement line. REM statements are disallowed in programs without
line numbers.

In the environment, a leading space or tab not followed by a line number
implies a new statement in a multi-statement line, compiler commands and
immediate mode statements cannot be preceded by a space, tab, or line
number. If you enter a compiler command or immediate mode statement,
you cannot add more continuation lines to the last program line. If you

attempt to do so, VAX BASIC signals the error “Unknown command input.”

1.1.4

Compiler Directives

Compiler directives are instructions for the VAX BASIC compiler. These
instructions cause the VAX BASIC compiler to perform certain operations as
it compiles the program.

By including compiler directives in a program, you can:

Place program titles and subtitles in the header that appears on each

Place a program version identification string in both the listing file and

Start or stop the inclusion of listing information for selected parts of a

page of the listing file
object module
program

e
e

Start or stop the inclusion of cross reference information for selected

parts of a program

Include VAX BASIC code from another source file or a text library

Conditionally compile parts of a program

Terminate compilation

e
e

Include CDD record definitions in a VAX BASIC program
Display messages during the compilation

Follow these rules when using compiler directives:
e Compiler directives must begin with a percent sign
Program Elements and Structure

1-9

Compiler directives must be the only text on the line (except
for
%1F-%THEN-%ELSE-%END-%IF)

Compiler directives cannot appear within a quoted string

Compiler directives can be preceded by an optional line number

See the VAX BASIC User Manual and Chapter 2 in this manual
for more
information on compiler directives.

1.1.5

Line Terminators
In the BASIC environment, a program line ends with a carriage
return/line
feed combination (the RETURN key) followed by an optional space
or tab
or a new line number. An ampersand followed by a carriage return
ends a
line of text, but not the program line. Note that spaces and tabs
are valid
between the ampersand and the carriage return; no other characte
rs are
valid. When line numbers are present, all statements between
the first line
number and the next line number are associated with the
first line number.

1.1.6

Lexical Order
Lexical order refers to the order in which the statements in a program

are compiled. In general terms, VAX BASIC compiles program
lines in
sequential order: multiple statements on a line of text are processe
d from

left to right, and lines of text are processed from top to bottom.
Note
that certain VAX BASIC statements can alter this flow of compilati
on,
example GOSUB and GOTO.

for

Some VAX BASIC statements, such as comments and MAP declarati

ons, are

nonexecutable. If program control passes to a nonexecutable
statement, the

VAX BASIC compiler executes the first statement that lexically follows
nonexecutable statement.

1.2

VAX BASIC Character Set
VAX BASIC uses the full ASCII character set. This includes

1-10

The letters A through Z, both upper- and lowercase

The digits 0 through 9

Special characters

Program Elements and Structure

the

Appendix C in this manual lists the full ASCII character set and character
values.

The VAX BASIC compiler does not distinguish between upper- and lowercase
letters except in string literals or within a DATA statement. The VAX
BASIC compiler does not process characters in REM statements or comment

fields, nor does it process nonprinting characters unless they are part of a
string literal.

In string literals, VAX BASIC processes:
e

T.owercase letters as lowercase

Nonprinting characters

The ASCII character NUL (ASCII code 0) and line terminators cannot

appear in a string literal. Use the CHR$ function or explicit literal notation

to use these characters and terminators.

You can use nonprinting characters in your program, for example, in string
constants, but to do so you must use one of the following:
e

A predefined constant such as ESC or DEL

The CHR$ function to specify an ASCII value

Explicit literal notation

See Section 1.5.4 for more information on explicit literal notation.

1.3

VAX BASIC Data Types
Each unit of data in a VAX BASIC program has a specific data type that
determines how that unit of data is to be interpreted and manipulated by
the VAX BASIC compiler. This data type also determines how many storage

bits make up the unit of data.

VAX BASIC recognizes five primary data types:
e

Integer

Floating-point

Character string

Packed decimal

Record’s file address

Integer data is stored as binary values in a byte, word, or longword. These
values correspond to the VAX BASIC data type keywords BYTE, WORD,
and LONG: these are all subtypes of the type INTEGER.
Program Elements and Structure

1-11

Floating-point values are stored using a signed exponent and a binary
fraction. VAX BASIC allows four floating-point formats: single, double,

G_floating, and H_floating. These formats correspond to the VAX BASIC
data type keywords SINGLE, DOUBLE, GFLOAT, AND HFLOAT:; these are

all subtypes of the type REAL.

VAX BASIC packed decimal data is stored in a string of bytes. Refer to the
VAX BASIC User Manual for more information on the storage of packed
decimal data.
Character data consists of strings of bytes containing ASCII code as binary
data. The first character in the string is stored in the first byte, the second
character is stored in the second byte, and so on. VAX BASIC allows up to

65535 characters for a STRING data element.

In addition to this data type, VAX BASIC also recognizes a special RFA data

type to provide information about a record’s file address. An RFA uniquely

specifies a record in a file: you can access RMS files of any organization
by record’s file address. By specifying the disk address of a record, RMS
retrieves the record at that address. Accessing records by RFA is more

efficient and faster than other forms of random record access. The RFA data

type can only be used for

RFA operations (the GETRFA function and the GET and FIND
statements)

*
*

Assignments to other variables of the RFA data type
Comparisons with other variables of the RFA data type with the equal to

(=) and not equal to (<>) relational operators
*

Formal and actual parameters

DEF and function results

You cannot declare a constant of the RFA data type, nor can you use RFA
variables for any arithmetic operations.
The RFA data type requires 6 bytes of information. See the VAX BASIC
User Manual for more information on Record File Addresses and the RFA
data type.

For the DECIMAL(d,s) data type, you can specify the total number of digits
(d) in the data type and the number of digits to the right of the decimal

point (s). For instance, DECIMAL(10,3) specifies decimal data with a total

of 10 digits, 3 of which are to the right of the decimal point.

1-12

Program Elements and Structure

Table 1-2 lists VAX BASIC data type keywords and summarizes VAX BASIC
data types.

Table 1-2:

VAX BASIC Data Types
Precision

Data Type

(decimal)

(digits)

Size

Range

BYTE

8 bits

WORD
LONG

16 bits
32 bits

-128 to +127
-32768 to +32767

Keyword
Integer

2147483648 to

NA
NA

+2147483647

Real

.29 #1038 to

29 *10738 to

64 bits

56 *1073% ¢o

128 bits

1074982 o

0tol6

1*1073 tol *

One

‘Max = 65535

SINGLE

32 bits

DOUBLE

64 bits

GFLOAT
HFLOAT

1.7 *10%

.90 * 10398

59 * 104932

Decimal

DECIMAL(d,s)

bytes

103

String

STRING

character

per byte

RFA

6 bytes

In Table 1-2, REAL and INTEGER are generic data type keywords that
specify floating-point and integer storage, respectively. If you use the
REAL or INTEGER keywords to type data, the actual data type (SINGLE,
Program Elements and Structure

1-13

DOUBLE, GFLOAT, HFLOAT, BYTE, WORD, or LONG) depends
on the
current default. If you do not explicitly type one of the appropri
ate subtypes,
VAX BASIC uses the current subtype defaults for REAL and INTEGER
.

You can specify data type defaults in the BASIC environment with
the
SET and COMPILE commands, or from DCL level with the DCL
command
BASIC. You can also specify whether program values are to be
typed

implicitly or explicitly. The following sections discuss data type
defaults and
implicit and explicit data typing.

1.3.1

Implicit Data Typing
You can implicitly assign a data format to program values by

adding a suffix
to the variable name or constant value. If you do not specify any
suffix, the
variable or constant is assigned the current default data type. The
following
rules apply for implicit data typing:
*

Adollar sign suffix ($) specifies STRING

A percent sign suffix (%) specifies INTEGER storage.

storage.

special suffix character specifies storage of the default type, which
can be INTEGER, REAL, or DECIMAL.

With implicit data typing, the range and precision for program

values are
determined by the corresponding default data sizes or subtypes:
*

BYTE, WORD, or LONG for INTEGER values

SINGLE, DOUBLE, GFLOAT, or HFLOAT for REAL values

The default (d,s) values for DECIMAL values

The default data type is determined by one of the following:
*

The system default (REAL)

The data type set for the BASIC environment with the SET or COMPILE
compiler command

The data type set for the BASIC environment with the BASIC statemen

OPTION

The data type set for VAX BASIC with a qualifier for the DCL command
BASIC

The VAX BASIC qualifiers for the SET and COMPILE commands are

described in Chapter 2 of this manual. The qualifiers for the DCL command
BASIC are listed in the VAX BASIC User Manual.

1-14

Program Elements and Structure

Note that if you compile your program with the /TYPE_DEFAULT=
EXPLICIT qualifier (on either the DCL command BASIC or VAX BASIC
command COMPILE), you can still add the appropriate suffixes to your
variable names or constant values. The suffixes are useful because they
identify the data type of the variable or constant immediately; the reader
does not have to refer to the declarations at the top of the program to see
which data type applies to a particular program value. However, with the
/TYPE_DEFAULT=EXPLICIT qualifier, you must still explicitly assign data
types to all program values or VAX BASIC signals an error.

It is considered good programming practice to use explicit data typing
because implicit data typing is dependent on compilation defaults. These
defaults may change, thereby affecting the precision of the program values.

1.3.2

Explicit Data Typing

Explicit data typing means that you use a declarative statement to spec-

ify the type, range, and precision of your program values. Declarative
statements associate attributes such as data type and value with user
identifiers.

In the following example, the first DECLARE statement associates the
constant value 03060 and the STRING data type with a constant named
zip_code. The second DECLARE statement associates the STRING data type
with emp_name, the DOUBLE data type with with_tax, and the SINGLE
data type with int_rate. No constant values are associated with identifiers
in the second DECLARE statement because they are variable names.
DECLARE STRING CONSTANT zip code = "03060"

DECLARE STRING emp name, DOUBLE with_tax, SINGLE int_rate

With explicit data typing, each program variable within a program can

have a different range and precision. You can explicitly assign data types to
variables, constants, arrays, parameters, and functions; therefore, integer
data does not have to take the compilation default types. Explicit data
typing gives you more control over your program.

Using the REAL and INTEGER keywords to explicitly type program values
allows you to write programs that are transportable across systems, because
these data type keywords specify that all floating-point and integer data take
the current defaults for REAL and INTEGER. The data type INTEGER, for
example, specifies only that the constant or variable is an integer. The
actual subtype (BYTE, WORD, or LONG) depends on the default set with
the COMPILE or SET command, the DCL command BASIC, or with the
OPTION statement.

Program Elements and Structure

1-15

You can also specify a particular data type size for values declared

INTEGER
or REAL with compilation qualifiers. The /DOUBLE qualifier
, for instance,
specifies that all data typed REAL is to be treated as double-p
recision data.

The /TYPE_DEFAULT=EXPLICIT qualifier or OPTION TYPE=E
statement allows you to specify that all program data

XPLICIT

must be explicitly

typed. Compiling a program with /TYPE_DEFAULT= EXPLICI
T or specifying OPTION TYPE=EXPLICIT means that any program value
not explicitly
declared causes VAX BASIC to signal an error.

For new applications, DIGITAL recommends using VAX BASIC’s
explicit data typing features. See the VAX BASIC User Manual
for more
information.

1.4

Variables
A variable is a named quantity whose value can change during

program

execution. Each variable name refers to a location in
the program’

s storage
area. Each location can hold only one value at a time.
Variables of all data
types can have subscripts that indicate their position in an
array. You can

declare variables implicitly or explicitly.

Depending on the program operations specified, the value
of a variable can
change from statement to statement. VAX BASIC uses the
most recently
assigned value when performing calculations. This value
remains in effect
until a new value is assigned to the variable.
VAX BASIC accepts the following general types of variables:
*

Floating-point

Integer

String

RFA

Packed decimal

Record

See the VAX BASIC User Manual for more information on RFA
variables
and RECORD data structures.

1-16

Program Elements and Structure

|1.4.1

Variable Names

The name given to a variable depends on whether the variable is internal or
external to the program and whether the variable is implicitly or explicitly
declared.

All variable names must conform to the following rules:
The name can have from 1 to 31 characters.
The name has no embedded spaces.

e
e

The first character of the name must be an upper- or lowercase alpha-

The last character of the name can be either a dollar sign ($) to indicate
a string variable or a percent sign (%) to indicate an integer variable. If

betic character (A through Z).

the last character is neither a dollar sign nor a percent sign, the name
indicates a variable of the default type.

The remaining characters, if present, can be any combination of upperor lowercase letters (A through Z), numbers (0 through 9), dollar signs
($), underscores (_), or periods (.). The use of underscores in variable
names helps improve readability and is preferred to the use of periods.
The name of an external, explicitly declared variable in VAX BASIC
must follow the rules for naming any explicitly declared variable.

Note that a program cannot have external, implicitly declared variables
since all implicitly declared names except SUB subprogram names are

internal to the program.

1.4.2

Implicitly Declared Variables
VAX BASIC accepts three types of implicitly declared variables:
e

Integer

String

Floating-point (or the default data type)

The name of an implicitly declared variable defines its data type. Integer
variables end with a percent sign (%), string variables end with a dollar

sign ($), and variables of the default type (usually floating-point) end with
any allowable character except a percent sign or dollar sign. All three types
of variables must conform to the rules listed in Section 1.4.1 for naming
variables. The current data type default INTEGER, REAL, or DECIMAL)
Program Elements and Structure

1-17

determines the data type of implicitly declared variables that

a percent sign or dollar sign.

do not end in

A floating-point variable is a named location that stores a

single floatingpoint value. The current default size for floating-point numbers
(SINGLE,
DOUBLE, GFLOAT or HFLOAT) determines the data type
of the floatingpoint variable. Table 1-3 lists valid floating-point variable
names:

Table 1-3:

Valid Floating-Point Variable Names

L...5

ID_NUMBER

BIG47

STORAGE_LOCATION_FOR_XX

F67T_J

Z2.

STRESS_VALUE

If a numeric value of a different data type is assigned to a
floating-point
variable, VAX BASIC converts the value to a floating
-point number.

An integer variable is a named location that stores a single

integer value.
The current default size for integers (BYTE, WORD, or LONG)
determines
the data type of an integer variable. The following are valid
integer variable
names:

ABCDEFG%

C_8%

RECORD_NUMBER%

D6E7%

THE_VALUE_I_WANT%

If the default data type is INTEGER, the percent suffix (%)

is not necessary.

If you assign a floating-point or decimal value to an integer
variable, VAX
BASIC truncates the fractional portion of the value. It does
not round to the

nearest integer. For example:
100

-5.7

VAX BASIC assigns the value —5 to the integer variable, not

—6.

A string variable is a named location that stores strings. The
following are
valid string variable names:
C1$

EMPLOYEE_NAMES$

L_6$

F34G$

TARGET_RECORDS$

ABC1$

T.$

STORAGE_SHELF_IDENTIFIER$

Strings have both value and length. VAX BASIC sets all string
variables to
a default length of zero before program execution begins, with the
exception
of those variables in a COMMON, MAP, virtual array, or record
definition.
See the COMMON statement and the MAP statement in Chapter
4 of this
manual for information on string length in COMMON and MAP
areas. See
1-18

Program Elements and Structure

the VAX BASIC User Manual for information on default string length in
virtual arrays.

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.

1.4.3

Explicitly Declared Variables
VAX BASIC lets you explicitly assign a data type to a variable or an array.
For example:
DECLARE DOUBLE Interest_rate

Data type keywords are described in Section 1.1.3.1. For more information
on explicit declaration of variables, see the sections on the COMMON,
DECLARE, DIMENSION, DEF, FUNCTION, EXTERNAL, MAP, and SUB
statements in Chapter 4 of this manual. See also the VAX BASIC User
Manual.

1.4.4

Subscripted Variables and Arrays
A subscripted variable references part of an array. Arrays can be of any
valid data type. Subscripted variables and arrays follow the same naming
conventions as unsubscripted variables. Subscripts follow the variable name
in parentheses and define the variable’s position in the array. When you
create an array, you specify the maximum size of the array (the bounds) in
parentheses following the array name.

In Example 1-2, the DECLARE statement sets the bounds of the array
emp_name to 1000. Therefore, the maximum value for an emp_name

subscript is 1000. The bounds of the array define the maximum value for a
subscript of that array.

Program Elements and Structure

1-19

Example 1-2:

Using the DECLARE Statement to Set Array Boundaries

DECLARE

emp name (1000)

FOR

STRING

INPUT
NEXT

1000%

"Employee

name";em
name (I%)
p

Subscripts can be any positive LONG integer value between 0 and
2147483647.

NOTE

By default, VAX BASIC signals an error if a subscript is bigger
than the allowable range. Note, however, that the amount of
storage the system can allocate depends on available memory.

Therefore, very large arrays may cause an internal allocation
error even though the subscript is still within the specified range.

An array is a set of data ordered in any number of dimensions. A onedimensional array, like emp_name(1000), is called a list or vector. A twodimensional array, like payroll_data(5,5), is called a matrix. An array of

more than two dimensions, like big_array(15,9,2), is called a tensor.

As a default, VAX BASIC arrays are always zero-based. The number of
elements in any dimension includes element number zero. For example,
the array emp_name contains 1001 elements, since VAX BASIC allocates

element zero. Payroll_data(5,5) contains 36 elements because VAX BASIC

allocates row and column zero.

Often, however, applications call for arrays that are not zero-based. In VAX
BASIC, you can define arrays that are not zero-based by specifying a lower

bound, as well as an upper bound, for the subscripts. In this way, you can

create an array with arbitrary starting and ending points. For example,
you might want to create array birth_rate that holds the annual birth rate

statistics for the years 1950 through 1985:
DECLARE

birth rate (1950

1985)

Lower bounds are not allowed with virtual arrays or arrays used in MAT
statements. However, you can specify lower bounds for any or all dimensions of a compile-time dimensioned array. If a multi-dimensional array is
declared with lower bounds specified for some dimensions and not others,

zero will be used for those dimensions without lower bounds.

You can use the UBOUND and LBOUND functions to determine the upper
and lower bounds of an array. For a description of these funtions, see
Chapter 4 of this manual.

1-20

Program Elements and Structure

For all arrays except virtual arrays, the total number of array elements
cannot exceed 2147483647. Note, however, that this is a theoretical value;
the actual maximum size of an array which you can declare depends on the
configuration of your system.

VAX BASIC arrays can have up to 32 dimensions. You can specify the type
of data the array contains with data type keywords. Table 1-2 lists VAX
BASIC data types.

An element in a one-dimensional array has a variable name followed by one
subscript in parentheses. There can be a space between the array name and
the subscripts. For example:

A(6%)
B

(6%)

A(6%) refers to the seventh item in this list:
A(0%)

A(1%)

A(2%)

A(3%)

A(4%)

A(5%)

A(6%)

An element in a two-dimensional array has two subscripts, in parentheses,
following the variable name. The first subscript specifies the row number
and the second subscript specifies the column. Use a comma to separate

the subscripts. You can include a space between the array name and the
subseripts if you like. For example:

(7%,2%)

A% (4%, 6%)

(10%,10%)

In figure Figure 1-1, the arrow points to the element specified by the
subscripted variable A%(4%,6%):

Program Elements and Structure

1-21

Figure 1-1:

Representation of the Subscript Variable A%(4%,6%)

COLUMNS
0123456

RO
O1
W2
S3
4

0000000
00000O00O
0000000
0000000

00000 0 0e— A%(4%, 6%)
ZK-5549-GE

An element in an array has as many subscripts as there are dimensions.
Although a program can contain a variable and an array with the same

name, this is poor programming practice. Variable A and the array A(3%,3%)
are *separateTM entities and are stored in completely separate locations, so it
is a good idea to give them different names.

Note that a program cannot contain two arrays with the same name but a

different number of subscripts. For example, the arrays A(3%) and A(3%,3%)
are invalid in the same program.

VAX BASIC arrays can be redimensioned at run time. See the VAX BASIC
User Manual for more information on arrays.

1.4.5

Initialization of Variables
VAX BASIC sets variables to zero or null values at the start of program
execution. Variables initialized by VAX BASIC include:

1-22

Numeric variables and in-storage array elements (except those in MAP
or COMMON statements).

String variables (except those in MAP or COMMON statements).

Variables in subprograms. Subprogram variables are initialized to zero
or the null string each time the subprogram is called.

Program Elements and Structure

VAX BASIC does not initialize the following:

1.5

Virtual arrays

Variables in MAP and COMMON areas

Constants
A constant is a numeric or character literal that does not change during
program execution. A constant can also be named and associated with a
data type. VAX BASIC allows the following types of constants:
¢

Numeric:
—

Floating-point

—

Integer

—

Packed decimal

String (ASCII characters enclosed in quotation marks)

A constant of any of the above data types can be named with the DECLARE
CONSTANT statement. You can then refer to the constant by name in your
program. Refer to Section 1.5.3 for information on naming constants.

You can use the OPTION statement to declare a default data type for all
constants in your program. This statement allows you to specify a data type
for only the constants in your program; you can specify a different data type
for variables. You can also use a special numeric literal notation to specify
the value and data type of a numeric literal. Numeric literal notation is
discussed in Section 1.5.4.

If you do not specify a data type for a numeric constant with the DECLARE
CONSTANT statement or with numeric literal notation, the type and size of
the constant is determined by the default REAL, INTEGER, or DECIMAL
type set with the DCL command BASIC, the VAX BASIC SET or COMPILE
commands, or the OPTION statement.

To simplify the representation of certain ASCII characters and mathematical
values, VAX BASIC also supplies some predefined constants.

The following sections discuss numeric and string constants, named
constants, numeric literal notation, and predefined constants.

Program Elements and Structure

1-23

1.5.1

Numeric Constants
A numeric constant is a literal or named constant whose value never

changes. In VAX BASIC, a numeric constant can be a floating-point number
an integer, or a packed decimal number. The type and size of a numeric

constant is determined by

®*

The system default values

The defaults set by the qualifiers for the DCL command BASIC

The data type qualifiers specified with the COMPILE command

The defaults set by the SET command

The data type specified in

a DECLARE CONSTANT or OPTION

statement

Numeric literal notation

If you use a declarative statement to name and declare the data type of
a numeric constant, the constant is of the type and size specified in the

statement. For example:

DECLARE

BYTE

CONSTANT

age

This example associates the numeric literal 12 and the BYTE data type with
the identifier age. To specify a data type for an unnamed numeric constant,
you must use the numeric literal notation format described in Section 1.5.4.

1.5.1.1

Floating-Point Constants

A floating-point constant is a literal or named constant with one or more

decimal digits, either positive or negative, with an optional decimal point
and an optional exponent (E notation). If the default data type is integer,
VAX BASIC will treat the literal as an INTEGER unless it contains a
decimal point or the character E. If the default data type is DECIMAL, an E
is required or VAX BASIC treats the literal as a packed decimal value.
Table 14 contains examples of floating-point literals with REAL, INTEGER,

and DECIMAL default data types.

1-24

Program Elements and Structure

Table 1-4:

Specifying Floating-Point Constants

REAL

INTEGER

DECIMAL

—8.738

239.21E-6

.79

T9E

299

299K

299E

Very large and very small numbers can be represented in E (exponential) notation. If a positive number appears in E notation, it can be preceded by an
optional plus sign (+). A negative number in E notation must be preceded
by a minus sign (—). A number can be carried to a maximum of 6 decimal
places for SINGLE precision, 16 decimal places for DOUBLE precision, 15
decimal places for GFLOAT precision, and 33 places for HFLOAT precision.
To indicate E notation, a number must be followed by the letter E. It also
must be followed by an exponent sign and an exponent. The exponent sign
indicates if the exponent is either positive or negative and is optional only if
you are specifying a positive exponent. The exponent is an integer constant
(the power of 10).

Table 1-5 compares numbers in standard and E notation.
Table 1-5:

Numbers in E Notation

Standard Notation

E Notation

.0000001

1E-06

1,000,000

1E+07

-10,000,000

-1E+08

100,000,000

1E+09

1,000,000,000,000

JE+13

The range and precision of floating-point constants are determined by the
current default data types or the explicit data type used in the DECLARE
CONSTANT statement. However, there are limits to the range allowed for
numeric data types. Table 1-2 lists VAX BASIC data types and ranges. VAX
BASIC signals the fatal error “Floating point error or overflow” (ERR=48)
when your program attempts to specify a constant value outside of the
allowable range for a floating-point data type.

Program Elements and Structure

1-25

1.5.1.2

Integer Constants

An integer constant is a literal or named constant, either positive or nega-

tive, with no fractional digits and an optional trailing percent sign (% ). The
percent sign is required for integer literals only if the default type is not
INTEGER.

In Table 1-6, the values are all integer constants. The presence of the

percent sign varies depending on the default data type.

Table 1-6:

Specifying Integer Constants
REAL or

INTEGER

DECIMAL

81257

81257%

—3477

—3477%

79%

The range of allowable values for integer constants is determined by either
the current default data type or the explicit data type used in the DECLARE

CONSTANT statement. Table 1-2 lists VAX BASIC data types and ranges.
VAX BASIC signals an error for a number outside the applicable range.
If you want VAX BASIC to treat numeric literals as integer numbers, you
must do one of the following:
*

Set the default data type to INTEGER

Make sure the literal has a percent sign suffix

Use explicit literal notation

The VAX BASIC compiler must convert numeric literals when assigning
them to integer variables. This means that your program runs somewhat
slower than it would if integer values were explicitly declared. You can
prevent this conversion step by using one of the following:
*

Percent signs for integer constants

®*

Numeric literal notation

Named integer constants

NOTE
You cannot use percent signs in integer constants that appear

in DATA statements. An attempt to do so causes VAX BASIC to
signal “Data format error” (ERR=50).

1-26

Program Elements and Structure

1.5.1.3

Packed Decimal Constants

A packed decimal constant is a number, either positive or negative, that has
a specified number of digits and a specified decimal point position (scale).
You specify the number of digits (d) and the position of the decimal point
(s) when you declare the constant as a DECIMAL(d,s). If the constant is not
declared, the number of digits and the position of the decimal is determined
by the representation of the constant.

For example, when the default data type is DECIMAL, 1.234 is a
DECIMAL(4,3) constant, regardless of the default decimal size. Likewise,
using numeric literal notation, "1.234"P is a DECIMAL(4,3) constant, regardless of the default data type and default DECIMAL size. Numeric literal
notation is described in Section 1.5.4.

1.5.2

String Constants
String constants are either string literals or named constants. A string
literal is a series of 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 (’ this
is a "text" string’) and vice versa ("this is a ’text’ string"). Note, however,
that VAX BASIC does not accept incorrectly paired quotation marks and
that only the outer quotation marks must be paired. For example, the
following character strings are valid:
"The

record number does not

exist."”

"I'm here!"

"The terminating ’condition’
"REPORT

is equal to A$."

543"

However, the following strings are not valid:
"Quotation marks that do not match’
"No closing quotation mark

Characters in string constants can be letters, numbers, spaces, tabs, 8-bit
data characters, or the NUL character (ASCII code 0). If you need a string
constant that contains a NUL, you should use the NUL predefined constant.
See Section 1.5.4 in this manual for information on explicit literal notation.

Program Elements and Structure

1-27

The VAX BASIC compiler determines the value of the string constant 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-FILE

"END-OF-FILE

REACHED

REACHED"

VAX BASIC stores every character between delimiters exactly as you type it

into the source program, including:

Lowercase letters (a—z)

Leading, trailing, and embedded spaces

Tabs

Special characters

The delimiting quotation marks are not printed when the program is
executing. The value of the string constant does not include the delimiting
quotation marks. For example:
PRINT

"END-OF-FILE

REACHED"

END

Output
END-OF-FILE

REACHED

VAX BASIC does, however, print double or single quotation marks when
they are enclosed in a second paired set. For example:
PRINT

‘FAILURE

CONDITION:

"RECORD

END

Output
FAILURE

1-28

CONDITION:

"RECORD

Program Elements and Structure

LENGTH"

LENGTH"'

1.5.3

Named Constants
VAX BASIC allows you to name constants. You can assign a name to a

constant that is either internal or external to your program and refer to the
constant by name throughout the program. This naming feature is useful
for the following reasons:

If a commonly used constant must be changed, you need to make only

Alogically named constant makes your program easier to understand.

one change in your program.

You can use named constants anywhere you can use a constant, for example,
to specify the number of elements in an array.

You cannot change the value of an explicitly named constant during program execution. To change the value of a constant, you must change the

program statement that names the constant and declares its value, and then
recompile the program.

1.5.3.1

Naming Constants Within a Program Unit

You name constants within a program unit with the DECLARE statement,
as is shown in Example 1-3.

Example 1-3:

Naming Constants Within a Program Unit

DECLARE DOUBLE CONSTANT preferred_rate = .147
DECLARE SINGLE CONSTANT normal_ rate = .162
DECLARE DOUBLE CONSTANT risky rate = .175

new bal = old bal *

(1 + preferred rate)“years_payment

When interest rates change, only three lines have to be changed rather than
every line that contains an interest rate constant.

Constant names must conform to the rules for naming internal, explicitly

declared variables listed in Section 1.4.1. Note that constant names cannot

have embedded spaces.

The value associated with a named constant can be a compile-time expression as well as a literal value, as shown in Example 1-4.

Program Elements and Structure

1-29

Example 1-4:

Associating Values with Named Constants

DECLARE

CONSTANT

STRING

Congrats

Congratulations!

[" + CR + CR + &

ll+

Congrats

Named constants can save you programming time because you do not have
to retype the value every time you want to display it. Named constants can
save you execution time because the named constant is known at compilation

time.

Valid operators in DECLARE CONSTANT

expressions include all valid
arithmetic, relational, and logical operators except exponentiation. You

cannot use built-in functions in DECLARE CONSTANT

expressions.

VAX BASIC allows constants of all data types except RFA to be named as
expressions. Because you cannot declare a constant of the RFA data type

you cannot name one as an expression. Example 1-5 illustrates the concept

of naming constants as expressions:

Example 1-5:

Naming Constants as Expressions

DECLARE

CONSTANT

DOUBLE

min_value

max value

= PI/2

You can specify only one data type in a DECLARE CONSTANT statement. To declare a constant of a different data type, you must use a second
DECLARE CONSTANT statement.

1-30

Program Elements and Structure

1.5.3.2

Naming Constants External to a Program Unit

To declare constants outside the program unit, use the EXTERNAL statement, as shown in Example 1-6.

Example 1-6:

Declaring Constants Outside the Program Unit

EXTERNAL LONG CONSTANT SS$ NORMAL

EXTERNAL WORD CONSTANT IS SUCCESS

The first line declares the VMS status code SS$_NORMAL to be an external
LONG constant. The second line declares IS_SUCCESS, a success code, to
be an external WORD constant. Note that VAX BASIC allows only external
BYTE, WORD, LONG, and SINGLE constants. The VMS Linker supplies
the values for the constants specified in EXTERNAL statements.

External constant names cannot exceed 31 characters and must conform to
the rules for naming external variables listed in Section 1.4.1. No external
constant name can have embedded spaces. In VAX BASIC, the named
constant might be a system status code or a global constant declared in a
VAX MACRO or VAX BLISS program.

1.5.4

Explicit Literal Notation

You can specify the value and data type of numeric literals by using a special
notation called explicit literal notation. The format of this notation is as
follows:
[radix] "num-str-lit* [data-type]

Radix specifies an optional base, which can be any of the following:
D

Decimal (base 10)

Binary (base 2)

Octal (base 8)

Hexadecimal (base 16)

ASCII

The VAX BASIC default radix is decimal. Binary, octal, and hexadecimal
notation allow you to set or clear individual bits in the representation of
an integer. This feature is useful in forming conditional expressions and in
using logical operations. The ASCII radix causes VAX BASIC to translate a
single ASCII character to its decimal equivalent. This decimal equivalent is
Program Elements and Structure

1-31

an INTEGER value; you specify whether the INTEGER subtype should be
BYTE, WORD, or LONG.

Num-str-lit is a numeric string literal. It can be the digits 0 and 1 when the
radix is binary, the digits 0 through 7 when the radix is octal, the digits 0
through F when the radix is hexadecimal, and the digits 0 through 9 when

the radix is decimal. When the radix is ASCII, num-str-lit can be any valid
ASCII character.
Data-type is an optional single letter that corresponds to a data type

g W

keyword, excluding INTEGER and REAL:
BYTE

WORD

QUTM

LONG

SINGLE
DOUBLE

GFLOAT

HFLOAT
DECIMAL

CHARACTER

Note that data-type for the ASCII radix is limited to BYTE, WORD, or
LONG. For example:
D" 255"L

Specifies a LONG decimal constant with a value of 255

"4000"F

Specifies a SINGLE decimal constant with a value of 4000

-"125"B

Specifies a BYTE decimal constant with a value of =125

A"M"L

Specifies a LONG integer constant with a value of 77

A"m"B

Specifies a BYTE integer constant with a value of 109

A quoted numeric string alone, without a radix and a data type, 1s a string
literal, not a numeric literal. For example:
"255"W

Specifies a WORD decimal constant with a value of 255

"255"

Is a string literal

If you specify a binary, octal, or hexadecimal radix, data-type must be an
integer. If you do not specify a data type, VAX BASIC uses the default

integer data type. For example:

1-32

B"11111111"B

Specifies a BYTE binary constant with a value of -1

Br11111111"W

Specifies a WORD binary constant with a value of 255

Program Elements and Structure

Br11111111"

Specifies a binary constant of the default data type (BYTE,
WORD, or LONG)

Bri11111111"F

Is illegal because F is not an integer data type

X"FF"B

Specifies a BYTE hexadecimal constant with a value of —1

- X"FF"W

Specifies a WORD hexadecimal constant with a value of 255

X"FF"D

Is illegal because D is not an integer data type

Oo"377"B

Specifies a BYTE octal constant with a value of -1

O"377"W

Specifies a WORD octal constant with a value of 255

o 377G

Is illegal because G is not an integer data type

When you specify a radix other than decimal, overflow checking is performed
as if the numeric string were an unsigned integer. However, when this value

is assigned to a variable or used in an expression, the VAX BASIC compiler
treats it as a signed integer.

In the following example, VAX BASIC sets all 8 bits in storage location A.
Because A is a BYTE integer, it has only 8 bits of storage. Because the 8-bit
two’s complement of 1 is 11111111, its value is —1. If the data type were W
(WORD), VAX BASIC would set the bits to 0000000011111111, and its value
would be 255.
DECLARE

BYTE A

A = B"11111111"B
PRINT

Output
-1

NOTE

In VAX BASIC, a D can appear in both the radix position and
the data type position. D in the radix position specifies that the
numeric string is to be treated as a decimal number (base 10). D
in the data type position specifies that the value is to be treated
as a double-precision, floating-point constant. P in the data type
position specifies a packed decimal constant. For example:
"255"D

Specifies a double-precision constant with a value of 255

"255.55"P

Specifies a DECIMAL constant with a value of 255.55

You can use explicit literal notation to represent a single-character string in
terms of its 8-bit ASCII value. For example:
[radix] num-str-lit C

Program Elements and Structure

1-33

The letter C is an abbreviation for CHARACTER. The value of the numeric
string must be from 0 through 255. This feature lets you create your own
compile-time string constants containing nonprinting characters.
The following example declares a string constant named control_g (ASCII

decimal value 7). When VAX BASIC executes the PRINT statement, the

terminal bell sounds.
DECLARE
PRINT

1.5.5

STRING

CONSTANT

control
g =

"7"C

control
g

Predefined Constants
Predefined constants are symbolic representations of either ASCII characters

or mathematical values. They are also called compile-time constants because
their value is known at compilation rather than at run time.
Predefined constants help you
*

Format program output to improve readability

Make source code easier to understand

Table 1-7 lists the predefined constants supplied by VAX BASIC, their
ASCII values, and their functions.

Table 1-7:

Predefined Constants
Decimal

Constant

ASCII Value

Function

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

(continued on next page)

1-34

Program Elements and Structure

Table 1—-7 (Cont.):

Predefined Constants
Decimal

Constant

ASCII Value

Function

CR (Carriage Return)

Moves the cursor to the beginning of

the current
line
SO (Shift 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 with the

precision of the default floating-point

data type

You can use predefined constants in many ways. For instance, the following
example shows how to print and underline a word on a hard copy terminal.
PRINT

"NAME:"

+ BS

END

Output
NAME
:

The following example shows how to print and underline a word on a VT'100
video display terminal.
PRINT

ESC

"[4mNAME:"

ESC +

"[On"

END

Output
NAME
:

Note that the “m” in the above example must be lowercase.

You can also create your own predefined constants with the DECLARE
CONSTANT statement.

Program Elements and Structure

1-35

In the following example, the first DECLARE statement defines underlined_

name as a string constant. The second DECLARE statement defines D_PI
as a DOUBLE constant equal to the predefined constant PI. If the default
REAL data size is SINGLE, the program can use both single-precision P/

and double-precision D_PI.
DECLARE

STRING CONSTANT

underlined name

= ESC

"[4mNAME:"

ESC

"[Om"

DECLARE DOUBLE CONSTANT DPI = PI

1.6

underlined name

D PI,,PI

EXxpressions
VAX BASIC expressions consist of operands (numbers, strings, constants,

variables, functions, and array elements) separated by arithmetic, string,
relational, and logical operators.
Almost all VAX BASIC expressions yield numeric values. The only
exceptions are string concatenation expressions and invocations of stringvalued functions. By using different combinations of numeric operators and
operands, and by using the resulting values, you can produce

Numeric expressions

String expressions

(Conditional expressions

VAX BASIC evaluates expressions according to operator precedence and

uses the results in program execution. Parentheses can be used to group
operands and operators, thus controlling the order of evaluation.

The following sections explain the types of expressions you can create and
the way VAX BASIC evaluates expressions.

1.6.1

Numeric Expressions
Numeric expressions consist of floating-point, integer, or packed decimal
operands separated by arithmetic operators and optionally grouped by

parentheses. Table 1-8 shows how numeric operators work in numeric
expressions.

Program Elements and Structure

Table 1-8:

Arithmetic Operators

Operator

Example

Use

A+B

Add Bto A

—

A-B

Subtract B from A

A*B

Multiply A by B

A/B

Divide A by B

A"B

Raise A to the power B

A**B

Raise A to the power B

In general, two arithmetic operators cannot occur consecutively in the same
expression. Exceptions are the unary plus and unary minus. The following
expressions are valid.
A*
+ B

A *

(-B)

The following expression is not valid:
A-

An operation on two numeric operands of the same data type yields a result
of that type. For example:
A% + B%

Yields an integer value of the default type

G3 * M5

Yields a floating-point value if the default type is REAL

If the result of the operation exceeds the range of the data type, VAX BASIC
signals an overflow error message.

The following example causes VAX BASIC to signal the error “Integer error

or overflow” because the sum of A and B (254) exceeds the range of —128
to +127 for BYTE integers. Similar overflow errors occur for REAL and
DECIMAL data types whenever the result of a numeric operation is outside

the range of the corresponding data type.
DECLARE

BYTE

A =127

B =

127

END

Program Elements and Structure

1-37

It is possible to assign a value of one data type to a variable of a different
data type. When this occurs, the data type of the variable overrides the

data type of the assigned value. The following example assigns the value
32 to the integer variable A% even though the floating-point value of the
expression is 32.13.
A%

1.6.1.1

5.1

6.3

Floating-Point and Integer Promotion Rules

When an expression contains operands with different data types, the data
type of the result is determined by VAX BASIC’s data type promotion rules:
e

With one exception, VAX BASIC promotes operands with different data

types to the lowest common data type that can hold the largest or most
precise possible value of either operand’s data type. VAX BASIC then
performs the operation using that data type, and yields a result of that
data type.

The exception is that when an operation involves SINGLE and LONG
data types, VAX BASIC promotes the LONG data type to SINGLE
rather than DOUBLE, performs the operation, and yields a result of the
SINGLE data type.

Note that VAX BASIC does sign extension when converting BYTE and
WORD integers to a higher INTEGER data type (WORD or LONG). The
high order bit (the sign bit) determines how the additional bits are set when
the BYTE or WORD is converted to WORD or LONG. If the high order bit
is zero (positive), all higher-order bits in the converted BYTE or WORD are
set to zero. If the high order bit is 1 (negative), all higher-order bits in the
converted BYTE or WORD are set to 1.

Table 1-9 lists the data type results possible in numeric expressions that
combine BYTE, WORD, LONG, SINGLE, and DOUBLE data. Table 1-10
lists the data type results possible in numeric expressions that combine the
data types GFLOAT and HFLOAT. When the operands are DOUBLE and
GFLOAT, VAX BASIC promotes both values to HFLOAT, and returns an
HFLOAT value. The promotion of DOUBLE and GFLOAT to HFLOAT is
necessary because a DOUBLE value is more precise than a GFLOAT value,

but cannot contain the largest possible GFLOAT value. Consequently, VAX
BASIC promotes these data types to a data type that can hold the largest
and most precise value of either operand.

1-38

Program Elements and Structure

Table 1-9:

Result Data Types in VAX BASIC Expressions

BYTE

WORD

LONG

SINGLE

DOUBLE

BYTE

WORD

LONG

SINGLE

DOUBLE

WORD

LONG

SINGLE

DOUBLE

LONG

SINGLE

DOUBLE

SINGLE

DOUBLE

For example, if one operand is SINGLE and one operand is DOUBLE, VAX
BASIC promotes the SINGLE value to DOUBLE, performs the specified
operation, and returns the result as a DOUBLE value. This promotion
is necessary because the SINGLE data type has less precision than the
DOUBLE value, whereas the DOUBLE data type can represent all possible
SINGLE values. If VAX BASIC did not promote the SINGLE value and the
operation yielded a result outside of the SINGLE range, loss of precision and
significance would occur.

The data types BYTE, WORD, LONG, SINGLE, and DOUBLE form a simple
hierarchy: if all operands in an expression are of these data types, the result
of the expression is the highest data type used in the expression.

Table 1-10:

1.6.1.2

VAX BASIC Result Data Types
GFLOAT

HFLOAT

BYTE

GFLOAT

HFLOAT

WORD

GFLOAT

HFLOAT

LONG

GFLOAT

HFLOAT

SINGLE

GFLOAT

HFLOAT

DOUBLE

HFLOAT

GFLOAT

HFLOAT

DECIMAL Promotion Rules

VAX BASIC allows the DECIMAL(d,s) data type. The number of digits (d)
and the scale or position of the decimal point (s) in the result of DECIMAL
operations depends 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.

Program Elements and Structure

1-39

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,
VAX BASIC uses the larger number of specified digits for the result.

In the following example, 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.
DECLARE

DECIMAL(5,2)

DECLARE

DECIMAL(4,3)

The result allows three digits to the left of the decimal point and three
digits to the right.

If one operand is DECIMAL and one is 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(5,0).

—

LONG is converted to DECIMAL(10,0).

VAX BASIC then determines the d and s values of the result by evaluating the d and s values of the operands as described above.

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 floating-point value. The total number of digits (d) in
the DECIMAL value determines its new data type, as shown in Table 1-11.
Table 1-11:

Result Data Types for DECIMAL Data

Number of

DECIMAL

Digits

in Operand

Floating-Point Operands

SINGLE

DOUBLE

1-6

SINGLE

7-15

DOUBLE

GFLOAT

HFLOAT

DOUBLE

GFLOAT

HFLOAT

DOUBLE

GFLOAT

HFLOAT

(continued on next page)

140

Program Elements and Structure

Table 1—-11 (Cont.):

Result Data Types for DECIMAL Data

Number of

DECIMAL
Digits

.
.
Floating-Point Operands

in Operand

SINGLE

DOUBLE

GFLOAT

HFLOAT

DOUBLE

HFLOAT

17-31

HFLOAT

If the value of d is between 7 and 15, the operand is converted to:
e

DOUBLE if the floating-point operand is SINGLE or DOUBLE

GFLOAT if the floating-point operand is GFLOAT

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. Note also
that exponentiation of a DECIMAL data type returns a REAL value.

See the VAX BASIC User Manual for tutorial information on data type
interactions, conversions, and promotion rules in VAX BASIC numeric
expressions.

1.6.2

String Expressions
String expressions are string entities separated by the plus sign (+). When
used in a string expression, the plus sign concatenates strings. For example:
INPUT "Type two words to be combined";A$,

C$ = A$ + BS
PRINT C$
END

Output
Type two words
?

to be combined?

long

word

longword

Ready

Program Elements and Structure

1-41

1.6.3

Conditional Expressions
Conditional expressions can be either relational or logical expressions.
Numeric relational expressions compare numeric operands to determine
whether the expression is true or false. String relational expressions
compare string operands to determine which string expression occurs first in

the ASCII collating sequence.

Logical expressions contain integer operands and logical operators. VAX
BASIC determines whether the specified logical expression is true or false

by testing the numeric result of the expression. Note that in conditional
expressions, as in any numeric expression, when BYTE and WORD operands
are converted to WORD and LONG, the specified operation is performed in
the higher data type, and the result returned is also of the higher data type.
When one of the operands is a negative value, this conversion will produce
accurate but perhaps confusing results, because VAX BASIC performs a sign
extension when converting BYTE and WORD integers to a higher integer

data type. See Section 1.6.1.1 for information on integer conversion rules.
1.6.3.1

Numeric Relational Expressions

Operators in numeric relational expressions compare the values of two
operands and returns either a —1 if the relation is true (as shown in Example
1), or a zero if the relation is false (as shown in Example 2). The data type
of the result is the default integer type.

Example 1
B

-1%

IF X%

THEN

’'Relationship

ELSE

THEN
END

END

Output

1-42

true’

’'Relationship

Relationship

true

Program Elements and Structure

false’

Example 2
A

B =15
X%

A =8B

IF X%

= -1%

THEN PRINT

’'Relationship

ELSE

= 0

IF X%

THEN PRINT
END
END

true’

’'Relationship

false’

Output
Relationship

false

Table 1-12 shows how numeric operators work in numeric relational
expressions.

Table 1-12:

Numeric Relational Operators

Operator

Example

Meaning

A=B

A is equal to B.

A<B

A is less than B.

A>B

A is greater than B.

<= 0Or =<

A<=B

A is less than or equal to B.

>= Oor =>

A>=B

A is greater than or equal to B.

<> Or ><

A<>B

A is not equal to B.

A==

A and B will PRINT the same if they are equal to
six significant digits. However, if one value prints
in explicit notation and the other value prints in E

format notation, the relation will always be false.

1.6.3.2

String Relational Expressions

Operators in string relational expressions determine how VAX BASIC
compares strings. The VAX BASIC compiler determines the value of each
character in the string by converting it to its ASCII value. ASCII values
are listed in Appendix C in this manual. VAX BASIC compares the strings
character by character, left to right, until it finds a difference in ASCII
value.

In the following example, VAX BASIC compares A$ and B$ character by
character. The strings are identical up to the third character. Because the

ASCII value of Z (90) is greater than the ASCII value of C (67), A$ is less

Program Elements and Structure

1-43

than B$. VAX BASIC evaluates the expression A$ < B$ as true (-1) and
prints “ABC comes before ABZ”.
AS

'ABC’

'ABZ’

IF AS$

< BS

THEN

’‘ABC

ELSE

IF A$

== BS$

before

ABZ’

strings

are

THEN

’'The

ELSE

IF AS$

> BS

THEN

’‘ABC

ELSE

’Strings

END
END
END

comes

identical’
after

are

ABZ’

equal

but

not

identical’

END

If two strings of differing lengths are identical up to the last character in the

shorter string, VAX BASIC pads the shorter string with spaces (ASCII value
32) to generate strings of equal length, unless the operator is the double

equal sign (==). If the operator is the double equal sign, VAX BASIC does
not pad the shorter string.
In the following example, VAX BASIC compares “ABCDE” to

“ABC ” to

determine which string comes first in the collating sequence. “ABC ” comes
before “ABCDE” because the ASCII value for space (32) is lower than the
ASCII value of D (68). Then VAX BASIC compares “ABC ” with “ABC”
using the double equal sign and determines that the strings do not match

exactly without padding. The third comparison uses the single equal sign.
VAX BASIC pads “ABC” with spaces and determines that the two strings

AS
BS

match with padding.
' ABCDE'
"ABC’

’'B$

comes

before AS$’

IF BS

< AS

’'AS$S

comes before BS$’

IF AS$

< B$S

"ABC

IF BS

END

== C$
THEN PRINT

’'B$

exactly matches

ELSE

’'BS$

does

THEN PRINT

’'B$

matches

ELSE PRINT

’'BS$

does

not

= C$
not

Output
B$

comes before A$

does

not

exactly match C$

B$ matches C$ with padding

1-44

C$’

exactly match C$’

IF BS

END

Program Elements and Structure

with padding’

match C$’

Table 1-13 shows how numeric operators work in string relational
expressions.

Table 1-13:

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

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$

length of the longer string.

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$
A$ == B$

String A$ is not identical to string B$.
Strings A$ and B$ are identical in composition and
length, without padding.

VAX BASIC treats unquoted strings typed in response to the INPUT
statement differently from quoted strings; it does so by ignoring leading
and trailing spaces and tabs. For example, it evaluates the quoted strings
“ABC” and “ABC ” as equal but not identical because the == operator
does not pad the shorter string with spaces. When you input those same
strings as unquoted strings in response to the INPUT prompt, VAX BASIC
evaluates them as equal and identical because it ignores the trailing spaces.
The LINPUT statement, on the other hand, treats unquoted strings as
string literals, so the trailing spaces are part of the string, and VAX BASIC
evaluates the strings as equal, but not identical.
1.6.3.3

Logical Expressions

A logical expression can have one of the following formats:
e

A unary logical operator and one integer operand

Two integer operands separated by a binary logical operator

One integer operand

Program Elements and Structure

1-45

Logical expressions are valid only when the operands are integers. If
the expression contains two integer operands of differing data types, the
resulting integer has the same data type as the higher integer operand. For

instance, the result of an expression that contains a BYTE integer and a
WORD integer would be a WORD integer. Table 1-9 shows how integer data
types interact with each other in expressions.

VAX BASIC determines whether the condition is true or false by testing
the result of the logical expression to see whether any bits are set. If
no bits are set, the value of the expression is zero and it is evaluated as
false; if any bits are set, the value of the expression is nonzero, and the
expression is evaluated as true. VAX BASIC generally accepts any nonzero

value in logical expressions as true. However, logical operators can return
unanticipated results unless —1 is specified for true values and zero for false.

Table 1-14 lists the logical operators.
NOTE
DIGITAL recommends that you use logical operators on the
results of relational expressions to avoid obtaining unanticipated

results.

Table 1-14:

Logical Operators

Operator

Example

NOT

NOT A%

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

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.

(continued on next page)

1-46

Program Elements and Structure

Table 1-14 (Cont.):

Logical Operators

Operator

Example

EQV

A% EQV B%

Meaning
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% IMP B%

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.

The truth tables in Figure 1-2 summarize the results of these logical
operations. Zero is false; —1 is true.

Program Elements and Structure

1-47

Figure 1-2:

Truth Tables

NOT A%

0
—1

~1
0

A%OR B%

0
0

0
-1

0
1

-1
-1

0
-1

A% AND B%|

B% A% EQV B%

0
0
1
-1

0
-1
0
-1

0
0
0
1

0
0
-1
I

0
-1
0

B% A% XOR B%|

B% A% IMP B%

0
0o
1
-1

0
-1
0
-1

0o
0o
-1
-1

0
-1
0
-

0
-1
1
0

1
0
0
~1

1
1
0
~1
ZK-5548-GE

The operators XOR and EQV are logical complements.

In the following example, the values of A% and B% both test as true because
they are nonzero values. However, the logical AND of these two variables
returns an unanticipated result of false.
A%

IF A%

THEN PRINT

‘A%

TRUE'

IF B%

THEN PRINT

’‘B%

TRUE’

IF A% AND

THEN PRINT

'A% AND B%

ELSE PRINT

‘A%

IS FALSE'

END

148

Program Elements and Structure

AND B%

TRUE’

Output
A%

TRUE

AND

FALSE

The 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 as follows:
0

The 8-bit binary representation of 4% is as follows:
0

Each value tests as true because it is nonzero. However, the AND operation
on these two values sets a bit in the result only if the corresponding bit is
set in both operands. Therefore, the result of the AND operation on 4% and
2% is as follows:
0O

No bits are set in the result, so the value tests as false (zero).
If the value of B% is changed to 6%, the resulting value tests as true

(nonzero) because both 6% and 2% have the second bit set. Therefore, VAX
BASIC sets the second bit in the result and the value tests as nonzero and
true.

The 8-bit binary representation of —1 is as follows:
1

The result of -1% AND —1% is —1% because VAX BASIC sets bits in the
result for each corresponding bit that is set in the operands. The result tests
as true because it is a nonzero value, as shown in the following example:

IF
IF

-1%
-1%

A% THEN PRINT ‘A% IS TRUE’

oo oo

THEN PRINT

AND B%

’‘B%

TRUE’

THEN PRINT

‘A%

AND B%

ELSE PRINT

‘A%

AND B%

IS FALSE’

TRUE’

END

Output
AS

TRUE

AND

TRUE

Your program may also return unanticipated results if you use the NOT
operator with a nonzero operand that is not —1.

Program Elements and Structure

1-49

In the following example, VAX BASIC evaluates both A% and B% as true
because they are nonzero. NOT A% is evaluated as false (zero) because the

binary complement of —1 is zero. NOT B% is evaluated as true because the
binary complement of 2 has bits set and is therefore a nonzero value.
A%=-1%
B%=2

IF A%
IF B%

THEN PRINT

'A%

TRUE’

ELSE

'A%

FALSE’

THEN

’'B%

TRUE’

ELSE

’'B%

FALSE’

IF NOT A%
IF

NOT

THEN PRINT

’'NOT A%

ELSE PRINT

’'NOT A%

IS FALSE’

TRUE’

THEN

’‘NOT

TRUE’

ELSE

’'NOT

FALSE’

END

Output

1.6.4

TRUE

NOT A%

FALSE

NOT B%

TRUE

Evaluating Expressions
VAX 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 informs VAX BASIC

of the order in which to perform the operation. Parentheses can change the
order of precedence.
Table 1-15 lists all operators as VAX BASIC evaluates them. N ote that

Operators with equal precedence are evaluated logically from left to
right.

VAX BASIC evaluates expressions enclosed in parentheses first, even

when the operator in parentheses has a lower precedence than that
outside the parentheses.
*

The addition (+) and multiplication (*) operators are evaluated in
algebraic order.

1-50

Program Elements and Structure

Table 1-15:

Numeric Operator Precedence
Precedence
N+

Operator
L Orl\

— (unary minus) or + (unary plus)

* or /

+ or —

+ (concatenation)

all relational operators

NOT

AND

OR, XOR
IMP
EQV

For example, VAX BASIC evaluates the expression A = 1572 + 1272 —
(35 * 8) in five steps:

1572 = 225

Exponentiation (leftmost expression)

1272 =144

Exponentiation

225 + 144 = 369

Addition

(835 * 8) = 280

Multiplication

369 — 280 = 89

Subtraction

There is one exception to this order of precedence: when an operator that
does not require operands on either side of it (such as NOT) immediately
follows an operator that does require operands on both sides (such as the
addition operator (+)), VAX BASIC evaluates the second operator first. For
example:
A%

+ NOT B$%

This expression is evaluated as:
(A%

(NOT B%))

+ C3%

VAX BASIC evaluates the expression NOT B before it evaluates the
expression A + NOT B. When the NOT expression does not follow the
addition ( +) expression, the normal order of precedence is followed. For
example:
NOT A%

+ B%

Program Elements and Structure

1-51

This expression is evaluated as:
NOT

((A%

B%)

VAX BASIC evaluates the two expressions (A% + B%) and (A% + B%) + C%)

because the + operator has a higher precedence than the NOT operator.
VAX BASIC evaluates nested parenthetical expressions from the inside out.

In the following example, VAX BASIC evaluates the parenthetical expression

A quite differently from expression B. For expression A, VAX BASIC
evaluates the innermost parenthetical expression (25 + 5) first, then the
second inner expression (30 / 5), then (6 * 7), and finally (42 + 3). For
expression B, VAX BASIC evaluates (5 / 5) first, then (1 * 7), then

(25 + 7 + 3) to obtain a different value.
A=

((((25
+5) / 5)

*7)
+ 3)

PRINT
A

B=25+5/5*74+
3
PRINT
B

Output
45

1.7

Program Documentation
Documentation within a program clarifies and explains source program
structure. These explanations, or comments, can be combined with code
to create a more readable program without affecting program execution.

Comments can appear in two forms:

1.7.1

Comment fields (including empty statements)

REM statements

Comment Fields
A comment field begins with an exclamation point (!) and ends with a
carriage return. You supply text after the exclamation point to document
your program. You can specify comment fields while creating VAX BASIC
programs at DCL level as well as in the BASIC environment. In both cases,

VAX BASIC does not execute text in a comment field. Example 1-7 shows

how to specify a comment field.

1-62

Program Elements and Structure

Example 1-7:
!

FOR

loop

Q(I)
NEXT

Specifying a Comment Field

initialize

This

list

comment

List

now

initialized

VAX BASIC executes only the FOR...NEXT loop. The comment fields,
preceded by exclamation points, are not executed.
Example 1-8 shows how you can use comment fields to help make your
program more readable and allow you to format your program into readily
visible logical blocks. Example 1-8 also shows how comment fields can be

used as target lines for GOTO and GOSUB statements.
Example 1-8:

Using Comments Fields to Format a Program

Square

root

program

}

INPUT

’'Enter

’'SQR of

';A;’is

number’;A

square

roots?

’;SQR(A)

INPUT

GOTO

'Type

"Y"

IF ANSS

continue,

press

RETURN

quit’ ;ANSS

"Y"

END

You can also use an exclamation point to terminate a comment field, but
this practice is not recommended. You should make sure that there are no

exclamation points in the comment field itself; otherwise, VAX BASIC treats

the text remaining on the line as source code.
NOTE
Comment fields in DATA statements are invalid; the VAX BASIC
compiler treats the comments as additional data.

Empty statements consist of a line number and an exclamation point.
Empty statements can make your program more legible by increasing the
amount of “white space” and visually separating logical program segments.
In Example 1-9, lines 100 and 300 are empty statements.

Program Elements and Structure

1-53

Example 1-9:
100

Using Empty Statements in a VAX BASIC Program

!
!

FOR

loop

initialize

list

200

FOR

Q(I)
NEXT

300

This

comment

List

now initialized

In general, empty statements can be used to make a program more legible

and organized.

1.7.2

REM Statements
A REM statement begins with the REM keyword and ends when VAX
BASIC encounters a new line number. The text you supply between the
REM keyword and the next line number documents your program. Like

comment fields, REM statements do not affect program execution. VAX
BASIC ignores all characters between the keyword REM and the next

line number. Therefore, the REM statement can be continued without
the ampersand continuation character and should be the only statement

on the line or the last of several statements in a multi-statement line.
Example 1-10 shows the use of the REM statement.

1-54

Program Elements and Structure

Example 1-10:
REM This

Using REM Statements in VAX BASIC Programs

an example

A=5

B=10
REM A

equals

The REM statement is nonexecutable. When you transfer control to a REM
statement, VAX BASIC executes the next executable statement that lexically

follows the referenced statement.
NOTE
Because VAX BASIC treats all text between the REM statement
and the next line number as commentary, REM should be used
very carefully in programs that follow the implied continuation

rules. REM statements are disallowed in programs without line
numbers.

In the following example, the conditional GOTO statement in line 20

transfers program control to line 10. VAX BASIC ignores the REM comment
on line 10 and continues program execution at line 20.
10

REM

INPUT

’'Enter

'SQR

INPUT

'Type

GOTO
40

Square

root

program

a number’
;A

’;A;’is

"Y"

IF ANSS

’';SQR(A)

continue,

press

‘
RETURN

quit’;ANSS$

"y"

END

Program Elements and Structure

1-55

Chapter 2

Environment Commands

Environment commands are commands that you use in the BASIC
environment. With environment commands, you can display, edit, and
merge VAX BASIC programs, set compiler defaults, move VAX BASIC source
programs to and from storage, and execute programs. This chapter lists
alphabetically all of the compiler commands that can be used within the
BASIC environment. For information on immediate mode and calculator
mode statements, see the VAX BASIC User Manual.

Environment Commands

2-1

! your-comment

! your-comment
You can enter comments while in the BASIC environment by typing an

exclamation point (!) and the comment.

Format
!

your-comment

Syntax Rules

The exclamation point must be the first character on the line.

You cannot continue a comment over more than one line.

Remarks

None.

Examples

Example 1
Ready

2-2

Comments

here

Environment Commands

...

! your-comment

Example 2
$ TYPE BUILD SPECIAL.COM
$ SET VERIFY
$ BASIC
1+

Set

the

appropriate

compilation

SET

LIST

options by uncommenting

ones.

SET

WORD

SET

DEBUG

Get

the

source

module.

| -

OLD

SPECIAL

Compile

it.

| —

COMPILE

'+
!

All

done.

EXIT

Environment Commands

2-3

$ system-command

$ system-command
You can execute a DCL command while in the BASIC environment by typing

a dollar sign ($) before the command. VAX BASIC passes the command to
the operating system for execution. The context of the BASIC environment

and the program currently in memory do not change.

Format

system-command

Syntax Rules

VAX BASIC passes system-command directly to the VMS operating system
without checking for validity.

Remarks

The terminal displays any error messages or output that the command
generates.

Control returns to the BASIC environment after the command executes.

The context (source file status, loaded modules, and so on) of the BASIC
environment and the program currently in memory do not change unless

the command causes the operating system to abort VAX BASIC or log
you out.

The command you specify executes within the context of a subprocess.

Consequently, commands such as the DCL command SET execute only
within the subprocess and do not affect the process running VAX BASIC.

2-4

Environment Commands

$ system-command

Example

Read

SHOW PROTECTION
SYSTEM=RWED,

OWNER=RWED,

GROUP=RWED,

WORLD=RE

Ready

Environment Commands

2-5

APPEND

APPEND
The APPEND command merges an existing VAX BASIC source program
with the program currently in memory.

Format

APPEND

[file-spec]

Syntax Rules

File-spec is the name of the VAX BASIC program you want to merge with
the program currently in memory. The default file type is BAS.

Remarks

You cannot specify the APPEND command on programs that do not
contain line numbers.

If you type APPEND without specifying a file name, VAX BASIC
prompts with
Append file name--—

You should respond with a file name. If you respond with a carriage
return and no file name, VAX BASIC searches for a file named

NONAME.BAS. If the VAX BASIC compiler cannot find NONAME.BAS,
VAX BASIC signals the error “Can’t find file or account” (ERR=5).

You can append the contents of file-spec to a source program that is
either called into memory with the OLD command or created in the
BASIC environment. If there is no program in memory, VAX BASIC
appends the file to an empty program with the default file name
NONAME.

2-6

Environment Commands

APPEND

If file-spec contains a VAX BASIC line with the same line number as a
line of the program in memory, the line in the appended file replaces the
line of the program in memory. Otherwise, VAX BASIC inserts appended
lines into the program in memory in sequential, ascending line number
order.

The APPEND command does not change the name of the program in
memory.

If you have not saved the appended version of the program, VAX BASIC
signals the warning “Unsaved change has been made, CTRL/Z or EXIT

to exit” the first time you try to leave the BASIC environment.

Example

Ready

New FIRST TRY.BAS
Ready

PRINT "First program"

APPEND NEWPROG.BAS
Ready
LIST

PRINT "First Program"

PRINT "This section has been appended"

Environment Commands

2-7

ASSIGN

ASSIGN
The ASSIGN command equates a logical name to a complete file

specification, a device, or another logical name within the context of the
BASIC environment.

Format

ASSIGN

equiv-name[:] log-namel:]

Syntax Rules

Equiv-name specifies the file specification, device, or logical name to be
assigned a logical name. If you specify a physical device name, you must
terminate it with a colon (:).

Log-name is the 1- to 63-character logical name to be associated with

equiv-name. You can specify a logical name for any portion of a file

specification. If the logical name translates to a device name, and will be
used in place of a device name in a file specification, you must terminate
it with a colon (:).

If log-name has more than 63 characters, VAX BASIC signals the error
“Invalid logical name”.

Remarks

When the logical name assignment supersedes another logical name

previously assigned, VAX BASIC dlsplays the message “Prevmus logical
name assignment replaced”-

2-8

Environment Commands

ASSIGN

Logical names assigned with the ASSIGN command are placed in the
process logical name table and remain there until you exit the BASIC
environment.

Example

ASSIGN

[HENRY.BAS]

PRO:

Environment Commands

2-9

COMPILE

COMPILE
The COMPILE command converts a VAX BASIC source program to an object
module and writes the object file to disk.

Format
COMPILE [ file-spec ] [ /qualifier |...
Command Qualifiers
/INOJANSI_STANDARD

Defaults

/NOANSI_STANDARD

/INOJAUDIT [ sep text-entry ]

/INOAUDIT

/INOJBOUNDS_CHECK

/BOUNDS_CHECK

/BYTE

/LONG

/INOJCROSS_REF [ sep [NOJKEYWORDS ]

INOCROSS_ REF

/INOIDEBUG

/NODEBUG

/DECIMAL_SIZE sep (d,s)

/IDECIMAL_SIZE=(15,2)

/DOUBLE

/SINGLE

[INOJFLAG [ sep ( flag-clause,... ) ]

/INOFLAG

/GFLOAT

/SINGLE

/HFLOAT

/SINGLE

/INOJLINES

/LINES

/[NOJLIST

/NOLIST

/LONG

/INOJMACHINE_CODE

/NOMACHINE

/[INOJOBJECT

/OBJECT

[INOJOVERFLOW [ sep (data-type,...) ]

/[INOJROUND

/OVERFLOW=(INTEGER,DECIMAL)

/NOROUND

/[INOJSETUP

/SETUP

[INOJSHOW [ sep ( show-item,... ) ]
ISINGLE

/SHOW
/SINGLE

/INOJSYNTAX_CHECK

INOSYNTAX_CHECK

/INO]JTRACEBACK
[TYPE_DEFAULT sep default-clause

2-10

Environment Commands

/TRACEBACK

[TYPE_DEFAULT=REAL

COMPILE

/VARIANT sep int-const

/INOJWARNINGS [ sep warn-clause ]

/WORD

/VARIANT=0

/WARNINGS
/LONG

Syntax Rules

File-spec specifies a name for the output file or files. If you do not
provide a file-spec, the VAX BASIC compiler uses the name of the
program currently in memory for the file name, a default file type of

OBJ for the object file, and a default file type of LIS for the listing file, if
a listing file is requested.

File-spec can precede or follow any qualifier.

/ Qualifier specifies a qualifier keyword that sets a VAX BASIC default.
You can abbreviate all positive qualifiers to the first three letters of the
qualifier keyword. You can abbreviate a negative qualifier to NO and the
first three letters of the qualifier keyword.

In cases of ambiguous or erroneous qualifiers, VAX BASIC signals
“Unknown qualifier”, and the program does not compile. When qualifiers
conflict, VAX BASIC compiles the program using the last specified
conflicting qualifier. For example, the following command line causes
VAX BASIC to compile the program currently in memory but does not
cause VAX BASIC to create an OB file.
COMPILE/OBJ/NOOBJ

There must be a program in memory, or the COMPILE command does
not execute; VAX BASIC does not signal an error or warning.

Remarks

The following qualifiers cannot be used within the VAX BASIC
environment with the COMPILE command:
e

/ANALYSIS_DATA

/CHECK

Environment Commands

2-11

COMPILE

/DESIGN

/DEPENDENCY_DATA

/DIAGNOSICS

/INTEGER_SIZE

/OLD_VERSION=CDD_ARRAY

/REAL_SIZE

/SCALE

If an object file for the program already exists in
your directory, VAX
BASIC creates a new version of the OBJ file.
You should not specify both a file name and file type.

you enter the following command line, VAX

of NEWOBJ.FIL:

For example, if

BASIC creates two versions

COMPILE NEWOBJ.FIL/LIS/OBJ

The first version, NEWOBJ.FIL:1, is the listing file;
the second version,
NEWOBJ.FIL;2, is the object file. If you specify
only a file name, VAX
BASIC uses the OBJ and LIS file type defaults when
creating these files.
Use the COMPILE/NOOBJECT command to check
your program for

errors without producing an object file.

When you exit from the BASIC environment, all
options set with
qualifiers return to the system default values.
Use the SHOW command
to display your system defaults before setting any
qualifiers.

Command Qualifiers
/[INOJANSI STANDARD
The /ANSI_STANDARD qualifier causes VAX BASIC
according to the ANSI Minimal BASIC standard

to compile programs
and to flag syntax that does

not conform to the standard. The /NOANSI STAND
ARD qualifier causes
VAX BASIC not to compile the program according
to the ANSI Minimal
BASIC standard. The default is /NOANSI_STANDAR
D.

See the VAX BASIC User Manual for more information
on the ANSI
Minimal BASIC Standard.

2-12

Environment Commands

COMPILE

vojaupiT{ *

{ str-lit
}]
file-spec

The /AUDIT qualifier causes VAX BASIC to include a history list entry in
the CDD data base when a CDD definition is extracted. Str-lit is a quoted
string. File-spec is a text file. The history entry includes

The contents of str-lit, or up to the first 64 lines in the file specified by
file-spec

The name of the program module, process, user name, and user UIC
that accessed the CDD

The time and date of the access

A note that access was made by the VAX BASIC compiler

A note that access was an extraction

If you specify /INOAUDIT VAX BASIC does not include a history list entry.
/NOAUDIT is the default.

/[NO]JBOUNDS CHECK

The /BOUNDS_CHECK qualifier causes VAX BASIC to perform range

checks on array subscripts. With bounds checking enabled, VAX BASIC
checks that all subscript references are within the array boundaries set
when the array was declared. If the subscript bounds are not within the
bounds initially declared for the array, VAX BASIC signals an error message.
If you specify /NOBOUNDS_CHECK VAX BASIC does not check that all
subscript references are within the array bounds set. /BOUNDS_CHECK is
the default.
/BYTE

The /BYTE qualifier causes VAX BASIC to allocate 8 bits of storage as the
default for all integer data not explicitly typed in the program. Untyped
integer values are treated as BYTE values and must be in the BYTE range
or VAX BASIC signals the error “Integer error or overflow.” Table 1-2 in
this manual lists VAX BASIC data types and ranges. By default, the VAX
BASIC compiler allocates 32 bits of storage.

/[NO]CROSS__REFERENCE[{ : } [NOJKEYWORDS ]
If you use the JCROSS_REFERENCE qualifier with the /LIST

qualifier when you compile your program, the VAX BASIC compiler
includes cross-reference information in the program listing file. If
Environment Commands

2-13

COMPILE

you specify /CROSS_REFERENCE=KEYWORDS, VAX BASIC also

cross-references VAX BASIC keywords used in the program. If you specify
/NOCROSS_REFERENCE, VAX BASIC does not include a cross reference
section in the compiler listing. The default is NOCROSS_REFERENCE.

/[NO]DEBUG
The /DEBUG qualifier appends to the object file information on symbolic

references and line numbers. This information is used by the VMS
Debugger when you debug your program. When you specify the /DEBUG
qualifier on the COMPILE command, you cause the debugger to be invoked
automatically when the program is run at DCL level (unless you specify
RUN/NODEBUG). If you specify COMPILE/NODEBUG, information on
program symbols and line numbers is not included in the object file. The
default is
NODEBUG.

See the VAX BASIC User Manual for more information on using the VMS

Debugger.

/DECIMAL_SIZE { * } (d,s)
The /DECIMAL_SIZE qualifier allows you to specify the default size and

precision for all DECIMAL data not explicitly assigned size and precision
in the program. You specify the total number of digits (d) and the number

of digits to the right of the decimal point (s). VAX BASIC signals the error
“Decimal error or overflow” (ERR=181) when DECIMAL values are outside

the range specified with this qualifier. See Table 1-2 in this manual for
more information on the storage and range of packed decimal data. The
default is /DECIMAL_SIZE=(15,2).

/DOUBLE
The /DOUBLE qualifier causes VAX BASIC to allocate 64 bits of storage
in D_floating format as the default size for all floating-point data not

explicitly typed in the program. Untyped floating-point values are treated as
DOUBLE values and must be in the DOUBLE range or VAX BASIC signals

the error “Floating-point error or overflow.” Table 1-2 in this manual lists

VAX BASIC data types and ranges. The default is /SINGLE.

INOIFLAG[ { _ }( { [NOJDECLINING
:

[NO]BP2COMPATIBILITY

}) ]

The /FLAG qualifier causes VAX BASIC to provide compile-time information
about program elements that are not compatible with BASIC-PLUS-2
or that DIGITAL designates as not recommended for new program

2-14

Environment Commands

COMPILE

development. For more information on source code that is incompatible

with BASIC-PLUS-2, see Appendix A in this manual.

If you specify the DECLINING clause, VAX BASIC will flag the following
source code as declining:

CVT$$ (use EDITS)

(CVT$%, CVT$F, CVT%$, CVTF$, AND SWAP% (use multiple MAP

DEF* functions (use DEF functions)

statements)

TFIELD statements (use MAP DYNAMIC and REMAP)

GOTO line-num% (do not use the integer suffix with a line number)

The default is /NOFLAG.
/GFLOAT

The /GFLOAT qualifier causes VAX BASIC to allocate 64 bits of storage
in G_floating format as the default size for all floating-point data not
explicitly typed in the program. Untyped floating-point values are treated
as G_floating values and must be in the G_floating range or VAX BASIC
signals “Floating-point error or overflow.” Table 1-2 in this manual lists
VAX BASIC data types and ranges. The default is /SINGLE.
/HFLOAT

The /HFLOAT qualifier causes VAX BASIC to allocate 128 bits of storage
in H_floating format as the default size for all floating-point data not
explicitly typed in the program. Untyped floating-point values are treated

as H_floating values and must be in the H_floating range or VAX BASIC
signals “Floating-point error or overflow.” Table 1-2 in this manual lists

VAX BASIC data types and ranges. The default is /SINGLE.
/[NOJLINES

The /LINES qualifier includes line number information in object modules.
If you specify /NOLINES VAX BASIC does not include line number
information in object modules. If you specify /NOLINES in a program

containing a RESUME statement or the run-time ERL function, VAX BASIC
issues a warning that the /NOLINES qualifier has been overridden. The
default is /LINES.

Environment Commands

2-15

COMPILE

/[NOJLIST

The /LIST qualifier causes VAX BASIC to produce a compiler listing

This compiler listing generated by the /LIST qualifier contains

file.

a memory

allocation map. By default, the name of the listing file is the
same as the
name of the first program module specified, and has a default
file type

of LIS. If you specify /NOLIST VAX BASIC does not generate a
compiler
listing. /NOLIST is the default.
/LONG

The /LONG qualifier causes VAX BASIC to allocate 32 bits of

storage as the
default size for all integer data not explicitly typed in the program.
Untyped
integer values are treated as LONG values and must be in the
LONG range
or VAX BASIC signals the error “Integer error or overflow.” Table
1-2 in
this manual lists VAX BASIC data types and ranges. /LONG is
the default.
/[NOJMACHINE CODE
|
When you specify the MACHINE_CODE qualifier with the /LIST

qualifier

in the COMPILE command, VAX BASIC includes the machine

code

/NOMACHINE_CODE, VAX BASIC does not include a machine

code section

generated by the compilation in the program listing file. If
you specify

in the listing file. /NOMACHINE_CODE is the default.

/[NOJOBJECT
The /OBJECT qualifier generates an object module with the same
as the program and a default file type of OBJ. The /NOOBJECT

file name

qualifier

allows you to check your program for errors without creating
an object file.
/OBJECT is the default.
GER
/[NO]OVERFLOW[{ .: }( { INTE
DEGIAL
}) ]

The /OVERFLOW qualifier causes VAX BASIC to report arithmet
ic overflow
for operations on integer or packed decimal data, or both. If you specify
/NOOVERFLOW, VAX BASIC does not report arithmetic overflows
. The
default is /OVERFLOW=(INTEGER,DECIMAL).

/[NOJROUND
The /ROUND qualifier causes VAX BASIC to round rather than

truncate
DECIMAL values. If you specify INOROUND, VAX BASIC truncates
DECIMAL values. The default is/NOROUND.

2-16

Environment Commands

COMPILE

/[NOJSETUP

The /SETUP qualifier causes VAX BASIC to make calls to the Run-Time
Library to set up the stack for VAX BASIC variables, set up dynamic string
and array descriptors, initialize variables, and enable VAX BASIC error
handling. If you specify the /NOSETUP qualifier, VAX BASIC will attempt
to optimize your program by omitting these calls. If your program contains
any of the following elements, VAX BASIC provides an informational
diagnostic and does not optimize your program:
e

CHANGE statements

DEF or DEF* statements

Dynamic string variables

Executable DIM statements

EXTERNAL string functions

MAT statements

MOVE statements for an entire array

ON ERROR statements

READ statements

REMAP statements

RESUME statements

WHEN blocks

All graphics statements

String concatenation

Built-in string functions

Virtual array declarations

Note that program modules compiled with the /NOSETUP qualifier cannot
perform I/O and have no error-handling capabilities. If an error occurs in
such a module, the error is resignaled to the calling program. The default is
/SETUP.

Environment Commands

2-17

COMPILE

¢ [NOJCDD_DEFINITIONS
_

[NOJENVIRONMENT

/[NO]SHOW[{ i } ( ! {xgch;_uos

. [NOJOVERRIDE

)]
)

The /SHOW qualifier (when used with the /LIST qualifier) tells VAX BASIC
what to include in the compiler listing file. You can specify the following
/SHOW qualifier items:

CDD_DEFINITIONS causes VAX BASIC to include a section of

translated CDD definitions
e

ENVIRONMENT causes VAX BASIC to include a list compilation

qualifiers in effect
e

INCLUDE causes VAX BASIC to include a section on the contents of any
%2INCLUDE files

MAP causes VAX BASIC to include a storage allocation map section

OVERRIDE cancels the effect of all %NOLIST directives in the source
program

For example, if you specify the following command, VAX BASIC includes a
storage allocation map section in the compiler listing:
COMPILE/LIST/SHOW=MAP

If you specify a /SHOW qualifier but do not specify any /SHOW items, VAX
BASIC includes all the aforementioned sections in the listing. If you specify

/NOSHOW, VAX BASIC does not add any additional sections to the compiler
listing. The default is /SHOW.

/SINGLE
The /SINGLE qualifier causes VAX BASIC to allocate 32 bits of storage in
F_floating format as the default size for all floating-point data not explicitly
typed in the program. Untyped floating-point values are treated as SINGLE

values and must bein the SINGLE range or VAX BASIC signals the error
“Floating-point error or overflow.” Table 1-2in this manual lists VAX BASIC

data types and ranges. The defaultis /SINGLE.

2-18

Environment Commands

COMPILE

/[NOJSYNTAX_CHECK
The /SYNTAX_CHECK qualifier causes VAX BASIC to perform
syntax checking after each program line is typed. If you specify
/NOSYNTAX_CHECK, VAX BASIC does not perform syntax checking
after each program line is typed. The default is /NOSYNTAX CHECK
/[NOJTRACEBACK
The /TRACEBACK qualifier causes VAX BASIC to include traceback

information in the object file that allows reporting of the sequence of calls
that transferred control to the statement where an error occurred. The
/NOTRACEBACK qualifier tells VAX BASIC not to include traceback
information in the object file. The default is TRACEBACK.
REAL

/TYPE DEFA ULT{ : }

:’)"ET53?_

EXPLICIT
The /TYPE_DEFAULT qualifier sets the default data type (REAL,
INTEGER, or DECIMAL) for all data not explicitly typed in your program
or specifies that all data must be explicitly typed (EXPLICIT).

REAL specifies that all data not explicitly typed is floating-point data of
the default size (SINGLE, DOUBLE, GFLOAT, or HFLOAT).

INTEGER specifies that all data not explicitly typed is integer data of
the default size (BYTE, WORD, or LONG).

DECIMAL specifies that all data not explicitly typed is packed decimal
data of the default size.

EXPLICIT specifies that all data in a program must be explicitly typed.
Implicitly declared variables cause VAX BASIC to signal an error.

The default is TYPE_DEFAULT=REAL.

/VARIANT{ * lint-const
The /VARIANT qualifier establishes int-const as a value to be used in
compiler directives. The variant value can be referenced in a lexical
expression with the lexical function, %#VARIANT. Int-const always has a data
type of LONG. The default is /VARIANT=0.

Environment Commands

2-19

COMPILE

/INOJWARNINGS [ { = } { [NOJINFORMATIONALS }]
:

[NOJWARNINGS

The /WARNINGS qualifier causes VAX BASIC to display warning or
informational messages, or both. If you specify /WARNINGS but do

not specify a warning clause, VAX BASIC displays both warnings and
informational messages. If you specify INOWARNINGS, VAX BASIC

does not display warning and informational messages. The default is
/WARNINGS.
/WORD

The /WORD qualifier causes VAX BASIC to allocate 16 bits of storage as
the default for all integer data not explicitly typed in the program. Untyped
integer values are treated as WORD values and must be in the range
—32768 to 32767 or VAX BASIC signals the error “Integer error or overflow.”
Table 1-2 in this manual lists VAX BASIC data types and ranges. The

default is /[LONG.
In the following example, VAX BASIC compiles the program LETSGO and

creates a new version of the object file as well as a listing file. In addition,
VAX BASIC allocates 64 bits of storage in D_FLOAT format as the default

for all floating point data not explicitly typed in the program.

Example

COMPILE LETSGO/DOUBLE/LIST

2—-20

Environment Commands

CONTINUE

CONTINUE
The CONTINUE command continues program execution after VAX BASIC
executes a STOP statement or encounters a CTRL/C.

Format

CONTINUE

Syntax Rules

None.

Remarks

After a STOP statement or a CTRL/C, you can enter immediate mode
commands and resume program execution with the CONTINUE
command.

After a STOP statement or a CTRL/C, you cannot resume program
execution if you have made source code changes or additions.

Example

$BAS-I-STO,

Stop

~-BAS-I-FROLINMOD,

from line

module

ABC

Ready

CONTINUE

Environment Commands

2-21

DELETE

DELETE
The DELETE command removes a specified line or range of lines from the

program currently in memory.

Format

DELETE line-num [‘.””e‘””m ]
Jine-num...

Syntax Rules

None.

Remarks

You cannot specify the DELETE command on programs that do not

contain line numbers.
2.

The separator characters (comma or hyphen) allow you to delete
individual lines or a block of lines.

If you separate line numbers with commas, VAX BASIC deletes each

specified line number.
*

If you separate line numbers with a hyphen, VAX BASIC deletes the
inclusive range of lines. The lower line number must be specified
first. If it is not specified first, the DELETE command has no effect.

You can combine individual line numbers and line ranges in a single
DELETE command. Note, however, that a line number range must be

followed by a comma and not another hyphen, or VAX BASIC signals an
error.

2-22

Environment Commands

DELETE

VAX BASIC signals an error if there are no lines in the specified range
or if you specify an illegal line number.

Examples

Example 1
DELETE

Example 2
DELETE

70-80,

110,

124

Example 3
DELETE

50,60,90-110

Environment Commands

2-23

EDIT

EDIT
The EDIT command allows you to edit individual program lines in the
BASIC environment while invoking an editor. EDIT with no arguments
invokes a text editor and reads the current program into the editor’s buffer.

Format

EDIT

[line-num search-clause [ replace-clause ||

search-clause:

delim unq-str1 delim

replace-clause:

[ung-str2 ][ delim [ int-consi1 ][ ,int-const2 ] ]

Syntax Rules

Line-num specifies the line to be edited.

Search-clause specifies the text you want to remove or replace. Ung-strl
is the search string you want to remove or replace.

Replace-clause specifies the replacement text and the occurrence of the
search string you want to replace.
o

Ung-str2 is the replacement string.

Int-constl specifies the occurrence of ung-strl you want to replace.

If you do not specify an occurrence, VAX BASIC replaces the first
occurrence of ung-strl.
*

Int-const2 specifies the line number of a block of program code where

you want VAX BASIC to begin the search.
4.

Delim can be any printing character not used in ung-strl or ung-str2.

The examples for this command use the slash (/) as a delimiter.

2-24

Environment Commands

EDIT

Remarks

The delim characters in search-clause must match, or VAX BASIC

signals an error.
If the delimiter you use to signal the end of replace-clause does not

match the delimiter used in search-clause, VAX BASIC does not signal
an error and treats the end delimiter as part of ung-str2.

VAX BASIC replaces or removes text in a program line as follows:
Ifung-strl is found, VAX BASIC replaces it with unq-str2.
*

If ung-strl is not found, VAX BASIC signals an error.

If ung-strl is null, VAX BASIC signals “No change made”.

Ifung-str2 is null, VAX BASIC deletes unqg-strl.

VAX BASIC matches and replaces strings exactly as you type them.

If unqg-strl is uppercase, VAX BASIC searches for an uppercase
string. If it is lowercase, VAX BASIC searches for a lowercase

string.

VAX BASIC displays the edited line with changes after the EDIT
command successfully executes.
If you specify a line number with no text parameters, VAX BASIC
displays the line.

The EDIT command followed by a carriage return causes VAX BASIC
to save your current source file in BASEDITMP.BAS and automatically

invoke VAX EDT as the default text editor.
At DCL level, you can override the default text editor. To do this, assign

the logical name BASIC$EDIT to another editor such as VAXTPU or
Language-Sensitive Editor before entering the BASIC environment.
For instance, in the following example, BASIC$EDIT is defined to be
TPUS$EDIT. The EDIT command followed by a carriage return will then
invoke VAXTPU as the default text editor.
$

DEFINE BASICSEDIT TPUSEDIT

If you define BASIC$EDIT to be an editor other than VAX EDT,
VAXTPU, or Language-Sensitive Editor, VAX BASIC spawns a

subprocess to invoke the editor assigned to BASIC$EDIT.

Environment Commands

2-25

EDIT

When you finish editing your program and exit from the editor, the
edited program is the program currently in memory, and the context of
the BASIC environment is unchanged. Note that VAX BASIC deletes all
versions of BASEDITMP.BAS when you return to VAX BASIC from the
editor.

Example

Ready
LIST

100

100 NEW_STRINGS$

= LEFT$ (STRINGS$,12)

EDIT 100 /LEFT$/RIGHTS$/3,2
LIST

100

100 NEW_STRING$

2-26

Environment Commands

= RIGHTS (STRINGS,12)

EXIT

EXIT
The EXIT command or CTRL/Z clears the memory and returns control to the
operating system.

Format

EXIT

Syntax Rules

None.

Remarks

If you type EXIT after creating a new program or editing an old program
without first typing SAVE or REPLACE, VAX BASIC signals “Unsaved

change has been made, CTRL/Z or EXIT to exit.” The message warns
you that the new or revised program will be lost if you do not SAVE or

REPLACE it. If you type EXIT again, VAX BASIC exits from the BASIC
environment whether you have saved your changes or not.

Environment Commands

2-27

EXIT

Example

EXIT

$BASIC-W-CHANGES,
Ready
SAVE
EXIT

Ready

2-28

Environment Commands

unsaved change has been made,

CTRL/Z or EXIT to exit

HELP

HELP
The HELP command displays online documentation for VAX BASIC
commands, keywords, statements, functions, and conventions.

Format
HELP

[ung-str]...

Syntax Rules

Ungq-str is a VAX BASIC topic, keyword, command, statement, function,

or convention.
The first ung-str must be one of the topics described in the HELP file. If
it is not, VAX BASIC displays a list of topics for you to choose from.

You can specify a subtopic after the topic. Separate one ung-str from
another with a space.
You can use the asterisk (*) wildcard character in ung-str. VAX BASIC

then matches any portion of the specified topic.

Remarks

If you type HELP with no parameters, VAX BASIC displays a list of
statements, functions, compiler directives, compiler commands and

language topics.
If the ung-str you specify is not a unique topic or subtopic, VAX BASIC

displays information on all topics or subtopics beginning with unqg-str.
An asterisk (*) indicates that you want to display information that
matches any portion of the topic you specify. For example, if you type

HELP GO*, VAX BASIC displays information on the GOSUB statement
and the GOTO statement.
Environment Commands

2-29

HELP

When information on a particular topic or subtopic is not available, VAX
BASIC signals the message “Sorry, no documentation on unq-str” and
provides a list of alternative HELP topics to choose from.

Example

Ready

Help

GO*

GOSUB

The GOSUB statement transfers control to a

specified line number or

label and stores the location of the GOSUB statement
return from the

for eventual

subroutine.

Example
200

GOSUB

1100

Additional

information available:

Syntax
GOTO

The GOTO statement transfers control to a specified line number or
label.

Example

GOTO 200

Additional

information available:

Syntax

Topic?

2-30

Environment Commands

IDENTIFY

IDENTIFY
The IDENTIFY command displays an identification header on the

controlling terminal. The header contains the name and version number
of VAX BASIC.

Format
IDENTIFY

Syntax Rules

None.

Remarks

The message displayed by the IDENTIFY command includes the name of
the VAX BASIC compiler and the version number.

Example

IDENTIFY
VAX BASIC V3.4

Environment Commands

2-31

INQUIRE

INQUIRE
The INQUIRE command is a synonym for the HELP command. See the
HELP command for more information.

2-32

Environment Commands

LIST and LISTNH

LIST and LISTNH
The LIST command displays the program lines of the program currently
in memory. Line numbers are sequenced in ascending order. The LISTNH
command displays program lines without the program header.

Format

]
LIST[NH] | line-num ["‘.””e'””’”
Jine-num...
Syntax Rules
A line-num followed by a hyphen (-) and a carriage return displays the
specified line and all remaining lines in the program.

Remarks

The LIST command displays program lines, along with a header
containing the program name, the current time, and the date. To
suppress the program header, type LISTNH.

LIST without parameters displays the entire program.

3. The separator characters (comma or hyphen) allow you to display
individual lines or a block of lines.

If you separate line numbers with commas, VAX BASIC displays

If you separate line numbers with hyphens, VAX BASIC displays the
inclusive range of lines. The lower line number must come first. If it

each specified line number.

does not, LIST has no effect.

Environment Commands

2-33

LIST and LISTNH

You can combine individual line numbers and line ranges in a single

LIST command. Note, however, that a line number range must be
followed by a comma and not another hyphen, or VAX BASIC signals
an

error.

A hyphen between the list command and line-num causes VAX BASIC

signal an error.

VAX BASIC displays the source program lines in the order you specify

in the command line. VAX BASIC displays line 100 before line 10 if you
type LIST 100,10.

Example

Example
LIST

200-300

Output

2-34

200

%IF

300

%END

%VARIANT =

%IF

Environment Commands

$THEN

$ABORT

LOAD

LOAD
The LOAD command makes a previously created object module or modules
available for execution with the RUN command.

Format

LOAD

file-spec [ + file-spec ] ...

Syntax Rules
File-spec must be a VAX BASIC object module or VAX BASIC signals an
error. OBJ is the default file type. If you specify only the file name, VAX
BASIC searches for an OBJ file in the current default directory.

Remarks

1. Each device and directory specification applies to all following file
specifications until you specify a new directory or device.

2. The LOAD command accepts multiple device, directory, and file
specifications.

3. VAX BASIC does not process the loaded object files until you issue the
RUN command. Consequently, errors in the loaded modules may not be
detected until you execute them.

VAX BASIC signals an error in the following cases:
o

If the file is not found

If the file specification is not valid

If the file is not a VAX BASIC object module

If run-time memory is exceeded

Errors do not change the program currently in memory.
Environment Commands

2-35

LOAD

The LOAD command clears all previously loaded object modules from
memory.

Typing the LOAD command does not change the program currently in
memaory.

Example

LOAD

2-36

PROGA

PROGB

Environment Commands

PROGC

LOCK

LOCK
The LOCK command changes default values for COMPILE command
qualifiers. It is a synonym for the SET command. See the SET command for
more information.

Environment Commands

2-37

NEW

NEW
The

NEW command clears VAX BASIC memory and allows you to assign a

name to a new program.

Format

NEW

[prog-name |

Syntax Rules

Prog-name is the name of the program you want to create. VAX BASIC
allows program names to contain a maximum of 39 characters. You can use
any combination of alphanumeric characters in your program name, as well
as the dollar sign ($), hyphen (-), and underscore (_) characters.

Remarks

VAX BASIC signals an error if prog-name exceeds 39 characters.

VAX BASIC signals “error in program name” if you specify a file type.

If you do not specify a prog-name, VAX BASIC prompts with:
New

file

name--

The default name is
NONAME. If you do not provide a prog-name in
response to the prompt, VAX BASIC assigns the file name NONAME to
your program.

2-38

When you type the NEW command, the program currently in memory
is cleared. Program modules loaded with the LOAD command remain
unchanged.

Environment Commands

NEW

Example

NEW PROG1

Environment Commands

2-39

OLD

OLD
The OLD command brings a previously created VAX BASIC program into
memory.

Format

OLD

[file-spec]

Syntax Rules

If you do not name a file-spec, VAX BASIC prompts for one. If you do
not enter a file-spec in response to the prompt, VAX BASIC searches for
a file named NONAME.BAS in the current default directory.

The default file type is BAS.

If the VAX BASIC compiler cannot find the file you specify, VAX BASIC
signals the error “File not found”.

When the specified file is found, it is placed in memory and any program

Remarks

currently in memory is erased. If VAX BASIC does not find the specified

file, the program currently in memory does not change.

Example

OLD

CHECK

Ready

2-40

Environment Commands

RENAME

RENAME
The RENAME command allows you to assign a new name to the program
currently in memory. VAX BASIC does not write the renamed program to a
file until you save the program with the REPLACE or SAVE command.

Format

RENAME

[ prog-name |

Syntax Rules
Prog-name specifies the new program name. VAX BASIC allows program
names to contain a maximum of 39 characters. You can use any

combination of alphanumeric characters in your program name, as well
as the dollar sign ($), hyphen (-), and underscore (_) characters.
If you specify a file type, VAX BASIC signals the error “Error in program
name.”

Remarks

The program you want to rename must be in memory. If you type

RENAME with no program in memory, VAX BASIC renames the default
program, NONAME, to the specified prog-name.

If you do not specify a prog-name, VAX BASIC renames the program

currently in memory NONAME.

Environment Commands

2-41

RENAME

You must type SAVE or REPLACE to write the renamed program to a
file. If you do not type SAVE or REPLACE, VAX BASIC does not save

the renamed program.
4.

The RENAME command does not affect the original saved version of the
program.

Example

OLD

TEST

Ready
RENAME NEWTEST
Ready
LIST

NEWTEST

06-0CT-1989

"This

program is

13:50

simple test"

Ready

SAVE

$BASIC-I-FILEWRITE,

NEWTEST written to

file:

USERS$$SDISK: [SMITH.COMS]NEWTEST.BAS;5
Ready

In this example, the OLD command calls the program named TEST into
memory. The RENAME command renames TEST to NEWTEST and the

SAVE command writes NEWTEST.BAS to a file. The original file, TEST.BAS

is not changed and is not deleted from your account.

2-42

Environment Commands

REPLACE

REPLACE
The REPLACE command writes the current program back to the file
specified by the last OLD command.

Format

REPLACE

Syntax Rules

None.

Remarks

1.
2.

If you do not have write access to the directory containing the original

file, VAX BASIC signals an error message.

VAX BASIC creates and saves a new version of the file, incrementing the
version number by 1 unless you supplied a specific version number with
the OLD command.

A REPLACE command following a NEW command or a SCRATCH
command causes VAX BASIC to write the program in memory to the
current default directory.

A REPLACE command following a RENAME command writes the file to
the directory specified in the OLD command with the file name specified
in the RENAME command.

Environment Commands

2-43

REPLACE

Example

DIR NODE: :USER$SDISK: [BASICUSER] TEST.BAS

Directory USER$$SDISK: [BASICUSER]
TEST.BAS;1

Total

BASIC

VAX

BASIC

file.

V3.4

Ready

OLD NODE: :USER$$SDISK: [BASICUSER]TEST.BAS;

Ready
REPLACE

$BASIC-I-FILEWRITE,

TEST written

file:

USER$SDISK: [BASICUSER]TEST.BAS; 2
Ready
EXIT

DIR NODE: :USERS$SSDISK: [BASICUSER] TEST.BAS

Directory

USERS$SDISK: [BASICUSER]

TEST.BAS;1

Total

TEST.BAS;2

files.

2-44

Environment Commands

RESEQUENCE

RESEQUENCE
In a program with line numbers, the RESEQUENCE command allows you
to resequence the line numbers of the program currently in memory. VAX

BASIC also changes all references to the old line numbers so they reference
the new line numbers.

Format

RESEQUENCE

[line-num1 [ - line-num2 ] [ line-num3] ] [ STEP int-const ]

Syntax Rules

Line-numl is the line number in the program currently in memory

where resequencing begins. The default for line-num1 is the first line of
the program module.
2.

Line-num? is the optional end of the range of line numbers to be

resequenced. If you specify a range, VAX BASIC begins resequencing

with line-numl and resequences through line-num?2. If you do not
specify line-num2, VAX BASIC resequences the specified line. If you do
not specify either line-num1 or line-num2, VAX BASIC resequences the
entire program.

3. Line-num3 spécifies the new first line number; the default number
for the new first line is 100. You can specify line-num3 only when
resequencing a range of lines.
If line-num3 causes existing lines to be deleted or surrounded, VAX

BASIC signals an error.
4.

Int-const specifies the numbering increment for the resequencing

operation. The default for int-const is 10.

Environment Commands

2-45

RESEQUENCE

Remarks

You cannot specify the RESEQUENCE command on programs that do
not contain line numbers.

VAX BASIC signals an error when you try to resequence a program that
contains a %IF directive. VAX BASIC also signals an error when you try
to resequence a program that has a ZINCLUDE directive if the file to be
included contains a reference to a line number.

Before the RESEQUENCE command executes, VAX BASIC verifies the

syntax of the program. If the program is not syntactically valid, the
RESEQUENCE command does not execute.

VAX BASIC sorts the renumbered program in ascending order when the
RESEQUENCE command executes.

If the renumbering creates a line number greater than the maximum
line number of 32767, VAX BASIC signals an error.

VAX BASIC signals an error if resequencing causes a change in the order
in which program statements are to execute and does not resequence the
program.

VAX BASIC signals the error “Undefined line number” in the case of
undefined line numbers and does not resequence the program.

VAX BASIC corrects all line numbers for statements that transfer
control.

VAX BASIC does not modify the program currently in memory when the
RESEQUENCE command generates an error.

10. In general, the RESEQUENCE command is not recommended for
programs containing error handlers that test the value of ERL. However,
the RESEQUENCE command correctly modifies the program if the tests
that reference ERL are of this form:
ERL relational-operator int-lit

2-46

Environment Commands

RESEQUENCE

The RESEQUENCE command does not correctly renumber programs
if the test compares ERL with an expression or a variable, or if ERL
follows the relational operator. The following line number references, for
example, would not be correctly renumbered:
IF ERL = 1000 + A%

THEN

...

1000

> ERL THEN

...

Example

INPUT

"Enter a numeric value";A%

IF A%

= 20

THEN PRINT

"Bye"

GOTO done

ELSE GOTO

60 END

Output
15

INPUT

"Enter a numeric value";A%

IF A%

= 20

THEN PRINT

55
65

"Bye"

GOTO done

ELSE GOTO 10
END

In this example, the command RESEQUENCE 10-60 STEP 5 causes VAX
BASIC to resequence lines 10 through 60, incrementing each new line
number by 5.

Environment Commands

2-47

RUN

RUN
The RUN command allows you to execute a program from the BASIC
environment without first invoking the VMS Linker to construct an

executable image. In addition, the RUN command allows you to access
user specified and system shareable image libraries for undefined symbols.

Format

RUN[NH] [file-spec ]

Syntax Rules

None.

Remarks

Executing a Program

If you specify only the file name, VAX BASIC searches for a file with

a BAS file type in the current default directory.
e

If you do not supply a file-spec, VAX BASIC executes the program
currently in memory.

VAX BASIC signals the warning message “No main program” if you

do not supply a file-spec and do not have a program currentlyin
memory.

The RUNNH command is identical to RUN, except that it does not

display the program header, current date, and time.

2-48

Environment Commands

RUN

When you specify a file-spec with the RUN command, VAX BASIC

brings the program into memory and then executes it. You do not
have to bring a program into memory with the OLD command in
order to run it. The RUN command executes just as if the program

had been brought into memory with the OLD command.
If your program calls a subprogram, the subprogram must be
compiled and placed in memory with the LOAD command. If your
program tries to call a subprogram that has not been compiled and

loaded, VAX BASIC signals an error.
The RUN command does not create an object module file or a list

file.
When VAX BASIC encounters a STOP statement in the program,

the program stops executing and control passes to the BASIC
environment immediate mode.

Any VAX BASIC statement that does not require the creation of new
storage can be entered in immediate mode to debug the program.

You cannot create new variables in immediate mode.
Type the CONTINUE command to resume program execution.
The RUN command uses whatever qualifiers have been set, with the
exception of those that have no effect on a program running in the

BASIC environment. These qualifiers are as follows:

—

NOCROSS

—

NODEBUG

—

NOLIST

—

NOMACHINE

—

NOOBJECT

These qualifiers are always in effect when you run a program in the
environment.
2.

Accessing Shareable Images
To automatically access shareable image libraries, you must make

an assignment to the logical name BASIC$LIBn. For example:
$ ASSIGN DBAO:BABCOCK]|TESTLIB.OLB BASIC$LIBO

After you enter a command line, VAX BASIC will automatically
access your library to resolve undefined program symbols.

Environment Commands

2-49

RUN
If you have more than one library for the VMS Linker to search,
you must assign the first one as BASIC$LIBO, the second one as
BASIC$LIB1, the third as BASIC$LIB2, and so on.
If you do not number libraries consecutively, the VMS Linker does
not search past the first missing logical name.

As long as routines are contained in shareable images in libraries,
they are not required to be written in VAX BASIC to be accessed
with the RUN command.

VAX BASIC provides no default file specification for user-supplied
shareable image libraries; the current default device and the
directory are used.

After all possible shareable image libraries have been accessed,
VAX BASIC will subsequently search the default library
SYS$LIBRARY:.OLB with the logical name IMAGELIB to resolve
any additional undefined program symbols.

Example

RUN PROG1

PROG1

06-0CT-1989 13:52

6
10

Ready
RUNNH PROGI1

2-50

Environment Commands

SAVE

SAVE
The SAVE command writes the VAX BASIC source program currently in

memory to a file on the default or specified device.

Format

SAVE

[file-spec ]

Syntax Rules

None.

Remarks

If you do not supply a file-spec, VAX BASIC saves the file with the name
of the program currently in memory and the BAS default file type.

If you specify only the file name, VAX BASIC saves the program with
the default file type in the current default directory.

When you type the SAVE command, VAX BASIC writes a new version of
the program.

VAX BASIC stores the sorted program in ascending line number order.

You can store the program on a specified device. For example:
SAVE DUAL:NEWTEST.PRO

VAX BASIC saves the file

NEWTEST.PRO on disk DUA1.:.

Environment Commands

2-51

SAVE

Example

SAVE PROG_SAMP.BAS

$BASIC-I-FILEWRITE, PROG_SAMP written to file:
USERS$S$SDISK[BASICUSER]PROG SAMP.BAS;?2

2-52

Environment Commands

SCALE

SCALE
The SCALE command allows you to control accumulated round-off errors by
multiplying numeric values by 10 raised to the scale factor before storing

them.

Format

SCALE

int-const

Syntax Rules

Int-const specifies the power of 10 you want to use as the scaling factor.

Int-const must be an integer from 0 through 6 or VAX BASIC signals the

error “Illegal argument for command.”

Remarks

SCALE with no argument causes VAX BASIC to signal the error “Illegal

argument for command.”

SCALE affects only values of the data type DOUBLE.

VAX BASIC multiplies values using the scale factor you specify. For
example, the value 2.488888 is rounded as is shown in Table 2-1.

Environment Commands

2-53

SCALE

Multiplying a Numeric Value with the SCALE Command

Scale

Value Produced for 2.488888

Table 2-1:

2.48889

24
2.48

2.488

2.48888

2.4888

2.48889

Example

SCALE 2

2-54

Environment Commands

SCRATCH

SCRATCH
The SCRATCH command clears any program currently in memory, removes
any object files loaded with the LOAD command, and resets the program
name to NONAME.

Format

SCRATCH

Syntax Rules

None.

Remarks

None.

Example

SCRATCH

Environment Commands

2-55

SEQUENCE

SEQUENCE
The SEQUENCE command causes VAX BASIC to automatically generate

line numbers for your program text. VAX BASIC supplies line numbers for
your text until you end the procedure or reach the maximum line number
of 32767.

Format

SEQUENCE

[line-num ][, int-const ]

Syntax Rules

Line-num specifies the line number where sequencing begins.

Int-const specifies the line number increment for your program. If you do
not specify an increment, VAX BASIC defaults to the int-const specified
in the last SEQUENCE command; if there is no previous SEQUENCE
command, the default is 10.

Remarks

You cannot specify the SEQUENCE command on programs that do not

contain line numbers.

If you do not specify a line-num, the VAX BASIC default is the last line
inserted by a SEQUENCE command; if there is no previous SEQUENCE
command, the default is line number 100.

If you specify a line-num that already contains a statement, or if the
sequencing operation generates a line number that already contains
a statement, VAX BASIC signals “Attempt to sequence over existing
statement”, and returns to normal input mode.

2-56

Environment Commands

SEQUENCE

Type your program text in response to the line number prompt; the

carriage return ends each line and causes VAX BASIC to generate a new

line number.

5.
6.
7.

If you press CTRL/Z in response to the line number prompt, VAX BASIC
terminates the sequencing operation and prompts for another command.
When the maximum line number of 32767 is reached, VAX BASIC
terminates the sequencing process and returns to normal input mode.
VAX BASIC does not check syntax during the sequencing process.

Example

SEQUENCE

100,10

100 INPUT "Enter a numeric value";A%
110

IF A%

In this example, the command SEQUENCE 100,10 causes VAX BASIC to
automatically generate line numbers into the program text, beginning with

the line number 100 and incrementing each line by 10.

Environment Commands

2-57

SET

SET
The SET command allows you to specify VAX BASIC defaults for all
VAX BASIC qualifiers. Qualifiers control the compilation process and
the run-time environment. The defaults you set remain in effect for

all subsequent operations until they are reset or until you exit from the

compiler.

Format

SET

[/qualifier]...

Syntax Rules

/Qualifier specifies a qualifier keyword that sets a VAX BASIC default.

See the COMPILE command for a list of all VAX BASIC qualifiers and
their defaults.
2.

VAX BASIC signals the error “Unknown qualifier” if you do not separate

multiple qualifiers with commas (,) or slashes (/), or if you mix commas

and slashes on the same command line. The same error is signaled if
you separate qualifiers with a slash but do not prefix the first qualifier

with a slash.

Remarks

If you do not specify any qualifiers, VAX BASIC resets all defaults to the
defaults specified with the DCL command BASIC.

2-58

Environment Commands

SET

Examples

Example 1
SET /DOUBLE/BYTE/LIST

Example 2
SET DOUBLE,BYTE, LIST

In these examples, the SET command causes VAX BASIC to allocate 64 bits
of storage for all floating-point data, and to allocate 8 bits of storage for all

integer data. A source listing file is also created.

Environment Commands

2-59

SHOW

SHOW
The SHOW command displays the current defaults for the VAX BASIC
compiler on your terminal.

Format

SHOW

Syntax Rules

None.

Remarks

None.

2-60

Environment Commands

SHOW

Example

SHOW
VAX BASIC

Current Environment

3.4

DEFAULT DATA TYPE

INFORMATION:

09-0CT-1989

Status

LISTING FILE

Data type

REAL

NO List

Real

SINGLE

NO Cross

size

reference

CDD Definitions

Integer

size

Decimal

size

(15,2)

factor

Scale

10:05:56.57

INFORMATION INCLUDES:

LONG

Environment

NO Override of

NO Round decimal numbers

NO Machine

%NOLIST

code

Map

COMPILATION QUALIFIERS

Object

INCLUDE

IN EFFECT:

files

file

Overflow check integers

FLAGGERS:

Overflow check decimal numbers

NO Declining features

Bounds checking

NO BASIC PLUS

subset

NO Syntax checking
Lines
Variant

DEBUG

INFORMATION:

Traceback records

Warnings

NO Debug symbol

Informationals

records

Setup

Object Libraries

NONE

Ready

Environment Commands

2-61

UNSAVE

UNSAVE
The UNSAVE command deletes a specified file from storage.

Format
UNSAVE [ file-spec |

Syntax Rules

None.

Remarks

If you do not supply a file-spec, VAX BASIC deletes a file that has the
file name of the program currently in memory and a file type of BAS.

If you do not supply a file-spec and do not have a program in memory,
VAX BASIC searches for the default file NONAME.BAS.

If you do not specify a complete file name with a file type, VAX BASIC
deletes the file with the specified name and the BAS file type from the

default device and directory. Other file types with the same file name

are not deleted.

Example

UNSAVE

2-62

DBZ2:CHECK.DAT

Environment Commands

Chapter 3

Compiler Directives
Compiler directives are instructions that cause VAX BASIC to perform
certain operations as it translates the source program. This chapter
describes all of the compiler directives supported by VAX BASIC. The
directives are listed and discussed alphabetically.

Compiler Directives

3—1

%ABORT

%ABORT
The %ABORT directive terminates program compilation and displays a fatal
error message that you can supply.

Format

%ABORT

[ str-lit]

Syntax Rules

None.

Remarks

Only a line number or a comment field can appear on the same physical
line as the %ABORT directive.

VAX BASIC stops the compilation and terminates the listing file as soon
as it encounters a %2ABORT directive. An optional str-lit is displayed on

the terminal screen and in the compilation listing, if a listing has been
requested.

Example

3IF

3SVARIANT = 2
3ABORT

3END

3-2

%IF

Compiler Directives

%THEN

"Cannot

compile with variant

%CROSS

%CROSS
The %CROSS directive causes VAX BASIC to begin or resume accumulating
cross-reference information for the listing file.

Format

%CROSS

Syntax Rules

None.

Remarks
1. Only a line number or a comment field can appear on the same physical
line as the %CROSS directive.

2. The %CROSS directive has no effect unless you request both a listing
file and a cross-reference. For more information on listing file format,
see the VAX BASIC User Manual.

3. When a cross-reference is requested, the VAX BASIC compiler starts
or resumes accumulating cross-reference information immediately after
encountering the %2CROSS directive.

Example

%CROSS

Compiler Directives

3-3

%DECLARED

%DECLARED
The %2DECLARED directive is a built-in lexical function that allows you
to determine whether a lexical variable has been defined with the %LET

directive. If the lexical variable named in the %#DECLARED function is
defined in a previous %LET directive, the #DECLARED function returns
the value —1. If the lexical variable is not defined in a previous %LET
directive, the %DECLARED function returns the value 0.

Format

%DECLARED

(lex-var)

Syntax Rules

The %DECLARED function can appear only in a lexical expression.

The lex-var is the name of a lexical variable. Lexical variables are
always LONG integers.

Lex-var must be enclosed in parentheses.

Remarks

None.

3-4

Compiler Directives

%DECLARED

Example

Use the following code in %INCLUDE files
which reference constants that may be already defined.

UE = 0
FALSE DEFINED)
$IF $DECLARED (3TR
3 THEN

DECLARE LONG CONSTANT True = -1, False = 0
$LET $TRUE FALSE_DEFINED = -1

SEND

$IF

Compiler Directives

3-5

%IDENT

%IDENT
The %IDENT directive lets you identify the version of a program module.
The identification text is placed in the object module and printed in the

listing header.

Format

%IDENT

str-lit

Syntax Rules

Str-lit is the identification text. Str-lit can consist of up to 31 ASCII
characters. If it has more than 31 characters, VAX BASIC truncates the
extra characters and signals a warning message.

Remarks

Only a line number or a comment field can appear on the same physical
line as the %IDENT directive.

The VAX BASIC compiler inserts the identification text in the first
31 character positions of the second line on each listing page. VAX

BASIC also includes the identification text in the object module, if
the compilation produces one, and in the map file created by the VMS
Linker.
3.

The %IDENT directive should appear at the beginning of your program
if you want the identification text to appear on the first page of your

listing. If the %IDENT directive appears after the first program

statement, the text will appear on the next page of the listing file.

3-6

Compiler Directives

%IDENT
4. You can use the %IDENT directive only once in a module. If you specify
more than one %IDENT directive in a module, VAX BASIC signals a
warning and uses the identification text specified in the first directive.
5.

No default identification text is provided.

Example

$IDENT "Version 10"

Output
TIMESMAIN
Version 10

$IDENT "Version 10"

Compiler Directives

3-7

%IF-%THEN-%ELSE-%END %IF

%IF-%THEN-%ELSE-%END %IF
~

The %IF-%THEN-%ELSE-%END %IF directive lets you conditionally include
source code or execute another compiler directive.

Format

%IF

lex-exp %THEN code [ %ELSE code | %END %IF

Syntax Rules

Lex-exp is always a LONG integer.

Lex-exp can be:

A lexical constant named in a %LET directive.

An integer literal, with or without the percent sign suffix.

A lexical built-in function.

Any combination of the above, separated by valid lexical operators.
Lexical operators include logical operators, relational operators,

and the arithmetic operators for addition (+), subtraction (-),
multiplication (*), and division (/).

Code is VAX BASIC program code. It can be any VAX BASIC statement
or another compiler directive, including another %IF directive. You can
nest %IF directives to eight levels.

The %IF directive can appear anywhere in a program where a space is
allowed, except within a quoted string. This means that you can use the

Remarks

%IF directive to make a whole statement, part of a statement, or a block

of statements conditional.

3-8

Compiler Directives

%IF-%THEN-%ELSE-%END %IF
2.

%THEN, %ELSE, and %END %IF do not have to be on the same

physical line as %IF.

If lex-exp is true, VAX BASIC processes the %THEN clause. If lex-exp is
false, VAX BASIC processes the %ELSE clause. If there is no %ELSE
clause, VAX BASIC processes the %END %IF clause. The VAX BASIC
compiler includes statements in the %#THEN or %ELSE clause in the
source program and executes directives in order of occurrence.

4. You must include the %END %IF clause. Otherwise, VAX BASIC
assumes the remainder of the program is part of the last %#THEN or
%ELSE clause and signals the error “MISENDIF, missing END IF
directive” when compilation ends.

Example

$IF

(%VARIANT = 2)

$THEN DECLARE SINGLE hourly pay(100)
$ELSE $%IF

(%VARIANT = 1)

pay (100)
$THEN DECLARE DOUBLE salary

$ELSE $%ABORT "Can’t compile with specified variant”
$END

sEND

%IF

PRINT $%IF (%$VARIANT = 2)
$THEN ’Hourly Wage Chart’

GOTO Hourly routine

$ELSE ’Salaried Wage Chart’
GOTO Salary_routine
$END

3%IF

Compiler Directives

3-9

%INCLUDE

%INCLUDE
The %INCLUDE directive lets you include VAX BASIC source text from

another program file in the current program compilation. VAX BASIC also
lets you access record definitions in the VAX Common Data Dictionary

(CDD) and access commonly used routines from text libraries.

Format
Including a File

%INCLUDE

str-lit

Including a CDD Definition

%INCLUDE

%FROM %CDD str-lit

Including a File from a Text Library

%INCLUDE

str-lit %FROM %LIBRARY [str-lit]

Syntax Rules

Imncluding a File

Str-lit must be a valid file specification for the file to be included.
2.

Including a CDD Definition
Str-lit specifies a VAX CDD path name enclosed in quotation marks. The
path name can be in either DMU or CDO format. This directive lets you
extract a RECORD definition from the dictionary.

Including a File from a Text Library

Str-lit specifies a particular module to be included.

The optional str-lit identifies a specific text library in which the

included module resides. If the library name is not specified, VAX
BASIC uses the default library name BASIC$LIBRARY.

3-10

Compiler Directives

%INCLUDE

Remarks

Any statement that appears after an END statement inside an included
file causes VAX BASIC to signal an error.
Only a line number or a comment field can appear on the same physical

line as the %INCLUDE directive.
The VAX BASIC compiler includes the specified source file in the
program compilation at the point of the %2INCLUDE directive and prints

the included code in the program listing file if the compilation produces
one.

The included file cannot contain line numbers. If it does, VAX BASIC
signals the error “Line number may not appear in %INCLUDE file.”
All statements in the accessed file are associated with the line number
of the program line that contains the %INCLUDE directive. This means

that a %ZINCLUDE directive cannot appear before the first line number

in a source program if you are using line numbers.
A file accessed by 2INCLUDE can itself contain a 2INCLUDE directive.

All %IF directives in an included file must have a matching %2END %IF
directive in the file.
You can control whether or not included text appears in the compilation

listing with the [/NOJSHOW:INCLUDE qualifier to the COMPILE

command. When you specify /SSHOW:INCLUDE, the compilation listing
file identifies any text obtained from an included file by placing a
mnemonic in the first character position of the line on which the text

appears. The “n” specifies that the text was either accessed from a
source file or from a text library. The “I” tells you that the text was

accessed with the %INCLUDE directive and n is a number that tells you
the nesting level of the included text. See the VAX BASIC User Manual
for more information on listing mnemonics.
Including a File
If you do not specify a complete file specification, VAX BASIC uses the

default device and directory and the file type BAS.

Compiler Directives

3-11

%INCLUDE

10. Including a CDD Definition

In versions to VAX CDD/Plus Version 4.0, there are two types of

CDD path names: full and relative. A full path name begins with
CDD$TOP and specifies the complete path to the record definition.
A relative path name begins with any string other than CDD$TOP
and is appended to the current CDD$DEFAULT.
In VAX CDD/Plus Version 4.0 or higher, the pathnames described
previously are known as DMU pathnames, as distinct from CDO

pathnames. You can specify either a full DMU pathname, a full
CDO pathname, or a relative pathname. A full pathname consists
of a dictionary origin followed by a dictionary path. A full DMU

pathname has CDD$TOP as its origin. A full CDO pathname has
an anchor as its origin. See CDD/Plus documentation for detailed

information on pathnames.
If the record definition being accessed is in a CDO-format dictionary,
you can create a dependency relationship in the dictionary between a

dictionary representation of your program and the record definitions
that you include in the program. The dictionary representation of

the program is called a compiled module entity.
If you specify the /DEPENDENCY_DATA qualifier to the compiler

and your CDD$DEFAULT points to a CDO-format dictionary, a
compiled module entity is created for each compilation unit at

compile time in CDD$DEFAULT. No compiled module entity is
created if both conditions are not true.
If a compiled module entity exists for the program, an %INCLUDE
%FROM %CDD directive specifying a record description in a

CDO-format dictionary creates a relationship between the compiled
module entity and the CDO-format record definition.

If the record description specified in the pathname exists, it is copied

to the program, whether a compiled module entity can be created or
not.

When you use the ZINCLUDE directive to extract a record definition
from the CDD, VAX BASIC translates the CDD definition to the

syntax of the VAX BASIC RECORD statement.

3-12

Compiler Directives

%INCLUDE

You can use the /SSHOW:CDD_DEFINITIONS qualifier to specify

that translated CDD definitions (in RECORD statement syntax) are
included in the compilation listing file. VAX BASIC places a “C” in
column 1 when the translated RECORD statement appears in the
listing file.

When you specify /SHOW:NOCDD_DEFINITIONS, VAX BASIC does
not include the CDD definition in the listing file. However, VAX
BASIC still includes the names, data types, and offsets of the CDD
record components in the program listing’s allocation map.

See the VAX BASIC User Manual and the CDD/Plus documentation
for more information on dictionary data definitions.
11. Including a File from a Text Library

The VAX BASIC compiler searches through the specified text library
for the module named and compiles the module upon encountering
the %INCLUDE directive.

VAX BASIC allows only 16 text libraries to be opened at one
time. Therefore, you cannot have %INCLUDE directives from a
text library nested more than 16 levels deep. If you exceed this
maximum, VAX BASIC signals an error message.

If you do not specify a directory name and file type, VAX BASIC uses

the default device and directory and the file type TLB.

VAX BASIC provides the text library BASIC$STARLET.
BASIC$STARLET contains condition codes and other symbols
defined in the system object and shareable image libraries. Using
the definitions from BASIC$STARLET allows you to reference
condition codes and other system-defined symbols as local, rather
than global symbols. To create your own text libraries using the
VMS Librarian Utility, see the VMS Librarian Utility Manual.

Examples

Example 1
!Including a File
%INCLUDE

"YESNO"

Compiler Directives

3-13

%INCLUDE

Example 2
!Including a CDD
%$INCLUDE

%FROM

Definition

$%CDD

"CDDS$TOP.EMPLOYEE"

Example 3
!Including

$INCLUDE
!The

a CDD

Definition with

a CDO-format

pathname

%FROM %CDD

anchor

"MYNODE: :MYSDISK: [MY DIR]PERSONNEL.EMPLOYEE"
is MYNODE::MY$DISK:[MY
DIR]

Example 4
!Including a File

SINCLUDE

3-14

from a

"EOF CHECK"

Compiler Directives

Text

Library

S$FROM $%LIBRARY

"SYS$LIBRARY:BASIC_LIB.TLB"

%LET

%LET
The %LET directive declares and provides values for lexical variables.
You can use lexical variables only in conditional expressions in the
%IF-%THEN-%ELSE directive and in lexical expressions in subsequent
%LET directives.

Format

%LET

%lex-var = lex-exp

Syntax Rules

Lex-var is the name of a lexical variable. Lexical variables are always
LONG integers.

Lex-var must be preceded by a percent sign (%) and cannot end with a
dollar sign ($) or percent sign.

Lex-exp can be any of the following:

A lexical variable named in a previous %LET directive.

An integer literal, with or without the percent sign suffix.
*

A lexical built-in function.

Any combination of the above, separated by valid lexical operators.
Lexical operators can be logical operators, relational operators,
and the arithmetic operators for addition (+), subtraction (-),
multiplication (*), and division (/).

Compiler Directives

3-15

%LET

Remarks

Only a line number or a comment field can appear on the same physical
line as the %LET directive.

You cannot change the value of lex-var within a program unit once it

has been named in a %LET directive. For more information on coding
conventions, see the VAX BASIC User Manual.

Example

3LET

3-16

%DEBUG
ON =

Compiler Directives

%LIST

%LIST
The %LIST directive causes the VAX BASIC compiler to start or resume
accumulating compilation information for the program listing file.

Format

%LIST

Syntax Rules

None.

Remarks

Only a line number or a comment field can appear on the same physical
line as the %LIST directive.

The %LIST directive has no effect unless you requested a listing file.
For more information on listing file format, see the VAX BASIC User
Manual.

As soon as it encounters the %LIST directive, the VAX BASIC compiler
starts or resumes accumulating information for the program listing file.
Thus, the directive itself appears as the next line in the listing file.

Example

SLIST

Compiler Directives

3—-17

%NOCROSS

%NOCROSS
The %NOCROSS directive causes the VAX BASIC compiler to stop

accumulating cross-reference information for the program listing file.

Format
%NOCROSS

Syntax Rules

None.

Remarks

Only a line number or a comment field can appear on the same physical
line as the %NOCROSS directive.
The VAX BASIC compiler stops accumulating cross-reference information
for the program listing file immediately after encountering the
%NOCROSS directive.

The %NOCROSS directive has no effect unless you request a listing file
and cross-reference information.

DIGITAL recommends that you do not embed a %NOCROSS directive
within a statement. Embedding a %ZNOCROSS directive within a
statement makes the accumulation of cross-reference information
unpredictable. For more information on listing file format, see the VAX
BASIC User Manual.

3-18

Compiler Directives

%NOCROSS

Example

*NOCROSS

Compiler Directives

3-19

%NOLIST

%NOLIST
The %NOLIST directive causes the VAX BASIC compiler to stop
accumulating compilation information for the program listing file.

Format

%NOLIST

Syntax Rules

None.

Remarks

Only a line number or a comment field can appear on the same physical
line as the %#NOLIST directive.

As soon as it encounters the ZNOLIST directive, the VAX BASIC

compiler stops accumulating information for the program listing file.
Thus, the directive itself does not appear in the listing file.
3.

The %NOLIST directive has no effect unless you requested a listing

In VAX BASIC, you can override all %#NOLIST directives in a program

file.

with the /SHOW:OVERRIDE qualifier. For more information on listing
file format, see the VAX BASIC User Manual.

Example

SNOLIST

3-20

Compiler Directives

%PAGE

%PAGE
The %PAGE directive causes VAX BASIC to begin a new page in the
program listing file immediately after the line that contains the %PAGE
directive.

Format

%PAGE

Syntax Rules

None.

Remarks
1. Only a line number or a comment field can appear on the same physical
line as the %PAGE directive.

9. The %PAGE directive has no effect unless you request a listing file.

Example

$PAGE

Compiler Directives

3—-21

%PRINT

%PRINT
The %PRINT directive lets you insert a message into your source code that
the VAX BASIC compiler prints during compilation.

Format
%PRINT

str-lit

Syntax Rules

None.

Remarks

Only a line number or a comment field can appear on the same physical
line as the %PRINT directive.

VAX BASIC will print the message specified as soon as it encounters a

%PRINT directive. Str-lit is displayed on the terminal screen and in the

compilation listing.

Example

3IF

%DEBUG =

$PRINT

"This

$%THEN

a debug compilation®

Output
$tBASIC-S-USERPRINT,

3-22

Compiler Directives

This

debug compilation

%REPORT

%REPORT
The %REPORT directive lets you record a dependency relationship between
the compiled module entity for your program and the data definitions in
CDD/Plus dictionaries. The data definitions are not copied into the program.

Format

%REPORT %DEPENDENCY

str-lit [ relationship-type |

Syntax Rules
str-lit specifies a path name in a CDO-format dictionary. It can be
either a DMU-format pathname or a CDO-format pathname, enclosed
in quotation marks. This specifies a dictionary entity, such as a form
definition or an Rdb/VMS database, that the program references.
relationship-type specifies a valid CDD/Plus protocol; it must be

enclosed in quotation marks if specified. The default relationship-type is
CDD$COMPILED_DEPENDS_ON.

Remarks
For this directive to be meaningful, you must specify the

/DEPENDENCY_DATA qualifier at compile time. If DEPENDENCY is
not specified, the compiler will simply check syntax and otherwise ignore
the %2REPORT directive.

Your current CDD$DEFAULT and str-lit must refer to CDO-format
dictionaries (not necessarily the same one).

Compiler Directives

3—23

%REPORT

If you specify the DEPENDEN
/
CY_DATA qualifier to the compiler,
and if CDD$DEFAULT points to a CDO-format dictionary, a compiled
module entity is created in CDD$DEFAULT for each compilation unit.

No compiled module entity is created if both conditions are not true.
4.

The %REPORT %DEPENDENCY directive creates a dependency
relationship in the dictionary between the compiled module entity for

the program and the CDO-format dictionary entity to which it refers.

Example

!Establish access

'on

to the

specified node,

and

form PINK_SLIP

report

a dictionary

the program’s

dependency
!relationship with the form.
$REPORT %DEPENDENCY “MYNODE::MYsDISK:[MYDIR]PERSONNEL.FORMS.PINK_SLIP"
IRelationship

3-24

Compiler Directives

CDD$COMPILED_DEPENDS
ON,

the default.

%SBTTL

%SBTTL
The %SBTTL directive lets you specify a subtitle for the program listing file.

Format

sir-lit

%SBTTL

Syntax Rules

Str-lit can contain up to 45 characters.

Remarks
1.

VAX BASIC truncates extra characters from sir-lit and does not signal a
warning or error.

Only a line number or a comment field can appear on the same physical

line as the %SBTTL directive.

The specified subtitle appears underneath the title on the second line of
all pages of source code in the listing file until the VAX BASIC compiler
encounters another %SBTTL or %TITLE directive. VAX BASIC clears
the subtitle field before the allocation map section of the listing is
generated. This way, you only get a subtitle on the listing pages that
contain source code.

Because VAX BASIC associates a subtitle with a title, a new %TITLE
directive sets the current subtitle to the null string. In this case, no
subtitle appears in the listing until VAX BASIC encounters another
%SBTTL directive.

Compiler Directives

3—25

%SBTTL

If you want a subtitle to appear on the first page of your listing, the
%SBTTL directive should appear at the beginning of your program,
immediately after the %TITLE directive. Otherwise, the subtitle will
start to appear only on the second page of the listing.

If you want the subtitle to appear on the page of the listing that contains
the %SBTTL directive, the %SBTTL directive should immediately

follow a %PAGE directive or a %TITLE directive that follows a %PAGE

directive.
7.

The %SBTTL directive has no effect unless you request a listing file.

Example

100

200

$TITLE

"Learning to Program in VAX BASIC"

$SBTTL

"Using FOR-NEXT Loops"

REM

THIS PROGRAM

DATA

300

IS A SIMPLE

TEST

END

Output
TESTS$SMAIN

Learning to Program in VAX BASIC
Using FOR-NEXT Loops

100

$TITLE

"Learning to

$SBTTL

"Using FOR-NEXT

REM THIS PROGRAM

200

DATA

300

END

10
11

3-26

Compiler Directives

Program in VAX BASIC"

Loops"

IS A SIMPLE

TEST
‘

%TITLE

%TITLE
The %TITLE directive lets you specify a title for the program listing file.

Format

%TITLE

str-lit

Syntax Rules

Str-lit can contain up to 45 characters.

Remarks
1. VAX BASIC truncates extra characters from str-lit and does not signal a
warning or error.

Only a line number or a comment field can appear on the same physical

line as the %TITLE directive.

The specified title appears on the first line of every page of the listing file
until VAX BASIC encounters another %TITLE directive in the program.

The %TITLE directive should appear on the first line of your program,
before the first statement, if you want the specified title to appear on the
first page of your listing.

If you want the specified title to appear on the page that contains the
%TITLE directive, the %TITLE directive should immediately follow a
%PAGE directive.

Because VAX BASIC associates a subtitle with a title, a new %TITLE

The %TITLE directive has no effect unless you request a listing file.

directive sets the current subtitle to the null string.

Compiler Directives

3-27

%TITLE

Example

100

$TITLE

200

300

"Learning to Program in VAX BASIC"

REM

THIS

DATA

PROGRAM

IS A

SIMPLE

TEST

END

Output
TESTSMAIN
1

Learning to Program in VAX BASIC
3TITLE

"Learning to Program in VAX BASIC"

$SBTTL

"Using FOR-NEXT

REM THIS

100

200

10
11

3-28

Compiler Directives

DATA 1,

NEXT
300

END

PROGRAM

Loops"

A SIMPLE

TEST

%VARIANT

%VARIANT
The %VARIANT directive is a built-in lexical function that allows you to
conditionally control program compilation. %VARIANT returns an integer
value when you reference it in a lexical expression. You set the variant
value with the /VARIANT qualifier when you compile the program or with
the SET %VARIANT command.

Format

%VARIANT

Syntax Rules

None.

Remarks
1. The %VARIANT function can appear only in a lexical expression.

2. The %VARIANT function returns the integer value specified either with
the COMPILE /VARIANT command, the SET /VARIANT command, or
the DCL command BASIC. The returned integer always has a data type
of LONG.

Compiler Directives

3-29

%VARIANT

Example

$LET

%VMS

$LET

%RSX =1

3LET
$IF

%RSTS

= 2

%VARIANT =

$%VMS

% THEN

RELSE

%IF

3%VARIANT

3RSX OR

$VARIANT

$THEN

$ELSE

%END

$END

3-30

$%ABORT

%IF

Compiler Directives

"Illegal

compilation

3RSTS

variant"

Chapter 4

Statements and Functions
This chapter provides reference material on all of the VAX BASIC
statements and functions. The statements and functions are listed in
alphabetical order and each description contains the following sections:
Definition

A description of what the statement does.

Format

The required syntax for the statement.

Syntax Rules
Remarks

Example

Any rules governing the use of parameters, separators, or other
syntax items.

Explanatory remarks concerning the effect of the statement on

program execution and any restrictions governing its use.

One or more examples of the statement in a VAX BASIC program.

Where appropriate, sample output is also shown.

Statements and Functions

ABS

ABS
The ABS function returns a floating-point number that equals the absolute
value of a specified floating-point expression.

Format

real-var = ABS (real-exp)

Syntax Rules

None.

Remarks

The argument of the ABS function must be a real expression. When
the argument is a real expression, VAX BASIC returns a value of the

same floating-point size. When the argument is not a real expression,
VAX BASIC converts the argument to the default floating-point size and
returns a value of the default floating-point size.
2.

The returned floating-point value is always greater than or equal to

zero. The absolute value of 0 is zero. The absolute value of a positive
number equals that number. The absolute value of a negative number
equals that number multiplied by —1.

4-2

Statements and Functions

ABS

Example

5.1273

ABS (-100

-39

ABS(B),

G)
A

Output
39

512.73

Statements and Functions

4-3

ABS%

ABS%
The ABS% function returns an integer that equals the absolute value of a
specified integer expression.

Format

int-var = ABS% (int-exp)

Syntax Rules

None.

Remarks

If you specify a floating-point expression for int-exp, VAX BASIC
truncates it to an integer of the default integer size.

The returned value is always greater than or equal to zero. The absolute
value of 0 is zero. The absolute value of a positive number equals that
number. The absolute value of a negative number equals that number
multiplied by —1.

4-4

Statements and Functions

ABS%

Example

5.1273

A = ABS%(-100%
B

G%)

-39

PRINT ABS%(B),

Output
39

512

Statements and Functions

4-5

ASCIl

ASCII
The ASCII function returns the ASCII value in decimal of a string’s first
character.

Format

int-var ={ figg" } (str-exp)
Syntax Rules

None.

Remarks

The ASCII value of a null string is zero.

The ASCII function returns an integer value of the default size between
0 and 255.

Example

DECLARE STRING time out

time out = "Friday"
PRINT ASCII(time_out)

Output
70

4-6

Statements and Functions

ATN

ATN
The ATN function returns the arctangent (that 1s, angular value) of
specified tangent in radians or degrees.

Format
real-var = ATN (real-exp)

Syntax Rules

None.

Remarks

ATN returns a value from —PI/2 through PI/2.

The returned angle is expressed in radians or degrees, depending
on
which angle clause you choose with the OPTION statement.

The argument of the ATN function must be a real expression. When
the argument is a real expression, VAX BASIC returns a value of the

same floating-point size. When the argument is not a real expressio
n,
VAX BASIC converts the argument to the default floating-point size
and
returns a value of the default floating-point size.

Statements and Functions

4-7

ATN

Example

OPTION ANGLE = RADIANS

DECLARE SINGLE angle_rad,

angle deg,

INPUT "Tangent value";T
angle rad = ATN(T)

PRINT "The smallest angle with that tangent is" ;angle_rad; "radians"
angle deg = angle rad/(PI/180)

PRINT "and";

angle deg;

"degrees”

Output
Tangent value? 2

The smallest angle with that tangent is 1.10715 radians
and 63.435 degrees

4-8

Statements and Functions

BUFSIZ

BUFSIZ
The BUFSIZ function returns the record buffer size, in bytes, of a specified
channel.

| Format
int-var = BUFSIZ (chnl-exp)

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number.
The value assigned to int-var is a LONG integer.

Remarks

If the specified channel is closed, BUFSIZ returns a value of zero.

BUFSIZ of channel #0 always returns the value 132.

Example

DECLARE LONG buffer size
buffer size = BUFSIZ(0)
PRINT "Buffer size equals";buffer
size

Output
Buffer size equals

132

Statements and Functions

4-9

CALL

CALL
The CALL statement transfers control to a subprogram, external function,
or other callable routine. You can pass arguments to the routine and can

optionally specify passing mechanisms. When the called routine finishes
executing, control returns to the calling program.

Format

CALL

routine [ pass-mech] [ ( actual-param,...) |

routine:

{ sub-name

pass-mech:

{ BY REF

param:
actual-param.

{
©XP ([]...) }[pass _ mech]
{ array

any-callable-routine
BY VALUE

BY DESC

}

Syntax Rules

Routine is the name of a SUB subprogram or any other callable

procedure, such as a system service or an RTL routine you want to call.
It cannot be a variable name. See the VAX BASIC for more information
on using system services, RTL routines, and other procedures.

4-10

Statements and Functions

CALL

Pass-mech specifies how arguments are passed to the called routine.
If you do not specify a pass-mech, VAX BASIC passes arguments as

indicated in Table 4-1.
e

BY VALUE specifies that VAX BASIC passes the argument’s 32-bit

value.
e

BY REF specifies that VAX BASIC passes the argument’s address.
This is the default for all arguments except strings and entire
arrays.

BY DESC specifies that VAX BASIC passes the address of a VAX

BASIC descriptor. For information about the format of a VAX
BASIC descriptor for strings and arrays, see Appendix C. For more

information on other types of descriptors, see the VAX Architecture

Handbook.
Table 4-1:

VAX BASIC Parameter-Passing Mechanisms
BY

Parameter

VALUE

BY REF

BY DESC

Variables

Yes

Yes!

Yes

Constants

Yes

Local

Expressions

Yes

Local

copy’

copy

Elements of a

Yes

Yes'

Yes

Virtual

Yes

Local

copy’

copy

Nonvirtual

Yes

Yes!

Integer and Real Data

copy’

copy

Local

nonvirtual array

array elements

Local

entire array

Virtual
entire array

1Specifies the default parameter-passing mechanism.

(continued on next page)

Statements and Functions

4-11

CALL

Table 4-1 (Cont.):

VAX BASIC Parameter-Passing Mechanisms
BY

Parameter

VALUE

BY REF

BY DESC

Variables

Yes!

Yes

Constants

Local

Expressions

Local

Nonvirtual

Yes!

Virtual

Local

copy"

copy

Nonvirtual

Yes

Yes!

Variables

Yes

Yes!

Constants

Local

copy

copy’

Packed Decimal Data

copy’

copy"

copy

Local

copy

Yes

array elements

Local

entire arrays

Virtual
entire arrays

String Data

Expressions

Local

copy

copy’

Yes

Yes!

Virtual
array elements

Local
copy

Local
copy’

Nonvirtual

Yes

Yes!

Nonvirtual

array elements

entire arrays

1Specifies the default parameter-passing mechanism.

(continued on next page)

4-12

Statements and Functions

CALL

Table 4-1 (Cont.):

VAX BASIC Parameter-Passing Mechanisms

Parameter

SXLUE

BY REF BY DESC

Yes'

Yes!

String Data

Virtual

entire arrays

Other Parameters

RECORD variables

RFA variables

1Specifies the default parameter-passing mechanism.

You should use parameter-passing mechanisms only when calling

non-BASIC routines or when a subprogram expects to receive a string or
entire array by reference.
4.

When pass-mech appears before the parameter list, it applies to all

arguments passed to the called routine. You can override this passing
mechanism by specifying a pass-mech for individual arguments in the

actual-param list.
5.

Actual-param lists the arguments to be passed to the called routine.

You can pass expressions or entire arrays. Optional commas in

parentheses after the array name specify the dimensions of the array.
The number of commas is equal to the number of dimensions —1. Thus,
no comma specifies a one-dimensional array, one comma specifies a

two-dimensional array, two commas specify a three-dimensional array,
and so on.

Statements and Functions

4-13

CALL

You cannot pass entire virtual arrays.

The name of the routine can be from 1 to 31 characters and must

conform to the following rules:
*

The first character of an unquoted name must be an alphabetic

character (A through Z). The remaining characters, if present, can
be any combination of letters, digits (0 through 9), dollar signs ($),
periods (.), or underscores (_).
*

A quoted name can consist of any combination of printable ASCII
characters.

VAX BASIC allows you to pass up to 255 parameters.

You can specify a null argument as an actual-param for non-BASIC
routines by omitting the argument and the pass-mech, but not the

Remarks

commas or parentheses. This forces VAX BASIC to pass a null argument

and allows you to access system routines from VAX BASIC.
2.

Arguments in the actual-param list must agree in data type and number

with the formal parameters specified in the subprogram.
3.

An argument is modifiable when changes to it are evident in the calling
program. Changing a modifiable parameter in a subprogram means the

parameter is changed for the calling program as well. Variables and
entire arrays passed by descriptor or by reference are modifiable.
4.

An argument is nonmodifiable when changes to it are not evident

in the calling program. Changing a nonmodifiable argument in a
subprogram does not affect the value of that argument in the calling
program. Arguments passed by value, constants, and expressions are

nonmodifiable. Passing an argument as an expression (by placing it in

parentheses) changes it from a modifiable to a nonmodifiable argument.
Virtual array elements passed as parameters are non-modifiable.

4-14

Statements and Functions

CALL

5. VAX BASIC will automatically convert numeric actual parameters to
match the declared data type. If the actual parameter is a variable,
VAX BASIC signals the informational message “Mode for parameter
<n> of routine <name> changed to match declaration” and passes the

argument by local copy. This prevents the called routine from modifying

the contents of the variable.

6. For expressions and virtual array elements passed by reference, VAX
BASIC makes a local copy of the value, and passes the address of this
local copy. For dynamic string arrays, VAX BASIC passes a descriptor of
the array of string descriptors. The compiler passes the address of the
argument’s actual value for all other arguments passed by reference.
7. Only BYTE, WORD, LONG, and SINGLE values can be passed by value.
BYTE and WORD values passed by value are converted to LONG values.
8.

If you attempt to call an external function, VAX BASIC treats the
function as if it were invoked normally and validates all parameters.

Note that you cannot call a STRING, HFLOAT, or RFA function. See the
EXTERNAL statement for more information on how to invoke functions.

Example

EXTERNAL SUB LIB$PUT OUTPUT
DECLARE

(string)

STRING msg_str

msg_str = "Successful call to LIBSPUT_OUTPUT!"
CALL LIBS$PUT OUTPUT

(msg_str)

Output
Successful call to LIBSPUT_OUTPUT!

Statements and Functions

4-15

CAUSE ERROR

CAUSE ERROR
The CAUSE ERROR statement allows you to artificially generate a VAX
BASIC run-time error and transfer program control to a VAX BASIC
error
handler.

Format

CAUSE ERROR

err-num

Syntax Rules

Err-num must be a valid VAX BASIC run-time error number.

Remarks

All error numbers are listed in the VAX BASIC User Manual.

4-16

Statements and Functions

CAUSE ERROR

Example

WHEN

ERROR

CAUSE ERROR

11%

USE
SELECT ERR

CASE =

"End of

file"

CONTINUE

CASE ELSE
EXIT
END
END

HANDLER

SELECT

WHEN

Statements and Functions

4-17

CCPOS

CCPOS
The CCPOS function returns the current character or cursor position of the
output record on a specified channel.

Format
int-var = CCPOS (chnl-exp)

Syntax Rules

Chnl-exp must specify an open file or terminal.

Remarks

If chnl-exp is zero, CCPOS returns the current character position of the
controlling terminal.

The int-var returned by the CCPOS function is of the default integer

size.

4-18

The CCPOS function counts only characters. If you use cursor
addressing sequences such as escape sequences, the value returned
will not be the cursor position.

The first character position on a line is zero.

Statements and Functions

CCPOS

Example

DECLARE

LONG

curs_pos

"Hello";

curs_pos = CCPOS
PRINT

(0)

curs_pos

Output
Hello

Statements and Functions

4-19

CHAIN

CHAIN
The CHAIN statement transfers control from the current program to another
executable image. CHAIN closes all files, then requests that the new
program begin execution. Control does not return to the original program

when the new image finishes executing.

NOTE
The CHAIN statement is not recommended for new program
development. DIGITAL recommends that you use subprograms,
external functions and pictures for program segmentation.

Format

CHAIN

sitr-exp

Syntax Rules

Str-exp represents the file specification of the program to which control is
passed. It can be a quoted or unquoted string.

Remarks

Str-exp must refer to an executable image or VAX BASIC signals an
error.

If you do not specify'a file type, VAX BASIC searches for an EXE file

type.

4-20

You cannot chain to a program on another node.

Execution starts at the beginning of the specified program.

Statements and Functions

CHAIN

Before chaining takes place, all active output buffers are written, all
open files are closed, and all storage is released.

Because a CHAIN statement passes control from the executing
image, the values of any program variables are lost. This means that
you can pass parameters to a chained program only by using files
or a system-specific feature such as LIBSGET_COMMON and
LIB$PUT _COMMON.

Example

DECLARE STRING time_out
time out =

"Friday"

PRINT ASCII(time_ out)

CHAIN

"CCPOSTM

Output
70

The current cursor position is O

In this example, the executing image ASCIL.EXE passes control to the
chained program, CCPOS.EXE. The value that results from ASCIL.EXE
is 70. The second line of output reflects the value that results from
CCPOS.EXE.

Statements and Functions

4-21

CHANGE

CHANGE
The CHANGE statement either converts a string of characters to their

ASCII integer values or converts a list of numbers to a string of ASCII
characters.

Format
String Variable to Array

CHANGE

str-exp TO num-array-name

Array to String Variable

CHANGE

num-array-name TO str-var

Syntax Rules

Str-exp is a string expression.
Num-array-name should be a one-dimensional array. If you specify-a
two-dimensional array, VAX BASIC converts only the first row of that

array. VAX BASIC does not support conversion to or from arrays of more

than two dimensions.

Remarks

VAX BASIC does not support RECORD elements as a destination string
or as a source or destination array for the CHANGE statement.

String Variable to Array
*

This format converts each character in the string to its ASCII value.

VAX BASIC assigns the value of the string’s length to the first
element of the array.

4-22

Statements and Functions

CHANGE

VAX BASIC assigns the ASCII value of the first character in the
string to the second element, (1) or (0,1), of the array, the ASCII
value of the second character to the third element, (2) or (0,2), and
SO on.

If the string is longer than the bounds of the array, VAX BASIC does
not translate the excess characters, and signals the error “Subscript
out of range” (ERR=55). The first element of array still contains the
length of the string.
Array to String Variable

This format converts the elements of the array to a string of
characters.

The length of the string is determined by the value in the zero
element, (0) or (0,0), of the array. If the value of element zero
is greater than the array bounds, VAX BASIC signals the error
“Subscript out of range” (ERR=55).

VAX BASIC changes the first element, (1) or (0,1), of array to its
ASCII character equivalent, the second element, (2) or (0,2), to
its ASCII equivalent, and so on. The length of the returned string
is determined by the value in the zero element of the array. For
example, if the array is dimensioned as (10), but the zero element
(0) contains the value 5, VAX BASIC changes only elements (1),
(2), (3), (4), and (5) to string characters.

VAX BASIC truncates floating-point values to integers before
converting them to characters.
Values in array elements are treated modulo 256.

Statements and Functions

4-23

CHANGE

Example

DECLARE
DIM

STRING ABCD,

INTEGER

ABCD

"ABCD"

CHANGE ABCD
FOR

TO array_changes
TO

array changes(I%)

CHANGE

array changes

PRINT A

Output

4-24

array changes(6)

Statements and Functions

TO A

CHR$

CHR$
The CHR$ function returns a 1-character string that corresponds to the
ASCII value you specify.

Format

str-var = CHR$ (int-exp)

Syntax Rules

None.

Remarks

CHRS$ returns the character whose ASCII value equals int-exp. If int-exp
is greater than 255, VAX BASIC treats it modulo 256. For example,
CHR$(325) is the same as CHR$(69).

All arguments between 0 and 255 are considered unsigned 8-bit integers.

If you specify a floating-point expression for int-exp, VAX BASIC

For example, —1 is treated as 255.

truncates it to an integer of the default size.

Statements and Functions

4-25

CHR$

Example

DECLARE

INTEGER num_exp

INPUT

"Enter

"The

the ASCII

equivalent

value

you wish

character

you wish

to be

converted";num_ exp

";CHRS (num_exp)

Output
Enter

the ASCII

The equivalent

4-26

Statements and Functions

value

character

converted?

CLOSE
The CLOSE statement ends I/O processing to a device or file on the specified
channel.

Format

[#]chnl-exp,...

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number associated
with a file. It can be preceded by an optional number sign (#).

Remarks

VAX BASIC writes the contents of any active output buffers to the file or
device before it closes that file or device.

Channel #0 (the controlling terminal) cannot be closed. An attempt to do
so has no effect.

An error handler that is invoked by a GET statement cannot successfully
close a file.

4.
5.

If you close a magnetic tape file that is open for output, VAX BASIC

writes an end-of-file on the magnetic tape.

If you try to close a channel that is not currently open, VAX BASIC does

not signal an error and the CLOSE statement has no effect.

Statements and Functions

4-27

Example

OPEN

"COURSE_REC.DAT"

INPUT

#2,

course_nam,

FOR INPUT AS
course_num,

#2
course_desc,

course instr

In this example, COURSE_REC.DAT is opened for input. After you have
entered all of the required information, the file is closed.

4-28

Statements and Functions

COMMON

COMMON
The COMMON statement defines a named, shared storage area called
a COMMON block or program section (PSECT). VAX BASIC program
modules can access the values stored in the COMMON block by specifying a
COMMON block with the same name.

Format

;
COM
..
} [ (com-name ) ] {[data-type ] com-item},.
{ COMMON
com-item:
num-unsubs-var

num-array-name ([int-const1 TO] int-const2 ,... )
str-unsubs-var = int-const

str-array-name ([int-const1 TO] int-const2,... ) [ = int-const ]
record-var

FILL [(int-const)][= int-const |
FILL% [(int-const)]

FILLS [(int-const)][ = int-const |

Syntax Rules
1. A COMMON block can have the same name as a program variable.
A COMMON block and a map in the same program module cannot have
the same name.

3. All COMMON elements must be sepai'ated with commas.

4. Com-name is optional. If you specify a com-name, it must be in

parentheses. If you do not specify a com-name, the default is “$BLANK”.
Statements and Functions

4-29

COMMON

Com-name can be from 1 through 31 characters. The first character of
the name must be an alphabetic character (A through Z). The remaining

characters, if present, can be any combination of letters, digits (0
through 9), dollar signs ($), periods (.), or underscores (_).

Data-type can be any VAX BASIC data type keyword or a data type

defined in the RECORD statement. Data type keywords, size, range,
and precision are listed in Table 1-2 in this manual.

When you specify a data type, all following com-items, including FILL
items, are of that data type until you specify a new data type.
If you do not specify any data type, com-items take the current default
data type and size.

Com-item declares the name and format of the data to be stored.
*

Num-unsubs-var and num-array-name specify a numeric variable or
a numeric array.

®*

Record-var specifies a record instance.

Str-unsubs-var and sir-array-name specify a fixed-length string

variable or array. You can specify the number of bytes to be reserved
for the variable with the =int-const clause. The default string length

is 16.
*

When you specify either a numeric or a string array, VAX BASIC
allows you to declare both lower and upper bounds. The upper

bound is required; the lower bound is optional.
—

Int-constl1 specifies the lower bounds of the array.

—

Int-const2 specifies the upper bounds of the array and, when

accompanied by int-constl, must be preceded by the keyword TO.

—

Int-const]l must be less than or equal to int-const2.

—

If you do not specify int-constl, VAX BASIC uses zero as the
default lower bound.

—

Int-constl and int-const2 can be either negative or positive

values.

The FILL, FILL%, and FILL$ keywords allow you to reserve parts

of the record buffer within or between data elements and to define
the format of the storage. Int-const specifies the number of FILL

items to be reserved. The =int-const clause allows you to specify the

4-30

Statements and Functions

COMMON

number of bytes to be reserved for string FILL items. Table 42
describes FILL item format and storage allocation.
NOTE

In the applicable formats of FILL, (int-const) represents a
repeat count, not an array subscript. FILL (n) represents
n elements, not n + 1.

Table 4-2:

FILL Item Formats and Storage Allocations

FILL Format
FILL

Storage Allocation
Allocates storage for one element of the

default data type unless preceded by a
data-type; the number of bytes allocated
depends on the default or the specified
data type.

FILL(int-const)

Allocates storage for the number of

floating-point elements specified by
int-const unless preceded by a data
type; the number of bytes allocated for
each element depends on the default
floating-point data size or the specified
data type.

FILL%

Allocates storage for one integer element;

FILL%(int-const)

Allocates storage for the number of

the number of bytes allocated depends on
the default integer size.
integer elements specified by int-const;
the number of bytes allocated for each
element depends on the default integer
size.

FILL$

Allocates 16 bytes of storage for a string
element. The dollar sign can be omitted
if the FILL keyword is preceded by the
STRING data type.

(continued on next page)

Statements and Functions

4-31

COMMON

Table 4-2 (Cont.):

FILL Item Formats and Storage Allocations

FILL Format

Storage Allocation

FILL$(int-const)

Allocates 16 bytes of storage for the
number of string elements specified by

int-const. The dollar sign can be omitted

if the FILL keyword is preceded by the
STRING data type.

FILL$=int-const

Allocates the number of bytes of storage

specified by int-const for a string element.
The dollar sign can be omitted if the FILL

keyword is preceded by the STRING data
type.

FILL$(int-constl )=int-const2

Allocates the number of bytes of storage

specified by int-const2 for the number of
string elements specified by int-constl1.
The dollar sign can be omitted if the FILL

keyword is preceded by the STRING data
type.

Remarks

Variables in a common are not initialized by VAX BASIC.
A COMMON area and a MAP area with the same name, in different
program modules, specify the same storage area.

VAX BASIC does not execute COMMON statements. The COMMON
statement allocates and defines the data storage area at compilation
time.

4-32

When you link your program, the size of the COMMON area is the size
of the largest COMMON area with that name. VAX BASIC concatenates
COMMON statements with the same com-name within a single program
module into a single PSECT. The total space allocated is the sum of the
space allocated in the concatenated COMMON statements.

Statements and Functions

COMMON

If you specify the same com-name in several program modules, the
size of the PSECT will be determined by the program module that has
the greatest amount of space allocated in the concatenated COMMON
statements.

5. The COMMON statement must lexically precede any reference to
variables declared in it.

6. A COMMON area can be accessed by more than one program module,
as long as you define the com-name in each module that references the
COMMON area.

7 Variable names in a COMMON statement in one program module need
not match those in another program module.

8. Variables and arrays declared in a COMMON statement cannot be
declared elsewhere in the program by any other declarative statements.
9. The data type specified for com-items or the default data type and size
determines the amount of storage reserved in a COMMON block:
e

BYTE integers reserve 1 byte.
WORD integers reserve 2 bytes.

LONG integers reserve 4 bytes.

e
e
e

e
e

SINGLE floating-point numbers reserve 4 bytes.
DOUBLE floating-point numbers reserve 8 bytes.
GFLOAT floating-point numbers reserve 8 bytes.
HFLOAT floating-point numbers reserve 16 bytes.

DECIMAL(,s) packed decimal numbers reserve (d+1 )/2 bytes.
STRING reserves 16 bytes (the default) or the number of bytes you
specify with =in¢-const.

10. For multi-dimensional arrays, values are assigned in row-column order.

Statements and Functions

4-33

COMMON

(sales_rec)

DECIMAL net sales
STRING

row =

report_ name

DOUBLE FILL,
LONG part_bins

4-34

Statements and Functions

(1965

2,
=

1975)

COMMON

Example

COMP%

COMP%
The COMP% function compares two numeric strings and returns a -1, 0, or

1, depending on the results of the comparison.

Format

int-var = COMP% (str-exp1, str-exp2)

Syntax Rules
Str-expl and str-exp2 are numeric strings. They must have one of the
following formats:

An optional minus sign (—), ASCII digits, and an optional decimal
point (.)

An optional minus sign, ASCII digits, an optional decimal point, the
letter E, an optional minus sign, and a 2-digit exponent

If str-expl is less than str-exp2, COMP% returns a —1.

If str-exp1 is greater than str-exp2, COMP% returns a 1.
If the string expressions are equal, COMP% returns a 0.

Remarks

The value returned by the COMP% function is an integer of the default
size.

Statements and Functions

4-35

COMP%

Example

DECLARE

STRING num_string,

INTEGER
num_string =

"-24.5"

old numstring =
result

"The

4-36

value

"33"

COMP% (num_string,
value

Output
The

old_num string,

result

-1

Statements and Functions

old_num string)

";result

CONTINUE

CONTINUE
The CONTINUE statement causes VAX BASIC to clear an error condition
and resume execution at the statement following the statement that caused
the error or at the specified target.

Format

CONTINUE

[target]

Syntax Rules
If you specify a target, it must be a label or line number that appears either
inside the associated protected region, inside a WHEN block protected region
that surrounds the current protected region, or in an unprotected region of
code.

Remarks

CONTINUE with no target causes VAX BASIC to transfer control to the
statement immediately following the statement that caused the error.
The next remark is an exception to this rule.
If an error occurs on a FOR, NEXT, WHILE, UNTIL, SELECT or CASE
statement, control is transferred to the statement immediately following
the corresponding NEXT or END SELECT statement, as in the following
code.

Statements and Functions

4-37

CONTINUE

WHEN ERROR

A=10
B=1

FOR I=A TO B STEP
GET #1

C=1
NEXT

C=0
USE

CONTINUE
END WHEN

If an error occurs on line 20, the CONTINUE statement transfers control
to line 50. If an error occurs on line 30, program control resumes at
line 40.
3.

The CONTINUE statement must be lexically inside of a handler.

If you specify a CONTINUE statement within a detached handler, you

cannot specify a target.

Example

WHEN ERROR USE err handler

END

WHEN

HANDLER err handler

SELECT ERR

CASE =

"Insufficient

CONTINUE
CASE ELSE
EXIT

END
END

4-38

HANDLER

SELECT

HANDLER

Statements and Functions

data"

COS

COS
The COS function returns the cosine of an angle in radians or degrees.

Format

real-var = COS (real-exp)

Syntax Rules

None.

Remarks

The returned value is between —1 and 1. This value is expressed in
either radians or degrees depending on which angle clause you choose

with the OPTION statement.

2. VAX BASIC expects the argument of the COS function to be a real
expression. When the argument is a real expression, VAX BASIC
returns a value of the same floating-point size. When the argument is
not a real expression, VAX BASIC converts the argument to the default
floating-point size and returns a value of the default floating-point size.

Statements and Functions

4-39

COS

Example

DECLARE

SINGLE

cos_value
PRINT

COS(cos_value)

Output
.646919

440

cos_value

Statements and Functions

CTRLC

CTRLC
The CTRLC function enables CTRL/C trapping. When CTRL/C trapping is
enabled, a CTRL/C typed at the terminal causes control to be transferred to
the error handler currently in effect.

Format

int-var = CTRLC

Syntax Rules

None.

Remarks

1. When VAX BASIC encounters a CTRL/C, control passes to the error
handler currently in effect. If there is no error handler in a program,
the program aborts.

9 1In a series of linked subprograms, setting CTRL/C for one subprogram
enables CTRL/C trapping for all subprograms.

3. When you trap a CTRL/C with an error handler, your program may be
in an inconsistent state; therefore, you should handle the CTRL/C error
and exit the program as quickly as possible.

4. CTRL/C trapping is asynchronous; that is, VAX BASIC suspends
execution and signals “Programmable *C trap” (ERR=28) as soon as it
detects a CTRL/C. Consequently, a statement can be interrupted while it
is executing. A statement so interrupted may be only partially executed
and variables may be left in an undefined state.

Statements and Functions

4-41

CTRLC

VAX BASIC can trap more than one CTRL/C error in a program as

long
as the error does not occur while the error handler is executing. If a
second CTRL/C is detected while the error handler is processing the first
CTRL/C, the program aborts.

The CTRLC function always returns a value of zero.

The function RCTRLC disables CRTL/C trapping. See the description of
the RCTRLC function for further details.

Example

WHEN ERROR USE

= CTRLC

END

WHEN

HANDLER
IF

repair_work

(ERR=28)

THEN PRINT

END HANDLER

4-42

repair work

Statements and Functions

"Interrupted by

CTRLC!"

CVT$$

CVT$$
The CVT$$ function is a synonym for the EDIT$ function. See the EDIT$

function for more information.

NOTE

DIGITAL recommends that you use the EDIT$ function rather
than the CVT$$ function for new program development.

Format

str-var = CVT$$ (str-exp, int-exp)

Statements and Functions 4-43

CVTxx

CVTxx
The CVT$% function maps the first two characters
of a string into a
16-bit integer. The CVT%$ function translates a 16-bit
integer into a
2-character string. The CVT$F function maps a 4or 8-character string into
a floating-point variable. The CVTF$ function transla
tes a floating-point
number into a 4- or 8-byte character string. The
number of characters
translated depends on whether the floating-point
variable is single- or
double-precision.

NOTE
CVT functions are supported only for compatibility with
BASIC-PLUS. DIGITAL recommends that you use
VAX BASIC’s
dynamic mapping feature or multiple MAP statements
for new

program development.

Format
int-var = CVT$% (str-var)
real-var = CVT$F (str-var)
str-var = CVT%$ (int-var)
str-var = CVTFS$ (real-var)

Syntax Rules

CVT functions reverse the order of the bytes when moving
them to or from
a string. Therefore, you can mix MAP and MOVE stateme
nts, but you

cannot use FIELD and CVT functions on a file if

or MOVE statements.

4-44

Statements and Functions

you also plan to use MAP

CVTxx

Remarks

CVT$%

If the CVT$% str-var has fewer than two characters, VAX BASIC
pads the string with nulls.

If the default data type is LONG, only two bytes of data are

extracted from str-var; the high-order byte is sign-extended into a

longword.

The value returned by the CVT$% function is an integer of the
default size.

CVT%$

Only two bytes of data are inserted into str-var.
®

If you specify a floating-point variable for int-var, VAX BASIC
truncates it to an integer of the default size. If the default size is
BYTE and the value of int-var exceeds 127, VAX BASIC signals an
error.

CVT$F

CVT$F maps 4 characters when the program is compiled with
/SINGLE and eight characters when the program is compiled with
/DOUBLE.

If str-var has fewer than four or eight characters, VAX BASIC pads
the string with nulls.

The real-var returned by the CVT$F function is the default
floating-point size. If the default size is GFLOAT or HFLOAT,
VAX BASIC signals the error “Floating CVT illegal for GFLOAT or
HFLOAT”.

Statements and Functions

445

CVTxx

CVTF$
*

The CVTF$ function maps single-precision numbers to a 4-character
string and double-precision numbers to an 8-character string.

VAX BASIC expects the argument of the CVTF$ function to be a real
expression. When the argument is a real expression, VAX BASIC
returns a value of the same floating-point size. When the argument

is not a real expression, VAX BASIC converts the argument to
the default floating-point size and returns a value of the default

floating-point size. If the default floating-point size is GFLOAT or
HFLOAT, VAX BASIC signals the error “Floating CVT illegal for
GFLOAT or HFLOAT".

Examples

Example 1
DECLARE

STRING test_string,

DECLARE

LONG

test_string =

first_number,

"AT"

PRINT CVT$% (test_string)
another string =

"at"

PRINT CVT$% (another string)

first_number = 16724
PRINT

CVT%$ (first number)

next_ number

24948

CVT%$ (next_number)

END

Output
16724

24948
AT
at

4-46

Statements and Functions

another string
next number

CVTxx

Example 2
DECLARE STRING test_string,

another_string

DECLARE SINGLE first num, second num
test_string = "DESK"
first num = CVTSF (test_string)
PRINT

first_num

another string = "desk"

second_num = CVTSF (another_string)

second_num

PRINT CVTF$ (first_num)
PRINT CVTFS$ (second_num)
END

$ BASIC/SINGLE CVTF
$ LINK CVTF

$ RUN CVTF

Output
.218256E+12
.466242E+31
DESK

desk

Statements and Functions

4-47

DATA

DATA
The DATA statement creates a data block for the READ statemen

Format
" num-lit 7

DATA

str-lit

you

| ung-str |

Syntax Rules

Num-lit specifies a numeric literal.

Str-lit is a character string that starts and ends with double or
single
quotation marks. The quotation marks must match.

Ung-str is a character sequence that does not start or end
with double
quotation marks and does not contain a comma.

Commas separate data elements. If a comma is part of a data
item, the
entire item must be enclosed in quotation marks.

Remarks

Because VAX BASIC treats comment fields in DATA statemen

of the DATA sequence, you should not include comments.
2.

A DATA statement must be the last or the only statement on a

line.
3.

4-48

ts as part

DATA statements must end with a line terminator.

Statements and Functions

physical

DATA

When a DATA statement is continued with an ampersand (&), VAX
BASIC interprets all characters between the keyword DATA and the
ampersand as part of the data. Any code that appears on a noncontinued
line is considered a new statement.

You cannot use the percent sign suffix for integer constants that appear

in DATA statements. An attempt to do so causes VAX BASIC to signal
the error, “Data format error” (ERR=50).

DATA statements are local to a program module.

VAX BASIC does not execute DATA statements. Instead, control is
passed to the next executable statement.

A program can have more than one DATA statement. VAX BASIC
assembles data from all DATA statements in a single program unit into
a lexically ordered single data block.

VAX BASIC ignores leading and trailing blanks and tabs unless they are
in a string literal.

10.

Commas are the only valid data delimiters. You must use a quoted

11.

VAX BASIC ignores DATA statements without an accompanying READ

string literal if a comma is to be part of a string.
statement.

12.

VAX BASIC signals the error “Data format error” if the DATA item does
not match the data type of the variable specified in the READ statement
or if a data element that is to be read into an integer variable ends with

a percent sign (%). If a string data element ends with a dollar sign ($),

VAX BASIC treats the dollar sign as part of the string.

Example

10 DECLARE INTEGER A,B,C
READ A,B,C
DATA 1,2,3

PRINT A + B + C

Output
6

Statements and Functions 4—49

DATE$

DATES$
The DATE$ function returns a string containing
a day, month, and year in
the form dd-Mmm-yy.

Format
str-var = DATES (int-exp)

Syntax Rules

Int-exp can have up to six digits in the form

yyyddd, where the
characters yyy specify the number of years since
1970 and the characters
ddd specify the day of that year.

You must fill all three of the d positions with digits
can fill the y positions. For example:

or zeros before you

DATE$(121) returns the date 01-May-70, day 121

of the year 1970.

DATE$(1201) returns the date 20—Jul-71, day 201

of the year 1971.

DATE$(12001) returns the date 01—Jan—82, day

one of the year

DATE$(10202) returns the date 21—Jul-80, day

202 of the year

1982.

1980.

Remarks

Ifint-exp equals zero, DATE$ returns the current

date.

The str-var returned by the DATES$ function consist
and expresses the day, month, and year in the form
3.

4-50

s of nine characters
dd-Mmm-yy.

If you specify an invalid date, such as day 385, results

Statements and Functions

are unpredictable.

DATE$

If you specify a floating-point expression for int-exp, VAX BASIC
truncates it to an integer of the default size.

Example

DECLARE

STRING todays date

todays_date = DATES (0)
PRINT

todays_date

Output
09-0Oct-89

Statements and Functions

4-51

DECIMAL

DECIMAL
The DECIMAL function converts a numeric expression or numeric string to
the DECIMAL data type.

Format

decimal-var = DECIMAL (exp [, int-const1, int-const2 | )

Syntax Rules

Int-constl specifies the total number of digits (the precision) and

int-const2 specifies the number of digits to the right of the decimal point
(the scale). If you do not specify these values, VAX BASIC uses the d
(digits) and s (scale) defaults for the DECIMAL data type.
2.

Int-constl and int-const2 must be positive integers from 1 through 31.

Int-const2 cannot exceed the value of int-const1.

Exp can be either numeric or numeric string. If a numeric string, it can
contain the ASCII digits 0 through 9, uppercase E, a plus sign (+), a
minus sign (—), and a period (. ).

Remarks

If exp is a string, VAX BASIC ignores leading and trailing spaces and
tabs.

The DECIMAL function returns a zero when a string argument contains

only spaces and tabs, or when it is null.

4-52

Statements and Functions

DECIMAL

Example

DECLARE

STRING CONSTANT

DECLARE

STRING num value,

INPUT
B

"Enter

format string =
DECIMAL(5,3)

"##.###"
B

a numeric value";num value

DECIMAL (num_value, 5, 3)

USING

format string,

Output
Enter

numeric value?

6.000

Statements and Functions

4-53

DECLARE

DECLARE
The DECLARE statement explicitly assigns a name and a data type to a
variable, an entire array, a function, or a constant.

Format
Variables

DECLARE

data-type { decl-item [,[ data-type ] decl-item J},...

DEF Functions

DECLARE

data-type FUNCTION { def-name
[ ( [ def-param ],... ) ] },...

Named Constants

DECLARE

data-type CONSTANT { const-name = const-exp },...

decl-item:

{record- var

def-param:

data-type

array-name ( [ int-const1 TO ] int-const2,...)

}

unsubs-var

Syntax Rules

Data-type can be any VAX BASIC data type keyword or a data type

defined by a RECORD statement. Data type keywords, size, range, and

precision are listed in Table 1-2 in this manual.
2.

Variables

®*

4-54

Decl-item names an array, a record, or a variable.

Statements and Functions

DECLARE
A decl-item named in a DECLARE statement cannot be named
in another DECLARE statement, or in a DEF, EXTERNAL,
FUNCTION, SUB, COMMON, MAP, DIM, HANDLER, or PICTURE
statement.

Each decl-item is associated with the preceding data type. A data

type is required for the first decl-item.

Decl-items of data type STRING are dynamic strings.

When you declare an array, VAX BASIC allows you to specify both
lower and upper bounds for each dimension of the array. The upper
bound is required; the lower bound is optional.
— Int-constl specifies the lower bounds of the array.

—

Int-const2 specifies the upper bounds of the array and, when
accompanied by int-constl, must be preceded by the keyword TO.

—

Int-constl must be less than or equal to int-const2.

—

If you do not specify int-constl, VAX BASIC uses zero as the

—

Int-constl and int-const2 can be any combination of negative or

default lower bound.

positive values or zero.

DEF Functions

Def-name names the DEF function.

Data-type specifies the data type of the value the function returns.

Def-params specify the number and, optionally, the data type of the
DEF parameters. Parameters define the arguments the DEF expects
to receive when invoked.

—

When you specify a data type, all following parameters are of

—

If you do not specify any data type, parameters take the current

—

The number of parameters equals the number of commas plus
1. For example, empty parentheses specify one parameter of
the default type and size; one comma inside the parentheses
specifies two parameters of the default type and size; and so on.
One data type inside the parentheses specifies one parameter of
the specified data type; two data types separated by one comma
specifies two parameters of the specified type, and so on.

that data type until you specify a new data type.
default data type and size.

Statements and Functions

4-85

DECLARE

Named Constants

Const-name is the name you assign to the constant.
Data-type specifies the data type of the constant. The value of the
const must be numeric if the data type is numeric and string if the
data type is STRING. If the data type is STRING, const must be a

quoted string or another string constant.

Const-exp cannot be a datatype that was defined with the RECORD
statement.

String constants cannot exceed 498 characters.
VAX BASIC allows const-exp to be an expression for all data types

except DECIMAL. Expressions are not allowed as values when you

name DECIMAL constants.

Allowable operators in DECLARE CONSTANT

expressions include
all valid arithmetic, relational, and logical operators except

exponentiation. Built-in functions cannot be used in DECLARE

CONSTANT

expressions. The following examples use valid

expressions as values:
DECLARE

DOUBLE

CONSTANT max_value

DECLARE

STRING

CONSTANT

left

arrow

(PI/2)
=

"<--—-- "

Remarks

The DECLARE statement is not executable.

The DECLARE statement must lexically precede any reference to the
variables, functions, or constants named in it.
3.

To declare a virtual or run-time array, use the DIMENSION statement.

Variables

Subsequent decl-items are associated with the specified data type

until you specify another data type.

All variables named in a DECLARE statement are initialized to zero
if numeric or to the null string if string.

4-56

Statements and Functions

DECLARE

DEF Functions

The DECLARE FUNCTION statement allows you to name a function
defined in a DEF or DEF* statement, specify the data type of the
value the function returns, and declare the number and data type of
the DEF parameters.

Data type keywords must be separated by commas.

The first specification of a data type for a def-param is the default
for subsequent arguments until you specify another def-param. For
example:
DECLARE DOUBLE FUNCTION interest (DOUBLE,SINGLE,,)

This example declares two parameters of the default type and size,
one DOUBLE parameter, and three SINGLE parameters for the
function named interest.

Named Constants

The DECLARE CONSTANT

statement allows you to name a

constant value and assign a data type to that value. Note that
you can specify only one data type in a DECLARE CONSTANT
statement. To declare a constant of another data type, you must use
a second DECLARE CONSTANT statement.

During program execution, you cannot change the value assigned to
|

the constant.

The specified data-type determines the data type of the constant. For
example:
DECLARE LONG CONSTANT True = -1, False = 0
DECLARE REAL CONSTANT ZZZ = 123.0
DECLARE BYTE CONSTANT YYY = ’"123'L
PRINT True,

False,

ZZZ,

YYY

Output
-1

123

In this example, VAX BASIC truncates the LONG value assigned to

YYY to a BYTE variable.

Statements and Functions

4-57

DECLARE

NOTE
Data types specified in a DECLARE statement override any
defaults specified in COMPILE command qualifiers or OPTION
statements.

Examples

Example 1
!DEF Functions
DECLARE

INTEGER FUNCTION

amount (, , DOUBLE, BYTE, , )

Example 2
!Named Constants
DECLARE

4-58

DOUBLE CONSTANT

Statements and Functions

interest rate =

15.22

DEF

DEF
The DEF statement lets you define a single- or multi-line function.
Format
Single-line DEF

DEF [ data-type ] def-name [ ( [ data-type ] var,...) | = exp

Muiti-Line DEF

DEF [ data-type ] def-name [ ([ data-type var },...) ] [ statement ]
[ statement |]...

{Fnenp J (o]
Syntax Rules
1. Data-type can be any VAX BASIC data type keyword or a data type
defined in the RECORD statement. Data type keywords, size, range,
and precision are listed in Table 1-2 in this manual.

2. The data type that precedes the def-name specifies the data type of the
co

value returned by the DEF function.

Def-name is the name of the DEF function. The def-name can contain
from 1 to 31 characters.

4. If the def-name also appears in a DECLARE FUNCTION statement, the
following rules apply:

A function data type is required.

Statements and Functions

4-59

DEF

The first character of the def-name must be an alphabetic character

(A through Z). The remaining characters can be any combination
of letters, digits (0 through 9), dollar signs ($), underscores (_), or

periods (. ).

If the def-name does not appear in a DECLARE FUNCTION statement,
but the DEF statement appears before the first reference to the

def-name, the following rules apply:
*
®

The function data type is optional.
The first character of the def-name must be an alphabetic letter (A

through Z). The remaining characters can be any combination of
letters, digits, dollar signs, underscores, or periods.
*

If a function data type is not specified, the last character in the
def-name must be a percent sign for an INTEGER function, or a
dollar sign for a STRING function.

If the def-name does not appear in a DECLARE FUNCTION statement,
and the DEF statement appears after the first reference to the def-name,

the following rules apply:
*

The function data type cannot be present.

The first two characters of the def-name must be FN. The remaining

characters can be any combination of letters, digits, dollar signs,
underscores, or periods, with one restriction: the last character must

be a percent sign for an INTEGER function, or a dollar sign for a
STRING function.

There must be at least one character between the FN characters and
the ending dollar sign or percent character. FN$ and FN% are not
valid function names.

Var specifies optional formal DEF parameters. Because the parameters
are local to the DEF function, any reference to these variables outside

the DEF body creates a different variable.

You can specify the data type of DEF parameters with a data type

keyword or with a data type defined in a RECORD statement. If you do

not include a data type, the parameters are of the default type and size.
Parameters that follow a data type keyword are of the specified type and
size until you specify another data type.
9.

4-60

You can specify up to 255 parameters in a DEF statement.

Statements and Functions

DEF

10. Single-Line DEF

Exp specifies the operations the function performs.

11. Multi-Line DEF

Statements specifies the operations the function performs.

The END DEF or FNEND statement is required to end a multi-line

VAX BASIC does not allow you to specify any statements that
indicate the beginning or end of any SUB, FUNCTION, PICTURE,
HANDLER (attached handlers are legal), PROGRAM or DEF in a

DEF.

function definition.

Exp specifies the function result. Exp must be compatible with the
DEF data type.

Remarks

When VAX BASIC encounters a DEF statement, control of the program
passes to the next executable statement after the DEF.
The function is invoked when you use the function name in an
expression.

You cannot specify how parameters are passed. When you invoke a
function, VAX BASIC evaluates parameters from left to right and passes
parameters to the function so that they cannot be modified. Numeric
parameters are passed by value and string parameters are passed by
descriptor, where the descriptor points to a local copy. A DEF function

can reference variables that are declared within the compilation unit
in which the function resides, but it cannot reference variables in other
DEF or DEF* functions. A DEF function can, therefore, modify other
variables in the program, but not variables within another DEF function.
A DEF function is local to the program, subprogram, function, or picture
that defines it.

You can declare a DEF either by defining it, by using the DECLARE

FUNCTION statement, or by implicitly declaring it with a reference to
the function in an expression.

Statements and Functions

4-61

DEF

If your program invokes a function with a name that does not start with
FN before the DEF statement defines the function, VAX BASIC
signals

an error.

If the number of parameters, types of parameters, or type of result
declared in the invocation disagree with the number or types of

parameters defined in the DEF statement, VAX BASIC signals

an error.

DATA statements in a multi-line DEF are not local to the function; they

are local to the program module containing the function definition.

The function value is initialized to zero or the null string each time
you
invoke the function.
10. You can invoke a DEF function within an attached or detached

handler.

11. DEF definitions cannot appear inside a protected region. However,
a
DEF can contain one or more protected regions.

12. In DEF definitions that contain handlers, the following rules apply:

If the function was invoked from a protected region, the EXIT
HANDLER statement transfers control to the handler specified for
that protected region.

If the function was not invoked from a protected region, the EXIT

HANDLER statement transfers control to the default error handler.

13. If an exception is not handled within a DEF function, control is

transferred to the module that invoked the DEF function.

14. ON ERROR statements within a DEF function are local to the

function.

15. A CONTINUE, GOTO, GOSUB, ON ERROR GOTO, or RESUME

statement in a multi-line function definition must refer to a line number
or label in the same function definition.

16. You cannot transfer control into a multi-line DEF except by invoking

function.

the

17. DEF functions can be recursive. However, VAX BASIC does not detect
infinitely recursive DEF functions during compilation.

4-62

Statements and Functions

DEF

Examples

Example 1
!Single-Line DEF

D+ E
DEF DOUBLE add (DOUBLE A, B, SINGLE C, D, E) = A+B+C+
INPUT ’'Enter five numbers to be added’;V,W,X,Y, Z

PRINT ’The sum is’;ADD(V,W,X,Y¥Y,Z)

Output
Enter five numbers to be added? 1,2,3,4,5
The sum is

Example 2
PROGRAM I want_a_ raise

&
&

OPTION TYPE = EXPLICIT,
CONSTANT TYPE = DECIMAL,
SIZE = DECIMAL

(6,2)

DECLARE DECIMAL CONSTANT Overtime_factor = 0.50
DECLARE DECIMAL Myhours, My_rate, Overtime

DECLARE DECIMAL FUNCTION Calculate_pay (DECIMAL,DECIMAL)
INPUT "Your hours this week";My_ hours
INPUT "Your hourly rate";My_rate

PRINT "My pay this week is"; Calculate_pay ( My_hours, My rate )
te (DECIMAL Hours, Rate)
DEF DECIMAL Calculapay
IF Hours = 0.0
THEN

EXIT DEF 0.0
END

Overtime = Hours - 40.0
IF Overtime < 0.0
THEN

END

END DEF

Overtime = 0.0
IF

(Hours * Rate) + (Overtime * (Overtime_factor * Rate) )

END PROGRAM

Statements and Functions

4-63

DEF

Output
Your

464

hours

this

Your pay

rate?

Your

for

pay

week?

the

Statements and Functions

45.7

20.35
week

987.95

DEF*

DEF*
The DEF* statement lets you define a single- or multi-line function.
NOTE

The DEF* statement is not recommended for new program

development. DIGITAL recommends that you use the DEF
statement for defining single- and multi-line functions.

Format
Single-line DEF*

DEF* [ data-type ] def-name [ ([ data-type Jvar,...) ] =exp

Multi-Line DEF*

DEF* [ data-type ] def-name [ ( [ data-type Jvar,...) ] [ statement ]...
[ statement |...

{FNEND } [exp]
END DEF

Syntax Rules

rd or a data type
1. Data-type can be any VAX BASIC data type keywo
keywords, size, range,
defined in the RECORD statement. Data type
and precision are listed in Table 1-2 in this manual.

2. The data type that precedes the def-name specifies the data type of the
value returned by the DEF* function.
3. Def-name is the name of the DEF* function. The def-name can contain
from 1 to 31 characters.

Statements and Functions 4-65

DEF*

If the def-name also appears in a DECLARE FUNC
TION statement, the
following rules apply:
*
®

A function data type is required.
The first character of the def-name must be

an alphabetic character

(A through Z). The remaining characters can be

of letters, digits (0 through 9), dollar signs ($),

periods (.).

any combination
underscores (_), or

If the def-name does not appear in a DECLARE
FUNCTION statement,
but the DEF* statement appears before the first
reference to the
def-name, the following rules apply:
*

The function data type is optional.

The first character of the def-name must be
an alphabetic character
(A through Z). The remaining characters can
be any combination of
letters, digits, dollar signs, underscores, or
periods.

If a function data type is not specified, the last
character in the
def-name must be a percent sign for an INTE
GER function, or a
dollar sign for a STRING function.

If the def-name does not appear in a DECLARE
FUNCTION statement,
and the DEF* statement appears after the first
reference to the
def-name, the following rules apply:
*
*

The function data type cannot be present.
The first two characters of the def-name must

be FN. The remaining

characters can be any combination of letters, digits,

dollar signs,
last character must
be a percent sign for an INTEGER function, or a
dollar sign for a
STRING function.
underscores, or periods, with one restriction: the

®*

7.
8.

There must be at least one character between the
FN characters and
the ending dollar sign or percent character. FN
$ and FN% are not
valid function names.

Var specifies optional formal function parameters.
You can specify the data type of function parame

ters with a data type

keyword. If you do not specify a data type, parame

ters are of the default

type and size. Parameters that follow a data
type are of the

type and size until you specify another data

4-66

type.

You can specify up to 8 parameters in a DEF*

Statements and Functions

statement.

specified

DEF*

10. Single-Line DEF*
Exp specifies the operations the function performs.
11. Multi-Line DEF*

Statements specifies the operations the function performs.

The END DEF or FNEND statement is required to end a multi-line
DEF*.

VAX BASIC does not allow you to specify any statements that
indicate the beginning or end of any SUB, FUNCTION, PICTURE,
HANDLER, PROGRAM or DEF in a function definition.

Exp specifies the function result. Exp must be compatible with the
DEF data type.

Remarks

When VAX BASIC encounters a DEF* statement, control of the program
passes to the next executable statement after the DEF*.

A function defined by the DEF* statement is invoked when you use the
function name in an expression.

You cannot specify how parameters are passed. When you invoke a

DEF* function, VAX BASIC evaluates parameters from left to right
and passes parameters to the function so that they cannot be modified.
Numeric parameters are passed by value, and string parameters are
passed by descriptor, where the descriptor points to a local copy. A
DEF* function can reference variables in the program unit where the

function is declared, but it cannot reference variables in other DEF or

DEF* functions. A DEF* function can, therefore, modify variables in its
program unit, but not variables within another DEF* function.

The following differences exist between DEF* and DEF statements:
*

You can use the GOTO, ON GOTO, GOSUB, and ON GOSUB
statements to a branch outside a multi-line DEF*, but they are not

recommended.

Statements and Functions

4-67

DEF*

Although other variables used within the body of a DEF* function
are not local to the DEF* function, DEF* formal parameters are.
However, if you change the value of formal parameters within a
DEF* function and then transfer control out of the DEF* function
without executing the END DEF or FNEND statement, variables
outside the DEF* that have the same names as DEF* formal
parameters are also changed.

You can pass up to 255 parameters to a DEF function. DEF*
functions accept a maximum of 8 parameters.

A DEF* function value is not initialized when the DEF* function
is invoked. Therefore, if a DEF* function is invoked, and no new
function value is assigned, the DEF* function returns the value of
its previous invocation.

The error handler of the program module that contains the DEF* is
the default error handler for a DEF* function. Parameters return to
their original values when control passes to the error handler.
o.

A DEF* is local to the program unit or subprogram that defines it.

You can declare a DEF* either by defining it, by using the DECLARE
FUNCTION statement, or by implicitly declaring it with a reference to
the function in an expression.

If the number of parameters, types of parameters, or type of result
declared in the invocation disagree with the number or types of
parameters defined in the DEF* statement, VAX BASIC signals an error.
8.

DEF* functions can be recursive.

DATA statements in a multi-line DEF* are not local to the function; they
are local to the program module containing the function definition.

10. You can invoke a DEF* function within an attached or detached handler.
11. DEF* definitions cannot appear inside a protected region, but they can
contain one or more protected regions.

4-68

Statements and Functions

DEF*

12. In DEF* functions that contain handlers, the following rules apply:
e If the function was invoked from a protected region, the EXIT
HANDLER statement transfers control to the handler specified for
that protected region.

e If the function was not invoked from a protected region, the EXIT .
HANDLER statement transfers control to the default error handler
Examples

Example 1
1Single-Line DEF*

DEF* STRING CONCAT (STRING A,B) = A + B
DECLARE STRING wordl,word2

INPUT "Enter two words";wordl,word2

PRINT CONCAT

(wordl,word2)

Output
Enter two words? TO
?

DAY

TODAY

Example 2
IMulti-Line DEF¥*

DEF* DOUBLE example (DOUBLE A, B, SINGLE C, D, E)
EXIT DEF IF B = 0

example = (A/B) + C - (D*E)

END DEF

INPUT "Enter 5 numbers";V,W,X,Y,Z

PRINT example(V,W,X,Y,2)

Output
Enter 5 numbers? 2,4,6,8,1
-1.5

Statements and Functions 4-69

DELETE

DELETE
The DELETE statement removes a recor

d from a relative or indexed file.

Format

DELETE

#chnl-exp

Syntax Rules

Chnl-exp is a numeric expression that specif
ies a channel number associated
with a file. It must be immediately prece
ded by a number sign (#).

Remarks

The DELETE statement removes the curre
nt record from a file. Once
the record is removed, you cannot access
it.

The file specified by chnl-exp must have
been opened with ACCESS
MODIFY or WRITE.

You can delete a record only if the last

specified channel was a successful GET

4-70

or FIND operation.

The DELETE statement leaves the curre

the next record pointer unchanged.
9.

I/O statement executed on the
nt record pointer undefined and

VAX BASIC signals an error when the
I/O channel is illegal or not open,
when no current record exists, when access
is illegal or illogical, or when
the operation is illegal.

Statements and Functions

DELETE

Example

DECLARE

STRING record_num

OPEN "CUS.DAT" FOR INPUT AS #1, RELATIVE FIXED
ACCESS MODIFY, RECORDSIZE 40

INPUT "WHICH RECORD WOULD YOU LIKE TO EXAMINE";record_num

GET #1, RECORD record num
DELETE #1

In this example, CUS.DAT is opened for input with ACCESS MODIFY.
Once you enter the number of the record you want to retrieve and the GET
statement executes successfully, the current record number is deleted.

Statements and Functions

4-71

DET

DET
The DET function returns the value of the determinant of the last matrix
inverted with the MAT INV function.

Format
real-var = DET

Syntax Rules

None.

Remarks

When a matrix is inverted with the MAT INV statement, VAX BASIC
calculates the determinant as a by-product of the inversion process. The
DET function retrieves this value.

If your program does not contain a MAT INV statement, the DET
function returns a value of zero.

The value returned by the DET function is a floating-point value of the

default size.

4-72

Statements and Functions

DET

Example

MAT

INPUT

first

MAT

first array;

array(3, 3)

PRINT
MAT

inv_array

determinant
MAT

INV

(first_array)

DET

inv_array;

determinant

PRINT
MAT

mult_array

MAT

first_array

inv_array

mult array;

O O

- O
o

=
oo
=

o O

o
O
=

O
[T

oo+

QOO

Output

Statements and Functions

4-73

DIF$

DIF$
The DIF$ function returns a numeric string whose value is the difference
between two numeric strings.

Format

str-var = DIF$ (str-exp1, str-exp2)

Syntax Rules
Each str-exp can contain up to 54 ASCII digits, an optional decimal point,
and an optional leading sign.

Remarks
1. The DIF$ function does not support E-format notation.

2. VAX BASIC subtracts str-exp2 from str-expl and stores the result in
str-var.

3. The difference between two integers takes the precision of the larger
integer.

4. The difference between two decimal fractions takes the precision of the
more precise fraction, unless trailing zeros generate that precision.

4-74

Statements and Functions

DIF$
The difference between two floating-point numbers takes precision as
follows:

The difference of the integer parts takes the precision of the larger
part.

The difference of the decimal fraction part takes the precision of the
more precise part.

VAX BASIC truncates leading and trailing zeros.

Example

PRINT DIF$

("689","-231")

Output
920

Statements and Functions 4-75

DIMENSION

DIMENSION
The DIMENSION statement creates and names a static,

dynamic, or virtual
array. The array subscripts determine the dimensions and the
size of the
array. You can specify the data type of the array and associate
the array
with an I/0 channel.

Format
Nonvirtual, Nonexecutable

DIM
i
] name ( [ int-con
{DIME
intNSION } {[ data-ty
pe ] arrayst1 TO ]

int-const2,... },...)
Executable

{D'M

DIMENSION

} {[ data-type | array-name
([ int-var1 TO ] int-var2,... ) },...

Virtual

{ DIM

DIMENSION

} #chnl-exp, { [ data-type | array-name
’

(int-const,... ) [ = int-const ] },...

Syntax Rules

An array name in a DIM statement cannot also appear in a COMMON
,
MAP, or DECLARE statement.

Data-type can be any VAX BASIC data type keyword or a data type

defined in a RECORD statement. Data type keywords, size, range,
and
precision are listed in Table 1-2 in this manual.

4-76

Statements and Functions

DIMENSION
If you do specify a data type and the array name ends in a percent sign
(%) or dollar sign ($) suffix character, the variable must be a string or
integer data type.

If you do not specify a data type, the array name determines the type
of data the array holds. If the array name ends in a percent sign, the
array stores integer data of the default integer size. If the array name
ends in a dollar sign, the array stores string data. Otherwise, the array
stores data of the default type and size.

An array can have up to 32 dimensions. Nonvirtual array sizes are
limited by the virtual memory limits of your system.

When you declare a nonvirtual array, VAX BASIC allows you to specify
both lower and upper bounds. The upper bound is required; the lower
bound is optional.

Int-constl or int-varl specifies the lower bounds of the array.

Int-const2 or int-var2 specifies the upper bounds of the array and,
when accompanied by int-constl or int-varl, must be preceded by the
keyword TO.

[Ini-constl must be less than or equal to int-const2. Int-varl must be

If you do not specify int-constl or int-varl, VAX BASIC uses zero as

Array dimensions can have either positive or negative values.

less than or equal to int-var2.

the default lower bound.

Nonvirtual, Nonexecutable

When all the dimension specifications are integer constants, as

in DIM A(15,10,20), the DIM statement is nonexecutable and the
array size is static. A static array cannot appear in another DIM
statement because VAX BASIC determines storage requirements at
compilation time.

A nonexecutable DIM statement must lexically precede any reference
to the array it dimensions. That is, you must dimension a static
array before you can reference array elements.

Virtual

The virtual array must be dimensioned and the file must be open
before you can reference the array.

Statements and Functions

4-77

DIMENSION

When the data type is STRING, the =int-const clause specifies
the length of each array element. The default string length is 16
characters. Virtual string array lengths are rounded to the next
higher power of 2. Therefore, specifying an element length of 12
results in an actual length of 16. For example:
DIM #1,
OPEN

STRING vir array(100)

"STATS.BAS"

FOR OUTPUT

12
#1,

VIRTUAL

Output
$BASIC-W-STRLENINC,
from 12

virtual

array

string

VIR ARRAY

length increased

Executable

When any of the dimension specifications are integer variables as in
DIM A(10%,20%,Y%), the DIM statement is executable and the array is

dynamic. A dynamic array can be redimensioned with a DIM statement
any number of times because VAX BASIC allocates storage at run time

when each DIM statement is executed.

‘

Remarks

You can create an array implicitly by referencing an array element
without using a DIM statement. This causes VAX BASIC to create an
array with dimensions of (10), (10,10), (10,10,10), and so on, depending
on the number of bounds specifications in the referenced array element.

You cannot create virtual or executable arrays implicitly.

VAX BASIC allocates storage for arrays by row, from right to left.
Nonvirtual, Nonexecutable
*

You can declare arrays with the COMMON, MAP, and DECLARE
statements. Arrays so declared cannot be redimensioned with

the DIM statement. Furthermore, string arrays declared with a
COMMON or MAP statement are always fixed-length.
®

If you reference an array element declared in an array whose
subscripts are smaller than the lower bound or larger than the upper
bound specified in the DIM statement, VAX BASIC signals the error

“Subscript out of range” (ERR=55).

4-78

Statements and Functions

DIMENSION

Virtual

For new development, DIGITAL does not recommend virtual arrays.
When the rightmost subscript varies faster than the subscripts to
the left, fewer disk accesses are necessary to access array elements
in virtual arrays.
Using the same DIM statement for multiple virtual arrays allocates
all arrays in a single disk file. The arrays are stored in the order
they were declared.

Any program or subprogram can access a virtual array by declaring
it in a virtual DIMENSION statement. For example:
DIM #1,

A(10)

DIM #1,

B(10)

In this example, array B overlays array A. You must specify the
same channel number, data types, and limits in the same order as
they occur in the DIM statement that created the virtual array.

VAX BASIC stores a string in a virtual array by padding it with
trailing nulls to the length of the array element. It removes these
nulls when it retrieves the string from the virtual array. Remember
that string array element sizes are always rounded to the next power
of 2.

The OPEN statement for a virtual array must include the
ORGANIZATION VIRTUAL clause for the channel specified in
the DIMENSION statement.

VAX BASIC does not initialize virtual arrays and treats them as
statically allocated arrays. You cannot redimension virtual arrays.
Refer to the VAX BASIC User Manual for more information on
virtual arrays.
Executable

You create an executable, dynamic array by using integer variables
for array bounds, as in DIM A(Y%,X%). This eliminates the need
to dimension an array to its largest possible size. Array bounds in
an executable DIM statement can be constants or variables, but not
expressions. At least one bound must be a variable.

You cannot reference an array named in an executable DIM
statement until after the DIM statement executes.

Statements and Functions

4-79

DIMENSION

You can redimension a dynamic array to make the bounds of

each dimension larger or smaller, but you cannot change the
number of dimensions. For example, you cannot redimension a

four-dimensional array to be a five-dimensional array.

The executable DIM statement cannot be used to dimension virtual
arrays, arrays received as formal parameters, or arrays declared in

COMMON, MAP, or nonexecutable DIM statements.

An executable DIM statement always reinitializes the array to zero
(for numeric arrays) or to the null string if string.

If you reference an array element declared in an executable DIM
statement whose subscripts are not within the bounds specified
in the last execution of the DIM, VAX BASIC signals the error

“Subscript out of range” (ERR=55).

Examples

Example 1
!Nonvirtual,
DIM

Nonexecutable

STRING name_list
(20 TO

100),

BYTE

age (100)

Example 2
!Virtual
DIM #1%,

STRING name_ l1list(500),

REAL amount (10,10)

Example 3
!Executable

4-80

DIM DOUBLE

inventory (base,markup)

DIM DOUBLE

inventory

Statements and Functions

(new_base,new markup)

ECHO

ECHO
The ECHO function causes characters to be echoed at a terminal that is
opened on a specified channel.

Format

int-var = ECHO (chnl-exp)

Syntax Rules
Chnl-exp must specify a terminal.

Remarks

1. The ECHO function is the complement of the NOECHO function; each
function disables the effect of the other.

9. The ECHO function has no effect on an unopened channel.
3. The ECHO function always returns a value of zero.

Statements and Functions 4-81

ECHO

Example

DECLARE

INTEGER Y,

STRING pass_word

Y = NOECHO(0%)

SET NO PROMPT
INPUT

"Enter

Y = ECHO(0%)

your password:

IF pass_word =

"i;pass_word

"Darlene"

THEN
PRINT

END

CR+LF+"YOU ARE

Output
Enter your password?

YOU ARE

4-82

CORRECT

Statements and Functions

CORRECT

EDITS

EDIT$
The EDIT$ function performs one or more string editing functions,
depending on the value of its integer argument.

Format

str-var = EDIT$ (str-exp, int-exp)

Syntax Rules

None.

Remarks

VAX BASIC edits str-exp to produce str-var.

2. The editing that VAX BASIC performs depends on the value of int-exp.
Table 4-3 describes EDIT$ values and functions.

3. All values are additive; for example, you can perform the editing
functions of values 8, 16, and 32 by specifying a value of 56.
4. If you specify a floating-point expression for int-exp, VAX BASIC
truncates it to an integer of the default size.

Statements and Functions

4-83

EDIT$

Table 4-3:

EDITS$ Values

Value

Edit Performed

Discards each character’s parity bit (bit 7)

Discards all spaces and tabs

Discards all carriage returns <CR>, line feeds <LF>, form feeds <FF>,
deletes <DEL>, escapes <ESC>, and nulls <NUL>
Discards leading spaces and tabs

Converts multiple spaces and tabs to a single space

Converts lowercase letters to uppercase letters

Converts left bracket ([) to left parenthesis [(] and right bracket (1) to

right parenthesis [)]
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, VAX BASIC suppresses all editing for the

characters following the quotation mark

Example

DECLARE

STRING

old_string =

old_string,

"a value

new _string

converts

lowercase

letters

new_string = EDITS (old string,
32)
PRINT

new_string

Output
A VALUE

4-84

CONVERTS

Statements and Functions

LOWERCASE

LETTERS

UPPERCASE

uppercase"

END

END
The END statement marks the physical and logical end of a main program,
a program module, or a block of statements.

Format

END

[block ]

DEF[exp ]
FUNCTION/ exp ]
GROUP
RECORD
VARIANT
IF

HANDLER

block:

PICTURE

PROGRAM(/ int-exp |

SELECT

WHEN

\ SUB

Syntax Rules
None.

Statements and Functions 4-85

END

Remarks

The END statement with no block keyword marks

the end of a main

program. The END or END PROGRAM stateme
nt must be the

statement on the last lexical line of the main program

last

The END statement followed by a block keyword marks

the end of a

program, a VAX BASIC SUB, FUNCTION, or PICTU
RE subprogram, a

DEF, an IF, a HANDLER, a PROGRAM, a SELECT
statement block or
a WHEN block.
3.

END RECORD, END GROUP, and END VARIANT
mark the end of a
RECORD statement, or a GROUP component or VARIA
NT component o
a RECORD statement.

END DEF and END FUNCTION
*

When VAX BASIC executes an END DEF or an END

FUNCTION

statement, it returns the function value to the stateme

nt that

invoked the function and releases all storage associated

DEF or FUNCTION.
*

If you specify an optional expression with the END

with the

DEF or END

FUNCTION statement, the expression must be compati

ble with the
function result
unless an EXIT DEF or EXIT FUNCTION statement is
executed.
This expression supersedes all function assignments.

DEF or FUNCTION data type. The expression is the

®*

The END DEF statement restores the error handler

in effect when

the DEF was invoked (this is not true of the DEF* statemen

t).

The END FUNCTION statement does not affect I/O operati

files.
5.

END HANDLER

The END HANDLER statement causes VAX BASIC to
transfer control
to the statement following the WHEN block with the excepti
on cleared.
END PROGRAM
*

4-86

ons or

The END PROGRAM statement allows you to end a program
module.

Statements and Functions

END

An optional integer expression specifies the exit status of the
program that is reported to DCL. This status is overridden by a
status expression in an EXIT PROGRAM statement.

You can specify an END PROGRAM statement without a matching
PROGRAM statement.

END WHEN

The END WHEN statement ends a WHEN block and transfers

control to the statement following the WHEN block.
e

If the END WHEN statement ends an attached handler, control is
transferred to the statement following the WHEN block with the

exception cleared.
8.

END SUB
e

The END SUB statement does not affect I/0 operations or files.

The END SUB statement releases the storage allocated to local
variables and returns control to the calling program.

The END SUB statement cannot be executed in an error handler
unless the END SUB is in a subprogram called by the error handler
of another routine.

When an END or END PROGRAM statement marking the end of a main
program executes, VAX BASIC closes all files and releases all program
storage.

10. If you use ON ERROR error handling, you must clear any errors with

the RESUME statement before executing an END PROGRAM, END
SUB, END FUNCTION or END PICTURE statement.
11. Except for the END PROGRAM statement, VAX BASIC signals an

error when a program contains an END block statement with no
corresponding and preceding block keyword.

Statements and Functions

4-87

END

Example

INPUT

"Guess

IF A%

number";A%

THEN

PRINT,
END

"YOU GUESSED

IT!"

IF A%

THEN

PRINT,
GOTO
END

"BIGGER

IS BETTER!"TM

10
IF

IF A%

THEN

PRINT,

GOTO

4-88

END

PROGRAM

Statements and Functions

"SMALLER

BETTER!"

ERL

ERL
The ERL function returns the number of the BASIC line where the last
error occurred.

Format

int-var = ERL

Syntax Rules

The value of int-var returned by the ERL function is a LONG integer.

Remarks

If the ERL function is used before an error occurs or after an error is
handled, the results are undefined.

The ERL function overrides the /NOLINE qualifier. If a program
compiled with the /NOLINE qualifier in effect contains an ERL function,
VAX BASIC signals the message “ERL overrides NOLINE”.

Statements and Functions

4-89

ERL

Example

DECLARE
WHEN

LONG

ERROR

int_exp

USE

error_routine

INPUT

PRINT DATES (int_exp)
END

"Enter

integer

expression";int_exp

WHEN

HANDLER error_ routine
IF ERL

THEN

"Invalid input...try

RETRY

ELSE

PRINT
EXIT

"UNEXPECTED ERROR"
HANDLER

END

HANDLER

END PROGRAM

Output
Enter

Error

occurred on

Enter

integer expression? ABCD

integer

09-0ct-89

4-90

Statements and Functions

line

expression?

3211

again"

ERNS$

ERN$
The ERN$ function returns the name of the main program, subprogram, or
DEF function that was executing when the last error occurred.

Format

str-var = ERN$

Syntax Rules

None.

Remarks

1.
2.

If the ERN$ function executes before an error occurs or after an error is

handled, ERN$ returns a null string.

If you call a subprogram or function compiled with /NOSETUP or

containing an OPTION INACTIVE=SETUP statement, the ERN$
function will not have a valid value if an exception occurs in the called
procedure.

Statements and Functions

4-91

ERNS$

Example

DECLARE

LONG

int_exp

!This module’s
WHEN ERROR
INPUT

name

DATE

"Enter

number";int
exp

USE
PRINT

"Error

in module

RETRY
END

WHEN

PRINT Date$ (int_exp)
END

Output
Enter

number?

ABCD

Error

in module

DATE

Enter

number?

11-Oct-89

492

Statements and Functions

";ERNS

ERR

ERR
The ERR function returns the error number of the current run-time error.

Format

int-var = ERR

Syntax Rules

The value of int-var returned by the ERR function is always a LONG
integer.

Remarks

If the ERR function is used before an error occurs or after an error is
handled, the results are undefined.

Statements and Functions

4-93

ERR

Example

DECLARE
WHEN

LONG

ERROR

INPUT

int exp

USE

"Enter

error_ routine

an integer expression";int_exp

PRINT DATES (int_exp)
END

WHEN

HANDLER error routine:
PRINT

"Error

ERR =

ELSE

END

number";ERR

THEN PRINT
"UNEXPECTED

"DATA FORMAT
ERROR"

RETRY
END

HANDLER
END

Output
Enter

Error

number

integer

DATA FORMAT

Enter

ABCD

expression?

ERROR

integer

06-0ct-89

4-94

expression?

Statements and Functions

ERROR"

ERT$

ERTS
The ERT$ function returns explanatory text associated with an error
number.

Format

str-var = ERT$ (int-exp)

Syntax Rules

Int-exp is a VAX BASIC error number. The error number must be in the
range 0 through 255.

Remarks

1. The ERT$ function can be used at any time to return the text associated
with a specified error number.

2. If you specify a floating-point expression for int-exp, VAX BASIC
truncates it to an integer of the default size.

Statements and Functions

4-95

ERTS$

Example

DECLARE
WHEN

LONG

ERROR

int_ exp

USE

error routine

INPUT

"Enter

DATES (int_exp)

integer

expression”;int exp

END WHEN
HANDLER

error routine

"Error

ERTS$ (ERR)

number";ERR

RETRY
END

HANDLER

END

Output
Enter

Error

number

$Data

format

error

Enter

integer

15-0ct-89

4-96

Statements and Funcitions

expression?

ABCD

EXIT

EXIT
The EXIT statement lets you exit from a main program, a SUB, FUNCTION,
or PICTURE subprogram, a multi-line DEF, a statement block, or a handler.

Format

EXIT

block

DEF[exp ]
FUNCTION/ exp ]

block:

SuB

| HANDLER
PICTURE
PROGRAM/ int-exp |

label

)

Syntax Rules

The DEF, FUNCTION, SUB, HANDLER, and PROGRAM keywords
specify the type of subprogram, multi-line DEF, or handler from which

VAX BASIC is to exit.

If you specify an optional expression with the EXIT DEF statement
or with the EXIT FUNCTION statement, the expression becomes
the function result and supercedes any function assignment. It also

overrides any expression specified on the END DEF or END FUNCTION
statement. Note that the expression must be compatible with the
FUNCTION or DEF data type.

Label specifies a statement label for an IF, SELECT, FOR, WHILE, or
UNTIL statement block.

Statements and Functions

4-97

EXIT

Remarks

An EXIT SUB, EXIT FUNCTION, EXIT PROGRAM, EXIT DEF, or

EXIT PICTURE statementis equivalent to an unconditional branch to

an equivalent END statement. Control then passes to the statement
that invoked the DEF or to the statement following the statement that

called the subprogram.

The EXIT HANDLER statement causes VAX BASIC to transfer control

to a specified area.

If the current WHEN block is nested, control transfers to the handler
associated with the next outer protected region.

If an ON ERROR statement is in effect and the current WHEN
block is not nested, control transfers to the target of the ON ERROR
statement.

If neither of the previous conditions is true, an EXIT HANDLER

statement transfers control to the calling program or DCL. This
action is the equivalent of the ON ERROR GO BACK statement.

The EXIT PROGRAM statement causes VAX BASIC to exit from a main

program module.

An optional integer expression on an EXIT PROGRAM statement
specifies the exit status of the program that is reported to DCL.

The expression specified by an EXIT PROGRAM statement overrides
any integer expression specified by an END PROGRAM statement.

VAX BASIC allows you to specify an EXIT PROGRAM statement

without a matching PROGRAM statement.

The EXIT label statementis equivalent to an unconditional branch to
the first statement following the end of the IF, SELECT, FOR, WHILE,

or UNTIL statement labeled by the specified label.

An EXIT FUNCTION, EXIT SUB or EXIT PROGRAM statement cannot

be used within a multi-line DEF function.
6.

When the EXIT FUNCTION, EXIT SUB or EXIT PROGRAM statement
executes, VAX BASIC releases all storage allocated to local variables and

returns control to the calling program.

498

Statements and Functions

EXIT

Example

DEF

emp.bonus
(A)

IF A

THEN

EXIT

"OUT

DEF

RANGE"

ELSE

emp.bonus
END

END

DEF

= A

INPUT A

emp.bonus
(A)

END

Output
11

OUT OF RANGE

Statements and Functions

4-99

EXP

EXP
The EXP function returns the value of the mathematical constant e raised to
a specified power.

Format
real-var = EXP (real-exp)

Syntax Rules

None.

Remarks

The EXP function returns the value of e raised to the power of real-exp.

VAX BASIC expects the argument of the EXP function to be a real

expression. When the argument is a real expression, VAX BASIC
returns a value of the same floating-point size. When the argument is
not a real expression, VAX BASIC converts the argument to the default
floating-point size and returns a value of the default floating-point size.
3.

When the default REAL size is SINGLE or DOUBLE, EXP allows

arguments between —88 and 88. If the default REAL size is GFLOAT,
EXP allows arguments between —709 and 709. If the default REAL size

is HFLOAT, the arguments can be in the range —11356 to 11355. When
the argument exceeds the upper limit of a range, VAX BASIC signals an

error. When the argument exceeds the lower limit of a range, the EXP
function returns a zero and VAX BASIC does not signal an error.

4100

Statements and Functions

EXP

Example

DECLARE SINGLE num val
num val = EXP (4.6)
PRINT

num val

Output
99.4843

Statements and Functions

4-101

EXTERNAL

EXTERNAL
The EXTERNAL statement declares constants, variables, functions, and

subroutines external to your program. You can describe parameters for
external functions and subroutines.

Format
External Constants

EXTERNAL

data-type CONSTANT const-name,...

External Variables

EXTERNAL

data-type unsubs-var,...

External Functions

EXTERNAL

data-type FUNCTION { func-name [ pass-mech ]|
[ ( external-param ,... ) ] },...

External Subroutines

EXTERNAL SUB

pass-mech:

external-param:

{ sub-name [ pass-mech ] [ ( external-param,...) ] },...

{ BY VALUE }
BY REF
BY DESC
[OPTIONAL ][ param-data-type ] [DIM([,]... ) ]
[ = int-const ] [ pass-mech |

External Pictures

EXTERNAL PICTURE

4-102

Statements and Functions

pic-name [ ( param-list ) |

EXTERNAL

Syntax Rules

For external constants, data-type can be BYTE, WORD, LONG, SINGLE,
INTEGER (any size), or REAL (if the default size is SINGLE).

For external variables, the data type can be any valid numeric data
type.

For external functions and subroutines, the data type can be BYTE,
WORD, LONG, SINGLE, DOUBLE, GFLOAT, HFLOAT, DECIMAL,
STRING, INTEGER, REAL, RFA, or a data type defined with the
RECORD statement. See Table 1-2 in this manual for more information
on data type size, range and precision.

The name of an external constant, variable, function, or subroutine can

be from 1 through 31 characters.

For all external routine declarations, the name must be a valid
VAX BASIC identifier and must not be the same as any other SUB,
FUNCTION, PICTURE, or PROGRAM name.

Param-data-type specifies the data type of a parameter. If you do not
specify a data type, parameters are of the default data type and size.

Param-list is identical to external-param except that no OPTIONAL
parameter is allowed.

Parameters in the param-list must agree in number and data type with
the parameters in the invocation. Param-data-type includes ANY, BYTE,
WORD, LONG, INTEGER, SINGLE, DOUBLE, GFLOAT, HFLOAT,
READ, a user-defined RECORD type, STRING, or RFA.

For more information on external pictures, see the Programming with
VAX BASIC Graphics.

External Functions and Subroutines

The data type that precedes the keyword FUNCTION defines the

Pass-mech specifies how parameters are to be passed to the function

data type of the function result.
or subroutine.

—

A pass-mech clause outside the parentheses applies to all
parameters.

Statements and Functions

4-103

EXTERNAL

—
*

A pass-mech clause inside the parentheses overrides the previous
pass-mech and applies only to the specific parameter.

External-param defines the form of the arguments passed to

the external function or subprogram. Empty parentheses
indicate that the subprogram expects zero parameters. Missing
parentheses indicate that the EXTERNAL statement does not define
parameters.

10. Using ANY as a VAX BASIC Data Type
*

The ANY data type should only be used for calling non-BASIC

procedures. Therefore, the ANY data type is illegal in a PICTURE

declaration.

If you specify ANY, VAX BASIC does not perform data type checking

or conversions. If no passing mechanism is specified, VAX BASIC

uses the default passing mechanism for the data type passed in a

given invocation.
*

When you specify a data type, all following parameters that are not

specifically declared default to the last specified data type. Similarly,
when you specify ANY, all following unspecified parameters default

to the data type ANY until a new declaration is provided. For
example:

EXTERNAL

SUB

allocate

(LONG,ANY,

)

11. Passing Optional Parameters

The OPTIONAL keyword should be used only for calling non-BASIC

procedures.

If you specify the keyword OPTIONAL, VAX BASIC treats all
following parameters as optional. In the following example, the last
three parameters are optional.
EXTERNAL

SUB

OPTIONAL

STRING,

LONG,

ANY)

When a procedure is called, the argument pointer (@AP) contains the
number of actual parameters specified.

VAX BASIC still performs type checking and conversion on optional
parameters.

4-104

queue (STRING,

Statements and Functions

EXTERNAL

If you want to omit an optional parameter that appears in the
middle of a parameter list, VAX BASIC requires you to insert a
comma placeholder. However, if you want to omit an optional
parameter that appears at the end of a parameter list, you can omit
that parameter without inserting any placeholder.

You can specify the keyword OPTIONAL only once in any one
parameter list.

12. Declaring Array Dimensions

The DIM keyword indicates that the parameter is an array. Commas
specify array dimensions. The number of dimensions is equal to the
number of commas plus 1. For example:
EXTERNAL STRING FUNCTION new

(DOUBLE,

STRING DIM(,),

DIM(

))

This statement declares a function named new that has three
parameters. The first is a double-precision floating-point value,
the second is a two-dimensional string array, and the third is a

one-dimensional string array. The function returns a string result.

Remarks

The EXTERNAL statement must precede any program reference to
the constant, variable, function, subroutine or picture declared in the
statement.

The EXTERNAL statement is not executable.

A name declared in an EXTERNAL CONSTANT statement can be used
in any nondeclarative statement as if it were a constant.

A name declared in an EXTERNAL FUNCTION statement can be used
as a function invocation in an expression. In addition, you can invoke
a function with the CALL statement unless the function data type is
DECIMAL, HFLOAT, or STRING.

A name declared in an EXTERNAL SUB statement can be used in a
CALL statement.

Statements and Functions

4-105

EXTERNAL

The optional pass-mech clauses in the EXTERNAL FUNCTION and
EXTERNAL SUB statements tell VAX BASIC how to pass arguments to
a non-BASIC function or subprogram. Table 4-1 describes VAX BASIC
parameter-passing mechanisms.

BY VALUE specifies that VAX BASIC passes the argument’s 32-bit
value.

BY REF specifies that VAX BASIC passes the argument’s address.

This is the default for all arguments except strings and entire arrays.
If you know the size of string parameters and the dimensions of
array parameters, you can improve run-time performance by passing

strings and arrays by reference.

BY DESC specifies that VAX BASIC passes the address of a VAX
BASIC descriptor. For information about the format of a VAX BASIC
descriptor for strings and arrays, see Appendix C in this manual.

If you do not specify the data type ANY or declare parameters as

optional, the arguments passed to external functions and subroutines
should match the external parameters declared in the EXTERNAL
FUNCTION or EXTERNAL SUB statement in number, type, and
passing mechanism. VAX BASIC forces arguments to be compatible with

declared parameters. If they are not compatible, VAX BASIC signals an

error.

Examples

Example 1
!External
EXTERNAL

Constant
LONG CONSTANT

Example 2
!External Variable
EXTERNAL WORD

4-106

SYSNUM

Statements and Functions

SS$~NORMAL

EXTERNAL

Example 3
IExternal Function

EXTERNAL DOUBLE FUNCTION USRS2 (WORD, LONG, ANY)

Example 4
IExternal Subroutine

EXTERNAL SUB calc BY DESC (STRING DIM(,),

BYTE BY REF')

Statements and Functions 4-107

FIELD

FIELD
The FIELD statement dynamically associates
string variables with all or
parts of a record buffer. FIELD statements do not
move data. Instead, they
permit direct access through string variables to
sections of a specified record

buffer.

NOTE
The FIELD statement is supported only for compati
BASIC-PLUS. Because data defined in the FIELD

be accessed only as string data, you must use the

bility with

statement can

CVTxx functions

to process numeric data; therefore, you must convert

to numeric after you move it from the record buffer.

processing, you must convert numeric data back

string data

Then, after

to string data

before transferring it to the record buffer. DIGITAL
recommends
that you use VAX BASIC’s dynamic mapping feature
or multiple
maps instead of the FIELD statement and CVTxx
functions.

Format

FIELD

#chnl-exp, int-exp AS str-var( , int-exp AS str-var ]...

Syntax Rules

Chnl-exp is a numeric expression that specifies a

channel number

associated with a file. It must be immediately precede
d by a number

sign (#). A file must be open on the specified channel
or VAX

signals an error.

Int-exp specifies the number of characters in str-var

. However, a
subsequent int-exp cannot depend on the return string
from a previous
int-exp. For example, the following statement is illegal
because the
second int-exp depends on the return string A$:

FIELD

4-108

BASIC

#1%,

Statements and Functions

AS$,

ASCII(AS)

BS$

FIELD

Remarks
A FIELD statement is executable. You can change a buffer description
at any time by executing another FIELD statement. For example:
FIELD #1%,

40% AS whole_field$

FIELD #1%, 10% AS AS$, 10% AS BS$,

10% AS C$, 10% AS DS

The first FIELD statement associates the first 40 characters of a buffer
with the variable whole_field$. The second FIELD statement associates
the first 10 characters of the same buffer with A$, the second 10
characters with B$, and so on. Later program statements can refer to

any of the variables named in the FIELD statements to access specific
portions of the buffer.

You cannot define virtual array strings as string variables in a FIELD
statement.

A variable named in a FIELD statement cannot be used in a COMMON
or MAP statement, as a parameter in a CALL or SUB statement, or in a
MOVE statement.

Using the FIELD statement on a virtual file that contains a virtual array
causes VAX BASIC to signal “Illegal or illogical access” (ERR=136).
If you name an array in a FIELD statement, you cannot use MAT
statements of the format

MAT array-name1 = array-name2 MAT array-namel = NUL$

where array-namel is named in the FIELD statement. An attempt to do
so causes VAX BASIC to signal a compile-time error.

Statements and Functions

4—-109

FIELD

Example

FIELD

#8%,

LSET U$
LSET

CL$

2% AS U$,

= CVT$$ (U%)
= CVT%$ (CL%)

LSET X$ = CVTFS$ (X)
LSET Y$

= CVTFS$(Y)

= CVT$%(US)

CL%

4-110

= CVT$$% (CLS)
= CVTSF (X$)

CVTSF (Y$)

Statements and Functions

2% AS

CL$,

AS X$,

4% AS

FIND

The FIND statement locates a specified record in a disk file and makes
it the current record for a GET, UPDATE, or DELETE operation. FIND
statements are valid on RMS sequential, relative, and indexed files.

Format

FIND

#chnl-exp [, position-clause ][ , lock-clause]
{ RFA rfa-exp

position-clause:

}

RECORD num-exp
KEY# key-clause

lock-clause:

allow-clause:

key-clause:

{ ALLOWallow-clause [ ,WAIT [ int-exp ] ] }
WAIT [int-exp ]
REGARDLESS
NONE

READ
MODIFY

int-exp1 rel-op key-exp

‘ EQ
rel-op:

W
L

GE
fi NXEQ

| NX

Statements and Functions

4-111

FIND

)

sir-exp

key-exp:

decimal-exp

¥
ot

( int-exp2

_ quadword-exp |

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number
associated with a file. It must be immediately preceded by a number
sign (#).

2.
3.

If you specify a lock-clause, it must follow the position-clause. If the
lock-clause precedes the position-clause, VAX BASIC signals an error.
If you specify the REGARDLESS lock-clause, you cannot specify another
lock-clause in the same FIND statement.

Remarks

Position-clause

Posttion-clause specifies the position of a record in a file. VAX BASIC
signals an error if you specify a position-clause and the channel is
not associated with a disk file. If you do not specify a position-clause,

FIND locates records sequentially. Sequential record access is valid
on all files.

The RFA position-clause allows you to randomly locate records by
specifying the record file address (RFA) of a record. You specify the

disk address of a record, and RMS locates the record at that address.

All file organizations can be accessed by RFA.

Rfa-exp in the RFA position-clause is a variable of the RFA data type

that specifies the record’s file address. Note that an RFA expression
can only be a variable of the RFA data type or the GETRFA function.
Use the GETRFA function to find the RFA of a record.

4-112

Statements and Functions

FIND

The RECORD position-clause allows you to randomly locate records
in relative and sequential fixed files by specifying the record
number.

—

Nume-exp in the RECORD position-clause specifies the number
of the record you want to locate. It must be between 1 and the
number of the record with the highest number in the file.

When you specify a RECORD clause, chnl-exp must be a channel
associated with an open relative or sequential fixed file.
The KEY position-clause allows you to randomly locate records in
indexed files by specifying a key of reference, a relational test, and a

—

key value.

An RFA value is valid only for the life of a specific version of a file.
If a new version of a file is created, the RFA values may change.
Attempting to access a record with an invalid RFA value results in a
run-time error.

Lock-clause

Lock-clause allows you to control how a record is locked to other
access streams, to override lock checking when accessing shared files
that may contain locked records, or to specify what action to take in
the case of a locked record.

The type of lock you impose on a record remains in effect until

you explicitly unlock it with a FREE or UNLOCK statement, until
you close the file, or until you perform a GET, FIND, UPDATE
or DELETE on the same channel (unless you specified UNLOCK
EXPLICIT).

The REGARDLESS lock-clause specifies that the FIND statement

can override lock checking and locate a record locked by another
program.

When you specify a REGARDLESS lock-clause, VAX BASIC does not
impose a lock on the retrieved record.

The ALLOW lock-clause lets you control how a record is locked
to other users and access streams. The file associated with the
specified channel must have been opened with the UNLOCK
EXPLICIT clause or VAX BASIC signals the error “Illegal record
locking clause”.

Statements and Functions

4-113

FIND

The ALLOW allow-clause can be one of the following:
—

ALLOW NONE denies access to the record. This means that
other access streams cannot retrieve the record unless they

bypass lock checking with the GET REGARDLESS clause.
—

ALLOW READ provides read access to the record. This means

that other access streams can retrieve the record but cannot use
the DELETE or UPDATE statements on the record.
—

ALLOW MODIFY provides read and write to the record. This
means that other access streams can use the GET, FIND,

DELETE, and UPDATE statements on the record.
*

If you do not open a file with the ACCESS READ clause or specify

an allow-clause, locking is imposed as follows:
—

If the file associated with the specified channel was opened with

UNLOCK EXPLICIT, VAX BASIC imposes the ALLOW NONE
lock on the retrieved record and the next GET or FIND operation
does not unlock the previously locked record.
—

If the file associated with the specified channel was not opened
with UNLOCK EXPLICIT, VAX BASIC locks the retrieved record

and unlocks the previously locked record.

The WAIT lock-clause accepts an optional int-exp. Int-exp represents
a timeout value in seconds. Int-exp must be from 0 through 255 or
VAX BASIC signals a warning message.
—

WAIT followed by a timeout value causes RMS to wait for a

locked record for a given period of time.
—

WAIT followed by no timeout value indicates that RMS should
wait indefinitely for the record to become available.

—

If you specify a timeout value and the record does not
become available within that period, VAX BASIC signals

the the run-time error “Keyboard wait exhausted” (ERR=15).
VMSSTATUS and RMSSTATUS then return RMS$_TMO.
For more information on the RMSSTATUS and VMSSTATUS
functions, see this chapter and the VAX BASIC User Manual.
—

If you attempt to wait for a record that another user has
locked, and consequently that user attempts to wait for the
record you have locked, a deadlock condition occurs. When
a deadlock condition persists for a period of time (as defined

4-114

Statements and Functions

FIND

by the SYSGEN parameter DEADLOCK_WAIT), RMS signals
the error “RMS$_DEADLOCK” and VAX BASIC signals the
error “Detected deadlock error while waiting for GET or FIND”
(ERR=193).

— If you specify a WAIT clause followed by a timeout value that
is Jess than the SYSGEN parameter DEADLOCK_WAIT, VAX
BASIC signals the error “Keyboard wait exhausted” (ERR=15)
even though a deadlock condition may exist.

Key-clause

In a key-clause, int-expl is the target key of reference. It must be
an integer in the range of zero through the highest-numbered key
for the file. The primary key is #0, the first alternate key is #1, the
second alternate key is #2, and so on. Int-expl must be preceded by
a number sign (#) or VAX BASIC signals an error.

When you specify a key-clause, the specified channel must be a
channel associated with an open indexed file.

Rel-op

Rel-op is a relational operator that specifies how key-exp is to be
compared with int-expl in the key-clause.

—

EQ means “equal to”

NXEQ means “next or equal to”

—

NX means “next”

— GE means “greater than or next” (a synonym for NXEQ)
—

GT means “greater than” (a synonym for NX)

A successful random FIND operation by key locates the first record
whose key satisfies the key-clause comparison:

—~ With an exact key match (EQ), a successful FIND locates the
first record in the file that equals the key value specified in
key-exp. However, if the characters specified by a str-exp key
expression are less than the key length, characters specified
by str-exp are matched approximately rather than exactly.
For example, if you specify “ABC” and the key length is six

characters, VAX BASIC locates the first record that begins with
ABC. If you specify “ABCABC”, VAX BASIC locates only a record
with the key “ABCABC”. If no match 1s possible, VAX BASIC
signals the error “Record not found” (ERR=155).

Statements and Functions

4-115

FIND

—

If you specify a next or equal to record key

match (NXEQ), a

successful FIND locates the next record that

equals the key

If you specify a greater than or equal to key

match (GE),

length specified in int-exp or str-exp. If no exact
match exists,
VAX BASIC locates the next record in the key sort
order. If the
keys are in ascending order, the next record will have
a greater
key value. If the keys are in descending order,
the next record
will have a lesser key value.
—

the behavior is identical to that of next or equal

(Likewise, the behavior of GT is identical to NX.)

to (NXEQ).
However, the

use of GE in a descending key file may be confusi

ng, since GE

will retrieve the next record in the key sort
order but the next
record will have a lesser key value. For this reason,
DIGITAL

recommends that you use NXEQ in new progra

especially if you are using descending key files.
—

m development,

If you specify a next key match (NX), a success

ful FIND locates

the first record that follows the relational operato

r in the sort
order. If no such record exists, VAX BASIC signals
the error
“Record not found” (ERR=155).
9.

Key-exp

Int-exp2 specifies an integer value to be compar

ed with the key value

of a record.

Sir-exp specifies a string value to be compared with

the key value of

a record. Str-exp can contain fewer characters
than the key of

record you want to locate, but cannot be a null
*

Decimal-exp in the key clause specifies a packed
compared with the key value of a record.

the

string.
decimal value to be

Quadword-exp in the key clause specifies a
a record or group which
is exactly 8 bytes long that is to be compared with
the key value of a
record.

The file on the specified channel must have
been opened with ACCESS
MODIFY, ACCESS READ, or SCRATCH before
your program can
execute a FIND operation.

FIND does not transfer any data to the record

contents of a record, use the GET statem

ent.

4-116

Statements and Functions

buffer. To access the

FIND

A successful sequential FIND operation updates both the current record
pointers and next record pointers.

For sequential files, a successful FIND operation locates the next
sequential record (the record pointed to by the next record pointer)
in the file, changes the current record pointer to the record just
found, and the next record pointer to the next sequential record.
If the current record pointer points to the last record in a file, a
sequential FIND operation causes VAX BASIC to signal “Record not
found” (ERR=155).

For relative files, a successful FIND operation locates the record that
exists with the next higher record number (or cell number), makes
it the current record, and changes the next record pointer to the
current record pointer plus 1.

Tor indexed files, a successful FIND operation locates the next
existing logical record in the current key of reference, makes this the
current record and changes the next record pointer to the current
record pointer plus 1.

A successful random access FIND operation by RFA or by record changes
the current record pointer to the record specified by rfa-exp or int-exp,
but leaves the next record pointer unchanged.
10. A successful random access FIND operation by key changes the current

record pointer to the first record whose key satisfies the key-clause
comparison and leaves the next record pointer unchanged.
11. When a random access FIND operation by RFA, record, or key is

not successful, VAX BASIC signals “Record not found” (ERR=155).
The values of the current record pointer and next record pointer are
undefined.
12. You should not use a FIND statement on a terminal-format or virtual

array file.

Statements and Functions

4-117

FIND

Example

DECLARE

MAP

LONG

(cusrec)

rec-num

WORD

cus num

STRING cus_nam=20,

OPEN

"CUS_ACCT.DAT"
RELATIVE

cus_add=20,

FOR INPUT AS

cus_city=10,

#1,

FIXED,

ACCESS MODIFY
MAP

INPUT

FIND

RECORD

rec_num,

DELETE #1

CLOSE #1
END

4-118

cusrec

"Which record number would you

#1,

cus_zip=9

Statements and Functions

WAIT

delete";rec
num

FIX

FIX
The FIX function truncates a floating-point value at the decimal point and
returns the integer portion represented as a floating-point value.

Format
real-var = FIX (real-exp)

Syntax Rules

None.

Remarks

The FIX function returns the integer portion of a floating-point value,

not an integer value.

VAX BASIC expects the argument of the FIX function to be a real

If real-exp is negative, FIX returns the negative integer portion. For
example, FIX(-5.2) returns -5.

Statements and Functions

4-119

FIX

Example

DECLARE

SINGLE

result

result = FIX(-3.333)
PRINT FIX(24.566),

Output
24

4-120

-3

Statements and Functions

result

FNEND

FNEND
The FNEND statement is a synonym for the END DEF statement. See the
END statement for more information.

Format
FNEND

[exp]

Statements and Functions

4-121

FNEXIT

FNEXIT
The FNEXIT statement is a synonym for the EXIT DEF statement. See the
EXIT statement for more information.

Format
FNEXIT

4-122

[exp]

Statements and Functions

FOR

The FOR statement repeatedly executes a block of statements, while
incrementing a specified control variable for each execution of the statement

block. FOR loops can be conditional or unconditional, and can modify other
statements.

Format
Unconditional

FOR

num-unsubs-var = num-exp1 TO num-exp2 [ STEP num-exp3 |
[ statement |...

num-unsubs-var

Conditional

FOR

num-unsubs-var = num-exp1 [ STEP num-exp3 ] { UNTIL }
WHILE

cond-exp

[ statement ]...
NEXT

num-unsubs-var

Unconditional Statement Modifier

statement FOR num-unsubs-var = num-exp1 TO num-exp2 [ STEP

num-exp3]

Conditional Statement Modifier

statement FOR num-unsubs-var = num-exp1 [ STEP num-exp3
|

{ UNTIL

WHILE } cond-exp
Statements and Functions

4-123

FOR

Syntax Rules

Num-unsubs-var must be a numeric, unsubscripted variable.
Num-unsubs-var cannot be a record field.

2. Num-unsubs-var is the loop variable. It is incremented each time the
loop executes.

3.
4.

In unconditional FOR loops, num-expl is the initial value of the loop

variable; num-exp2 is the maximum value.

In conditional FOR loops, num-expl is the initial value of the loop
variable, while the cond-exp in the WHILE or UNTIL clause is the
condition that controls loop iteration.

5. Num-exp3 in the STEP clause is the value by which the loop variable is
incremented after each execution of the loop.

Remarks

There is a limit to the number of inner loops you can contain within a
single outer loop. This number varies according to the complexity of the

loops. If you exceed the limit, VAX BASIC signals an error message.
An inner loop must be entirely within an outer loop; the loops cannot
overlap.

You cannot use the same loop variable in nested FOR loops. For
example, if the outer loop uses FOR I = 1 TO 10, you cannot use the
variable I as a loop variable in an inner loop.

The default for num-exp3 is 1 if there is no STEP clause.

You can transfer control into a FOR loop only by returning from a
function invocation, a subprogram call, a subroutine call, or an error
handler that was invoked in the loop.

4-124

The starting, incrementing, and ending values of the loop do not change

The loop variable can be modified inside the FOR loop.

during loop execution.

Statements and Functions

FOR

VAX BASIC converts num-expl, num-exp2, and num-exp3 to the data
type of the loop variable before storing them.

When an unconditional FOR loop ends, the loop variable contains the
value last used in the loop, not the value that caused loop termination.
10. During each iteration of a conditional loop, VAX BASIC tests the value

of cond-exp before it executes the loop.
*

If you specify a WHILE clause and cond-exp is false (value ZEero),
VAX BASIC exits from the loop. If the cond-exp is true (value
nonzero), the loop executes again.

If you specify an UNTIL clause and cond-exp is true (value Nonzero),
VAX BASIC exits from the loop. If the exp is false (value zero), the
loop executes again.

11. When FOR is used as a statement modifier, VAX BASIC executes the

statement until the loop variable equals or exceeds num-exp2 or until

the WHILE or UNLESS condition is satisfied.

12, Each FOR statement must have a corresponding

NEXT statement or
VAX BASIC signals an error. (This is not the case if the FOR statement
1s used as a statement modifier.)

Examples

Example 1
!Unconditional
DECLARE

LONG

course_num,

FOR

STEP

STRING

INPUT

"Course

number";course
num

INPUT

"Course

name";course
nam

course

nam

Statements and Functions

4-125

FOR

Output
Course number? 221

Course name? Botany
Course number? 231

Course name? Organic Chemistry
Course number? 237

Course name? Life Science II
Course number? 244

Course name? Programming in VAX BASIC

Example 2
iUnconditional Statement Modifier

DECLARE INTEGER counter

PRINT "This is an unconditional statement modifier" FOR counter = 1 TO 3
END

Output

This is an unconditional statement modifier
This is an unconditional statement modifier
This is an unconditional statement modifier

Example 3
IConditional Statement Modifier

DECLARE INTEGER counter,

STRING my name

INPUT "Try and guess my name";my_ name FOR counter = 1 UNTIL my name = "VAX [

PRINT "You guessed it!"

Output
Try and guess my name? VAX PASCAL
Try and guess my name? VAX SCAN
Try and guess my name? VAX BASIC
You guessed it!

4-126

Statements and Functions

FORMATS

FORMAT$
The FORMATS$ function converts an expression to a formatted string.

Format

str-var = FORMATS$ (exp, str-exp)

Syntax Rules

The rules for building a format string are the same as those for printing
numbers with the PRINT USING statement. See the description of the

PRINT USING statement for more information.

Remarks

DIGITAL recommends that you use compile-time constant expressions for
string expressions whenever possible. When you do this, the VAX BASIC

compiler compiles the string at compilation time rather than at run time,
thus improving the performance of your code.

Statements and Functions

4-127

FORMATS

Example

DECLARE

STRING
INTEGER

num_exp =

result,

num_exp

12345

result = FORMATS (num_exp, "##, ###")
PRINT

result

Output
12,345

4-128

Statements and Functions

FREE

FREE
The FREE statement unlocks all records and buckets associated with a
specified channel.

Format
FREE

#chnl-exp

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number associated
with a file. It must be immediately preceded by a number sign (#).

Remarks

The file specified by chnl-exp must be open.

You cannot use the FREE statement with files not on disk.
3.

If there are no locked records or buckets on the specified channel, the
FREE statement has no effect and VAX BASIC does not signal an error.

The FREE statement does not change record buffers or pointers.
Moreover, the position of the record pointers is undefined.

After a FREE statement has executed, your program must execute a

GET or FIND statement before a PUT, UPDATE, or DELETE statement

can execute successfully.

Statements and Functions

4-129

FREE

Example

OPEN "CUST ACCT.DAT" FOR INPUT AS #3

INPUT "Enter customer record number to retrieve";cust_rec_num
FREE #3
GET #3

In this example, CUST_ACCT.DAT is opened for input. The FREE
statement unlocks all records associated with the specified channel
contained in the file. Once the FREE statement successfully executes, the
user can then obtain a record with either a FIND or GET statement.

4-130

Statements and Functions

FSP$

FSP$
The FSP$ function returns a string describing an open file on a specified
channel.

Format

str-var = FSP$ (chni-exp)

Syntax Rules

A file must be open on chnl-exp.

The FSP$ function must come immediately after the OPEN statement

for the file.

Remarks

Use the FSP$ function with files opened as ORGANIZATION
UNDEFINED. Then use multiple MAP statements to interpret the

returned data.
2.

See the VAX BASIC User Manual and the VMS Record Management
Services Manual for more information on FSP$ values.

NOTE

VAX BASIC supports the FSP$ function for compatibility
with BASIC-PLUS-2. DIGITAL recommends that you use a
USEROPEN routine to identify file characteristics.

Statements and Functions

4-131

FSP$

Example

10 MAP

(A)

STRING A = 32

MAP

(A)

BYTE org,

WORD mrs,

rat,

WORD bks bls,

LONG alg,

num_keys,LONG mrn

OPEN "STUDENT.DAT" FOR INPUT AS #1%,
ORGANIZATION UNDEFINED,
RECORDTYPE ANY, ACCESS READ
A = FSPS(1%)

PRINT "RMS organization = ";org
PRINT "RMS record attributes = ";rat

PRINT
PRINT
PRINT
PRINT
PRINT

"RMS maximum record size = ";mrs
"RMS allocation quantity = ";alq
"RMS bucket size = ";bks_bls
"Number of keys = ";num_keys
"RMS maximum record number = ";mrn

Output

RMS bucket size = 0
Number of keys = 0
RMS maximum record number

4-132

Statements and Functions

organization = 2
record attributes = 2
maximum record size = 5
allocation quantity = 1

RMS
RMS
RMS
RMS

&
&

FUNCTION

FUNCTION
The FUNCTION statement marks the beginning of a FUNCTION
subprogram and defines the subprogram’s parameters.

Format
FUNCTION

data-type func-name [ pass-mech ] [([ formal-param ],...) ]

[ statement |...

{ END FUNCTI[ON
exp ] }
FUNCTIONEND [ exp ]

pass-mech:

formal param:

{ BY DESC }
BY REF

[ unsubs-var

)

[ data-type ] J array-name ( [ lnt-const] , )t
\

[ = int-const ][ pass-mech ]
Syntax Rules

Func-name names the FUNCTION subprogram.

Func-name can be from 1 through 31 characters. The first character
must be an alphabetic character (A through Z). The remaining
characters, if present, can be any combination of letters, digits (0

through 9), dollar signs ($), periods (.), or underscores ( ).

Statements and Functions

4-133

FUNCTION

Data-type can be any VAX BASIC data type keyword or a data type

The data type that precedes the func-name specifies the data type of the

defined in the RECORD statement. Data type keywords, size, range,
and precision are listed in Table 1-2 in this manual.

value returned by the function.

Formal-param specifies the number and type of parameters for the
arguments the function expects to receive when invoked.
e

Empty parentheses indicate that the function has no parameters.

Data-type specifies the data type of a parameter. If you do not
specify a data type, parameters are of the default data type and size.
When you do specify a data type, all following parameters are of that
data type until you specify a new data type.

If the data type is STRING and the passing mechanism is by
to specify the
reference (BY REF), the =int-const clause allows you
length of the string.

Parameters defined in formal-param must agree in number and type
with the arguments specified in the function invocation. VAX BASIC
allows you to specify from 1 through 255 formal parameters.

Pass-mech specifies the parameter-passing mechanism by which the
FUNCTION subprogram receives arguments when invoked. A pass-mech
clause should be specified only when the FUNCTION subprogram is
being called by a non-BASIC program or when the FUNCTION receives
a string or array by reference.

A pass-mech clause outside the parentheses applies by default to all
function parameters. A pass-mech clause in the formal-param list
overrides the specified default and applies only to the immediately
preceding parameter.

4-134

Exp specifies the function result which supersedes any function
assignment. Exp must be compatible with the function’s data type.

Statements and Functions

FUNCTION

Remarks

The FUNCTION statement must be the first statement in the
FUNCTION subprogram.

Every FUNCTION statement must have a corresponding END
FUNCTION or FUNCTIONEND statement.

Any VAX BASIC statement except END, PICTURE, END PICTURE,
PROGRAM, END PROGRAM, SUB, SUBEND, END SUB, or SUBEXIT

can appear in a FUNCTION subprogram.
FUNCTION subprograms must be declared with the EXTERNAL

statement before your VAX BASIC program can invoke them.
FUNCTION subprograms receive parameters by reference or by
descriptor.

BY REF specifies that the function receives the argument’s address.

BY DESC specifies that the function receives the address of a VAX
BASIC descriptor. For information about the format of a VAX
BASIC descriptor for strings and arrays, see the VAX BASIC User
Manual; for information on other types of descriptors, see the VAX
Architecture Handbook.

By default, FUNCTION subprograms receive numeric unsubscripted
variables by reference, and all other parameters by descriptor. You can
override these defaults with a BY clause:

If you specify a string length with the =int-const clause, you must
also specify BY REF. If you specify BY REF and do not specify a
string length, VAX BASIC uses the default string length of 16.

If you specify array bounds, you must also specify BY REF.

All variables and data, except virtual arrays, COMMON areas, MAP
areas, and EXTERNAL variables, in a FUNCTION subprogram, are
local to the subprogram.

Statements and Functions

4-135

FUNCTION

VAX BASIC initializes local numeric variables to zero and local string
variables to the null string each time the FUNCTION subprogram is

invoked.
9.

If an exception is not handled within the FUNCTION subprogram,

control is transferred back to the main program that invoked the
function.

Example

FUNCTION REAL
IF

R <

sphere volume

THEN EXIT

sphere_volume = 4/3
END

4-136

FUNCTION

Statements and Functions

(REAL R)

FUNCTION

* PI *R **3.

FUNCTIONEND

FUNCTIONEND
The FUNCTIONEND statement is a synonym for the END FUNCTION
statement. See the END statement for more information.

Format

FUNCTIONEND

[exp]

Statements and Functions

4-137

FUNCTIONEXIT

FUNCTIONEXIT
The FUNCTIONEXIT statement is a synonym for the EXIT FUNCTION
statement. See the EXIT statement for more information.

Format
FUNCTIONEXIT

4-138

[exp]

Statements and Functions

GET

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 sequential,
relative, and indexed files.

Format

GET

#chnl-exp [, position-clause ] [ , lock-clause ]

position-clause:

lock-clause:

{ RFA rfa-exp

}

RECORD num-exp
KEY# key-clause
{ ALLOWallow-clause [, WAIT[ int-exp ] | }

WAIT [int-exp ]

REGARDLESS
NONE

allow-clause:

READ

MODIFY
key-clause:

int-exp1 rel-op key-exp

" EQ
rel-op:

)

GE
NXEQ
GT

. NX

)

Statements and Functions

4-139

GET

(int-exp2

)

str-exp

key-exp

fi decimal-exp

_quadword-exp |

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number
associated with a file. It must be immediately preceded by a number

sign (#).
2.

If you specify a lock-clause, it must follow the position-clause. If the
lock-clause precedes the position-clause VAX BASIC signals an error.

If you specify the REGARDLESS lock-clause, you cannot specify another
lock-clause in the same GET statement.

Remarks

Position-clause

Position-clause specifies the position of a record in a file. VAX BASIC
signals an error if you specify a position-clause and chnl-exp is not
associated with a disk file. If you do not specify a position-clause,
GET retrieves records sequentially. Sequential record access is valid
on all files.

The RFA position-clause allows you to randomly retrieve records by
specifying the record file address (RFA); you specify the disk address
of a record, and RMS retrieves the record at that address. All file
organizations can be accessed by RFA.

Rfa-exp in the RFA position-clause is an expression of the RFA data
type that specifies the record’s file address. An RFA expression must
be a variable of the RFA data type or the GETRFA function. Use the
GETRFA function to obtain the RFA of a record.

4-140

Statements and Functions

GET

The RECORD position-clause allows you to randomly retrieve

records in relative and sequential fixed files by specifying the record
number.

— Num-exp in the RECORD position-clause specifies the number of
the record you want to retrieve. It must be between 1 and the
number of the record with the highest number in the file.

— When you specify a RECORD clause, chnl-exp must be a channel
associated with an open relative or sequential fixed file.

The KEY position-clause allows you to randomly retrieve records in
indexed files by specifying a key of reference, a relational test, or a
key value.

An RFA value is valid only for the life of a specific version of a file.

If a new version of a file is created, the RFA values may change.
Attempting to access a record with an invalid RFA value results in a
run-time error.

Lock-clause

The type of lock you impose on a record remains in effect until
you explicitly unlock it with a FREE or UNLOCK statement, until
you close the file, or until you perform a GET, FIND, UPDATE
or DELETE on the same channel (unless you specified UNLOCK
EXPLICIT).

The REGARDLESS lock-clause specifies that the GET statement can
override lock checking and read a record locked by another program.

When you specify a REGARDLESS lock-clause, VAX BASIC does not
impose a lock on the retrieved record.

If you specify an ALLOW lock-clause the file associated with chnl-exp
must have been opened with the UNLOCK EXPLICIT clause or VAX
BASIC signals the error “Illegal record locking clause”.
The ALLOW allow-clause can be one of the following:

— ALLOW NONE denies access to the record. This means that
other access streams cannot retrieve the record unless they
bypass lock checking with the REGARDLESS clause.

Statements and Functions 4-141

GET

—

ALLOW READ provides read access to the record.
This means
that other access streams can retrieve the record,
but cannot
DELETE or UPDATE the record.

—

ALLOW MODIFY provides both read and write

access to the
record. This means that other access streams can
GET, FIND,

DELETE, or UPDATE the record.
*

If you do not open a file with ACCESS READ or
specify an ALLOW
lock-clause, locking is imposed as follows:
—

If the file associated with chnl-exp was opened
with UNLOCK
EXPLICIT, VAX BASIC imposes the ALLOW NONE
lock on the

retrieved record and the next GET or FIND statem
ent does not
unlock the previously locked record.

—

If the file associated with chnl-exp was not opened
with
UNLOCK EXPLICIT, VAX BASIC locks the retriev
ed record and
unlocks the previously locked record.

The WAIT lock-clause accepts an optional int-exp

. Int-exp represents
a timeout value in seconds. Int-exp must be from
0 through 255 or
VAX BASIC issues a warning message.

—

WAIT followed by a timeout value causes RMS

locked record for a given period of time.
=

WAIT followed by no timeout value indicates that
RMS should
wait indefinitely for the record to become availab
le.

—

If you specify a timeout value and the record
does not
become available within that period, VAX BASIC
signals
the the run-time error “Keyboard wait exhausted”
(ERR=15).
VMSSTATUS and RMSSTATUS then return RMS$_
TMO.
For more information on the RMSSTATUS and
VMSSTATUS
functions, see this chapter and the VAX BASIC
User Manual.
If you attempt to wait for a record that anothe
r user has
locked, and consequently that user attempts to wait
for the
record you have locked, a deadlock condition
occurs. When
a deadlock condition persists for a period of time
(as defined
by the SYSGEN parameter DEADLOCK_WAIT), RMS
signals
the error “RMS$_DEADLOCK” and VAX BASIC
signals the
error “Detected deadlock error while waiting
for GET or FIND”

—

(ERR=193).

4-142

to wait for a

Statements and Functions

GET

—

If you specify a WAIT clause followed by a timeout value that is
less than the SYSGEN parameter DEADLOCK_WAIT, then VAX
BASIC signals the error “Keyboard wait exhausted” (ERR=15)
even though a deadlock condition may exist.

—

If you specify a WAIT clause on a GET operation to a unit device,

the timeout value indicates how long to wait for the input to
complete. This is equivalent to the WAIT statement.

Key-clause

In a key-clause, int-expl is the target key of reference. It must be a
integer value in the range of zero through the highest-numbered key
for the file. The primary key is #0, the first alternate key is #1, the
second alternate key is #2, and so on. Int-expl must be preceded by
a number sign (#) or VAX BASIC signals an error.

When you specify a key clause, chnl-exp must be a channel
associated with an open indexed file.

Rel-op

Rel-op specifies how key-exp is to be compared with int-expl in the
key-clause.

EQ means “equal to”

—

NXEQ means “next or equal to”

—

GE means “greater than or equal to” (a synonym for NXEQ)

—

NX means “next”

—

GT means “greater than” (a synonym for NX)

With an exact key match (EQ), a successful GET operation retrieves
the first record in the file that equals the key value specified
in key-exp. If the key expression is a str-exp whose length is
less than the key length, characters specified by the str-exp are
matched approximately rather than exactly. That is, if you specify
a string expression “ABC” and the key length is six characters,
VAX BASIC matches the first record that begins with ABC. If you
specify “ABCABC”, VAX BASIC matches only a record with the key
“ABCABC”. If no match is possible, VAX BASIC signals the error
“Record not found” (ERR=155).

Statements and Functions

4-143

GET

If you specify a next or equal to key match (NXEQ), a successful

GET operation retrieves the first record that equals the key value

specified in key-exp. If no exact match exists, VAX BASIC retrieves
the next record in the key sort order. If the keys are in ascending
order, the next record will have a greater key value. If the keys are
in descending order, the next record will have a lesser key value.

If you specify a greater than key match (GT), a successful GET
operation retrieves the first record with a value greater than key-exp.

If no such record exists, VAX BASIC signals the error “Record not
found” (ERR=155).
*

If you specify a next key match (NX), a successful GET operation
retrieves the first record that follows the key expression in the key

sort order. If no such record exists, VAX BASIC signals the error
“Record not found” (ERR=155).
*

If you specify a greater than or equal to key match (GE), the
behavior is identical to that of next or equal to (NXEQ). Likewise,

the behavior of GT is identical to NX. However, the use of GE in a

descending key file may be confusing, because GE will retrieve the
next record in the key sort order but the next record will have a

lesser key value. For this reason, DIGITAL recommends that you
use NXEQ in new program development, especially if you are using
descending key files.

Key-exp
®

Int-exp2 in the key clause specifies an integer value to be compared

with the key value of a record.

Str-exp in the key clause specifies a string value to be compared with
the key value of a record. The string expression can contain fewer
characters than the key of the record you want to retrieve but it
cannot be a null string.

Decimal-exp in the key clause specifies a packed decimal value to be
compared with the key value of a record.

*
6.

Quadword-exp in the key clause specifies a RECORD or GROUP
exactly 8 bytes long to be compared with the key value of a record.

The file specified by chAnl-exp must be opened with ACCESS READ or
ACCESS MODIFY or SCRATCH before your program can execute a GET
statement. The default ACCESS clause is MODIFY.

4-144

Statements and Functions

GET

If the last I/O operation was a successful FIND operation, a sequential
GET operation retrieves the current record located by the FIND
operation and sets the next record pointer to the record logically
succeeding the pointer.

If the last I/0 operation was not a FIND operation, a sequential

GET operation retrieves the next record and sets the record logically
succeeding the record pointer to the current record.

For sequential files, a sequential GET operation retrieves the next
record in the file.

TFor relative files, a sequential GET operation retrieves the record
with the next higher cell number.

For indexed files, a sequential GET operation retrieves the next
record in the current key of reference.

A successful random GET operation by RFA or by record retrieves the
record specified by rfa-exp or int-exp.
10. A successful random GET operation by key retrieves the first record

whose key satisfies the key-clause comparison.
11.

A successful random GET operation by RFA, record, or key sets the
value of the current record pointer to the record just read. The next
record pointer is set to the next logical record.

12. An unsuccessful GET operation leaves the record pointers and the record

buffer in an undefined state.
13. If the retrieved record is smaller than the receiving buffer, VAX BASIC

fills the remaining buffer space with nulls.
14. If the retrieved record is larger than the receiving buffer, VAX BASIC

truncates the record and signals an error.
15. A successful GET operation sets the value of the RECOUNT variable to

the number of bytes transferred from the file to the record buffer.

16. You should not use a GET statement on a terminal-format or virtual

array file.

Statements and Functions

4-145

GET

Example

DECLARE
MAP

LONG rec-num

(CUSREC)

WORD

cus_num

STRING cus_nam =

OPEN

"CUS_ACCT.DAT"
RELATIVE

MAP
INPUT

FIXED,

ACCESS

20,

cus_city =

10,

cus_zip

MODIFY,

record number would you

RECORD REC_NUM,

"The

customer’s

number

"The

customer’s

name

"The

customer’s

address

"The

customer’s

city

";cus_city

"The

customer’s

zip

code

END

Statements and Functions

to view";rec
num

REGARDLESS

CLOSE #1

4-146

cus_add =

CUSREC

"Which

GET #1,

20,

FOR INPUT AS

is ";CUS NUM

";cus_nam

";cus add

";cus_zip

GETRFA

GETRFA
The GETRFA function returns the record’s file address (RFA) of the
last
record accessed in an RMS file open on a specified channel.

Format

rfa-var = GETRFA (chnl-exp)

Syntax Rules

Rfa-var is a variable of the RFA data type.
Chnl-exp is the channel number of an open RMS file. You cannot include
a number sign in the channel expression.
You must access a record in the file with a GET, FIND, or PUT

statement before using the GETRFA function, or VAX BASIC signals
“No current record” (ERR=131).

Remarks

There must be a file open on the specified chnl-exp or VAX BASIC
signals an error.
You can use the GETRFA function with RMS sequential, relative,
indexed, and block I/0O files.
The RFA value returned by the GETRFA function can be used only

for
assignments to and comparisons with other variables of the RFA data

type. Comparisons are limited to equal to (=) and not equal to
(<>)

relational operations.

RFA values cannot be printed or used for any arithmetic operations.

Statements and Functions

4-147

GETRFA

Example

DECLARE RFA RARRAY
(1l TO 100)

FOR I%$ = 1% TO 100%
PUT #1

R_ARRAY (I%)
NEXT

4-148

= GETRFA(1)

Statements and Functions

GOSUB

GOSUB
The GOSUB statement transfers control to a specified line number or label
and stores the location of the GOSUB statement for eventual return from
the subroutine.

Format

{ GO SUB
GOSUB

} farget

Syntax Rules
Target must refer to an existing line number or label in the same
program unit as the GOSUB statement or VAX BASIC signals an error.
Target cannot be inside a block structure such as a FOR...NEXT,
WHILE, or UNTIL loop or a multi-line function definition unless the
GOSUB statement is also within that block or function definition.

Remarks
You can use the GOSUB statement from within protected regions of a
WHEN block. GOSUB statements can also contain protected regions
themselves.

If you fail to handle an exception that occurs while a statement
contained in the body of a subroutine is executing, the exception is

handled by the default error handler. The exception is not handled
by any WHEN block surrounding the statement that invoked the
subroutine.

Statements and Functions

4-149

GOSUB

Example

GOSUB

subroutin1
e

subroutine 1:

RETURN

4-150

Statements and Functions

GOTO

GOTO
The GOTO statement transfers control to a specified line number or label.

Format

{ GO TO
GOTO

} target

Syntax Rules

Target must refer to an existing line number or label in the same
program unit as the GOTO statement or VAX BASIC signals an error.

Target cannot be inside a block structure such as a FOR...NEXT,
WHILE, or UNTIL loop or a multi-line function definition unless the

GOTO statement is also inside that loop or function definition.

Remarks

You can specify the GOTO statement inside a WHEN block if the target

is in the same protected region, an outer level protected region, or in a
nonprotected region.
You cannot specify the GOTO statement inside a WHEN block if the

target already resides in another protected region that does not contain
the innermost current protected region.

Statements and Functions

4-151

GOTO

Example

IF
END

answer

THEN

GOTO

0
done

done:
EXIT

4-152

PROGRAM

Statements and Functions

HANDLER

HANDLER
The handler statement marks the beginning of a detached handler.

Format

HANDLER

handler-name

Syntax Rules
Handler-name must be a valid VAX BASIC identifier and must not be the
same as any label, DEF, DEF*, SUB, FUNCTION or PICTURE name.

Remarks

A detached handler must be delimited by a HANDLER statement and

A detached handler can be used only with VAX BASIC’s
exception-handling mechanism. If you attempt to branch into a
detached handler for example with the GOTO statement, VAX BASIC

an END HANDLER statement.

signals a compile-time error.

To exit from a detached handler, you must use either END HANDLER,
EXIT HANDLER, RETRY or CONTINUE. See these statements for
more information.

Within a handler, VAX BASIC allows you to specify user-defined function
references and procedure invocations as well as VAX BASIC statements.

Statements and Functions

4-153

HANDLER

The following statements are illegal inside a handler:

EXIT PROGRAM, FUNCTION, SUB, or PICTURE

GOTO to a target outside the handler
GOSUB to a target outside the handler
ON ERROR
RESUME

Example

WHEN

END

ERROR

USE

err handler

WHEN

HANDLER
IF

err handler

ERR

THEN

RETRY
ELSE

END
END

4-154

EXIT

HANDLER

Statements and Functions

HANDLER

"Insufficient

data"

IF
The IF statement evaluates a conditional expression and transfers program
control depending on the resulting value.

Format
Conditional

cond-exp THEN statement... [ ELSE statement...]

END IF
Statement Modifier

statement IF cond-exp

Syntax Rules

Conditional

Cond-exp can be any valid conditional expression.

All statements between the THEN keyword and the next ELSE, line

number, or END IF are part of the THEN clause. All statements
between the keyword ELSE and the next line number or END IF are
part of the ELSE clause.

VAX BASIC assumes a GOTO statement when the keyword ELSE is

followed by a line number. When the target of a GOTO statement is
a label, the keyword GOTO is required. The use of this syntax is not
recommended for new program development.

The END IF statement terminates the most recent unterminated IF
statement.

A new line number terminates all unterminated IF statements.

Statements and Functions

4-155

Statement Modifier
*

IF can modify any executable statement except a block statement

Cond-exp can be any valid conditional expression.

such as FOR, WHILE, UNTIL, or SELECT.

Remarks
1.

Conditional

VAX BASIC evaluates the conditional expression for truth or falsity.

If true (nonzero), VAX BASIC executes the THEN clause. If false
(zero), VAX BASIC skips the THEN clause and executes the ELSE
clause, if present.

The keyword NEXT cannot be in a THEN or ELSE clause unless

the FOR or WHILE statement associated with the keyword NEXT is

also part of the THEN or ELSE clause.

If a THEN or ELSE clause contains a block statement such as a
FOR, SELECT, UNTIL, or WHILE, then a corresponding block

termination statement such as a NEXT or END, must appear in the

same THEN or ELSE clause.

IF statements can be nested to 12 levels.

Any executable statement is valid in the THEN or ELSE clause,
including another IF statement. You can include any number of
statements in either clause.

Execution continues at the statement following the END IF or ELSE
clause. If the statement does not contain an ELSE clause, execution

continues at the next statement after the THEN clause.

Statement Modifier
*

VAX BASIC executes the statement only if the conditional expression
is true (nonzero).

4-156

Statements and Functions

Example

Update_flag =

True

THEN

Weekly salary

UPDATE
IF

= New rate

40.0

Dept

New dept

THEN

GET

#1,

KEY #1 EQ New dept

Dept_employees

UPDATE
END

Dept employees

"Update

"Skipping

complete"

ELSE

END

update

for

this

employee"

Statements and Functions

4-157

INKEY$

INKEY$
The INKEY$ function reads a single keystroke from a terminal opened on a
specified channel and returns the typed character.

Format

string-var = INKEY$ (chnl-exp [ ,WAIT [ int-exp | ])

Syntax Rules
Chnl-exp must be the channel number of a terminal.

Int-exp represents the timeout value in seconds and must be from 0
through 255. Values beyond this range cause VAX BASIC to signal a
compile-time or run-time error.

Remarks
Before using the INKEY$ function, specify the DCL command SET
TERMINAL/HOSTSYNC. This command controls whether the system
can synchronize the flow of input from the terminal. If you specify
SET TERMINAL/HOSTSYNC, the system generates a CTRL/S or a
CTRL/Q to enable or disable the reception of input. This prevents the
typeahead buffer from overflowing. If you do not use this command
and the typeahead buffer overflows, VAX BASIC signals the error “Data
overflow” (ERR=289).

Before using the INKEY$ function on a VT200-series terminal, set your

terminal to VT200 mode with 7 bit controls.

4-158

Statements and Functions

INKEY$

Before using the INKEY$ function, either your terminal or VMS, but
not both, must enable screen wrapping. To enable terminal screen

wrapping, use the Set-Up key on your terminal’s keyboard to set the
terminal to Auto Wrap. Then disable VMS screen wrapping by entering

the DCL SET TERMINAL /NOWRAP command. To enable VMS screen
wrapping, enter the DCL SET TERMINAL/WRAP command. Then
disable terminal screen wrapping by using the Set-Up key to set the
terminal to No Auto Wrap.

The INKEY$ function behaves as if the terminal were in
APPLICATION_KEYPAD mode.

If the channel is not open, VAX BASIC signals the error “I/O, channel
not open” (ERR=9). If a file or a device other than a terminal is open on

the channel, VAX BASIC signals the error “Illegal operation” (ERR=141).
The optional WAIT clause specifies a timeout interval during which the

command will await terminal input. If you specify WAIT int-exp, the
timeout period will be the specified number of seconds. If you specify a

WAIT clause followed by no timeout value, VAX BASIC waits indefinitely
for terminal input.

VAX BASIC always examines the typeahead buffer first and retrieves
the next keystroke in the buffer if the buffer is not empty. If the
typeahead buffer is empty and an optional WAIT clause was specified,
VAX BASIC waits for a keystroke to be typed for the specified timeout
interval (indefinitely if WAIT was specified with no timeout interval).
If the typeahead buffer is empty, and the waiting period is either not
specified or expired, VAX BASIC returns the error message “Keyboard
wait exhausted” (ERR=15).

The escape character (ASCII code 27) is not valid as INKEY$ input. If
you enter an escape character, normal program execution resumes when
the INKEY$ times out. Without a specified timeout value, the program
execution cannot resume without error.

VAX BASIC returns the error message “Keyboard wait exhausted”

(ERR=15) when any key is pressed after the escape character if no
timeout is specified or if the specified timeout has not yet occurred.
10. INKEY$ turns off all line editing. As a result, control of all line-editing

characters and the arrow keys is passed back to the user.

Statements and Functions

4-159

INKEY$

11. Non-editing characters normally intercepted by the VMS terminal
driver are not returned. These include the CTRL/C, CTRL/Y, CTRL/S,

CTRLY/O characters (unless CTRL/C trapping is enabled). They are
handled by the device driver just as in normal input.

12. All ASCII characters are returned in a 1-byte string.
13. All keystrokes that result in an escape sequence are translated to
mnemonic strings based on the following key names:

PF1-PF4

4-160

EKEI1-E6

PF7-F20

LEFT

RIGHT

DOWN

KPO to KP9

KP-

KP,

KP.

ENTER

Statements and Functions

INKEY$

Example

PROGRAM

Inkey_ demo

DECLARE

STRING KEYSTROKE

Inkey Loop:

WHILE

S
(0%, WAIT)
= INKEY

KEYSTROKE

SELECT KEYSTROKE
CASE

r26'C

PRINT "CTRL/Z to exitTM
EXIT
CASE

Inkey Loop

CR,LF,VT,FF

"Line terminatorTM
"PF4"
PRINT "P function key"

PRINT
CASE
CASE

"PF1"
"El"

IIF7II

“E6"’

I|F9Il,

llFlO"

IIFZOII

function key"

CASE
CASE

PRINT "VT200
"KPO" TO "KP9"
PRINT "Application keypad key"
<

"Control

character"

’127'C

CASE

PRINT
CASE ELSE

"<DEL>"

PRINT ’‘Character is "’; KEYSTROKE;

END

'"'/

SELECT

END

PROGRAM

Statements and Functions

4-161

INPUT

INPUT
The INPUT statement assigns values from your terminal or from a
terminal-format file to program variables.

Format

INPUT

[#chnl-exp, ] [ str-const1 { : }Jvart [ { M str-const2
{ . }]
var2 |...

Syntax Rules

You must supply an argument to the INPUT statement. Otherwise, VAX
BASIC signals an error message.

Chnl-exp is a numeric expression that specifies a channel number
associated with a file. It must be immediately preceded by a number

You can include more than one string constant in an INPUT statement.

sign (#).

Str-const1 is issued for str-varl, str-const2 for str-var2, and so on.
4.

Str-varl and str-var2 cannot be a DEF function names unless the

INPUT statement is inside the multi-line DEF that defines the function.

The separator (comma or semicolon) that directly follows str-varl and

str-var2 has no formatting effect. VAX BASIC always advances
to a new

line when you terminate input with a carriage return.
6.

The separator that directly follows str-constl and str-const2, determines
where the question mark prompt (if requested) is displayed and where
the cursor is positioned for input.

A comma causes VAX BASIC to skip to the next print zone and display
thé question mark unless a SET NO PROMPT statement has been
executed, as follows.

4-162

Statements and Functions

INPUT

DECLARE STRING your name
INPUT "What is your name",your_ name

Output
What is your name

A semicolon causes VAX BASIC to display the question mark next to
str-const unless a SET NO PROMPT statement has been executed. For
example:

DECLARE STRING your name

INPUT "What is your name";your_ name

Output
What is your name?

VAX BASIC always advances to a new line when you terminate input
with a carriage return.

Remarks

If you do not specify a channel, the default chnl-exp is #0 (the controlling
terminal). If a chnl-exp is specified, a file must be open on that channel
with ACCESS READ or MODIFY before the INPUT statement can
execute.

If input comes from a terminal, VAX BASIC displays the contents of
str-constl, if present. If the terminal is open on channel #0, VAX BASIC
also displays a question mark (?).

You can disable the question mark prompt by using the SET NO
PROMPT statement. See the SET PROMPT statement for more
information.

When VAX BASIC receives a line terminator or a complete record, it
checks each data element for correct data type and range limits, then
assigns the values to the corresponding variables.

If you specify a string variable to receive the input text, and the user
enters an unquoted string in response to the prompt, VAX BASIC
ignores the string’s leading and trailing spaces and tabs. An unquoted
string cannot contain any commas.

Statements and Functions

4-163

INPUT

If there is not enough data in the current record or line to satisfy
the
variable list, VAX BASIC takes one of the following actions:

If the input device is a terminal and you have not specified SET
NO PROMPT, VAX BASIC repeats the question mark but not the

sir-const, on a new line until sufficient data is entered.

If the input device is not a terminal, VAX BASIC signals “Not

enough data in record” (ERR=59).

If there are more data items than variables in the INPUT response,
VAX
BASIC ignores the excess.

If there is an error while data is being converted or assigned (for
example, string data being assigned to a numeric variable), VAX BASIC

takes one of the following actions:
*

If there is no error handler in effect and the input device is a
terminal, VAX BASIC signals a warning, reexecutes the INPUT
statement, and displays str-const and the input prompt.

If there is an error handler in effect and the input device is not
a
terminal, VAX BASIC signals “Illegal number” (ERR=52) or “Data

format error” (ERR=50).
9.

When a RETRY, CONTINUE or RESUME statement transfers control

to an INPUT statement, the INPUT statement retrieves a new

line regardless of any data left in the previous record or line.

record or

10. After a successful INPUT statement, the RECOUNT variable contains

the number of characters transferred from the file or terminal to the
record buffer.

11. If you terminate input text with CTRL/Z, VAX BASIC assigns the

value to the variable and signals “End of file on device” (ERR=11)
when the next terminal input statement executes. If you are in the
BASIC environment and there is no subsequent INPUT, INPUT LINE,
or LINPUT statement in the program, the CTRI/Z is passed to VAX

BASIC as a signal to exit the BASIC environment. VAX BASIC signals

“Unsaved changes have been made, CTRL/Z or EXIT to exit” if you have

made changes to your program or are running a program that has
never
been saved. If you have not made changes, VAX BASIC exits from the
BASIC environment and does not signal an error.

4-164

Statements and Functions

INPUT

Example

DECLARE

STRING var 1,

INTEGER var
2

INPUT

"The

first

variable";var
1,

"The

second variable";var 2

Output
The

first

The

second wvariable?

wvariable?

name
4

Statements and Functions

4-165

INPUT LINE

INPUT LINE
The INPUT LINE statement assigns a string value (including the line
terminator in some cases) from a terminal or terminal-format file to a string
variable.

Format

INPUT LINE [#chnl-exp, ] [ str-const1 { : } ] str-vart

[ statement ]...[ { ] str-const2{ : } ] str-var2 ...
Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number
associated with a file. It must be immediately preceded by a number
sign (#).

2.
3.

Str-varl or str-var2 cannot be a DEF function name unless the INPUT
LINE statement is inside the multi-line DEF that defines the function.
You can include more than 1 string constant in an INPUT LINE
statement. Str-constl is issued for str-varl, str-const2 for str-var2, and
SO on.

The separator (comma or semicolon) that directly follows str-varl and
str-var2 has no formatting effect. VAX BASIC always advances to a new
line when you terminate input with a carriage return.

The separator that directly follows str-constl and str-const2 determines
where the question mark (if requested) is displayed and where the
cursor is positioned for input. Specifically:

A comma causes VAX BASIC to skip to the next print zone and
display the question mark unless a SET NO PROMPT statement has
been executed. For example:

4-166

Statements and Functions

INPUT LINE

DECLARE STRING your_ name
INPUT LINE "Name",your name

Output
?

Name

A semicolon causes VAX BASIC to display the question mark next to
str-const unless a SET NO PROMPT statement has been executed.
For example:
DECLARE

STRING your name

INPUT LINE "Name";your_ name

Output
Name?

VAX BASIC always advances to a new line when you terminate input
with a carriage return.

Remarks
The default chnl-exp is #0 (the controlling terminal). If a channel is
specified, a file must be open on that channel with ACCESS READ

before the INPUT LINE statement can execute.

VAX BASIC signals an error if the INPUT LINE statement has no
argument.

If input comes from a terminal, VAX BASIC displays the contents of
str-constl, if present. If the terminal is open on channel #0, VAX BASIC
also displays a question mark (?).

You can disable the question mark prompt by using the SET NO
PROMPT statement. See the SET PROMPT statement for more

information.

The INPUT LINE statement assigns all input characters to string
variables. In addition, the INPUT LINE statement places the following

line terminator characters in the assigned string if they are part of the
string value.

Statements and Functions

4—167

INPUT LINE

Hex code

ASCII char

Character name

Line Feed

Vertical Tab

Form Feed

Carriage Return

0DOA

CRLF

Carriage Return/Line Feed

ESC

Escape

Any other line terminator, such as CRTL/D and CTRL/F when
editing is turned off, is not included in the assigned string.

line

When a RETRY, CONTINUE or RESUME statement transfers control
an INPUT LINE statement, the INPUT LINE statement retrieves

record or line regardless of any data left in the previous record or

a new
line.

After a successful INPUT LINE statement, the RECOUNT variable

contains the number of characters transferred from the file or
terminal
to the record buffer.

If you terminate input text with CTRL/Z, VAX BASIC assigns
the
value to the variable and signals “End of file on device” (ERR=11) when

the next terminal input statement executes. If you are in the BASIC
environment and there is no next INPUT, INPUT LINE, or LINPUT
statement in the program, the CTRL/Z is passed to VAX BASIC

as a

signal to exit the BASIC environment. VAX BASIC signals “Unsaved
changes have been made, CTRL/Z or EXIT to exit” if you have made
changes to your program. If you have not made changes, VAX BASIC
exits from the BASIC environment and does not signal an error.

Example

DECLARE

4-168

STRING

Z,N,record string

INPUT

LINE

"Type

INPUT

LINE

#4%,

two

words",

Z$,’Type

record string$

Statements and Functions

your

name’;N$

INSTR

INSTR
The INSTR function searches for a substring within a string. It returns the
position of the substring’s starting character.

Format
int-var = INSTR (int-exp, str-exp1, str-exp2)

Syntax Rules

Int-exp specifies the character position in the main string at which VAX

BASIC starts the search.

Str-expl specifies the main string.

Str-exp2 specifies the substring.

The INSTR function searches str-expl, the main string, for the first
occurrence of a substring, str-exp2, and returns the position of the

Remarks

substring’s first character.

INSTR returns the character position in the main string at which VAX
BASIC finds the substring, except in the following situations:

If only the substring is null, and if int-exp is less than or equal to

zero, INSTR returns a value of 1.

If only the substring is null, and if int-exp is equal to or greater than

1 and less than or equal to the length of the main string, INSTR
returns the value of int-exp.

If only the substring is null, and if int-exp is greater than the length
of the main string, INSTR returns the main string’s length plus 1.

Statements and Functions

4-169

INSTR

If the substring is not null, and if ini-exp is greater than the length
of the main string, INSTR returns a value of zero.

If only the main string is null, INSTR returns a value of zero.

If both the main string and the substring are null, INSTR returns
a l.

If VAX BASIC cannot find the substring, INSTR returns a value of zero.

1If int-exp does not equal 1, VAX BASIC still counts from the beginning
of the main string to calculate the starting position of the substring.
That is, VAX BASIC counts character positions starting at position 1,
regardless of where you specify the start of the search. For example,
if you specify 10 as the start of the search and VAX BASIC finds the
substring at position 15, INSTR returns the value 15.

If int-exp is less than 1, VAX BASIC assumes a starting position of 1.

If you specify a floating-point expression for inf-exp, VAX BASIC
truncates it to an integer of the default size.

Example

DECLARE STRING alpha,
INTEGER
alpha

result =
PRINT

"ABCDEF"

INSTR(l,alpha, "DEF")

result

Output
4

4-170

result

Statements and Functions

INT

INT
The INT function returns the floating-point value of the largest whole
number less than or equal to a specified expression.

Format

real-var = INT (real-exp)

Syntax Rules

VAX BASIC expects the argument of the INT function to be a real
expression. When the argument is a real expression, VAX BASIC returns
a value of the same floating-point size. When the argument is not a real
expression, VAX BASIC converts the argument to the default floating-point
size and returns a value of the default floating-point size.

Remarks

If real-exp is negative, VAX BASIC returns the largest whole number less
than or equal to real-exp. For example, INT(-5.3) is 6.

Statements and Functions

4-171

INT

Examples

Example 1
DECLARE

SINGLE

any _num =
result
PRINT

any num,

result

6.667
INT(any_ num)

result

Output
6

Example 2
!This example contrasts
DECLARE

SINGLE

test_num =

INT and FIX functions

-32.7

"INT OF

-32.7

IS:

INT(test_ num)

"FIX OF

-32.7

IS:

FIX(test_num)

Output
INT

4-172

the

test num

-32.7

IS:

-33

FIX OF

-32.7

IS:

-32

Statements and Functions

INTEGER

INTEGER
The INTEGER function converts a numeric expression or numeric string to
a specified or default INTEGER data type.

Format
", BYTE 1
int-var= INTEGER (exp | , WORD | )

L, LONG

Syntax Rules

Exp can be either numeric or string. A string expression can contain the
ASCII digits 0 through 9, a plus sign (+), or a minus sign (-).

Remarks

VAX BASIC evaluates exp, then converts it to the specified INTEGER
size. If you do not specify a size, VAX BASIC uses the default INTEGER
size.

Ifexp is a string, VAX BASIC ignores leading and trailing spaces and
tabs.

The INTEGER function returns a value of zero when a string argument
contains only spaces and tabs, or when it is null.

The INTEGER function truncates the decimal portion of REAL and
DECIMAL numbers.

Statements and Functions

4-173

INTEGER

Example

INPUT

"Enter

INTEGER(F_P,

floating-point

number";F
P

WORD)

Output
Enter

floating-point

4-174

Statements and Functions

number?

76.99

ITERATE

ITERATE
The ITERATE statement allows you to explicitly reexecute a loop.

Format

ITERATE

[label]

Syntax Rules

Label is the label of the first statement of a FOR...NEXT, WHILE, or
UNTIL loop.

Label must conform to the rules for naming variables.

ITERATE is equivalent to an unconditional branch to the current loop’s
NEXT statement. If you supply a label, ITERATE transfers control to
the NEXT statement in the specified loop. If you do not supply a label,

Remarks

ITERATE transfers control to the current loop’s NEXT statement.

The ITERATE statement can be used only within a FOR... NEXT,
WHILE, or UNTIL loop.

Statements and Functions

4-175

ITERATE

Example

WHEN ERROR

Date loop:

WHILE

GET #1
ITERATE

Date_loop

ITERATE

Date loop

IF Month$

ITERATE

Date_loop

Item$

USE
IF

ERR

THEN

CONTINUE DONE
ELSE

EXIT HANDLER
END

END WHEN

Done:

4-176

END

Statements and Functions

Day$

Year$

Today$

<>
<>

This

month$

This_ year$

KILL

KILL
The KILL statement deletes a disk file, removes the file’s directory entry,
and releases the file’s storage space.

Format
KILL

file-spec

Syntax Rules

File-spec can be a quoted string constant, a string variable, or a string
expression. It cannot be an unquoted string constant.

Remarks

The KILL statement marks a file for deletion but does not delete the file

until all users have closed it.
2.

If you do not specify a complete file specification, VAX BASIC uses the
default device and directory. If you do not specify a file version, VAX
BASIC deletes the highest version of the file.

The file must exist, or VAX BASIC signals an error.

You can delete a file in another directory if you have access to that

directory and privilege to delete the file.

Example

KILL

"TEMP.DAT"

Statements and Functions

4-177

LBOUND

LBOUND
The LBOUND function returns the lower bounds of a compile-time or

run-time dimensioned array.

Format

num-var = LBOUND (array-name [, num-exp ])

Syntax Rules

Array-name must specify an array that has been either explicitly or
implicitly declared.

Nume-exp specifies the number of the dimension for which you have
requested the lower bound.

Remarks

1.
2.

If you do not specify a dimension, VAX BASIC automatically returns the
lower bounds of the first dimension.
If you specify a numeric expression that is less than or equal to zero,
VAX BASIC signals an error.

4-178

If you specify a numeric expression that exceeds the number of
dimensions, VAX BASIC signals an error.

Statements and Functions

LBOUND

Example

DECLARE

INTEGER CONSTANT B =

DIM A (B)

account num =

FOR dim num = LBOUND
A(dim_num)

(A)

TO 5

= account_num

account num = account num + 1
PRINT A(dim_ num)

NEXT dim num

oOndbd W

Output

Statements and Functions

4-179

LEFTS

LEFTS
The LEFT$ function extracts a specified substring from a string’s left side,
leaving the main string unchanged.

Format

str-var = LEFT[$] (str-exp, int-exp)

Syntax Rules

Int-exp specifies the number of characters to be extracted from the left

side of sir-exp.

If you specify a floating-point expression for int-exp, VAX BASIC
truncates it to an integer of the default size.

Remarks

The LEFT$ function extracts a substring from the left of the specified

str-exp and stores it in str-var.

2.
3.

If int-exp is less than 1, LEFT$ returns a null string.
If int-exp is greater than the length of str-exp, LEFT$ returns the entire

string.

4-180

Statements and Functions

LEFTS

Example

DECLARE STRING sub_string,
main_ string =

main_string

"1234567"

sub string = LEFTS$ (main_string,
PRINT

sub_string

Output
1234

Statements and Functions

4-181

LEN

LEN
The LEN function returns an integer value equal to the number of

characters in a specified string.

Format
int-var = LEN (str-exp)

Syntax Rules

None.

Remarks

If str-exp is null, LEN returns a value of zero.
The length of str-exp includes leading, trailing, and embedded blanks.

Tabs in str-exp are treated as a single space.
3.

4-182

The value returned by the LEN function is a LONG integer.

Statements and Functions

LEN

Example

DECLARE

STRING alpha,

INTEGER length
alpha =
length =
PRINT

"ABCDEFG"
LEN(alpha)

length

Output
7

Statements and Functions

4-183

LET

LET
The LET statement assigns a value to one or more variables.

Format
[LET]

var,... =exp

Syntax Rules

Var cannot be a DEF or FUNCTION name unless the LET statement

occurs inside that DEF block or in that FUNCTION subprogram.

The keyword LET is optional.

You cannot assign string data to a numeric variable or unquoted numeric

Remarks

data to a string variable.

The value assigned to a numeric variable is converted to the variable’s

data type. For example, if you assign a floating-point value to an integer
variable, VAX BASIC truncates the value to an integer.
3.

For dynamic strings, the destination string’s length equals the source

string’s length.

When you assign a value to a fixed-length string variable (a variable

declared in a COMMON, MAP, or RECORD statement), the value is
left-justified and padded with spaces or truncated to match the length of
the string variable.

4-184

Statements and Functions

LET

Example

DECLARE

STRING
INTEGER

LET

alpha

LET

length =

alpha,

length

"ABCDEFG"

LEN (alpha)

length

Output
7

Statements and Functions

4-185

LINPUT

LINPUT
The LINPUT statement assigns a string value, without line terminators,
from a terminal or terminal-format file to a string variable.

Format

LINPUT [#chnl-exp, ] [ str-const1 { : } ] str-var1 [ { : } [ str-constz{ : } ]
str-var2 |...

Syntax Rules
Chnl-exp is a numeric expression that specifies a channel number
associated with a file. It must be immediately preceded by a number
sign (#).

Str-varl and str-var2 cannot be DEF function names unless the LINPUT
statement is inside the multi-line DEF that defines the function.
You can include more than one string constant in a LINPUT statement.
Str-constl is issued for str-varl, str-const2 for str-var2, and so on.

The separator (comma or semicolon) that directly follows str-varl and
str-var2 has no formatting effect. VAX BASIC always advances to a new
line when you terminate input with a carriage return.

The separator character that directly follows str-constl and sir-const2
determines where the question mark (if requested) is displayed and
where the cursor is positioned for input.

A comma causes VAX BASIC to skip to the next print zone to display
the question mark unless a SET NO PROMPT statement has been
executed. For example:
DECLARE
LINPUT

4-186

STRING your name
"Name",your name

Statements and Functions

LINPUT

Output
Name

A semicolon causes VAX BASIC to display the question mark next to

str-const unless a SET NO PROMPT statement has been executed.
For example:
DECLARE

LINPUT

STRING your name

"What

your name";your name

Output
What

your

name?

VAX BASIC always advances to a new line when you terminate input
with a carriage return.

Remarks

The default chnl-exp is #0 (the controlling terminal). If you specify a
channel, the file associated with that channel must have been opened
with ACCESS READ or MODIFY.

VAX BASIC signals an error if the LINPUT statement has no argument.

If input comes from a terminal, VAX BASIC displays the contents of
str-constl, if present. If the terminal is open on channel #0, VAX BASIC
also displays a question mark (?).

You can disable the question mark prompt by using the SET NO

PROMPT statement. See the SET PROMPT statement for more
information.

The LINPUT statement assigns all characters, except any line
terminator’s to str-varl and str-var2. Single and double quotation
marks, commas, tabs, leading and trailing spaces, or other special
characters in the string are part of the data.
If the RETRY, CONTINUE or RESUME statement transfers control to
a LINPUT statement, the LINPUT statement retrieves a new record
regardless of any data left in the previous record.

Statements and Functions

4-187

LINPUT

After a successful LINPUT statement, the RECOUNT variable contains
the number of bytes transferred from the file or terminal to the record

buffer.
8.

If you terminate input text with CTRL/Z, VAX BASIC assigns the
value to the variable and signals “End of file on device” (ERR=11) when

the next terminal input statement executes. If you are in the BASIC
environment and there is no next INPUT, INPUT LINE, or LINPUT
statement in the program, the CTRL/Z is passed to VAX BASIC as a

signal to exit the BASIC environment.

Example

DECLARE

LINPUT

STRING last name

"ENTER YOUR LAST NAME";Last name

LINPUT #2%,

4-188

Last_name

Statements and Functions

LOC

LOC
The LOC function returns a longword integer specifying the virtual address
of a simple or subscripted variable, or the address of an external function.
For dynamic strings, the LOC function returns the address of the descriptor
rather than the address of the data.

Format

int-var = LOGC ( { ext-routine })
.

var

Syntax Rules

Var can be any local or external, simple or subscripted variable.
Var cannot be a virtual array element.

Ext-routine can be the name of an external function.

The LOC function always returns a LONG value.

Remarks

The LOC function is useful for passing the address of an external
function as a parameter to a procedure. When passing a routine address
as a parameter you should usually pass the address by value. For
example, VMS system services expect to receive AST procedure entry
masks by reference; therefore, the address of the entry mask should be
in the argument list on the stack.

Statements and Functions

4-189

LOC

Example

DECLARE

INTEGER A,

A =12
B

LOC(A)

Output
2146799372

4-190

Statements and Functions

LOG

LOG
The LOG function returns the natural logarithm (base e) of a specified
number. The LOG function is the inverse of the EXP function.

Format

real-var = LOG (real-exp)

Syntax Rules

None.

Remarks

Real-exp must be greater than zero. An attempt to find the logarithm
of zero or a negative number causes VAX BASIC to signal “Illegal
argument in LOG” (ERR=53).

The LOG function uses the mathematical constant e as a base. VAX
BASIC approximates e to be 2.718281828459045 (double precision).

The LOG function returns the exponent to which e must be raised to
equal real-exp.

VAX BASIC expects the argument of the LOG function to be a real

Statements and Functions

4-191

LOG

Example

DECLARE

exponent
PRINT

SINGLE

exponent

= L0OG(98.6)

exponent

Output
4.59107

4-192

Statements and Functions

LOG10

LOG10
The LOG10 function returns the common logarithm (base 10) of a specified
number.

Format

real-var = LOG10 (real-exp)

Syntax Rules

None.

Remarks

Real-exp must be larger than zero. An attempt to find the logarithm
of zero or a negative number causes VAX BASIC to signal “Illegal
argument in LOG” (ERR=53).

The LOG10 function returns the exponent to which 10 must be raised to
equal real-exp.

VAX BASIC expects the argument of the LOG10 function to be a real
expression. When the argument is a real expression, VAX BASIC
returns a value of the same floating-point size. When the argument is
not a real expression, VAX BASIC converts the argument to the default
floating-point size and returns a value of the default floating-point size.

Statements and Functions

4-193

LOG10

Example

DECLARE

SINGLE

exp base 10

exp_base
10 = LOG10(250)
PRINT

exp base 10

Output
2.39794

4-194

Statements and Functions

LSET

LSET
The LSET statement assigns left-justified data to a string variable. LSET

does not change the length of the destination string variable.

Format

LSET

str-var,... = str-exp

Syntax Rules

Str-var is the destination string. Str-exp is the string value assigned to
str-var.

Str-var cannot be a DEF function or function name unless the LSET
statement 1s inside the multi-line DEF or function that defines the

function.

Remarks

The LSET statement treats all strings as fixed length. LSET neither
changes the length of the destination string nor creates new storage.
Rather, it overwrites the current storage of str-var.
If the destination string is longer than str-exp, LSET left-justifies

str-exp and pads it with spaces on the right. If smaller, LSET truncates
characters from the right of str-exp to match the length of sir-var.

Statements and Functions

4-195

LSET

Example

DECLARE STRING alpha
alpha =

"ABCDE"

LSET

alpha =

alpha

"FGHIJKLMN"

Output
FGHIJ

4-196

Statements and Functions

MAG

MAG
The MAG function returns the absolute value of a specified expression. The
returned value has the same data type as the expression.

Format

var = MAG (exp)

Syntax Rules

None.

Remarks

1. The returned value is always greater than or equal to zero. The absolute
value of 0 is zero. The absolute value of a positive number equals that
number. The absolute value of a negative number equals that number
multiplied by -1.

2. The MAG function is similar to the ABS function in that it returns
the absolute value of a number. The ABS function, however, takes a
floating-point argument and returns a floating-point value. The MAG
function takes an argument of any numeric data type and returns a
value of the same data type as the argument. DIGITAL recommends
the use of the MAG function rather than the ABS and ABS% functions,
because the MAG function returns a value using the data type of the
argument.

Statements and Functions

4-197

MAG

Example

DECLARE

SINGLE

-34.6

PRINT MAG (A)

Output
34.6

4-198

Statements and Functions

MAGTAPE

MAGTAPE
The MAGTAPE function permits your program to control unformatted
magnetic tape files.

NOTE

The MAGTAPE function is supported only for compatibility with
BASIC-PLUS-2. DIGITAL recommends that you do not use the
MAGTAPE function for new program development.

Format

int-var1 = MAGTAPE (func-code, int-var, chnl-exp)

Syntax Rules

Func-code specifies the code for the MAGTAPE function you want

to perform. VAX BASIC supports only function code 3, rewind tape.
Table 4—4 explains how to perform other MAGTAPE functions with VAX
BASIC.

2. Int-var is an integer parameter for function codes 4, 5, and 6. However,
because VAX BASIC supports only function code 3, int-var is not used
and always equals zero.

Chnl-exp is a numeric expression that specifies a channel number
associated with the magnetic tape file.

Statements and Functions

4-199

MAGTAPE

Table 4-4:

MAGTAPE Functionality in VAX BASIC

Code

Function

Write EOF

VAX BASIC Action

Close channel with the CLOSE
statement

Rewind tape

Use the RESTORE # statement,
the REWIND clause on an OPEN

Skip records

Perform GET operations, ignore data

statement, or the MAGTAPE function
until reaching desired record

Backspace

Rewind tape, perform GET operations,
ignore data until reaching desired
record

Set density or set parity

Use the DCL commands
MOUNT/DENSITY and
MOUNT/FOREIGN or the $MOUNT
system service

Get status

Use the RMSSTATUS function

Remarks

For more information on the MAGTAPE function, see Appendix A in this

manual.

Example

4-200

= MAGTAPE

(3%,0%,2%)

Statements and Functions

MAP

The MAP statement defines a named area of statically allocated storage

called a PSECT, declares data fields in the record, and associates them with
program variables.

Format
MAP

(map-name) { [ data-type ] map-item },...

map-item:
num-unsubs-var

num-array-name ( [ int-const1 TO ] int-const2,... )
record-var
str-unsubs-var [ = int-const |
str-array-name ( [ int-const1 TO ] int-const2,... ) [ = int-const ]
FILL [ (int-const ) ] [ = int-const |
FILL% [ (int-const ) ]

FILLS$ [ ( int-const ) ] [ = int-const ]

Syntax Rules

Map-name is global to the program and image. It cannot appear

elsewhere in the program unit as a variable name.
2.

Map-name can be from 1 through 31 characters. The first character of
the name must be an alphabetic character (A through Z). The remaining

characters, if present, can be any combination of letters, digits (0
through 9), dollar signs ($), periods (.), or underscores (_).
3.

Data-type can be any VAX BASIC data type keyword or a data type
defined by a RECORD statement. Data type keywords, size, range, and

precision are listed in Table 1-2.

Statements and Functions

4-201

MAP

When you specify a data type, all following map-items, including FILL
items, are of that data type until you specify a new data type.

If you specify a dollar sign ($) or percent sign (%) suffix character, the
variable must be a string or integer data type.

If you do not specify a data type, a map-item without a suffix character
(% or $) takes the current default data type and size.

Map-item declares the name and format of the data to be stored.
e

Num-unsubs-var and num-array-name specify a numeric variable or
a numeric array.

Record-var specifies a record instance.

Str-unsubs-var and sir-array-name specify a fixed-length string
variable or array. You can specify the number of bytes to be reserved
for the variable with the =int¢-const clause. The default string length
is 16.

The FILL, FILL%, and FILL$ keywords allow you to reserve parts
of the record buffer within or between data elements and to define
the format of the storage. Int-const specifies the number of FILL
items to be reserved. The =int-const clause allows you to specify the
number of bytes to be reserved for string FILL items. Table 4-2
describes FILL item format and storage allocation.

In the applicable formats of FILL, (inf-const) represents a repeat

count, not an array subscript. FILL (n), for example, represents n
elements, not n + 1.

Variable names, array names and FILL items following a data type
other than STRING cannot end with a dollar sign. Variable names,
array names and FILL items following a data type other than BYTE,
WORD, LONG or INTEGER, cannot end with a percent sign.

Variables and arrays declared in a MAP statement cannot be declared
elsewhere in the program by any other declarative statements.

10. When you declare an array, VAX BASIC allows you to specify both
lower and upper bounds. Upper bounds are required; lower bounds are
optional.

4-202

Int-const2 specifies the upper bounds of the array and, when
accompanied by int-constl, must be preceded by the keyword TO.

Int-constl must be less than or equal to int-const2.

Statements and Functions

MAP

If you do not specify int-constl, VAX BASIC uses zero as the default
lower bound.

Int-constl and int-const2 can be any combination of negative and
positive values.

Remarks

VAX BASIC does not execute MAP statements. The MAP statement
allocates static storage and defines data at compilation time.
A program can have multiple maps with the same name. The allocation

for each map overlays the others. Thus, data is accessible in many ways.
The actual size of the data area is the size of the largest map. When

you link your program, the size of the map area is the size of the largest
map with that name.

Map-items with the same name can appear in different MAP statements
with the same map name only if they match exactly in attributes such
as data type, position, and so forth. If the attributes are not the same,
VAX BASIC signals an error. For example:
MAP

(ABC)

LONG A,

MAP

(ABC)

LONG A,

This MAP

statement is wvalid

MAP

(ABC)

LONG B,

This MAP

statement produces

an error

MAP

(ABC)

WORD A,

This MAP

statement produces

an error

The third MAP statement causes VAX BASIC to signal the error

“variable <name> not aligned in multiple references in MAP <name>”,
while the fourth MAP statement generates the error “attributes of
overlaid variable <name> don’t match”.

The MAP statement should precede any reference to variables declared
in 1it.

Storage space for map-items is allocated in order of occurrence in the
MAP statement.

A MAP area can be accessed by more than one program module, as long
as you define the map-name in each module that references the MAP.

Statements and Functions

4-203

MAP

A COMMON area and a MAP area with the same name specify the same
storage area and are not allowed in the same program module. However,

a COMMON in one module can reference the storage declared by a MAP
or COMMON in another module.
8.

Variables in a MAP statement are not initialized by VAX BASIC.

A map named in an OPEN statement’s MAP clause is associated with

that file. The file’s records and record fields are defined by that map.
The size of the map determines the record size for file I/0, unless the
OPEN statement includes a RECORDSIZE clause.

Example

MAP

(BUF1l)

BYTE AGE,

STRING emp name = 20

SINGLE emp num
MAP

4-204

(BUF1l)

BYTE FILL,

FILL =

STRING

SINGLE FILL

Statements and Functions

last name

(11)

12,

MAP DYNAMIC

MAP DYNAMIC
The MAP DYNAMIC statement names the variables and arrays whose size
and position in a storage area can change at run time. The MAP DYNAMIC
statement is used in conjunction with the REMAP statement. The REMAP
statement defines or redefines the position in the storage area of variables
named in the MAP DYNAMIC statement.

Format

MAP DYNAMIC

(map-dyn-name){[ data-type Jmap-item },...

map-dyn-name: {static—str—var }
e

map-name

([ num-unsubs-var

map-item:

num-array-name ( [ int-const1 TO ] int-const2 ,...)

* record-var

str-unsubs-var
\ str-array-name ( [ int-const1 TO ] int-const2,...)

Syntax Rules

Map-dyn-name can either be a map name or a static string variable.
*

Map-name is the storage area named in a MAP statement.

If you specify a map name, then a MAP statement with the same
name must precede both the MAP DYNAMIC statement and the
REMAP statement.

When you specify a static string variable, the string must be
declared before you can specify a MAP DYNAMIC statement or a
REMAP statement.

Statements and Functions

4-205

MAP DYNAMIC

Static-str-var must specify a static string variable or a string
parameter variable.

If you specify a static-str-var, the following restrictions apply:
—

Static-str-var cannot be a string constant.

—

Static-str-var cannot be the same as any previously declared
map-item in a MAP DYNAMIC statement.

—

Static-str-var cannot be a subscripted variable.

—

Sltatic-str-var cannot be a record component.

—

Static-str-var cannot be a parameter declared in a DEF or DEF*
function.

Map-item declares the name and data type of the items to be stored

in the storage area. All variable pointers point to the beginning of the
storage area until the program executes a REMAP statement.

Num-unsubs-var and num-array-name specify a numeric variable or
a numeric array.

Record-var specifies a record instance.

Str-unsubs-var and str-array-name specify a string variable or

array. You cannot specify the number of bytes to be reserved for the
variable in the MAP DYNAMIC statement. All string items have a

fixed length of zero until the program executes a REMAP statement.

When you specify an array name, VAX BASIC allows you to specify both
lower and upper bounds. The upper bound is required; the lower bound
is optional.
®

Int-constl specifies the lower bounds of the array.

Int-const2 specifies the upper bounds of the array and, when
accompanied by int-constl, must be preceded by the keyword TO.

Int-constl must be less than or equal to int-const2.

If you do not specify int-const1, VAX BASIC uses zero as the default

lower bound.
®*
4.

Ini-constl and int-const2 can be either negative or positive values.

Data-type can be any VAX BASIC data type keyword or a data type

defined with a RECORD statement. Data type keywords, size, range,
and precision are listed in Table 1-2 in this manual.

4-206

Statements and Functions

MAP DYNAMIC

When you specify a data type, all following map-items are of that data
type until you specify a new data type.
If you do not specify any data type, map-items take the current default

data type and size.
Map-items must be separated with commas.

If you specify a dollar sign or percent sign suffix, the variable must be a

STRING data type or one of the integer data types.

Remarks

All variables and arrays declared in a MAP DYNAMIC statement
cannot be declared elsewhere in the program by any other declarative
statements.

The MAP DYNAMIC statement does not affect the amount of storage
allocated to the map buffer declared in a previous MAP statement or

the storage allocated to a static string. Until your program executes a
REMAP statement, all variable and array element pointers point to the

beginning of the MAP buffer or static string.
VAX BASIC does not execute MAP DYNAMIC statements. The MAP

DYNAMIC statement names the variables whose size and position in
the MAP or static string buffer can change and defines their data type.
Before you can specify a map name in a MAP DYNAMIC statement,
there must be a MAP statement in the program unit with the same map
name. Otherwise, VAX BASIC signals the error “Insufficient space for

MAP DYNAMIC variables in MAP <name>”. Similarly, before you can
specify a static string variable in the MAP DYNAMIC statement, the

string variable must be declared. Otherwise, VAX BASIC signals the
same error message.

A static string variable must be either a variable declared in a MAP or
COMMON statement or a parameter declared in a SUB, FUNCTION,
or PICTURE. It cannot be a parameter declared in a DEF or DEF*

function.
If a static string variable is the same as a map name, VAX BASIC uses
the map name if the name appears in a MAP DYNAMIC statement.

Statements and Functions

4-207

MAP DYNAMIC

The MAP DYNAMIC statement must lexically precede the REMAP
statement or VAX BASIC signals the error “MAP variable <name>
referenced before declaration.”

Example

100

MAP (MY.BUF) STRING DUMMY = 512
MAP DYNAMIC (MY.BUF) STRING LAST,
BYTE AGE,

FIRST,

MIDDLE,

STRING EMPLOYER,

STRING CHARACTERISTICS

4-208

Statements and Functions

&
&

MAR

MAR
The MAR function returns the current margin width of a specified channel.

Format
int-var = MAR[%] (chnl-exp)

Syntax Rules

The file associated with chnl-exp must be open.

Remarks

If chnl-exp specifies a terminal and you have not set a margin width

with the MARGIN statement, the MAR function returns a value of zero.

If you have set a margin width, the MAR function returns that number.

The value returned by the MAR function is a LONG integer.

Example

DECLARE

INTEGER width

MARGIN #0,

width = MAR(0)
PRINT width

Output
80

Statements and Functions

4-209

MARGIN

MARGIN
The MARGIN statement specifies the margin width for a terminal or for
records in a terminal-format file.

Format

MARGIN

[#chnl-exp, | int-exp

Syntax Rules
Chnl-exp is a numeric expression that specifies a channel number
associated with a file. It must be immediately preceded by a number
sign (#).
Int-exp specifies the margin width.

Remarks

If you do not specify a channel, VAX BASIC sets the margin on the

controlling terminal.

The file associated with chnl-exp must be an open terminal-format file or
terminal.

VAX BASIC signals the error “Illegal operation” (ERR=141) if the file
associated with chnl-exp is not a terminal-format file.

If chnl-exp does not correspond to a terminal, and. if int-exp is
zero, VAX BASIC sets the right margin to the size specified by the

RECORDSIZE clause in the OPEN statement, if the clause is present. If
no RECORDSIZE clause is present, VAX BASIC sets the margin to 72
(or, in the case of channel 0, to the width of SYS$OUTPUT).

4-210

Statements and Functions

MARGIN

If chnl-exp is not present or if it corresponds to a terminal, and if int-exp
is zero, VAX BASIC sets the right margin to the size specified by the
RECORDSIZE clause in the OPEN statement, if the clause is present. If
no RECORDSIZE clause is present, VAX BASIC sets the margin to 72.
VAX BASIC prints as much of a specified record as the margin setting
allows on one line before going to a new line. Numeric fields are never
split across lines.

If you specify a margin larger than the channel’s record size, VAX
BASIC signals an error. The default record size for a terminal or
terminal format file is 132.

The MARGIN statement applies to the specified channel only while the
channel is open. If you close the channel and then reopen it, VAX BASIC
uses the default margin.

Example

OPEN

"EMP.DAT" FOR OUTPUT AS #1
132

MARGIN #1,

Statements and Functions

4-211

MAT

MAT
The MAT statement lets you implicitly create and manipulate one- and

two-dimensional arrays. You can use the MAT statement to assign values to
array elements, or to redimension a previously dimensioned array. You can
also perform matrix arithmetic operations such as multiplication, addition,

and subtraction, and other matrix operations such as transposing and
inverting matrices.

Format
Numeric Initialization

CON

MAT num-array= { IDN } [ (int-exp1 [, int-exp2]) ]
ZER

String Initialization

MAT

str-array = NULS$ [ (int-exp1 [, int-exp2]) ]

Array Arithmetic
=

MAT num-array1 = num-array2 {- } num-array3
+

MAT

num-array1 = num-array2* num-array3 [* num-array4 | ,...

Scalar Multiplication

MAT

num-array4 = ( num-exp ) * num-array5

Inversion and Transposition

MAT num-array6 = { ;Il-\IRVN } ( num-array?7)

4-212

-l

Statements and Functions

MAT

Syntax Rules
Int-expl and int-exp2 define the upper bounds of the array being
implicitly created or the new dimensions of an existing array.

If you are creating an array, int-expl and int-exp2 cannot exceed 10.
If you do not specify bounds, VAX BASIC creates the array and
dimensions it to (0 TO 10) or (10 TO 10, 0 TO 10).

If you specify bounds, VAX BASIC creates the array with the specified
bounds. If the bounds exceed (0 TO 10) or (10 TO 10, 0 TO 10), VAX
BASIC signals “Redimensioned array” (ERR=105).
The lower bounds must be zero.

Remarks
To perform MAT operations on arrays larger than (10,10), create the

input and output arrays with the DIM statement.

When the array exists, the following rules apply:

If you specify upper bounds, VAX BASIC redimensions the array
to the specified size. However, MAT operations cannot increase the
total number of array elements.

All arrays specified with the MAT statement must have lower
bounds of zero. If you supply a nonzero value, VAX BASIC signals
either a compile-time or a run-time error.

If you do not specify bounds, VAX BASIC does not redimension the
array.

An array passed to a subprogram and redimensioned with a MAT
statement remains redimensioned when control returns to the
calling program, with two exceptions:

—

When the array is within a record and is passed by descriptor

—

When the array is passed by reference

Statements and Functions

4-213

MAT

You cannot use the MAT statement on arrays of more than two

dimensions.

You cannot use the MAT statement on arrays of data type DECIMAL or
on arrays named in a RECORD statement.

Initialization

CON sets all elements of num-array to 1, except those in row and
column zero.
IDN creates an identity matrix from num-array. The number of
rows and columns in num-array must be identical. IDN sets all
elements to zero except those on the diagonal from num-array(1,1) to
num-array(n,n), which are set to 1.

ZER sets all array elements to zero, except those in row and column
Zero.

NULS$ sets all elements of a string array to the null string, except

those in row and column zero.
6.

Array Arithmetic
The equal sign (=) assigns the results of the specified operation to
the elements in num-arrayl.

If num-array3 is not specified, VAX BASIC assigns the values of

num-array2’s elements to the corresponding elements of num-arrayl.

Num-arrayl must have at least as many rows and columns as
num-array2.

Use the plus sign (+) to add the elements of two arrays. Num-array2
and num-array3 must have identical bounds.

Use the minus sign (-) to subtract the elements of two arrays.
Num-array2 and num-array3 must have identical bounds.
Use the asterisk (*) to perform matrix multiplication on the
elements of num-array2 and num-array3 and to assign the results

to num-arrayl. This operation gives the dot product of num-array2

and num-array3. All three arrays must be two-dimensional, and
the number of columns in num-array2 must equal the number of

rows in num-array3. VAX BASIC redimensions num-arrayl to have
the same number of rows as num-array2 and the same number of

columns as num-array3.

4-214

Statements and Functions

MAT

With matrix multiplication, you can specify more than two numeric
arrays. However, each array must be two-dimensional. Moreover, in
each dimension, the lower bound of each array must be zero and the
upper bound must be 4. You can use the graphics transformation
functions, which will automatically create arrays with these

dimensions. See the DRAW statement in Programming with VAX
BASIC Graphics for more information.
Scalar Multiplication
*

VAX BASIC multiplies each element of num-array5 by num-exp and

stores the results in the corresponding elements of num-array4.

Inversion and Transposition
*

TRN transposes num-array7 and assigns the results to num-array6.

If num-array7 has m rows and n columns, num-array6 will have n
rows and m columns. Both arrays must be two-dimensional.
*

You cannot transpose a matrix to itself: MAT A = TRN(A) is invalid.

INV inverts num-array7 and assigns the results to num-array6.
Num-array7 must be a two-dimensional array that can be reduced

to the identity matrix with elementary row operations. The row and
column dimensions must be identical.

You cannot increase the number of array elements or change the
number of dimensions in an array when you redimension with the MAT
statement. For example, you can redimension an array with dimensions

(5,4) to (4,5) or (3,2), but you cannot redimension that array to (5,5)
or to (10). The total number of array elements includes those in row
and column zero.
10. If an array is named in both a DIM statement and a MAT statement,

the DIM statement must lexically precede the MAT statement.
11. MAT statements do not operate on elements in the zero element

(one-dimensional arrays) or in the zero row or column (two-dimensional
arrays). MAT statements use these elements to store results of

intermediate calculations. Therefore, you should not depend on values
in row and column zero if your program uses MAT statements.

Statements and Functions

4-215

Examples

Example 1
!Numeric Initialization
MAT CONVERT = zer (10,10)

Example 2
!Initialization
MAT na_me$ = NULS$(5,5)

Example 3
!Array Arithmetic
MAT new_int = old_int - rslt_int

Example 4
!Scalar Multiplication
MAT Z40 = (4.24) * Z

Example 5
!Inversion and Transposition
MAT Q%

4-216

INV

(2)

Statements and Functions

MAT INPUT

MAT INPUT
The MAT INPUT statement assigns values from a terminal or
terminal-format file to array elements.

Format
MAT INPUT

[#chnl-exp, ] { array
[ ( int-exp1 [, int-exp2]) ] },...

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number
associated with a file. It must be immediately preceded by a number
sign (#).

The file associated with chnl-exp must be an open terminal-format file

or terminal. If chnl-exp is not specified, VAX BASIC takes data from the
controlling terminal.

Int-expl and int-exp2 define the upper bounds of the array being
implicitly created or the dimensions of an existing array:.

If you are creating an array, int-expl and int-exp2 cannot exceed 10.

You cannot use the MAT INPUT statement on arrays of more than two

Remarks

dimensions.

You cannot use the MAT INPUT statement on arrays of data type

DECIMAL or on arrays named in a RECORD statement.

All arrays specified with the MAT INPUT statement must have lower

bounds of zero.

Statements and Functions

4-217

MAT INPUT

If you do not specify bounds, VAX BASIC creates the array and

dimensions it to (10,10).

If you do specify upper bounds, VAX BASIC creates the array with the
specified bounds. If the bounds exceed (10) or (10,10), VAX BASIC
signals “Redimensioned array” (ERR=105).

To use the MAT INPUT statement with arrays larger than (10,10),
create the input and output arrays with the DIM statement.
When the array exists, the following rules apply:

If you specify bounds, VAX BASIC redimensions the array to the
specified size. However, MAT INPUT cannot increase the total

number of array elements.

If you do not specify bounds, VAX BASIC does not redimension the
array.

The MAT INPUT statement prompts with a question mark on terminals
open on channel #0 only unless a SET NO PROMPT statement has been
executed. See the description of the SET PROMPT statement for more
information.

Use commas to separate data elements and a line terminator to end
the input of data. Use an ampersand (&) before the line terminator to
continue data over more than one line.

For example, it
assigns values to all elements in row 1 before beginning row 2.

10. The MAT INPUT statement assigns values by row.

The MAT INPUT statement assigns the row number of the last data
element transferred into the array to the system variable NUM.
12. The MAT INPUT statement assigns the column number of the last data
element transferred into the array to the system variable NUM2.

11.

13. If there are fewer elements in the input data than there are array

elements, VAX BASIC does not change the remaining array elements.
14. If there are more data elements in the input stream than there are array
elements, VAX BASIC ignores the excess.

15. Row zero and column zero are not changed.
16. For information about graphics input, see the MAT LOCATE and the

MAT GET statements in Programming with VAX BASIC Graphics.

4-218

Statements and Functions

MAT INPUT

Example

MAT

INPUT

XYZ(5,5)

MAT

XYZ;

Output

OO
Qo

O
o
O
o

COWw

O
o

1,2’3’4,
OO0+

Statements and Functions

4-219

MAT LINPUT

MAT LINPUT
The MAT LINPUT statement receives string data from a terminal or
terminal-format file and assigns it to string array elements.

Format

MAT LINPUT

[#chnl-exp, | { str-array
[ (int-exp1 [, int-exp2]) ]}, ...

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number
associated with a file or terminal. It must be immediately preceded by a
number sign (#).

The file associated with chnl-exp must be an open terminal-format file or
terminal. If a channel is not specified, VAX BASIC takes data from the
controlling terminal.
Int-expl and int-exp2 define the upper bounds of the array being
implicitly created or the dimensions of an existing array.

If you are creating an array, int-expl and int-exp2 cannot exceed 10.

Remarks

You cannot use the MAT LINPUT statement on arrays of more than two
dimensions.

You cannot use the MAT LINPUT statement on arrays of data type other
than STRING or on arrays named in a RECORD statement.

If you do not specify bounds, VAX BASIC creates the array and
dimensions it to (10,10).

4-220

Statements and Functions

MAT LINPUT

If you do specify upper bounds, VAX BASIC creates the array with the
specified bounds. If the bounds exceed (10) or (10,10), VAX BASIC

signals “Redimensioned array” (ERR=105).

All arrays specified with the MAT LINPUT statement must have lower
bounds of zero.

To use MAT LINPUT with arrays larger than (10,10), create the input
and output arrays with the DIM statement.

When the array exists, the following rules apply:
*

If you specify bounds, VAX BASIC redimensions the array to the

specified size. However, MAT LINPUT cannot increase the total
number of array elements.

Ifyou do not specify bounds, VAX BASIC does not redimension the
array.

For terminals open on channel zero only, the MAT LINPUT statement

prompts with a question mark (unless a SET NO PROMPT statemen

has been executed) for each string array element, starting with element
(1,1). VAX BASIC assigns values to all elements of row 1 before

beginning row 2.
9.

The MAT LINPUT statement assigns the row number of the last data
element transferred into the array to the system variable NUM.

10. The MAT LINPUT statement assigns the column number of the

last
data element transferred into the array to the system variable NUM2.

11. Typing only a line terminator in response to the question mark prompt
causes VAX BASIC to assign a null string to that string array element.

12. MAT LINPUT does not change row and column zero.

Statements and Functions

4-221

MAT LINPUT

Example

DIM cus_rec$(3,3)

MAT LINPUT cus_rec$(2,2)
PRINT cus_rec$(1,1)
PRINT cus_rec$(1,2)
PRINT cus_rec$(2,1)
PRINT cus_rec$(2,2)

)

Babcock

Santani

") )

Output

Lloyd
Kelly

Babcock

Santani
Lloyd

Kelly

4-222

Statements and Functions

MAT PRINT

MAT PRINT
The MAT PRINT statement prints the contents of a one- or two-dimensional

array on your terminal or assigns the value of each array element to a record

in a terminal-format file.

Format

MAT PRINT

[#chnl-exp, ] { array [ ( int-exp1 [, int-exp2] ) ][ ] J...

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number
associated with a file or terminal. It must be immediately preceded by a
number sign (#).

The file associated with cAnl-exp must be an open terminal-format file or
terminal. If you do not specify a channel, VAX BASIC takes data from

the controlling terminal.
3.

Int-expl and int-exp2 define the upper bounds of the array being
implicitly created or the dimensions of an existing array.

The separator (comma or semicolon) determines the output format for

the array:
*

If you use a comma, VAX BASIC prints each array element in a new
print zone and starts each row on a new line.

If you use a semicolon, VAX BASIC separates each array element
with a space and starts each row on a new line.

If'you do not use a separator character, VAX BASIC prints each
array element on its own line.

Statements and Functions

4-223

MAT PRINT

Remarks
You cannot use the MAT PRINT statement on arrays of more than two
dimensions.

You cannot use the MAT PRINT statement on arrays of data type

DECIMAL or on arrays named in a RECORD statement.
When you use the MAT PRINT statement to print more than one array,

each array name except the last must be followed with either a comma
or a semicolon. VAX BASIC prints a blank line between arrays.
If the array does not exist, the following rules apply:

All arrays specified with the MAT PRINT statement must have lower
bounds of zero.

If you do not specify bounds, VAX BASIC creates the array and

If you specify upper bounds, VAX BASIC creates the array with the
specified bounds. If the bounds exceed (10) or (10,10), VAX BASIC
prints the elements (10) or (10,10), and signals “Subscript out of

dimensions it to (10,10).

range” (ERR=55).

When the array exists, the following rules apply:

If the specified bounds are smaller than the maximum bounds of
a dimensioned array, VAX BASIC prints a subset of the array, but
does not redimension the array. For example, if you use the DIM
statement to dimension A(20,20), and then MAT PRINT A(2,2), VAX
BASIC prints elements (1,1), (1,2), (2,1), and (2,2) only; array
A(20,20) does not change.

If you do not specify bounds, VAX BASIC prints the entire array.
The MAT PRINT statement does not print elements in row or column
e

ZEero.

The MAT PRINT statement cannot redimension an array.

4-224

Statements and Functions

MAT PRINT

Example

DIM

cus_rec$
(3, 3)

MAT

LINPUT

MAT PRINT

cus_rec$(2,2)

cus_rec$
(2, 2)

Output
?

Babcock

Santani

Lloyd

Kelly

Babcock

Santani
Lloyd
Kelly

Statements and Functions

4-225

MAT READ

MAT READ
The MAT READ statement assigns values from DATA statements to array
elements.

Format

MAT READ

{array [ (int-expl [, int-exp2]) ] },...

Syntax Rules

Int-expl and int-exp2 define the upper bounds of the array being
implicitly created or the dimensions of an existing array.

If you are creating an array, int-expl and int-exp2 cannot exceed 10.

Remarks

If you do not specify bounds, VAX BASIC creates the array and

dimensions it to (10) or (10,10).

If you specify bounds, VAX BASIC creates the array with the specified
bounds. If the bounds exceed (10) or (10,10), VAX BASIC signals
“Redimensioned array” (ERR=105).

To read arrays larger than (10,10), create the array with the DIM
statement.

All arrays specified with the MAT statement must have lower bounds of
Z€To.

4-226

Statements and Functions

MAT READ

When the array exists, the following rules apply:
¢

If you specify upper bounds, VAX BASIC redimensions the array to

the specified size. However, MAT READ cannot increase the total
number of array elements.
e

If you do not specify bounds, VAX BASIC does not redimension the
array.

All the DATA statements must be in the same program unit as the MAT
READ statement.
The MAT READ statement assigns data items by row. For example, it
assigns data items to all elements in row 1 before beginning row 2.
The MAT READ statement does not read elements into row or column
Zero.

The MAT READ statement assigns the row number of the last data

element transferred into the array to the system variable, NUM.
10. The MAT READ statement assigns the column number of the last data

element transferred into the array to the system variable, NUM2.
11. If you use MAT READ for an existing array without specifying bounds,

VAX BASIC does not redimension the array. If you use MAT READ
for an existing array and specify bounds, VAX BASIC redimensions the
array.

12. You cannot use the MAT READ statement on arrays of more than two

dimensions.
13. You cannot use the MAT READ statement on arrays of data type

DECIMAL or on arrays named in a RECORD statement.

Statements and Functions

4-227

MAT READ

Example

MAT READ A (3, 3)
MAT

READ

B(3, 3)

"Matrix A"

MAT

"Matrix

PRINT
MAT

DATA

1,2,3,4,5,6

Output
Matrix A

Matrix B

4-228

Statements and Functions

MAX

MAX
The MAX function compares the values of two or more numeric expressions

and returns the highest value.

Format
num-var = MAX ( num-exp1, num-exp2 [, num-exp3,...])

Syntax Rules

VAX BASIC allows you to specify up to eight numeric expressions.

Remarks

If you specify values with different data types, VAX BASIC performs
data type conversions to maintain precision.

VAX BASIC returns a function result whose data type is compatible with
the values you supply.

Statements and Functions

4-229

MAX

Example

DECLARE REAL John grade,

Bob_grade,

Joe grade,

highest grade

INPUT "John’s grade";John_grade
INPUT "Bob’s grade";Bob grade
INPUT

"Joe’s grade";Joe_grade

highest grade = MAX(John_grade, Bob_grade, Joe_grade)
PRINT "The highest grade is";highest grade

Output
John'’s grade?
Bob’s grade?

90
95

79
The highest grade is

Joe’s grade?

4-230

Statements and Functions

MID$

MID$
MID$ can be used either as a statement or as a function. The MID$
statement performs substring insertion into a string. The MID$ function
extracts a specified substring from a string expression.

Format
MID$ statement

MID[$]

( str-var, int-exp1 [, int-exp2 ] ) = str-exp

MID$ function

str-var = MID[$] (str-exp, int-exp1, int-exp2)

Syntax Rules

Int-expl specifies the position of the substring’s first character.

Int-exp2 specifies the length of the substring.

Remarks

If int-expl is less than 1, VAX BASIC assumes a starting character

position of 1.
2.

If int-exp2 is less than or equal to zero, VAX BASIC assumes a length of
Zero.

If you specify a floating-point expression for int-expl or int-exp2, VAX
BASIC truncates it to a LONG integer.

Statements and Functions

4-231

MID$

MID$ statement

The MID$ statement replaces a specified portion of str-var with
str-exp.

If int-expl is greater than the length of str-var, str-var remains
unchanged.

The length of str-var does not change regardless of the value of
int-exp2.

If the optional int-exp2 is not specified, VAX BASIC assumes int-exp2
to be the length of str-exp minimized by the length of str-var minus
int-expl. For example:
AS$ =

"ABCDEFG"

MIDS (A$,3)
PRINT AS$

= "123456789"

Output
"AB12345"

Ifint-exp2 is less than or equal to zero, str-var remains unchanged.

Ifint-exp2 is greater than the length of str-var, VAX BASIC assumes
int-exp2 to be equal to the length of str-var.

Int-exp2 is always minimized against the length of str-var minus
int-expl.

MID$ function

The MID$ function extracts a substring from s¢r-exp and stores it in
sir-var.

If int-expl is greater than the length of str-exp, MID$ returns a null
string.

If int-exp2 is greater than the length of str-exp, VAX BASIC returns
the string that begins at int-expl and includes all characters
remaining in str-exp.

4-232

Ifint-exp2 is less than or equal to zero, MID$ returns a null string.

Statements and Functions

MID$

Examples

Example 1
!MID$

Function

DECLARE

STRING

old string,

new_string

old _string =

"ABCD"

new_string =

MID$ (old_string,1,
3)

new_string

Output
ABC

Example 2
IMIDS

Statement

DECLARE

STRING

old string =

old_string,

replace_string =
PRINT

"123"

old_string

MIDS (oldstring,1,3)
PRINT

replace string

"ABCD"

= replace_string

old_string

Output
ABCD

123D

Statements and Functions

4-233

MIN

MIN
The MIN function compares the values of two or more numeric expressions
and returns the smallest value.

Format

num-var = MIN ( num-exp1, num-exp2 [ , num-exp3,... ])
Syntax Rules
VAX BASIC allows you to specify up to eight numeric expressions.

Remarks
1. If you specify values with different data types, VAX BASIC performs
data type conversions to maintain precision.

2. VAX BASIC returns a function result whose data type is compatible with
the values you supply.

4-234

Statements and Functions

Example

DECLARE

REAL

John grade,

Bob_grade,

Joe_grade,

lowest_grade
INPUT

"John’s

INPUT

"Bob’s

INPUT

"Joe'’s

grade";Joe grade

lowest grade

= MIN (John_ grade,

"The

grade";John grade

grade";Bob grade

lowest

grade

Bob_grade,

Joe grade)

is";lowest grade

Output
John’s

grade?

Bob’s

grade?

100

Joe’s

grade?

The

lowest

grade

Statements and Functions

4-235

MOD

MOD
The MOD function divides a numeric value by another numeric value and
returns the remainder.

Format

num-var = MOD ( num-exp1, num-exp2 )

Syntax Rules
Num-expl is divided by num-exp2.

Remarks
1. If you specify values with different data types, VAX BASIC performs
data type conversions to maintain precision.

9. VAX BASIC returns a function result whose data type is compatible with
the values you supply.

3. The function result is either a positive or negative value, depending
on the value of the first numeric expression. For example, if the first
numeric expression is negative, then the function result will also be
negative.

4-236

Statements and Functions

MOD

Example

DECLARE REAL A,B

A =
B

500

= MOD (A, 70)

"The

remainder

equals";B

Output
The

remainder equals

Statements and Functions

4-237

MOVE

MOVE
The MOVE statement transfers data between a record buffer and a list of

variables.

Format

]
iy
MOVE { TO
FROM } #chnl-exp,
move-item,...

( num-var

)

num-array ( [,]...)

move-item:

str-var[ = int-exp |

fi str-array ([,]...) [ = int-exp ]

[ data-type JFILL [ (int-exp ) | [ = int-const |
FILL% [ (int-exp )]
| FILL$ [ (int-exp ) ][ = int-exp ]
)

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number
associated with a file. It must be immediately preceded by a number
sign (#).

4-238

Move-item specifies the variable or array to which or from which data is
to be moved.

Parentheses indicate the number of dimensions in a numeric array. The
number of dimensions is equal to the number of commas plus 1. Empty
parentheses indicate a one-dimensional array, one comma indicates a
two-dimensional array, and so on.

Statements and Functions

MOVE

Str-var and str-array specify a fixed length string variable or array.

Parentheses indicate the number of dimensions in a string array. The
number of dimensions is equal to the number of commas plus 1. You

can specify the number of bytes to be reserved for the variable or array
elements with the =int-exp clause. The default string length for a MOVE

FROM statement is 16. For a MOVE TO statement, the default is the
string’s length.
The FILL, FILL%, and FILL$ keywords allow you to transfer fill

items of a specific data type. Table 4-2 shows FILL item formats,
representations, and storage requirements.

If you specify a data type before the FILL keyword, the fill is of that

data type. If you do not specify a data type, the fill is of the default
data type. Data-type can be any VAX BASIC data type keyword or

a data type defined by a RECORD statement. Data type keywords,
size, range, and precision are listed in Table 1-2 in this manual.

FILL items following a data type other than STRING cannot end
with a dollar sign. FILL items following a data type other than
BYTE, WORD, LONG or INTEGER, cannot end with a percent sign.

Int-exp specifies the number of FILL items to be moved.

FILL% indicates integer fill. FILL$ indicates string fill. The =int-exp
clause specifies the number of bytes to be moved for string FILL

items.
*

In the applicable formats of FILL, (int-exp) represents a repeat
count, not an array subscript. FILL (n), for example, represents n

elements, not n + 1.

You cannot use an expression or function reference as a move-item.

Remarks

Before a MOVE FROM statement can execute, the file associated with
chnl-exp must be open and there must be a record in the record buffer.

Statements and Functions

4-239

MOVE

A MOVE statement neither transfers data to or from external devices,
nor invokes the VAX Record Management Services (RMS). Instead, it
transfers data between user areas. Thus, a record should first be fetched
with the GET statement before you use a MOVE FROM statement,
and a MOVE TO statement should be followed by a PUT or UPDATE
statement that writes the record to a file.

MOVE FROM transfers data from the record buffer to the move-item.

MOVE TO transfers data from the move-item to the record buffer.

The MOVE statement does not affect the record buffer’s size. If a MOVE
statement partially fills a buffer, the rest of the buffer is unchanged. If
there is more data in the variable list than in the buffer, VAX BASIC
signals “MOVE overflows buffer’” (ERR=161).

Each MOVE statement to or from a channel transfers data starting at

the beginning of the buffer. For example:
MOVE FROM #1%,

1%,

A$ = I%

In this example, VAX BASIC assigns the first value in the record buffer
to I%; the value of I% is then used to determine the length of A$.
7.

If a MOVE statement operates on an entire array, the following
conditions apply:

VAX BASIC transfers elements of row and column zero (in contrast
to the MAT statements).

The storage size of the array elements and the size of the array
determine the amount of data moved. A MOVE statement that
transfers data from the buffer to a longword integer array transfers
the first four bytes of data into the first element (for example, (0,0)),
the next four bytes of data into element (0,1 ), and so on.

If the MOVE TO statement specifies an explicit string length, the

following restrictions apply:

If the string is equal to or longer than the explicit string length, VAX
BASIC moves only the specified number of characters into the buffer.

If the string is shorter than the explicit string length, VAX BASIC

moves the entire string and pads it with spaces to the specified
length.

VAX BASIC does not check the validity of data during the MOVE
operation.

4-240

Statements and Functions

MOVE

Example

MOVE FROM #4%,
MOVE TO #9%,

RUNS%,

FILLS

HITS%,

= 10%,

ERRORS%,
=

10%,

RBI%,

BAT_ AVERAGE

= 30%,

C$ = 2%

Statements and Functions

4-241

NAME...AS

NAME...AS
The NAME...AS statement renames the specified file.

Format

NAME

file-spec1 AS file-spec2

Syntax Rules

File-specl and file-spec2 must be string expressions.
There is no default file type in file-specl or file-spec2. If the file to be

renamed has a file type, file-specl must include both the file name and
the file type.

If you specify only a file name, VAX BASIC searches for a file with no file

type. If you do not specify a file type for file-spec2, VAX BASIC names

the file, but does not assign a file type.
4.

You can include a directory name but not a device name. If you specify

a directory name with file-spec2, the file will be placed in the specified
directory. If you do not specify a directory name the default is the
current directory.

File version numbers are optional. VAX BASIC renames the highest
version of file-specl if you do not specify a version number.

4-242

Statements and Functions

NAME...AS

Remarks

If the file specified by file-specl does not exist, VAX BASIC signals “Can’t
find file or account” (ERR=5).

If you use the NAME...AS statement on an open file, VAX BASIC does

not rename the file until it is closed.

You cannot use the NAME...AS statement to move a file between devices.
You can only change the directory, name, type, or version number.

Example

Directory USERSSDISK: [BASIC_PROG]

Directory USER$$DISK: [BASIC_PROG]
FIRST_PROG.BAS;I

Total

file.

$ BASIC
VAX BASIC V3.4
Ready
NAME

"FIRST PROG.BAS"

"SECOND_PROG.BAS"

Ready
EXIT

$ Directory USER$$DISK: [BASIC PROG]
Directory USER$$DISK: [BASIC_ PROG]
SECOND_PROG.BAS;
1

Total of

file.

Statements and Functions

4-243

NEXT
The NEXT statement marks the end of a FOR, UNTIL, or WHILE loop.

Format
NEXT

[num-unsubs-var |

Syntax Rules

Num-unsubs-var is required in a FOR...NEXT loop and must correspond

to the num-unsubs-var specified in the FOR statement.
2.

Num-unsubs-var is not allowed in an UNTIL or WHILE loop.

Num-unsubs-var must be a numeric, unsubscripted variable.

Remarks

Each NEXT statement must have a corresponding FOR, UNTIL, or WHILE

statement or VAX BASIC signals an error.

4-244

Statements and Functions

Example

PROGRAM
DECLARE

calculating
pay
INTEGER no_hours,

SINGLE weekly pay,

minimum wage
no_hours
WHILE

INPUT

"Enter

weekly

pay
"If

NEXT
END

minimum wage

3.65

no_hours

the number

= no_hours
you

hours

you

intend to work this

week";no hours

minimum wage

worked";no_hours;"hours,

your pay would be";weekly
pay

'
PROGRAM

Output
Enter the number

of hours

If you worked 35

hours,

Enter the number

of hours

If you worked 23

hours,

Enter

the

number

If you worked 0

intend to work this

you
you

week?

83.95

intend to work

your pay would be

week?

127.75

intend to work this

your pay would be

of hours

hours

you

your pay would be

this

Statements and Functions

4-245

NOECHO

NOECHO
The NOECHO function disables echoing of input on a terminal.

Format

int-var = NOECHO (chnl-exp)

Syntax Rules

Chnl-exp must specify a terminal.

Remarks

If you specify NOECHO, VAX BASIC accepts characters typed on the

terminal as input, but the characters do not echo on the terminal.

The NOECHO function is the complement of the ECHO function;

NOECHO disables the effect of ECHO and vice versa.
3.

4-246

NOECHO always returns a value of zero.

Statements and Functions

NOECHO

Example

&
DECLARE INTEGER Y,
STRING pass_word

Y = NOECHO(O0)

INPUT "Enter your password";pass_word

IF pass_word = "DARLENE"” THEN PRINT "Confirmed"

Y = ECHO(0)

Output
Enter your password?
Confirmed

Statements and Functions

4-247

NOMARGIN

NOMARGIN
The
NOMARGIN statement removes the right margin limit set with the
MARGIN statement for a terminal or a terminal-format file.

Format
NOMARGIN

[#chnl-exp ]

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number associated
with a file. It must be immediately preceded by a number sign (#).

Remarks

When you specify

NOMARGIN, the right margin is set to 132.

Chnl-exp, if specified, must be an open terminal-format file or a terminal.
3.

If you do not specify a channel, VAX BASIC sets the margin on the
controlling terminal to 132.

The NOMARGIN statement applies to the specified channel only while

the channel is open. If you close the channel and then reopen it, VAX
BASIC uses the default margin of 72.

4-248

Statements and Functions

NOMARGIN

Example

OPEN

"EMP.DAT"

NOMARGIN

FOR

OUTPUT AS

Statements and Functions

4-249

NUM

NUM
The NUM function returns the row number of the last data element

transferred into an array by a MAT I/O statement.

Format

int-var = NUM

Syntax Rules

None.

Remarks

NUM returns a value of zero if it is invoked before VAX BASIC has
executed any MAT I/O statements.

For a two-dimensional array, NUM returns an integer specifying the
row number of the last data element transferred into the array. For a
one-dimensional array, NUM returns the number of elements entered.

The value returned by the NUM function is an integer of the default
size.

4-250

Statements and Functions

NUM

Example

OPEN

"STU ACCT"

FOR INPUT AS

DIM stu_rec$(3,3)
MAT

INPUT #2,

"Row

"Column

stu_rec$

count

=";NUM

number

=";NUM2

Output
Row

count

Column

number =

Statements and Functions

4-251

NUM2

NUM2
The NUM2 function returns the column number of the last data element
transferred into an array by a MAT I/0O statement.

Format
int-var = NUM2

Syntax Rules

None.

Remarks

NUM2 returns a value of zero if it is invoked before VAX BASIC
has executed any MAT I/O statements or if the last array element
transferred was in a one-dimensional list.

The NUM2 function returns an integer specifying the column number of

the last data element transferred into an array.
3.

The value returned by the NUM2 function is an integer of the default

size.

4-252

Statements and Functions

NUM2

Example

OPEN

"STU_ACCT"

FOR

INPUT

DIM stu_rec$
(3, 3)
MAT

INPUT

#2,

"Row

"Column

stu_rec$

count

=";NUM

number

=";NUM2

Output
Row

count

Column number =

Statements and Functions

4-253

NUMS$

NUM$
The NUMS$ function evaluates a numeric expression and returns a string of
characters in PRINT statement format, with leading and trailing spaces.

Format

str-var = NUM$ (num-exp)

Syntax Rules

None.

Remarks

If num-exp is positive, the first character in the string expression is a
space. If num-exp is negative, the first character is a minus sign (-).

The NUMS$ function does not include trailing zeros in the returned

string. If all digits to the right of the decimal point are zeros, NUM$

omits the decimal point as well.

When num-exp is a floating-point variable and has an integer portion of
six decimal digits or less (for example, 1234.567), VAX BASIC rounds
the number to six digits (1234.57). If num-exp has seven decimal digits
or more, VAX BASIC rounds the number to six digits and prints it in E
format.

4-254

When num-exp is between 0.1 and 1 and contains more than six digits,
VAX BASIC rounds it to six digits. When num-exp is smaller than 0.1,
VAX BASIC rounds it to six digits and prints it in E format.

If num-exp is a longword integer, the returned string can have up to 10
digits.

Statements and Functions

NUMS$

If num-exp is a DECIMAL value, the returned string can have up to 31

digits.
7.

The last character in the returned string is a space.

Example

DECLARE

STRING number

number = NUMS$ (34.5500/31.8)
PRINT

number

Output
1.08648

Statements and Functions

4-255

NUM1$

NUM1$
The NUM1$ function changes a numeric expression to a numeric character
string without leading and trailing spaces and without rounding.

Format

str-var = NUM1$ (num-exp)

Syntax Rules

None.

Remarks

The NUM1$ function returns a string consisting of numeric characters
and a decimal point that corresponds to the value of num-exp. Leading

The NUM1$ function returns a maximum of

and trailing spaces are not included in the returned string.

4-256

3 digits for BYTE integers

5 digits for SINGLE floating-point numbers and WORD integers

10 digits for LONG integers

16 digits for DOUBLE floating-point numbers

15 digits for GFLOAT floating-point numbers

33 digits for HFLOAT floating-point numbers

31 digits for DECIMAL numbers

The NUM1$ function does not support E-format notation.

Statements and Functions

NUM1$

Example

DECLARE

STRING number

number = NUM1$(PI/2)
PRINT number

Output
1.5708

Statements and Functions

4-257

ON ERROR GO BACK

ON ERROR GO BACK
Under certain conditions, an ON ERROR GO BACK statement executed in a
subprogram or DEF function transfers control to the calling program.
NOTE
The ON ERROR GO BACK statement is supported for
compatibility with other DIGITAL BASICs. For new program

development, DIGITAL recommends that you use WHEN blocks.

Format

{ N ERroR ) 90 BACK
ONERROR

Syntax Rules

The ON ERROR GO BACK statement is illegal inside a protected region
or within an attached or detached handler. Use the EXIT HANDLER
statement instead.

Remarks

If there is no error outstanding, execution of an ON ERROR GO BACK
statement causes subsequent errors to return control to the calling
program’s error handler.

If there is an error outstanding, execution of an ON ERROR GO BACK
statement immediately transfers control to the calling program’s error
handler.

4-258

Statements and Functions

ON ERROR GO BACK

By default, DEF functions and subprograms re-signal errors to the
calling program.
The ON ERROR GO BACK statement remains in effect until the
program unit completes execution, until VAX BASIC executes another
ON ERROR statement, or until VAX BASIC enters a protected region.
An ON ERROR GO BACK statement executed in the main program is

equivalent to an ON ERROR GOTO 0 statement.
If a main program calls a subprogram named SUBI1, and SUB1 calls
the subprogram named SUB2, an ON ERROR GO BACK statement
executed in SUB2 transfers control to SUB1’s error handler when an

error occurs in SUB2. If SUB1 also has executed an ON ERROR GO
BACK statement, VAX BASIC transfers control to the main program’s
error handling routine.
For current program development, see the WHEN ERROR statement.

DIGITAL does not recommend that you mix ON ERROR statements

with protected regions in the same program unit. For more information,

see the VAX BASIC User Manual.

Example

ERR =

THEN

RESUME

err_ hand

ELSE

ON ERROR GO BACK
END

Statements and Functions

4-259

ON ERROR GOTO

ON ERROR GOTO
The ON ERROR GOTO statement transfers program control to a specified
line or label in the current program unit when an error occurs under certain

conditions.

NOTE
The ON ERROR GOTO statement is supported for compatibility
with other DIGITAL BASICs. For new program development,

DIGITAL recommends that you use WHEN blocks.

Format

{ ON ERROR } { GOTO } target
ONERROR ) [ GO TO

Syntax Rules

You cannot specify an ON ERROR GOTO statement within a protected
region or handler.

Target must be a valid VAX BASIC line number or label and must exist
in the same program unit as the ON ERROR GOTO statement.

If an ON ERROR GOTO statement is in a DEF function, {arget must
also be in that function definition.

4-260

Statements and Functions

ON ERROR GOTO

Remarks
VAX BASIC transfers program control to a specified line number or label
under two conditions:

If an error does not occur within the protected region of WHEN
block.

If an error occurs within the protected region of a WHEN block and
was propagated by the handler associated with the WHEN block.

Execution of an ON ERROR GOTO statement causes subsequent errors

to transfer control to the specified target.

The ON ERROR GOTO statement remains in effect until the program
unit completes execution or until VAX BASIC executes another ON
ERROR statement.

VAX BASIC does not allow recursive error handling. If a second error
occurs during execution of an error-handling routine, control passes to
the VAX BASIC error handler and the program stops executing.
For current program development, see the WHEN ERROR statement.
DIGITAL does not recommend that you mix ON ERROR statements with

protected regions within the same program unit. For more information,
see the VAX BASIC User Manual.

Statements and Functions

4-261

ON ERROR GOTO

Example

SUB

LIST

DECLARE

(STRING A)
STRING B

ON ERROR GOTO err_block
OPEN A FOR

INPUT AS FILE

Input_loop:

LINPUT
PRINT

GOTO

#1,

Input_ loop

err_block:
IF

(ERR=11%)

THEN

#1%

RESUME done
ELSE
ON ERROR GOTO O

END

done:
END

4-262

SUB

Statements and Functions

ON ERROR GOTO 0

ON ERRORGOTOO
The ON ERROR GOTO 0 statement disables ON ERROR error handling and
passes control to the VAX BASIC error handler when an error occurs.
NOTE

The ON ERROR GOTO 0 statement is supported for compatibility
with other DIGITAL BASICs. For new program development,
DIGITAL recommends that you use WHEN blocks.

Format

{ON ERROR } {GOTO }0
ONERROR J | GOTO

Syntax Rules
VAX BASIC does not allow you to specify an ON ERROR GOTO 0 statement
within an attached or detached handler or within a protected region.

Remarks

If an error is outstanding, execution of an ON ERROR GOTO 0
statement immediately transfers control to the VAX BASIC error
handler. The VAX BASIC error handler will report the error and exit
the program.

If there is no error outstanding, execution of an ON ERROR GOTO
0 statement causes subsequent errors to transfer control to the VAX
BASIC error handler.

Statements and Functions

4-263

ON ERROR GOTO 0

When an ON ERROR GOTO 0 statement is executed, control is
transferred to the VAX BASIC error handler if an error did not occur

within the protected region of a WHEN block.

If an error occurs within the protected region of a WHEN block and

was propagated by the handler associated with the WHEN block, VAX

BASIC transfers control to the specified line number or label contained
in the subprogram or DEF.
5.

For current program development, see the WHEN ERROR statement.

DIGITAL does not recommend that you mix ON ERROR statements
with attached or detached handlers within the same program unit. For
more information, see the VAX BASIC User Manual.

Example

ON ERROR GOTO err_ routine
FOR

10%

"Please

type

a number"

INPUT A
NEXT

err routine:
IF

ERR =

THEN

RESUME
ELSE

ON ERROR GOTO 0
END

Output
Please

type

a number

2
$BAS-F-ILLUSADEV,

Illegal

~BAS-I-ON_CHAFIL,

channel

-RMS-F-DEV,

device

name

for
for

device
file

SYSSINPUT: [TUTTI]SYSINPUT.DAT;
at

error

-BAS-I-FROLINMOD,

4-264

usage

Statements and Functions

from

line

inappropriate

module

BADUSER

user

device

type

00000632

for

operation

ON...GOSUB

ON...GOSUB
The ON...GOSUB statement transfers program control to one of several
subroutines, depending on the value of a control expression.

Format

int-exp GOSUB target,...

[ OTHERWISE target |

Syntax Rules

Int-exp determines which target VAX BASIC selects as the GOSUB
argument. If int-exp equals 1, VAX BASIC selects the first target. If
int-exp equals 2, VAX BASIC selects the second target, and so on.

Target must be a valid VAX BASIC line number or label and must exist
in the current program unit.

Remarks

Control cannot be transferred into a statement block (such as
FOR..NEXT, UNTIL.. NEXT, WHILE.. NEXT, DEF...END DEF,
SELECT...END SELECT, WHEN...END WHEN, or HANDLER...END
HANDLER).

If there is an OTHERWISE clause, and if int-exp is less than 1 or greater
than the number of targets in the list, VAX BASIC selects the target of
the OTHERWISE clause.

If there is no OTHERWISE clause, and if int-exp is less than 1 or
greater than the number of targets in the list, VAX BASIC signals “ON
statement out of range” (ERR=58).

If a target specifies a nonexecutable statement, VAX BASIC transfers
control to the first executable statement that lexically follows the target.
Statements and Functions

4-265

ON...GOSUB

You can only use the ON...GOSUB statement inside a handler if all the
targets are contained within the handler.

If you fail to handle an exception that occurs while an ON...GOSUB
statement in the body of a subroutine is executing, the exception is

handled by the default error handler. The exception is not handled by
any WHEN block surrounding the ON...GOSUB statement that invoked
the subroutine.

You can specify the ON...GOSUB statement inside a WHEN block if the
ON...GOSUB target is in the same protected region, an outer protected
region, or in a non-protected region.

You cannot specify an ON...GOSUB statement inside a WHEN block if

the ON...GOSUB target already resides in another protected region that

does not contain the most current protected region.
9.

The target cannot be more than 32767 bytes away from the ON...GOSUB
statement.

Example

100

INPUT

"Please enter

ON A%

GOSUB

1000,

GOTO done

1000

"That was

a 2"

"That was

a 3"

RETURN

2000

PRINT
RETURN

3000

PRINT
RETURN

err routine:
PRINT

"Out

RETURN

done:
END PROGRAM

4-266

Statements and Functions

2000,

range:

or
3000

3";

OTHERWISE

err_ routine

ON...GOTO

ON...GOTO
The ON...GOTO statement transfers program control to one of several lines
or targets, depending on the value of a control expression.

Format

ON int-exp { GO TO } target,... [ OTHERWISE tfarget |
GOTO

Syntax Rules

Int-exp determines which target VAX BASIC selects as the GOTO
argument. If int-exp equals 1, VAX BASIC selects the first target. If
int-exp equals 2, VAX BASIC selects the second target, and so on.
Target must be a valid VAX BASIC line number or a label and must
exist in the current program unit.

Remarks

Control cannot be transferred into a statement block (such as
FOR..NEXT, UNTIL..NEXT, WHILE..NEXT, DEF...END DEF,

SELECT...END SELECT, WHEN...END WHEN, or HANDLER...END
HANDLER).

2. If there is an OTHERWISE clause, and if int-exp is less than one or

greater than the number of targets in the list, VAX BASIC transfers
control to the target of the OTHERWISE clause.

If there is no OTHERWISE clause, and if int-exp is less than 1 or greater
than the number of line numbers in the list, VAX BASIC signals “ON
statement out of range” (ERR=58).

Statements and Functions

4-267

ON...GOTO

If a target specifies a nonexecutable statement, VAX BASIC transfers
control to the first executable statement that lexically follows the target.

You can only use the ON...GOTO statement inside a handler if all the
targets are contained within the handler.

You can specify the ON...GOTO statement inside a WHEN block if the

ON...GOTO target is in the same protected region, an outer protected
region, or in a non-protected region.

You cannot specify an ON...GOTO statement inside a WHEN block if the
ON...GOTO target already resides in another protected region that does
not contain the most current protected region.

Example

INDEX%

GOTO

700,800,900

finish:
END

4-268

PROGRAM

Statements and Functions

OTHERWISE

finish

OPEN

OPEN
The OPEN statement opens a file for processing. It transfers user-specified

file characteristics to VAX Record Management Services (RMS) and verifies
the results.

Format

OPEN file-specT [ FOR INPUT

FOR OUTPUT

] AS [ FILE ] f#] chnl-exp

[, open-clause |]...
open-clause:

ACCESS

APPEND
READ
WRITE
MODIFY

)

SCRATCH

ALLOW {

NONE

READ
WRITE
MODIFY

| BUFFER int-exp4 |

[ CONTIGUOUS |
| DEFAULTNAME file-spec2 |

[ EXTENDSIZE int-exp5 |
[ FILESIZE int-exp2 |
Statements and Functions

4—269

OPEN

| MAP map-name |

RELATIVE
[ ORGANIZATION ] { SEQUENTIAL
UNDEFINED

| VIRTUAL

| RECORDSIZE int-exp1 |

RECORDTYPE

|l-'Tz)SI;iI“TFIAN
NONE
ANY

| TEMPORARY |
| UNLOCK EXPLICIT |

| USEROPEN func-name |
[ WINDOWSIZE int-exp3 ]
Sequential Files Only

[ BLOCKSIZE int-exp8 ]

[ BUCKETSIZE int-exp9 |

4-270

Statements and Functions

|
J

STREAM
[VARIABLE ]
FIXED

OPEN

Indexed Files Only

" ALTERNATE [ KEY ] key-clause [ DUPLICATES ] [ CHANGES ]

ASCENDING

DESCENDING

]

| CONNECT chnl-exp2 |

PRIMARY [ KEY] key-clause[DUPLICATES] [ AESENDING

]

key-clause:

(int-unsubs-var
decimal-unsubs-var
str-unsubs-var
(str-unsubs-var1 ,... str-unsubs-var8
)
. quad-record-group

Syntax Rules

File-specl specifies the file to be opened and associated with chnl-exp.

It can be any valid string expression and must be a valid VMS file
specification. VAX BASIC passes these values to RMS without editing,
alteration, or validity checks.

VAX BASIC does not supply any default file specifications, unless you
include the DEFAULTNAME clause in the OPEN statement.

The FOR clause determines how VAX BASIC opens a file.
*

If you open a file with FOR INPUT, the file must exist or VAX

BASIC signals an error.
*

If you open a file with FOR OUTPUT, VAX BASIC creates the file

if it does not exist. If the file does exist, VAX BASIC creates a new

version of the file.

Statements and Functions

4-271

OPEN

If you do not use FOR INPUT or FOR OUTPUT to open an indexed

file, you must specify a primary key in the event the file does not
exist.

If you do not specify either FOR INPUT or FOR OUTPUT, VAX
BASIC tries to open an existing file. If there is no such file, VAX
BASIC creates one.

Chnl-exp is a numeric expression that specifies a channel number to be
associated with the file being opened. It can be preceded by an optional
number sign (#) and must be in the range of 1 through 119. Note that
channels 100 through 119 are usually reserved for allocation by the RTL
routines, LIB§GET_LUN and LIB$FREE_LUN.

A statement that accesses a file cannot execute until you open that file

The OPEN statement does not retrieve records.

and associate it with a channel.

Remarks

Channel #0, the terminal, is always open. If you try to open channel

zero, VAX BASIC signals the error “Illegal I/0 channel” (ERR=46).

If a program opens a file on a channel already associated with an open
file, VAX BASIC closes the previously opened file and opens the new one.

The ACCESS clause determines how the program can use the file.
e ACCESS READ allows only FIND, GET, or other input statements
on the file. The OPEN statement cannot create a file if the ACCESS
READ clause is specified.

4-272

ACCESS WRITE allows only PUT, UPDATE, or other output

ACCESS MODIFY allows any I/O statement except SCRATCH on

ACCESS SCRATCH allows any I/O statement valid for a sequential

statements on the file.

the file. ACCESS MODIFY is the default.
or terminal-format file.

Statements and Functions

OPEN

ACCESS APPEND is the same as ACCESS WRITE for

sequential
after the last

files, except that VAX BASIC positions the file pointer

record when it opens the file. You cannot use ACCES
S APPEND on
relative or indexed files.

The ALLOW clause can be used in the OPEN stateme

nt to specify file
sharing of relative, indexed, sequential, and virtual files.
*

ALLOW NONE lets no other users access the file. This
is the default
if any access other than READ is specified. Note that
you must have
write access to the file in order to specify ALLOW NONE.

ALLOW READ lets other users have read access to the

ALLOW WRITE lets other users have write access to

ALLOW MODIFY lets other users have unlimited access

file.

the file.

The BLOCKSIZE clause specifies the physical block size

to the file.

of magnetic

tape files. The BLOCKSIZE clause can be used for
magnetic tape

only.
®

The value of int-exp8 is the number of records in a block.

Therefore,

the block size in bytes is the product of the RECORDSIZE
BLOCKSIZE value.
®

files

and the

The default blocksize is one record.

The BUCKETSIZE clause applies only to relative and indexed
specifies the size of an RMS bucket in terms of the number

one bucket should hold.

files. It

of records

The value of int-exp9 is the number of records in a bucket.

®*

The default is one record.

The BUFFER clause can be used with all file organizations
except
UNDEFINED.
*

For RELATIVE and INDEXED files, int-exp4 specifies the

device or file buffers RMS uses for file processing.
*

number of

For SEQUENTIAL files, int-exp4 specifies the size of the
buffer; for
example, BUFFER 8 for a SEQUENTIAL file sets the buffer
size to
eight 512-byte blocks.
DIGITAL recommends that you accept the system defaults

the defaults with the DCL SET RMS_DEFAULT command.

or change

Statements and Functions

4-273

OPEN
The CONTIGUOUS clause causes RMS to try to create the file as a
contiguous-best-try sequence of disk blocks. The CONTIGUOUS clause
does not affect existing files or nondisk files.

The CONTIGUOUS clause does not guarantee that the file will occupy
contiguous disk space. If RMS can locate the file in a contiguous area,
it will do so. However, if there is not enough free contiguous space for
a file, RMS allocates the largest possible contiguous space and does not
signal an error. See the VMS Record Management Services Manual for
more information on contiguous disk allocation.

10. The CONNECT clause permits multiple record streams to be connected

to the file.

The CONNECT clause must specify an INDEXED file already

You cannot connect to a connected channel; you can connect only to

e
e

You can connect more than one stream to an open channel.
All clauses of the two files to be connected must be identical except

opened on chnl-exp2 with the primary OPEN statement.
the initially opened channel.

MAP, CONNECT, and USEROPEN.

Do not use the CONNECT clause when accessing files over DECnet
or VAX BASIC will signal the error "Cannot open file" (ERR=162).
ion.
11. The DEFAULTNAME clause lets you supply a default file specificat
the
in
file-spec2
ion,
specificat
file
complete
a
not
is
file-specl
If
e

DEFAULTNAME clause supplies the missing parts. For example:
10

INPUT ’'FILE NAME’; fnam$

OPEN fnam$ FOR INPUT AS FILE #1%,

DEFAULTNAME "USERS$SSDISK: .DAT"

If you type “ABC” for the file name, VAX BASIC tries to open

USER$$DISK:[ JABC.DAT.

which RMS
int-exp5 is
of
value
extends a file after its initial allocation is filled. The
on an
effect
no
has
in 512-byte disk blocks. The EXTENDSIZE clause

12. The EXTENDSIZE clause lets you specify the increment by

existing file.

13. The FILESIZE clause lets you pre-extend a new file to a specified

e
e
4-274

The value of int-exp2 is the initial allocation of disk blocks.
The FILESIZE clause has no effect on an existing file.

Statements and Functions

size.

OPEN

14. The MAP clause specifies that a previously declared map is associated
with the file’s record buffer. The MAP clause determines the record
buffer’s address and length unless overridden by the RECORDSIZE
clause.

The size of the specified map must be as large or larger than the
longest record length or maximum record size. For files with a fixed
record size, the specified map must match exactly.

The size of the largest MAP with the same map name in the current
program unit becomes the file’s record size if the OPEN statement
does not include a RECORDSIZE clause.

DIGITAL recommends that you do not use both the MAP and
RECORDSIZE clauses in an OPEN statement. However, if you
do use both the MAP and RECORDSIZE clauses in an OPEN
statement, the following rules apply:

—

The RECORDSIZE clause overrides the record size set by the
MAP clause.

—

The map must be as large or larger than the specified
RECORDSIZE.

If there is no MAP clause, the record buffer space that VAX BASIC
allocates is not directly accessible. Therefore, MOVE statements are
needed to access data in the record buffer.

You must have a MAP clause when creating an indexed file; you
cannot use KEY clauses without MAP statements because keys serve
as offsets into the buffer.

The size of the specified map cannot exceed 32767 bytes.
15. The NOREWIND clause controls tape positioning on magnetic tape

files. The NOREWIND clause can be used for magnetic tape files only.
If you specify NOREWIND, the OPEN statement does not position
the tape at the beginning. Your program can search for records from
the current position.

If you do not specify either ACCESS APPEND or NOREWIND,
the OPEN statement positions the tape at its beginning and then
searches for the file.

Statements and Functions

4-275

OPEN

16. The

NOSPAN clause specifies that sequential records cannot cross
block boundaries.
*

SPAN specifies that records can cross block boundaries. SPAN is the

default.

The NOSPAN clause does not affect nondisk files.

17. The ORGANIZATION clause specifies the file organization. When
present, it must precede all other clauses. When you specify
an ORGANIZATION clause, you must also specify one of the
following organization options: VIRTUAL, UNDEFINED, INDEXED,

SEQUENTIAL or RELATIVE. Specify ORGANIZATION UNDEFINED if
you do not know the actual organization of the file. If you do not specify
an ORGANIZATION clause VAX BASIC opens a terminal format file by
default.
*

When you specify ORGANIZATION VIRTUAL, you create a
sequentially fixed file with a record size of 512 (or a multiple of 512).

You can then access the file with the FIND, GET, PUT, or UPDATE
statements or through one or more virtual arrays. VAX BASIC

allows you to overwrite existing records in a file not containing
virtual arrays and opened as ORGANIZATION VIRTUAL by using

the PUT statement with a RECORD clause. All other organizations
require the UPDATE statement to change an existing record.
DIGITAL recommends that you also use the

UPDATE statement to change existing records in VIRTUAL files
that do not contain virtual arrays.

When you do not know the organization of a file, you can open

a file for input and specify ORGANIZATION UNDEFINED. You
can then use the FSP$ function or a USEROPEN routine to
- determine the attributes of the file. You will usually want to
specify the RECORDTYPE ANY clause with the ORGANIZATION
UNDEFINED clause. The combination of these two clauses should
allow you to access any file sequentially.

When you specify ORGANIZATION INDEXED, you create an
indexed file whose data records are sorted in ascending or descending

order according to a primary index key value.

—

The index keys you specify determine the order in which records

are stored.

4-276

Statements and Functions

OPEN

—

Index keys must be variables declared in a MAP statement
associated with the OPEN statement for the file.

—

VAX BASIC allows you to specify an indexed file as either
variable or fixed length.

When you specify ORGANIZATION SEQUENTIAL, you create a file
that stores records in the order that they are written.

—

Sequential files can contain records of any valid VAX BASIC
record format: fixed-length, variable-length, or stream.

—

If you open an existing file using stream as a record format

option, the file must be one of the following stream record
formats defined by RMS:

STREAM records can be delimited by any special character.

STREAM_LF must be delimited by a line-feed character.

STREAM_CR must be delimited by a carriage return.

If the file is not one of these stream formats, VAX BASIC signals
the error “RECATTNOT, record attributes not matched”.
*

When you specify ORGANIZATION RELATIVE, you create a file that

contains a series of records that are numbered consecutively. VAX
BASIC allows you to specify either fixed-length or variable-length

records.

Ifyou omit the ORGANIZATION clause entirely, a terminal-format
file is opened.
—

Terminal-format files are implemented as RMS sequential
variable files and store ASCII characters in variable-length

records.

—

Carriage control is performed by the operating system: the record

does not contain carriage returns or line feeds.
—

You use essentially the same syntax to access terminal-format

files as when reading from or writing to the terminal (INPUT
and PRINT).

18. The PRIMARY KEY clause lets you specify an indexed file’s key.

You must specify a primary key when opening an indexed file. The

Statements and Functions

4-277

OPEN
ALTERNATE KEY clause lets you specify up to 254 alternate keys.
The ALTERNATE KEY clause is optional.

RMS creates one index list for each primary and alternate 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.

You can specify each key as ASCENDING or DESCENDING;
ASCENDING is the default. In an ASCENDING key, lower key
values occur toward the beginning of the index. In a DESCENDING
key, higher key values occur toward the beginning of the index.
The keys you specify determine the order in which records in the
file are stored. All keys must be variables declared in the file’s

corresponding MAP statement. The position of the key in the MAP
statement determines its position in the record. The data type and
size of the key are as declared in the MAP statement.

A key can be an unsubscripted string, a WORD, LONG, or packed
decimal variable, or a record or group which is exactly eight bytes
long.

You can also create a segmented index key for string keys by
separating the string variable names with commas and enclosing
them in parentheses. You can then reference a segment of the
specified key by referencing one of the string variables instead of the
entire key. A string key can have up to eight segments.
The order of appearance of keys determines key numbers. The
primary key, which must appear first, is key #0. The first alternate
key is #1, and so on.

DUPLICATES in the PRIMARY and ALTERNATE key clauses

specifies that two or more records can have the same key value. If
you do not specify DUPLICATES, the key value must be unique in
all records.

CHANGES in the ALTERNATE KEY clause specifies that you can
change the value of an alternate key when updating records. If
you do not specify CHANGES when creating the file, you cannot
change the value of a key. You cannot specify CHANGES with the
PRIMARY KEY clause.

KEY clauses are optional for existing files. If you do specify a key, it
must match a key in the file.
4-278

Statements and Functions

OPEN

19. The RECORDTYPE clause specifies the file’s record attributes.

LIST specifies implied carriage control, <CR>. This is the default for
all file organizations except VIRTUAL.

FORTRAN specifies a control character in the record’s first byte.
NONE

specifies no attributes. This is the default for VIRTUAL files.

If you open a terminal-format file with RECORDTYPE NONE, you
must explicitly insert carriage control characters into the records

your program writes to the file.

ANY specifies a match with any file attributes when opening an

existing file. If you create a new file, ANY is treated as LIST for

all organizations except VIRTUAL. For VIRTUAL, it is treated as
NONE.
20. The RECORDSIZE clause specifies the file’s record size. Note that
there are restrictions on the maximum record size allowed for various
file and record formats. See the VMS Record Management Services

Manual for more information.

For fixed-length records, int-expl specifies the size of all records.

For variable-length records, int-expl specifies the size of the largest

record.

DIGITAL recommends that you do not use both the MAP and

RECORDSIZE clauses in an OPEN statement. However, if you
do use both the MAP and RECORDSIZE clauses in an OPEN
statement, the following rules apply:

The RECORDSIZE clause overrides the record size set by the

MAP clause.
—

The map must be as large or larger than the specified
RECORDSIZE.

If you specify a MAP clause but no RECORDSIZE clause, the record

size is equal to the map size.

If there is no MAP clause, the RECORDSIZE clause determines the

record size.

When creating a relative or indexed file, you must specify either a

MAP or RECORDSIZE clause. Otherwise, VAX BASIC signals an
error.

For fixed files, the record size must match exactly.

Statements and Functions

4-279

OPEN
If you do not specify a RECORDSIZE clause when opening an
existing file, VAX BASIC retrieves the record size value from the file.

When you print to a terminal-format file, you must supply a record
size if the margin is to exceed 72 characters. For example, if you

want to print a 132-character line, specify RECORDSIZE 132 or use
the MARGIN and NOMARGIN statements.

When creating SEQUENTIAL files, VAX BASIC supplies a default
record size of 132.

The record size is always 512 for VIRTUAL files, unless you specify
a RECORDSIZE.

21. The TEMPORARY clause causes VAX BASIC to delete the output file

as soon as the program closes it.

22. The UNLOCK EXPLICIT clause allows you to retain locks on records

until they are explicitly unlocked.

The type of lock you impose on a record with a GET or FIND
statement remains in effect until you explicitly unlock the record or
file with a FREE or UNLOCK statement or until you close the file.

If you specify UNLOCK EXPLICIT, and do not specify an ALLOW
clause with a GET or FIND statement, VAX BASIC imposes the
ALLOW NONE lock by default and the next GET or FIND operation
does not unlock the previously locked record.
You must open a file with UNLOCK EXPLICIT before you can

explicitly lock records with the ALLOW clause on GET and FIND
statements. See the sections on GET and FIND in this manual and
the VAX BASIC User Manual for more information on explicit record
locking and unlocking.

23. The USEROPEN clause lets you open a

file with your own FUNCTION

subprogram.

Func-name must be a separately compiled FUNCTION subprogram
and must conform to FUNCTION statement rules for naming
subprograms.

You do not need to declare the useropen routine as an external
function.

4-280

Statements and Functions

OPEN

VAX BASIC calls the user program after it fills the FAB (File Access

Block), the RAB (Record Access Block), and the XABs (Extended
Attribute Blocks). The subprogram must issue the appropriate RMS
calls, including $OPEN and $CONNECT, and return the RMS status
as the value of the function. See the VAX BASIC User Manual for
more information on the USEROPEN routine.

NOTE
Future releases of the Run-Time Library may alter the use
of some VAX RMS fields. Therefore, you may have to alter
your USEROPEN procedures accordingly.

24. The WINDOWSIZE clause followed by int-exp3 lets you specify the

number of block retrieval pointers you want to maintain in memory for

the file.

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 I/O

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 any one time is

determined by the system default or by the WINDOWSIZE clause.

The default number of retrieval pointers on VMS systems is 7.

A value of zero specifies the default number of retrieval pointers. A
value of —1 means to map the entire file, if possible. Values from
—128 through -2 are reserved.

Examples

Example 1
OPEN

"FILE.DAT"

FILE

Statements and Functions

4-281

OPEN

Example 2
2

OPEN "INPUT.DAT" FOR INPUT AS FILE #4,
ORGANIZATION SEQUENTIAL FIXED,
RECORDSIZE 200,
MAP ABC,

ACCESS MODIFY

ALLOW MODIFY,

OPEN Newfile$ FOR OUTPUT AS FILE #3,
&

Emp_ name,

STRING last name = 15,

(SEGKEY)

MI = 1,

DEFAULTNAME "USERS$SDISK: .DAT",
PRIMARY KEY Last$ DUPLICATES,
ALTERNATE KEY First$ CHANGES

MAP

INDEXED VARIABLE,
MAP

first name = 15

ORGANIZATION

INDEXED,

PRIMARY KEY

(last name,

MAP

OPEN "NAMES.IND" FOR OUTPUT AS FILE #1,
first name,

MI),

SEGKEY

Example 3
MAP

(OWNERKEYS)

STRING owner id = 6,

last _name = 25,

no = 7,
dog_reg

first_name = 20

ALTERNATE KEY (last name) DUPLICATES CHANGES,
ALTERNATE (dog reg no) DESCENDING,

INDEXED,

(owner_id),

ORGANIZATION

PRIMARY KEY

OPEN "OWNERS.IND" FOR OUTPUT AS FILE #1,

MAP OWNERKEYS

The MAP statement describes the three string variables used as index keys
in the file OWNERS.IND. The OPEN statement declares an indexed file
with two alternate keys in addition to the primary key. The alternate key
dog_reg_no is a DESCENDING key; the other keys are ASCENDING by
default.

4-282

Statements and Functions

OPTION

OPTION
The OPTION statement allows you to set compilation qualifiers such as

default data type, size, and scale factor. You can also set compilation
conditions such as severity of run-time errors to handle, constant type

checking, subscript checking, overflow checking, decimal rounding, and

setup in a source program. The options you set affect only the program
module in which the OPTION statement occurs.

Format

OPTION

option-clause,...
( ANGLE=angle-clause

HANDLE=handle-clause
CONSTANT TYPE =const-type-clause
OLD VERSION = CDD

option-clause:

{ TYPE=type-clause

)

SIZE=size-clause

SCALE=int-const

l { ACTIVE
|

angle-clause:

LINACTIVE

{ DEGREES }
RADIANS

BASIC
handle-clause:

} = aclive-clause

”

SEVERE
ERROR

‘

WARNING

INFORMATIONAL |,

Statements and Functions

4-283

OPTION

const-type-clause:

| INTEGER }
REAL

DECIMAL

type-clause:

size-clause:

¥size-item }
(size-item,...

size-item:

int-clause:
real-clause:

aclive-clause:

4-284

Statements and Functions

INTEGER
REAL
EXPLICIT
DECIMAL

REAL real-clause
DECIMAL(d,s)
BYTE

WORD }
LONG

SINGLE

{

}
active-item
(active-item,...)

DOUBLE |

GFLOAT
HFLOAT

OPTION

( INTEGER OVERFLOW

active-item:

)

DECIMAL OVERFLOW

! SETUP

DECIMAL ROUNDING

. SUBSCRIPT CHECKING )

Syntax Rules

None.

Remarks

Option-clause specifies the compilation qualifiers to be in effect for the
program module.

Angle-clause specifies whether angles are to be evaluated in radians
or in degrees. If you do not specify an angle-clause, VAX BASIC uses

radians as the default.
3.

Handle-clause specifies the severity level of the errors which are to be

handled by an error handler.
*

If you do not specify an OPTION HANDLE statement, VAX BASIC
uses OPTION HANDLE = BASIC as the default. Only those errors

that are trappable and that map onto a VAX BASIC ERR value will
transfer control to the current error handler. See the VAX BASIC

User Manual for a list of VAX BASIC run-time errors.
e

If you specify a severity level, all trappable and non-trappable
errors of the specified severity or less transfer control to the current

error handler. This includes non-BASIC errors. For example,
OPTION HANDLE = ERROR implies ERROR, WARNING, and
INFORMATIONAL errors but not SEVERE errors.

Statements and Functions

4-285

OPTION

If you specify OPTION HANDLE = SEVERE, you can handle
fatal errors. However, in most cases, a fatal error indicates that
the program environment is badly corrupted and you should not
continue program execution.

Const-type-clause specifies the data type for all constants that do not
end in a data type suffix or are not in explicit literal notation with a
data type supplied.

Type-clause sets the default data type for variables that have not
been explicitly declared and for constants if no constant type clause is

specified. You can specify only one type-clause in a program module.
Size-clause sets the default data subtypes for floating-point, integer,
and packed decimal data. Size-item specifies the data subtype you want
to set. You can specify an INTEGER, REAL or DECIMAL size-item, or
an combination. Multiple size-items in an OPTION statement must be
enclosed in parentheses and separated by commas.

SCALE controls the scaling of double precision floating-point variables.
Int-const specifies the power of 10 you want as the scaling factor. It
must be an integer between 0 and 6 or VAX BASIC signals an error. See
the description of the SCALE command in Chapter 2 of this manual for
more information on scaling.

OLD VERSION = CDD is provided for compatibility with previous
versions of BASIC. When bounds are specified in the CDD array, VAX
BASIC changes the lower bound to zero and adjusts the upper bound of
the array. By default, if you do not specify OLD VERSION = CDD, VAX
BASIC compiles the program with the bounds specified in the CDD data
definition.

Active-clause specifies the decimal rounding, integer and decimal
overflow checking, setup, and subscript checking conditions you want in
effect for the program module. Active-item specifies the conditions you
want to set. Multiple active-items in an OPTION statement must be
enclosed in parentheses and separated by commas.

10. You can have more than one option in an OPTION statement, or you can

use multiple OPTION statements in a program module. However, each
OPTION statement must lexically precede all other source code in the
program module, with the exception of comment fields, REM, PICTURE,
PROGRAM, SUB, FUNCTION, and OPTION statements.

4-286

Statements and Functions

OPTION

11. OPTION statement specifications apply only to the
program

in which the statement appears and affect all variables in
including SUB and FUNCTION parameters.

module

the module,

12. VAX BASIC signals an error in the case of conflicting

options. For
example, you cannot specify more than one type-clause or
SCALE factor
in the same program unit.

13. If you do not specify a type-clause or a subtype-clause,

the current environment default data types.

14. If you do not specify a scale factor, VAX BASIC uses
environment default scale factor.

VAX BASIC uses

the current

15. ACTIVE specifies the conditions that are to be in effect

for a particular

program module. INACTIVE specifies the conditions
that are not to be

in effect for a particular program module. If a condition does
not appear
in an active-clause, VAX BASIC uses the current environment
default for
the condition.

See the description of the COMPILE command in Chapter 2 of
this
manual and the VAX BASIC User Manual for more informat
ion
on the INTEGER_OVERFLOW, DECIMAL_OVERFLOW,
SETUP,
DECIMAL_ROUNDING, and SUBSCRIPT CHECKING compilat
ion
qualifiers. These qualifiers correspond to active-clause condition
s (INTEGER

OVERFLOW, DECIMAL OVERFLOW, SETUP, DECIMAL ROUNDI
NG, and
SUBSCRIPT CHECKING).

Example

DOUBLE

(DOUBLE

monthly payment,

interest_rate,

LONG

no_of payments,

TYPE

= REAL,

SIZE

SCALE =

(REAL

DOUBLE principle)
OPTION

&
- g)

FUNCTION REAL

DOUBLE,

INTEGER

LONG),

Statements and Functions

4-287

PLACE$

PLACES$S
The PLACE$ function explicitly changes the precision of a numeric string.
PLACES$ returns a numeric string, truncated or rounded, according to the
value of an integer argument you supply.

Format

str-var = PLACES$ (str-exp, int-exp)

Syntax Rules

1. Str-exp specifies the numeric string you want to process. It can contain
an optional minus sign (-), ASCII digits, and an optional decimal point.
2. Int-exp specifies the numeric precision of str-exp. Table 4-5 shows
examples of rounding and truncation and the values of int-exp that
produce them.

Remarks
1. The PLACE$ function does not support E-format notation.
2. If str-exp has more than 60 characters, VAX BASIC signals the error
“Illegal number” (ERR=52).

3. Str-exp is rounded or truncated, or both, according to the value of
int-exp.

4. If int-exp is between —60 and 60, rounding and truncation occur as
follows:

For positive integer expressions, rounding occurs to the right of

the decimal place. For example, if int-exp is 1, rounding occurs one

digit to the right of the decimal place (the number is rounded to
the nearest tenth). If int-exp is 2, rounding occurs two digits to the

4-288

Statements and Functions

PLACES$

right of the decimal place (the number is rounded to the nearest
hundredth), and so on.
If int-exp is zero, VAX BASIC rounds to the nearest unit.

For negative integer expressions, rounding occurs to the left of the
decimal point. If int-exp is —1, for example, VAX BASIC moves the

decimal point one place to the left, then rounds to units. If int-exp is
—2, rounding occurs two places to the left of the decimal point; VAX

BASIC moves the decimal point two places to the left, then rounds
to tens.

If int-exp is between 9940 and 10,060, truncation occurs as follows:
If int-exp is 10,000, VAX BASIC truncates the number at the decimal
point.

If int-exp is greater than 10,000 (10,000 plus n) VAX BASIC
truncates the numeric string n places to the right of the decimal
point. For example, if int-exp is 10,001 (10,000 plus 1), VAX BASIC
truncates the number starting one place to the right of the decimal
point. If int-exp is 10,002 (10,000 plus 2), VAX BASIC truncates the

number starting two places to the right of the decimal point, and
SO on.

If int-exp is less than 10,000 (10,000 minus ), VAX BASIC truncates
the numeric string n places to the left of the decimal point. For
example, if int-exp is 9999 (10,000 minus 1), VAX BASIC truncates

the number starting one place to the left of the decimal point. If
9998 (10,000 minus 2), VAX BASIC truncates starting two places to
the left of the decimal point, and so on.

If int-exp is not between —60 and 60 or 9940 and 10,060, VAX BASIC
returns a value of zero.
If you specify a floating-point expression for int-exp, VAX BASIC
truncates it to an integer of the default size.
Table 4-5 shows examples of rounding and truncation and the values of

int-exp that produce them. The number used is 123456.654321.

Statements and Functions

4-289

PLACES$

Table 4-5:

Rounding and Truncation of 123456.654321
Value

4-290

Int-exp

Effect

Returned

-5

Rounded to 100,000s and truncated

—4

Rounded to 10,000s and truncated

-3

Rounded to 1000s and truncated

123

-2

Rounded to 100s and truncated

1235

-1

Rounded to 10s and truncated

12346

Rounded to units and truncated

123457

Rounded to tenths and truncated

123456.7

Rounded to hundredths and truncated

123456.65

Rounded to thousandths and truncated

123456.654

Rounded to ten-thousandths and truncated

123456.6543

Rounded to hundred-thousandths and truncated

123456.65432

9,995

Truncated to 100,000s

9,996

Truncated to 10,000s

9,997

Truncated to 1000s

123

9,998

Truncated to 100s

1234

9,999

Truncated to 10s

12345

10,000

Truncated to units

123456

10,001

Truncated to tenths

12345.6

10,002

Truncated to hundredths

123456.65

10,003

Truncated to thousandths

123456.654

10,004

Truncated to ten-thousandths

123456.6543

10,005

Truncated to hundred-thousandths

123456.65432

Statements and Functions

PLACES$

Example

DECLARE

STRING

str_exp

str_var

= PLACES (str_exp, 3)

str_exp,

str_var

"9999.9999"

str_ var

Output
10000

Statements and Functions

4-291

POS

POS
The POS function searches for a substring within a string and returns the
substring’s starting character position.

Format

int-var = POS (str-exp1, str-exp2, int-exp)

Syntax Rules

Str-expl specifies the main string.

Str-exp2 specifies the substring.

Int-exp specifies the character position in the main string at which VAX
BASIC starts the search.

Remarks

The POS function searches str-expl, the main string, for the first
occurrence of str-exp2, the substring, and returns the position of the
substring’s first character.

If int-exp is greater than the length of the main string, POS returns a
value of zero.

POS always returns the character position in the main string at which
VAX BASIC finds the substring, with the following exceptions:
e

If only the substring is null, and if int-exp is less than or equal to

If only the substring is null, and if int-exp is equal to or greater
than 1 and less than or equal to the length of the main string, POS

zero, POS returns a value of 1.

returns the value of int-exp.

4-292

Statements and Functions

POS

If only the substring is null and if int-exp is greater than the length
of the main string, POS returns the main string’s length plus 1.

If only the main string is null, POS returns a value of zero.

If both the main string and the substring are null, POS returns 1.

If VAX BASIC cannot find the substring, POS returns a value of zero.
If int-exp is less than 1, VAX BASIC assumes a starting position of 1.

If int-exp does not equal 1, VAX BASIC still counts from the string’s
beginning to calculate the starting position of the substring. That is,

VAX BASIC counts character positions starting at position 1, regardless
of where you specify the start of the search. For example, if you specify
10 as the start of the search and VAX BASIC finds the substring at
position 15, POS returns the value 15.
If you know that the substring is not near the beginning of the string,
specifying a starting position greater than 1 speeds program execution

by reducing the number of characters VAX BASIC must search.

If you specify a floating-point expression for int-exp, VAX BASIC
truncates it to an integer of the default size.

Example

DECLARE

STRING main_str,

sub_str
DECLARE

INTEGER

main_str =

sub_str =

first char

"ABCDEFG"

"DEFG"

first_char = POS(main_str,
PRINT

first char

sub str,

Output
4

Statements and Functions

4-293

PRINT
The PRINT statement transfers program data to a terminal or a

terminal-format file.

Format

[#chnl-exp, ] [ output-list ]

output-list:

[exp ][ { : } exp J... [: ]

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number
associated with a file. It must be immediately preceded by a number
sign (#). If you do not specify a channel, VAX BASIC prints to the
controlling terminal.

QOutput-list specifies the expressions to be printed and the print format
to be used.

Exp can be any valid expression.

A separator character (comma or semicolon) must separate each exp.
Separator characters control the print format as follows:

4-294

A comma (,) causes VAX BASIC to skip to the next print zone before
printing the expression.

A semicolon (;) causes VAX BASIC to print the expression
immediately after the previous expression.

Statements and Functions

Remarks

A terminal or terminal-format file must be open on the specified channel.

(Your current terminal is always open on channel #0.)

A PRINT line has an integral number of print zones. Note, however,
that the number of print zones in a line differs from terminal to
terminal.

The right margin setting, if set by the MARGIN statement, controls the
width of the PRINT line. The default right margin is 72.

The PRINT statement prints string constants and variables exactly as

they appear, with no leading or trailing spaces.
VAX BASIC prints quoted string literals exactly as they appear.
Therefore, you can print quotation marks, commas, and other characters

by enclosing them in quotation marks.
A PRINT statement with no output-list prints a blank line.
An expression in the output-list can be followed by more than one
separator character. That is, you can omit an expression and specify
where the next expression is to be printed by the use of multiple

separator characters. For example:
PRINT

"Name",,"Address

and

";"City"

Output
Name

Address

and City

In this example, the double commas after “Name” cause VAX BASIC
to skip two print zones before printing “Address and ”. The semicolon
causes the next expression, “City”, to be printed immediately after the
preceding expression. Multiple semicolons have the same effect as a

single semicolon.

When printing numeric fields, VAX BASIC precedes each number with a
space or minus sign (—) and follows it with a space.

VAX 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, VAX

BASIC omits the decimal point as well.

Statements and Functions

4-295

10. For REAL numbers (SINGLE, DOUBLE, GFLOAT, and HFLOAT), VAX

BASIC does not print more than six digits in explicit notation. If a
number requires more than six digits, VAX BASIC uses E format and
precedes positive exponents with a plus sign (+). VAX BASIC rounds
a floating-point number with a magnitude between 0.1 and 1.0 to six
digits. For magnitudes smaller than 0.1, VAX BASIC rounds the number
to six digits and prints it in E format.

11. The PRINT statement can print up to

3 digits of precision for BYTE integers

5 digits of precision for WORD integers
10 digits of precision for LONG integers

31 digits of precision for DECIMAL numbers

The string length for STRING values

VAX BASIC prints both INTEGER and DECIMAL values according to
the previous rules. However, for REAL values, VAX BASIC displays a
maximum of 6 digits.

12. If there is a comma or semicolon following the last item in output-list,
VAX BASIC does the following:

When printing to a terminal, VAX BASIC does not generate a line
terminator after printing the last item. The next item printed with a
PRINT statement is printed at the position specified by the separator
character following the last item in the first PRINT statement.

When printing to a terminal-format file, VAX BASIC does not write
out the record until a PRINT statement without trailing punctuation
executes.

13. If no punctuation follows the last item in the output-list VAX BASIC
does the following:

4-296

When printing to a terminal, VAX BASIC generates a line terminator

When printing to a terminal-format file, VAX BASIC writes out the

after printing the last item.

record after printing the last item.

Statements and Functions

14. If a string field does not fit on the current line VAX BASIC does the
following:

When printing string elements to a terminal, VAX BASIC prints as
much as will fit on the current line and prints the remainder on the
next line.

When printing string elements to a terminal-format file, VAX BASIC
prints the entire element on the next line.

15. If a numeric field is the first field in a line, and the numeric field spans

more than one line, VAX BASIC prints part of the number on one line
and the remainder on the next. Otherwise, numeric fields are never split
across lines. If the entire field cannot be printed at the end of one line,
the number is printed on the next line.

16. When a number’s trailing space does not fit in the last print zone, the
number is printed without the trailing space.

Example

"name

"age",

"height

"weight"

Output
name age

height weight

Statements and Functions

4-297

PRINT USING

PRINT USING
The PRINT USING statement generates output formatted according to a
format string (either numeric or string) to a terminal or a terminal-format
file.

Format

PRINT [ #chnl-exp ] USING str-exp{ : }output-/ist

output-list:

[ exp ][{ : }exp ]... [ ]

Syntax Rules

Str-exp is the format string. It must contain at least one valid format
field and must be followed by a separator (comma or semicolon) and at
least one expression.

NOTE

DIGITAL recommends that you use compile-time constant
expressions for str-exp whenever possible. When you do this,
the VAX BASIC compiler compiles the string at compilation
time rather than at run time, thus improving the performance
of your program.

4-298

Statements and Functions

PRINT USING

Output-list specifies the expressions to be printed.
e

Exp can be any valid expression.

A comma or semicolon must separate each expression.

A comma or semicolon is optional after the last expression in the

list.

Remarks

The PRINT USING statement can print up to

Three digits of precision for BYTE integers

Five digits of precision for WORD integers

Six digits of precision for SINGLE floating-point numbers

Ten digits of precision for LONG integers

Sixteen digits of precision for DOUBLE floating-point numbers

Fifteen digits of precision for GFLOAT floating-point numbers

Thirty-three digits of precision for HFLOAT floating-point numbers

Thirty-one digits of precision for DECIMAL numbers

The string length for STRING values

A terminal or terminal-format file must be open on the specified channel
or VAX BASIC signals an error.
The separator characters (comma or semicolon) in the PRINT USING

statement do not control the print format as in the PRINT statement.
The print format is controlled by the format string. Therefore, it does
not matter whether you use a comma or semicolon.
Formatting Numeric Output

The number sign (#) reserves space for one sign or digit.

The comma (,) causes VAX BASIC to insert commas before every
third significant digit to the left of the decimal point. In the format
field, the comma must be to the left of the decimal point, and to

the right of the rightmost dollar sign, asterisk, or number sign. A
comma reserves space for a comma or digit.

Statements and Functions

4-299

PRINT USING

The period (.) inserts a decimal point. The number of reserved
places on either side of the period determines where the decimal
point appears in the output.

The hyphen (-) reserves space for a sign and specifies trailing minus

sign format. If present, it must be the last character in the format
field. It causes VAX BASIC to print negative numbers with a minus
sign after the last digit, and positive numbers with a trailing space.

The hyphen (—) can be used as part of a dollar sign ($$) format
field.

The letters CD (Credit/Debit) enclosed in angle brackets (<CD>)

print CR (Credit Record) after negative numbers or zero and DR
(Debit Record) after positive numbers. If present, they must be the
last characters in the format field. The Credit/Debit format can be

used as part of a dollar sign ($$) format field.
¢

Four carets(*
/) specify E-format notation for floating-point
and DECIMAL numbers. They reserve four places for SINGLE,
DOUBLE, GFLOAT, and DECIMAL values and five places for
HFLOAT values. If present, they must be the last characters in the
format field.

Two dollar signs ($$) reserve space for a dollar sign and a digit and
cause VAX BASIC to print a dollar sign immediately to the left of
the most significant digit.

Two asterisks (**) reserve space for two digits and cause VAX
BASIC to fill the left side of the numeric field with leading asterisks.
A zero enclosed in angle brackets (<0>) prints leading zeros instead
of leading spaces.

A percent sign enclosed in angle brackets (<%>) prints all spaces in
the field if the value of the print item is zero.
NOTE

You cannot specify the dollar sign ($$), asterisk-fill (**),
and zero-fill (<0>) formats within the same print field.

Similarly, VAX BASIC does not allow you to specify the
zero-fill (<0>) and the blank-if-zero (<%>) formats within
the same print field.

4-300

Statements and Functions

PRINT USING

An underscore (_) forces the next formatting character in the
format string to be interpreted as a literal. It affects only the next

character. If the next character is not a valid formatting character,
the underscore has no effect and will itself be printed as a literal.
VAX BASIC interprets any other characters in a numeric format string
as string literals.
Depending on usage, the same format string characters can be combined

to form one or more print fields within a format string. For example:

When a dollar sign ($$) or asterisk-fill (**) format precedes a
number sign (#) , it modifies the number sign format. The dollar

sign or asterisk-fill format reserves two places, and with the number
signs forms one print field. For example:
SO

Forms one field and reserves five spaces

Forms one field and reserves four spaces

When these formats are not followed by a number sign or a

blank-if-zero (<%>) format, they reserve two places and form a
separate print field.
¢

When a zero-fill (<0>) or blank-if-zero format precedes a number

sign, it modifies the number sign format. The <0> or <%> reserves
one place, and with the number signs forms one print field. For
example:
<0>ititt

Forms one field and reserves five spaces

<%o>iti#

Forms one field and reserves four spaces

When these formats are not followed by a number sign, they reserve
one space and form a separate print field.
e

When a blank-if-zero (<%>) format follows a dollar sign or

asterisk-fill format (**), it modifies the dollar sign ($$) or asterisk fill
(**) format string. The blank-if-zero reserves one space, and with
the dollar signs or asterisks forms one print field. For example:
$S<To>###

Forms one field and reserves six spaces

** < o>t

Forms one field and reserves five spaces

When the blank-if-zero precedes the dollar signs or asterisks, it
reserves one space and forms a separate print field.

Statements and Functions

4-301

PRINT USING

The comma (digit separator), dollar sign (currency symbol), and decimal

point (radix point) are the defaults for U.S. currency. On VMS systems,
you can change the digit separator, currency symbol and radix point
by assigning the logical names SYS$DIGIT _SEP, SYS$CURRENCY

and SYS$RADIX_POINT. Once you make each assignment, the PRINT
USING statement accesses these logical names for these symbols.
8.

For E-format notation, PRINT USING left-justifies the number in the
format field and adjusts the exponent to compensate, except when
printing zero. When printing zero in E-format notation, VAX BASIC
prints leading spaces, leading zeros, a decimal point, and zeros in the
fractional portion if the PRINT USING string contains these formatting

characters, and then the string “E+00”.
9.

Zero cannot be negative. If a small negative number rounds to zero, it is

represented as a positive zero.

10. If there are reserved positions to the left of the decimal point, and the

printed number is less than 1, VAX BASIC prints one zero to the left of
the decimal point and pads with spaces to the left of the zero.
11. If there are more reserved positions to the right of the decimal point

than fractional digits, VAX BASIC prints trailing zeros in those
positions.

12. If there are fewer reserved positions to the right of the decimal point

than fractional digits, VAX BASIC rounds the number to fit the reserved
positions.

13. If a number does not fit in the specified format field, VAX BASIC prints
a percent sign warning symbol (%), followed by the number in PRINT
format.
14. Formatting String Output

4-302

Format string characters control string output and can be entered
as either uppercase or lowercase characters. All format characters
except the backslash and exclamation point must start with a single
quotation mark (’). A single quote by itself reserves one character
position. A single quote followed by any format characters marks
the beginning of a character format field and reserves one character
position.

Statements and Functions

PRINT USING

L reserves one character position. The number of Lss plus the leading

single quote determines the field’s size. VAX BASIC left-justifies the

print expression and pads with spaces if the print expression is less
than or equal to the field’s width. If the print expression is larger
than the field, VAX BASIC left-justifies the expression and truncates
its right side to fit the field.
*

R reserves one character position. The number of Rs plus the leading

single quote determines the field’s size. VAX BASIC right-justifies
the print expression and pads with spaces if the print expression
is less than or equal to the field’s width. If the print expression is
larger than the field, VAX BASIC truncates the right side to fit the

field.
*

(C reserves one character position. The number of Cs plus the
leading single quote determines the field’s size. If the string does not

fit in the field, VAX BASIC truncates its right side. Otherwise, VAX
BASIC centers the print expression in this field. If the string cannot

be centered exactly, it is offset one character to the left.
¢

E reserves one character position. The number of Es plus the leading

single quote determines the field’s size. VAX BASIC left-justifies the
print expression if it is less than or equal to the field’s width and

pads with spaces. Otherwise, VAX BASIC expands the field to hold
the entire print expression.
e

Two backslashes (\ \) when separated by n spaces reserve n+2
character positions. PRINT USING left-justifies the string in this
field. VAX BASIC does not allow a leading quotation mark with this
format.

An exclamation point (!) creates a 1-character field. The exclamation
point both starts and ends the field. VAX BASIC does not allow a
leading quotation mark with this format.

15. VAX BASIC interprets any other characters in the format string as
string literals and prints them exactly as they appear.
16. If a COMMA or semicolon follows the last item in output-list:
e

When printing to a terminal, VAX BASIC does not generate a line

terminator after printing the last item. The next item printed with a
PRINT statement is printed at the position specified by the separator
character following the last item in the first PRINT statement.

Statements and Functions

4-303

PRINT USING

When printing to a terminal-format file, VAX BASIC does not write
out the record until a PRINT statement without trailing punctuation
executes.

17. If no punctuation follows the last item in output-list:
*

When printing to a terminal, VAX BASIC generates a line terminator

after printing the last item.
¢

When printing to a terminal-format file, VAX BASIC writes out the
record after printing the last item.

Examples

Example 1
PRINT USING "###.###",-12.345
PRINT USING

"##.###",12.345

Output
-12.345
12.345

Example 2
INPUT

"Your Name";Winner$
Jackpot =

PRINT USING

10000.0

"CONGRATULATIONS,

'EEEEEEEEE,

YOU WON

S$S$#####.##",

END

Output
Your Name?

Hortense

CONGRATULATIONS,

4-304

Statements and Functions

Corabelle

Hortense Corabelle,

YOU WON $10000.00

Winner$,

Jacl

PROD$

PROD$
The PROD$ function returns a numeric string that is the product of two
numeric strings. The precision of the returned numeric string depends on
the value of an integer argument.

Format

str-var = PRODS$ (str-exp1, str-exp2, int-exp)

Syntax Rules

Str-expl and str-exp2 specify the numeric strings you want to multiply.
A numeric string can contain an optional minus sign (—), ASCII digits,
and an optional decimal point (.)
If str-exp consists of more than 60 characters, VAX BASIC signals the
error “Illegal number” (ERR=52).

Int-exp specifies the numeric precision of str-exp. Table 4-5 shows
examples of rounding and truncation and the values of int-exp that
produce them.

The PRODS$ function does not support E-format notation.

Remarks

Str-exp is rounded or truncated, or both, according to the value of
int-exp.

If int-exp is between —60 and 60, rounding and truncation occur as
follows:

For positive integer expressions, rounding occurs to the right of
the decimal place. For example, if int-exp is 1, rounding occurs one
digit to the right of the decimal place (the number is rounded to
Statements and Functions

4-305

PROD$
the nearest tenth). If int-exp is 2, rounding occurs two digits to the
right of the decimal place (the number is rounded to the nearest
hundredth), and so on.

If int-exp is zero, VAX BASIC rounds to the nearest unit.

For negative integer expressions, rounding occurs to the left of the
decimal point. If int-exp is —1, for example, VAX BASIC moves the
decimal point one place to the left, then rounds to units. If int-exp is
—2. rounding occurs two places to the left of the decimal point; VAX
BASIC moves the decimal point two places to the left, then rounds
to tens.

If int-exp is between 9940 and 10,060, truncation occurs as follows:

Ifint-exp is 10,000, VAX BASIC truncates the number at the decimal
point.

If int-exp is greater than 10,000 (10000 plus n) VAX BASIC truncates
the numeric string n places to the right of the decimal point. For
example, if in¢-exp is 10,001 (10,000 plus 1), VAX BASIC truncates
the number starting one place to the right of the decimal point. If
int-exp is 10,002 (10,000 plus 2), VAX BASIC truncates the number
starting two places to the right of the decimal point, and so on.

Ifint-exp is less than 10,000 (10,000 minus ), VAX BASIC truncates
the numeric string n places to the left of the decimal point. For
example, if int-exp is 9999 (10,000 minus 1), VAX BASIC truncates
the number starting one place to the left of the decimal point. If

9998 (10,000 minus 2), VAX BASIC truncates starting two places to

the left of the decimal point, and so on.

If int-exp is not between —60 and 60 or 9940 and 10,060, VAX BASIC
returns a value of zero.

4-306

If you specify a floating-point expression for int-exp, VAX BASIC

truncates it to an integer of the default size.

Statements and Functions

PRODS$

Example

DECLARE

STRING num expl,

num_exp2,

product
num_expl

"34.555"

num_exp2

"297.676"

product = PRODS$ (num_expl,

num exp2,

PRINT product

Output
10286.2

Statements and Functions

4-307

PROGRAM

PROGRAM
The PROGRAM statement allows you to identify a main program with a
name other than the file name.

Format
PROGRAM

prog-name

Syntax Rules

Prog-name specifies the module name of the compiled source and cannot
be the same as any SUB, FUNCTION or PICTURE name.

Prog-name also defines the global entry point name for the main
program.

The first character of a prog-name must be an alphabetic character (A
through Z). The remaining characters, if any, can be any combination of

alphabetic characters, digits (0 through 9), dollar signs ($), periods (.),
and underscores (_).

Prog-name cannot be a quoted name.

The PROGRAM statement must be the first statement in a main

Remarks

program and can be preceded only by comment fields and lexical
directives.
2.

If you insert the program into a text or object library or examine it using
the VMS Debugger, the program name you specify will be the module
name used.

4-308

Statements and Functions

PROGRAM

The PROGRAM statement is optional; VAX BASIC allows you to specify
an END PROGRAM statement and an EXIT PROGRAM statement

without a matching PROGRAM statement.

Example

PROGRAM

first test

END PROGRAM

Statements and Functions

4-309

PUT

PUT
The PUT statement transfers data from the record buffer to a file. PUT

statements are valid on RMS sequential, relative, and indexed files. You
cannot use PUT statements on terminal-format files or virtual array files.

Format
PUT

#chnl-exp [, RECORD num-exp [, COUNT int-exp | |

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number
associated with a file. It must be immediately preceded by a number
sign (#).

The RECORD clause allows you to randomly write records to a relative
or sequential fixed file by specifying the record number. Num-exp must
be between 1 and the maximum record number allowed for the file. VAX

BASIC does not allow you to use the RECORD clause on sequential
variable, sequential stream, or indexed files.
3.

Int-exp in the COUNT clause specifies the record’s size. If there is
no COUNT clause, the record’s size is that defined by the MAP or
RECORDSIZE clause in the OPEN statement. The RECORDSIZE
clause overrides the MAP clause.
*

If you write a record to a file with variable-length records, int-exp

must be between zero and the maximum record size specified in the
OPEN statement.
*

If you write a record to a file with fixed-length records, the COUNT

clause serves no purpose. If used, int-exp must equal the record size

specified in the OPEN statement.

4-310

Statements and Functions

PUT

Remarks

For sequential access, the file associated with chnl-exp must be open
with ACCESS WRITE, MODIFY, SCRATCH, or APPEND.

To add records to an existing sequential file, open it with ACCESS
APPEND. If you are not at the end of the file when attempting a PUT to
a sequential file, VAX BASIC signals “Not at end of file” (ERR=149).

After a PUT statement executes, there is no current record pointer. The
next record pointer is set as follows:

For sequential files, variable and stream PUT operations set the

For relative files, a sequential PUT operation sets the next record

next record pointer to the end of the file.
pointer to the next record plus 1.

For relative and sequential fixed files, a random PUT operation

leaves the next record pointer unchanged.

For indexed files, a PUT operation leaves the next record pointer
unchanged.

When you specify a RECORD clause, VAX BASIC evaluates num-exp

and uses this value as the relative record number of the target cell.
o If the target cell is empty or occupied by a deleted record, VAX
BASIC places the record in that cell.

If there is a record in the target cell and the file has not been opened
as a VIRTUAL file, the PUT statement fails, and VAX BASIC signals

the error “Record already exists” (ERR=153).

A PUT statement with no RECORD clause writes records to the file as
follows:

For sequential variable and stream files, a PUT operation adds a

For relative and sequential fixed files, a PUT operation places the
record in the empty cell pointed to by the next record pointer. If the
file is empty, the first PUT operation places a record in cell number

record at the end of the file.

1, the second in cell number 2, and so on.

For indexed files, RMS stores records in order of ascending primary
key value and updates all indexes so that they point to the record.
Statements and Functions

4-311

PUT

When you a open file as ORGANIZATION VIRTUAL, the file you open is
a sequential fixed file with a record size that is a multiple of 512 bytes.

You can then access the file with the FIND, GET, PUT, or UPDATE

statements or through one or more virtual arrays. VAX BASIC allows
you to overwrite existing records in a file not containing virtual arrays

and opened as ORGANIZATION VIRTUAL by using the PUT statement
with a RECORD clause. All other organizations require the UPDATE
statement to change an existing record. DIGITAL recommends that you
also use the UPDATE statement to change existing records in VIRTUAL
files that do not contain virtual arrays.
7.

If an existing record in an indexed file has a record with the same

key value as the one you want to put in the file, VAX BASIC signals

the error “Duplicate key detected” (ERR=134) if you did not specify

DUPLICATES for the key in the OPEN statement. If you specified
DUPLICATES, RMS stores the duplicate records in a first-in/first-out
sequence.

The number specified in the COUNT clause determines how many bytes
are transferred from the buffer to a file:

If you have not completely filled the record buffer before executing a
PUT statement, VAX BASIC pads the record with nulls to equal the
specified value.

If the specified COUNT value is less than the buffer size, the record
is truncated to equal the specified value.

The number in the COUNT clause must not exceed the size specified
in the MAP or RECORDSIZE clause in the OPEN statement or VAX
BASIC signals “Size of record invalid” (ERR=156).

4-312

For files with fixed length records, the number in the COUNT clause
must match the record size.

Statements and Functions

PUT

Examples

Example 1
tSequential, Relative, Indexed, and Virtual Files
PUT #3,

COUNT

55%

Example 2
IRelative and Virtual Files Only
PUT #5, RECORD 133, COUNT 16%

Statements and Functions

4-313

QUOS$

QUO$
The QUOS$ function returns a numeric string that is the quotient

of two

numeric strings. The precision of the returned numeric string
depends on

the value of an integer argument.

Format
str-var = QUOS$ (str-exp1, str-exp2, int-exp)

Syntax Rules

Str-expl and str-exp2 specify the numeric strings you want to divide.
numeric string can contain an optional minus sign (-), ASCII

and an optional decimal point (.)

digits,

Int-exp specifies the numeric precision of str-exp. Table 4-5
shows
examples of rounding and truncation and the values of int-exp
that
produce them.

The QUO$ function does not support E-format notation.

Remarks

If str-exp consists of more than 60 characters, VAX BASIC signals the
error “Illegal number” (ERR=52).
3.

Str-exp is rounded or truncated, or both, according to the value of

int-exp.

If int-exp is between —60 and 60, rounding and truncation occur as

follows:
*

4-314

Statements and Functions

QuUO$

the nearest tenth). If int-exp is 2, rounding occurs two digits to the
right of the decimal place (the number is rounded to the nearest
hundredth), and so on.

If int-exp is zero, VAX BASIC rounds to the nearest unit.
For negative integer expressions, rounding occurs to the left of the
decimal point. If int-exp is —1, for example, VAX BASIC moves the
decimal point one place to the left, then rounds to units. If int-exp is
—2, rounding occurs two places to the left of the decimal point; VAX
BASIC moves the decimal point two places to the left, then rounds
to tens.

If int-exp is between 9940 and 10,060, truncation occurs as follows:

If int-exp is 10,000, VAX BASIC truncates the number at the decimal
point.

If int-exp is less than 10,000 (10,000 minus ), VAX BASIC truncates
the numeric string n places to the left of the decimal point. For
example, if int-exp is 9999 (10,000 minus 1), VAX BASIC truncates

the number starting one place to the left of the decimal point. If

9998 (10,000 minus 2), VAX BASIC truncates starting two places to
the left of the decimal point, and so on.

If int-exp is not between —60 and 60 or 9940 and 10,060, VAX BASIC
returns a value of zero.

If you specify a floating-point expression for int-exp, VAX BASIC
truncates it to an integer of the default size.

Statements and Functions

4-315

QUO$

Example

DECLARE

STRING num_strl,

num_str2,

quotient
num _strl

"458996.43"

num_str2

"123222.444"

quotient = QUOS$ (num_strl,
PRINT

quotient

Output
3.72

4-316

Statements and Functions

num _str2,

RAD$

RAD$
The RAD$ function converts a specified integer in Radix—50 format to a
3-character string.
NOTE

The RAD$ function is supported only for compatibility with

BASIC-PLUS-2. DIGITAL recommends that you do not use the

RAD$ function for new program development.

Format

str-var = RAD$ (int-var)

Syntax Rules

None.

Remarks

The RADS$ function does not support E-format notation.
The RAD$ function converts int-var to a 3-character string in Radix—50
format and stores it in str-var. Radix-50 format allows you to store
three characters of data as a 2-byte integer.

VAX BASIC supports the RAD$ function, but not its complement, the

FSS$ function.
4.

If you specify a floating-point variable for int-var, VAX BASIC truncates
1t to an integer of the default size.

Statements and Functions

4-317

RADS$

Example

DECLARE STRING radix
radix = RAD$ (999)

4-318

Statements and Functions

RANDOMIZE

RANDOMIZE
The RANDOMIZE statement gives the random number function, RND, a
new starting value.

Format

{ RANDOMIZE }
RANDOM

Syntax Rules

None.

Remarks

Without the RANDOMIZE statement, successive runs of the same
program generate the same random number sequence.

If you use the RANDOMIZE statement before invoking the RND
function, the starting point changes for each run. Therefore, a different
random number sequence appears each time.

Statements and Functions

4-319

RANDOMIZE

Example

DECLARE REAL random_num
RANDOMIZE

FOR I = 1 TO 2
random num = RND

PRINT random_num
NEXT

Output
.379784

.311572

4-320

Statements and Functions

RCTRLC

RCTRLC
The RCTRLC function disables CTRL/C trapping.

Format

int-var = RCTRLC

Syntax Rules

None.

Remarks

After VAX BASIC executes the RCTRLC function, a CTRL/C typed

at the terminal returns you to DCL command level or to the BASIC
environment.

RCTRLC always returns a value of zero.

Example

= RCTRLC

Statements and Functions

4-321

RCTRLO

RCTRLO
The RCTRLO function cancels the effect of a CTRL/O typed on a specified
channel.

Format

int-var = RCTRLO (chnl-exp)

Syntax Rules

Chnl-exp must refer to a terminal.

Remarks

If you type a CTRL/O to cancel terminal output, nothing is printed on
the specified terminal until your program executes the RCTRLO or
until you type another CTRL/O, at which time normal terminal output
resumes.

4-322

The RCTRLO function always returns a value of zero.

RCTRLO has no effect if the specified channel is open to a device that
does not use the CTRL/O convention.

Statements and Functions

RCTRLO

Example

"A"

RCTRLO(0%)

FOR I%

"Normal

output

TO 10%
is

resumed"

Output

off

Normal

output

resumed

Statements and Functions

4-323

READ

READ
The READ statement assigns values from a DATA statement to variables.

Format

READ

var,...

Syntax Rules

Var cannot be a DEF function name, unless the READ statement is inside

the multi-line DEF body.

Remarks

If your program has a READ statement without DATA statements, VAX
BASIC signals a compile-time error.

When VAX BASIC initializes a program unit, it forms a data sequence of
all values in all DATA statements. An internal pointer points to the first
value in the sequence.

When VAX BASIC executes a READ statement, it sequentially assigns

values from the data sequence to variables in the READ statement

variable list. As VAX BASIC assigns each value, it advances the internal
pointer to the next value.
4.

VAX BASIC signals the error “Out of data” (ERR=57) if there are fewer
data elements than READ statements. Extra data elements are ignored.

The data type of the value must agree with the data type of the variable
to which it is assigned or VAX BASIC signals “Data format error”

(ERR=50).

4-324

Statements and Functions

READ

If you read a string variable, and the DATA element is an unquoted
string, VAX BASIC ignores leading and trailing spaces. If the DATA
element contains any commas, they must be inside quotation marks.

VAX BASIC evaluates subscript expressions in the variable list after it
assigns a value to the preceding variable, and before it assigns a value
to the subscripted variable. For instance, in the following example, VAX
BASIC assigns the value of 10 to variable A, then assigns the string,
LESTER, to array element A$(A).
AS$(10)

READ A,

DATA 10,

LESTER

The string, LESTER, will be assigned to A$(10).

Example

DECLARE

STRING A,B,C

READ A,B,C
DATA

"X",

"gz"

"wy",

PRINT A + B +

Output
XYZ

Statements and Functions

4-325

REAL

REAL
The REAL function converts a numeric expression or numeric string to a

specified or default floating-point data type.

Format

", SINGLE
e

, DOUBLE

real-var = REAL (exp

' GFLOAT

]
)

, HFLOAT

Syntax Rules

Exp can be either numeric or string. If a string, it can contain the ASCII
digits 0 through 9, uppercase E, a plus sign (+), a minus sign (-), and a

period (. ).

Remarks

VAX BASIC evaluates exp, then converts it to the specified REAL size.

If you do not specify a size, VAX BASIC uses the default REAL size.

VAX BASIC ignores leading and trailing spaces and tabs if exp is a

string.
3.

The REAL function returns a value of zero when a string argument

contains only spaces and tabs, or when the argument is null.

4-326

Statements and Functions

REAL

Example

DECLARE

STRING any num

INPUT "Enter a number";any_num
PRINT REAL(any num, DOUBLE)

Output
Enter a number?

123095959

.123096E+09

Statements and Functions

4-327

RECORD

RECORD
The RECORD statement lets you name and define data structures in a VAX
BASIC program and provides the VAX BASIC interface to the VAX Common
Data Dictionary/Plus (CDD/Plus). You can use the defined RECORD name

anywhere a VAX BASIC data type keyword is valid if all data types are valid

in that context.

Format

RECORD

rec-name
rec-component

END RECORD

[rec-name ]

data-type rec-item [ ,... |
rec-component:{

group-clause

variant-clause

rec-item:

group-clause:

{ unsubs-var [ = int-const |

array ( [ int-const1 TO ] int-const2 ,...) [ = int-const |
FILL [ (int-const ) ] [ = int-const |
GROUP group-name ([ int-const1 TO ] int-const2,... ) ]
rec-component

END GRbUP [ group-name |
variant-clause: VARIANT
4-328

Statements and Functions

}

RECORD

case-clause

END VARIANT
case-clause:

CASE

[ rec-component |

Syntax Rules

Each line of text in a RECORD, GROUP, or VARIANT block can have an

optional line number.
2.

Data-type can be a VAX BASIC data type keyword or a previously

defined RECORD name. Table 1-2 lists and describes VAX BASIC data
type keywords.
3.

If the data type of a rec-item is STRING, the string is fixed-length. You

can supply an optional string length with the = int-const clause. If you
do not specify a string length, the default is 16.
4.

When you create an array of components with GROUP or create an
array as a rec-item, VAX BASIC allows you to specify both lower

and upper bounds. The upper bound is required; the lower bound is
optional.
*

Int-constl specifies the lower bounds of the array.

Int-const2 specifies the upper bounds of the array and when

accompanied by int-constl, must be preceded by the keyword TO.
e

Int-constl must be less than or equal to int-const2.

If you do not specify int-const1, VAX BASIC uses zero as the default
lower bound.

Statements and Functions

4-329

RECORD

Remarks

The total size of a RECORD cannot exceed 65,535 bytes. Also, a

RECORD that is used as an array component is limited to 32,767 bytes.

The declarations between the RECORD statement and the END
RECORD statement are called a RECORD block.

Variables and arrays in a RECORD definition are also called RECORD

The RECORD statement names and defines a data structure called

components.

a RECORD template, but does not allocate any storage. When you
use the RECORD template as a data type in a statement such as
DECLARE, MAP, or COMMON, you declare a RECORD instance. This

declaration of the RECORD instance allocates storage for the RECORD.
For example:
DECLARE

EMPLOYEE

emp rec

This statement declares a variable named emp_rec, which is an instance

of the user-defined data type EMPLOYEE.
5.

Rec-item

The rec-name qualifies the group-name and the group-name qualifies
the rec-item. You can access a particular rec-item within a record

by specifying rec-name:.group-name::rec-item. This specification is
called a fully qualified reference. The full qualification of a rec-item
is also called a component path name.

Rec-item must conform to the rules for naming VAX BASIC variables.
Whenever you access an elementary record component, that is, a
variable named in a RECORD definition, you do it in the context
of the record instance. Therefore, rec-item names need not be
unique in your program. For example, you can have a variable
called first_name in any number of different RECORD definitions.

However, you cannot use a VAX BASIC reserved keyword as a
rec-item name and you cannot have two variables or arrays with the
same name at the same level in the RECORD or GROUP definition.

4-330

Statements and Functions

RECORD

The group-name is optional in a rec-item specification unless there is
more than one rec-item with the same name or the group-name has
subscripts. For example:
DECLARE

EMPLOYEE

Emp rec

RECORD Address

STRING Street,
END

RECORD

City,

State,

Zip

Address

Employee
GROUP

Emp name

STRING First

STRING Middle =1

STRING Last = 15
END

GROUP

Emp name

ADDRESS Work
ADDRESS

Home

END RECORD Employee

You can access the rec-item “Last” by specifying only “Emp_rec::Last”
because only one rec-item is named “Last”. However, if you
try to reference “Emp_rec::City”, VAX BASIC signals an error
because “City” is an ambiguous field, a component of both
“Work” and “Home”. To access “City”, you must specify either
“Emp_rec::Work::City” or “Emp_rec::Home::City”.
6.

Group-clause

The declarations between the GROUP keyword and the END
GROUP keywords are called a GROUP block. The GROUP keyword
is valid only within a RECORD block.

A subscripted group is similar to an array within the record. The
group can have both lower and upper bounds for one or more
dimensions. Each group element consists of all the record items
contained within the including other groups.

Variant-clause

The declarations between the VARIANT keyword and the END
VARIANT keywords are called a VARIANT block.

The amount of space allocated for a VARIANT field in a RECORD
is equal to the space needed for the variant field requiring the most
storage.

Statements and Functions

4-331

RECORD

A variant defines the record items that overlay other items, allowing
you to redefine the same storage one or more ways.

Case-clause
*

Each case in a variant starts at the position in the record where the

variant begins.

The size of a variant is the size of the longest case in that variant.

Example

1000

RECORD Employee
GROUP

Emp name

STRING Last

STRING First

= 14

STRING Middle =
END

GROUP

Emp name

Emp_ address
STRING

Street

STRING City = 20
STRING

State

DECIMAL(5,0)
END

GROUP

Zip

Emp address

STRING Wage class

VARIANT

CASE
GROUP

Hourly

DECIMAL(4,2)

Hourly wage

SINGLE Regular
pay ytd
SINGLE Overtime
pay ytd
END

GROUP

Hourly

CASE

GROUP

Salaried

DECIMAL(7,2)
SINGLE

END GROUP

Yearly salary

Pay_ytd

Salaried

CASE

GROUP Executive
DECIMAL(8,2)

Yearly salary

SINGLE Pay_ytd

SINGLE Expenses_ytd
END
END VARIANT

END

4-332

RECORD Employee

Statements and Functions

GROUP

Executive

RECOUNT

RECOUNT
The RECOUNT function returns the number of characters transferred by
the last input operation.

Format

int-var = RECOUNT

Syntax Rules

None.

Remarks

The RECOUNT value is reset by every input operation on any channel,
including channel #0.

After an input operation from your terminal, RECOUNT contains the
number of characters (bytes), including line terminators, transferred.

After accessing a file record, RECOUNT contains the number of

characters in the record.

Because RECOUNT is reset by every input operation on any channel,
you should copy the RECOUNT value to a different storage location

before executing another input operation.
3.

If an error occurs during an input operation, the value of RECOUNT is
undefined.

RECOUNT is unreliable after a CTRL/C interrupt because the CTRL/C
trap may have occurred before VAX BASIC set the value for RECOUNT.

The RECOUNT function returns a LONG value.

Statements and Functions

4-333

RECOUNT

Example

DECLARE

INPUT

INTEGER

"Enter

character count

sequence

character_count
PRINT

numeric

characters";character
count

RECOUNT

character_count;"characters

received

(including CR

Output
Enter

4-334

sequence

characters

numeric

received

Statements and Functions

characters?

(including

12345678

CR and LF)

and LF)"

REM

REM
The REM statement allows you to document your program.

Format
REM

[comment]

Syntax Rules

REM must be the only statement on the line or the last statement on a
multi-statement line.
VAX BASIC interprets every character between the keyword REM and
the next line number as part of the comment.

VAX BASIC does not allow you to specify the REM statement in
programs that do not contain line numbers.

Remarks

Because the REM statement is not executable, you can place it anywhere
In a program, except where other statements, such as SUB and END

SUB, must be the first or last statement in a program unit.
When the REM statement is the first statement on a line-numbered line,
VAX BASIC treats any reference to that line number as a reference to

the next higher-numbered executable statement.
The REM statement is similar to the comment field that begins with an

exclamation point, with one exception: the REM statement must be the
last statement on a BASIC line. The exclamation point comment field
can be ended with another exclamation point or a line terminator and
followed by a VAX BASIC statement. See Chapter 1 of this manual for
more information on the comment field.

Statements and Functions

4-335

REM

Example

10 REM This is a multi-line comment
All text up to BASIC line 20
is part

of this REM statement.

Any BASIC statements on line 10
are ignored.
PRINT "This does not
execute".

20 PRINT

"This will execute"

Output
This will

4-336

execute

Statements and Functions

REMAP

REMAP
The REMAP statement defines or redefines the position in the storage area

of variables named in the MAP DYNAMIC statement.

Format
REMAP

(map-dyn-name) remap-item,...

map-dyn-name: { static-str-var }
e

map-name

num-var

num-array-name ( [ int-exp,... | )

str-var [ = int-exp |
remap-item:

str-array-name ( [ int-exp,...] )[ = int-exp |
[ data-type JFILL [ (int-exp) ] [ = int-exp ]
FILL% [ (int-exp ) ]
. FILL$ [ (int-exp ) ][ = int-exp |

Syntax Rules

Map-dyn-name can be either a map name or a static string variable.

®*
e

Map-name is the storage area named in a MAP statement.
If you specify a map name, then a MAP statement with the same

name must precede both the MAP DYNAMIC statement and the

REMAP statement.
*

When you specify a static string variable, the string must be
declared before you can specify a MAP DYNAMIC statement or a
REMAP statement.

Statements and Functions

4-337

REMAP

If you specify a static-str-var, the following restrictions apply:
—

Static-str-var cannot be a string constant.

—

Static-str-var cannot be the same as any previously declared
map-item in a MAP DYNAMIC statement.

—

If static-str-var is a parameter to the subprogram containing
the REMAP statement, static-str-var cannot be a RECORD
component.

—

Static-str-var cannot be a subscripted variable.

—

Static-str-var cannot be a parameter declared in a DEF or DEF*
function.

Remap-item names a variable, array, or array element declared in a
preceding MAP DYNAMIC statement:
e

Num-var specifies a numeric variable or array element.
Num-array-name followed by a set of empty parentheses specifies an
entire numeric array.

Str-var specifies a string variable or array element. Str-array-name
followed by a set of empty parentheses, specifies an entire
fixed-length string array. You can specify the number of bytes
to be reserved for string variables and array elements with the
=int-exp clause. The default string length is 16.

Remap-item can also be a FILL item. The FILL, FILL%, and FILL$
keywords let you reserve parts of the record buffer. Int-exp specifies
the number of FILL items to be reserved. The =int-exp clause allows
you to specify the number of bytes to be reserved for string FILL items.
Table 4-2 describes FILL item format and storage allocation.
NOTE

In the FILL clause, (int-exp) represents a repeat count, not an

array subscript. FILL (n), for example, represents n elements,
not n + 1.
4.

4-338

All remap-items, except FILL items, must have been named in a
previous MAP DYNAMIC statement, or VAX BASIC signals an error.

Statements and Functions

REMAP

Data-type can be any VAX BASIC data type keyword or a data type

defined in a RECORD statement. Data type keywords and their size,

range, and precision are listed in Table 1-2 in this manual. You can
specify a data type only for FILL items.

When you specify a data type before a FILL keyword in a REMAP

statement, the FILL item is of that data type. The specified data
type applies only to that one FILL item.

If you do not specify any data type for a FILL item, the FILL item
takes the current default data type and size.

Remap-items must be separated with commas.

Remarks

The REMAP statement does not affect the amount of storage allocated
to the map area.

Each time a REMAP statement executes, VAX BASIC sets record
pointers to the named map area for the specified variables from left to
right.

The REMAP statement must be preceded by a MAP DYNAMIC

statement or VAX BASIC signals the error “No such MAP area <name>”.

The MAP statement or static string variable creates a named area of

static storage, the MAP DYNAMIC statement specifies the variables
whose positions can change at runtime, and the REMAP statement

specifies the new positions for the variables named in the MAP
DYNAMIC statement.

Before you can specify a map name in a REMAP statement, there must
be a MAP statement in the program unit with the same map name.

Otherwise, VAX BASIC signals the error “<Name> is not a DYNAMIC
MAP variable of MAP <name>”. Similarly, before you can specify a
static string variable in a REMAP statement, the string variable must

be declared. Otherwise, VAX BASIC signals the same error message.
If a static string variable is the same as a map name, VAX BASIC
overrides the static string name and uses the map name.

Statements and Functions

4-339

REMAP
6. Until the REMAP statement executes, all variables named in the MAP
DYNAMIC statement point to the first byte of the MAP area and all
string variables have a length of zero. When the REMAP statement
executes, VAX BASIC sets the internal pointers as specified in the
REMAP statement. For example:
100

MAP (DUMMY) STRING map_buffer = 50
MAP DYNAMIC (DUMMY) LONG A, STRING B,
REMAP

(DUMMY)

B=14,

SINGLE C(7)

C()

The REMAP statement sets a pointer to byte 1 of DUMMY for string
variable B, a pointer to byte 15 for LONG variable A, and pointers to
bytes 19, 23, 27, 31, 35, 39, 43, and 47 for the elements in SINGLE
array C.

7. You can use the REMAP statement to redefine the pointer for an array
element or variable more than once in a single REMAP statement. For
example:
100

MAP (DUMMY) STRING FILL = 48
MAP DYNAMIC (DUMMY) LONG A, B(10)
REMAP

(DUMMY)

B(),

B(0)

This REMAP statement sets a pointer to byte 1 in DUMMY for array B.
Because array B uses a total of 44 bytes, the pointer for the first element
of array B, B(0) points to byte 45. References to array element B(0) will
be to bytes 45 through 48. Pointers for array elements 1 through 10 are
set to bytes 5, 9, 13, 17 and so forth.

4-340

Because the REMAP statement is local to a program module, it affects

pointers only in the program module in which it executes.

Statements and Functions

REMAP

Examples

Example 1
DECLARE
MAP

LONG CONSTANT

(emp buffer)

empfixed_info

STRING social_sec_num =

BYTE

DYNAMIC

2
&

name_length,

address_length,

FILL
MAP

LONG badge,

(emp_buffer)

(60)

STRING emp_name,

emp_address
WHILE

GET #1
REMAP

(emp_buffer)

STRING FILL =

emp name

emp_fixed info,

name_ length,

emp_address

emp name

emp address

address_length

NEXT
END

Example 2
SUB deblock
MAP

(STRING

DYNAMIC

REMAP

(input rec)

A(l)

=5,

A(2)

= 3,

A(3)
FOR I

STRING item())

STRING A(l

TO 3)

LBOUND(A)

item(I)

input_rec,

(input_rec)

TO UBOUND (A)

= A(I)

END SUB

Statements and Functions

4-341

RESET

RESET
The RESET statement is a synonym for the RESTORE statement. See the

RESTORE statement for more information.

Format

RESET

4-342

[#chnl-exp [, KEY #int-exp ] |

Statements and Functions

RESTORE

RESTORE
The RESTORE statement resets the DATA pointer to the beginning of the
DATA sequence, or sets the record pointer to the first record in a file.

Format

RESTORE

[#chnl-exp [, KEY #int-exp | ]

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number

associated with a file. It must be immediately preceded by a number
sign (#).

Int-exp must be between zero and the number of keys in the file

minus 1. It must be immediately preceded by a number sign (#).

Remarks

If you do not specify a channel, RESTORE resets the DATA pointer to
the beginning of the DATA sequence.
RESTORE affects only the current program unit. Thus, executing a

RESTORE statement in a subprogram does not affect the DATA pointer
in the main program.

If there is no channel specified, and the program has no DATA
statements, RESTORE has no effect.

The file specified by chnl-exp must be open.

If chnl-exp specifies a magnetic tape file, VAX BASIC rewinds the tape
to the first record in the file.

Statements and Functions

4-343

RESTORE

The KEY clause applies to indexed files only. It sets a new key of
reference equal to int-exp and sets the next record pointer to the first
logical record in that key.
|
For indexed files, the RESTORE statement without a KEY clause sets
the next record pointer to the first logical record specified by the current
key of reference. If there is no current key of reference, the RESTORE

statement sets the next record pointer to the first logical record of the

primary key.
If you use the RESTORE statement on any file type other than indexed,

VAX BASIC sets the next record pointer to the first record in the file.
The RESTORE statement is not allowed on virtual array files or on files
opened on unit record devices.
10. For information on the RESTORE GRAPHICS statement, see

Programming with VAX BASIC Graphics.

Example

RESTORE #7%,

4-344

KEY #4%

Statements and Functions

RESUME

RESUME
The RESUME statement marks an exit point from an ON ERROR

error-handling routine. VAX BASIC clears the error condition and returns
program control to a specified line number, label or to the program block in
which the error occurred.
NOTE

The RESUME statement is supported for compatibility with other
DIGITAL BASICs. For new program development, DIGITAL
recommends that you use WHEN blocks.

Format

RESUME

[target]

Syntax Rules

Target must be a valid VAX BASIC line number or label and must exist in
the same program unit.

Remarks

The following restrictions apply:

The RESUME statement cannot appear within a protected region, or
within an attached or detached handler.

The target of a RESUME statement cannot exist within a protected
region or handler.

The RESUME statement cannot be used in a multi-line DEF unless
the target is also in the DEF function definition.

Statements and Functions

4-345

RESUME

The execution of a RESUME with no target is illegal if there is no
error active.

A RESUME statement cannot transfer control out of the current
program unit. Therefore,

a RESUME statement with no target

cannot terminate an error handler if the error handler is handling
an error that occurred in a subprogram or an external function, and

the error was passed to the calling program’s error handler by an

ON ERROR GO BACK statement or by default.
2.

When no target is specified in a RESUME statement, VAX BASIC

transfers control based on where the error occurs. If the error occurs
on a numbered line containing a single statement, VAX BASIC always
transfers control to that statement. When the error occurs within a
multi-statement line under the following conditions, VAX BASIC acts as
follows:
Within a FOR, WHILE, or UNTIL loop, VAX BASIC transfers control
to the first statement that follows the FOR, WHILE, or UNTIL
statement.

Within a SELECT block, VAX BASIC transfers control to the start of

the CASE block in which the error occurs.
After a loop or SELECT block, VAX BASIC transfers control to the

statement that follows the NEXT or END SELECT statement.
If none of the above conditions occurs, VAX BASIC transfers control

back to the statement that follows the most recent line number.
3.

A RESUME statement with a specified line number transfers control
to the first statement of a multi-statement line, regardless of which

statement caused the error.
4.

A RESUME statement with a specified label transfers control to the

block of code indicated by that label.

4-346

Statements and Functions

RESUME

Example

Error routine:

IF ERR =

THEN

CLOSE
RESUME

#1
end_of prog

ELSE
RESUME
END

end
of prog:

END

Statements and Functions

4-347

RETRY

RETRY
The RETRY statement clears an error condition and reexecutes the

statement that caused the error inside a protected region of a WHEN
block.

Format

RETRY

Syntax Rules

The RETRY statement must appear lexically inside of a handler associated
with a WHEN block.

Remarks

The following rules apply to errors that occur during execution of loop

control statements (not the statements inside the loop body):
e

In FOR...NEXT loops, the RETRY statement reexecutes the FOR

statement if the error occurs while VAX BASIC is evaluating the limit or
increment values.
*

In FOR..NEXT loops, if the error occurs while VAX BASIC is evaluating

the index variable, the RETRY statement reexecutes the

statement.

In a FOR...UNTIL or FOR...WHILE loop, if an error occurs while VAX

BASIC is evaluating the relational expression, the RETRY statement
reexecutes the NEXT statement.

4-348

Statements and Functions

RETRY

Example

10 DECLARE LONG YOUR AGE
WHEN ERROR IN
INPUT

"Enter your age";your
age

USE

IF ERR =

THEN RETRY
ELSE EXIT
END

HANDLER

END WHEN

Statements and Functions

4-349

RETURN

RETURN
The RETURN statement transfers control to the statement immediately
following the most recently executed GOSUB or ON...GOSUB statement in

the current program unit.

Format
RETURN

Syntax Rules

None.

Remarks

Once the RETURN is executed in a subroutine, no other statements
in the subroutine are executed, even if they appear after the RETURN
statement.

Execution of a RETURN statement before the execution of a GOSUB or

ON...GOSUB causes VAX BASIC to signal “RETURN without GOSUB”

(ERR=72).

4-350

Statements and Functions

RETURN

Example

GOSUB

subroutine_1

subroutine 1:

RETURN

Statements and Functions

4-351

RIGHT$

RIGHT$
The RIGHTS$ function extracts a substring from a string’s right side, leaving
the string unchanged.

Format

str-var = RIGHT[$] (str-exp, int-exp)

Syntax Rules

None.

Remarks

The RIGHTS$ function extracts a substring from str-exp and stores the
substring in str-var. The substring begins with the character in the
position specified by int-exp and ends with the rightmost character in

the string.

If int-exp is less than or equal to zero, RIGHT$ returns the entire string.

If int-exp is greater than the length of str-exp, RIGHT$ returns a null
string.

If you specify a floating-point expression for int-exp, VAX BASIC
truncates it to a LONG integer.

4-352

Statements and Functions

RIGHTS

Example

DECLARE

STRING main_str,

end result

main str

end_result
PRINT

"1234567"
= RIGHTS (main_str,

end result

Output
34567

Statements and Functions

4-353

RMSSTATUS

RMSSTATUS
The RMSSTATUS function returns the RMS status or the status value of
the last I/O operation on a specified open I/O channel.

Format

long-var = RMSSTATUS ( chnl-exp [ », VALUE
STATUS ] )
Syntax Rules

Chnl-exp must be the number of a channel opened from a VAX BASIC
routine.

Chnl-exp cannot be zero.

Remarks

If chnl-exp does not represent an open channel, VAX BASIC signals the
error “I/O channel not open” (ERR=9).

If you do not specify either STATUS or VALUE, RMSSTATUS returns
the STATUS value by default.

If you specify STATUS, RMSSTATUS returns the FAB$L_STS or the
RABS$L_STS status value. However, if you specify VALUE, RMSSTATUS
returns the FAB$L STV or the RAB$L_STV status value.
Use the RMSSTATUS function to return the status of the following
operations:

4-354

RESTORE

GET

Statements and Functions

RMSSTATUS

PUT

UPDATE

UNLOCK

PRINT and PRINT USING

INPUT, INPUT LINE, and LINPUT

SCRATCH

FREE

Virtual array references

To determine the reason for the failure of an OPEN, CLOSE, KILL, or
NAME...AS statement, use the VMSSTATUS function within an error

handler.

Examples

Example 1
$TITLE

"RMSSTATUS

$SBTTL

"Reference Manual Examples"

Example”

$IDENT

"V1.0"

PROGRAM Demo_ RMSSTATUS function

OPTION
OPEN

WHEN

CONSTANT

TYPE

INTEGER

"DOES_
NOT EXIST.LIS"
SEQUENTIAL

VARIABLE,

RECORDSIZE

ERROR

GET

FOR OUTPUT

&
&

USE

END
END

"GET

Operation

"RMS

Status

=";

failed"

"RMS

Status

Value =";

RMSSTATUS
(1, STATUS)

RMSSTATUS(1,VALUE)

WHEN

PROGRAM

Statements and Functions

4-355

RMSSTATUS

Example 2
OPTION

TYPE=EXPLICIT

EXTERNAL LONG CONSTANT RMS$ OK_DUP
LONG ORD_ENTRY,

"ORD DB"

FOR

ORGANIZATION

INPUT AS

FILE

1%,

INDEXED FIXED,

ORDER,

PRIMARY

ORD_ENTRY NODUPLICATES,

ALTERNATE

MAP

6%,

OPEN

STRING ORD_CUST
NO =

50%

(ORDER)

STRING ORD_REMARK =

ORD_CUST
NO

MAP

DUPLICATES

INPUT

"Enter

order number";ORD ENTRY

INPUT

"Enter

customer number";ORD
CUST NO

INPUT

"Remark";ORD REMARK

]

Enter the

Check if the customer has

order

in the

order

database

other orders

PUT

#1%

IF RMSSTATUS(

1%,

STATUS

)

= RMS$_OK DUP

THEN
{

The

discount

customer has

END

4-356

Statements and Functions

other orders;

for other orders

compute

the customer’s

RND

RND
The RND function returns a random number greater than or equal to zero
and less than 1.

Format
real-var = RND

Syntax Rules

None.

Remarks

If the RND function is preceded by a RANDOMIZE statement, VAX
BASIC generates a different random number or series of numbers each

time a program executes.
2.

The RND function returns a pseudorandom number if not preceded by a
RANDOMIZE statement; that is, each time a program runs, VAX BASIC
generates the same random number or series of random numbers.

The RND function returns a floating-point SINGLE value.

The RND function returns values over a uniform distribution between
0 and 1. For example, a value between 0 and .1 is as likely as a value

between .5 and .6. Note the difference between this and a bell-curve
distribution where the probability of values in the range .3 to .7 is higher
than the outer ranges.

Statements and Functions

4-357

RND

Example

DECLARE REAL

random_num

RANDOMIZE

FOR I =1

TO 3

IFOR loop causes VAX BASIC to print

random num = RND*

PRINT
NEXT

random num

Output
.865243
.477417

.734673

4-358

Statements and Functions

three

random numbers

RSET

RSET
The RSET statement assigns right-justified data to a string variable. RSET
does not change a string variable’s length.

Format
RSET

str-var,... = str-exp

Syntax Rules

Str-var cannot be a DEF function name unless the RSET statement is inside
the DEF function definition.

Remarks

1.
2.

The RSET statement treats strings as fixed-length. It does not change
the length of str-var, nor does it create new storage locations.
If str-var is longer than str-exp, RSET right-justifies the data and pads it
with spaces on the left.

If str-var is shorter than str-exp, RSET truncates str-exp on the left.

Statements and Functions

4-359

RSET

Example

DECLARE
test

STRING test
"ABCDE"

RSET test =

"123"

test

"X"

Output
X

4-360

123

Statements and Functions

SCRATCH

SCRATCH
The SCRATCH statement deletes the current record and all following
records in a sequential file.

Format

SCRATCH

#chnl-exp

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel associated with a
file. It must be immediately preceded by a number sign (#).

Remarks

Before you execute the SCRATCH statement, the file must be opened
with ACCESS SCRATCH.

The SCRATCH statement applies to ORGANIZATION SEQUENTIAL
files only.

The SCRATCH statement has no effect on terminals or unit record
devices.

For disk files, the SCRATCH statement discards the current record and
all that follows it in the file. The physical length of the file does not
change.

For magnetic tape files, the SCRATCH statement overwrites the current
record with two end-of-file marks.

Use of the SCRATCH statement on shared sequential files is not
recommended.

Statements and Functions

4-361

SCRATCH

Example

SCRATCH

4-362

#4%

Statements and Functions

SEG$

SEG$
The SEG$ function extracts a substring from a main string, leaving the

original string unchanged.

Format

str-var = SEG$ (str-exp, int-exp1, int-exp2)

Syntax Rules

None.

Remarks

VAX BASIC extracts the substring from str-exp, the main string, and

stores the substring in str-var. The substring begins with the character
in the position specified by int-expl and ends with the character in the
position specified by int-exp2.

Ifint-expl is less than 1, VAX BASIC assumes a value of 1.

Ifint-expl is greater than int-exp2 or the length of str-exp, the SEG$
function returns a null string.

If int-expl equals int-exp2, the SEG$ function returns the character at
the position specified by int-exp1.

Unless int-exp2 is greater than the length of str-exp, the length of the
returned substring equals int-exp2 minus int-expl plus 1. If int-exp2
is greater than the length of str-exp, the SEG$ function returns all
characters from the position specified by int-exp1 to the end of str-exp.

If you specify a floating-point expression for int-expl or int-exp2, VAX
BASIC truncates it to LONG integer.

Statements and Functions

4-363

SEGS

Example

DECLARE STRING alpha,
alpha =

center = SEGS (alpha,
PRINT

center

Output
DEFGH

4-364

center

"ABCDEFGHIJK"

Statements and Functions

SELECT

SELECT
The SELECT statement lets you specify an expression, a number of possible

values the expression may have, and a number of alternative statement

blocks to be executed for each possible case.

Format

SELECT

exp1
case-clause

[ else-c}ause ]
END SELECT

case-clause:

CASEcase-item,...
[ statement |...

[rel-op] exp2

case-item. { exp3 TO exp4 [ ,exp5 TO expb ] ,...
else-clause:

}

CASE ELSE

[ statement |...

Syntax Rules

Expl is the expression to be tested against the case-clauses and the

else-clause. It can be numeric or string.
2.

Case-clause consists of the CASE keyword followed by a case-item and
statements to be executed when the case-item is true.

Statements and Functions

4-365

SELECT

3.
4.

Else-clause consists of the CASE ELSE keywords followed by statements
to be executed when no previous case-item has been selected as true.
Case-item is either an expression to be compared with expl or a range of
values separated with the keyword TO.
*

Rel-op is a relational operator specifying how exp1 is to be compared

to exp2. If you do not include a rel-op, VAX BASIC assumes the
equals (=) operator. VAX BASIC executes the statements in the
CASE block when the specified relational expression is true.
o

FExp3 and exp4 specify a range of numeric or string values separated

by the keyword TO. Multiple ranges must be separated with
commas. VAX BASIC executes the statements in the CASE block
when expl falls within any of the specified ranges.

Remarks

A SELECT statement can have only one else-clause. The else-clause is

optional and, when present, must be the last CASE block in the SELECT
block.
2.

Each statement in a SELECT block can have its own line number.

The SELECT statement begins the SELECT BLOCK and the END
SELECT keywords terminate it. VAX BASIC signals an error if you do
not include the END SELECT keywords.

Each CASE keyword establishes a CASE block. The next CASE or END
SELECT keyword ends the CASE block.

You can nest SELECT blocks within a CASE or CASE ELSE block.

VAX BASIC evaluates expl when the SELECT statement is first
encountered; VAX BASIC then compares expl with each case-clause in
order of occurrence until a match is found or until a CASE ELSE block
or END SELECT is encountered.

The following conditions constitute a match:

[Expl satisfies the relationship to exp2 specified by rel-op.

Expl is greater than or equal to exp3, but less than or equal to exp4,

greater than or equal to exp5 but less than or equal to exp6, and
SO on.

4-366

Statements and Functions

SELECT

When a match is found between expl and a case-item, VAX BASIC
executes the statements in the CASE block where the match occurred.
If ranges overlap, the first match causes VAX BASIC to execute the
statements in the CASE block. After executing CASE block statements,
control passes to the statement immediately following the END SELECT

keywords.
9.

If no CASE match occurs, VAX BASIC executes the statements in

the else-clause, if present, and then passes control to the statement
immediately following the END SELECT keywords.
10. If no CASE match occurs and you do not supply a case-else clause,
control passes to the statement following the END SELECT keywords.

Example

100

SELECT A%

+ B%

CASE

100

CASE

100

’'THE VALUE

EXACTLY

100’

‘THE VALUE

IS BETWEEN

1 AND

99’

'THE

VALUE

GREATER

THAN

100’

’‘THE VALUE

LESS

PRINT
PRINT

CASE ELSE

PRINT
END

THAN

1’

SELECT

Statements and Functions

4-367

SET PROMPT

SET PROMPT
The SET PROMPT statement enables a question mark prompt to appear

after VAX BASIC executes either an INPUT, LINPUT, INPUT LINE, MAT
INPUT, or MAT LINPUT statement on channel #0. The SET NO PROMPT
statement disables the question mark prompt.

Format

SET [NO] PROMPT

Syntax Rules

None.

Remarks

If you do not specify a SET PROMPT statement, the default is SET
PROMPT.

SET NO PROMPT disables VAX BASIC from issuing a question mark
prompt for the INPUT, LINPUT, INPUT LINE, MAT INPUT, and MAT
LINPUT statements on channel #0.

4-368

Prompting is reenabled when either a SET PROMPT statement or a
CHAIN statement is executed, or when a NEW, OLD, RUN or SCRATCH
command is executed in the BASIC environment.

The SET NO PROMPT statement does not affect the string constant you
specify as the input prompt with the INPUT statement.

Statements and Functions

SET PROMPT

Example

DECLARE
INPUT

STRING your_name,

"Enter

your

your_age,

your_grade

name";your name

SET NO PROMPT

INPUT

"Enter your

age";

your age

SET PROMPT
INPUT

"Enter

the

last

school

grade

you

completed”;your
grade

Output
Enter

your

Enter your

name?

Katherine

age

Enter the last

school

Kelly

grade you completed?

Statements and Functions

4-369

SGN

SGN
The SGN function determines whether a numeric expression is positive,

negative, or zero. It returns a 1 if the expression is positive, a —1 if the
expression is negative, and zero if the expression is zero.

Format

int-var = SGN (real-exp)

Syntax Rules

None.

Remarks

If real-exp does not equal zero, SGN returns MAG(real-exp)/real-exp.

If real-exp equals zero, SGN returns a value of zero.

SGN returns a LONG integer.

Example

DECLARE

INTEGER sign

sign = SGN(46/23)
PRINT

sign

Output
1

4-370

Statements and Functions

SIN

SIN
The SIN function returns the sine of an angle in radians or degrees.

Format
real-var = SIN (real-exp)

Syntax Rules

Real-exp is an angle specified in radians or degrees depending upon which
angle clause you choose with the OPTION statement.

Remarks

The returned value is between —1 and 1.
VAX BASIC expects the argument of the SIN function to be a real
expression. When the argument is a real expression, VAX BASIC
returns a value of the same floating-point size. When the argument is
not a real expression, VAX BASIC converts the argument to the default

floating-point size and returns a value of the default floating-point size.

Statements and Functions

4-371

SIN

Example

OPTION ANGLE = RADIANS
DECLARE REAL sl_angle

sl_angle = SIN(PI/2)
PRINT sl _angle

Output
1

4-372

Statements and Functions

SLEEP

SLEEP
The SLEEP statement suspends program execution for a specified number of
seconds or until a carriage return is entered from the controlling terminal.

Format

SLEEP

int-exp

Syntax Rules

Int-exp is the number of seconds VAX BASIC waits before resuming
program execution.

Int-exp must be between 0 and 2,147,483,647; if it is greater than
2.147,483,647, VAX BASIC signals the error “Integer error or overflow”
(ERR=51).

Remarks
Pressing the RETURN key on the controlling terminal cancels the effect

of the SLEEP statement.

All characters typed while SLEEP is in effect, including a RETURN
character entered to terminate the SLEEP statement, will remain in the
typeahead buffer. Therefore, if you type RETURN without preceding
data, an INPUT statement that follows the SLEEP will complete without
data.

Statements and Functions

4-373

SLEEP

Example

SLEEP

4-374

120%

Statements and Functions

SPACE$

SPACE$
The SPACE$ function creates a string containing a specified number of
spaces.

Format

str-var = SPACES$ (int-exp)

Syntax Rules

Int-exp specifies the number of spaces in the returned string.

Remarks

VAX BASIC treats an int-exp less than 0 as zero.

If you specify a floating-point expression for int-exp, VAX BASIC
truncates it to a LONG integer.

Example

DECLARE

STRING A,

A =

"1234"

B =

"5678"

PRINT A + SPACES(5%)

+ B

Output
1234

5678

Statements and Functions

4-375

SQR

SQR
The SQR function returns the square root of a positive number.

Format
var_ J SQRT
i
real-var
= { SQR } (real-exp)

Syntax Rules

None.

Remarks

VAX BASIC signals the error “Imaginary square roots” (ERR=54) when
real-exp is negative.

VAX BASIC assumes that the argument of the SQR function is a real
expression. When the argument is a real expression, VAX BASIC

returns a value of the same floating-point size. When the argument
is not a real expression, VAX BASIC returns a value of the default
floating-point size.

4-376

Statements and Functions

SQR

Example

DECLARE

root
PRINT

REAL

root

SQR(20%*5)
root

Output
10

Statements and Functions

4-377

STATUS

STATUS
The STATUS function returns an integer value containing information about
the last opened channel. Your program can test each bit to determine the
status of the channel.

NOTE

The STATUS function is supported only for compatibility with
other DIGITAL BASICs. DIGITAL recommends that you use the
RMSSTATUS function for new program development.

Format

int-var = STATUS

Syntax Rules

None.

Remarks

The STATUS function returns a LONG integer.

The value returned by the STATUS function is undefined until VAX
BASIC executes an OPEN statement.

3. The STATUS value is reset by every input operation on any channel.
Therefore, you should copy the STATUS value to a different storage
location before your program executes another input operation.

4-378

Statements and Functions

STATUS

If an error occurs during an input operation, the value of STATUS is
undefined. When no error occurs, the six low-order bits of the returned
value contain information about the type of device accessed by the last

Record-oriented device

Carriage-control device

Device Type

Terminal

Bit Set

Directory device

VAX BASIC STATUS Bits

Single directory device

Table 4-6:

input operation. Table 46 lists STATUS bits set by VAX BASIC.

Sequential block-oriented device (magnetic tape)

Example

150

STATUS

Statements and Functions

4-379

STOP

STOP
The STOP statement halts program execution allowing you to optionally
continue execution.

Format

STOP

Syntax Rules

None.

Remarks

The STOP statement cannot appear before a PROGRAM, SUB or
FUNCTION statement.

The STOP statement does not close files.

When a STOP statement executes in a program executed with the

RUN command in the BASIC environment, VAX BASIC prints the line
number and module name associated with the STOP statement, then
displays the Ready prompt. In response to the prompt, you can type
immediate mode statements, CONTINUE to resume program execution,
or any valid compiler command. See the VAX BASIC User Manual for
more information on immediate mode.
4.

When a STOP statement is in an executable image, the line number,

module name, and a number sign (#) prompt are printed. In response
to the prompt, you can type CONTINUE to continue program execution
or EXIT to end the program. If the program module was compiled with
the /NOLINE qualifier, no line number is displayed.

4-380

Statements and Functions

STOP

Example

PROGRAM

Stopper

PRINT "Type CONTINUE when the program stops"
INPUT "Do you want to stop now"; Quit$
IF Quit$ =

"Y"

THEN

STOP
ELSE

PRINT "So what are you waiting for?"
STOP

END

PRINT "You told me to continue...thank you"
END PROGRAM

Output
Do you want to stop now? CONTINUE
So what are you waiting for?

Statements and Functions

4-381

STR$

STR$
The STR$ function changes a numeric expression to a numeric character
string without leading and trailing spaces.

Format

str-var = STR$ (num-exp)

Syntax Rules

None.

Remarks

If num-exp is negative, the first character in the returned string is a

minus sign (—).

The STR$ function does not return leading or trailing spaces.

When you print a floating-point number that has six decimal digits
or more but the integer portion has six digits or less (for example,

1234.567), VAX BASIC rounds the number to six digits (1234.57). If a
floating-point number’s integer part is seven decimal digits or more, VAX
BASIC rounds the number to six digits and prints it in E format.
4.

When you print a floating-point number with magnitude between 0.1

and 1, VAX BASIC rounds it to six digits. When you print a number
with magnitude smaller than 0.1, VAX BASIC rounds it to six digits and
prints it in E format.

4-382

The STR$ function returns up to 10 digits for LONG integers and up to
31 digits for DECIMAL numbers.

Statements and Functions

STRS$

Example

DECLARE

STRING new_num

new num = STR$ (1543.659)
PRINT

new num

Output
1543.66

Statements and Functions

4-383

STRINGS

STRINGS$
The STRING$ function creates a string containing a specified number of
identical characters.

Format

str-var = STRINGS (int-exp1, int-exp2)

Syntax Rules

Int-expl specifies the character string’s length.

Int-exp2 is the decimal ASCII value of the character that makes up the
string. This value is treated modulo 256.

Remarks

VAX BASIC signals the error “String too long” (ERR=227) if int-expl is
greater than 65535.

2.
3.

Ifint-expl is less than or equal to zero, VAX BASIC treats it as zero.
VAX BASIC treats int-exp2 as an unsigned 8-bit integer. For example,
—1 is treated as 255.

If either int-expl or int-exp2 is a floating-point expression, VAX BASIC
truncates it to a LONG integer.

4-384

Statements and Functions

STRINGS

Example

DECLARE

STRING

output str

output_str = STRINGS(10%,
PRINT

output str

50%)

!50

the ASCII

!character

value

of the

"2"

Output
2222222222

Statements and Functions

4-385

SUB

The SUB statement marks the beginning of a VAX BASIC subprogram and
specifies the number and data type of its parameters.

Format

SUB

sub-name [ pass-mech ][ ([ formal-param |,... ) ]
[ statement |]...

{ END SUB }
SUBEND

pass-mech:

{ BY DESC }

BY REF

( unsubs-var

formal-param:

[ data-type ] [ array-name ( [ int-const]

[ = int-const ] [ pass-mech |

Syntax Rules

Sub-name is the name of the separately compiled subprogram.
Formal-param specifies the number and type of parameters for the

arguments the SUB subprogram expects to receive when invoked.
e

Empty parentheses indicate that the SUB subprogram has no
parameters.

4-386

Statements and Functions

SUB

and their size, range, and precision are listed in Table 1-2 in this
manual.

Sub-name can have from 1 to 31 characters and must conform to the

following rules:
*

The first character of an unquoted name must be an alphabetic

character (A through Z). The remaining characters, if present, can
be any combination of letters, digits (0 through 9), dollar signs ($),

periods (. ), or underscores (_).
*

A quoted name can consist of any combination of printable ASCII
characters.

Data-type can be any VAX BASIC data type keyword or a data type
defined by a RECORD statement.

Pass-mech specifies the parameter passing mechanism by which the

subprogram receives arguments.
A pass-mech clause outside the parentheses applies by default to all

SUB parameters. A pass-mech clause in the formal-param list overrides
the specified default and applies only to the immediately preceding
parameter.

Remarks

The SUB statement must be the first statement in the SUB subprogram.

Compiler directives and comment fields created with an exclamation
point (!), can precede the SUB statement because they are not VAX
BASIC statements. Note that REM is a VAX BASIC statement;
therefore, it cannot precede the SUB statement.
Every SUB statement must have a corresponding END SUB statement

or SUBEND

statement.

If you do not specify a passing mechanism, the SUB program receives
arguments by the default passing mechanisms, as shown in Table 4-1.

Statements and Functions

4-387

SUB

Parameters defined in formal-param must agree in number, type,
ordinality, and passing mechanism with the arguments specified in the
CALL statement of the calling program.
You can specify up to 255 parameters.

Any VAX BASIC statement except those that refer to other program
unit types (FUNCTION, PICTURE or PROGRAM) can appear in a SUB
subprogram.

All variables, except those named in MAP and COMMON statements
are local to that subprogram.

VAX BASIC initializes local variables to zero or the null string.

A
4-1
Table
VALUE.
BY
parameter
any
receive
cannot
SUB subprogram
lists and describes VAX BASIC parameter-passing mechanisms.

10. SUB subprograms receive parameters by reference or by descriptor.

BY REF specifies that the subprogram receives the argument’s
address.

BY DESC specifies that the subprogram receives the address of a
VAX BASIC descriptor. For information about the format of a VAX
BASIC descriptor for strings and arrays, see the VAX BASIC User
Manual. For information on other types of descriptors, see the VAX
Architecture Handbook.

11.

By default, VAX BASIC subprograms receive numeric unsubscripted
variables by reference, and all other parameters by descriptor. You can
override these defaults for strings and arrays with a BY clause:
e

If you specify a string length with the =int-const clause, you must
also specify BY REF. If you specify BY REF and do not specify a
string length, VAX BASIC uses the default string length of 16.

If you specify array bounds, you must also specify BY REF.

12. Subprograms can be called recursively.

4-388

Statements and Functions

SUB

Example

SUB

SUB3

BY REF

(DOUBLE A,

STRING Emp_ nam BY DESC,

&
&

wage (20))

END

SUB

Statements and Functions

4-389

SUBEND

SUBEND
The SUBEND statement is a synonym for the END SUB statement. See the

END statement for more information.

Format

SUBEND

4-390

Statements and Functions

SUBEXIT

SUBEXIT
The SUBEXIT statement is a synonym for the EXIT SUB statement. See
the EXIT statement for more information.

Format

SUBEXIT

Statements and Functions

4-391

SUM$

SUM$
The SUM$ function returns a string whose value is the sum of two numeric
strings.

Format

str-var = SUMS$ (str-exp1, str-exp2)

Syntax Rules

None.

Remarks

The SUMS$ function does not support E-format notation.
Each string expression can contain up to 54 ASCII digits and an optional

decimal point and sign.
3.

VAX BASIC adds str-exp2 to str-expl and stores the result in str-var.

If str-expl and str-exp2 are integers, str-var takes the precision of the
larger string unless trailing zeros generate that precision.

If str-expl and str-exp2 are decimal fractions, str-var takes the precision
of the more precise fraction, unless trailing zeros generate that precision.

4-392

SUMS$ omits trailing zeros to the right of the decimal point.

The sum of two fractions takes precision as follows:
*

The sum of the integer parts takes the precision of the larger part.

The sum of the decimal fraction part takes the precision of the more
precise part.

Statements and Functions

SUM$

SUMS truncates leading and trailing zeros.

Example

DECLARE
A

"46"

ng7v

STRING A,

total

total = SUMS (A, B)
PRINT

total

Output
133

Statements and Functions

4-393

SWAP%

SWAP%
The SWAP% function transposes a WORD integer’s bytes.

NOTE
The SWAP% function is supported only for compatibility with

BASIC-PLUS-2. DIGITAL recommends that you do not use the
SWAP% function for new program development.

Format

int-var = SWAP% (int-exp)

Syntax Rules

None.

Remarks

4-394

SWAP% is a WORD function. VAX BASIC evaluates int-exp and converts
it to the WORD data type, if necessary.

VAX BASIC transposes the bytes of int-exp and returns a WORD integer.

Statements and Functions

SWAP%

Example

DECLARE
word int

INTEGER word int
= SWAP%(23)

PRINT word int

Output
5888

Statements and Functions

4-395

TAB

TAB
When used with the PRINT statement, the TAB function moves the cursor
or print mechanism to a specified column.

When used outside the PRINT statement, the TAB function creates a string

containing the specified number of spaces.

Format

str-var =TAB (int-exp)

Syntax Rules

When used with the PRINT statement, int-exp specifies the column
number of the cursor or print mechanism.

When used outside the PRINT statement, int-exp specifies the number of

spaces in the returned string.

Remarks

You cannot tab beyond the current MARGIN restriction.
The leftmost column position is zero.

If int-exp is less than the current cursor position, the TAB function has
no effect.

The TAB function can move the cursor or print mechanism only from the
left to the right.

You can use more than one TAB function in the same PRINT statement.

Use semicolons to separate multiple TAB functions in a single statement.

If you use commas, VAX BASIC moves to the next print zone before
executing the TAB function.
4-396

Statements and Functions

TAB

7. If you specify a floating-point expression for ini-exp, VAX BASIC
truncates it to LONG integer.

Example
PRINT "Number 1"; TAB(15); "Number 2"; TAB(30); "Number 3"
Output
Number 1

Number 2

Number 3

Statements and Functions

4-397

TAN

TAN
The TAN function returns the tangent of an angle in radians or degrees.

Format
real-var =TAN(real-exp)

Syntax Rules

Real-exp is an angle specified in radians or degrees, depending on which
angle clause you choose with the OPTION statement.

Remarks

VAX BASIC expects the argument of the TAN function to be a real

expression. When the argument is a real expression, VAX BASIC returns
a value of the same floating-point size. When the argument is not a real

expression, VAX BASIC converts the argument to the default floating-point
size and returns a value of the default floating-point size.

Example

OPTION ANGLE

= DEGREES

DECLARE

REAL

tangent

TAN(45.0)

tangent

Output
1

4-398

Statements and Functions

TIME

TIME
The TIME function returns the time of day (in seconds) as a floating-point
number. The TIME function can also return process CPU time and connect
time.

Format

real-var =TIME (int-exp)

Syntax Rules

None.

Remarks

The value returned by the TIME function depends on the value of
int-exp.

If int-exp equals zero, TIME returns the number of seconds since
midnight.

3. VAX BASIC also accepts values 1 and 2 and returns values as shown in
Table 4-7. All other arguments to the TIME function are undefined and
cause VAX BASIC to signal “Not implemented” (ERR=250).
4.

The TIME function returns a SINGLE floating-point value.
If you specify a floating-point expression for int-exp, VAX BASIC

truncates it to a LONG integer.

Statements and Functions

4-399

TIME

Table 4-7:

TIME Function Values

Argument Value:

VAX BASIC Returns:

The amount of time elapsed since midnight in seconds

The CPU time of the current process in tenths of a second

The connect time of the current process in minutes

Example

TIME (0)

Output
49671

4-400

Statements and Functions

TIME$S

TIME$
The TIME$ function returns a string displaying the time of day in the form
hh:mm AM or hh:mm PM.

Format

str-var =TIMES$ (int-exp)

Syntax Rules

Int-exp specifies the number of minutes before midnight.

Remarks

If int-exp equals zero, TIME$ returns the current time of day.

The value of int-exp must be between 0 and 1440 or VAX BASIC signals
an error.

The TIMES$ function uses a 12-hour, AM/PM clock. Before 12:00 noon,
- TIMES$ returns hh:mm AM, and after 12:00 noon, hh:mm PM.

If you specify a floating-point expression for int-exp, VAX BASIC
truncates it to a LONG integer.

Statements and Functions

4-401

TIME$

Example

DECLARE

STRING current_time

current_time = TIMES (0)
PRINT current time

Output
01:51

4-402

Statements and Functions

TRM$

TRM$
The TRM$ function removes all trailing blanks and tabs from a specified
string.

Format

str-var =TRM$(str-exp)

Syntax Rules

None.

Remarks

The returned str-var is identical to sir-exp, except that it has all the trailing
blanks and tabs removed.

Example

DECLARE

STRING old_string,

old_string =

new_string

"ABCDEFG

new_string = TRM$ (old_string)
PRINT

old_string;"XYz"

PRINT new_string;"XYZ"

Output
ABCDEFG

XY2Z

ABCDEFGXY2Z

Statements and Functions

4-403

UBOUND

UBOUND
The UBOUND function returns the upper bounds of a compile-time or
run-time dimensioned array.

Format
num-var = UBOUND (array-name [, num-exp ])

Syntax Rules

Array-name must specify an array that has been previously explicitly or

implicitly declared.
2.

Num-exp specifies the number of the dimension for which you have

requested the upper bound.

Remarks

If you do not specify a numeric expression, VAX BASIC automatically

returns the upper bound of the first dimension.

If you specify a numeric expression that is less than or equal to zero,
VAX BASIC signals an error message.

If you specify a numeric expression that exceeds the number of
dimensions, VAX BASIC signals an error message.

4-404

Statements and Functions

UBOUND

Example

DECLARE

INTEGER CONSTANT

DIM A (B)

account num =

FOR dim num = 0

A(dim num)

TO UBOUND (A)

= account num

account_num =

account

num

PRINT A (dim_num)

dim_num

Output

Statements and Functions

4-405

UNLESS

UNLESS
The UNLESS qualifier modifies a statement. VAX BASIC executes the
modified statement only if a conditional expression is false.

Format

statement UNLESS cond-exp

Syntax Rules

None.

Remarks

The UNLESS statement cannot be used on nonexecutable statements or
on statements such as SELECT, IF, and DEF that establish a statement
block.

VAX BASIC executes the statement only if cond-exp is false (value zero).

Example

PRINT "A DOES NOT EQUAL 3" UNLESS A% = 3%

4-406

Statements and Functions

UNLOCK

UNLOCK
The UNLOCK statement unlocks the current record or bucket locked by the
last FIND or GET statement.

UNLOCK

#chnl-exp

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number associated
with a file. It must be immediately preceded by a number sign (#).

Remarks

A file must be opened on the specified channel before UNLOCK can
execute.

The UNLOCK statement only applies to files on disk.
If the current record is not locked by a previous GET or FIND statement,
the UNLOCK statement has no effect and VAX BASIC does not signal
an error.

The UNLOCK statement does not affect record buffers.

After VAX BASIC executes the UNLOCK statement, you cannot update
or delete the current record.

Once the UNLOCK statement executes, the position of the current
record pointer is undefined.

Statements and Functions

4—407

UNLOCK

Example

UNLOCK #10%

4-408

Statements and Functions

UNTIL

UNTIL
The UNTIL statement marks the beginning of an UNTIL loop or modifies
the execution of another statement.

Format
Conditional

UNTIL

cond-exp
[ statement |...

NEXT
Statement Modifier

statement UNTIL cond-exp

Syntax Rules

None.

Statements and Functions

4-409

UNTIL

Remarks

Conditional
*

A NEXT statement must end the UNTIL loop.

VAX BASIC evaluates cond-exp before each loop iteration. If the
expression is false (value zero), VAX BASIC executes the loop. If

the expression is true (value nonzero), control passes to the first
executable statement after the
2.

NEXT statement.

Statement Modifier

VAX BASIC executes the statement repeatedly until cond-exp is true.

Examples

Example 1
!Conditional

UNTIL A >=
A

=24+

TOTAL

.01
TOTAL

Example 2
!Statement Modifier
A=A

4-410

UNTIL A

Statements and Functions

200

UPDATE

UPDATE
The UPDATE statement replaces a record in a file with a record in the
record buffer. The UPDATE statement is valid on sequential, relative, and
indexed files.

Format

UPDATE

#chnl-exp [, COUNT int-exp ]

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number
associated with a file. It must be immediately preceded by a number

sign (#).

Int-exp specifies the size of the new record.

Remarks

The file associated with chnl-exp must be a disk file opened with
ACCESS MODIFY.

Each UPDATE statement must be preceded by a successful GET or
FIND operation or VAX BASIC signals “No current record” (ERR=131).
FIND locates but does not retrieve records. Therefore, you must specify
a COUNT clause when retrieving variable-length records when the
preceding operation was a FIND. Int-exp must exactly match the size of
the old record.

If you are updating a variable-length record, and the record that you
want to write out is not the same size as the record you retrieved, you
must use a COUNT clause.

Statements and Functions

4-411

UPDATE

After an UPDATE statement executes, there is no current record pointer.
The next record pointer is unchanged.

The length of the new record must be the same as that of the existing
record for all files with fixed-length records and for all sequential files.
If you specify a COUNT clause, the int-exp must match the size of the
existing record.
For relative files with variable-length records, the new record can be

larger or smaller than the record it replaces.
*

The new record must be smaller than or equal to the maximum

record size set with the MAP or RECORDSIZE clause when the file
was opened.

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

operation on that channel.
For indexed files with variable-length records, the new record can be
larger or smaller than the record it replaces. When the program does

not permit duplicate primary keys, the new record can be no longer than
the size specified by the MAP or RECORDSIZE clause when the file was

opened. The record must include at least the primary key field.
An indexed file alternate key for the new record can differ from that of
the existing record only if the OPEN statement for that file specified

CHANGES for the alternate key.

Example

UPDATE #4%,

4-412

COUNT 32

Statements and Functions

VAL

VAL
The VAL function converts a numeric string to a floating-point value.

NOTE
DIGITAL recommends that you use the DECIMAL, REAL, and

INTEGER functions to convert numeric strings to numeric data
types.

Format
real-var = VAL (str-exp)

Syntax Rules

Str-exp can contain the ASCII digits 0 through 9, uppercase E, a plus sign

(+), a minus sign (-), and a period (. ).

Remarks

1.
2.

The VAL function ignores spaces and tabs.
If str-exp is null, or contains only spaces and tabs, VAL returns a value
of zero.

The value returned by the VAL function is of the default floating-point
size.

Statements and Functions

4-413

VAL

Example

DECLARE REAL

real num

real _num = VAL ("990.32")
PRINT

real num

Output
990.32

4-414

Statements and Functions

VAL%

VAL%
The VAL% function converts a numeric string to an integer.
NOTE

DIGITAL recommends that you use the DECIMAL, REAL, and
INTEGER functions to convert numeric strings to numeric data
types.

Format

int-var = VAL% (str-exp)

Syntax Rules
Str-exp can contain the ASCII digits 0 through 9, a plus sign (+), or a minus
sign (-).

Remarks

The VAL% function ignores spaces and tabs.

If str-exp is null or contains only spaces and tabs, VAL% returns a value
of zero.

The value returned by the VAL% function is an integer of the default
size.

Statements and Functions

4-415

VAL%

Example

DECLARE

INTEGER

ret_int

= VAL%("789")

ret int

Output
789

4-416

Statements and Functions

ret int

VMSSTATUS

VMSSTATUS
VMSSTATUS returns the underlying VMS condition code when control is

transferred to a VAX BASIC error handler.

Format
int-var = VMSSTATUS

Syntax Rules

None.

Remarks

If ERR contains the value 194, you can specify VMSSTATUS to examine
the actual error that was signaled to VAX BASIC.

If an error is raised by an underlying system component such as the
Run-Time Library, you can specify VMSSTATUS to determine the
underlying error.

If you are writing a utility routine that may be called from languages
other than VAX BASIC, you can specify VMSSTATUS in a call to

LIB$SIGNAL to signal the underlying error to the caller of the utility
routine.

When there is no error pending, VMSSTATUS remains undefined.

Statements and Functions

4-417

VMSSTATUS

Example

PROGRAM
WHEN

END

ERROR

USE

global handler

final status%

= VMSSTATUS

HANDLER

END PROGRAM

4-418

handler

WHEN

HANDLER
END

global

final status$%

Statements and Functions

WAIT

WAIT
The WAIT statement specifies the number of seconds the program waits for
terminal input before signaling an error.

Format

WAIT

int-exp

Syntax Rules
Int-exp must be between 0 and 255; if it is greater than 255, VAX BASIC
assumes a value of 255.

Remarks

The WAIT statement must precede a GET operation to a terminal or
an INPUT, INPUT LINE, LINPUT, MAT INPUT, or MAT LINPUT
statement. Otherwise, it has no effect.

Int-exp is the number of seconds VAX BASIC waits for input before
signaling the error, “Keyboard wait exhausted” (ERR=15).
3. After VAX BASIC executes a WAIT statement, all input statements wait
the specified amount of time before VAX BASIC signals an error.

WAIT 0 disables the WAIT statement.

Statements and Functions

4-419

WAIT

Example

DECLARE
WAIT
INPUT

WAIT

STRING your name

60
"You

have

sixty

seconds

type

your

name";your name

Output
You have

sixty

seconds

type your

$BAS-F-KEYWAIEXH,

Keyboard wait

—BAS-I-ON_CHAFIL,

-RMS-W-TMO,

timeout

-BAS-I-FROLINMOD,

name

—————

above

for

symbolic

line

condition handler

called with

keyboard wait
on

timeout

user PC

00000644

follows

routine name

$BAS-F-KEYWAIEXH,

—————

SYS$INPUT:.;

in module WAIT

stack dump

-BAS~I-ON_CHAFIL,

-RMS-W-TMO,

file

expired

from line

3TRACE-F-TRACEBACK,
module

channel
period

name?

exhausted

channel

exception

rel PC

abs PC

00007334

001A807C:

exhausted
for

file

SYS$INPUT:.;

user PC

00000644

period expired

end of exception message

00011618

WAITSMAIN

4-420

WAITSMAIN

Statements and Functions

00011618

0000F02F

OOO0OOQFO2F

0000E3F6

O0OOOQE3F6

0001387A

00000044

00000644

WHEN ERROR

WHEN ERROR
The WHEN ERROR statement marks the beginning of a WHEN ERROR
construct. The WHEN ERROR construct contains a protected region and
can include an attached handler or identify a detached handler.

Format
With an Attached Handler

WHEN ERROR IN

protected-statement
[ protected-statement,... ]

USE

handler-statement

[ handler-statement,... ]

END WHEN
With a Detached Handler

WHEN ERROR USE

handler-name

protected-statement

[ protected-statement,... ]

END WHEN

Statements and Functions

4-421

WHEN ERROR

HANDLER

handler-name

handler-statement...

END HANDLER

Syntax Rules

Protected-statement specifies a statement that appears within a protected

region. A protected region is a special block of code that is monitored by
VAX BASIC for the occurrence of a run-time error.
2.

Handler-statement specifies the statement that appears inside an error

With an Attached Handler

handler.

The keyword USE marks the start of handler statements.

An attached handler must be delimited by a USE and END WHEN
statement.

With a Detached Handler
*

The keyword USE names the associated handler for the protected

region.

Handler-name must be a valid VAX BASIC identifier and cannot be
the same as any label, DEF, DEF*, SUB, FUNCTION or PICTURE

name within the same program unit.
*

A detached handler must be delimited by a HANDLER and END
HANDLER statement.

You can specify the same detached handler with more than one
WHEN ERROR USE statement.

4-422

Statements and Functions

WHEN ERROR

Remarks

The WHEN ERROR statement designates the start of a block of
protected statements.

If an error occurs inside a protected region, VAX BASIC transfers control
to the error handler associated with the WHEN ERROR statement.
VAX BASIC does not allow you branch into a WHEN block.
When VAX BASIC encounters an END WHEN statement for an attached
handler or an END HANDLER statement for a detached handler,
VAX BASIC clears the exception and transfers control to the following
statement.

VAX BASIC allows you to nest WHEN blocks. If an exception occurs

within a nested protected region, VAX BASIC transfers control to the
handler associated with the innermost protected region in which the
error occurred.

WHEN blocks cannot exist inside a handler.
WHEN blocks cannot cross other block structures.

You cannot specify a RESUME statement within a WHEN ERROR
construct.

You cannot specify an ON ERROR statement within a protected region.
10. An attached handler must immediately follow the protected region of a
WHEN ERROR IN block.

11.

Exit from a handler must occur through a RETRY, CONTINUE, or EXIT
HANDLER statement, or by reaching the end of the handler delimited

by END WHEN or END HANDLER.

12. For more information about detached handlers, see the HANDLER
statement.

Statements and Functions

4-423

WHEN ERROR

Examples

Example 1
IWith an

attached handler

PROGRAM

salary

DECLARE

REAL hourly_rate,

WHEN

ERROR

INPUT

"Enter

INPUT

"Enter the

weekly pay
PRINT

your

no_of_hours,

hourly

number

rate”;hourly

of hours

= no_of hours

"Your pay

for

weekly pay

this

rate

you worked this

hourly rate

week

is";weekly pay

USE
SELECT

ERR

CASE =

50
PRINT

"Invalid data"

RETRY

CASE ELSE
EXIT

END

HANDLER

SELECT

END

WHEN

END

PROGRAM

Output
Enter

your

Enter

the

Your pay

4-424

hourly

number

for

this

Statements and Functions

rate?

35.00

of hours

week is

you worked this

1575

week?

week";no of hours

WHEN ERROR

Example 2
!With a detached handler
PROGRAM salary

DECLARE REAL hourly rate,

no_of hours,

weekly pay

WHEN ERROR USE patch work
INPUT

"Enter your hourly

INPUT

"Enter the number of hours you worked this week";no_of hours

weekly pay = no_of hours

PRINT
END

"Your pay

rate";hourly
rate
*

hourly_ rate

for this week is";weekly
pay

WHEN

HANDLER patch_work
SELECT

ERR

CASE =

"Invalid data"

RETRY

CASE ELSE
EXIT

END
END

HANDLER

SELECT

HANDLER

END PROGRAM

Output
Enter your hourly rate?

Nineteen dollars and fifty cents

Invalid data
Enter your hourly

rate?

19.50

Enter the number of hours you worked this week?
Your pay

for this week is

780

Statements and Functions

4—-425

WHILE

WHILE
The WHILE statement marks the beginning of a WHILE loop or modifies
the execution of another statement.

Format
Conditional

WHILE

cond-exp

[ statement ]...

NEXT
Statement Modifier

statement WHILE cond-exp

Syntax Rules

A NEXT statement must end the WHILE loop.

Remarks

Conditional

VAX BASIC evaluates cond-exp before each loop iteration. If the
expression is true (value nonzero), VAX BASIC executes the loop. If the
expression is false (value zero), control passes to the first executable

statement after the

4-426

Statements and Functions

NEXT statement.

WHILE

Statement Modifier

VAX BASIC executes the statement repeatedly as long as cond-exp is
true.

Examples

Example 1
!Conditional
WHILE X <
X

100
+

SQOR(X)

Example 2
IStatement Modifier

= X%

1% WHILE X%

100%

Statements and Functions

4-427

XLATES$

XLATES$
The XLATE$ function translates one string to another by referencing a table
string you supply.

Format

str-var = XLATE[$] (str-exp1, str-exp2)

Syntax Rules

Str-expl is the input string.

Str-exp2 is the table string.

Remarks

Str-exp2 can contain up to 256 ASCII characters, numbered from 0 to

255; the position of each character in the string corresponds to an ASCII
value. Because 0 is a valid ASCII value (null), the first position in the
table string is position zero.

XLATES$ scans str-expl character by character, from left to right. It
finds the ASCII value n of the first character in str-expl and extracts
the character it finds at position » in str-exp2. XLATE$ then appends
the character from str-exp2 to str-var. XLATE$ continues this process,

character by character, until the end of str-expl is reached.

4-428

Statements and Functions

XLATES

The output string may be smaller than the input string for the following
reasons:

XLATE$ does not translate nulls. If the character at position n in
str-exp2 is a null, XLATE$ does not append that character to str-var.

If the ASCII value of the input character is outside the range of

positions in str-exp2, XLATE$ does not append any character to
str-var.

Example

DECLARE

A =

STRING A,

table,

source

"abcdefghijklmnopgrstuvwxyz"

table =
LINPUT

STRINGS (65,
"

Type

string

PRINT XLATES (source,

+ A
of

uppercase

letters";

source

table)

Output
Type

string of uppercase

letters? ABCDEFG

abcdefg

Statements and Functions

4—429

Appendix A

Transporting Programs Between VAX BASIC
and BASIC-PLUS-2

This appendix summarizes transportability issues
and VAX BASIC.

A.1

between BASIC-PLUS-2

Overview
This appendix is for users who want to write BASIC
programs that can
be used in both VAX BASIC and PDP-11 BASICPLUS-2. It describes
functionality that is particular to one language, as
well as statements and
functions that appear the same in both langua
ges, but produce different
results.
Note that this appendix does not describe all the
differences between
VAX BASIC and BASIC-PLUS-2. To assist you in
writing transportable
programs, use the DCL command BASIC/FLAG

=BP2COMPATIBILITY

when you invoke VAX BASIC. This command causes
an informational message whenever you use

compatible with BASIC-PLUS-2.

VAX BASIC to signal

functionality that is not

This appendix contains the following sections:
*

Language-specific functionality

/O differences

Procedure calling

Generated errors

Miscellaneous differences

Transporting Programs Between VAX BASIC and BASIC-

PLUS-2

A-1

A.2 Language-Specific Functionality
The following statements, functions, and clauses are available only in
BASIC-PLUS-2:

Specifying a line number with the CHAIN statement T

The FSS$ function

The ONECHR function (see the VAX BASIC INKEY$ function)
The PEEK function ¥

The SPEC% function ¥

The CLUSTERSIZE and MODE clauses on the OPEN statement T
VAX BASIC supports the following functionality which is not available in
BASIC-PLUS-2:
LJ

Graphics

Support for the VAX Language-Sensitive Editor (LSE)
Support for the Program Design Facility (PDF)
Support for the VAX Source Code Analyzer (SCA)
Non-zero lower bounds for arrays
WHEN blocks

Return values on the END, EXIT DEF, END DEF, EXIT FUNCTION,
and END FUNCTION statements

Dollar sign ($) and percent sign (%) suffixes in explicitly declared

variables

User-defined data types with the RECORD statement
DECIMAL, GFLOAT, and HFLOAT data types
Hexadecimal, binary, and octal literal notation

The following statements, functions, and commands are available only in

VAX BASIC:

The %DECLARED directive

The %INCLUDE %FROM %CDD directive
The %INCLUDE %FROM %LIBRARY directive
The %PRINT directive

The %REPORT %DEPENDENCY directive

T Specific to BASICA-PLUS-Z on RSTS/E systems.

A-2 Transporting Programs Between VAX BASIC and BASIC-PLUS-2

All graphics statements

The CAUSE ERROR statement

The FREE statement

The FIND statement with the ALLOW, REGA

RDLESS, and WAIT

clauses
®*

The GET statement with the ALLOW, REGA

®*

The MID$ assignment statement

The OPTION CONSTANT TYPE, OPTION
HANDLE, and OPTION
ANGLE statements

The PROGRAM, END PROGRAM and EXIT

The RECORD statement

RDLESS, and WAIT clauses

PROGRAM statements

All WHEN block statements and clauses (WHEN

...END WHEN,

HANDLER...END HANDLER, CONTINUE, RETRY

, and EXIT

HANDLER)

A.3

The DECIMAL function

The INKEYS$ function

The LBOUND and UBOUND functions

The LOC function

The MARGIN and

°*

The MAX, MIN, and MOD functions

The VMSSTATUS and RMSSTATUS functions

The ANY and OPTIONAL keywords in EXTE

NOMARGIN functions

RNAL routine declarations

1/0 Differences
This section discusses some I/O differences betwee
n VAX BASIC and
BASIC-PLUS-2.

A.3.1

The MAGTAPE Function
VAX BASIC does not support the MAGTAPE functio

n except for the rewind
tape function (code 3). Table A-1 describes the
VAX BASIC actions you can
perform to obtain other MAGTAPE functionality.

Transporting Programs Between VAX BASIC and BASIC-

PLUS-2

A-3

Table A-1: MAGTAPE Functionality in VAX BASIC
Code

Function

Write EOF

Rewind tape

VAX BASIC Action

Close channel with the CLOSE statement

Use the RESTORE # statement, the REWIND clause
on an OPEN statement, or the MAGTAPE function

Skip records

Perform GET operations, ignore data until reaching

Backspace

Rewind tape, perform GET operations, ignore data

Set density or set parity

Get status

A.3.2

The OPEN Statement

desired record

until reaching desired record

Use the DCL commands MOUNT/DENSITY and

MOUNT/FOREIGN or the $MOUNT system service

Use the RMSSTATUS function

The following differences exist in the OPEN statement when used in VAX
BASIC and BASIC-PLUS-2:

zed;
e In VAX BASIC, a map named in an OPEN statement is never initiali
the
to
or
zero
to
zed
in BASIC-PLUS-2, variables in the map are initiali
null string.

In VAX BASIC, an OPEN error causes the STATUS variable to be set to
zero. In BASIC-PLUS-2, an OPEN error causes the STATUS variable to
be set to the RMS STS field value. Use the VAX BASIC RMSSTATUS
function to return the RMS STS field value.

Both VAX BASIC and BASIC-PLUS-2 allow you to omit key clauses
when opening an existing indexed fie. However, VAX BASIC requires
that you explicitly specify FOR INPUT; BASIC-PLUS-2 does not.

The following OPEN statement clauses produce different results when used
in VAX BASIC and BASIC-PLUS-2:
e

The ALLOW Clause

VAX BASIC requires that you have write access to a file in order to
specify ALLOW NONE in an OPEN statement; BASIC-PLUS-2 does not.

A-4 Transporting Programs Between VAX BASIC and BASIC-PLUS-2

The CLUSTERSIZE Clause

The CLUSTERSIZE clause can be used with an OPEN statement on
RSTS/E systems only. In VAX BASIC and BASIC-PLUS-2 on RSX

systems, you can obtain functionality similar to the CLUSTERSIZE

clause by using the EXTENDSIZE and WINDOWSIZE clauses. The
EXTENDSIZE clause specifies the amount of space a file is extended
after the existing space is full. The WINDOWSIZE clause specifies the
number of block retrieval pointers that are kept in memory for the file.
The CONTIGUOUS Clause
In VAX BASIC, using the CONTIGUOUS clause with an OPEN

statement does not necessarily mean the file will occupy contiguous
disk space. If there is not enough contiguous space available, RMS
allocates the largest possible contiguous space and does not signal

an error. In BASIC-PLUS-2, if there is not enough contiguous space

available, RMS signals an error.

The MODE Clause
The MODE clause cannot be used with an OPEN statement in VAX

BASIC. In BASIC-PLUS-2 on RSX systems, the MODE clause is ignored
except when used for device-specific I/O. Table A-2 lists transportable

BASIC statements that correspond to RSTS/E disk MODE values. You
can use these statements in VAX BASIC as well as in BASIC-PLUS-2 on

RSX systems.
Table A-2:

RSTS/E Disk MODE Values and Corresponding BASIC Statements

MODE
Value

Function

Normal read/write

Transportable Statement
Use OPEN with ACCESS MODIFY and

ALLOW MODIFY
1%

Update file

Use OPEN with ACCESS MODIFY

Append to file

Use OPEN with ACCESS APPEND

Update file

Use OPEN with ACCESS MODIFY and

ALLOW MODIFY
16%

Create contiguous

Use OPEN with CONTIGUOUS

32%

Create tentative file

Use OPEN with TEMPORARY

(continued on next page)

Transporting Programs Between VAX BASIC and BASIC-PLUS-2

A-5

Table A-2 (Cont.): RSTS/E Disk MODE Values and Corresponding BASIC Statements
MODE

Value

Function

Transportable Statement

64%

Create contiguous file

Use OPEN with CONTIGUOUS

Read only regardless

Use GET or FIND with REGARDLESS'

conditionally

8192%

Read Only

4096%

Use OPEN with ACCESS READ

1The REGARDLESS clause is not available in BASIC-PLUS-2.

The RECORDSIZE Clause

In all VAX BASIC files and BASIC-PLUS-2 RMS files, the RECORDSIZE
clause specifies the RMS logical record size. In BASIC-PLUS-2 virtual
files, the RECORDSIZE clause specifies the size of the I/O buffer for the
channel.

A.3.3

The PUT Statement

In VAX BASIC, a PUT statement with a count of zero to a variable length
file creates a record with a length of zero; in BASIC-PLUS-2, the size of
the record created is the size specified in the RECORDSIZE clause or, if no
RECORDSIZE clause is specified, the length of the longest map.

A.4

Procedure Calling
This section discusses some differences in procedure calling between

VAX BASIC and BASIC-PLUS-2.

A.4.1

The CALL Statement

The following difference occur in the CALL statement when used in

VAX BASIC and BASIC-PLUS-2:

TIn VAX BASIC, you can use the CALL statement to call a procedure that
is written in any language which supports the VAX Procedure Calling
Standard. In BASIC-PLUS-2, you can use the CALL statement to call
only BASIC-PLUS-2 and MACRO subprograms.

A-6 Transporting Programs Between VAX BASIC and BASIC-PLUS-2

In VAX BASIC, individual array element parameters (except virtual
array elements) are passed by reference and are modifiable. In

BASIC-PLUS-2, individual array element parameters are passed by
local copy and are not modifiable.
*

VAX BASIC does not allow passing of entire virtual arrays;

BASIC-PLUS-2 allows passing of entire virtual arrays.
*

A.4.2

In VAX BASIC, you can pass up to 255 parameters in each subprogram.
In BASIC-PLUS-2, you can pass up to 8 parameters in each subprogram.

The CHAIN Statement
In VAX BASIC and in BASIC-PLUS-2 on RSX systems, you cannot specify a

line number in a CHAIN statement. In BASIC-PLUS-2 on RSTS/E systems,
line numbers are allowed.

A.4.3

SYS and FIP SYS Calls
VAX BASIC supports a subset of RSTS/E SYS and FIP calls. These are
summarized in Tables A-3 and A—4.

Table A-3:

VAX BASIC Subset of RSTS/E SYS Calls

Function

Code

Function

Cancel CTRL/O effect on terminal

Enable echoing on terminal

Disable echoing on terminal

Exit with no prompt message

SYS call to the file processor

Get core common string

Put core common string

Exit and clear program

Cancel all type ahead

Transporting Programs Between VAX BASIC and BASIC-PLUS-2

A-7

Table A-4:

VAX BASIC Subset of RSTS/E FIP SYS Calls

Function

Code

Function

—23

Terminate file name string scan

-13

Change priority/run burst/job size

-10

Begin file name string scan

-7

Enable CTRL/C trap

Return error messages

Assign user logical

Deallocate a device or deassign user logical

Deallocate all devices

Obsolete (use function code 22)

Message send/receive

Note that the FIP call for sending or receiving messages (code 22) produces

different results when used in VAX BASIC and BASIC-PLUS-2 on RSTS/E
systems. In VAX BASIC, a receiver identification is removed from the
receiver table when the image that declared it exits; in BASIC-PLUS-2
on RSTS/E systems, a receiver identification stays in the receiver table
until it is explicitly removed or the job terminates. This difference causes
incompatible behavior with chained programs, because in VAX BASIC the
receiver identification is valid only for the program that declares it; whereas
in BASIC-PLUS-2 on RSTS/E systems, the chained programs can share

a receiver identification. DIGITAL recommends the use of mailboxes or
DECnet task-to-task communication as a replacement for these FIP calls in
VAX BASIC.

A.5

Generated Errors
In VAX BASIC and BASIC-PLUS-2, the same errors are handled differently
or signal different error messages and numbers:
e

If you press CTRL/Z after responding to an INPUT statement, VAX
BASIC makes the assignment and signals the error “End of file
on device” (ERR=11) when the next INPUT statement executes;

BASIC-PLUS-2 signals the same error, does not make the assignment,
and terminates the current input line.

A-8

Transporting Programs Between VAX BASIC and BASIC-PLUS-2

When nonnumeric or floating-point data is input to an INPUT or READ
statement expecting numeric or integer data, VAX BASIC signals the

error “Data format error” (ERR=50); BASIC-PLUS-2 signals the error

“Illegal number” (ERR=52).

When the integer index of a FOR loop exceeds the default integer size,
VAX BASIC signals the error “Integer error or overflow” (ERR=51);

BASIC-PLUS-2 signals the error “Integer overflow, FOR loop” (ERR=60).

When a program opens channel 0, VAX BASIC signals the error “Illegal
I/O channel” (ERR=46); BASIC-PLUS-2 signals the error “I/O channel

already open at line <line number>” (ERR=7).

If no error handler is active, the errors in Table A-5 are fatal errors in
VAX BASIC, but warnings in BASIC-PLUS-2.
Table A-5:

Fatal Errors in VAX BASIC that are Warnings in BASIC-PLUS-2

Error Number

Message

Floating point error

Integer error

Illegal number

Illegal argument in LOG

Imaginary square roots

Division by zero

When a user has WRITE access to a block in a virtual file and a second
user attempts to access that block, VAX BASIC and BASIC-PLUS-2 on

RSX signal the error “Record/bucket locked” (ERR=154); BASIC-PLUS-2
on RSTS/E signals the error “Disk block is interlocked” (ERR=19).

A.6

Miscellaneous Differences
This section discusses some miscellaneous differences between VAX BASIC

and BASIC-PLUS-2.

Transporting Programs Between VAX BASIC and BASIC-PLUS-2

A-9

A.6.1

Data Types
VAX BASIC supports DECIMAL, HFLOAT, GFLOAT and user-defined data
types; BASIC-PLUS-2 does not. In BASIC-PLUS-2, as an alternative to the
DECIMAL data type, use the DOUBLE data type with the OPTION SCALE
statement or the SCALE command to minimize floating-point inaccuracy.

A.6.2

The DEF and DEF* Statements
In VAX BASIC, you can specify a maximum of 255 parameters in a DEF
statement and a maximum of 8 parameters in a DEF* statement; in
BASIC-PLUS-2, you can specify a maximum of 8 parameters in both the
DEF and DEF* statements.

A.6.3

Default Integer Size
If you do not specify a default integer size when invoking VAX BASIC, the
default integer size is LONGWORD; in BASIC-PLUS-2, the default integer

size is WORD. In VAX BASIC, use the OPTION SIZE=INTEGER WORD
statement or the COMPILE/WORD command to make BASIC-PLUS-2

programs transportable to VAX BASIC.

A.6.4

Integer Overflow
When performing integer arithmetic, VAX BASIC signals an error
message if the size of the value returned exceeds the default integer
size. BASIC-PLUS-2 does not signal an error message, truncates the result,
and returns a signed integer quantity.

To disable error checking for integer overflow in VAX BASIC, use the
OPTION INACTIVE=INTEGER OVERFLOW statement or the DCL
command BASIC/CHECK=NOOVERFLOW.

A.6.5

Line Numbers and Labels
In VAX BASIC, line numbers are optional. In BASIC-PLUS-2, you need at
|
least one line number in each program.
In a VAX BASIC program, labels, compiler directives, and comments can
begin in column zero. In BASIC-PLUS-2, they cannot.

A-10

Transporting Programs Between VAX BASIC and BASIC-PLUS-2

A.6.6

The MAP and COMMON Statements
The MAP and COMMON statements have different functionality when used
in VAX BASIC and BASIC-PLUS-2. The differences are as follows:
e

In VAX BASIC, both COMMON areas and maps can have names
containing a maximum of 31 characters and include underscore ( )

characters. In BASIC-PLUS-2, COMMON areas and maps can have
names containing a maximum of six characters; underscore characters

are not allowed.
*

If two strings overlap in a map, VAX BASIC performs string assignments

as if no overlap exists; BASIC-PLUS-2 performs string assignments one
character at a time from left to right. (Note that RSET assignment is
performed from right to left.) For example:
10

MAP

(FOO)

MAP

(FOO)

FILLS

5
=

’'ABCDE’

PRINT AS

B$ = A$
PRINT BS,

When you run this program in VAX BASIC, the following output is

displayed:

ABCDE

ABABC

When you run this program in BASIC-PLUS-2, the following output is
displayed:
ABCDE

ABABA

A.6.7

ABABA

The MAP DYNAMIC Statement
The following differences occur in the MAP DYNAMIC statement when used
in VAX BASIC and BASIC-PLUS-2:

If the MAP DYNAMIC statement is in an external subprogram or

function, BASIC-PLUS-2 resets all pointers to the first byte each time
the external module is called. VAX BASIC initializes the map area once

when the external module is first called, and does not reset the variables
pointers on subsequent calls.

Transporting Programs Between VAX BASIC and BASIC-PLUS-2

A-11

A.6.8

VAX BASIC allows you to specify a PSECT name or a static string
variable in a MAP DYNAMIC statement; BASIC-PLUS-2 allows you to
specify only a PSECT name.

The PRINT Statement
In VAX BASIC and RSX BASIC-PLUS-2, when you print to a
terminal-format file and the line is to exceed 72 characters, you must
either specify a record size, or a map, or use the VAX BASIC MARGIN
function; this is not the case in BASIC-PLUS-2 on RSTS/E.

A.6.9

The PRINT USING Statement
In VAX BASIC, the PRINT USING string formatting characters (L,R,C,
and E) can be either uppercase or lowercase. In BASIC-PLUS-2, string
formatting characters must be uppercase; otherwise, they are treated as
string literals.

A.6.10

The REPLACE Command
In VAX BASIC, the REPLACE command writes the source program to the
device and directory you specify in the OLD command. In BASIC-PLUS-2,
the REPLACE command writes the source program to the current directory.

A.6.11

The SPEC% and PEEK Functions
You can use the SPEC% and PEEK functions only on RSTS/E systems.
These functions are not transportable.

A.6.12

String Comparisons
When making string comparisons in all relational operations, VAX BASIC
pads the shorter string with a blank space (ASCII value 32). BASIC-PLUS-2
pads the shorter string with a blank space only on equals (=) and not equals
(<>) relational operations.

A-12

Transporting Programs Between VAX BASIC and BASIC-PLUS-2

A.6.13

Assigning Symbols
In VAX BASIC, you use the logical name SYS$CURRENCY

currency symbol, SYSSRADIX_POINT to change the radix

to change the

point symbol, and

SYS$DIGIT_SEP to change the separator symbol. In BASIC-P
LUS-2, you
select the symbols for currency, radix point, and separator when
installing
the compiler.

A.6.14

The TIME Function
The numeric arguments to the TIME function have different

results when
used in VAX BASIC and BASIC-PLUS-2. These differences
are summarized
in Table A—6.

Table A-6:

VAX BASIC and BASIC-PLUS-2 TIME Function Differences

TIME

Argument

Result

In both VAX BASIC and BASIC-PLUS-2, TIME returns the number

of seconds that elapsed since midnight.
1
2

In VAX BASIC and BASIC-PLUS-2 on RSTS/E systems, TIME
returns the current job’s CPU time in tenths of a second.
In VAX BASIC and BASIC-PLUS-2 on RSTS/E systems, TIME

returns the current job’s connect time in minutes.

In VAX BASIC, TIME returns zero. In BASIC-PLUS-2 on RSTS/E

systems, TIME returns kilo-core ticks.

In VAX BASIC, TIME returns zero. In BASIC-PLUS-2 on RSTS/E

systems, TIME returns device time in minutes.

1Zero is the only valid argument for TIME in BASIC-PLUS-2 on RSX systems.

A.6.15

The TIME$ Function
In VAX BASIC, the value returned by the TIME$ function is always
displayed in AM/PM format. In BASIC-PLUS-2, the time can be
expressed
in either AM/PM format or 24-hour format, depending on the option
you
select when installing BASIC-PLUS-2.

Transporting Programs Between VAX BASIC and BASIC-PLUS-2

A-13

Appendix

ANSI Minimal BASIC

This appendix explains the operation of the VAX BASIC compiler when used
with the /ANSI_STANDARD qualifier.

B.1

Introduction
The American National Standard for Minimal BASIC (ANSI X3.60-1978)

describes a nucleus of the BASIC programming language. This nucleus will
be a part of any BASIC implementation that conforms to this standard.

Thus, writing programs that conform to the ANSI Minimal BASIC standard
helps assure that they will run under any standard implementation of

BASIC.

The ANSI Minimal BASIC Standard allows both extensions to the current

standard and features whose behavior is defined by each implementation.
This chapter describes these extensions and implementation-defined

features. Many features of VAX BASIC are allowed as extensions to ANSI
Minimal BASIC. For example, programs with 31-character variable names

will compile correctly; however, VAX BASIC reports an informational

message for each instance of a long variable name. This tells you that your
program does not strictly conform to ANSI Minimal BASIC.

Certain features of VAX BASIC are invalid in ANSI Minimal BASIC

programs. For example, variables ending in a percent sign are invalid

because ANSI Minimal BASIC does not allow integer variables. If you try to
use this VAX feature in ANSI Minimal BASIC, VAX BASIC signals the error

“Integer data type not supported in ANSI.”

For a thorough understanding of ANSI Minimal BASIC, read ANSI

X3.60-1978.

ANSI Minimal BASIC

B-1

Note that the descriptions and explanations in this chapter apply only to
programs compiled or run with the /ANSI_STANDARD qualifier in effect.

The /ANSI _STANDARD Qualifier

B.2

JANSI_STANDARD is a qualifier to both the DCL command BASIC and
to the SET command in the BASIC environment. When you specify this
qualifier, the following qualifiers are not allowed:
o

/ANALYSIS_DATA

/DESIGN

/OPTIMIZE (/NOSETUP in the BASIC environment)

/SCALE

/SYNTAX CHECK

/TYPE_DEFAULT

VAX BASIC signals an error if you use any of these qualifiers in addition to
the /ANSI_STANDARD qualifier.

Note that you cannot use compiler directives in programs compiled with the
/ANSI_STANDARD qualifier. In addition, you cannot use immediate mode
statements while the /ANSI_STANDARD qualifier is in effect.

B.3 Extensions To ANSI Minimal BASIC Standard X3.60-1978
The following items are extensions to the ANSI Minimal BASIC Standard.
In order to write completely transportable programs, you should avoid these
extensions and use only the capabilities allowed by the standard. In most
cases VAX BASIC reports an informational error if you use any extensions.
B.3.1

Program Format

The ANSI Minimal BASIC Standard permits comments only with the REM
statement. With the /ANSI_STANDARD qualifier in effect, VAX BASIC
allows comment fields beginning with an exclamation point and ending with
an exclamation point or a carriage return.

VAX BASIC also allows explicit line continuation with ampersands.
However, implicit line continuation is invalid.

B—-2

ANSI Minimal BASIC

B.3.2

Statements
The ANSI Minimal BASIC Standard requires that each program have

an END statement. In VAX BASIC the END statement is optional. If

your program does not have an END statement, VAX BASIC reports

the

informational message, “ENDSTAREQ, END statement required in ANSI.”

Also, the LET keyword is required in ANSI Minimal BASIC. VAX BASIC

signals “LETKEYREQ, LET keyword required in ANSI” when it encounter
s
an assignment statement without the LET keyword.

B.3.3

Delimiters
The ANSI Minimal BASIC Standard specifies that all keywords must be

preceded by one space and followed by at least one space, if the keyword
is
not at the end of a line. With the /ANSI_STANDARD qualifier in effect,
you
can delimit keywords with either spaces or tabs.

B.3.4

Variables
The ANSI Minimal BASIC Standard limits variable names in the following
ways:

String variables and string arrays can be named with only one
alphabetic character, followed by a dollar sign. For example, valid
identifiers for string variables are K$, T$, and Q$(17).
Numeric arrays can be named with only one alphabetic character,

followed by the subscript reference. For example, valid identifiers for

numeric arrays are M(25), K(n), and A(n/2).

Simple numeric variables can be named with a maximum of two
characters: one alphabetic character, followed by an optional digit. For
example, valid identifiers for simple numeric variables are R5, K1,
and T2.

With the /ANSI_STANDARD qualifier in effect, VAX BASIC allows up to

31-character variable and array names. Names ending in a percent sign (%)
are invalid, as are any explicitly declared variables.

Note that VAX BASIC initializes all numeric variables
to zero and all string
variables to the null string. To conform to the minimal standard, you should
explicitly initialize all variables in your program.

ANSI! Minimal BASIC

B-3

All VAX BASIC keywords remain reserved words when the
/ANSI_STANDARD qualifier is in effect; you cannot use these reserved
words as variable names. See Appendix D in this manual for a list of
reserved keywords.

Numeric Constants

B.3.5

The ANSI Minimal BASIC Standard allows numeric constants of the
following form:

sd...d

Implicit point representation

sd...drd...d

Explicit point unscaled representation

sd...drd...dEsd...d

Explicit point scaled representation

sd...dEsd...d

implicit point scaled representation

Is a decimal digit.
r

Is a period.
S

Is an optional sign.
E

Is the explicit character E.

In addition to constants of this form, VAX BASIC with the
/ANSI_STANDARD qualifier in effect allows integer constants that end
in a percent sign (%) and explicitly typed numeric constants.

B.3.6

Data Input

VAX BASIC provides several extensions to the ANSI Minimal BASIC
Standard for data input.

B—4

ANSI Minimal BASIC

B.3.6.1

Unquoted String Data

The ANSI Minimal BASIC Standard limits unquoted strings occurrin
DATA statement, or in response to the input prompt, to the following

g in a

of ASCII characters:
*

Uppercase letters (A-Z)

Digits (0-9)

The period (.)

The plus sign (+)

The minus sign (-)

The space character

subset

In VAX BASIC, an unquoted string in a DATA statement can
contain any
ASCII character, with the following exceptions:
®

The comma (,)

The null character

®*

The form feed character

An ampersand (&), if it is the last character on the line

As input to the INPUT statement, VAX BASIC allows unquoted
to contain any printable ASCII character (that is, all characte

strings

rs with an

ASCII code greater than 31, except character code 127, the delete
VAX BASIC also allows the following nonprinting characters in
statement:

B.3.6.2

The back space character

®*

The horizontal tab

The vertical tab

The form feed character

character).
the INPUT

Null Input
The ANSI Minimal BASIC Standard requires that the DATA statemen
consist of numeric constants, string constants, or unquoted strings.

VAX

BASIC allows these items, and also allows null items (that is, two successiv

commas not within a quoted string) as input in a DATA statement

. A

null item in a DATA statement results in the assignment of either a

string or a numeric value of zero to the corresponding variable in the

statement.

null
READ

ANSI Minimal BASIC

B-5

User-Defined Functions (the DEF Statement)

B.3.7

The ANSI Minimal BASIC Standard requires that user-defined functions
accept a single parameter. The formal parameter in the DEF function
must be an unsubscripted numeric variable. With the /ANSI_STANDARD
qualifier in effect, VAX BASIC reports a syntax error for DEF functions that
specify more than one parameter.

The ANSI Minimal BASIC Standard makes no mention of DEFs with string
parameters. VAX BASIC in ANSI Standard mode allows string DEFs but
signals the informational error “String DEF not ANSL.”

DEF functions can be recursive. However, VAX BASIC does not detect
infinitely recursive DEF functions. If your program invokes an infinitely
recursive DEF function, your program will eventually terminate with a fatal
error (typically, an access violation).

B.3.8

Built-In Functions
The ANSI Minimal BASIC Standard allows only the following
implementation-supplied (built-in) functions:
*

ABS

ATN

COS

EXP

INT

LOG
e

RND

SGN

SIN

SQR

TAN

With the /ANSI_STANDARD qualifier in effect, if you use any built-in
functions other than these, VAX BASIC reports an informational error
“Language feature not ANSI.”

B-6

ANSI Minimal BASIC

Further, VAX BASIC reports an error if you use any of the following
functions in a program compiled with the /ANSI_STANDARD qualifier:

B.3.9

DECIMAL

INTEGER

REAL

GETRFA

Arrays
The ANSI Minimal BASIC Standard requires that array declarations are
valid only for numerics, and allows only one or two dimensions. With the
/ANSI_STANDARD qualifier in effect, VAX BASIC allows multi-dimensional
arrays of all data types, including strings.
All arrays have a lower bound of zero unless an OPTION BASE statement
specifies a lower bound of 1. The format of OPTION BASE is as follows:

OPTION BASE n
n

Is either zero or 1. A value of zero specifies that the lower bound of arrays
is either (0) or (0,0). A value of 1 specifies that the lower bound is either

(1)or(1,1).

Although you can have arrays of any floating-point data type, you control
this feature with qualifiers to the DCL command BASIC or the SET

command. This means that all floating-point arrays in a single program are
of the same data type.

The ANSI Minimal BASIC Standard requires that all variables and arrays
have unique names. However, VAX BASIC allows a variable and an array to
have the same name.

B.4

Implementation-Defined Features
The ANSI Minimal BASIC Standard leaves the following features
to be defined by the implementation. The behavior of these

implementation-defined features in VAX BASIC is as described in the

following sections.

ANSI Minimal BASIC

B-7

B.4.1

Initial Values for Variables
The ANSI Minimal BASIC Standard recommends that all variables are
“detectably undefined in the sense that an exception will result from any
attempt to access the value of a variable before that variable is explicitly
assigned a value.” Therefore you should explicitly initialize all variables.
VAX BASIC initializes all numeric variables to zero and all dynamic string
variables to the null string.

B.4.2

Retention of Long Strings
The ANSI Minimal BASIC Standard states that string variables must be
able to contain strings of at least 18 characters. VAX BASIC lets you use
strings of up to 65535 characters.

B.4.3

Accuracy of Evaluation of Numeric Expressions
The ANSI Minimal BASIC Standard does not specify a minimum accuracy,
but recommends at least six significant decimal digits of precision. In VAX
BASIC, the accuracy of numeric expressions is always the same as that of
the operands. This is specified with the /REAL_SIZE qualifier.

B.4.4

Machine Infinitesimal
The ANSI Minimal BASIC Standard recommends that machine infinitesimal
be at most 1E-38. For programs compiled with /REAL_SIZE of SINGLE
or DOUBLE, machine infinitesimal is approximately 2.9E-39; with
/REAL_SIZE=GFLOAT, machine infinitesimal is approximately 5.6E-308;
and with /REAL_SIZE=HFLOAT, machine infinitesimal is approximately
8.4E—-4933.

B.4.5

Machine Infinity
The ANSI Minimal BASIC Standard recommends that machine
infinity be at least 1E38. For programs compiled with /REAL_SIZE of

SINGLE or DOUBLE, machine infinity is approximately 1.7E38; with
/REAL_SIZE=GFLOAT, machine infinity is approximately 9.0E309; and with
/REAL_SIZE=HFLOAT, machine infinity is approximately 8.4K4933.

B-8

ANSI Minimal BASIC

B.4.6

Precision For Numeric Values
The ANSI Minimal BASIC Standard recommends at least six significant

decimal digits of precision. This corresponds to the SINGLE argument of
the VAX BASIC REAL_SIZE qualifier. You can also specify DOUBLE or
GFLOAT (up to 15 significant decimal digits of accuracy), or HFLOAT (up to
33 significant decimal digits of accuracy). See the VAX BASIC User Manual

for more information.

Note that the accuracy of numeric expressions is always the same as the
precision specified with an argument to the REAL_SIZE qualifier.

B.4.7

Exrad-Width For Printing Numeric Representations
The ANSI Minimal BASIC Standard requires at least two positions for the

representation of the exrad component of a numeric representation. In VAX

BASIC for programs compiled with /REAL_SIZE of SINGLE or DOUBLE,

exrad-width is two. For programs compiled with /REAL_SIZE=GFLOAT,
exrad-width is three. For programs compiled with /REAL_SIZE=HFLOAT,

exrad-width is four.

B.4.8

Significance-Width For Printing Numeric Representations
The ANSI Minimal BASIC Standard specifies at least six positions for

controlling the number of significant decimal digits printed in numeric

representations. In VAX BASIC the PRINT statement provides up to six

significant positions for numeric values, regardless of the floating-point data

type in effect.

B.4.9

Print Zone Length
VAX BASIC always has five 14-position print zones per print line.

B.4.10

Margin for Output Line
The ANSI Minimal BASIC Standard makes no recommendation for the
width of the output line. With the /ANSI_STANDARD qualifier in effect, the

margin width for the controlling terminal is 80 characters. Note that the
margin width for the controlling terminal is infinite for programs compiled

with the /NOANSI_STANDARD qualifier.

ANSI Minimal BASIC

B-9

Pseudorandom Number Sequence

B.4.11

In VAX BASIC the RND function produces a pseudorandom sequence of
numbers until the RANDOMIZE statement is executed. After RANDOMIZE
executes, the RND function produces a random sequence of numbers.
B.4.12

Unique Line Numbers

VAX BASIC follows the ANSI Minimal BASIC Standard’s recommendations
for local editing of statement lines. Statement lines can be entered in any
order; VAX BASIC sorts the program into the proper order. If you enter
two lines with the same line number, VAX BASIC keeps the second line and
deletes the first. VAX BASIC deletes any line containing only a line number;
it also deletes any line containing only a line number and formatting
characters (such as spaces or form feeds).

B.4.13

Input Prompt

The ANSI Minimal BASIC Standard recommends that the input prompt
be a question mark followed by a single space. VAX BASIC conforms to

this recommendation. Note that you cannot supply a string constant to be
displayed as an input prompt. If you attempt to supply a string prompt,

VAX BASIC signals “Language feature not ANSI.”

B.4.14

End of Input Reply
In VAX BASIC, the end of input reply is a carriage return.

B.4.15

End of Print Line

In VAX BASIC, the end of print line is a carriage return/line feed
combination (ASCII code 13 and 10).

B.4.16

Exponentiation Operator

VAX BASIC accepts two asterisk characters (**) as the exponentiation
operator.

B-10

ANSI Minimal BASIC

Appendix C

ASCII Character Codes

ASCII is a 7-bit character code with an optional parity bit (8) added for
many devices. Programs normally use seven bits internally with the eighth
bit being zero; the extra bit is either stripped (on input) or added by a
device driver (on output) so the program will operate with either parityor nonparity-generating devices. The eighth bit is reserved for future
standardization.

The International Reference Version (IRV) of ISO Standard 646 is identical
to the IRV in CCITT Recommendation V.3 (International alphabet No. 5).
The character sets are the same as ASCII except that the ASCII dollar sign
(hexadecimal 24) is the international currency sign, which looks like ###.

ISO Standard 646 and CCITT V.3 also specify the structure for national
character sets, of which ASCII is the U.S. national set. Certain specific
characters are reserved for national use. Table C—1 contains the values and
symbols:

Table C—1:

ASCII Characters Reserved for National Use

Hexadecimal Value

IRV

ASCII

###

$ (General currency symbol vs. dollar sign)

[

(continued on next page)

ASCIl Character Codes

C-1

Table C-1 (Cont.):

ASCII Characters Reserved for National Use

Hexadeciinal Value

IRV

ASCII

(tbs)

~ (Overline vs. tilde)

5D
53 D)

60
7B
7C

7D
7E

ISO Standard 646 and CCITT Recommendation V.3 (International
Alphabet No. 5) are identical to ASCII except that the number sign (23)
is represented as ## instead of #, and certain characters are reserved for
national use.

Table C-2:

ASCII Codes
8-Bit

Decimal

Hexadecimal

Code

Character

Remarks
Null (tape feed)

NUL

SOH

Start of heading ("A)

STX

Start of text (end of address, ~B)

ETX

End of text (*C)

EOT

End of transmission (shuts off the

TWX machine AD)
5

ENQ

Enquiry (WRU, ~E)

ACK

Acknowledge (RU, AF)

BEL

Bell (*G)

Backspace (*H)

Horizontal tabulation (*I)

Line feed (AJ)

Vertical tabulation (~K)

(continued on next page)

C—2

ASCII Character Codes

Table C-2 (Cont.):

ASCII Codes

8-Bit
Decimal

Hexadecimal

Code

Character

Form feed (page, ~L)

Carriage return

Shift out (AN)

Shift in (20)

Remarks

("M )

DLE

Data link escape (AP)

DC1

Device control 1 (*Q)

DC2

Device control 2 (*R)

DC3

Device control 3 (AS)

DC4

Device control 4 (AT)

NAK

Negative acknowledge (ERR, AU)

SYN

Synchronous idle (AV)

ETB

End-of-transmission block

Cancel (*X)

CAN

End of medium (*Y)

SUB

Substitute (~Z)

(A"W)

ESC

Escape (prefix of escape sequence)

File separator

Group separator

Record separator

Unit separator

Space

Exclamation point

Double quotation mark

Number sign

Dollar sign

Percent sign

Ampersand

(continued on next page)

ASCIl Character Codes

C-3

Table C-2 (Cont.):

ASCIl Codes

Decimal

8-Bit
Hexadecimal

Code

Character

Remarks

’

Apostrophe

(

Left (open) parenthesis

)

Right (close) parenthesis

Asterisk

Plus sign

Comma

—

Minus sign, hyphen

Period (decimal point)

Slash (slant)

Zero

One

Two

Three

Four

Five

Six

Seven

Eight

Nine

;

Semicolon

Less than (left angle bracket)

Equal sign

Greater than (right angle bracket)

Question mark

Commercial at

Uppercase A

Colon

(continued on next page)

C-4

ASCII Character Codes

Table C-2 (Cont.):

ASCII Codes

8-Bit

Decimal

Hexadecimal

Code

Character

Remarks

Uppercase B

Uppercase C

Uppercase D

Uppercase E

Uppercase F

Uppercase G

Uppercase H
Uppercase I

Uppercase J

Uppercase K

Uppercase L

Uppercase M

Uppercase N

Uppercase O

Uppercase P

Uppercase Q

Uppercase R

Uppercase S

Uppercase T

Uppercase U

Uppercase V

Uppercase W

Uppercase X

Uppercase Y

Uppercase Z

[

Left square bracket

Backslash (reverse slant)

(continued on next page)

ASCIl Character Codes

C-5

Table C-2 (Cont.):

ASCII Codes

8-Bit

Decimal

Hexadecimal

Code

Character

Remarks

93
94
95

5D
S5E
5F

]
A
_

Right square bracket
Circumflex (caret)
Underscore (underline)

)

Grave accent

. a

Lowercase a

Lowercase b
Lowercase ¢

101

102

103

Lowercase d
Lowercase e
Lowercase f
Lowercase g

104
105
106
107
108

68
69
6A
6B
6C

h
i
j
k
1

Lowercase h
Lowercase 1
Lowercase j
Lowercase k
Lowercase 1

109

Lowercase m

110

Lowercase n

111

Lowercase o

112

Lowercase p

113

Lowercase q

114

Lowercase r

115

Lowercase s

116

Lowercase t

117

Lowercase u

Code

(continued on next page)

C—6

ASCIl Character Codes

Table C-2 (Cont.):

ASCII Codes

8-Bit

Decimal

Hexadecimal

Code

Character

Remarks

118

Lowercase v

119

Lowercase w

120

.¢

Lowercase x

121

Lowercase y

122

Lowercase z

123

{

Left brace

124

125

}

Right brace

126

Tilde

127

DEL

Delete (rubout)

Vertical line

ASCIl Character Codes

C-~7

Appendix

VAX BASIC Keywords

The following is a list of the VAX BASIC keywords. Most of the keywords
are reserved. The unreserved keywords are marked with a dagger.
%ABORT
%CDD

%CROSS
%ELSE
%END
%FROM
%IDENT
%IF
%INCLUDE
%LET
%LIBRARY
%LIST
%NOCROSS
%NOLIST
%PAGE
%PRINT
%SBTTL
%THEN
%TITLE
%VARIANT
ABORT
ABS
ABS%

ACCESS
ACCESS%
ACTIVATE

1 Unreserved keyword.

VAX BASIC Keywords

D-1

ACTIVE
ALIGNED

ALLOW
ALTERNATE

AND

ANGLE
ANY
APPEND

AREA
AS
ASC
ASCENDING
ASCII
ASK

AT ¥
ATN

ATN2
BACK

BASE
BASIC

BEL
BINARY
BIT

BLOCK

BLOCKSIZE
BS

BUCKETSIZE
BUFFER

BUFSIZ
BY

BYTE

CALL

CASE
CAUSE
CCPOS
CHAIN
CHANGE
CHANGES
CHECKING
CHOICE ¢

CHR$
CLEAR
t Unreserved keyword.

D-2

VAX BASIC Keywords

CLIP ¥

CLK$
CLOSE
CLUSTERSIZE
COLOR ¥

COM

COMMON

COMP%
CON
CONNECT
CONSTANT
CONTIGUOUS

CONTINUE

COS
COT
COUNT
CR
CTRLC
CVTF$
CVTS$F

CVT$$

CVT$%
CVT%$
DAT

DAT$
DATA

DATE$
DEACTIVATE
DECIMAL
DECLARE

DEF
DEFAULTNAME

DEL

DELETE

DESC
DESCENDING

DET
DEVICE

DIF$
DIM

DIMENSION

DOUBLE
T Unreserved keyword.

VAX BASIC Keywords

D-3

DOUBLEBUF
DRAW

DUPLICATES
DYNAMIC
ECHO

EDIT$
ELSE
END

EQ
EQV
ERL

ERN$
ERR
ERROR

ERT$
ESC

EXIT
EXP

EXPAND

EXPLICIT
EXTEND
EXTENDSIZE
EXTERNAL
FF
FIELD
FILE
FILESIZE
FILL

FILLS$
FILL%
FIND

FIX
FIXED
FLUSH

FNAME$
FNEND

FNEXIT

FONT ¥
FOR

FORMATS$
FORTRAN
FREE
T Unreserved keyword.

D-4

VAX BASIC Keywords

FROM

FSP$
FSS$
FUNCTION

FUNCTIONEND
FUNCTIONEXIT
GE
GET

GETRFA
GFLOAT
GO
GOBACK
GOSUB
GOTO

GRAPH
GRAPHICS ¥
GROUP

GT
HANDLE
HANDLER
HEIGHT 7
HFLOAT
HT
IDN
IF

IFEND
IFMORE

IMAGE
IMP
IN ¥

INACTIVE
INDEX ¥
INDEXED

INFORMATIONAL
INITIAL

INKEY$
INPUT

INSTR
INT
INTEGER
INV
INVALID
Tt Unreserved keyword.

VAX BASIC Keywords

D-5

ITERATE

JSB
JUSTIFY
KEY

KILL
LBOUND

LEFT
LEFT$

LEN
LET

LINE
LINES ¥
LINO

LINPUT
LIST

LOC
LOCKED

LOG

LOG10

LONG
LSET

MAG

MAGTAPE
MAP

MAR
MAR%

MARGIN
MAT

MAX
METAFILE t

MID

MID$
MIN

MIX ¥

MOD
MOD%
MODE
MODIFY

MOVE
MULTIPOINT ¥

NAME
T Unreserved keyword.

D-6

VAX BASIC Keywords

NEXT
NO

NOCHANGES
NODATA

NODUPLICATES
NOECHO
NOEXTEND
NOMARGIN

NONE

NOPAGE
NOREWIND
NOSPAN

NOT

NUL$
NUM

NUM$

NUM1$
NUM?2
NX
NXEQ
OF
ON
ONECHR
ONERROR

OPEN
OPTION
OPTIONAL

OR
ORGANIZATION
OTHERWISE
OUTPUT

OVERFLOW
PAGE
PATH +
PEEK

PICTURE
PLACES$

PLOT
POINT +

POINTS ¥

POS
T Unreserved keyword.

VAX BASIC Keywords

D-7

POS%
PPS%

PRIMARY
PRINT

PRIORITY

PROD$
PROGRAM
PROMPT
PUT

QUO$

RADS$

RANDOM
RANDOMIZE
RANGE ¥
RCTRLC
RCTRLO
READ
REAL
RECORD
RECORDSIZE
RECORDTYPE
RECOUNT
REF

REGARDLESS
RELATIVE
REM
REMAP
RESET

RESTORE
RESUME
RETRY
RETURN
RFA
RIGHT

RIGHT$
RMSSTATUS
RND

ROTATE
ROUNDING
RSET
SCALE
SCRATCH
+ Unreserved keyword.

D-8

VAX BASIC Keywords

SEG$
SELECT
SEQUENTIAL
SET
SETUP

SEVERE

SGN
SHEAR
SHIFT
SI
SIN
SINGLE
SIZE
SLEEP
SO
SP
SPACE

SPACE$
SPAN

SPEC%
SQR
SQRT
STATUS
STEP
STOP

STR$
STREAM

STRING

STRING$
STYLE

SUB

SUBEND
SUBEXIT
SUBSCRIPT

SUM$
SWAP%
SYS
TAB
TAN

TEMPORARY

TERMINAL
TEXT +
1 Unreserved keyword.

VAX BASIC Keywords

D-9

THEN
TIM

TIME

TIME$
TO
TRAN 7

TRANSFORM
TRANSFORMATION +

TRMS$
TRN

TYP
TYPE

TYPE$
UBOUND
UNALIGNED
UNDEFINED

UNIT +
UNLESS

UNLOCK
UNTIL

UPDATE

USAGES$
USEROPEN
USING
USR$
VAL

VAL%
VALUE
VARIABLE

VARIANT
VFC
VIEWPORT
VIRTUAL
VPS%

VT
WAIT
WARNING

WHEN
WHILE
WINDOW

WINDOWSIZE

WITH
T Unreserved keyword.

D-10

VAX BASIC Keywords

WORD
WRITE
XLATE

XLATE$
XOR
ZER

VAX BASIC Keywords

D-11

Index

Array (Cont.)

A
%ABORT directive, 3-2
ABS% function, 4-4
ABS function, 4-2
Absolute value

ABS% function, 44
ABS function, 4-2
MAG function, 4-197

creating with MAT statement, 4-212, 4-217,
4-220, 4-223, 4-226
data type of, 4-76
dimensions of, 4-76
dynamic, 4~76, 4-78, 4-79
elements, 4-77

element zero, 4-78, 4-215, 4-218, 4-221, 4-224,
4-227, 4-240

ACCESS clause, 4-272, 4-311
ACTIVE clause, 4-287

initialization of, 4-214

ALLOW clause, 4273

inversion of, 4-215

Alphanumeric label, 1-3

initializing, 4-80

redimensioning with MAT statement, 4-213, 4-215,
4-218, 4-221, 4-227