Digital PDFs

AA-P102B-TK

May 1983

16 pages

Original

1.1MB

Document:	BASIC-PLUS-2 Documentation Supplement
Order Number:	AA-P102B-TK
Revision:	0
Pages:	16
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/pro3xx/POS/AA-P102B-TK_BASIC-PLUS-2_Documentation_Supplement_198305.pdf

OCR Text

BASIC-PLUS-2
Documentation Supplement
Order No. AA-P1 02B-TK

May 1983

This supplement presents an overview of Professional Tool Kit BASIC-PLUS-2 and
describes the differences between BASIC-PLUS-2 on the Professional Developer's
Tool Kit and BASIC-PLUS-2 on RSX systems. Tool Kit BASIC-PLUS-2 can be used
with the Professional 300 Series Developer's Tool Kit to create application software
for use on the Professional Operating System (P/OS).

OPERATING SYSTEM AND VERSION:

VAXNMS V3.2 or later
RSX-11 M V4.1 or later
RSX-11 M-PLUS V2.1 or later

SOFTWARE VERSION:

Professional Developer's Tool Kit
V1.S
Professional Tool Kit BASIC-PLUS-2
V2.1

DIGITAL EQUIPMENT CORPORATION

Maynard, Massachusetts 01754

1st Printing, December 1982
2nd Printing (Rev), May 1983

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 only
be used or copied in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that
is not supplied by DIGITAL or its affiliated companies.
The specifications and drawings, herein, are the property of Digital Equipment Corporation and shall not be reproduced or copied or used in whole or in part as the
basis for the manufacture or sale of items without written permission.

The following are trademarks of Digital Equipment Corporation:
CTI BUS
DEC
DECmate
DECsystem-10
DECSYSTEM-20
DECUS
DECwriter
DIBOL

...

MASSBUS
PDP
P/OS
PRO/BASIC
PRO/Communications
Professional
PRO/FMS
PRO/RMS
PROSE
PROSE PLUS

Rainbow
RSTS
RSX
Tool Kit
UNIBUS
VAX
VMS
VT
Work Processor

CONTENTS
1.0
2.0
3.0

4.0

Page
RELATED DOCUMENTATION . . . . . . . . . . . . . . . . . . . . . . . 1
PROFESSIONAL TOOL KIT BASIC-PLUS-2 . . . . . . . . . . . . . . . 1
DEVELOPMENT CYCLE . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3.1 Writing the Source Program . . . . . . . . . . . . . . . . . . . . . . 2
3.1.1 Differences and Unsupported Features . . . . . . . . . . . 4
3.2 Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.3 Compiling the Source Program . . . . . . . . . . . . . . . . . . . . 5
3.4 Generating the Command and Descriptor Files . . . . . . . . . . . 6
3.4.1 Rebuilding an Application . . . . . . . . . . . . . . . . . . . 6
3.5 Editing the Command File . . . . . . . . . . . . . . . . . . . . . . . 6
3.6 Editing the Overlay Descriptor File . . . . . . . . . . . . . . . . . . 7
3.7 Building the PIOS Task Images . . . . . . . . . . . . . . . . . . . . 7
3.8 Debugging During Execution . . . . . . . . . . . . . . . . . . . . . 7
TOOL KIT BASIC-PLUS-2 RUN TIME ERROR MESSAGES . . . . . . 7

FIGURE
Tool Kit BASIC-PLUS-2 Development Cycle . . . . . . . . . . . . . . . . 3
TABLES
1
2

Tool Kit BASIC-PLUS-2-ltems of Interest . . . . . . . . . . . . . . . . . 4
Tool Kit BASIC-PLUS-2 Error Messages . . . . . . . . . . . . . . . . . . 8

iii

BASIC-PLUS-2
DOCUMENTATION SUPPLEMENT
1.0

RELATED DOCUMENTATION

This manual supplements the manual BASIC on RSX-11 MIM-PLUS Systems.
Both manuals are included in the documentation set shipped to Tool Kit users
who have ordered BASIC-PLUS-2. Also included in that set are the BASIC Reference Manual and the BASIC User's Guide, and the BASIC Pocket Reference
Guide. See these three documents for additional information on BASIC and
BASIC-PLUS-2 on RSX systems. The Pocket Reference Guide is useful for
quick reference.
For information on the current release of Professional Tool Kit BASIC-PLUS-2,
its installation and known problems, see the Professional Tool Kit BASICPLUS-2lnstallation Guide and Release Notes.

2.0

PROFESSIONAL TOOL KIT BASIC-PlUS-2

BASIC-PLUS-2 is a programming language that uses familiar words and mathematical notations. With Tool Kit BASIC-PLUS-2 you can create applications on
an RSX-11 M/M-PLUS or VAXIVMS host system that run on the Professional
Operating System (P/OS). This manual describes the differences between
BASIC-PLUS-2 on RSX systems and Tool Kit BASIC-PLUS-2.
The material here is intended for programmers experienced with BASICPLUS-2 on RSX systems.

2 TOOL KIT BASIC-PLUS-2 SUPPLEMENT

3.0

DEVELOPMENT CYCLE

The development cycle for Tool Kit BASIC-PLUS-2 applications (Figure 1) consists of the following steps:
1.

Write source program.

Compile source program, creating object module file.

Compile with IDEBUG to debug at run time.

Compile without IDEBUG when program is error-free.

Build command file and overlay descriptor language file. You may need
to edit these files (see Sections 3.5 and 3.6)

Task build to create executable task image file.

Write application installation file; move it and the task to the Professional.

Run task on the Professional. If desired, debug using REDIRECT command and terminal attached to the Professional workstation.

Run Application Diskette Builder when program is error-free, creating
final diskette.

The following sections present specific details of application development in
Tool Kit BASIC-PLUS-2. For a complete description of each stage in Tool Kit
application development, you should refer to the Too! Kit User's Guide. Also
note that, with the Tool Kit, you can create application diskettes that will run on
P/OS Diskette andlor P/OS Hard Disk. There are some important differences in
the application development cycle for these two environments. Refer to the Tool
Kit User's Guide for full details. This document focuses on application development for the P/OS Hard Disk Environment.

3.1

Writing the Source Program

The BASIC-PLUS-2 source program can include external subroutine calls to
access P/OS facilities from your program. The external subroutine calls are
described in the Too! Kit User's Guide and the CORE Graphics Library Manual.
Facilities exist in the following areas:

P/OS user interface support: the Tool Kit BASIC-PLUS-2 application
has access to P/OS menu, help, message, and other system services.
The ability to display error messages, status, on-line Help, and menus
on the screen is provided through the PIOS Service Routines Library.

Extended software functions: the Tool Kit BASIC-PLUS-2 application
can invoke callable system services, such as PROSE (the P/OS text
editor) and the PRO/Communications.

P/OS facilities are accessed through the register 5 (R5) calling sequence with
the BASIC-PLUS-2 CALL BY REF statement.

TOOL KIT BASIC-PLUS-2 SUPPLEMENT 3

HOST SYSTEM
HOST

WORKSTATION

.........._ _ _ _

TERMINAL
Log on to Host - - - - EMULATION MODE

Write
Source Code

I
Compile
Source Program

I
Build and Edit
Command Files

File. MAP
Memory
Allocation
Map

I
-

Task Build
Program
WithPAB

Symbol Tables
Language Ubraries

I
Application
Task Image(s)

I
Application
Files

I
Write Application
Installation File (.INS)

1
File Transfer to

-----------------~~~

Workstation

LOCAL MODE
Professional
FAST INSTALL
(Disk to Disk)

Optional Terminal
Attached for
Debugging

Run Application
Diskette Builder

DISKETIE
Figure 1
Tool Kit BASIC-PLUS-2 Development Cycle

4 TOOL KIT BASIC-PLUS-2 SUPPLEMENT

Table 1
Tool Kit BASIC-PLUS-2-ltems of Interest

Feature

Please Note

Compiler Commands
RUN

Not in the Tool Kit compiler.

LOAD

Not in the Tool Kit compiler.

BUILD

.CMD and .ODL files may need to be edited.

BUILD/DUMP

Unsupported.

BUILD/NOSEOUENTIAL

Unsupported for programs that do not access RMS files.

BUILD/CLUSTER

You can cluster one library in addition to POSRES, RMSRES,
and BP2SML, which are added by default.

SET DUMP

Unsupported.

SET NOSEOUENTIAL

Unsupported for programs that do not access RMS files.

Debugger Commands
REDIRECT

Allows debugging during application execution from a terminal
attached to the Professional. Does not accept terminal device
number.

Error Messages

A subset of error messages for BASIC-PLUS-2 on RSX. You
must press RESUME to continue after receiving error message.

Immediate Mode

Not in Tool Kit compiler.

Magnetic Tape Operations

Unsupported.

RMS Support

Must not be removed from task image.

Statements
CHAIN

Accepts installed task name, same as name in application
installation file (not file specification).

FSS$ Function

Unsupported for named directories.

EDIT$

Do not use any odd integer as argument to EDIT$ if the string
to be operated on is an 8-bit character: high-order bit will be
cleared.

Time Format

Twelve-hour AM/PM format unsupported.

CTRLlC Trapping

Enabling CTRLlC trapping causes the terminal to be attached.
Some of the callable P/OS routines can not be called if the terminal is attached (see the Tool Kit User's Guide).

DECnet file access (DAP)

Unsupported.

3.1.1 Differences and Unsupported Features-Table 1 summarizes features that will influence your source code. Some operate differently than on
RSX systems, others are unsupported. Do not use the unsupported features listed here when you write an application using Tool Kit BASIC-PLUS-2.
For more information on editing the command and overlay descriptor files, see
Sections 3.5 and 3.6 of this supplement. For a complete list of Tool Kit BASICPLUS-2 error messages, see Section 4.

TOOL KIT BASIC-PLUS-2 SUPPLEMENT 5

3.2

Character Sets

Tool Kit BASIC-PLUS-2 supports the DEC Multinational Character Set in string
literals, comments, and DATA statements when you compile the application,
and as input or output when you run the application on the Professional. (See
the Terminal Subsystem Manual for a description of the DEC Multinational
Character Set.)
The compiler does not allow European alphabetics in variable names.
Do not use any odd integer as the argument to EDIT$ if the string to be operated
on is an a-bit character: the high-order bit will be cleared.

3.3

Compiling the Source Program

When you install Tool Kit BASIC-PLUS-2 on your host system, you select the
Extended Instruction Set (EIS) compiler, the Floating Point Unit (FPU) compiler,
or both, as part of the installation process. Your choice should reflect the environment in which your applications will run. Floating Point hardware is optional
on the Professional. Your host development system does not require an FPU to
run the Tool Kit FPU compiler. Build your programs with the FPU compiler only if
your applications will run on Professionals which have the Floating Point option.

To invoke the EIS compiler on RSX-11 M/11 M-PLUS, type:
>RUN $PBE

To invoke the FPU compiler, type:
>RUN $PBF

To invoke the EIS compiler on VAXNMS, use the command:
$ RUN SYS$SYSTEM:PBE

To invoke the FPU compiler, use the command:
$ RUN SYS$SYSTEM:PBF

Compile your source program using the BASIC-PLUS-2 COMPILE command.
The compiler will check each line of the source program for errors, returning an
appropriate message if an error is found. You can then correct the program as
necessary and recompile it. Program compilation produces an object module
file (file.OBJ) that can be task built on the host system.
BASIC-PLUS-2 has its own debugger. To use the debugger with your application, compile your source program using the IDEBUG qualifier. When you
execute the application on the Professional, you can issue commands to the
debugger to control and monitor application execution.

6 TOOL KIT BASIC-PLUS-2 SUPPLEMENT

3.4

Generating the Command and Descriptor Files

After compiling the program, use the BASIC-PLUS-2 BUILD command to generate a command file (file.CMO) and overlay descriptor file (file.OOL) for your
application. The Professional Application Builder (PAB) uses these files to
define how libraries are referenced, and to specify special-purpose buffers, logical unit numbers (LUNs), and event flags (EFNs).
You may need to edit the command file and/or the overlay descriptor file before
you task build. The following sections describe the conditions under which you
might want to edit these files.
3.4.1 Rebuilding an Application-If you are rebuilding an application to use
the FPU OTS, having first built it for the EIS OTS, you must change all occurrences of PBE to PBF in the command and overlay descriptor files generated by
the EIS compiler. You must also add the /FP switch to the task image output file
specification in the command file.
3.5

Editing the Command File

A command file generated by the Tool Kit BASIC-PLUS-2 EIS compiler for an
application named "TEST1" would look like this (comments have been added
to describe the entries).
SY,TEST1/CP=SY:TEST/MP
TASK=tasf(-nafl1e
UNITS = 18
ASG = TI:13:15
ASG = SY:5:6:7:8:9:10:11:12
E)-(TTSK = 952
CLSTR = PBESML.RMSRES,POSRES:RO
DEFINE BUFFER SIZES
E)-(TSCT
E)-(TSCT

DM$BUF:4540
FL$BUF:4310

E)-(TSCT
E)-(TSCT
E)-(TSCT

HL$BUF:3410
MM$BUF:1000
MN$BUF:4540

GBLDEF
GBLDEF
GBLDEF
GBLDEF
GBLDEF
GBLDEF

HL$LUN:21
MN$LUN:20
MS$LUN:16
TT$EFN:l
TT$LUN:15
WC$LUN:22

dynamic sin!le choice menu
file selectionlspecification
for ODFIL and NEWFIL routine
help text/f~enu
multi-screen menu
static single choice menu
DEFINE LUN ASSIGNMENTS
help frame file
fl1enu

frarne

file

messa!e frame file
terminal 1/0 event flag
terfTlinal liD
directory searches for oLDFIL and NEWFIL
routine or callable print services

TOOL KIT BASIC-PLUS-2 SUPPLEMENT 7

The values shown for the extend section lines (EXTSCT) are default values.
They are calculated for the largest possible frame of each type. That is, if every
field on a menu, help, and message frame were filled in with the maximum
amount of data, the respective buffers should be allocated tile sizes shown. To
optimize buffer allocation you may want to reduce these values based on your
application's needs.

3.6

Editing the Overlay Descriptor File

The Tool Kit BASIC-PLUS-2 EIS compiler would produce this overlay descriptor
file for the Tool Kit application TEST1 :
.ROOT

BASIC2-RMSROT-USER,RMSALL

USER:

.FCTR

SY:TEST1-LIBR

LIBR:

.FCTR

LB: [1,5 J PBEOTS/LB

@LB:El,5JPBEICl
@LB:[l,5JRMSRLX

.END

If you want to reference any Tool Kit object libraries facilities, such as FMS-11,
you should edit the .ODL file. The PROIEMS-11 Documentation Supplement
provides an example of the editing required to include FMS-11. In the general
case, see BASIC on RSX-11 MIM-PLUS Systems for information on editing
BASIC-PLUS-2 .ODL files.

3.7

Building the P/OS Task Images

Use the Professional Application Builder (PAB) to create an application task
image (file.TSK). See the Tool Kit User's Guide for complete information on
Professional Application Builder commands.

3.8

Debugging During Execution

Use the BASIC-PLUS-2 debugger to debug the program. (See your BASiC documentation for more information on the BASIC-PLUS-2 debugger.) In addition,
when you execute a task on the Professional, you can also connect a terminal to
the printer port on the Professional for debugging. (See the Tool Kit User's
Guide for details.) Use the Tool Kit BASIC-PLUS-2 REDIRECT command to
display debugger 1/0 and issue debugger commands on that terminal. Input is
accepted from and output goes to the printer port. Note that the REDIRECT
command does not accept a terminal device number. All other 1/0, including
graphics or forms, will remain unaffected.

4.0

TOOL KIT BASIC-PLUS-2 RUN-TIME ERROR MESSAGES

Tool Kit BASIC-PLUS-2 run-time error messages are a subset of BASICPLUS-2 run-time error messages on RSX systems. The Tool Kit BASIC-PLUS-2
run-time error messages are preceded by a number to help you report the error.
If you use ERT$ to reference an error not in the Tool Kit BASIC-PLUS-2 subset,
ERT$ will return the following message:
Can't

access

LB:[l ,2JBASIC2.ERR

can't

find

frame

<id>

TOOL KIT BASIC-PLUS-2 SUPPLEMENT

Frame <id> will identify the error number of the ERT$ you tried to reference.
If the debugger is not present, the following notice will appear on the screen
after the error message is displayed:
Please write

down

the above message --

press RESUME to

You must press the RESUME key to clear the screen and continue.
Note: Error 135 is issued if indexed I/O is attempted on a P/OS Diskette application (as opposed to P/OS Hard Disk)
Table 2
Tool Kit BASIC-PLUS-2 Error Messages
Number

Text

?Bad directory for device
2

?IIlegal file name

?Account or device in use

?No room for user on device

?Can't find file or account

?Not a valid device

?I/O channel already open

?Device not available

?I/O channel not open

?Protection violation

? End of file on device

?Fatal system I/O failure

?User data error on device

?Device hung or write locked

?Keyboard wait exhausted

?Disk block is interlocked

?Programmable "C trap

?IIlegal byte count for I/O

?Reserved instruction trap

?Memory management violation

?Virtual array not on disk

?Matrix or array too big

?Virtual array not yet open

?llIegalllO Channel

?Line too long

%Floating point error

%Data format error

%Integer error

?IIlegal number

%IIlegal argument in LOG

continue.

TOOL KIT BASIC-PLUS-2 SUPPLEMENT

Table 2 Continued
Tool Kit BASIC-PLUS-2 Error Messages

Number

Text

%Imaginary square roots

?Subscript out of range

?Can't invert matrix

?Out of data

?ON statement out of range

?Not enough data in record

?Integer overflow, FOR loop

%Division by 0

?FIELD overflows buffer

?Not a random access device

?RETURN without GOSUB

?FNEND without function call

?Arguments don't match

?Too many arguments

?Too few arguments

104

?RESUME and no error

105

?Redimensioned array

116

?PRINT-USING format error

126

?Maximum memory exceeded

127

%SCALE factor interlock

130

?Key not changeable

131

?No current record

132

?Record has been deleted

133

?llIegal usage for device

134

?Duplicate key detected

135

?lIlegal usage

136

?lIlegal or illogical access

137

?lllegal key attributes

138

?File is locked

139

?Invalid file options

140

?Index not initialized

141

?llIegal operation

142

?llIegal record on file

143

?Bad record identifier

144

?Invalid key of reference

145

?Key size too large

147

?RECORD number exceeds maximum

148

?Bad RECORDSIZE value on OPEN

TOOL KIT BASIC-PLUS-2 SUPPLEMENT

Table 2 Continued
Tool Kit BASIC-PLUS-2 Error Messages
Number

Text

149

?Not at end of file

150

?No primary key specified

151

?Key field beyond end of record

152

?lIIogical record accessing

153

?Record already exists

154

?Record/bucket locked

155

?Record not found

156

?Size of record invalid

157

?Record on file too big

158

?Primary key out of sequence

159

?Key larger than record

160

?File attributes not matched

161

?Move overflows buffer

162

?Cannot open file

164

?Terminal format file required

166

?Negative fill or string length

167

?lIlegal record format

168

?llIegal ALLOW clause

170

?Index not fully optimized

171

?RRV not fully updated

173

?Invalid RFA field

180

?No support for op in task

183

?REMAP overflows buffer

184

%Unaligned REMAP variable

185

?RECORDSIZE overflows MAP buffer

186

?Improper error handling

227

?String too long

246

?Error trap needs RESUME

247

?lIlegal RESUME to subroutine

248

?llIegal return from subroutine

250

?Not implemented

251

?Recursive subroutine call

252

?FILE ACP failure

253

?Directive error

BASIC-PLUS-2
Documentation Supplement
Order No. AA-P102B-TK
READER'S COMMENTS

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

,§
III

:£

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

(ij

'5
u

III
ttl

a::

Please indicate the type of reader that you most nearly represent.
o Assembly language programmer
Higher-level language programmer
o Occasional programmer (experienced)
User with little programming experience
o Student programmer
o Other (please specify) _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

o
o

Name ________________________ Date ____________
Organization __________________________________
Street ____________________________________
City ________________ State _ _ _ _ _ _ _ Zip Code _ _ _ _ _ __
or
Country

- - - Do Not Tear - Fold Here and Tape - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

~amaDmD

No Postage
Necessary
if Mailed in the
United States

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

Professional 300 Series Publications
DIGITAL EQUIPMENT CORPORATION
146 MAIN STREET
MAYNARD, MASSACHUSETTS 01754

- - - - Do Not Tear - Fold H e r e - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - I

I
I
I
I
I
I

OIl

:;;;:
:;
U