For a sample copy of PDA Developers, contact Creative Digital at info© cdpubs.com or visit their web site at http://www.cdpubs.com.

THE NS BASIC CORNER - FILE EDITING
John Schettino
GTE Laboratories, Inc.
js12© gte.com

Let me tell you a bit about myself. Besides programming in (and writing about) NewtonScript, I've been involved with NS BASIC from the beginning. I was one of the beta testers for NS BASIC when it was being developed, and continue to have a close relationship with the company. I coauthored the NS BASIC Handbook, and wrote many of the example programs. I also coauthored the book BASIC for the Newton, Programming for the Newton with NS BASIC, ISBN 0-12-623955-X, published last summer by AP Professional. This 404-page book describes developing database applications with Newton interfaces in NS BASIC, and includes a demo version of NS BASIC and source code to all the examples on the bundled disk.

This regular feature will cover beginning and advanced topics on programming Newton devices with NS BASIC. Prior to moving to PDA Developers, I wrote four columns for the electronic journal NewtOnLine. Only two issues of that magazine were published, but all four columns are available on my home page: http://users.aol.com/pdcjohns. The columns you may have missed are:

• July - column goals, an interview with George Henne of NS BASIC Corp.
• August - your first program (loan amortization), patching the system with NS BASIC.
• September - data types and flow control, using NewtonScript soup functions.
• October - frames, arrays, and files, creating multidimensional arrays, array functions.

In general, the articles in PDA Developers will be a bit shorter that the original four columns due to space constraints.

You may be asking yourself "Why BASIC?" The answer is simple: BASIC is an easy language to learn, with few surprises. You can start writing programs quickly, even if you've never programmed before. If you have any programming experience in functional languages like FORTRAN, C, or other BASICs, then you'll find this a comfortable home. NewtonScript is a wonderful language, and the NTK is the best development environment for commercial applications.

But it's an awful lot to learn for just tinkering. If you've got a simple problem to solve, or you'd like to write a custom application, NS BASIC could be for you.

I'm going to make several assumptions in this column. The first assumption is that if you have a question or suggestion, you'll e-mail me (js12© gte.com). The second assumption is that you have a copy of NS BASIC, and understand how to use the package. Unless otherwise noted, all programs I present will work with NS BASIC 2.0 or later, and the demo version of NS BASIC. I also recommend that you read the first four columns, since I won't be presenting that material here.

NS BASIC NEWS
There are two important releases of NS BASIC. Version 2.5.2, the most recent, has significant speed improvements, adds the EDIT lineNo command, and fixes some rare bugs. Version 3.0 is the Newton 2.0-compatible version. It adds several new Widgets, runs twice as fast, and can produce stand-alone packages. You can turn your programs into royalty-free packages that you can sell, or give away. I devote the next column to version 3.0.

WHERE WERE WE? FILES!
I covered how to create new and open existing files in the October column. I also covered a bit about adding new records to a file, and finding records. The next logical step is to edit existing records and delete records. Editing records in a file is very easy. You need to locate the record you want to edit using the GET statement, change the field values as needed, and then save it using the PUT statement. As with any programming language, there are some special rules to consider.

Deleting is also straight forward. You locate the record you want to delete using the GET statement, and then delete it using the DEL statement.

Let's extend the example music information program presented in the October column to support adding, editing, and deleting records. Figure 1 shows the program's interface. I use the simple character I/O statements PRINT and INPUT to display and enter a record's values for now. This form of user interface is not very friendly or pleasant to use, but it is easy to program. When you are creating programs you can always start with a simple character interface and then add a better one later. Just be sure to structure your program so there are gaps in the line numbers so you can add in the appropriate code. In a future column, I show you how to use Widgets to enter and display information via pick-lists, input lines, and check boxes arranged in a form.

To keep this example short, I have only three fields in each record in the file: Group, Title, and RunningTime. Here's the complete program:

10 REM Music Information
15 REM Open or create the file

20 OPEN MusicDb, "MusicFile", Title
30 IF FSTAT <> 0 THEN CREATE MusicDb, "MusicFile", Title

100 REM Main Menu

110 PRINT "Music Database"
120 PRINT
130 PRINT "1) Add Title"
140 PRINT "2) Search Title"
150 PRINT "3) List All Titles"
160 PRINT
170 PRINT "Select 1-3, Q to Quit:"
180 INPUT selection$
190 IF selection$ = "Q" THEN END
200 ON STRINGTONUMBER(selection$) GOSUB 2500,5000,7500 210 GOTO 110

1000 REM Display/Edit a frame in the variable editRecord

1010 PRINT "Music Record"
1020 PRINT
1030 PRINT "1) Title: "; editRecord.Title & ""
1040 PRINT "2) Group: "; editRecord.Group & ""
1050 PRINT "3) Running Time:";editRecord.RunningTime & ""
1060 PRINT
1070 PRINT "Select 1-3 to edit, D when Done:"
1080 INPUT selection$
1090 IF selection$ = "D" THEN RETURN
1100 ON STRINGTONUMBER(selection$) GOSUB 1200,1400,1600 1110 GOTO 1000

1200 REM edit the title

1210 PRINT "Enter Title [" & editRecord.Title & "]"
1220 INPUT title$
1230 editRecord.Title := title$
1240 RETURN

1400 REM edit the Group

1410 PRINT "Enter Group [" & editRecord.Group & "]"
1420 INPUT group$
1430 editRecord.Group := group$
1440 RETURN

1600 REM edit the running time

1610 PRINT "Enter RunningTime [" & editRecord.RunningTime
		 & "]"
1620 INPUT runningTime
1630 editRecord.RunningTime := runningTime
1640 RETURN

2500 REM Add A New Record

2510 editRecord:=  {Title:nil,Group:nil,RunningTime:nil}
2520 GOSUB 1000
2530 GET MusicDb, checkRec, editRecord.Title
2540 IF FSTAT <> 0 THEN GOTO 2570
2550 PRINT "New record would overwrite existing record!" 2560 GOTO 5320
2570 PUT MusicDb, editRecord
2580 RETURN

5000 REM search for record key, edit the matching record

5010 PRINT "Enter a Title, or press return for Main Menu"
5020 INPUT searchTitle$
5030 IF searchTitle$ = "" THEN RETURN
5040 GET MusicDb, foundRec, searchTitle$
5050 IF FSTAT <> 1 THEN GOTO 5060
5053 PRINT "Not found."
5056 GOTO 5000
5060 IF FSTAT = 2 THEN PRINT "Next Closest Record:"
		 ELSE PRINT "Matching Record:"
5070 PRINT "Title: ";foundRec.Title;" Group: ";
	   foundRec.Group
5080 PRINT "1) Edit Title"
5090 PRINT "2) Delete Title"
5100 PRINT
5110 PRINT "Select 1, 2, or R to Return to Search:"
5120 INPUT selection$
5130 IF selection$ = "R" THEN GOTO 5000
5140 ON STRINGTONUMBER(selection$) GOSUB 5300,5500 5150
		 GOTO 5000

5300 REM edit record in foundRec

5310 editRecord = foundRec
5320 GOSUB 1000
5330 IF editRecord.Title = foundRec.Title THEN GOTO 5390
5340 GET MusicDb, checkRec, editRecord.Title
5350 IF FSTAT <> 0 THEN GOTO 5380
5360 PRINT "Edited record would overwrite existing
		 record!"
5370 GOTO 5320
5380 DEL MusicDb, foundRec
5390 PUT MusicDb, editRecord
5400 RETURN

5500 REM delete record in foundRec

5510 DEL MusicDb, foundRec
5520 RETURN

7500 REM dump all records block

7510 GET MusicDb, foundRec, ""
7520 IF FSTAT = 1 THEN GOTO 7560
7530 PRINT "Title: "; foundRec.Title; " Group: ";
		 foundRec.Group; " Time: "; foundRec.RunningTime
7540 GET MusicDb, foundRec
7550 GOTO 7520
7560 RETURN

Lines 1000-1640 display and edit the three field values stored in the record frame for the file. The program uses this same block of code to enter information for new records and edit information in existing records.

Lines 2500-2580 add a new record to the file. First an empty record frame is created, so the user can enter the values (line 2510). Then the program calls the subroutine at line 1000 to GET the user input for the fields in the record. When this subroutine returns, the Title entered is used as the key in a GET statement. If the GET finds an exact match, the variable FSTAT is set to zero. Rather than overwriting the existing record, a message is displayed and the user is sent back to the record edit subroutine. Once a Title that does not exist is entered, the record is added using the PUT statement (line 2570).

Lines 5040-5060 search for a record using the key. Once a record is located, it can be edited or deleted. Lines 5300-5400 edit an existing record in the file. As in the case of adding a record, the data for the record is put in the variable editRecord. In this case, we make a copy of the record by using the copy assignment operator (line 5310). We do this because we need to compare the edited record against the original Title to see if the user changed the key. If the Title is changed, then the new Title is searched to see if it already exists, just like we did when adding records (lines 5340-5370). If the new Title does not exist, then the old record is deleted from the file using the original record frame in a DEL statement, and the new record is added. If the Title was not changed, all those lines are skipped and the record is replaced by the PUT statement in line 5390.

Lines 5500-5520 delete the found record. The remaining block of code in lines 7500-7560 sequentially accesses each record in the file and prints it.

To review, the GET statement can be used to find a record using a key value, and to access the next record in the file. You use the variable FSTAT to see what happened:

• When it is set to zero an exact match was found.
• When it is set to one, the end of the file was reached, and no match was found.
• When it is set to two, the key was not found, but the next greater key was located.

NEXT TIME
Next time I explore NS BASIC 3.0, including the new Widgets. Since I haven't talked about using Widgets yet, it will be a good time to go over their use in all versions of NS BASIC.