Portfolio BASIC, version 3.0  (c) 1990 BJ Gleason

by BJ Gleason,  The American University


INTRODUCTION

          PBASIC is a simple BASIC interpreter.  It only requires
     33k of disk space and about 49k of memory to run.  PBASIC is
     a batch oriented interpreter.  It will also interact with
     the built-in editor for program development.

          PBASIC was one of the winners in the Compuserve/
     Portfolio Conference Programming Contest, 1990.


A NOTE FROM THE AUTHOR

          A number of considerate users have offered their help. 
     If you have an interesting application that you have
     developed in PBASIC, I will be more than happy to distribute
     your code in future releases.  Please make sure to place
     your name and other information as REMarks in the program. 
     You can include a documentation file as well.  The only
     thing that I ask is that you do not charge for the use of
     your program, as I am not charging for the use of this
     interpreter.  Send me a note, and tell me where the code is
     and I will include it in the package.

          Thanks to all you have helped and are going to help!


DESIGN CONSIDERATION

          When I was laying out the initial design of PBASIC,
     here are some of the topics I took into consideration:

          - Microsoft BASIC compatible.
          - Size of Interpreter (as small as possible).
          - Unique features of the Portfolio.
          - Using the Built-in editor for Program Editing.
          - Reasonable size BASIC programs.


NEW FEATURES FOR VERSION 3.0

     STRINGS!!!! and arrays of strings.
     Two Dimensional Arrays.
     Added many Sample Programs.
     New Functions : ASC, DATE$, INSTR, INKEY$, VAL, LEFT$, MID$,
          RIGHT$, CHR$, HEX$, OCT$, SPACE$, STR$, STRING$, TIME$,
          PBVER
INTERFACING WITH THE EDITOR

          Instead of trying to create an editor, PBASIC makes
     full use of the built in editor.

          If you run BASIC without any parameters, it will load
     the last file you used in the editor.  To speed up the
     process, you might want to rename PBASIC.EXE to P.EXE, so
     you only need to type P<RETURN> at the prompt.  You can also
     specify a file to execute on the command line.

          Whenever an error is detected, an error message is
     displayed, along with the line number.  Press any key and
     PBASIC will invoke the built-in editor and point to the
     error position.  This will only happen if the file you are
     executing is the same as the one you are editing.  On other
     systems, you will be returned to the DOS prompt.

          ALTR.COM is a small TSR program that will, only from
     inside the editor, save the current file and invoke PBASIC. 
     PBASIC.EXE should be rename P.EXE for the <ALT-R> command to
     work.  ALTR takes up about 450 bytes.  It can be removed by
     rebooting the machine.  It can only be loaded into memory
     once.  The <ALT-R> command will only work inside the editor.

          When the program is finished, PBASIC will wait for a
     keypress and then return you to the editor.


RUNNING PBASIC

          There are two forms to execute PBASIC:

               PBASIC [-T]

               PBASIC filename.ext [-T]

          In the first form, the default file is the last one
     edited in the built-in editor on the Portfolio.  The second
     form loads and executes the specified file.  If you leave
     off the extension, the default ".BAS" is added.

          If you have run the ALTR program before editing your
     code, you can execute PBASIC by pressing <ALT-R>.

          The command line switch -T will turn on the trace
     feature.  This is the same as putting TRON at the beginning
     of you program.


GENERAL

     Source code is standard ASCII format.

     Source code can be in upper or lower case.

     200 floating point variables.  Variable names can not exceed
     8 characters in length.

     FOR/NEXT loops may be nested 10 deep.

     GOSUBs may be nested 10 deep.

     Line numbers are not required for each statement.  Only 100
     line numbers are allowed.  They do not have to be in
     sequence.  Line numbers can range from 0 to 99999.

     Multiple statements per line (:) is supported.


DEVELOPING PROGRAMS WITH GWBASIC

          You can develop your programs on the PC with Microsoft
     BASIC or QuickBASIC.  If using Microsoft BASIC, be sure to
     save the file in ASCII format [ SAVE "myfile",A ] so that it
     can be read by PBASIC.  

     Do NOT attempt to use the Portfolio statements on the PC.

          Starting with version 2.0, all variables are floating
     point.  The statement DEFINT A-Z  will now generate a syntax
     error in PBASIC, since it has not been implemented yet.  It
     is no longer treated as a remark.


MATH EXPRESSIONS

          Single precision math.  Parentheses supported. 
     Standard operator evaluation.  Hexadecmial and Octal
     constants are supported.

          - negation
          ^ exponent
          * multiply
          / divide
          % remainder (MOD)
          \ integer division
          + addition
          - subtraction
     

NOTES ON CONVENTIONS USED

     An expression (exp) can contain variables, constants.  When
     a dummy exp is indicated, it is suggested that you use a
     constant, i.e. POS(0).

     A variable name (varname) must be used when indicated.

     Unless otherwise noted, all parameters can be constants,
     variables or equations.

     
BASIC STATEMENTS

          I have tried to keep the syntax and semantics for the
     statements as close to Microsoft BASIC as possible.  The
     notes presented indicate exceptions.  There are some
     statements included the are not from Microsoft.  They will
     not run on GWBASIC.


     CLS

               Clears the screen.


     DATA      list of numbers/strings

               Allows for numbers to be stored inline.  Data
               statements MUST have a line number.  Numbers are
               separated by commas.  Data statements may be
               located on any line of the program.  Strings must
               be enclosed in quotes.

                    12 DATA 1,2,3,4,5,6

 
     DEF SEG   = exp

               Assigns a segment address for direct memory
               accessing via PEEK, POKE and CALL.


     DIM       varname(size)[,varname(size)....]

               Creates a one dimensional array of single
               precision floating point variables.  Arrays start
               at 0.  Arrays are not initialized to a value. 
               Arrays must be defined before they are used. 
               Upper arrays bounds are not checked, arrays are
               not allowed to go below 0.


     END

               SYSTEM and END have the same effect.


     FOR       varname = exp TO exp [STEP exp]

               You can not use an array element for varname.


     FORMFEED

               Send a formfeed to the printer.  NOT GWBASIC.


     GOSUB     line number


     GOTO      line number


     IF        exp THEN statement [ ELSE statement ]


     INPUT     ["prompt" (,|;)] varname

               Read an integer from the keyboard.  Only one
               variable is allowed per input.  If a comma (,)
               separates the prompt string and the varname, no
               question mark (?) will be printed.  If a semi-
               colon (;) is used, the question mark will appear. 


     LOCATE    row,col

               Move the cursor to row, col.


     LPRINT    list of expressions

               Send output to printer.  See PRINT.


     NEXT      [varname]

               You can not use an array element for varname.


     ON        exp  GOTO  list of line numbers


     ON        exp  GOSUB list of line numbers


     OUT       port, exp

               Send value to the indicated port.

               
     POKE      addr, exp

               Places value at SEG:addr.  SEG is set via the DEF
               SEG statement.  NOTE: Due to the design of the
               Portfolio, if you poke screen memory (DEF
               SEG=&HB000), the value may not appear.  After you
               poke, you should use the REFRESH statement to
               update the screen.


     PRINT     list of expressions

               List of Expressions can consist of strings,
               variables, constants or expressions, separated by
               the comma (,) or semi-colon (;) or a space ( ).


     PRINTER   

               This is a toggle to start copying all PRINT
               statements to the printer.  Issue it again and it
               will toggle off.  Can be used instead of
               converting all PRINTs to LPRINTs.  Information
               will still be displayed on the screen.  This will
               not wrap the output lines like the screen will. 
               NOT GWBASIC.


     PRTSC

               This invoke the PRINT SCREEN function to copy the
               screen out to the printer.  If you are using a
               laser printer, you might want to use a FORMFEED
               after this to do a page eject.  NOT GWBASIC.


     PSET      (row, col) [, exp]

               Set the pixel at row, col to exp.  The Portfolio,
               regardless of the screen mode, has a maximum
               64x240 for row, col.  Exp can evaluate to 0 or 1.


     RANDOMIZE

               Initialize the random number generator.

     READ      list of variables

               Read the values of the variables from the DATA
               statements.  Variables can be simple or array.


     REM

               Remark.  The rest of the line is ignored.  You can
               also use the quote (') mark as a REM statement.


     RESTORE   [line number]

               Sets the internal data pointer to the specified
               line number.  Line number specified must be a data
               statement.  If no line number is given, the data
               pointer will point back to the first data
               location.


     RETURN


     SCREEN    exp

               Set the screen mode.  There is no testing for
               validity.  Some of the values that work on the
               Portfolio are:

                     4   graphics  320x200
                     5   graphics  320x200
                     6   graphics  640x200
                     7   text      80x25
                     8   graphics  160x200
                    10   graphics  640x200

               These are standard PC modes, but remember that the
               Portfolio Screen is only 240x64.

               If you use the screen function of the portfolio,
               it is highly recommend that you set the screen
               back to mode 7 before you exit.  Many portfolio
               utilities only work in mode 7.

               At present, text will not be displayed properly on
               a graphics screen.


     STOP

               To allow for "breakpoints", STOP will terminate
               the program and display the line number.  It will
               point the built-in editor to the last position
               executed if the editor file is the same as the
               file being executed.


     SWAP      varname, varname


     SYSTEM

               END and SYSTEM have the same effect.


     TROFF

               Disable line tracing.


     TRON

               Enable line tracing.  Will display the line number
               in brackets ([x]).  Using this statement will slow
               down the program execution.  Can be placed
               anywhere in program.


     WAIT

               Unlike the GWBASIC version, this only waits for a
               key press.  It gives no prompt and returns no
               value.


BASIC FUNCTIONS

          I have tried to keep the syntax and semantics for the
     functions as close to Microsoft BASIC as possible.  The
     notes presented indicate exceptions.


     ABS(exp)

               Returns the absolute value of exp.


     ASC(x$)

               Returns the ASCII value of the first character in
               x$.


     ATN(exp)

               Returns the Arc Tangent of exp.


     CHR$(n)

               Returns the ASCII character of the value n.


     COS(exp)

               Returns the Cosine of exp.


     CSRLIN

               Returns the current cursor line.


     DATE$     

               Returns the system date.


     EXP(exp)

               Returns e to the power of exp.


     FIX(exp)

               Returns the integer portion of exp.


     FRE(exp)

               Returns the free amount of memory.  The parameter
               exp is a dummy expression.


     HEX$(n)

               Converts n to a hexidecmial string.


     INKEY$

               If a key is pressed, the character is returned,
               otherwise, the empty string ("") is returned.


     INP(port)

               Returns the byte value from port.


     INSTR(x$,y$)

               Returns the position of y$ in x$.


     INT(exp)

               Returns the integer portion of exp.


     LEFT$(x$,n)

               Returns the leftmost n characters of x$.


     LOG(exp)

               Returns the LOG of exp.


     LPOS(exp)

               Returns the current position of the line printer
               head.  Exp is a dummy expression.


     MID$(x$,n,m)

               Returns a string from x$, starting at position n
               for m characters.


     OCT$(n)

               Converts n to an Octal string.


     PBVER

               Returns the version number of PBASIC.


     PEEK(address)

               Returns the byte from memory location SEG:address. 
               SEG is set via the DEF SEG instruction.

     POINT(row,col)

               Returns the value of the pixel at row,col.  If
               this function does not appear to work, try running
               FIX0D, to fix the ROM pixel read function.


     POS(exp)

               Returns the current cursor column.  Exp is a dummy
               expression.


     RAND(exp)

               This will return a number between 0 and exp-1. 
               NOT GWBASIC.


     RIGHT$(x$,n)

               Returns the rightmost n characters from x$.


     RND

               This will return an number between 0 and 1.


     SGN(exp)

               Returns the sign of exp.

                    -1   exp < 0
                     0   exp = 0
                     1   exp > 0


     SIN(exp)

               Returns the Sine of exp.


     SPACE$(n)

               Returns a string of n spaces.


     SQR(exp)

               Returns the Square Root of exp.

     STR$(n)

               Returns the string representation of n.


     STRING$(n,m)

               Returns a string composed of n characters.  The
               ASCII value of the character is m. 


     TAN(exp)

               Returns the Tangent of exp.


     TIME$

               Returns the system time.


     TIMER

               Returns the number of seconds since midnight.


     VAL(x$)

               Returns the numeric value of x$.


PORTFOLIO ONLY STATEMENTS

          The statements in this section are specific to the
     Atari Portfolio and will not run on a regular PC.  YOU CAN
     LOCK UP YOUR REGULAR PC IF YOU ATTEMPT TO USE THESE.


     ALARM

               This will beep the speaker, about once a second
               until the user presses a key.  The program will
               then continue with the next statement.


     BEEP

               This will cause a single beep from the speaker.


     BOX       row1, col1, row2, col2, type

               This will draw a box.  Row1 and Col1 specify the
               upper left corner position of the box, while Row2
               and Col2 specify the lower right corner.  Type is
               0 for single line box, and 1 for a double line
               box.
 
               Trying to draw a box larger than the screen (8x40)
               has unpredictable results.


     CLICK

               Make the key click sound.


     DIAL      string

               This will dial the "number" through the speaker. 
               Valid characters for tones are: 0 1 2 3 4 5 6 7 8
               9 A B C D * #.  The letters must be in uppercase.


     DISPLAY   exp

               Set the Portfolio screen to Normal, Static or
               Tracked.  0=Static, 1=Normal, 2=Tracked.  The mode
               is only effective while in PBASIC.  Using this
               statement might clear the screen depending on the
               position of the cursor.


     ERRWIN    row, col, "message"

               This will draw a box around the message and
               display it at the specified row, col.  It will
               then beep and wait for a keypress.  The text
               underneath the message is left untouched.

               Trying to place the message outside the screen
               (8x40) has unpredictable results.


     GETDISPLAY

               This function will return the current display
               mode.  See DISPLAY for details.


     OFF

               This will turn the Portfolio off until the user
               presses a key.  The program will continue
               execution with the next statement.


     PORT

               This function will return a 1 if running on a
               Portfolio, a 0 if not.  Handy if you want to run
               program on both machines without locking up the
               PC.  WARNING: There is no positive way to identify
               the Portfolio.  This functions checks to see if
               the Interrupt 61h vector is pointing to 0000:0000. 
               This is not normally used on the PC, but is on the
               Portfolio.  If you are running a TSR that takes
               over this vector, PORT will return 1.


     REFRESH

               Copy video memory to the LCD controller.  Needed
               for when you are doing direct write to screen
               memory.


     ROMVER

               This function will return the version number of
               the Portfolio rom's.


     SOUND     code, duration

               This will activate the tone generator.  Duration
               is the length of tone in 10 msec intervals.  Tone
               codes are displayed below.  These codes are taken
               from the Atari Portfolio Technical Reference
               Manual, copyrighted by the Atari Corporation.

               CODE      NOTE      Frequency (Hz)

               48        D#5       622.3
               49        E5        659.3
               50        F5        698.5
               51        F#5       740.0
               52        G5        784.0
               53        G#5       830.6
               54        A5        880.0
               55        A#5       932.3
               56        B5        987.8
               57        C6        1046.5
               58        C#6       1108.7
               41        D6        1174.7
               59        D#6       1244.5
               60        E6        1318.5
               61        F6        1396.9
               14        F#6       1480.0
               62        G6        1568.0
               44        G#6       1661.2
               63        A6        1760.0
                4        A#6       1864.7
                5        B6        1975.5
               37        C7        2093.0
               47        C#7       2217.5
                6        D7        2349.3
                7        D#7       2489.0

               Aside from these codes, other values will produce
               sounds as well.


     STATUS    exp

               This will enable or disable the Status line.  This
               is the line that you see when you use the <LOCK>
               key on the Portfolio.  0 for off, 1 for on.


     TICK      exp

               Sets the Clock tick speed.  0 is Normal, 1 tick
               every 128 seconds.  1 is Fast, 1 tick every
               second.  1 uses much more power.


     VCSRLIN

               Returns the current virtual cursor line.


     VLOCATE   row,col

               Move the virtual cursor to row, col.  This
               location will be at position 1,1 on the physical
               screen.


     VMOVE     dir, dis

               Move the screen in direction dir for dis number of
               lines.  Works only in Static and Tracked modes. 
               Same as using the ALT arrow keys.  Values for dir
               are 1=Up,2=Down,3=Left,4=Right.


     VPOS(exp)
               Returns the current virtual cursor column.  Exp is
               a dummy expression.


UPGRADE HISTORY

     Version 3.0    November 25, 1990.

          Added sample programs.
          Complied with Turbo C, version 2.0.
          Added Help file for Portfolio Address Function.
          Two Dimensional Arrays.
          Expanded TEST.BAS to TEST30.BAS with strings.
          TEST30.BAS - 17.0 seconds
          TEST21.BAS - 10.4 seconds
          New Functions: PBVER


     Version 2.9    Beta Release - September 30, 1990.

          Added Strings.
          Modified READ, SWAP and DIAL to handle strings.
          Added STRING arrays.
          Modified IF and PRINT to work with string expressions.
          Fixed PRINT" problem. 
          Allow line numbers directly after THEN or ELSE.
          Now allows two dimensional arrays of any type.
          Converted to Turbo C++, Version 1.0.
          New Functions : ASC, DATE$, INSTR, INKEY$, VAL, LEFT$,
               MID$, RIGHT$, CHR$, HEX$, OCT$, SPACE$, STR$,
               STRING$, TIME$


     Version 2.2    Not Released.

          Added hashing feature to symbol table to speed up
               variable table access.  10% increase in TEST.
          Added automatic default extension of ".BAS"


     Version 2.1    August 4, 1990

          New Statements: DATA, READ, RESTORE
          New Functions : LOG
          TRON invoked from command line switch -T
          Adjusted the screen coordinates from 0,0 to 1,1 to
               match GWBASIC.  While this will cause some
               incompatibilities with previous versions of
               PBASIC, it will make it more compatible with
               GWBASIC.
          Added INP to the documentation.
          Added FRE to the documentation.
          Installed Binary search for command checking.  Speed
               increase about 40%.
          One letter variable names are not checked in command
               table.
          Fixed the load routine to allow for no CR/LF at the end
               of the file.
          Fixed FIX function.
          Fixed scientific constants.
          Fixed power (^) function.


     Version 2.0    July 27, 1990

          New Statements: LPRINT, PRINTER, FORMFEED, PRTSC, WAIT,
               OUT, DIM
          New Functions : LPOS, ATN, EXP, FIX, INT, COS, SIN,
               SQR, TAN, TIMER, \, INP, FRE
          New Portfolio Only : GETDISPLAY, DISPLAY, VLOCATE,
               VMOVE, VPOS, VCSRLIN, ROMVER, PORT
          200 variables, 8 significant characters.
          <ALT-R> TSR to invoke BASIC from inside editor.
          Program size limited to available memory.
          All variables are now SINGLE PRECISION FLOATING POINT.
          One Dimensional Floating Point Arrays.
          Fixed FOR/NEXT looping with a negative step.
          Fixed the use of FUNCTIONS in PRINT statements.
          Fixed EOF error on Portfolio: Lockup if no END
               statement.
          Added extensive printer support.
          DEFINT will now cause a syntax error.
          RND was changed to make it MS compatible.
          SWAP was make array compatible.
          Fixed ... else "string" problem.
          Added NEXT to the documentation.


     Version 1.1    July 21, 1990

          New Statements: DEF SEG, POKE
          New Functions : PEEK
          New Portfolio Only : REFRESH, TICK, CLICK, STATUS
          Automatically invoke Editor on Error.
          Fixed ALARM problem: keystroke was going into buffer.
          Fixed ON x GOTO/GOSUB problem: Offset line count by 1.
          Improved Error Detection.
          Allow REM in PRINT with preceding colon (:).
          Implement the quote (') as a substitute for REM.
          Fix PSET documentation to indicate ()'s.
          Screen mode changes, return to original on error.
          Allow for spaces as separator in PRINT.

     Version 1.0    July 14, 1990
          Initial release.


TECHNICAL NOTES

          PBASIC is about 2500 lines of code was written in Turbo
     C, version 2.0, compiled to an executable file just under
     50k in size.  PBASIC was then compressed with LZEXE, version
     0.91, to further reduce the size to about 33k.

          PBASIC will run on a regular PC, providing you do not
     use any Portfolio specific statements.  If you have the
     Portfolio Emulation software (I60, I61), you can use all the
     features.

          PBASIC was developed on a Gateway 2000, 33Mhz 386 PC
     with 4meg of memory.  It was tested on the Atari Portfolio,
     ROM version 1.052.


BATCH CONSIDERATIONS

          If you are running PBASIC as a batch file, you can
     access the ERRORLEVEL code generated upon exit.

               0 - Successful exit
               1 - Program aborted
               2 - STOP encountered


FUTURE ENHANCEMENTS

     - A much better manual (about Christmas time)
     - Files
     - Menus
     - CHAINing programs 
     - Increase compatibility with Microsoft BASIC


THE FILES

     PBASIC.EXE     The Interpreter.
     PBASIC.TXT     This file.
     PBASIC.ADR     Help file to be loaded into the Address book
                         on the Portfolio.
     ALTR.COM       TSR to execute PBASIC from editor.
     TEST.BAS       A program to exercise the interpreter. 
                         Should not generate any errors.  It will
                         run on a PC or Portfolio.  Take a look
                         at it, it demos many of the features of
                         the Portfolio Only routines.
     C.BAT          Calculate Expression from DOS.  Invokes
                         PBASIC.EXE to display answer.
                    Example: C 123*(567+9845)/18

     Sample PBASIC programs
     100DAYS.BAS    Calculate 100 days after a date.
     2CURVE.BAS     Graph Plot program.  Written by Rob Kunstadt.
     ADDTIME.BAS    Program to add up time in Minutes and
                         Seconds.  Written by Louis Shapiro.
     BAR.BAS        Bar Chart program.  Written by Rob Kunstadt.
     CHART.BAS      Chart hours worked.  Written by Rob Kunstadt.
     CIRCLE.BAS     Demo of Circle Drawing Subroutine.
     DAYS.BAS       Calc the number of days between two dates.
     ETCH.BAS       Simple Drawing Program.
     REV.BAS        Game of Reverse.

     The MUSIC Files by John Fraser
     BACH1.BAS      BACH2.BAS      BETH2.BAS
     BDAY.BAS       KRIEGER.BAS    PETER1.BAS
     MUSIC.TXT      Notes from the author.

     Utilities
     FIX0D.COM           TSR fix for Portfolio graphics rom.
     FIX0D.TXT 


ABOUT THE AUTHOR

     Mr. BJ Gleason is an Instructor at The American University
     in the Computer Science and Information Systems Department. 
     He has been programming for over a decade now.


COMMENTS, BUGS AND IDEAS

          What features do you really need in PBASIC to make it
     more useful on the Portfolio?  If you would like to see some
     new features, contact me and I will try to accommodate you
     and release a new version.


ACKNOWLEDGEMENTS

          Thanks to all those Compuserve for their bug reports,
     suggestions and words of encouragement.  Without their
     feedback, version 3.0 would have never seen the light of
     day.  Keep those cards and letters coming!

          The author would also like to extend his thanks to
     Walter Daniels, for helping me track down the ever-elusive
     bugs, and putting up with a flaky copy of version 2.9.


ADDRESS

          If you have an comments, suggestions or bug reports,
     you can write to the author at:


          BJ Gleason
          The American University
          CSIS  (Thin Air Labs)
          4400 Massachusetts Avenue, N.W.
          Washington, DC  20016

          Compuserve : 73337,2011

     
          This program and documentation is being placed into the
     public domain by the author.  It can be copied and
     distributed freely.  It can not be sold or used for
     commercial purposes without permission.

     PBASIC version 3.0, Copyright 1990 by BJ Gleason.

     Portfolio, Atari, Microsoft, GWBASIC are trademarks of their
     respective companies.
