Using Xbasic to Read and Write to a Table

Script or Function?

Perhaps the first question you will ask is: "Should this be a script or a function?". There is little difference in the Xbasic coding between the two alternatives. The determining issue is whether you want to return a value. Functions can return values. Scripts cannot return values, except by setting the value(s) of global variable(s), and this is often considered a sloppy and potentially troublesome programming practice.

How Do I Call a Script or Function?

Calling a function is as easy as naming it and catching the return value, if any. This example returns a value from the find_last_name()function:

dim return_value as C
... some code
return_value = find_last_name()
... some code

Or, if the find_last_name()function required a parameter, you might write something like this:

dim return_value as C
... some code
return_value = find_last_name("Michael")
... some code

If the find_last_name()function did not return a value, the syntax would simply be:

... some code
find_last_name()
... some code

Calling a script named find_first_nameis just as easy:

... some code
script_play("find_first_name")
... some code

Sequencing Through the Records of a Table

The following is the beginning of a scriptthat reads and writes to the customertable. This script does not require that the customertable be open in a layout. First, create a table object named tbl(any variable namethat is not a reserved wordwill do).

dim tbl as P
tbl = table.open("customer")

Now read the first record.

tbl.fetch_first()
while .not. table.fetch_eof()
    ' ... do something
    tbl.fetch_next()
end while
tbl.close()

Keep reading until you reach the end of the file.

tbl.fetch_first()
while .not. table.fetch_eof()
    ' ... do something
    tbl.fetch_next()
end while

Now, close the table.

tbl.close()

Reading a Field Value

Reading a field value is as simple as referencing table_object.field_name. In the following script the variable lnalways contains the value of the lastnamefield in the current record:

dim tbl as P
dim ln as C
tbl = table.open("customer")
tbl.fetch_first()
while .not. table.fetch_eof()
    ln = tbl.lastname
    tbl.fetch_next()
end while
tbl.close()

Writing a Field Value

Writing a changed field value in a record requires two more statements. Suppose you wanted to make sure that the lastnamefield had an initial capital letter.

dim tbl as P
dim ln as C
tbl = table.open("customer")
tbl.fetch_first()
while .not. table.fetch_eof()

The tbl.change_begin(.t.)statement says that you are changing an existing field and that you want to honor any existing field rules.

tbl.change_begin(.t.)
    tbl.lastname = f_upper(tbl.lastname)

The tbl.change_end(.t.)statement says that you are finished changing an existing field and want to save the changes.

tbl.change_end(.t.)
tbl.fetch_next()
end while
tbl.close()

Deleting a Record

The process of deleting a record is similar to changing a record. First, you need to use one of many techniques for finding the record you are going to delete.

dim tbl as P
dim ln as C
tbl = table.open("customer")
tbl.fetch_first()
while .not. table.fetch_eof()

This script tests the values of the firstnameand lastnamefields, and only deletes specific records.

if (tbl.lastname = "Smith") .and. (tbl.firstname = "John") then
        tbl.change_begin(.t.)
        tbl.delete()

The tbl.change_end(.t.)statement says that you are want to delete the record.

tbl.change_end(.t.)
    end if
    tbl.fetch_next()
end while
tbl.close()

Adding a Record

Adding a record is simple. You bracket your field updates with the tbl.enter_begin()and tbl.enter_end()statements.

dim tbl as P
tbl = table.open("customer")
tbl.enter_begin()

The tbl.enter_begin(.t.)statement says that you are adding a existing field to the end of the table and that you want to honor any existing field rules.

tbl.firstname = "George"
tbl.lastname = "Washington"

The tbl.enter_end(.t.)statement says that you are finished adding a record and want to save the changes.

tbl.enter_end(.t.)
tbl.close()

Selecting a Subset of Records with a Query

In each of the examples above, the code opened the customer table and sequenced through all of its records. Suppose you wanted only to sequence through the records when the bill_state_regionfield contained the value "MA". Instead of writing this code at the beginning of the script:

dim tbl as P
tbl = table.open("customer")

you would write:

dim tbl as P
dim qry as P
tbl = table.open("customer")
query.filter = "bill_state_region = 'MA'"
qry = tbl.query_create()
... add, change, or delete ...

Finish the script or function by detaching the query and closing the table.

tbl.query_detach()
tbl.close()

Now, you will sequence through only those customers in the state of Massachusetts. See Also: Table Functions and Methods, Overview: Functions and Expressions