ULConnectionParms class

UL Ext: Builds a connection string for opening a connection to an UltraLite database.

Visual Basic syntax

Public Class ULConnectionParms Inherits System.ComponentModel.Component

C# syntax

public class ULConnectionParms : System.ComponentModel.Component

Members

All members of ULConnectionParms class, including all inherited members.

Name	Description
ULConnectionParms constructor	Initializes a ULConnectionParms instance with its default values.
Dispose method (Inherited from System.ComponentModel.Component)	Releases all resources used by the System.ComponentModel.Component.
Finalize method (Inherited from System.ComponentModel.Component)	Releases unmanaged resources and performs other cleanup operations before the System.ComponentModel.Component is reclaimed by garbage collection.
GetService method (Inherited from System.ComponentModel.Component)	Returns an object that represents a service provided by the System.ComponentModel.Component or by its System.ComponentModel.Container.
ToString method	Returns the string representation of this instance.
AdditionalParms property	Specifies additional parameters as a semicolon-separated list of name=value pairs.
CacheSize property	Specifies the size of the cache.
CanRaiseEvents property (Inherited from System.ComponentModel.Component)	Gets a value indicating whether the component can raise an event.
ConnectionName property	Specifies a name for the connection.
Container property (Inherited from System.ComponentModel.Component)	Gets the System.ComponentModel.IContainer that contains the System.ComponentModel.Component.
DatabaseOnDesktop property	Specifies the path and file name of the UltraLite database on Windows desktop platforms.
DatabaseOnDevice property	Specifies the path and file name of the UltraLite database on Windows Mobile.
DesignMode property (Inherited from System.ComponentModel.Component)	Gets a value that indicates whether the System.ComponentModel.Component is currently in design mode.
EncryptionKey property	Specifies a key for encrypting the database.
Disposed (Inherited from System.ComponentModel.Component) Gets the list of event handlers that are attached to this System.ComponentModel.Component. Events property (Inherited from System.ComponentModel.Component)	Occurs when the component is disposed by a call to the System.ComponentModel.Component.Dispose method.
Password property	Specifies the password for the authenticated user.
Site property (Inherited from System.ComponentModel.Component)	Gets or sets the System.ComponentModel.ISite of the System.ComponentModel.Component.
UserID property	Specifies an authenticated user for the database.

Remarks

The frequently-used connection parameters are individual properties on the ULConnectionParms object.

A ULConnectionParms object is used to specify the parameters for opening a connection (with the ULConnection.Open method) or dropping a database (with the ULDatabaseManager.DropDatabase method).

Leading and trailing spaces are ignored in all values. Values must not contain leading or trailing spaces, or a semicolon, or begin with either a single quote or a double quote.

When building a connection string, you need to identify the database and specify any optional connection settings. Once you have supplied all the connection parameters by setting the appropriate properties on a ULConnectionParms object, you create a connection string using the ULConnectionParms.ToString method. The resulting string is used to create a new ULConnection object with the ULConnection(String) constructor or set the ULConnection.ConnectionString property of an existing ULConnection object.

Identifying the database

Each instance contains platform-specific paths to the database. Only the value corresponding to the executing platform is used. For example, in the code below the path \UltraLite\mydb1.udb would be used on Windows Mobile, while mydb2.db would be used on other platforms.

' Visual Basic
Dim dbName As ULConnectionParms = new ULConnectionParms
dbName.DatabaseOnDevice = "\UltraLite\mydb1.udb"
dbName.DatabaseOnDesktop = "somedir\mydb2.udb"

The following code is the C# language equivalent:

// C#
ULConnectionParms dbName = new ULConnectionParms();
dbName.DatabaseOnDevice = "\\UltraLite\\mydb1.udb";
dbName.DatabaseOnDesktop = "somedir\mydb2.udb";

The recommended extension for UltraLite database files is .udb. On Windows Mobile devices, the default database is \UltraLiteDB\ulstore.udb. On other Windows platforms, the default database is ulstore.udb. In C#, you must escape any backslash characters in paths or use @-quoted string literals.

If you are using multiple databases, you must specify a database name for each database.

Optional connection settings

Depending on your application's needs and how the database was created, you might need to supply a non-default ULConnectionParms.UserID value, a non-default ULConnectionParms.Password value, a database ULConnectionParms.EncryptionKey value, and the ULConnectionParms.CacheSize value. If your application is using multiple connections, you should provide a unique ULConnectionParms.ConnectionName value for each connection.

Databases are created with a single authenticated user, DBA, whose initial password is sql. By default, connections are opened using the user ID DBA and password sql. To disable the default user, use the ULConnection.RevokeConnectFrom method. To add a user or change a user's password, use the ULConnection.GrantConnectTo method.

If an encryption key was supplied when the database was created, all subsequent connections to the database must use the same encryption key. To change a database's encryption key, use the ULConnection.ChangeEncryptionKey method.