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 , 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 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 ? 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 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 ' ? 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 . 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