|
For each table whose state is being preserved, UltraLite stores a name for the table as well as enough information to restore the state of the table. The name associated with the table may be, but is not required to be, the name of the table. It is called the persistent name.
UltraLite applications can open more than one instance of the same table at the same time. In this case, the table name is not unique. For example, the following code (using MobileVB) opens the same table twice:
' MobileVB Set table1 = Connection.GetTable( "ULCustomer" ) table1.Open "", "customer1" ' operations here Set table2 = Connection.GetTable( "ULCustomer" ) table2.Open "", "customer2"
When opening a table, an application can optionally provide a persistent name as a parameter. If the state of the persistent name has been saved, 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 open tables and close the connection. If it does not close an open table, 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.
'MobileVB using VB6 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 is 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 associates 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 computer.