UltraLite for MobileVB User's Guide
Understanding UltraLite for MobileVB Development
Maintaining database state on Palm OS
When a request is made to open a table, the user can pass in a persistent name. UltraLite looks up the persistent name in the state PDB to see if there is a table associated with it. If so, the table is opened and positioned to the proper row. If not, the table is opened and positioned before the first row.
When an application terminates, it may or may not explicitly close the UltraLite connection and all open tables. If it does not, then UltraLite records the current row of each open table that was supplied with a persistent name. Tables without a persistent name are closed.
Suppose the Connection object is of type ULConnection and a table called ULCustomer exists in the database.
Dim table As ULTable Set table = Connection.GetTable( "ULCustomer" ) table.Open "", "customer"
The second line of code gets the table object representing the ULCustomer table. The table has not been opened for reading or writing yet.
In the Open call (the third line of code), the first parameter is the empty string, which indicates that the data will be ordered by the primary key. The second parameter is the persistent name being assigned to the table. If the application terminates while this table is still open, the state PDB will associate customer with the ULCustomer table and save the current position.
If the persistent name is empty, UltraLite does not store state information for this table, or attempt to look it up when opening the table.
If you do not need to store the state of your tables, supply an empty persistent name. The state is then not looked up in the state database.
HotSync synchronization does not affect the state of your open tables. When a user presses the HotSync button on a device, the operating system closes the application in the same way it closes the application when any other application is started. Consequently, the state of the open tables is recorded in the state PDB and when the user returns to the application and the tables are re-opened, the user is positioned on the expected row. If that row has been deleted as part of the synchronization, the user is positioned on the next row (or after the last row if it was the last row).
Applications with auto-commit turned off could terminate with uncommitted transactions. UltraLite maintains these transactions so that when the application restarts, they are not lost.
If UltraLite finds a table in the state PDB that matches the persistent name you have provided, it checks that the table and index are the same as the table and index used when the position information was recorded. If they are not, then the call to Open fails.
The use of the persistent name is unique to the Palm OS. If you create UltraLite for MobileVB applications for Windows CE, they do not use the persistent name. Applications on Windows CE run more like they do on a desktop machine.
It is possible with UltraLite to have the same table open multiple times and at the same time in your application. In this case, the table name is not unique enough to store in the state PDB. In an application that does this, the code would look something like the following:
Set table1 = Connection.GetTable( "ULCustomer" ) table1.Open "", "customer1" // operations here Set table2 = Connection.GetTable( "ULCustomer" ) table2.Open "", "customer2"