PBASIC Programming



Copyright 1991, BJ Gleason



Welcome to the PBASIC Programming Column.  This column with focus

on developing applications for the Portfolio using PBASIC.  Since

PBASIC is an offshoot of standard BASIC, and since this is a

newsletter on programming, I will assume that you, kind reader,

know general BASIC programming.  This column will focus more on

the "Portfolio-only", and "PBASIC-only" features of the language.



Portfolio-only features are functions and statements that will

only work on the Portfolio.  These functions and statements are

unique to the Portfolio and use several of the Portfolio's built-

in ROM functions.  To use these features on machines other than

the Portfolio, you will need the "Portfolio Emulation Software",

from Atari Corporation.  With the emulations software loaded, you

can then use the "-E" switch (for Emulation) to trick PBASIC into

thinking that you are running on the Portfolio instead of the PC. 

Be warned: If you use the -E switch without the Emulation

software, you can lock up your machine.  Typically Portfolio-only

features include MENU, BOX, EDIT$, and others.



PBASIC-only features are statements and commands that are unique

to PBASIC.  These features will work on both a PC and a

Portfolio, without problems, but are not included in most other

BASICs.  One of the nice things about writing a language is that

I can add features to it that I always though were lacking in

other version.  These features include EVAL, EXITCMD, NUMFMT,

WKSREAD and others.



In each column, I will discuss a few of these features and show

you how to use them so you can include them in your own programs.



First, lets start out by looking at the new features of PBASIC

4.7.





NEW FEATURES FOR VERSION 4.7



     New Statements: EXITCMD, EXITCODE

     New Functions: INSTAT, ISALTR, ISRUN

     Multi-lined IF/THEN/ELSE/ENDIF.

     Modified parameters for MENU( to allow for more flexibility.

     Maximum size of string is now 350 characters.  This changes

          the way SCRLOAD and SCRSAVE can operate.

     Added PBCOMP to allow for .BAS source code compression. 

          Auto-detection and decompression on load.  Reduces

          source code by 60%

     Disabled -T parameter for compressed/encode programs.



There were also a fair number of bug fixes, see the PBASIC.TXT

file for a complete list.



Let's take a closer look at some of these features.



EXITCMD s$



This will exit PBASIC, and place the contents of s$ in the

keyboard buffer.  If your program was creating some data files,

you might want to list them when the program ends to alert the

user of their presence and remind them to back them up: 



     PRINT "Data Files were Created."

     PRINT "Please back them up."

     EXITCMD "dir *.dat"



     Data Files were Created.

     Please back them up.

     A>dir *.dat

     .....

     A>





EXITCODE  n



Exit PBASIC, and set MS/DOS ERRORLEVEL variable to n.  ERRORLEVEL

can be tested in a batch file.



     CLS

     PBASIC myfile

     IF ERRORLEVEL 5 GOTO :ERROR

     ....





MULTI-LINE IF/THEN/ELSE/ENDIF



     IF        exp THEN

                    statements

               [ ELSE

                    statements ]

               ENDIF



In an effort to make PBASIC programs more structured and more

readable, a multi-line IF statement has been added.  Multi-line

IF statements may not be nested.  There can not be anything after

the THEN or the ELSE on the same line, or it will be recognized

as a single line IF.





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.  This is used extensivly in this

month's program.



     IF ISRUN THEN RUN "MENU" ELSE END





PBCOMP.EXE



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 a compressed file.



This program is supplied to allow developers to write programs in

PBASIC and distribute them without releasing the source code of

the program.  It also allows users to have more programs on a

RAMcard.



For security reasons, a program can not be decompressed, so be

sure to keep a regualr copy of the code, in case changes need to

be made.





THIS MONTH'S PROGRAM: MENU.BAS



PBASIC comes with a number of sample programs to demonstrate the

different features.  In this month's program, we will construct

MENU.BAS, a program that will allow us to run these sample

programs from a two-level menu.



The idea behind the menu program is to allow uses to select a

program, execute it, and then return to the top-level menu.  To

achieve this, we will first have to modify each sample program to

include the following line, in place of the normal exit:



     IF ISRUN THEN RUN "MENU" ELSE END 



This will check to see if the program was executed from the

command line (pbasic program.bas) or via the RUN statement (run

"program.bas").  If execution is via the RUN statement, we will

re-run the MENU program, otherwise, it will have no effect, and

will return back to DOS.  This line has already been added to the

programs contained in PBAS47.ZIP.



Now onto the Menu program itself.  Since we are going to save

screens, we want to set string size to 350.  We then want to

create the arrays for the menu choices.



' set string size 

ssize=350 

' Declare our main and auxilary menu arrays 

dim m$(7), a$(7) 



Now we will create the menu matrix.  One of the features of this

program is that as we add new programs, we don't have to change

the program, just the data.  The menus are created dynamically.



Here is the matrix of programs.  The first element in each line

is an option on the main menu, as well as the title for the

auxilary menu.  The data lines need to be numbered from 1, with

the last data line containing only the null "" string.  Then the

entire list of programs for the auxilary menu are listed,

followed by the null "" string.  Notice the program names do not

have ".BAS" on them, since it is automatically added by the RUN

command.



1 data "Recreation","ETCH","QCHESS","REDDOG","REV","VADERS","" 

2 data "Music","BACH1","BACH2","BDAY","KRIEGER","PETER1","" 

3 data "Graphics","2CURVE","BAR","CIRCLE","PGDEMO","WKSPLOT","" 

4 data "Time","WTIME","100DAY","ADDTIM","DAYS","" 

5 data "Other","AREACD","SIEVE","TEST47","GATE40","TERMINAL","" 

6 data "" 



Now we will initialize and create the main menu.  Starting with

data line 1, we will read the first string.  This will be a

selection from the main menu, as well as the title of the

auxiliary menu.  We fill the M$() array until we reach the ""

string (currently on data line 6). 

  

cls

cline=0   ' Current Line 

select=0  ' Selected Item 

mcnt=0    ' Main Menu Count 

done=false                          

repeat 

     restore mcnt+1      ' Point to data line 

     read m$(mcnt)       ' Read Title 

     if m$(mcnt)<>"" then mcnt=mcnt+1 else done=true 

until done 



The creation of the main menu only needs to be done once, since

it will not change.  The auxiliary menus need to be created each

time.  Now to display the menu, we use the Portfolio Only

function MENU.  Let's take a closer look at the MENU function.



     x=MENU(row, col, display, top line, selected, elements,

          "Title", entries....)



Row and Col indicate the location of the menu on the screen. 

Display is the number of elements to display at one time.  The

maximum is 6.  You can have more than six elements in a menu, but

only 6 can be displayed at any time.  You can use the arrow keys

to scroll through the menu.



Top Line is element at the top of the menu, and Selected is the

element that the cursor is placed on.  Normally both of these are

initialized to 0, to place the first element at the top of the

menu and place the cursor on it.  We will use variables for

these, so that if a user returns from a sub-menu, by pressing

<ESC>, the cursor will still be on the same menu element.



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.  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.



Armed with this knowledge, let's create the menu.



10 mc=menu(1,1,mcnt,cline,select,mcnt+1,"PBASIC Menu",

     m$(0),m$(1),m$(2),m$(3),m$(4),m$(5),m$(6),m$(7)) 



We have allowed for up to eight entries, M$(0) to M$(7), which is

more than we currently have.  This will allow you to quickly add

more sample programs to the list without modifying the program. 



This will display a menu, allow a selection, and will return the

item selected.  The menu elements are numbered from 0.  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.



Here is the code to find the selected item, as well as the top

line, so that we can go back to the item.  Let's also handle the

<ESC> key from the main menu.



select = mc % 256   ' Determine the item selected 

cline = mc \ 256    ' Determine the top line so we can go back 

if select=-1 then cls:end     ' Hit <ESC>? Exit... 



If we have gotten this far, we now want to create, display, and

select from an auxiliary menu.  Using the RESTORE statement, we

can move the data pointer back to the proper data statement.  We

will then read the title, and then the elements in the A$()

array.



restore select+1    ' Point to selected data line 

read title$         ' Read Title 

ocnt=0 

done=false 

repeat 

     read a$(ocnt)  ' Read the Programs 

     if a$(ocnt)<>"" then ocnt=ocnt+1 else done=true 

until done 



Now we want to display the menu.  Before we display it, we want

to save the current screen, so that we can come back to the main

menu.  While we could use CLS before moving back to the main

menu, the SCRSAVE and SCRLOAD make for a much smoother

transition.

To save a screen, using SCRSAVE, requires 320 bytes of memory. 

To save it in a single string, we need to set SSIZE to 321 or

more.  We have already set it to 350 at the beginning of the

program.



After saving the screen, we need to display the auxiliary menu,

handle the <ESC> key, to return to the main menu.



scrsave s$          ' Save the current screen 



' display the aux menu

mc=menu(1,10,ocnt,0,0,ocnt+1,title$,

     a$(0),a$(1),a$(2),a$(3),a$(4),a$(5),a$(6)) 

pick = mc % 256     ' Determine which Program 



' <ESC>?  Restore Screen, return to Main Menu 

if pick=-1 then scrload s$:goto 10 



Finally, we can run the program:



cls                  

run a$(pick)        ' Run the Program 

 



If you want to add your own programs to this list, we can modify

the program table easily enough.  If you want to add a section

entitled "Travel", and a few programs called: ETA.BAS, and

MPG.BAS, we would replace data line 6 and add data line 7:



     6 data "Travel","ETA","MPG",""

     7 data ""



The entire program is available in the PBAS47.ZIP archive as

MENU.BAS.





PROGRAMMING TIP



Often in a program, you must ask a question like "Exit (Y/N)?" or

"Play Again (Y/N)?" or some variation thereof.  Processing this

(did the person type "Y", "y" or "Yes"?) can be a pain.  The MENU

function can make this much easier.



     mc=MENU(2,2,2,0,0,3,"Exit?","Yes","No")



This will return 0 for Yes, 1 for No, and a -1 for <ESC>.





FUTURE COLUMNS



     Graphics Program with .PGC files

     Window Routines

     Worksheet Importing

     Serial Communications

     





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, and is the

     author of PBASIC 4.7.



     You can write to him 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



     

