Portfolio BASIC, version 4.8 (c) 1991 BJ Gleason by BJ Gleason, The American University INTRODUCTION PBASIC is a simple BASIC interpreter. It only requires 43k of disk space and about 67k 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! MANUAL AVAILABLE A 250 page manual on PBASIC is now available. The manual is 8.5 x 11, and has comb binding so it can lay flat. Each instruction is explained in detail, with examples. The manual costs 35 dollars, including postage. If you are interested in obtaining the manual, send a check or money order to "BJ Gleason" at the address on the last page of this document. WHAT THE CRITICS SAY: PBASIC 2.1 was reviewed by John Jainschigg in Atari Explorer, January 1991. Here is some of he said: "...PBASIC is a terrific little job of programming... Though freeware, PBASIC has been professionally and completely documented... even those who are waiting on tenterhooks for Atari's own Portfolio BASIC may find PBASIC very useful in the interim. The program is reasonably reliable, complete, and professionally executed - and at the present time, stands as the best alternative for casual programming on the Portfolio system." Ron Luks, Sysop of the APORTFOLIO forum on Compuserve says: "...I was blown away!!! Its FAR, FAR more complete and polished that I ever would have expected for a freeware product. The PBASIC manual is equal to the best I've seen for any commercial program, and superior to 90% or the rest." Don Messerli, developer of the PGC graphics standard, stated in ATARI.RSC, The Atari Developer's Resource, May 1991: "PBASIC is the most significant public domain program, and arguably the most significant third-party application of any kind currently available for the Portfolio." NOTES TO NEW USERS PBASIC is not like GWBASIC in one important feature. GWBASIC has a built-in editor, and PBASIC does not. PBASIC uses the Atari Portfolio's Built-in editor. PBASIC is run from the command line, with the name of the program you want to execute. For example, to run the program MENU.BAS, you would type: PBASIC MENU For more information, see INTERFACING WITH THE EDITOR, and RUNNING PBASIC. PROGRAM LAUNCHER On the disk, there are a number of example programs. To use any of these programs, enter the command "PBASIC filename" where filename is the name of the program you wish to execute. An alternative method is to use the program launcher, MENU.BAS. This provides a pull-down interface to all the demo programs. To use the launcher, enter the command "PBASIC MENU". COMPATIBILITY NOTE There was a slight change in the PBASIC language from version 4.5 to 4.6 that caused a minor incompatibility with some programs. For example, the following line was correct in version 4.5: PSET (x,y) Notice the space between the "T" and the "(". In version 4.6 and later this will cause an "= expected error in xx" error. In functions and statements that require the use of a "(" as part of the syntax, no space is allowed. So the line would have to be re-written as: PSET(x,y) This can be done automatically with SPB.EXE, which will eliminate any needed line numbers, spaces and REMarks. 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 4.8 New Functions: CHARPTR, CWD$, EXISTS, FILESIZE, FINDFILE$, FINDNEXT$ New Statements: CMODE, GLOCATE, GPRINT PRINT will now work on a graphics screen. Added -P switch, to allow users to swap memory cards. New Demo Program: RUNMAN.BAS 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 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. On a PC compatible machine, the error message will include the line number, character position and offset from the front of the file. This is so that the PBASIC EDITOR, for the PC, can determine where the error is and point to it. 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 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 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] [-E] [-P] PBASIC filename.ext [-T] [-E] [-P] 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 . The command line switch -T will turn on the trace feature. This is the same as putting TRON at the beginning of you program. The command line switch -E will force Portfolio Emulation. This can lock you your computer it I60 and I61 are not loaded first. The command line switch -P will turn off the Portfolio before the .BAS program is loaded. This will allow the user to load PBASIC from one card, and run a program on another card. Press any key to continue. GENERAL Source code is standard ASCII format. Source code can be in upper or lower case. 130 variables. Variable names can not exceed 8 characters in length. Default string size is 256 bytes. This can be changed with SSIZE. FOR/NEXT loops may be nested 10 deep. GOSUBs may be nested 10 deep. WHILE / WEND may be nested 10 deep. REPEAT / UNTIL 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 1 to 65535. Multiple statements per line (:) is supported. Up to 10 Files can be open at the same time. 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. For easier development on a PC, PBE, the PBASIC Editor is now available. PBE operates similar to Turbo Pascal, and allows you to execute programs from inside the editor. IT will also let you transfer files back and forth to the Portfolio. MATH EXPRESSIONS Single precision math. Parentheses supported. Standard operator evaluation. Hexadecimal and Octal constants are supported. - negation ^ exponent * multiply / divide % remainder (MOD) \ integer division + addition - subtraction AND, OR, NOT, XOR, EQV, IMP <, >, <=, >=, =, <> 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 that are not from Microsoft. They will not run on GWBASIC. BLOAD filename, offset Load a file to location SEG:offset. BSAVE filename, offset, length Copies memory to file, starting from SEG:offset for length bytes. CALL address Transfer control to SEG:address. Data is passed via the registers with the REG statement/function. CALL INTERRUPT intno Invoke DOS interrupt intno. Data is passed via the registers with the REG statement/function. CHAIN filename Load and execute the indicated file. All variables are retained. CHDIR path Change the current directory to path. CLOSE# fileno Close the file. CLS Clears the screen. CMODE = cm Set character mode when printing in graphics mode. The bit pattern is: 0 Underline (+1) 1 Reverse (+2) 2 Wide (+4) 3 Upside Down (+8) 4 Sideway (+16) To set Reverse Wide = 2+4 = 6. Use 24 to print sideways in the other direction. COMOUT = val Send val to serial port. See TERMINAL.BAS. COMSET = config Set the serial port to the config byte, bits defined as follows: 7 6 5 4 3 2 1 0 Baud Rate Parity Stop Bits Word Length 0 0 0 = 110 x 0 = none 0 = 1 bits 1 0 = 7 bits 0 0 1 = 150 0 1 = odd 1 = 2 bits 1 1 = 8 bits 0 1 0 = 300 1 1 = even 0 1 1 = 600 1 0 0 = 1200 1 0 1 = 2400 1 1 0 = 4800 1 1 1 = 9600 See TERMINAL.BAS. 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 DECR(var) Decrement the variable by 1. DEF funname(params) = expression Creates a functions called funname. All variables are global. Function names do not have to begin with FN. Only numerical functions are allowed. DEF SEG = exp Assigns a segment address for direct memory accessing via PEEK, POKE and CALL. DIM varname(size,[size])[,varname(size,[size])....] Creates a one or two 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 array bounds are not checked, arrays are not allowed to go below 0. END SYSTEM and END have the same effect. ERROR errnum Simulate Error for testing ON ERROR GOTO. EVAL var$ Evaluates the contents of var$ as if it was part of a BASIC program. EXITCMD s$ Exit PBASIC, and place the contents of s$ in the keyboard buffer. .... EXITCMD "dir *.dat" {exit PBASIC} A>dir *.dat ..... EXITCODE n Exit PBASIC, and set MS/DOS ERRORLEVEL variable to n. ERRORLEVEL can be tested in a batch file. SAMPLE.BAT CLS PBASIC myfile IF ERRORLEVEL 5 GOTO :ERROR .... FOR varname = exp TO exp [STEP exp] FORMFEED Send a formfeed to the printer. GLOCATE x,y Set the graphics cursor to location x,y. Used with GPRINT. GOSUB line number GOTO line number GPRINT list of expressions Bit mapped character display. Top bit is 0, bottom bit is 7. Expressions can be a string of hexadecimal values, or hex numbers. Separators are (;) and (,) where the comma will skip one space. This is handy for creating your own character set. screen 6 gprint "58483e28cc" : 'display a man wait end IF exp THEN statement [ ELSE statement ] IF exp THEN statements [ ELSE statements ] ENDIF Multi-line IF statements may not be nested. There can not be anything after the THEN or the ELSE on the same line. INCR(var) Increment var by 1. INPUT ["prompt" (,|;)] varname Reads input 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. INPUT# fileno, varname This will read a variable from a disk file. KILL filename Delete filename from disk. LINE(x1,y1)-(x2,y)[,c[,B[F]]] Line will draw a line from x1,y1 to x2,y2. c is the color of the line. B means to draw a box, and F is to fill the box. NOTE: You must write as LINE(... not LINE (... LOCATE row,col[,cursor] Move the cursor to row, col. The optional parameter cursor can be used to turn the cursor on or off. On the Portfolio: 0=off, 1=underline, 2=block. On the PC: 0=off, 1=block, 2=block. LPCHR$(x) Send the ASCII character of value x to the printer. This was done to allow the printing of characters 0 and 9, where are filtered by the LPRINT statement. LPRINT list of expressions Send output to printer. See PRINT. MID$(s$,p[,l])=r$ Replace the characters in s$, starting at position p, for length l, with the characters in r$. MKDIR path Create a directory named path. NEXT [varname] If no variable name is given, last FOR statement is used. If variable name is given, matching FOR is searched for and used, if found. This process allows for exiting early from inner loops. NUMFMT = "format" In PBASIC numbers are not displayed in classic GWBASIC format. GWBASIC always prints numbers with a leading space or -, and a trailing space. To make the porting of GWBASIC programs easier, you can specify the format that numbers are to print with the NUMFMT statement. The default is "%g", and GWBASIC format would be "% g ". This can also be used if you want all numbers in scientific or other format. See the PRINT USING description for the format. ON ERROR GOTO line number Error trapping. When an error occurs, user will be transferred to line number. A line number of 0 will disable error trapping. ON exp GOTO list of line numbers ON exp GOSUB list of line numbers OPEN "mode",fileno,filename Open a file. Mode can be: I Input O Output A Append Fileno can be between 1 and 10. Only ten files may be open at any one time. Filename is any standard MS/DOS filename. 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[@l,] list of expressions List of expressions can consist of strings, variables, constants or expressions, separated by the comma (,) or semi-colon (;) or a space ( ). Starting with version 4.0, the ? can be used as an abbreviation for PRINT. @l indicate screen position 0-319, 40 columns by 8 rows. For Model 100 compatibility. The PRINT statements will not work on a graphics screen. The screen will not scroll. PRINT# fileno, list of expressions Same as PRINT, but send output to file. PRINT[@l,] USING format; list of variables This is not GWBASIC compatible. To implement the full version of the PRINT USING would take up too much room. This version is like C's printf. Format is a string, indicating the format to print a single variable. Each variable in the list is printed with that format. For more details, refer to Turbo C's reference manual. @l indicate screen position 0-319, 40 columns by 8 rows. For Model 100 compatibility. Format Specifiers: %s String %f Real [-]dddd.dddd %e Real [-]d.ddde[+/-]ddd %E Real [-]d.dddE[+/-]ddd %g Real, general format, e or f %G Real, general format, E or f %% Print % character in format string % g Print numbers in GWBASIC format Widths/Precisions: n n characters are printed 0n n characters with leading 0's .0 no decimal point .n n digits after the decimal point Examples Output "|%10.2f|";123.123 | 123.12| "|%10.0f|";123.123 | 123| "|%5.0f%%|";10;15 | 10%|| 15%| "|%010.2f|";123.456 |0000123.46| "|%e|";456.789 |4.56789e+02| "|%E|";567.901 |5.67901E+02| PRINT# fileno, USING format; list of variables Same as PRINT USING, but send output to file. PRINTER This is a toggle to start copying all PRINT statements to the printer. Issue it again and it will toggle off. It 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. PRTSC This invokes 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. 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. REG rn, val Set rn to val. Allows for access to the 8086's register set. Values for rn are: 0 - Flags 1 - AX 2 - BX 3 - CX 4 - DX 5 - SI 6 - DI REM Remark. The rest of the line is ignored. You can also use the quote (') mark as a REM statement. REPEAT / UNTIL exp Statements between the REPEAT and UNTIL statements are executed until exp becomes TRUE. 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. RESUME line number After an error is trapped via ON ERROR GOTO, resume will allow a program to continue at the indicated line number. RETURN Return from a subroutine invoked via a GOSUB. RMDIR Remove a directory from the disk. Directory must be empty. RUN filename Load and execute the indicated program. All the variables are reset. 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 recommended 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. SSIZE = x This sets the default string size. Normally, strings are set to 256 bytes in length. Under many circumstances, this can waste a large amount of memory. For Example, A$(100) normally requires about 25600 bytes. If SSIZE=80, it only requires about 8100 bytes. This should normally be set only once at the beginning of the program. The range of x can be 1 to 350. You can use it elsewhere in the program, but be careful. 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 Exchange the contents of two variables. They must be of the same type. 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. WHILE exp / WEND All the statements between the WHILE and WEND statements are executed while exp is TRUE. If exp is FALSE, the loop is not executed. WRITE list of expressions Similar to PRINT, but each element is separated by a command (,), and strings are enclosed in quotes ("). WRITE# fileno, list of expressions Same as WRITE, but send output to file. 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. ACOS(exp) Returns the arc cosine of exp. ARG$(x) Returns the command line arguments. ARG$(1) would be the first parameter after the PBASIC command. Under DOS 3.0 and later, ARG$(0) would be the name of the PBASIC program. ARGC Returns the number of parameters on the command line when PBASIC starts. If ARGC returns 0, then the program from the editor is being executed. ASC(x$) Returns ASCII value of the first character in x$. ASIN(exp) Returns the arc sine of exp. ATN(exp) Returns the arc tangent of exp. BIN$(n) Convert n to a Binary string. CEIL(x) Round x up to the next integer. CHARPTR Returns the address of the bit maps for the ASCII characters. This address can be used to insert your own character set. CHR$(n) Returns the ASCII character of the value n. COMMAND$ Returns the command line tail. COMIN Returns the ASCII value from the serial port. See TERMINAL.BAS. COMSTAT Returns the status of the serial port: Bit Significance (if set) Port Status 15 timed-out 14 transmit shift register empty 13 transmit holding register empty 12 break detected 11 framing error detected 10 parity error detected 9 overrun error detected 8 receive data ready Modem Status 7 receive line signal detect 6 ring indicator 5 data-set-ready 4 clear-to-send 3 change in receive line signal detect 2 trailing edge ring indicator 1 change in data-set-ready status 0 change in clear-to-send status See TERMINAL.BAS. COS(exp) Returns the Cosine of exp. COSH(exp) Returns the Hyperbolic cosine of exp. CSRLIN Returns the current cursor line. CWD$ Returns the current directory DATE$ Returns the system date. DEG(exp) Converts radians to degrees. DMS(exp) Convert degrees into degrees/minutes/seconds, in the form ddd.mmss. DOSVER Returns the version number of MS/DOS. EOF(fileno) Returns TRUE if fileno is at End-of-File. ERADR Returns the position of the error that occurred, as an offset from the beginning of the program. ERL Return the line number the error occurred on. ERMSG$ Returns the text of the error that occurred. ERR Returns the error number of the last error. EXISTS(x$) Returns TRUE if the file x$ exists. IF EXISTS("mystuff.txt") THEN ... EXP(exp) Returns e to the power of exp. FALSE Returns 0. FILESIZE Returns the filesize of the last file found by FINDFILE or FINDNEXT. FINDFILE$(x$) Returns the name of a file matching x$. Wildcards are allowed. print "Directory of ";cwd$ n$=findfile$("*.*") while n$<>"" print n$;tab(15);filesize n$=findnext$ wend FINDNEXT$ Returns the next file matching the criteria set by FINDFILE. FIX(exp) Returns the integer portion of exp. FRE(exp) Returns the free amount of memory. The parameter exp is a dummy expression. FREEFILE Returns the next free file number. HEX$(n) Converts n to a hexadecimal string. INKEY$ If a key is pressed, the character is returned, otherwise, the empty string ("") is returned. For a function key, a 2 character string is returned, with the second character indicating the function key. INP(port) Returns the byte value from port. INPUT$(n,#f) Returns the next n characters from file #f. INSTAT Returns TRUE if key has been pressed, otherwise FALSE. INSTR(x$,y$) Returns the position of y$ in x$. INT(exp) Returns the integer portion of exp. ISALTR Returns -1 if ALTR.COM is loaded, 0 otherwise. ISRUN Returns -1 if current program was executed via the RUN "filename" statement from another program. IF ISRUN THEN RUN "MENU" ELSE END LCASE$(x$) Return the lowercase version of x$. LEFT$(x$,n) Returns the leftmost n characters of x$. LEN(x$) Returns the length of x$. LOG(exp) Returns the natural logarithm of exp. LPOS(exp) Returns the current position of the line printer head. Exp is a dummy expression. LTRIM$(n$) Strips off any leading spaces. MID$(x$,n[,m]) Returns a string from x$, starting at position n for m characters. MSD(exp) Converts degrees/minutes/seconds in the form ddd.mmss to degrees. OCT$(n) Converts n to an Octal string. PASSWORD$ Reads a 8 character string from the keyboard without displaying it on the screen. 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. PI Returns the value of PI = 3.14159 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. PROGLOC Returns the address of the BASIC program. RAD(exp) Convert degrees to radians. RAND(exp) This will return a number between 0 and exp-1. REG(rn) Returns rn's value. Allows for access to the 8086's register set. Values for rn are: 0 - Flags 1 - AX 2 - BX 3 - CX 4 - DX 5 - SI 6 - DI REVERSE$(x$) Return the reverse of the string x$. RIGHT$(x$,n) Returns the rightmost n characters from x$. RND This will return a number between 0 and 1. RTRIM$(n$) Strips any trailing spaces from the string. SCREEN Returns the current video mode. See the command SCREEN for more information. SGN(exp) Returns the sign of exp. -1 exp < 0 0 exp = 0 1 exp > 0 SHIFT Returns the status of the shift keys. Bit Meaning 7 Insert On 6 Caps Lock On 5 Num Lock On 4 Scroll Lock On 3 Alt Key is down 2 Ctrl Key is down 1 Left Shift Key is down 0 Right Shift Key is down SIN(exp) Returns the sine of exp. SINH(exp) Returns the hyperbolic sine of exp. SPACE$(n) Returns a string of n spaces. SPC(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. m is the ASCII value of the characters. TAB(n) Moves the cursor to the nth column. TAN(exp) Returns the tangent of exp. TANH(exp) Returns the hyperbolic tangent of exp. TIME$ Returns the system time. TIMER Returns the number of seconds since midnight. TRUE Returns -1. UCASE$(x$) Returns the uppercase version of x$. VAL(x$) Returns the numeric value of x$. VARSEG(var) Returns the segment of the variable. VARPTR(var) Returns the offset of the variable. WKSREAD(filename, row, col) Returns the numeric contents of the cell at row, col from a worksheet file. Default Extension is .WKS. Row/Col start at 0,0. Example B5 would be 4,1. WKSREAD$(filename, row, col) Returns the string contents of the cell at row, col from a worksheet file. Default Extension is .WKS. Row/Col start at 0,0. Example D10 would be 9,3. WKSTYPE(filename, row, col) Returns the type of the cell at row, col from a worksheet file. Default Extension is .WKS. Row/Col start at 0,0. Example AB2 would be 1,27. Values returned: 1 EOF 12 Blank 13 Integer 14 Real 15 Label 16 Formula Result (Real) 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. Starting with version 4.0, using these statements on a standard PC will generate an error message. 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. EDIT$(title$,x$) This function return a string after it has been edited by the user. Title$ is the title placed on the editing box, while X$ is the string to be edited. The text under the window is not saved. The window located at the current cursor position. 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. INVERT Reverse the image on the graphics screen. MENU(row, col, display, top line, selected, elements, "Title", entries....) This will display a menu, allow a selection, and will return the item selected. If value returned is -1, then the escape has been pressed. If the value returned is > 255 then (value % 256) is the selected element, and (value \ 256) is the top line. Elements are numbered from 0. Row and Col indicate the location of the menu. Display is the number of elements to display at one time. The maximum is 6. Top Line is element at the top of the menu, and selected is the element that the cursor is placed on. Elements is the number of menu entries plus the Title. The title string is first, followed by each entry. Each element can be a string or a string variable. Example: mc = MENU(2,2,4,0,0,7,"Demo","A", "B", "C", "D", "E", "F") If the user picks A, mc = 0, for B, mc = 1. If the user picks F, mc = 517, which means the entry is 5, and the top line was 2. This will allow selection from the menu from the same position the second time it is invoked. Starting with version 4.7, you can have more entries than elements specifies. This allows for more flexible handling of the menus. After element number of entries, the rest are ignored. OFF This will turn the Portfolio off until the user presses a key. The program will continue execution with the next statement. PGLOAD filename Load a .PGC file into screen memory. PGSAVE filename Save video memory to .PGC file. PGSHOW filename, delay Display a .PGC file, and wait delay seconds. If delay is 0, wait for keypress. 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. SCRLOAD n$ Copy the contents from n$ back to the screen. SCRSAVE n$ Save the contents of the screen to n$. Using SSIZE, set the size of the strings to at least 325 since the screen requires 320 bytes to be saved. No check is made to see if enough memory is available. Example: SSIZE=325:n$="" : rem initialize n$ SCRSAVE n$ : rem save it .... SCRLOAD n$ : rem restore it 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 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. BREAKING OUT OF PROGRAMS It appears that if you use the CONTROL-C key to break out of a PBASIC program, it will lock up a few minutes later. I have tried to trace this, but to no avail. Chalk it up a difference between the PC and Portfolio. To eliminate this problem, you can now use the ATARI key, ( /|\ ) by itself, to exit from a PBASIC program. Press the key at any point. As long as you hold down the key, the error message "BREAK in xx" will remain on the screen. Release the key and you are returned to the MD/DOS prompt. If you execute the program from the editor, you will be returned to the editor, with the cursor pointing to the last executed statement. UPGRADE HISTORY Version 4.8 October 5, 1991 TAB and (,) should now be more accurate. LINE( now has a default color of 1. PRINT will now work on a graphics screen. Fixed SSIZE effect on CHR$, LPCHR$, STRING$. Speeded up CLS statement. Fixed INPUT$( function. Reset screen mode, if necessary, on exit. Added -P switch, to allow users to swap memory cards. New Functions: CHARPTR, CWD$, EXISTS, FILESIZE, FINDFILE$, FINDNEXT$ New Statements: GLOCATE, GPRINT, CMODE Version 4.71 August 21, 1991 (Beta Testers Only) Fixed PRINT's " ..; ELSE " problem. Fixed MSD() offset by 1 error. Changes PGSHOW/PGLOAD/PGSAVE to Portfolio Only Version 4.7 August 14, 1991 Fixed DMS and REG() functions. Improved TEST.BAS program. COMIN and COMOUT routines were modified to work on the classic "three-wire" connection. Replaced PBCODE.EXE with PBCOMP.EXE. Fixed WKSREAD$/WKSREAD switch. Fixed "Undefined Array" error detection. Modified parameters for MENU( to allow for more flexibility. Fixed Print error: day "/" month. Fixed clear screen on error. Maximum size of string is now 350 characters. This changes the way SCRLOAD and SCRSAVE can operate. Fixed graphics LINE statement. Added optional length to MID$ function. Fixed MID$ function to return null string instead of error if starting position is past end of string. Fixed STR$ to return Microsoft format if NUMFMT="% g ". Fixed ELSE problem: if a then if b then x else y y would be executed if a was false. Added PBCOMP to allow for .BAS source code compression. Autodetection and decompression on load. Reduces source code by 60% Cleaned up the code for PRINT. Disabled -T parameter for compressed/encode programs. Added Multi-lined IF/THEN/ELSE/ENDIF. New Statements: EXITCMD, EXITCODE New Functions: INSTAT, ISALTR, ISRUN Disk Size - 41342 bytes SPEED.BAS - 21.9 seconds SIEVE.BAS - 52.0 seconds TEST47.BAS - 17.9 seconds TEST45.BAS - 16.5 seconds Version 4.6 July 19, 1991 Speeded up PGLOAD/PGSHOW routines. RESTORE now accepts variables. New Function: PROGLOC Disk Size - 40855 bytes SPEED.BAS - 21.9 seconds SIEVE.BAS - 52.0 seconds TEST45.BAS - 16.5 seconds Version 4.54 July 12, 1991 (Beta Testers Only) Added -E switch. Allows for Portfolio emulation on a PC, requires I60 and I61 be loaded. Improved Memory Management for the RUN statement. Auto-detection of Serial or Parallel port for printing. New Statements: SSIZE New Portfolio Only: EDIT$ Version 4.53 July 7, 1991 (Beta Testers Only) Fixed MID$ offset-by-one problem. Added optional length to MID$ statement. Fixed communication routines. New Statements: LINE (graphics) New Functions: ARG$, ARGC, CEIL, DOSVER, ERADR, ERMSG$, FREEFILE, PASSWORD$, REVERSE$, SCREEN, SHIFT New Portfolio Only: INVERT Version 4.52 June 23, 1991 (Beta Testers Only) Applied Patched to TC 2.0 to fix "%.0f" problem. Changed PORTFOLIO Recognition routine. Is now compatible with HP95LX computer. Version 4.51 June 14, 1991 (Beta Testers Only) Modified INKEY$ to handle Function Keys. Added MID$ as a statement for string replacement. Modified tokenizer to allow Q and Q( to be separate variables. Version 4.5 May 17, 1991 Added program encoding for security. Use PBCODE to encode. PBASIC will decode and execute. Much faster .PGC graphics support, thanks to Don Messerli. Graphic screens can now be displayed at about 4 frames per second. Added Functions. Added COM port support. Line numbers must be between 1 and 65535. GOTO and GOSUB now support variables: GOTO X. Function PORT has been modified to return a -1 instead of 1. This change allows the use of IF NOT PORT THEN... New Statements: COMOUT, COMSET New Functions: COMIN, COMSTAT Disk Size - 38914 bytes SPEED.BAS - 21.9 seconds SIEVE.BAS - 52.4 seconds TEST45.BAS - 16.4 seconds Version 4.12 April 19, 1991 (School Only) Fixed two dimensional array addressing. Fixed ON...GOSUB error. Fixed -0 error on multiplication. Fixed (') Remark problem. Fixed MID$ for values greater than length of string. Fixed RAND(x) for x <= 0. Version 4.11 March 3, 1991 (Atari Only) Added LPCHR$(x) to print unfiltered characters. Modified INPUT# to accept EOF as end of string/number. Fixed LPRINT newline. Version 4.1 February 13, 1991 Now using PKLITE for compressions, saves about 1k. Added parameter to LOCATE statement to turn off cursor. Increased range of HEX$/OCT$/BIN$. Fixed ASC for characters greater than 127. Fixed FOR loop parameters: K=5:FOR K=1 to K+5 is now 1 to 10 instead of 1 to 6. Fixed DMS and MSD for negative numbers. Fixed Error messages in EVAL function. Fixed DIM out of memory for strings. Version 4.01 February 7, 1991 (School Only) Added @location, to PRINT statements for Model 100 compatibility. Reorganized command table to save about 1k. Fixed negative numbers in DATA statements problem. Modified the NEXT statement: If no variable, top of stack is used. If variable is given, stack is searched for match. Allows for aborting FOR loops early. Fixed relational operators. Return -1 instead of 1. Fixed symbol table overflow. Fixed documentation - 130 variables. Add additional error checking on file handling. Add range checking to the string operations. Fixed INPUT: long numbers entered as strings caused overflow errors. Fixed String Initialization problem. Version 4.0 February 1, 1991 New Statements: USING, CLOSE, EOF, INPUT$, NUMFMT, OPEN, PRINT#, REPEAT, UNTIL, WEND, WHILE, WRITE# New Functions: ACOS, AND, ASIN, COSH, DEG, DMS, EOF, EQV, IMP, LTRIM$, MSD, OR, RAD, RTRIM$, SINH, SPC, TAB, TANH, WKSREAD, WKSREAD$, WKSTYPE, XOR New Portfolio Only: MENU, SCRLOAD, SCRSAVE Sequential Files. Menus. Worksheet Importing Functions. Reorganized GetToken to increase speed. Reserved word lookup is now indexed binary search. Code was tighten and refined. Arrays can be used with FOR statements. Fixed error in .PGC compression routines. To convert any old .PGC files to the correct format, use the following program: 10 INPUT "Filename? ";f$:IF f$ = "" THEN END SCREEN 6:PGLOAD f$:PGSAVE f$:SCREEN 7:GOTO 10 Changed PC error messages to interface with PBE. IF statements modified to allow for single expression evaluation. Allows for IF EOF(1) THEN etc... If the result is 0, it is false, anything else is true. Modified the FOR statement to work more like GWBASIC. If the starting value to beyond the ending value, the loop is not executed. This includes nested loops. The Atari key ( /|\ ) will now act as a break key. Reorganized the IF statement to handle strings better. Installed option to output numbers in GWBASIC style: leading space or -, followed by space. Can be set by NUMFMT="% g " at the beginning of the program. Eliminated recursive ON ERROR trapping. Fixed DIM problem with multiple/mixed arrays. Fixed TAN error. Added looping - WHILE/WEND, REPEAT/UNTIL. Added LEN to the documentation. Fixed CHAIN variable loss. Added additional math error traps. Fixed -0 problem. Fixed negative numbers in print statements. Disk Size - 38539 bytes SPEED.BAS - 19.4 seconds SIEVE.BAS - 51.4 seconds TEST40.BAS - 17.0 seconds TEST31.BAS - 16.5 seconds TEST30.BAS - 15.9 seconds TEST21.BAS - 10.0 seconds Version 3.1a January 12, 1991 Minor bug : A$ = A$ + ... A$ is lost. Fixed. Version 3.1 January 5, 1991 New Statements: BLOAD, BSAVE, CALL, CALL INTERRUPT, CHAIN, CHDIR, DECR, ERROR, EVAL, INCR, KILL, MKDIR, ON ERROR GOTO, PGLOAD, PGSAVE, PGSHOW, RESUME, RMDIR, RUN New Functions: BIN$, COMMAND$, ERL, ERR, FALSE, LCASE$, PI, TRUE, UPCASE$, VARSEG, VARPTR Corrected the spelling of Walter Daniel's name. :-} Added support for .PGC files. Fixed DATA wrap around problem. Fixed DIAL problem. Error message for Portfolio Only Statements on PC. Disk Size - 35186 bytes SPEED.BAS - 25.9 seconds SIEVE.BAS - 79.5 seconds TEST31.BAS - 21.0 seconds TEST30.BAS - 20.5 seconds TEST21.BAS - 13.0 seconds 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. Disk Size - 33123 bytes SPEED.BAS - 27.4 seconds TEST30.BAS - 21.5 seconds (corrected) TEST21.BAS - 13.0 seconds (corrected) 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. Disk Size - 29649 bytes SPEED.BAS - 30.9 seconds TEST21.BAS - 12.9 seconds 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. 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 4000 lines of code was written in Turbo C, version 2.0, compiled to an executable file just under 66k in size. PBASIC was then compressed with PKLITE, version 1.01, to further reduce the size to about 43k. 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 if you use the -E switch. PBASIC will generate an error if you try to use a Portfolio only instruction on a PC. PBASIC was developed on a Gateway 2000, 33Mhz 386 PC with 4 megabytes 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 This ERRORLEVEL value can be modified by using EXITCODE. ERROR NUMBER AND MESSAGES 1 NEXT without FOR 2 Syntax Error 3 RETURN without GOSUB 4 Out of DATA 5 Illegal Function Call 6 Overflow 7 Out of Memory 8 Undefined Line Number 9 Subscript Out of Range 10 Duplicate Definition 11 Division by Zero 13 Type Mismatch 14 Out of String Space 15 String Too Long 18 Undefined User Function 19 No RESUME 20 RESUME without Error 22 Missing Operand 30 WEND without WHILE 31 Array Undefined 32 Not A Variable 33 Too Many Line Numbers 34 Duplicate Line Number 35 Too Many Nested FORs 36 Too Many Nested GOSUBs 37 Name/Line Number Too Long 38 BREAK 39 Portfolio Only 51 Internal Error 52 Bad File Number 53 File Not Found 54 Bad File Mode 61 Disk Full 73 Advanced Feature 76 Path Not Found FUTURE ENHANCEMENTS - Increase compatibility with Microsoft BASIC - Faster UTILITIES SPB SPB is a program to Squeeze PBASIC source code. This program will remove and unneeded spaces, line numbers and REMarks from the source code. This will reduce (slightly) the source code, but it will still be readable by the editor. This program will also help convert GWBASIC programs to PBASIC. PBCODE PBCODE was designed to encrypt PBASIC files. This program has been replaced by PBCOMP, which will encrypt and compress programs at the same time. PBCOMP PBCOMP was designed to compress PBASIC files. The compress ratio varies, from 60% to 40% depending on the program. Once a file in compressed, there is no way to decompress it. There is no difference in running the file. PBASIC will automatically detect and decompress an encrypted file. This program is supplied to allow developers to write programs in PBASIC and distribute them without releasing the source code to the program. It also allows users to have more programs on a RAMcard. THE FILES PBASIC.EXE The Interpreter. PBASIC.TXT This file. PBASIC.ADR Help file to be loaded into the Address book on the Portfolio. PBCOMP.EXE Compress PBASIC files for distribution. SPB.EXE Remove spaces, REMarks, and unneeded line numbers. ALTR.COM TSR to execute PBASIC from editor. TEST47.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 MENU.BAS A program launcher for all the demo 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 now with PGC support. REV.BAS Game of Reverse. RUNMAN.BAS A program to demo the new graphics functions. TERMINAL.BAS Simple Terminal Program. VADERS.BAS Space Invaders program from Model 100 forum. QCHESS.BAS Chess Program from the Model 100 forum. WKSPLOT.BAS Plot .WKS ranges as BAR or XY graphs. WKSPLOT.WKS Sample .WKS file for WKSPLOT.BAS. The MUSIC Files by John Fraser BACH1.BAS BACH2.BAS BETH2.BAS BDAY.BAS KRIEGER.BAS PETER1.BAS MUSIC.TXT Notes from the author. Portfolio Graphic Files (Compressed) by Don Messerli BOMB.PGC FUJI.PGC PORTF.PGC USA.PGC SPRIAL.PGC GORBY.PGC PGDEMO.BAS Sample program to demo PGC files. Utilities FIX0D.COM TSR fix for Portfolio graphics rom. FIX0D.TXT ALSO AVAILABLE PBE.EXE PBASIC Editor for PC's PBE.DOC Full screen editor designed for PBASIC development for the Portfolio. Invoke PBASIC from inside the editor. Access FT to transmit/receive files to/from the Portfolio. 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. He is a monthly columnist for AtariUser Magazine, and writes a PBASIC programming column for RE:Port. 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 4.8 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 Daniel, for helping me track down the ever-elusive bugs, and putting up with a flaky copy of version 2.9. Thanks also to Don Messerli, for his help implementing the graphic routines to support the .PGC graphics standard. Finally, many thanks to Ron Luks, the sysop of the APORTFOLIO conference on Compuserve. Thanks also to all the students (Those bug stomping fools!) in my Programming Languages Course, Spring 1991, at the American University. 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 EMAIL : bjgleas@auvm.american.edu This program and documentation can be copied and distributed freely. It can not be sold or used for commercial purposes without permission. PBASIC version 4.8, Copyright 1991 by BJ Gleason. Portfolio, Atari, Microsoft, GWBASIC are trademarks of their respective companies.