UltraLite connection strings and parameters

A connection string is a set of connection parameters that is passed from an application so that a database connection can be defined and established. Some parameters are always required to open a connection while others are used to adjust database features for a single connection.

Connection strings are defined as keyword=value pairs in a semicolon delimited list. The following example illustrates a connection string fragment that specifies a database file name, user ID, and password:

DBF=myULdb.udb;UID=JDoe;PWD=token

Methods of supplying these parameters to a database can vary depending on whether you are connecting from an UltraLite utility or an UltraLite application.

UltraLite command line utilities typically use a connection string if a connection to a database is required.

UltraLite applications can be developed using an UltraLite API to read connection parameter values from a stored file or in the application code. You can supply fixed connection strings when user authentication is not required, or prompt users to supply parameter values at connection time.

When a connection string has been assembled, it is passed to the UltraLite runtime for processing. The connection to the database is granted when the connection attempt is validated. Connection failures can occur if the database file does not exist, or the authentication was not successful.

UltraLite generates an error when it encounters an unrecognized connection parameter.

Precedence of connection parameters for UltraLite administration tools

UltraLite administration tools follow a specific order of connection parameter precedence:

OS-specific options take precedence over nonspecific options. For example: CE_DBF takes precedence over DBF on Windows CE devices.
If specified, the CE_FILE, desktop, device, and NT_FILE parameters always take precedence over DBF.
If you supply duplicate parameters in a connection string, the last one supplied is used. All others are ignored.
Parameters in the connection string take precedence over those supplied in the ULSQLCONNECT environment variable or a connection object.
If no value is supplied for both UID and PWD in either the connection string or ULSQLCONNECT, the defaults of UID=DBA and PWD=sql are assumed.

Limitations

Example

You can type a connection string on a single line with the parameter names and values separated by semicolons:

parameter1=value1;parameter2=value2

The UltraLite runtime ensures that the parameters are assembled into a connection string before establishing a connection with it. For example, if you use the ulload utility, the following connection string is used to load new XML data into an existing database. You cannot connect to the database file until you supply this string:

ulload -c "DBF=sample.udb;UID=DBA;PWD=sql" sample.xml

Discuss this page in DocCommentXchange.