1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
|
Bywater BASIC Interpreter, version 3.20
---------------------------------------------
Copyright (c) 1993, Ted A. Campbell
for bwBASIC version 2.10, 11 October 1993
Copyright (c) 2014-2015, Howatd Wulf, AF5NE
for bwBASIC version 3.00, 12 May 2015
Copyright (c) 2015-2016, Howatd Wulf, AF5NE
for bwBASIC version 3.10, 27 July 2016
Copyright (c) 2016-2017, Howatd Wulf, AF5NE
for bwBASIC version 3.20, 4 June 2017
CONTENTS:
1. DESCRIPTION
2. TERMS OF USE
3. QUICK REFERENCE LIST OF COMMANDS, FUNCTIONS AND OPERATORS
4. GENERAL NOTES ON USAGE
5. PREDEFINED VARIABLES
6. UNIMPLEMENTED COMMANDS AND FUNCTIONS
and AGENDA FOR DEVELOPMENT
7. THE STORY OF Bywater BASIC
8. COMMUNICATIONS
9. EXPANDED REFERENCE FOR COMMANDS, FUNCTIONS AND OPERATORS
The author wishes to express his thanks to Mr. David MacKenzie,
who assisted in the development Unix installation and configuration
for this version.
1. DESCRIPTION
The Bywater BASIC Interpreter (bwBASIC) implements a large superset
of the ANSI Standard for Minimal BASIC (X3.60-1978) and a significant
subset of the ANSI Standard for Full BASIC (X3.113-1987), and many
classic BASIC dialects in C.
bwBASIC can be configured to enable commands, functions, operators
and punctuation characters available in many classic dialects of BASIC;
these are controlled by various OPTION commands. bwBASIC does not attempt
bug-level compatibility with any particular BASIC dialect nor does it
currently support graphics. bwBASIC seeks to be as portable as possible.
The interpreter is fairly slow. Whenever faced with a choice
between conceptual clarity and speed, I have consistently chosen the
former. The interpreter is the simplest design available, and
utilizes no system of intermediate code, which could speed up
considerably its operation. As it is, each line has only one
command. Multi-statement lines are internally broken into distinct
lines as they are loaded.
2. TERMS OF USE:
This version of Bywater BASIC is released under the terms of the
GNU General Public License (GPL), which is distributed with this
software in the file "COPYING". The GPL specifies the terms under
which users may copy and use the software in this distribution.
A separate license is available for commercial distribution,
for information on which you should contact the author.
3. QUICK REFERENCE LIST OF COMMANDS, FUNCTIONS AND OPERATORS
The complete list of over 500 commands, functions and operators is
in the file "ALL.txt" in the DOCS directory. Documentation for each
BASIC dialect is in the other text files in the DOCS directory.
A BASIC dialect is a selection of commands, functions, operators,
punctuation characters and other behaviors. The OPTION VERSION
command is used to choose a specific BASIC dialect. Additional
OPTION commands are available to fine-tune the behavior.
In bwBASIC, any function can be executed as a command. For example,
the function "OUT(X, Y)" can be executed as the command "OUT X, Y".
You can overload functions by parameter signature (the number
and types of parameters), and user defined functions can replace
any instrinsic function, including INP, OUT, PEEK, POKE, and WAIT.
4. GENERAL NOTES ON USAGE:
4.a. Interactive Environment
An interactive environment is provided if the flag INTERACTIVE
is defined as TRUE in bwBASIC.h, so that a line with a
line number can be entered at the bwBASIC prompt and it will be
added to the program in memory.
Line numbers are not strictly required, but are useful if the
interactive enviroment is used for programming. For longer
program entry one might prefer to use an ASCII text editor, and
in this case lines can be entered without numbers. See also the
documentation below for the pseudo-command EDIT, in section 5.
4.b. Naming Conventions
Command, function, label, and variable names are not case sensitive,
so that "Run" and "RUN" and "run" are equivalent.
The characters allowed in variable names depends upon the specific
BASIC dialect selected with the OPTION VERSION command. Usually,
variable names can use any alphabetic characters, the period
and underscore characters and decimal digits (but not in the
first position) and they can be terminated with the various numeric
type characters (!,@,#,%,&,~) or the string type character ($).
4.c. Numerical Constants
Numerical constants may begin with a digit 0-9 (decimal), with
the "&H" or "&h" (hexadecimal) or the "&o" or "&O" (octal).
Numerical constants may include 'E' or 'e' followed by an
exponent number to denote exponential notation. Numerical
constants may also be terminated by the various numeric type
characters (!,@,#,%,&,~).
4.d. Command-Line Execution
A filename can be specified on the command line and will be
loaded and executed immediately, so that the command line
bwBASIC prog.bas
will load and execute "prog.bas". If a program is executed
from the command line, control is returned to the operating
system when the program terminates.
4.e. Program Storage
All programs are stored as ASCII text files.
4.f. TRUE and FALSE
TRUE is defined as -1 and FALSE is defined as 0 in the default
distribution of bwBASIC. Alhtough these definitions can be changed
by those compiling bwBASIC (see file bwBASIC.h), any other values
are not supported.
4.g. Assignments
Assignment must be made to variables. This differs from some
implementations of BASIC where assignment can be made to a
function. Implication: "INSTR( 3, x$, y$ ) = z$" will not
work under bwBASIC. The command "MID$(X$,...) = ..." is
implemented and should be used instead.
Some BASIC dialects allow the multiple variable assignments,
such as:
100 LET A = B = C = 0
In bwBASIC, only the first '=' is considered an assignment.
All other '=' are considered comparison operators. To resolve
this issue, use commas to seperate the variables, such as:
100 LET A, B, C = 0
If these statements are only used to initialize the variable
values, then they may not needed in bwBASIC, since all numeric
variables are initialized to zero (0) and all string variables
are initialized to the empty string ("").
4.h. Operators and Precedence
The available operators are determined by the OPTION VERSION
setting. bwBASIC recognizes many operators, with their level of
precedence fixed. The precedence levels chosen for the various
operators in bwBASIC were selected to be compatible with many
dialects of BASIC. If your application requires a specific order
of evaluation, then use parentheses.
The collating sequence (ASCII, EBCDIC, and so on) is determined
by the C compiler. As a consequenece, the results of string
comparisons may vary. A simple check for collating sequence is
shown in the following example:
100 REM Purpose: Verify collating sequence (sort order)
110 REM Author: Howard Wulf, AF5NE
120 REM Date: 2015-11-28
130 REM
200 IF "1" < "A" THEN 300
210 PRINT "EBCDIC"
220 GOTO 999
300 PRINT "ASCII"
999 END
4.i. Numerical Precision (NOT)
bwBASIC utilizes numbers with only one level of precision.
All numbers are internally represented using a C double.
The various numeric type suffix characters (!,@,#,%,&,~),
just like the string type suffix character ($), are part
of the variable name.
This version also supports type declarations, such as:
100 DIM X AS INTEGER
110 FUNCTION ABC( X AS INTEGER ) AS INTEGER
120 LET ABC = X * 2
130 END FUNCTION
For each type character there is an equivalent type declaration.
Type Equivalent
Char declaration
==== ===========
$ STRING
# DOUBLE
! SINGLE
@ CURRENCY
& LONG
% INTEGER
~ BYTE
However, combining both a type suffix character and a type
declaration in the same statement is not supported.
100 DIM A$ AS INTEGER ' this is not supported
The type of a variable is used to range-check the values.
This allows many programs to run correctly, but does not
handle all possible cases. The current implementation is not
complete for all possible uses of numeric type declarations.
In the current version, the type of numeric values is used
to select the appropriate operation. As a consequence,
integer division is used when dividing two integer values.
The MOD and \ operators use the rounded integer values of
their parameters and return a rounded integer result.
Within an expression, the result of an operation is promoted
to the greater of:
the type of the left parameter,
the type of the right parameter, and
the type required to hold the result.
In bwBASIC, numeric constants are DOUBLE by default. If you
wish to coerce a numeric constant, then add the appropriate
numeric type character immediately after the numeric digits.
Many BASIC dialects that allow numeric constants to have a
numeric type character adopt this convention.
4.j. OPTION VERSION and so on
OPTION commands change how a BASIC program is parsed. All OPTION commands
should be in "profile.bas" so they are effective when a BASIC program
is loaded. The first OPTION command should be OPTION VERSION to select a
specific BASIC dialect. Additional OPTION commands fine-tune the available
commands, functions, operators, punctuation characters and so on to support
programs written in many different BASIC dialects. All other OPTION commands
must follow the OPTION VERSION command. Conflicting and pathological OPTION
combinations are not supported.
The OPTION VERSION command selects a specific BASIC dialect.
OPTION VERSION "BYWATER" ' Bywater BASIC 3
OPTION VERSION "BYWATER-2" ' Bywater BASIC 2
OPTION VERSION "CALL/360" ' SBC CALL/360 Mainframe BASIC
OPTION VERSION "CBASIC-II" ' CBASIC-II for CP/M
OPTION VERSION "DARTMOUTH" ' Dartmouth DTSS BASIC
OPTION VERSION "ECMA-55" ' ANSI Minimal BASIC
OPTION VERSION "ECMA-116" ' ANSI Full BASIC
OPTION VERSION "GCOS" ' GE 600 Mainframe BASIC
OPTION VERSION "HAARDT" ' bas 2.4 by Michael Haardt
OPTION VERSION "HANDBOOK1" ' The BASIC Handbook, 1st Edition
OPTION VERSION "HANDBOOK2" ' The BASIC Handbook, 2nd Edition
OPTION VERSION "HEATH" ' Heath Benton Harbor BASIC
OPTION VERSION "MARK-I" ' GE 265 Mainframe BASIC
OPTION VERSION "MARK-II" ' GE 435 Mainframe BASIC
OPTION VERSION "MBASIC" ' Microsoft BASIC-80 for Xenix
OPTION VERSION "PDP-8" ' DEC PDP-8 BASIC
OPTION VERSION "PDP-11" ' DEC PDP-11 BASIC
OPTION VERSION "RBASIC" ' Micronics RBASIC for 6809 FLEX
OPTION VERSION "RSTS-11" ' DEC RSTS-11 BASIC-PLUS
OPTION VERSION "SYSTEM/360" ' IBM System/360 Mainframe BASIC
OPTION VERSION "SYSTEM/370" ' IBM System/370 Mainframe BASIC
OPTION VERSION "TRS-80" ' TRS-80 Model I/III/4 LBASIC
OPTION VERSION "VINTAGE" ' Vintage BASIC 1.0.1
OPTION VERSION "XBASIC" ' TSC XBASIC for 6800 FLEX
For example, MOD is a function in OPTION VERSION "ECMA-116",
MOD is an operator in OPTION VERSION "MBASIC", and
MOD is a valid variable name in OPTION VERSION "CALL/360".
The OPTION VERSION command also sets the following OPTION commands:
OPTION STRICT ON | OFF
OPTION ANGLE DEGREES | RADIANS | GRADIANS
OPTION BUGS ON | OFF
OPTION LABELS ON | OFF
OPTION COMPARE BINARY | DATABASE | TEXT
OPTION BASE integer
OPTION RECLEN integer
OPTION COVERAGE ON | OFF
OPTION TRACE ON | OFF
OPTION ERROR GOTO | GOSUB
OPTION DATE "format"
OPTION TIME "format"
OPTION PUNCT COMMENT "char"
OPTION PUNCT STATEMENT "char"
OPTION PUNCT PRINT "char"
OPTION PUNCT IMAGE "char"
OPTION PUNCT INPUT "char"
OPTION USING DIGIT "char"
OPTION USING COMMA "char"
OPTION USING PERIOD "char"
OPTION USING PLUS "char"
OPTION USING MINUS "char"
OPTION USING EXRAD "char"
OPTION USING DOLLAR "char"
OPTION USING FILLER "char"
OPTION USING LITERAL "char"
OPTION USING FIRST "char"
OPTION USING ALL "char"
OPTION USING LENGTH "char"
OPTION PUNCT QUOTE "char"
OPTION PUNCT STRING "char"
OPTION PUNCT DOUBLE "char"
OPTION PUNCT SINGLE "char"
OPTION PUNCT CURRENCY "char"
OPTION PUNCT LONG "char"
OPTION PUNCT INTEGER "char"
OPTION PUNCT BYTE "char"
OPTION PUNCT LPAREN "char"
OPTION PUNCT RPAREN "char"
OPTION PUNCT FILENUM "char"
OPTION PUNCT AT "char"
The commands, functions, operators and settings for each BASIC dialect
is documented in the text files in the DOCS directory.
OPTION DISABLE COMMAND
Disable a specific command.
OPTION DISABLE FUNCTION
Disable a specific function.
OPTION DISABLE OPERATOR
Disable a specific operator.
OPTION ENABLE COMMAND
Enable a specific command.
OPTION ENABLE FUNCTION
Enable a specific function.
OPTION ENABLE OPERATOR
Enable a specific operator.
OPTION ERROR GOSUB
The program will GOSUB to the error handler.
The error handler exits with the RETURN command.
OPTION ERROR GOTO
The program will GOTO to the error handler.
The error handler exits with the RESUME command.
OPTION LABELS OFF
Disables textual labels.
OPTION LABELS ON
Enables textual labels.
Regardless of the OPTION LABELS setting, statements of the form
IF x THEN label
are not allowed, instead use the form
IF x THEN GOTO label
The reason for this rule is because
IF x THEN y
is considered to be the same as
IF x THEN
y
END IF
where "y" is a command, function, or subroutine. Many BASIC dialects
that allow textual labels adopt this convention.
OPTION ROUND controls how floating point values are converted to
whole number values. OPTION ROUNG MATH rounds toward the nearest
whole number, with halves rounding up to the next larger whole number,
as commonly expected by many scientific applications. OPTION ROUND
BANK rounds halves to the even whole numbers, as commonly expected
by many financial applications. OPTION ROUND TRUNCATE truncates to
the next smaller whole number, as commonly expected by many
applications written for an integer BASIC. The selected rounding
method is used whenever a whole number is required, including:
a) selection value for ON ... GOTO and ON ... GOSUB
b) any function parameter requiring a whole number
c) array subscripts and dimensions
d) string positions and lengths
e) CINT() and similar
The OPTION ROUND command does not change the results of INT() or FIX().
The default rounding method is OPTION ROUND BANK.
A comparison of the different OPTION ROUND settings upon the results of CINT()
BANK MATH TRUNCATE
X int(X) fix(X) cint(X) cint(X) cint(X)
-2.0 -2 -2 -2 -2 -2
-1.6 -2 -1 -2 -2 -1
-1.5 -2 -1 -2 -2 -1
-1.4 -2 -1 -1 -1 -1
-1.0 -1 -1 -1 -1 -1
-0.6 -1 0 -1 -1 0
-0.5 -1 0 0 -1 0
-0.4 -1 0 0 0 0
0.0 0 0 0 0 0
0.4 0 0 0 0 0
0.5 0 0 0 1 0
0.6 0 0 1 1 0
1.0 1 1 1 1 1
1.4 1 1 1 1 1
1.5 1 1 2 2 1
1.6 1 1 2 2 1
2.0 2 2 2 2 2
The OPTION BUGS command determines the behavior of a number of BASIC keywords.
BASIC programs which rely on these behaviors are non-portable and non-standard.
I have considered several different names for this command, but have not yet
thought of a better short name.
OPTION BUGS ON disables the ANSI/ECMA/ISO standard behavior:
FOR ... ' values are evaluated left-to-right
GOTO X OF ... ' an invalid value for X falls thru without ERROR
GOSUB X OF ... ' an invalid value for X falls thru without ERROR
ON X GOTO ... ' an invalid value for X falls thru without ERROR
ON X GOSUB ... ' an invalid value for X falls thru without ERROR
X = VAL("X") ' returns zero without ERROR
INPUT X ' empty string returns zero without ERROR
INPUT X$ ' empty string returns "" without ERROR
INPUT X$ ' allows unquoted character strings
variable names ' period and underscore are allowed
variable types ' the type characters #!@&% are allowed
PRINT "a" X ' string concatenation is implied
1.2% is 1 ' the type characters #!@&% are allowed
1D1 is ERROR ' 'D' is not allowed as exponent seperator
OPTION BUGS OFF enables the ANSI/ECMA/ISO standard behavior:
FOR ... ' values are evaluated according to standard
GOTO X OF ... ' an invalid value for X is an ERROR
GOSUB X OF ... ' an invalid value for X is an ERROR
ON X GOTO ... ' an invalid value for X is an ERROR
ON X GOSUB ... ' an invalid value for X is an ERROR
X = VAL("X") ' raises an illegal function call (ERROR 5)
INPUT X ' empty string retries input
INPUT X$ ' empty string retries input
INPUT X$ ' unquoted character strings retries input
variable names ' period and underscore are not allowed
variable types ' the type characters #!@&% are not allowed
PRINT "a";X ' string concatenation is not implied
1.2% is ERROR ' the type characters #!@&% are not allowed
1D1 is ERROR ' 'D' is not allowed as exponent seperator
4.k. ERROR handling
bwBASIC implements a simplified error handling strategy.
Errors are seperated into two categories:
a) Fatal errors. These errors include:
- Unknown command
- FOR without NEXT
- NEXT without FOR
- WHILE without WEND
- WEND without WHILE
- and so on.
The program is scanned prior to running and if any of these errors is
detected, then the program is not allowed to run. If these errors
occur as the result of a DELETE or MERGE in a running program, then the
program is terminated.
b) Non-fatal errors. If an error handler exists, then it is executed,
otherwise the default behaivor is performed. The correct action to
take in an error handler depends upon the specific application.
- Overflow (ERROR 6)
- the default behavior is to display a warning message.
- Division by zero (ERROR 11)
- the default behavior is to display a warning message.
- String too long (ERROR 15)
- the default behavior is to display a warning message.
- All other non-fatal errors
- the default behavior is to terminate the program.
bwBASIC 2.61 used ON ERROR GOSUB for error trapping.
This version defaults to ON ERROR GOTO instead.
4.l. Implementation rules for functions and commands
In many BASIC dialects, keywords are seperated into three distinct groups:
Commands, Statements, and Functions. In bwBASIC, keywords are seperated
into only two groups: Commands and Functions. A keyword documented as a
Command or Statament in a specific BASIC dialect may have been implemented
in bwBASIC as a Function. This is merely an implementation decision, which
may change in the future. Each keyword should only be used as described in
the reference document. The following rules are considered when deciding
whether a BASIC keyword is implemented as a command or a function:
a) If the keyword requires significant parsing,
then it is implemented as a command. An example is "PRINT".
b) If the keyword requires access to variables BYREF,
then it is implemented as a command. An example is "SWAP".
c) If the keyword changes the flow of control,
then it is implemented as a command. An example is "GOTO".
d) A function may be used as though it were a command,
but a command cannot be used as though it were a function.
e) The BASIC program can redefine a function,
but the BASIC program cannot redefine a command.
f) The BASIC program can overload a function,
but the BASIC program cannot overload a command.
g) Other than semantics, there is no practical difference
between a BASIC function and a BASIC subroutine. The
return value of a BASIC subroutine, when called as a
function, is zero. Calling a BASIC function as if it
were a subroutine simply discards the return value.
These rules were chosen to maintain compatibility with
many BASIC dialects.
An example of the results of the above rules is "OUT".
Since "OUT" is implemented as a function, you may:
a) call it as a subroutine like this:
100 OUT X, Y
b) call it as a function like this:
100 LET N = OUT( X, Y ) ' N = 0
c) redefine it as a subroutine like this:
SUB OUT( X, Y )
REM ...
END SUB
d) redefine it as a function like this:
FUNCTION OUT( X, Y )
REM ...
END FUNCTION
e) overload it using subroutines like these:
SUB OUT( X, Y )
REM ...
END SUB
SUB OUT( X, A$ )
REM ...
END SUB
SUB OUT( A$, X )
REM ...
END SUB
SUB OUT( A$, B$ )
REM ...
END SUB
f) overload it using functions like these:
FUNCTION OUT( X, Y )
REM ...
END FUNCTION
FUNCTION OUT( X, A$ )
REM ...
END FUNCTION
FUNCTION OUT( A$, X )
REM ...
END FUNCTION
FUNCTION OUT( A$, B$ )
REM ...
END FUNCTION
4.m. Reference documentation
bwBASIC is preconfigured to support a number of specific BASIC dialects which were
implemented using the following references, however bwBASIC does not attempt to be
bug-level compatible and does not implement non-portable design choices. A manual
for each dialect is in the DOCS directory to make you aware that a specific keyword
is implemented, however you should refer to the reference document for a proper
understanding of how to use each keyword. There are many other good books which
describe these BASIC dialects in detail.
OPTION VERSION "BYWATER" ' Bywater BASIC 3
MANUAL:
BYWATER.TXT
OPTION VERSION "BYWATER-2" ' Bywater BASIC 2
MANUAL:
BYWATER-2.TXT
NOT IMPLEMENTED:
DO NUM, DO UNNUM
NOTES:
SUB MAIN is not automatically called.
CALL requires parentheses around the function/subroutine parameters,
so instead of
CALL abc 1, 2, 3
use
CALL abc( 1, 2, 3 )
OPTION VERSION "CALL/360" ' SBC CALL/360 Mainframe BASIC
MANUAL:
CALL-360.TXT
NOT IMPLEMENTED:
MAT PRINT USING.
NOTES:
The APPENDIXES are implementation specific and are not supported.
OPTION VERSION "CBASIC-II" ' CBASIC-II for CP/M
MANUAL:
CBASIC-II.TXT
ADDITIONAL INFORMATION:
"CBASIC Language Reference Manual, 2nd Edition"
by Diigital Research
(c) 1982, Diigital Research
http://bitsavers.trailing-edge.com/pdf/digitalResearch/cb80/
CBASIC_Language_Reference_Manual_Oct82.pdf
NOT IMPLEMENTED:
CONSTAT%, CONCHAR% and compiler directives.
NOTES:
The APPENDIXES are implementation specific and are not supported.
The %INCLUDE directive is implemented, but only supports literal
unquoted filesnames without drive or directory, such as:
%INCLUDE LIBRARY.BAS
Note that the %INCLUDE directive is executed as a file is being loaded,
and as a result the %INCLUDE does not appear in the resulting listing.
Machine language functions and commands are not supported.
The parsing of command line parameters is implementation defined.
The specification of an array in a COMMON statement is the same as
the specification in a DIM statement.
The SIZE() function assumes 1024 bytes and does not support wild-cards;
if the file does not exist then SIZE() returns zero, otherwise SIZE()
returns the number of 1024 bytes blocks required to contain the file;
an existing file of zero bytes returns a value of 1.
OPTION VERSION "DARTMOUTH" ' Dartmouth DTSS BASIC
MANUAL:
DARTMOUTH.TXT
NOTES:
The APPENDICES are implementation specific and are not supported.
Sections 4.2 and 4.3 are implementation specific and are not supported.
Lines containing data to be READ must have a line number and a DATA command.
NOT IMPLEMENTED:
Card punch codes are not supported, use a comma or semicolon instead.
OPTION VERSION "ECMA-55" ' ANSI Minimal BASIC
MANUAL:
ECMA-55.TXT
NOTES:
The APPENDICES are implementation specific and are not supported.
DIM is an executed statement in bwBASIC.
This is a design decision to support the following example.
100 INPUT "How many?"; N
110 DIM A$(N)
OPTION VERSION "ECMA-116" ' ANSI Full BASIC
MANUAL:
ECMA-116.TXT
NOT IMPLEMENTED:
Graphic commands, chapters 11 thru 15.
NOTES:
The APPENDICES are implementation specific and are not supported.
WORK-IN-PROGRESS.
OPTION VERSION "GCOS" ' GE 600 Mainframe BASIC
MANUAL:
GCOS.TXT
NOT IMPLEMENTED:
HPS, LIN, RESTORE*, RESTORE$, VPS and binary files.
NOTES:
The APPENDIXES are implementation specific and are not supported.
Local variables in a multiline DEF are declared using DIM.
Line numbers are not written to, nor read from, data files.
FILES does not support passwords.
Literal values for file names are not supported, use string values instead.
This is a design decision to support the following:
100 INPUT "Which files?"; A$, B$, C$
110 FILES A$, B$, C$
OPTION VERSION "HAARDT" ' bas 2.4 by Michael Haardt
MANUAL:
HAARDT.TXT
NOT IMPLEMENTED:
BBC syntax, use ANSI syntax instead.
ON ERROR statement(s) is not supported, use ON ERROR GOTO instead.
ON ERROR OFF, use ON ERROR GOTO 0 instead.
MAT REDIM, OPTION RUN, OPTION STOP, TRUNCATE, UNNUM and XREF.
DEC$(X,A$), ENVIRON$(X), FIND$(A$[,X]) and INSTR(A$,B$,X,Y).
NOTES:
POS and TAB are 1-based instead of 0-based.
ON ERROR GOTO 0 does not cause any error to occur, instead
ON ERROR GOTO 0 removes the current error handler and clears
ERL, ERR and ERROR$.
OPTION VERSION "HANDBOOK1" ' The BASIC Handbook, 1st Edition
MANUAL:
HANDBOOK1.TXT
NOT IMPLEMENTED:
Abbreviated commands (such as A.) and graphic commands.
NOTES:
The APPENDICES are implementation specific and are not supported.
The ERR function returns different values.
OPTION VERSION "HANDBOOK2" ' The BASIC Handbook, 2nd Edition
MANUAL:
HANDBOOK2.TXT
NOT IMPLEMENTED:
Abbreviated commands (such as A.) and graphic commands.
NOTES:
The APPENDICES are implementation specific and are not supported.
The ERR function returns different values.
OPTION VERSION "HEATH" ' Heath Benton Harbor BASIC
NOT IMPLEMENTED:
FREEZE, UNFREEZE, LOCK, UNLOCK, STEP
NOTES:
The APPENDICES are implementation specific and are not supported.
PRINT #-1 is sent to the printer.
INPUT #-1 is an ERROR.
OPTION VERSION "MARK-I" ' GE 265 Mainframe BASIC
MANUAL:
MARK-I.TXT
ADDITIONAL REFERENCE:
"Time-Sharing Service BASIC LANGUAGE EXTENSIONS Reference Manual"
by Time-Sharing Service, Information Service Department, General Electric
(c) 1968, General Electric Company and Trustees of Dartmouth College
http://www.bitsavers.org/pdf/ge/MarkI_Timesharing/
802207A_Time-SharingServiceBASICLanguageExtensionsReferenceManual_Feb1968.pdf
NOTES:
The APPENDIXES are implementation specific and are not supported.
NOT IMPLEMENTED:
A series of variables seperated by equal signs is not supported,
use a series of variables seperated by commas instead.
Literal values for file names are not supported, use string values instead.
This is a design decision to support the following:
100 INPUT "Which files?"; A$, B$, C$
110 FILES A$, B$, C$
CALL, to execute another compiled program, is not supported, use SHELL instead.
OPTION VERSION "MARK-II" ' GE 435 Mainframe BASIC
MANUAL:
MARK-II.TXT
ADDITIONAL INFORMATION:
"Basic Software Library" (Volumes 1 to 8)
by R. W. Brown
(c) 1977, Scientific Research Inst.
NOT IMPLEMENTED:
HPS, LIN, RESTORE*, RESTORE$, VPS and binary files.
NOTES:
The APPENDIXES are implementation specific and are not supported.
Local variables in a multiline DEF are declared using DIM.
Line numbers are not written to, nor read from, data files.
Literal values for file names are not supported, use string values instead.
This is a design decision to support the following:
100 INPUT "Which files?"; A$, B$, C$
110 FILES A$, B$, C$
FILES does not support passwords.
OPTION VERSION "MBASIC" ' Microsoft BASIC-80 for Xenix
MANUAL:
MBASIC.TXT
NOTES:
The APPENDICES are implementation specific and are not supported.
The ERR function returns different values.
Specifying "D" in the exponent is not supported, instead use "E".
OPTION VERSION "PDP-8" ' DEC PDP-8 BASIC
MANUAL:
PDP-8.TXT
NOT IMPLEMENTED:
NO RUBOUTS, RUBOUTS
NOTES:
The APPENDICES are implementation specific and are not supported.
OPTION VERSION "PDP-11" ' DEC PDP-11 BASIC
MANUAL:
PDP-11.TXT
NOTES:
The APPENDICES are implementation specific and are not supported.
OPTION VERSION "RBASIC" ' Micronics RBASIC for 6809 FLEX
MANUAL:
RBASIC.TXT
NOT IMPLEMENTED:
"+" command, COMPILE, CVT$, CVTF$, CVT$%, CVT$F
NOTES:
The APPENDICES are implementation specific and are not supported.
The ERR function returns different values.
OPTION VERSION "RSTS-11" ' DEC RSTS-11 BASIC-PLUS
MANUAL:
RSTS-11.TXT
ADDITIONAL INFORMATION:
"BASIC-PLUS Language Manual : for use with RSTS-11 (PDP-11 Resource Time-Sharing System)"
by Digital Equipment Corporation
(c) 1972, Digital Equipment Corporation
http://bitsavers.trailing-edge.com/pdf/dec/pdp11/rsts/V04/
DEC-11-ORBPA-A-D_BASIC-PLUS_LangMan_Oct72.pdf
ADDITIONAL INFORMATION:
"PDP-11 : BASIC-PLUS Language Manual"
by Digital Equipment Corporation
(c) 1975, Digital Equipment Corporation
http://bitsavers.trailing-edge.com/pdf/dec/pdp11/rsts/V06/
DEC-11-ORBPB-A-D_BASIC-PLUS_LangMan_Jul75.pdf
NOT IMPLEMENTED:
HELLO, RENAME, REPLACE, COMPILE, LENGTH, TAPE, KEY, ASSIGN, DEASSIGN.
FOR ... WHILE, FOR ... UNTIL, statement modifiers.
NOTES:
The APPENDIXES are implementation specific and are not supported.
The ERR function returns different values.
The statemnet NAME ... AS does not support the <protection> specifier.
OPTION VERSION "SYSTEM/360" ' IBM System/360 Mainframe BASIC
MANUAL:
SYSTEM-360.TXT
ADDITIONAL INFORMATION:
"IBM System/360 0S(TS0) ITF:BASIC Terminal User's Guide"
by International Business Machines Corporation
(c) 1971, International Business Machines Corporation
http://bitsavers.org/pdf/ibm/360/os/tso/
SC28-6840-0_TSO_ITF_BASIC_Terminal_UG_Apr71.pdf
NOT IMPLEMENTED:
MAT PRINT USING.
NOTES:
The APPENDIXES are implementation specific and are not supported.
OPTION VERSION "SYSTEM/370" ' IBM System/370 Mainframe BASIC
MANUAL:
SYSTEM-370.TXT
NOT IMPLEMENTED:
MAT PRINT USING.
NOTES:
The APPENDIXES are implementation specific and are not supported.
OPTION VERSION "TRS-80" ' TRS-80 Model I/III/4 LBASIC
MANUAL:
TRS-80.TXT
NOT IMPLEMENTED:
CMD, SET EOF, cassette I/O.
NOTES:
The APPENDICES are implementation specific and are not supported.
The ERR function returns different values.
For the TRS-80 Model I use "WIDTH 16,64" in "profile.bas".
For the TRS-80 Model III use "WIDTH 16,64" in "profile.bas".
For the TRS-80 Model 4 use "WIDTH 24,80" in "profile.bas".
bwBASIC requires a space around all keywords, so the LINEINPUT
command must be written as LINE INPUT, and so on.
PRINT #-1 is sent to the printer.
INPUT #-1 is an ERROR.
OPTION VERSION "VINTAGE" ' Vintage BASIC 1.0.1
MANUAL:
VINTAGE.TXT
NOTES:
The APPENDICES are implementation specific and are not supported.
OPTION VERSION "XBASIC" ' TSC XBASIC for 6800 FLEX
MANUAL:
XBASIC.TXT
NOT IMPLEMENTED:
"+" command, COMPILE, CVT$, CVTF$, CVT$%, CVT$F
NOTES:
The APPENDICES are implementation specific and are not supported.
The ERR function returns different values.
5. PREDEFINED VARIABLES - no longer exist
BWB.EDITOR$
BWB.FILES$
BWB.PROMPT$
BWB.IMPLEMENTATION$
These preset variables no longer exist in bwBASIC. They have
been replaced with OPTION EDIT, OPTION FILES and OPTION PROMPT
commands.
The commands EDIT and FILES are pseudo-commands that launch
shell programs set by OPTION EDIT and OPTION FILES commands,
respectively. The default values for these commands can
be changed in bwBASIC.h (DEF_EDITOR and DEF_FILES), and they
can be changed on the fly by the user. It is expected that
the user will add the appropriate commands to "profile.bas"
for their specific implementation; OPTION FILES "ls -l" on Unix
systems and OPTION FILES "dir" on DOS systems.
The command OPTION PROMPT can be used to set the prompt
string for bwBASIC. Again, it is suggested that a user-
selected prompt can be set up in a "profile.bas" to be
initialized each time bwBASIC starts. Note that special
characters can be added to the prompt string, e.g.,
OPTION PROMPT "Ok"+CHR$(10)
will give an "Ok" prompt followed by a linefeed.
In previous versions, the preset variable BWB.IMPLEMENTATION$
would return "TTY" (IMP_IDSTRING) for the bwx_tty implementation.
In previous versions of bwBASIC, the existance of the keywords CLS,
COLOR and LOCATE were determined at compile and BWB.IMPLEMENTATION$
was used at runtime to determine whether these keywords existed.
In the current version, these keywords always exist and are now
controlled at runtime using the OPTION TERMINAL commands. With
OPTION TERMINAL NONE these keywords output nothing.
6. UNIMPLEMENTED COMMANDS AND FUNCTIONS, and AGENDA FOR DEVELOPMENT
There are some items not implemented that have been so long
a part of some BASIC dialects that their absence may seem surprising.
In each case, though, their implementation would require
operating-system-specific functions or terminal-specific functions
that cannot be universally provided. Some specific examples are
detailed below.
INP reads a value from a hardware port. In the current version,
using INP() will generate ERROR 73. It is expected that you will
provide a suitable implementation for your specific application.
For example:
FUNCTION INP( X )
REM Return whatever value your application requires
INP = 0
END FUNCTION
OUT writes a value to a hardware port. In the current version,
using OUT() will generate ERROR 73. It is expected that you will
provide a suitable implementation for your specific application.
For example:
SUB OUT( X, Y )
REM do whatever your application requires
END SUB
PEEK reads a value from a memory location. In the current version,
using PEEK() will generate ERROR 73. It is expected that you will
provide a suitable implementation for your specific application.
For example:
FUNCTION PEEK( X )
REM Return whatever value your application requires
PEEK = 0
END FUNCTION
POKE writes a value to a memory location. In the current version,
using POKE() will generate ERROR 73. It is expected that you will
provide a suitable implementation for your specific application.
For example:
SUB POKE( X, Y )
REM do whatever your application requires
END SUB
WAIT reads a value from a hardware port. In the current version,
using WAIT() will generate ERROR 73. It is expected that you will
provide a suitable implementation for your specific application.
For example:
SUB WAIT( X, Y )
REM do whatever your application requires
END SUB
SUB WAIT( X, Y, Z )
REM do whatever your application requires
END SUB
USR executes a machine code routine. In the current version,
using USR() will generate ERROR 73. It is expected that you will
provide a suitable implementation for your specific application.
For example:
FUNCTION USR( ... )
REM Return whatever value your application requires
USR = 0
END FUNCTION
VARPTR reads a value from a memory location. In the current version,
using VARPTR() will generate ERROR 73. It is expected that you will
provide a suitable implementation for your specific application.
For example:
FUNCTION VARPTR( ... )
REM Return whatever value your application requires
VARPTR = 0
END FUNCTION
There are other commands, functions, and implementation details
that I am working on, and which are on the agenda list for future
versions of bwBASIC. These agenda include:
PARACT i.e., the ability to execute PARallel ACTions. This
is described in ANSI BASIC, although I have not seen it
implemented before. It will offer a rough, non-preemptive
form of multitasking within the scope of a BASIC program.
Programmers will note that the global My pointer provides
one possible hook mechanism for PARACT in bwBASIC. In the
interim, you might use the "ON TIMER" command to implement
a simple multitasking BASIC program.
XMEM PC-type computers usually are able to use extended
memory. If we could use extended memory for program
lines, variables, and function defitions, we could
write much longer programs. This would entail,
however, a fairly serious rewriting of the program
to utilize memory handles for these storage features
instead of direct memory pointers. In the interim,
you might use a "DOS Extender" which hooks calloc()
and free() to enable transparent access to EMS or XMS
memory.
Windows The addition of memory handles in addition to the
non-preemptive execution of program lines (in a
crude form, already present) will make it possible
to develop implementations for Windows and perhaps
for other graphical user interfaces. But what form
should this take? I have in mind presently a BASIC
that would run in the background, appearing only
as an icon in the GUI space, with pop-up editors
and output windows. Thus, the interpreted language
would serve a purpose something like 'cron' (a task
scheduler) under Unix systems. You may have some
reflections that would help me in this.
Graphics Here we face fairly critical differences in different
styles and implementations of graphics, e.g., between
GWBASIC, ANSI BASIC, VisualBASIC, etc. But it's
possible that Graphics commands and functions could
be added. These would all be OPTION VERSION specific.
In the interim, you might consider using ReGIS or Tektronix
graphics (ESC codes) with xterm.
The ANSI Standard for full BASIC does not specify which particular
commands or functions must be implemented, and in fact the standard
is very robust. Perhaps no implementation of BASIC would ever
include all of the items, but some ANSI commands and functions which
remain unimplemented are:
ACCESS
AREA
ARRAY
ASK
BSTR
BVAL
CELLS
CLIP
COLLATE
CONNECT
DATUM
DEBUG
DECLARE
DEVICE
DISCONNECT
DISPLAY
DOT
DRAW
ERASE
EVENT
EXCEPTION
GRAPH
HANDLER
IMAGE
KEY
LINES
MIX
MULTIPOINT
OUTIN
OUTPUT
PARACT
PICTURE
PIXEL
PLOT
POINTS
RECEIVE
RENUMBER
REWRITE
ROTATE
SEIZE
SEND
SHIFT
TIMEOUT
TRACE
TRANSFORM
VIEWPORT
WAIT
VIEWPORT
ZONEWIDTH
7. THE STORY OF Bywater BASIC
This program was originally begun in 1982 by my grandmother, Mrs.
Verda Spell of Beaumont, TX. She was writing the program using
an ANSI C compiler on an Osborne I CP/M computer and although my
grandfather (Lockwood Spell) had bought an IBM PC with 256k of
RAM my grandmother would not use it, paraphrasing George Herbert
to the effect that "He who cannot in 64k program, cannot in 512k."
She had used Microsoft BASIC and although she had nothing against
it she said repeatedly that she didn't understand why Digital
Research didn't "sue the socks off of Microsoft" for version 1.0
of MSDOS and so I reckon that she hoped to undercut Microsoft's
entire market and eventually build a new software empire on
the North End of Beaumont. Her programming efforts were cut
tragically short when she was thrown from a Beaumont to Port
Arthur commuter train in the summer of 1986. I found the source
code to bwBASIC on a single-density Osborne diskette in her knitting
bag and eventually managed to have it all copied over to a PC
diskette. I have revised it slightly prior to this release. You
should know, though, that I myself am an historian, not a programmer.
8. COMMUNICATIONS:
email: tcamp@delphi.com
9. EXPANDED REFERENCE FOR COMMANDS, FUNCTIONS AND OPERATORS
bwBASIC provides a simple "HELP" command to refresh your memory
regarding the appropriate syntax for a specific command or function.
In the DOCS directory are text files which provide brief descriptions
of every intrinsic command, function and operator available in BASIC
dialect available in bwBASIC; these files are not intented to be an
authoritative or exhaustive reference. Refer to the reference document
for each dialect for details regarding each keyword.
THE END
|