Tutorial 06: Reading and Writing data

March 25, 2009

© NSB Corporation. All rights reserved.

Contributed by Chris Kenworthy

1. Introduction

This tutorial will demonstrate how to use NSBasic a program that will store data in a persistent file and retrieve it.

For this exercise, the data that our program will store is the name of a user. The first time the program runs, it will say that it doesn't remember any name, but after the user has entered a name, it will greet them by name when they come back.

2. Getting started

Start with a new project file.
Call it HelloYou, by setting the (Name) property in the Project Properties window.
Save your project at this point using CTRL+S or the File menu in the top left corner of the NS Basic IDE window.
Go to the project Startup code by right-clicking on the project name (HelloYou) in the Project Explorer window and selecting "View Startup Code" or picking "Startup Code" from the Project menu.

3. Creating and opening a file

Now, enter the following code, right after "Sub Project_Startup()":

    Global myDB as Database    
    Dim iResult as Integer    
    iResult = dbOpen (myDB, "whoisit", 0)    
    If iResult = 519 Then ' DB not found    
        iResult = dbCreate (myDB, "whoisit", 0, "Test") 
        
        If iresult <> 0 Then
            MsgBox "dbcreate error " + str(iResult) + " in whoisit"            
        Else
            iResult = dbOpen (myDB, "whoisit", 0)            
            If iResult <> 0 Then
                MsgBox "dbopen error " + str(iResult) + " in whoisit"
            End If
        End If  
        
    ElseIf iResult <> 0 Then
        MsgBox "dbopen error " + str(iResult) + " in whoisit"    
    End If

This code does a lot of important things that we'll need for reading and writing data. First, it declares a global variable for our file operations, myDB. A file variable represents one file on the device, which is all that we'll need for our program. (More complicated programs might involve many files, and many variables.) Then we attempt to open the file named 'whoisit' with our myDB file reference.

If there's any problem with opening the file, then the error trapping code is triggered. First off, we need to pay particular attention to the "DB not found" error code, which is a result of 519, because that suggests that this may be the first time our program was run on this device. In that case, we attempt to make a fresh file with dbcreate. If there is any unexpected error in creating the file, opening it after creating it, or any open error code that is not DB-not-found, we output the error message using a msgbox command.

4. Reading String data

We're almost ready to start reading from the file, but first we need to put a label onto our project's form. Do this by switching back to the form in the Project Explorer, clicking on the Label icon in the toolbox, then up in the top right corner of your form. Left click on the label and change its name to lblHello, and enter enough label text to make the label stretch all the way across the form.

Right click on the form, and pick 'View Before Code'. Enter the following lines for the form_before sub:

    Dim iResult as Integer, k as Integer, strName as String   
    k = 1    
    iResult = dbread (myDB, k, strName)    
    If iResult = 2 Or iResult = 1 Then
    	lblHello.text = "I'm sorry, I don't remember you."
    	
    ElseIf iResult <> 0 Then
    	MsgBox "dbread error " + str(iResult) + " in whoisit"
    	lblHello.Text = "dbread error " + str(iResult) + " in whoisit"
    	
    Else
    	lblHello.Text = "Welcome back, " + strName

    End If

After declaring the variables we need, we use the dbread routine to search for a record in the file with a key of 1. This will hold any name that has been written into the file. If the result code is 1 or 2, then we assume that the record was not found. (2 is a 'record not found, skipped to next record after', however, if there are no records after record key 1, then the return code will be 1, 'operation failed.' A brief description of these error codes are in the manual under dbopen, but sometimes you need to experiment for yourself.)

Then the proper message, for name found, name not found, and unexpected error are displayed.

At this point, if you compile the program and run it on a device, it should run correctly and show the "I don't remember you" message. To actually read any true data, we will have to write it into the file.

5. Writing string data

As with reading, to write a name into our file, we'll need to add some controls to the form. A field and a button control are necessary, along with another label to provide a cue to the user. Call the field txtName, and the button btnSave. The form should look something like this once you've added them:

Now double click on btnSave. Enter the following lines for its sub:

    Dim strName as String, iResult as Integer, k as Integer
    k = 1
    If txtName.Text = "" Then
        MsgBox "You must enter a name to save!"
        Exit Sub
    End If
			
    iResult = dbread (myDB, k, strName)  
    strName = txtName.Text
    
    If iResult = 2 Or iResult = 1 Then
    	iResult = dbInsert (myDB, k, strName)    
    	If iResult <> 0 Then    	
    		MsgBox "dbinsert error " + str(iResult) + " in whoisit"   		
    	End If    	
    Else   
    	iResult = dbUpdate (myDB, k, strName)   	
    	If iResult <> 0 Then    	
    		MsgBox "dbupdate error " + str(iResult) + " in whoisit" 		
    	End If
    End If
    
    If iResult = 0 Then
    	MsgBox "I will remember that name."
    End If

First, we validate the text field to make sure that the user has entered something. We could have validated that the name wasn't too long, that it didn't just consist of numbers, etcetera at this point if we wanted to.

Then, we attempt to read a name from the file, to determine if we need to use a dbinsert command, to write a new record, or a dbupdate command to change an existing record. Finally, we make the change, and check for any file errors.

At this point, you should be able to tell the program your name and have it greet you next time, kind of like this:

6. Working with number data

Now, our program will read and write data, but only of a string type. Let's try adding simple numeric data to the file - a second field, with key value 2, that will hold the user's age.

Again, we'll need to add some form controls for this - a textbox and button for saving ages, (txtAge and btnSaveAge,) a button for reading ages. (btnReadAge)

Now, add the following code for the new buttons, (by double-clicking on the buttons.) For btnSaveAge:

    Dim age as Integer, iResult as Integer, k as Integer
    k = 2
    If txtAge.Text = "" Then
        MsgBox "You must enter an age to save!"
        Exit Sub
    End If
		
    If testnum(txtAge.Text, "", 3, 0) <> 0 Then
        MsgBox "You must use a numeric age to save!"
        Exit Sub
    End If

    iResult = dbread (myDB, k, age)
    age = val(txtAge.Text)    
    If iResult = 2 Or iResult = 1 Then
    	iResult = dbInsert (myDB, k, age)    
    	If iResult <> 0 Then    	
    		MsgBox "dbinsert error " + str(iResult) + " in whoisit"    		
    	End If    	
    Else    
    	iResult = dbUpdate (myDB, k, age)    	
    	If iResult <> 0 Then    	
    		MsgBox "dbupdate error " + str(iResult) + " in whoisit"    		
    	End If    
    End If
    
    If iResult = 0 Then
    	MsgBox "I will remember that."
    End If

And, for txtReadAge:

    Dim iResult as Integer, k as Integer, age as Integer, strAge as String    
    k = 2    
    iResult = dbread (myDB, k, age)    
    If iResult = 2 Or iResult = 1 Then
    	MsgBox "I'm sorry, I don't remember your age."    	
    ElseIf iResult <> 0 Then
    	MsgBox "dbread error " + str(iResult) + " in whoisit"    	
    Else
    	strAge = str(age + 1)    	
    	MsgBox "When's your " + strAge + "th birthday?"
    End If

Have fun with your data!