Sequence of Steps for a Java Application
The following sequence of steps are typical of an application or applet. The first two steps are the same for both tightly coupled and for loosely coupled databases:
1
Establish an instance of Session that is used as the execution environment. (A Driver object does not have to be instantiated because Driver is a static class.) It is also possible for an application/applet to create multiple sessions.
2
Get a Database object for the database by invoking Session.connectToDatabase() specifying a URI. See PSQL Programmer's Guide for more information on database URIs. It is also possible to get multiple Database objects in a session, one for each database to be accessed.
Now choose either Case 1: The application is accessing tables of a tightly coupled database. (Btrieve database uses a DDF) or Case 2: The application is accessing data files of a loosely coupled database (or data files that store tables of a tightly coupled database in the "classic" way).
Case 1: The application is accessing tables of a tightly coupled database.
3
Optionally, get the names of tables in the database (if they are not known for the application) by invoking Database.getTableNames.
4
Get a Table object for each table to be worked on by invoking Database.getTable.
5
Optionally, get a TableMetaData object for each table if the application has to get the column names and/or index names from the dictionary.
6
Create at least one RowSet object for each table to be processed in the application. RowSet objects are used to retrieve and modify data. A row set can be created including all or none of columns of the table (see more in step 7).
An application creates more than one RowSet for a table if it wants to process the table in some parallel fashion while maintaining multiple currencies (positioning) when navigating through the table. A RowSet object for a given table can be used for the entire duration of the application. That is, it can be used for retrievals by different indexes, by different conditions, and so forth.
7
For a given row set
a.
Get a RowSetMetaData object for the row set.
b.
Add needed columns to the definition if the row set was created with no columns included.
c.
Change the default characteristics (direction, access path, and so forth) of the row set if necessary.
d.
Define a selection criterion (addFirstTerm, addAndTerm, etc) if a row set should include only some selected rows of the base table.
e.
Invoke RowSet.getNext method to retrieve Row objects. Optionally, invoke other methods of RowSet (getByIndex, getbyPercent, insertRow, updateRow, and so forth).
f.
Invoke methods of Row (getString, setString, getInt, and so forth) to get/set values of columns in a row.
*Note: Steps a) through d) are optional and depending on the application, they might not be needed for some row sets.
Case 2: The application is accessing data files of a loosely coupled database (or data files that store tables of a tightly coupled database in the "classic" way).
3.
Create an SCursor or an XCursor object for each data file the application plans to work on. XCursor is needed only if any extended get/step operation will be executed on the file. Optionally, the application can get multiple cursor objects for the same file if it wants to process the file in some parallel fashion maintaining multiple positions at the same time.
4
Execute “classic” Btrieve operations (open, get/step, insert, etc) using SCursor.BTRV.
*Note: The BTRV method can be used also on XCursor because XCursor extends SCursor.
5
Optionally, define some FieldDef objects for data fields, use these field objects to set selection criterion (XCursor.addFirstTerm, etc) and define extraction list and use the methods like getNextExtended to execute extended operations.
6
Invoke methods like getDString, setKString, getDInt4, and so forth, to get/set values of fields in the private data and key buffers of SCursor (XCursor) objects.
The sections that follow explain these overview steps in more detail.