UltraLite User's Guide
UltraLite Reference
Macros and compiler directives for UltraLite C/C++ applications
Supply a set of keyword-value pairs to configure database storage.
#define UL_STORE_PARMS UL_TEXT( "keyword=value;..." )
All spaces in the keyword-value list are significant, except spaces at the start of the string and any spaces that immediately follow a semicolon.
Define the UL_STORE_PARMS macro in the header of your application source code so that it is visible to all db_init() calls.
Keywords are case insensitive. The case sensitivity of the values depends on the application interpreting it. For example, the case sensitivity of the filename depends on the operating system.
cache_size Defines the size of the cache. You can specify the size in units of bytes. Use the suffix k or K to indicate units of kilobytes and use the suffix M or m to indicate megabytes. For example, the following string sets the cache size to 128 kb.
#define UL_STORE_PARMS UL_TEXT("cache_size=128k")The default cache size is sixteen pages. Using the default page size of 4 K, the default cache size is therefore 64 K. The minimum cache size is platform dependent.
The default cache size is conservative. If your testing shows the need for better performance, you should increase the cache size.
Increasing the caches size beyond the size of the database itself provides no performance improvement. Also, large cache sizes may interfere with the number of other applications you can use.
On the Palm Computing Platform, the parameter applies only to virtual file system (VFS) databases. The cache itself resides in record storage, not VFS storage.
file_name Defines the full pathname of the file-based persistent store. No substitutions are performed on this value. In addition, you must ensure that this directory exists when db_init is called. The directory is not created automatically.
#define UL_STORE_PARMS
UL_TEXT("file_name=\\uldb\\my own name.udb" )Under Windows CE, the filename must include the absolute path. Under other Windows operating systems, the path may either be absolute, or relative to the current directory.
An alias for this parameter is DBF.
You must escape any backslash characters in the path.
This parameter does not apply to the Palm Computing Platform.
key Define an encryption key for strong encryption of the database store.
An alias for this parameter is DBKey.
For more information, see Encrypting UltraLite databases.
page_size UltraLite databases are stored in pages. I/O operations are carried out a page at a time. The default page size for UltraLite databases is 4kb. You can specify 2 kb pages using the following storage parameters string:
#define UL_STORE_PARMS UL_TEXT("page_size=2k")This parameter is ignored when starting an existing database. It can be used on any C/C++ target platform. Setting a page size of 2 kb reduces the maximum number of tables to approximately 500.
palm_allow_backup If the backup bit is set on the UltraLite database, and if this parameter is set to yes, the entire Palm database is backed up every time the device is synchronized using HotSync. If this parameter is not set, UltraLite ensures that the backup bit is cleared.
In most applications, data is backed up by synchronization, so there is no need to set this parameter.
The backup bit is set when a database file is deployed by HotSync, and can also be set by the ULUtil utility. For more information, see The UltraLite utility.
The following string sets the parameter.
#define UL_STORE_PARMS UL_TEXT("palm_allow_backup=yes")reserve_size Reserves file system space for storage of UltraLite persistent data.
The reserve_size parameter allows you to pre-allocate the file system space required for your UltraLite database without actually inserting any data. Reserving file system space can improve performance slightly and also prevent out of memory failures. By default, the persistent storage file only grows when required as the application updates the database.
Note that reserve_size reserves file system space, which includes the metadata in the persistent store file, and not just the raw data. The metadata overhead as well as data compression must be considered when deriving the required file system space from the amount of database data. Running the database with test data and observing the persistent store file size is recommended.
The reserve_size parameter reserves space by growing the persistent store file to the given reserve size on startup, regardless of whether the file previously existed. The file is never truncated.
Use the reserve_size parameter to pre-allocate space as follows:
#define UL_STORE_PARMS UL_TEXT( "reserve_size=2m" )
This example ensures that the persistent store file is at least 2 Mb upon startup.
This parameter does not apply to the Palm Computing Platform unless the application uses the Virtual File System (VFS).
The following statements set the cache size to 128 kb.
#undef UL_STORE_PARMS
#define UL_STORE_PARMS UL_TEXT("cache_size=128k")
. . .
db_init( &sqlca );You can set UL_STORE_PARMS to a string, then set the value of that string programmatically before calling db_init, as in the following example. The UL_TEXT macro and the _stprintf function are used to achieve proper character encoding.
char store_parms[32];
#undef UL_STORE_PARMS
#define UL_STORE_PARMS store_parms
. . .
/* Set cache_size to the correct number of bytes. */
. . .
_stprintf( store_parms, UL_TEXT("cache_size=%lu"),
cache_size );
db_init( &sqlca );Configuring and managing database storage
Encrypting UltraLite databases