PUBLIC

SQL Anywhere - UltraLite

Document Version: 17 – 2019-03-21

UltraLite - .NET API Reference

© 2019 SAP SE or an SAP affiliate company. All rights reserved.

THE BEST RUN

Content

1 System requirements and supported platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 UltraLite.NET application development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.1 SQL Anywhere tools in Microsoft Visual Studio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 Connection setup for an UltraLite database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Connecting to an UltraLite database using UltraLite.NET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 Data creation and modification in UltraLite.NET using SQL statements. . . . . . . . . . . . . . . . . . . . . . . 9
Data modification in UltraLite.NET using INSERT, UPDATE, and DELETE. . . . . . . . . . . . . . . . . . . 10
Retrieving data in UltraLite.NET using SELECT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Result set schema description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
SQL result set navigation in UltraLite.NET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.4 Data creation and modification in UltraLite.NET using the ULTable class. . . . . . . . . . . . . . . . . . . . . . 14
Row navigation in UltraLite.NET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
UltraLite modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Row insertion in UltraLite.NET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Row updates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Row searches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Row retrieval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Row deletions in UltraLite.NET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
2.5 Transaction management in UltraLite.NET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.6 Schema information in UltraLite.NET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.7 Error handling in UltraLite.NET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
2.8 MobiLink data synchronization in UltraLite.NET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Synchronization initiation in a C# application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Microsoft ActiveSync synchronization setup in UltraLite.NET. . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.9 How to deploy UltraLite.NET applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Deploying an UltraLite.NET application for Microsoft Windows Mobile. . . . . . . . . . . . . . . . . . . . .25
Deploying an UltraLite.NET application for Windows Mobile (UltraLite engine). . . . . . . . . . . . . . . 27

3 Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET. . . . . . . . . . . . 29

3.1 Lesson 1: Creating a Microsoft Visual Studio project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.2 Lesson 2: Creating an UltraLite database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.3 Lesson 3: Adding database connection controls to the application. . . . . . . . . . . . . . . . . . . . . . . . . .35
3.4 Lesson 4: Inserting, updating, and deleting data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
3.5 Lesson 5: Building and deploying the application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.6 Code listing for C# tutorial. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
3.7 Code listing for Microsoft Visual Basic tutorial. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

UltraLite - .NET API Reference

2 PUBLIC Content
4 UltraLite .NET API reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.1 UltraLite .NET API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
ULActiveSyncListener interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
ULBulkCopy class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
ULBulkCopyColumnMapping class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
ULBulkCopyColumnMappingCollection class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
ULCommand class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
ULCommandBuilder class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
ULConnection class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
ULConnectionParms class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
ULConnectionStringBuilder class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
ULCreateParms class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
ULCursorSchema class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
ULDataAdapter class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
ULDatabaseManager class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
ULDatabaseSchema class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
ULDataReader class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302
ULException class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
ULFactory class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
ULFileTransfer class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
ULFileTransferProgressData class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
ULFileTransferProgressListener interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .386
ULIndexSchema class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
ULInfoMessageEventArgs class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .398
ULMetaDataCollectionNames class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
ULParameter class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
ULParameterCollection class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
ULResultSet class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
ULResultSetSchema class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
ULRowsCopiedEventArgs class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
ULRowUpdatedEventArgs class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
ULRowUpdatingEventArgs class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
ULServerSyncListener interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
ULSqlProgressData class (Deprecated). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
ULSyncParms class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
ULSyncProgressData class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
ULSyncProgressListener interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
ULSyncResult class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
ULTable class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
ULTableSchema class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .578
ULTransaction class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598

UltraLite - .NET API Reference

Content PUBLIC 3
 ULInfoMessageEventHandler(object, ULInfoMessageEventArgs) delegate. . . . . . . . . . . . . . . . 603
ULRowsCopiedEventHandler(object, ULRowsCopiedEventArgs) delegate. . . . . . . . . . . . . . . . . 604
ULRowUpdatedEventHandler(object, ULRowUpdatedEventArgs) delegate. . . . . . . . . . . . . . . . 604
ULRowUpdatingEventHandler(object, ULRowUpdatingEventArgs) delegate. . . . . . . . . . . . . . . 605
ULSyncProgressedDlg(IAsyncResult, ULSyncProgressData) delegate. . . . . . . . . . . . . . . . . . . 606
ULAuthStatusCode enumeration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
ULBulkCopyOptions enumeration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
ULDateOrder enumeration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
ULDbType enumeration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
ULDBValid enumeration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612
ULRuntimeType enumeration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
ULSqlProgressState enumeration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
ULStreamType enumeration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
ULSyncProgressState enumeration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616

UltraLite - .NET API Reference

4 PUBLIC Content
1 System requirements and supported
platforms

UltraLite.NET supports Microsoft Windows Mobile devices. Third-party software is required for database
development.

Development platforms

To develop applications using UltraLite.NET, you must have the following:

● A supported desktop version of Microsoft Windows.

● Microsoft Visual Studio.

Target platforms

UltraLite.NET supports the following target platforms:

● Microsoft .NET Framework 2.0 or later for Microsoft Windows.

● Microsoft .NET Compact Framework 2.0 or later for Microsoft Windows Mobile.

UltraLite - .NET API Reference

System requirements and supported platforms PUBLIC 5
2 UltraLite.NET application development

The UltraLite.NET API provides the Sap.Data.UltraLite namespace. This namespace provides a Microsoft
ADO.NET interface to UltraLite. It has the advantage of being built on an industry-standard model and
providing a migration path to the SQL Anywhere ADO.NET interface, which is very similar.

The .NET Compact Framework is the Microsoft .NET runtime component for Microsoft Windows Mobile. It
supports several programming languages. You can use either Visual Basic.NET or C# to build applications
using UltraLite.NET.

 Note

You can use the UltraLite C++ API as an alternative to the UltraLite.NET API to create applications for
Microsoft Windows Mobile devices and desktop.

In this section:

SQL Anywhere tools in Microsoft Visual Studio [page 7]

Microsoft Visual Studio integration is supported for UltraLite.NET. You can access the SQL Anywhere
integration tools from the Microsoft Visual Studio Server Explorer in Microsoft Visual Studio 2005 or
later.

Connection setup for an UltraLite database [page 7]

UltraLite applications must connect to a database before carrying out operations on the data in it.

Data creation and modification in UltraLite.NET using SQL statements [page 9]

UltraLite applications can access table data using SQL statements or the Table API.

Data creation and modification in UltraLite.NET using the ULTable class [page 14]
UltraLite applications can access table data using SQL statements or by using the ULTable class.

Transaction management in UltraLite.NET [page 21]

UltraLite provides transaction processing to ensure the integrity of the data in your database. A
transaction is a logical unit of work. Either an entire transaction is executed, or none of the statements
in the transaction are executed.

Schema information in UltraLite.NET [page 22]

The objects in the table API represent tables, columns, indexes, and synchronization publications. Each
object has a Schema property that provides access to information about the structure of that object.

Error handling in UltraLite.NET [page 23]

You can use the standard .NET error-handling features to handle errors. Most UltraLite methods throw
ULException errors.

MobiLink data synchronization in UltraLite.NET [page 23]

You synchronize an UltraLite database with a central consolidated database. Synchronization requires
the MobiLink synchronization software included with SQL Anywhere.

How to deploy UltraLite.NET applications [page 25]

UltraLite.NET applications can be deployed to Microsoft Windows Mobile and Microsoft Windows. If you
are deploying to Microsoft Windows Mobile, UltraLite.NET requires the Microsoft .NET Compact

UltraLite - .NET API Reference

6 PUBLIC UltraLite.NET application development
 Framework. If you are deploying to Microsoft Windows, it requires the Microsoft .NET Framework.
UltraLite.NET also supports Microsoft ActiveSync synchronization.

2.1 SQL Anywhere tools in Microsoft Visual Studio

Microsoft Visual Studio integration is supported for UltraLite.NET. You can access the SQL Anywhere
integration tools from the Microsoft Visual Studio Server Explorer in Microsoft Visual Studio 2005 or later.

2.2 Connection setup for an UltraLite database

UltraLite applications must connect to a database before carrying out operations on the data in it.

 Note

The code samples in this chapter are written in Microsoft C#. If you are using one of the other supported
development tools, you must modify the instructions appropriately.

Using the ULConnection object

Most applications use a single connection to an UltraLite database and leave the connection open. Multiple
connections are only required for multithreaded data access. For this reason, it is often best to declare the
ULConnection object as global to the application.

The following properties of the ULConnection object govern global application behavior.

Commit behavior

By default, UltraLite.NET applications are in AutoCommit mode. Each Insert, Update, or Delete statement
is committed to the database immediately. You can use ULConnection.BeginTransaction to define the start
of a transaction in your application.
User authentication

You can change the user ID and password for the application from the default values of DBA and sql,
respectively, by using methods. Each UltraLite database can define a maximum of four user IDs.
Synchronization

A set of objects governing synchronization is accessed from the Connection object.

Tables

UltraLite tables are accessed using methods of the Connection object.

Commands

A set of objects is provided to handle the execution of dynamic SQL statements and to navigate result sets.

UltraLite - .NET API Reference

UltraLite.NET application development PUBLIC 7
Multithreaded applications

Each ULConnection object and all objects created from it should be used on a single thread. If your application
requires multiple threads accessing the UltraLite database, each thread requires a separate connection. For
example, if you design your application to perform synchronization in a separate thread, you must use a
separate connection for the synchronization and you must open the connection from that thread.

In this section:

Connecting to an UltraLite database using UltraLite.NET [page 8]

Use the ULConnectionParms object to connect to an UltraLite database named mydata.udb.

Related Information

Transaction management in UltraLite.NET [page 21]

MobiLink data synchronization in UltraLite.NET [page 23]
Data creation and modification in UltraLite.NET using the ULTable class [page 14]
Data creation and modification in UltraLite.NET using SQL statements [page 9]

2.2.1 Connecting to an UltraLite database using

UltraLite.NET

Use the ULConnectionParms object to connect to an UltraLite database named mydata.udb.

Procedure

1. Declare a ULConnection object.

ULConnection conn;

2. Open a connection to an existing database.

You can specify connection parameters either as a connection string or using the ULConnectionParms
object.

ULConnectionParms parms = new ULConnectionParms();

parms.DatabaseOnDesktop = "mydata.udb";
conn = new ULConnection( parms.ToString() );
conn.Open();

UltraLite - .NET API Reference

8 PUBLIC UltraLite.NET application development
Results

A connection to the mydata.udb database is established.

Next Steps

Use the database connection to perform SQL operations that create, modify, or delete data. You can modify
existing database options on an open connection. Close the ULConnection object when finished.

2.3 Data creation and modification in UltraLite.NET using

SQL statements

UltraLite applications can access table data using SQL statements or the Table API.

The following tasks can be performed using SQL statements:

● Inserting, deleting, and updating rows.

● Executing queries and retrieving rows to a result set.
● Scrolling through the rows of a result set.

In this section:

Data modification in UltraLite.NET using INSERT, UPDATE, and DELETE [page 10]
With UltraLite, you can perform SQL data manipulation language operations. These operations are
performed using the ULCommand.ExecuteNonQuery method.

Retrieving data in UltraLite.NET using SELECT [page 13]

Execute a SELECT statement to retrieve information from an UltraLite database and handle the result
set that is returned.

Result set schema description [page 13]

The ULDataReader.GetSchemaTable method and ULDataReader.Schema property allow you to retrieve
information about a result set, such as column names, total number of columns, column scales,
column sizes, and column SQL types.

SQL result set navigation in UltraLite.NET [page 14]

You can navigate through a result set using methods associated with the ULDataReader object.

Related Information

Data creation and modification in UltraLite.NET using the ULTable class [page 14]

UltraLite - .NET API Reference

UltraLite.NET application development PUBLIC 9
2.3.1 Data modification in UltraLite.NET using INSERT,
UPDATE, and DELETE

With UltraLite, you can perform SQL data manipulation language operations. These operations are performed
using the ULCommand.ExecuteNonQuery method.

In this section:

Inserting a row in a table using UltraLite.NET [page 10]

Placeholders for parameters in SQL statements are indicated by the ? character. For any INSERT,
UPDATE, or DELETE, each ? is referenced according to its ordinal position in the command's
parameters collection. For example, the first ? is referred to as 0, and the second as 1.

Updating a row in a table using UltraLite.NET [page 11]

Placeholders for parameters in SQL statements are indicated by the ? character. For any INSERT,
UPDATE, or DELETE, each ? is referenced according to its ordinal position in the command's
parameters collection. For example, the first ? is referred to as 0, and the second as 1.

Deleting a row in a table in UltraLite.NET [page 12]

Placeholders for parameters in SQL statements are indicated by the ? character. For any INSERT,
UPDATE, or DELETE, each ? is referenced according to its ordinal position in the command's
parameters collection. For example, the first ? is referred to as 0, and the second as 1.

2.3.1.1 Inserting a row in a table using UltraLite.NET

Placeholders for parameters in SQL statements are indicated by the ? character. For any INSERT, UPDATE, or
DELETE, each ? is referenced according to its ordinal position in the command's parameters collection. For
example, the first ? is referred to as 0, and the second as 1.

Procedure

1. Declare a ULCommand.

ULCommand cmd;

2. Assign a SQL statement to the ULCommand object.

cmd = conn.CreateCommand();
cmd.CommandText = "INSERT INTO MyTable(MyColumn) values (?)";

3. Assign input parameter values for the statement.

The following code shows a string parameter.

String newValue;
cmd.Parameters.Clear();
// assign value
cmd.Parameters.Add("", newValue);

UltraLite - .NET API Reference

10 PUBLIC UltraLite.NET application development
4. Execute the statement.

The return value indicates the number of rows affected by the statement.

int rowsInserted = cmd.ExecuteNonQuery();

5. If you are using explicit transactions, commit the change.

myTransaction.Commit();

Results

A new row is added to MyTable where the MyColumn value is set to an empty string.

2.3.1.2 Updating a row in a table using UltraLite.NET

Placeholders for parameters in SQL statements are indicated by the ? character. For any INSERT, UPDATE, or
DELETE, each ? is referenced according to its ordinal position in the command's parameters collection. For
example, the first ? is referred to as 0, and the second as 1.

Procedure

1. Declare a ULCommand.

ULCommand cmd;

2. Assign a statement to the ULCommand object.

cmd = conn.CreateCommand();
cmd.CommandText = "UPDATE MyTable SET MyColumn1 = ? WHERE MyColumn2 = ?";

3. Assign input parameter values for the statement.

String newValue;
String oldValue;
cmd.Parameters.Clear();
// assign values
cmd.Parameters.Add("", newValue);
cmd.Parameters.Add("", oldValue);

4. Execute the statement.

int rowsUpdated = cmd.ExecuteNonQuery();

5. If you are using explicit transactions, commit the change.

myTransaction.Commit();

UltraLite - .NET API Reference

UltraLite.NET application development PUBLIC 11
Results

Row entries from MyTable are updated where the MyColumn1 value is an empty string. In this scenario, the
MyColumn2 value is also set to an empty string.

2.3.1.3 Deleting a row in a table in UltraLite.NET

Placeholders for parameters in SQL statements are indicated by the ? character. For any INSERT, UPDATE, or
DELETE, each ? is referenced according to its ordinal position in the command's parameters collection. For
example, the first ? is referred to as 0, and the second as 1.

Procedure

1. Declare a ULCommand.

ULCommand cmd;

2. Assign a statement to the ULCommand object.

cmd = conn.CreateCommand();
cmd.CommandText = "DELETE FROM MyTable WHERE MyColumn = ?";

3. Assign input parameter values for the statement.

String deleteValue;
cmd.Parameters.Clear();
// assign value
cmd.Parameters.Add("", deleteValue);

4. Execute the statement.

int rowsDeleted = cmd.ExecuteNonQuery();

5. If you are using explicit transactions, commit the change.

myTransaction.Commit();

Results

Row entries from MyTable are deleted where the MyColumn value in the table is an empty string.

UltraLite - .NET API Reference

12 PUBLIC UltraLite.NET application development
2.3.2 Retrieving data in UltraLite.NET using SELECT

Execute a SELECT statement to retrieve information from an UltraLite database and handle the result set that
is returned.

Procedure

1. Declare a ULCommand object to holds the query.

ULCommand cmd;

2. Assign a statement to the object.

cmd = conn.CreateCommand();
cmd.CommandText = "SELECT MyColumn FROM MyTable";

3. Execute the statement.

Query results can be returned as one of several types of objects. In this example, a ULDataReader object is
used.

ULDataReader customerNames = cmd.ExecuteReader();

int fc = customerNames.FieldCount();
while( customerNames.MoveNext() ) {
for ( int i = 0; i < fc; i++ ) {
System.Console.Write(customerNames.GetString( i ) + " " );
}
System.Console.WriteLine();
}

Results

The result of the SELECT statement contains a string, which is then output to the command prompt.

2.3.3 Result set schema description

The ULDataReader.GetSchemaTable method and ULDataReader.Schema property allow you to retrieve

information about a result set, such as column names, total number of columns, column scales, column sizes,
and column SQL types.

 Example

The following example demonstrates how to use the ULDataReader.Schema and ResultSet.Schema
properties to display schema information in a command prompt.

for ( int i = 0; i < MyResultSet.Schema.GetColumnCount(); i++ ) {

System.Console.WriteLine( MyResultSet.Schema.GetColumnName(i)

UltraLite - .NET API Reference

UltraLite.NET application development PUBLIC 13
 + " "
+ MyResultSet.Schema.GetColumnSQLType(i) );
}

2.3.4 SQL result set navigation in UltraLite.NET

You can navigate through a result set using methods associated with the ULDataReader object.

The result set object provides you with the following methods to navigate a result set:

MoveAfterLast

moves to a position after the last row.

MoveBeforeFirst

moves to a position before the first row.

MoveFirst

moves to the first row.

MoveLast

moves to the last row.

MoveNext

moves to the next row.

MovePrevious

moves to the previous row.

MoveRelative(offset)

moves a certain number of rows relative to the current row, as specified by the offset. Positive offset values
move forward in the result set, relative to the current position of the cursor in the result set, and negative
offset values move backward in the result set. An offset value of zero does not move the cursor, but allows
you to repopulate the row buffer.

2.4 Data creation and modification in UltraLite.NET using

the ULTable class

UltraLite applications can access table data using SQL statements or by using the ULTable class.

The following tasks can be performed using the Table API:

● Scroll through the rows of a table.

● Access the values of the current row.
● Use find and lookup methods to locate rows in a table.
● Insert, delete, and update rows.

In this section:

UltraLite - .NET API Reference

14 PUBLIC UltraLite.NET application development
 Row navigation in UltraLite.NET [page 15]
UltraLite.NET provides you with several methods to navigate a table to perform a wide range of
navigation tasks.

UltraLite modes [page 16]

An UltraLite mode determines the purpose for which the values in the buffer are used. UltraLite has the
following four modes of operation, in addition to a default mode.

Row insertion in UltraLite.NET [page 17]

The steps to insert a row are very similar to those for updating rows, except that there is no need to
locate a row in the table before carrying out the insert operation.

Row updates [page 17]

By default, UltraLite.NET operates in AutoCommit mode, so that the update is immediately applied to
the row in permanent storage. If you have disabled AutoCommit mode, the update is not applied until
you execute a commit operation.

Row searches [page 18]

UltraLite has several modes of operation for working with data. Two of these modes, the find and
lookup modes, are used for searching. The Table object has methods corresponding to these modes for
locating particular rows in a table.

Row retrieval [page 20]

Row operations can be managed using various methods in the ULTable class.

Row deletions in UltraLite.NET [page 21]

The steps to delete a row are simpler than to insert or update rows. There is no delete mode
corresponding to the insert or update modes.

Related Information

Data creation and modification in UltraLite.NET using SQL statements [page 9]

2.4.1 Row navigation in UltraLite.NET

UltraLite.NET provides you with several methods to navigate a table to perform a wide range of navigation
tasks.

The table object provides you with the following methods to navigate a table.

MoveAfterLast

moves to a position after the last row.

MoveBeforeFirst

moves to a position before the first row.

MoveFirst

moves to the first row.

MoveLast

moves to the last row.

UltraLite - .NET API Reference

UltraLite.NET application development PUBLIC 15
 MoveNext

moves to the next row.

MovePrevious

moves to the previous row.

MoveRelative(offset)

moves a certain number of rows relative to the current row, as specified by the offset. Positive offset values
move forward in the table, relative to the current position of the cursor in the table, and negative offset
values move backward in the table. An offset value of zero does not move the cursor, but allows you to
repopulate the row buffer.

 Example

The following code opens the MyTable table and displays the value of the MyColumn column for each row.

ULTable t = conn.ExecuteTable( "MyTable" );

int colID = t.GetOrdinal( "MyColumn" );
while ( t.MoveNext() ){
System.Console.WriteLine( t.GetString( colID ) );
}

You expose the rows of the table to the application when you open the table object. By default, the rows are
ordered by primary key value, but you can specify an index when opening a table to access the rows in a
particular order.

 Example

The following code moves to the first row of the MyTable table as ordered by the ix_col index.

ULTable t = conn.ExecuteTable( "MyTable", "ix_col" );

t.MoveFirst();

2.4.2 UltraLite modes

An UltraLite mode determines the purpose for which the values in the buffer are used. UltraLite has the
following four modes of operation, in addition to a default mode.

Insert mode

The data in the buffer is added to the table as a new row when the insert method is called.
Update mode

The data in the buffer replaces the current row when the update method is called.
Find mode

Used to locate a row whose value exactly matches the data in the buffer when one of the find methods is
called.
Lookup mode

Used to locate a row whose value matches or is greater than the data in the buffer when one of the lookup
methods is called.

UltraLite - .NET API Reference

16 PUBLIC UltraLite.NET application development
2.4.3 Row insertion in UltraLite.NET

The steps to insert a row are very similar to those for updating rows, except that there is no need to locate a row
in the table before carrying out the insert operation.

The order of row insertion into the table has no significance.

 Example

The following code inserts a new row.

t.InsertBegin();
t.SetInt( id, 3 );
t.SetString( lname, "Carlo" );
t.Insert();

If you do not set a value for one of the columns, and that column has a default, the default value is used. If
the column has no default, one of the following entries is used:

● For nullable columns, NULL.

● For numeric columns that disallow NULL, zero.
● For character columns that disallow NULL, an empty string.
● To explicitly set a value to NULL, use the SetDBNull method.

For update operations, an insert is applied to the database in permanent storage when a commit is carried
out. In AutoCommit mode, a commit is carried out as part of the insert method.

2.4.4 Row updates

By default, UltraLite.NET operates in AutoCommit mode, so that the update is immediately applied to the row
in permanent storage. If you have disabled AutoCommit mode, the update is not applied until you execute a
commit operation.

 Caution

You cannot update the primary key value of a row. Delete the row and add a new row instead.

In this section:

Updating a row in a table using UltraLite.NET [page 18]

Use the Update method to update a row in a table.

Related Information

Transaction management in UltraLite.NET [page 21]

UltraLite - .NET API Reference

UltraLite.NET application development PUBLIC 17
2.4.4.1 Updating a row in a table using UltraLite.NET

Use the Update method to update a row in a table.

Procedure

1. Move to the row you want to update.

You can move to a row by scrolling through the table or by searching the table using find or lookup
methods.
2. Enter update mode.

For example, the following instruction enters update mode on a table.

t.UpdateBegin();

3. Set the new values for the row to be updated.

For example, the following instruction sets the id column in the buffer to 3.

t.SetInt( id , 3);

4. Execute the Update.

t.Update();

Results

The current row is updated. If you changed the value of a column in the index specified when the Table object
was opened, the current row is undefined.

2.4.5 Row searches

UltraLite has several modes of operation for working with data. Two of these modes, the find and lookup
modes, are used for searching. The Table object has methods corresponding to these modes for locating
particular rows in a table.

 Note

The columns searched using Find and Lookup methods must be in the index used to open the table.

Find methods

move to the first row that exactly matches specified search values, under the sort order specified when the
Table object was opened. If the search values cannot be found, the application is positioned before the first
or after the last row.

UltraLite - .NET API Reference

18 PUBLIC UltraLite.NET application development
 Lookup methods

move to the first row that matches or is greater than a specified search value, under the sort order
specified when the Table object was opened.

In this section:

Searching for a row with the find and lookup methods [page 19]
Use the find and lookup methods to search for a row in a ULTable object.

2.4.5.1 Searching for a row with the find and lookup

methods

Use the find and lookup methods to search for a row in a ULTable object.

Procedure

1. Enter find or lookup mode.

The mode is entered by calling a method on the table object. For example, the following code enters find
mode.

t.FindBegin();

2. Set the search values.

You do this by setting values in the current row. Setting these values affects the buffer holding the current
row only, not the database. For example, the following code sets the value in the buffer to Kaminski.

int lname = t.GetOrdinal( "lname" );

t.SetString( lname, "Kaminski" );

3. Search for the row.

Use the appropriate method to perform the search. For example, the following instruction looks for the first
row that exactly matches the specified value in the current index.

For multi-column indexes, a value for the first column is always used, but you can omit the other columns.

t.FindFirst();

4. Search for the next instance of the row.

Use the appropriate method to perform the search. For a find operation, FindNext locates the next instance
of the parameters in the index. For a lookup, MoveNext locates the next instance.

UltraLite - .NET API Reference

UltraLite.NET application development PUBLIC 19
Results

The cursor points to the desired row.

Next Steps

Perform operations on the row, such as delete, or modify data that pertains to the row.

2.4.6 Row retrieval

Row operations can be managed using various methods in the ULTable class.

A Table object is always located at one of the following positions:

● Before the first row of the table.

● On a row of the table.
● After the last row of the table.

If the Table object is positioned on a row, you can use one of a set of methods appropriate for the data type to
retrieve or modify the value of each column.

Retrieving column values

The Table object provides a set of methods for retrieving column values. These methods take the column ID as
argument.

 Example

The following code retrieves the value of the lname column, which is a character string.

int lname = t.GetOrdinal( "lname" );

string lastname = t.GetString( lname );

The following code retrieves the value of the cust_id column, which is an integer.

int cust_id = t.GetOrdinal( "cust_id" );

int id = t.GetInt( cust_id );

Modifying column values

In addition to the methods for retrieving values, there are methods for setting values. These methods take the
column ID and the value as arguments.

UltraLite - .NET API Reference

20 PUBLIC UltraLite.NET application development
  Example

For example, the following code sets the value of the lname column to Kaminski.

t.SetString( lname, "Kaminski" );

By assigning values to these properties you do not alter the value of the data in the database. You can
assign values to the properties even if you are before the first row or after the last row of the table, but it is
an error to try to access data when the current row is at one of these positions, for example, by assigning
the property to a variable.

// This code is incorrect

t.MoveBeforeFirst();
id = t.GetInt( cust_id );

Casting values

The method you choose must match the data type you want to assign. UltraLite automatically casts database
data types where they are compatible, so that you could use the getString method to fetch an integer value into
a string variable, and so on.

2.4.7 Row deletions in UltraLite.NET

The steps to delete a row are simpler than to insert or update rows. There is no delete mode corresponding to
the insert or update modes.

You delete a row by moving the cursor to the row you want to delete and then executing the Table.Delete
method.

 Example

The following code illustrates how to delete the first row in a table:

t.MoveFirst();
t.Delete();

2.5 Transaction management in UltraLite.NET

UltraLite provides transaction processing to ensure the integrity of the data in your database. A transaction is a
logical unit of work. Either an entire transaction is executed, or none of the statements in the transaction are
executed.

By default, UltraLite.NET operates in AutoCommit mode, so that each insert, update, or delete is executed as a
separate transaction. Once the operation is complete, the change is made to the database.

UltraLite - .NET API Reference

UltraLite.NET application development PUBLIC 21
To use multi-statement transactions, you must create a ULTransaction class object by calling
ULConnection.BeginTransaction. For example, if your application transfers money between two accounts, both
the deduction from the source account and the addition to the destination account must be completed as a
distinct operation, otherwise both statements must not be completed.

If the connection has performed a valid transaction, you must execute ULTransaction.Commit statement to
complete the transaction and commit the changes to your database. If the set of updates is to be abandoned,
execute ULTransaction.Rollback statement to cancel and roll back all the operations of the transaction. Once a
transaction has been committed or rolled back, the connection will revert to AutoCommit mode until a
subsequent call to ULConnection.BeginTransaction.

For example, the following code fragment shows how to set up a transaction that involves multiple operations
(avoiding the default autocommit behavior):

// Assuming an already open connection named conn

ULTransaction txn = conn.BeginTransaction(IsolationLevel.ReadUncommitted);
// Perform transaction operations here
txn.Commit();

 Note

UltraLite supports only the ReadCommitted and ReadUncommitted members of the IsolationLevel
enumeration.

Some SQL statements, especially statements that alter the structure of the database, cause any pending
transactions to be committed. Examples of SQL statements that automatically commit transactions in
progress are: CREATE TABLE and ALTER TABLE.

2.6 Schema information in UltraLite.NET

The objects in the table API represent tables, columns, indexes, and synchronization publications. Each object
has a Schema property that provides access to information about the structure of that object.

You cannot modify the schema through the API. You can only retrieve information about the schema.

You can access the following schema objects and information:

ULDatabaseSchema

Exposes the number and names of the tables in the database, and the global properties such as the format
of dates and times.

Call ULConnection.Schema to obtain a ULDatabaseSchema object.

ULTableSchema

The number and names of the columns and indexes for this table.

Call ULTable.Schema to obtain a ULTableSchema object.

ULIndexSchema

Information about the column in the index. As an index has no data directly associated with it there is no
separate Index class, just a ULIndexSchema class.

UltraLite - .NET API Reference

22 PUBLIC UltraLite.NET application development
 Call the ULTableSchema.GetIndex, ULTableSchema.GetOptimalIndex, or ULTableSchema.GetPrimaryKey
method to obtain a ULIndexSchema object.

2.7 Error handling in UltraLite.NET

You can use the standard .NET error-handling features to handle errors. Most UltraLite methods throw
ULException errors.

You can use ULException.NativeError to retrieve the ULSQLCode value assigned to this error. ULException has
a Message property, which you can use to obtain a descriptive text of the error. ULSQLCode errors are negative
numbers indicating the error type.

After synchronization, you can use the SyncResult property of the connection to obtain more detailed error
information. For example, the following sample illustrates a possible technique for reporting errors that occur
during synchronization:

public void Sync() {

try {
_conn.Synchronize( this );
_inSync = false;
}
catch( ULException uEx ) {
if( uEx.NativeError == ULSQLCode.SQLE_MOBILINK_COMMUNICATIONS_ERROR ) {
MessageBox.Show(
"StreamErrorCode = " +
_conn.SyncResult.StreamErrorCode.ToString() + "\r\n"
+ "StreamErrorParameters = " +
_conn.SyncResult.StreamErrorParameters + "\r\n"
+ "StreamErrorSystem = " +
_conn.SyncResult.StreamErrorSystem + "\r\n"
);
}
else {
MessageBox.Show(uEx.Message);
}
}
catch(System.Exception ex ) {
MessageBox.Show(ex.Message);
}
}

2.8 MobiLink data synchronization in UltraLite.NET

You synchronize an UltraLite database with a central consolidated database. Synchronization requires the
MobiLink synchronization software included with SQL Anywhere.

You can find a working example of synchronization in the CustDB sample application. For more information,
see the Samples\UltraLite.NET\CustDB subdirectory of your SQL Anywhere 17 installation.

UltraLite.NET supports TCP/IP, HTTP, HTTPS, and TLS (transport layer security) synchronization.
Synchronization is initiated by the UltraLite application. Always use properties of the SyncParms object to
control synchronization.

UltraLite - .NET API Reference

UltraLite.NET application development PUBLIC 23
In this section:

Synchronization initiation in a C# application [page 24]

Use the SyncParms object to initiate synchronization in a C# application.

Microsoft ActiveSync synchronization setup in UltraLite.NET [page 24]

Microsoft ActiveSync synchronization can be added to an UltraLite.NET application, and your
application can be registered for use with Microsoft ActiveSync on your end users' computers.

2.8.1 Synchronization initiation in a C# application

Use the SyncParms object to initiate synchronization in a C# application.

private void Sync( ULConnection conn )

{
// Sync
try
{
// setup to synchronize a publication named "high_priority"
conn.SyncParms.Publications = "high_priority";

// Set the synchronization parameters

conn.SyncParms.Version = "Version1";
conn.SyncParms.StreamParms = "";
conn.SyncParms.Stream = ULStreamType.TCPIP;
conn.SyncParms.UserName = "51";
conn.Synchronize();
}
catch (System.Exception t)
{
MessageBox.Show("Exception: " + t.Message);
}
}

2.8.2 Microsoft ActiveSync synchronization setup in

UltraLite.NET

Microsoft ActiveSync synchronization can be added to an UltraLite.NET application, and your application can
be registered for use with Microsoft ActiveSync on your end users' computers.

Microsoft ActiveSync synchronization can only be initiated by Microsoft ActiveSync. Microsoft ActiveSync
initiates synchronization when the device is placed in the cradle or when Synchronize is selected from the
Microsoft ActiveSync window.

When Microsoft ActiveSync initiates synchronization, the MobiLink provider for Microsoft ActiveSync starts the
UltraLite application, if it is not already running, and sends a message to it. Your application must implement a
ULActiveSyncListener object to receive and process messages from the MobiLink provider. Your application
must specify the listener object using the SetActiveSyncListener method, where MyAppClassName is a unique
Microsoft Windows class name for the application.

dbMgr.SetActiveSyncListener( "MyAppClassName", listener );

UltraLite - .NET API Reference

24 PUBLIC UltraLite.NET application development
When UltraLite receives a Microsoft ActiveSync message, it invokes the specified listener's ActiveSyncInvoked
method on a different thread. To avoid multithreading issues, your ActiveSyncInvoked method should post an
event to the user interface.

If your application is multithreaded, use a separate connection and use the lock keyword in Microsoft C# or
SyncLock keyword in Microsoft Visual Basic .NET to access any objects shared with the rest of the application.
The ActiveSyncInvoked method should specify a ULStreamType.ACTIVE_SYNC for its connection's
SyncParms.Stream and then call ULConnection.Synchronize.

When registering your application, set the following parameter:

Class Name

The same class name the application used with the Connection.SetActiveSyncListener method.

2.9 How to deploy UltraLite.NET applications

UltraLite.NET applications can be deployed to Microsoft Windows Mobile and Microsoft Windows. If you are
deploying to Microsoft Windows Mobile, UltraLite.NET requires the Microsoft .NET Compact Framework. If you
are deploying to Microsoft Windows, it requires the Microsoft .NET Framework. UltraLite.NET also supports
Microsoft ActiveSync synchronization.

In this section:

Deploying an UltraLite.NET application for Microsoft Windows Mobile [page 25]

Specify appropriate creation parameters, connection parameters, synchronization parameters,
protocol options, references, and deployment files to ensure that your UltraLite.NET application runs
successfully.

Deploying an UltraLite.NET application for Windows Mobile (UltraLite engine) [page 27]
Specify appropriate creation parameters, connection parameters, synchronization parameters,
protocol options, references, and deployment files to ensure that your UltraLite.NET application runs
successfully.

2.9.1 Deploying an UltraLite.NET application for Microsoft

Windows Mobile

Specify appropriate creation parameters, connection parameters, synchronization parameters, protocol

options, references, and deployment files to ensure that your UltraLite.NET application runs successfully.

Procedure

1. Specify the following parameters:

○ When using obfuscation, set the creation parameter obfuscate=1 while creating the database.

UltraLite - .NET API Reference

UltraLite.NET application development PUBLIC 25
 ○ When using AES encryption, set the connection parameter DBKEY= encryption-key while creating
or connecting to the database.
2. Set the appropriate parameter settings when using synchronization in your UltraLite application:

Synchronization type Parameter settings

TCP/IP Set the Stream synchronization parameter to tcpip.

HTTP Set the Stream synchronization parameter to http.

RSA TLS Set the Stream synchronization parameter to tls.

RSA HTTPS Set the Stream synchronization parameter to https.

3. When using RSA end-to-end encryption, set the protocol option e2ee_public_key= key-file.
4. When using ZLIB compression, set the protocol option compression=zlib.
5. Add references to:
○ Sap.Data.UltraLite
○ Sap.Data.UltraLite.resources
6. Deploy the following files:
○ %SQLANY17%\UltraLite\UltraLite.NET\Assembly\V2\Sap.Data.UltraLite.dll.
○ %SQLANY17%\UltraLite\UltraLite.NET\Assembly\V2\en
\Sap.Data.UltraLite.resources.dll.
○ ulnet17.dll, located in %SQLANY17%\UltraLite\UltraLite.NET\CE\Arm50 for Microsoft
Windows Mobile. For Microsoft Windows, it is located in %SQLANY17%\UltraLite\UltraLite.NET
\x64 or %SQLANY17%\UltraLite\UltraLite.NET\win32.
7. Deploy the files appropriate for your application:
○ When using ZLIB compression, mlczlib17.dll.
○ When using RSA TLS, RSA HTTPS, or RSA E2EE, mlcrsa17.dll.

For Microsoft Windows Mobile, the files are located in %SQLANY17%\UltraLite\CE\Arm.50. For
Microsoft Windows, the files are located in %SQLANY17%\UltraLite\Windows\x64 or %SQLANY17%
\UltraLite\Windows\x86.

Results

The UltraLite.NET application runs successfully on the Microsoft Windows desktop or Microsoft Windows
Mobile device that it is deployed to.

Next Steps

Deploy an UltraLite database to the Microsoft Windows desktop or Microsoft Windows Mobile device that the
application was deployed to, or create a new database with the deployed application.

UltraLite - .NET API Reference

26 PUBLIC UltraLite.NET application development
2.9.2 Deploying an UltraLite.NET application for Windows
Mobile (UltraLite engine)

Specify appropriate creation parameters, connection parameters, synchronization parameters, protocol

options, references, and deployment files to ensure that your UltraLite.NET application runs successfully.

Procedure

1. Specify the following parameters:

○ When using obfuscation, set the creation parameter obfuscate=1 while creating the database.
○ When using AES encryption, set the connection parameter DBKEY= encryption-key while creating
or connecting to the database.
2. Set the appropriate parameter settings when using synchronization in your UltraLite application:

Synchronization type Parameter settings

TCP/IP Set the Stream synchronization parameter to tcpip.

HTTP Set the Stream synchronization parameter to http.

RSA TLS Set the Stream synchronization parameter to tls.

RSA HTTPS Set the Stream synchronization parameter to https.

3. When using RSA end-to-end encryption, set the protocol option e2ee_public_key= key-file.
4. When using ZLIB compression, set the protocol option compression=zlib.
5. Add references to:
○ Sap.Data.UltraLite
○ Sap.Data.UltraLite.resources
6. Deploy the following files:
○ %SQLANY17%\UltraLite\UltraLite.NET\Assembly\V2\Sap.Data.UltraLite.dll.
○ %SQLANY17%\UltraLite\UltraLite.NET\Assembly\V2\en
\Sap.Data.UltraLite.resources.dll.
○ ulnetclient17.dll, located in %SQLANY17%\UltraLite\UltraLite.NET\CE\Arm50 for
Windows Mobile. For Windows, it is located in %SQLANY17%\UltraLite\UltraLite.NET\x64 or
%SQLANY17%\UltraLite\UltraLite.NET\win32.
7. Deploy the files appropriate for your application:
○ uleng17.exe.
○ When using ZLIB compression, mlczlib17.dll.
○ When using RSA TLS, RSA HTTPS, or RSA E2EE, mlcrsa17.dll.

For Windows Mobile, the files are located in %SQLANY17%\UltraLite\CE\Arm.50. For Windows, the
files are located in %SQLANY17%\UltraLite\Windows\x64 or %SQLANY17%\UltraLite\Windows
\x86.

UltraLite - .NET API Reference

UltraLite.NET application development PUBLIC 27
Results

The UltraLite.NET application, which uses the UltraLite engine, runs successfully on the Windows desktop or
Windows Mobile device that it is deployed to.

Next Steps

Deploy an UltraLite database to the Windows desktop or Windows Mobile device that the application was
deployed to, or create a new database with the deployed application.

UltraLite - .NET API Reference

28 PUBLIC UltraLite.NET application development
3 Tutorial: Building a Microsoft Windows
Mobile application using UltraLite.NET

This tutorial guides you through the process of building an UltraLite application for Microsoft Windows Mobile
using Microsoft Visual Studio. It uses the Microsoft ADO.NET interface provided by the Sap.Data.UltraLite
namespace and runs on the Microsoft .NET 3.5 Compact Framework.

Prerequisites

This tutorial assumes the following:

● You are familiar with the C# programming language or the Microsoft Visual Basic programming language.
● You know how to create an UltraLite database using the UltraLite plug-in for SQL Central.
● You have Microsoft Visual Studio installed on your computer and you are familiar with using Microsoft
Visual Studio. This tutorial is tested using Microsoft Visual Studio 2008 and may refer to Microsoft Visual
Studio actions or procedures that may be slightly different in other versions of Microsoft Visual Studio.
● You have installed the Microsoft Windows Mobile 5.0 SDK or later from Microsoft
● You have installed the Microsoft .NET 3.5 Compact Framework to your mobile device

Context

The goal for the tutorial is to gain competence and familiarity with the process of developing UltraLite
applications in the Microsoft Visual Studio environment.

This tutorial contains code for a Microsoft Visual Basic application and a Microsoft Visual C# application.

If you install UltraLite software on a Microsoft Windows computer that already has Microsoft Visual Studio
installed, the UltraLite installation process detects the presence of Microsoft Visual Studio and performs the
necessary integration steps. If you install Microsoft Visual Studio after installing UltraLite, or install a new
version of Microsoft Visual Studio, the process to integrate UltraLite with Microsoft Visual Studio must be
performed manually at a command prompt as follows:

● Ensure Microsoft Visual Studio is not running.

● For Microsoft Visual Studio 2005 or later, run installULNet.exe from the folder named %SQLANY17%
\UltraLite\UltraLite.NET\Assembly\v2\. This task may require administrator privileges.

1. Lesson 1: Creating a Microsoft Visual Studio project [page 30]

In this lesson, you create and configure a new Microsoft Visual Studio application. You can choose
whether to use Microsoft Visual Basic or C# as your programming language.
2. Lesson 2: Creating an UltraLite database [page 33]
In this lesson, you create an UltraLite database using SQL Central on a desktop PC.

UltraLite - .NET API Reference

Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET PUBLIC 29
3. Lesson 3: Adding database connection controls to the application [page 35]
In this lesson, you add a control to your UltraLite.NET application that establishes a connection to an
UltraLite database.
4. Lesson 4: Inserting, updating, and deleting data [page 37]
In this lesson, you add code to your application that uses Dynamic SQL to modify the data in your
database.
5. Lesson 5: Building and deploying the application [page 41]
In this lesson, you build your application and deploy it to a remote device or emulator.
6. Code listing for C# tutorial [page 43]
Following is the complete code for the tutorial program described in the preceding sections.
7. Code listing for Microsoft Visual Basic tutorial [page 45]
Following is the complete code for the tutorial program described in the preceding sections.

3.1 Lesson 1: Creating a Microsoft Visual Studio project

In this lesson, you create and configure a new Microsoft Visual Studio application. You can choose whether to
use Microsoft Visual Basic or C# as your programming language.

Prerequisites

This lesson assumes that you have installed the required software.

Context

This tutorial assumes that if you are designing a C# application, your files are in the directory C:\tutorial
\uldotnet\CSApp and that if you are designing a Microsoft Visual Basic application, your files are in the
directory C:\tutorial\uldotnet\VBApp. If you choose to use a directory with a different name, use that
directory throughout the tutorial.

Procedure

1. Create a Microsoft Visual Studio project.

○ In the Microsoft Visual Studio File menu, click New Project .

○ The New Project window appears. In the left pane, expand either the Visual Basic folder or the Visual
C# folder. Click Smart Device for the project type.
In the right pane, click a Smart Device Project and name your project VBApp or CSApp, depending on
whether you are using Microsoft Visual Basic or C# for the programming language.
○ Enter a Location of C:\tutorial\uldotnet and click OK.

UltraLite - .NET API Reference

30 PUBLIC Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET
 ○ Click Windows Mobile 5.0 Pocket PC SDK as the target platform and .NET Compact Framework Version
3.5 as the target Microsoft .NET Compact Framework version. Click OK.
2. Add references to your project.
○ Add the Sap.Data.UltraLite assembly and the associated resources to your project.
1. From the Project menu, click Add Reference.
2. Click Sap.Data.UltraLite and Sap.Data.UltraLite EN (for English) in the list of available references.
Click OK to add them to the list of selected components.
If your desired language is not English, click Browse and locateSap.Data.UltraLite xx in the
UltraLite\UltraLite.NET\ce\Assembly\v2\xx subdirectory of your SQL Anywhere
installation, where xx is a two-letter abbreviation for your desired language (for example, use en for
English). Click Sap.Data.UltraLite.resources.dll and click Open.
○ Link the UltraLite component to your project.
In this step, ensure that you add a link to the component, and that you do not open the component.
1. From the Project menu, click Add Existing Item and browse to the UltraLite\UltraLite.NET
\ce subdirectory of your SQL Anywhere installation.
2. In the Objects of Type list, click Executable Files.
3. Open the folder corresponding to the processor of the Microsoft Windows Mobile device you are
using. For Microsoft Visual Studio 2005 and later, open the arm.50 folder. Click ulnet17.dll;
Click the arrow on the Add button and click Add as Link.
3. Create a form for your application.

If the Microsoft Visual Studio toolbox panel is not currently displayed, from the main menu click View
Toolbox . Add the following visual components to the form by selecting the object from the toolbox and
dragging it onto the form in the desired location.

Type Design - name

Button btnInsert

Button btnUpdate

Button btnDelete

TextBox txtName

ListBox lbNames

Label laName

UltraLite - .NET API Reference

Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET PUBLIC 31
 Your form should look like the following figure:

4. Build and deploy your solution.

Building and deploying the solution confirms that you have configured your Microsoft Visual Studio project
properly.
a. From the Build menu, click Build Solution. Confirm that the project builds successfully. If you are
building a Microsoft Visual Basic application, you can ignore the following warning that may appear:

Referenced assembly 'Sap.Data.UltraLite.resources' is a localized

satellite assembly

b. From the Debug menu, click Start Debugging.

This action deploys your application to the mobile device or emulator, and starts it. The application is
deployed to the emulator or device location: \Program Files\VBApp or \Program Files\CSApp
depending on your project name.

The deployment may take some time.

c. Confirm that the application deploys to the emulator or your target device and the form (Form1) you
have designed is displayed correctly.
d. Shutdown the emulator or the application on your target device.

UltraLite - .NET API Reference

32 PUBLIC Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET
Results

The UltraLite.NET API is functional in the new Microsoft Windows Mobile application.

Next Steps

Proceed to the next lesson.

Task overview: Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET [page 29]

Next task: Lesson 2: Creating an UltraLite database [page 33]

3.2 Lesson 2: Creating an UltraLite database

In this lesson, you create an UltraLite database using SQL Central on a desktop PC.

Prerequisites

You must have completed the previous lessons in this tutorial.

You must have the roles and privileges listed at the beginning of this tutorial.

Procedure

1. Click Start Programs SQL Anywhere 17 Administration Tools SQL Central .

2. Use the UltraLite plug-in for SQL Central to create a database in the same directory as your application.

From the Tools menu, click UltraLite 17 Create Database .

In general, the default database characteristics provided by SQL Central are suitable. Note the following
characteristics:

Database file name

c:\tutorial\uldotnet\VBApp\VBApp.udb or c:\tutorial\uldotnet\CSApp\CSApp.udb,
depending on your application type.
DBA user ID and password

Set to DBA and sql, respectively, for the purposes of examples in this documentation.
Collation sequence

UltraLite - .NET API Reference

Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET PUBLIC 33
 Use the default collation.
Use case-sensitive string comparisons

This option should not be on.

Click Finish and connect to the UltraLite database.

3. Create a new UltraLite table by highlighting the Tables folder icon in the SQL Central tree view and then
click File New Table . Note the following characteristics:

Table name

Type Names.
Columns

Create columns in the Names table with the following attributes:

Column Name Data Type (Size) Nulls Unique Default value

ID Integer No Yes (primary key) Global autoincre­

ment

Name Varchar(30) No No None

Primary key

Specify the ID column as primary key.

4. Exit SQL Central and verify the database file is created in the required directory.
5. Link the initialized (empty) database file to your Microsoft Visual Studio project so that the database file is
deployed to the device along with the application code:

○ From the Visual Studio menu, click Project Add Existing Item .
○ Ensure that Objects of Type is set to All Files. Browse to the directory where you created the database
file and click the file VBApp.udb or CSApp.udb depending on your application type.
○ Click the arrow in the Add button and click Add As Link.
○ In the Solution Explorer frame, right click the database file name that has just been added to the
project and click Properties.
In the properties panel, set the Build Action property to Content; set the Copy to Output Directory
property to Copy always.

Results

An UltraLite database is created.

Next Steps

Proceed to the next lesson.

Task overview: Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET [page 29]

UltraLite - .NET API Reference

34 PUBLIC Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET
Previous task: Lesson 1: Creating a Microsoft Visual Studio project [page 30]

Next task: Lesson 3: Adding database connection controls to the application [page 35]

3.3 Lesson 3: Adding database connection controls to the

application

In this lesson, you add a control to your UltraLite.NET application that establishes a connection to an UltraLite
database.

Prerequisites

You must have completed the previous lessons in this tutorial.

You must have the roles and privileges listed at the beginning of this tutorial.

Procedure

1. Double-click the form to open the source file (Form1.cs or Form1.vb).

2. Add code to import the Sap.Data.UltraLite namespace.

Add the following statement as the very first line of the file.

//Microsoft Visual C#
using Sap.Data.UltraLite;

'Microsoft Visual Basic

Imports Sap.Data.UltraLite

3. Add global variables to the form declaration.

For Microsoft Visual C#, add the following code after the code describing the form components and before
the first method declaration.

//Microsoft Visual C#
private ULConnection Conn;
private int[] ids;

For Microsoft Visual Basic, add the following code at the beginning of the Form1 class.

'Microsoft Visual Basic

Dim Conn As ULConnection
Dim ids() As Integer

UltraLite - .NET API Reference

Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET PUBLIC 35
 These variables are used as follows:

ULConnection

A Connection object is the root object for all actions executed on a connection to a database.
ids

The ids array is used to hold the ID column values returned after executing a query.

Although the ListBox control itself allows you access to sequential numbers, those numbers differ from
the value of the ID column once a row has been deleted. For this reason, the ID column values must be
stored separately.
4. Double-click a blank area of your form to create a Form1_Load method.

This method performs the following tasks:

○ Open a connection to the database using the connection parameters set in the ulConnectionParms1
control.
○ Call the RefreshListBox method (defined later in this tutorial).
○ Print (display) and error message if an error occurs. For SQL Anywhere errors, the code also prints the
error code.

For C#, add the following code to the Form1_Load method.

//Microsoft Visual C#
try {
String ConnString = "dbf=\\Program Files\\CSApp\\CSApp.udb";
Conn = new ULConnection( ConnString );
Conn.Open();
Conn.DatabaseID = 1;
RefreshListBox();
}
catch ( System.Exception t ) {
MessageBox.Show( "Exception: " + t.Message);
}

For Microsoft Visual Basic, add the following code to the Form1_Load method.

'Microsoft Visual Basic

Try
Dim ConnString as String = "dbf=\Program Files\VBApp\VBApp.udb"
Conn = New ULConnection( ConnString )
Conn.Open()
Conn.DatabaseID = 1
RefreshListBox()
Catch
MsgBox("Exception: " + err.Description)
End Try

5. Build the project.

From the Build menu, click Build Solution. At this stage, you may receive a single error reported; for
example in C#: error CS0103: The name 'RefreshListBox' does not exist in the current
context. because RefreshListBox is not yet declared. The next lesson adds that function.

If you get other errors, you must correct them before proceeding. Check for common errors, such as case
inconsistencies in C#. For example, UltraLite and ULConnection must match case exactly. In Microsoft
Visual Basic you must include the Imports Sap.Data.UltraLite statement described in Lesson 3.

UltraLite - .NET API Reference

36 PUBLIC Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET
Results

The application is set up to connect to an UltraLite database.

Task overview: Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET [page 29]

Previous task: Lesson 2: Creating an UltraLite database [page 33]

Next task: Lesson 4: Inserting, updating, and deleting data [page 37]

3.4 Lesson 4: Inserting, updating, and deleting data

In this lesson, you add code to your application that uses Dynamic SQL to modify the data in your database.

Prerequisites

You must have completed the previous lessons in this tutorial.

You must have the roles and privileges listed at the beginning of this tutorial.

Context

In this lesson, you create a supporting method to maintain the listbox. This approach is required for the data
manipulation methods used in the remaining procedures.

Procedure

1. Right-click the form and click View Code.

2. Add a method of the Form1 class to update and populate the listbox. This method carries out the following
tasks:
○ Clears the listbox.
○ Instantiates a ULCommand object and assigns it a SELECT query that returns data from the Names
table in the database.
○ Executes the query, returning a result set as a ULDataReader.
○ Instantiates an integer array with length equal to the number of rows in the result set.
○ Populates the listbox with the names returned in the ULDataReader and populates the integer array
with the ids returned in the ULDataReader.

UltraLite - .NET API Reference

Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET PUBLIC 37
 ○ Closes the ULDataReader.
○ If an error occurs, prints the error message. For SQL errors, the code also prints the error code.

For C#, add the following code to your application as a method of the Form1 class.

//Microsoft Visual C#
private void RefreshListBox(){
try{
long NumRows;
int I = 0;
lbNames.Items.Clear();
using( ULCommand cmd = Conn.CreateCommand() ){
cmd.CommandText = "SELECT ID, Name FROM Names";
using( ULDataReader dr = cmd.ExecuteReader()){
dr.MoveBeforeFirst();
NumRows = dr.RowCount;
ids = new int[ NumRows ];
while (dr.MoveNext())
{
lbNames.Items.Add(
dr.GetString(1));
ids[ I ] = dr.GetInt32(0);
I++;
}
}
txtName.Text = " ";
}
}
catch( Exception err ){
MessageBox.Show(
"Exception in RefreshListBox: " + err.Message );
}
}

For Microsoft Visual Basic, add the following code to your application as a method of the Form1 class.

'Microsoft Visual Basic

Private Sub RefreshListBox()
Try
Dim cmd As ULCommand = Conn.CreateCommand()
Dim I As Integer = 0
lbNames.Items.Clear()
cmd.CommandText = "SELECT ID, Name FROM Names"
Dim dr As ULDataReader = cmd.ExecuteReader()
ReDim ids(dr.RowCount)
While (dr.MoveNext)
lbNames.Items.Add(dr.GetString(1))
ids(I) = dr.GetInt32(0)
I = I + 1
End While
dr.Close()
txtName.Text = " "
Catch ex As Exception
MsgBox(ex.ToString)
End Try
End Sub

3. Build the project.

Building the project should result in no errors.

4. On the form design tab, double-click Insert to create a btnInsert_Click method. This method carries out the
following tasks:
○ Instantiates a ULCommand object and assigns it an INSERT statement that inserts the value in the text
box into the database.

UltraLite - .NET API Reference

38 PUBLIC Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET
 ○ Executes the statement.
○ Disposes of the ULCommand object.
○ Refreshes the listbox.
○ If an error occurs, prints the error message. For SQL errors, the code also prints the error code.

For Microsoft C#, add the following code to the btnInsert_Click method.

//Microsoft Visual C#
try {
long RowsInserted;
using( ULCommand cmd = Conn.CreateCommand() ) {
cmd.CommandText =
"INSERT INTO Names(name) VALUES (?)";
cmd.Parameters.Add("", txtName.Text);
RowsInserted = cmd.ExecuteNonQuery();
}
RefreshListBox();
}
catch( Exception err ) {
MessageBox.Show("Exception: " + err.Message );
}

For Microsoft Visual Basic, add the following code to the btnInsert_Click method.

'Microsoft Visual Basic

Try
Dim RowsInserted As Long
Dim cmd As ULCommand = Conn.CreateCommand()
cmd.CommandText = "INSERT INTO Names(name) VALUES (?)"
cmd.Parameters.Add("", txtName.Text)
RowsInserted = cmd.ExecuteNonQuery()
cmd.Dispose()
RefreshListBox()
Catch
MsgBox("Exception: " + Err.Description)
End Try

5. On the form design tab, double-click Update to create a btnUpdate_Click method. This method carries out
the following tasks:
○ Instantiates a ULCommand object and assigns it an UPDATE statement that inserts the value in the
text box into the database based on the associated ID.
○ Executes the statement.
○ Disposes of the ULCommand object.
○ Refreshes the listbox.
○ If an error occurs, prints the error message. For SQL errors, the code also prints the error code.

For Microsoft C#, add the following code to the btnUpdate_Click method.

//Microsoft Visual C#
try {
long RowsUpdated;
int updateID = ids[ lbNames.SelectedIndex ];
using( ULCommand cmd = Conn.CreateCommand() ){
cmd.CommandText =
"UPDATE Names SET name = ? WHERE id = ?" ;
cmd.Parameters.Add("", txtName.Text );
cmd.Parameters.Add("", updateID);
RowsUpdated = cmd.ExecuteNonQuery();
}
RefreshListBox();
}

UltraLite - .NET API Reference

Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET PUBLIC 39
 catch( Exception err ) {
MessageBox.Show(
"Exception: " + err.Message);
}

For Microsoft Visual Basic, add the following code to the btnUpdate_Click method.

'Microsoft Visual Basic

Try
Dim RowsUpdated As Long
Dim updateID As Integer = ids(lbNames.SelectedIndex)
Dim cmd As ULCommand = Conn.CreateCommand()
cmd.CommandText = "UPDATE Names SET name = ? WHERE id = ?"
cmd.Parameters.Add("", txtName.Text)
cmd.Parameters.Add("", updateID)
RowsUpdated = cmd.ExecuteNonQuery()
cmd.Dispose()
RefreshListBox()
Catch
MsgBox("Exception: " + Err.Description)
End Try

6. On the form design tab, double-click Delete to create a btnDelete_Click method. Add code to perform the
following tasks:
○ Instantiates a ULCommand object and assigns it a DELETE statement. The DELETE statement deletes
the selected row from the database, based on the associated ID from the integer array ids.
○ Executes the statement.
○ Disposes of the ULCommand object.
○ Refreshes the listbox.
○ If an error occurs, displays the error message. For SQL errors, the code also displays the error code.

For Microsoft C#, add the following code to the btnDelete_Click method.

//Microsoft Visual C#
try{
long RowsDeleted;
int deleteID = ids[lbNames.SelectedIndex];
using( ULCommand cmd = Conn.CreateCommand() ){
cmd.CommandText =
"DELETE From Names WHERE id = ?" ;
cmd.Parameters.Add("", deleteID);
RowsDeleted = cmd.ExecuteNonQuery ();
}
RefreshListBox();
}
catch( Exception err ) {
MessageBox.Show("Exception: " + err.Message );
}

For Microsoft Visual Basic, add the following code to the btnDelete_Click method.

'Microsoft Visual Basic

Try
Dim RowsDeleted As Long
Dim deleteID As Integer = ids(lbNames.SelectedIndex)
Dim cmd As ULCommand = Conn.CreateCommand()
cmd.CommandText = "DELETE From Names WHERE id = ?"
cmd.Parameters.Add("", deleteID)
RowsDeleted = cmd.ExecuteNonQuery()
cmd.Dispose()
RefreshListBox()
Catch

UltraLite - .NET API Reference

40 PUBLIC Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET
 MsgBox("Exception: " + Err.Description)
End Try

7. Build your application to confirm that it compiles properly.

Results

The Microsoft Windows Mobile application is set up to perform data operations on the UltraLite database.

Next Steps

Proceed to the next lesson.

Task overview: Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET [page 29]

Previous task: Lesson 3: Adding database connection controls to the application [page 35]

Next task: Lesson 5: Building and deploying the application [page 41]

Related Information

Data creation and modification in UltraLite.NET using the ULTable class [page 14]

3.5 Lesson 5: Building and deploying the application

In this lesson, you build your application and deploy it to a remote device or emulator.

Prerequisites

You must have completed the previous lessons in this tutorial.

You must have the roles and privileges listed at the beginning of this tutorial.

UltraLite - .NET API Reference

Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET PUBLIC 41
Procedure

1. Build the solution.

Ensure that your application builds without errors.

2. Choose the deployment target.

The deployment target must match the version of ulnet17.dll that you included in your application.

3. Click Debug Start .

This builds an executable file containing your application and deploys it to the emulator. The process may
take some time, especially if it must deploy the Microsoft .NET Compact Framework before running the
application.
4. If errors are reported, use the following checklist to ensure that your deployment was completed
successfully:
○ Confirm that the application is deployed into \Program Files\appname, where appname is the
name you gave your application in Lesson 1 (CSApp or VBApp).
○ Confirm that the path to the database file in your application code is correct.
○ Confirm that you chose Link File when adding the database file to the project and you set the Build
Action to Content Only and Copy to Output Directory is set to Copy Always. If you did not set these
options correctly, the files will not be deployed to the device.
○ Ensure that you added a reference to the correct version of ulnet17.dll for your target platform, or
ran the Microsoft Windows Mobile installer. For versions of Microsoft Windows Mobile earlier than
Microsoft Windows Mobile 5.0, if you switch between the emulator and a real device, you must change
the version of the library that you use.
○ You may want to exit the emulator without saving the emulator state. Redeploying the application
copies all required files to the emulator, and ensures there are no version problems.
5. Test your application:
a. Insert data into the database.

Enter a name in the text box and click Insert. The name should now appear in the listbox.
b. Update data in the database.

Click a name in the listbox. Enter a new name in the text box. Click Update.

The new name should now appear in place of the old name in the listbox.
c. Delete data from the database.

Click a name in the list. Click Delete.

The name no longer appears in the list.

Results

The application is tested and can be deployed.

Task overview: Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET [page 29]

UltraLite - .NET API Reference

42 PUBLIC Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET
Previous task: Lesson 4: Inserting, updating, and deleting data [page 37]

Next: Code listing for C# tutorial [page 43]

3.6 Code listing for C# tutorial

Following is the complete code for the tutorial program described in the preceding sections.

using Sap.Data.UltraLite;
using System;
using System.Linq;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
namespace CSApp
{
public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
}
private ULConnection Conn;
private int[] ids;
private void Form1_Load(object sender, EventArgs e)
{
try
{
String ConnString = "dbf=\\Program Files\\CSApp\\CSApp.udb";
Conn = new ULConnection(ConnString);
Conn.Open();
Conn.DatabaseID = 1;
RefreshListBox();
}
catch (System.Exception t)
{
MessageBox.Show("Exception: " + t.Message);
}
}
private void RefreshListBox()
{
try
{
long NumRows;
int I = 0;
lbNames.Items.Clear();
using (ULCommand cmd = Conn.CreateCommand())
{
cmd.CommandText = "SELECT ID, Name FROM Names";
using (ULDataReader dr = cmd.ExecuteReader())
{
dr.MoveBeforeFirst();
NumRows = dr.RowCount;
ids = new int[NumRows];
while (dr.MoveNext())
{
lbNames.Items.Add(
dr.GetString(1));

UltraLite - .NET API Reference

Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET PUBLIC 43
 ids[i] = dr.GetInt32(0);
I++;
}
}
txtName.Text = " ";
}
}
catch (Exception err)
{
MessageBox.Show(
"Exception in RefreshListBox: " + err.Message);
}
}
private void btnInsert_Click(object sender, EventArgs e)
{
try
{
long RowsInserted;
using (ULCommand cmd = Conn.CreateCommand())
{
cmd.CommandText =
"INSERT INTO Names(name) VALUES (?)";
cmd.Parameters.Add("", txtName.Text);
RowsInserted = cmd.ExecuteNonQuery();
}
RefreshListBox();
}
catch (Exception err)
{
MessageBox.Show("Exception: " + err.Message);
}
}
private void btnUpdate_Click(object sender, EventArgs e)
{
try
{
long RowsUpdated;
int updateID = ids[lbNames.SelectedIndex];
using (ULCommand cmd = Conn.CreateCommand())
{
cmd.CommandText =
"UPDATE Names SET name = ? WHERE id = ?";
cmd.Parameters.Add("", txtName.Text);
cmd.Parameters.Add("", updateID);
RowsUpdated = cmd.ExecuteNonQuery();
}
RefreshListBox();
}
catch (Exception err)
{
MessageBox.Show(
"Exception: " + err.Message);
}
}
private void btnDelete_Click(object sender, EventArgs e)
{
try
{
long RowsDeleted;
int deleteID = ids[lbNames.SelectedIndex];
using (ULCommand cmd = Conn.CreateCommand())
{
cmd.CommandText =
"DELETE From Names WHERE id = ?";
cmd.Parameters.Add("", deleteID);
RowsDeleted = cmd.ExecuteNonQuery();
}
RefreshListBox();

UltraLite - .NET API Reference

44 PUBLIC Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET
 }
catch (Exception err)
{
MessageBox.Show("Exception: " + err.Message);
}
}
}
}

Parent topic: Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET [page 29]

Previous task: Lesson 5: Building and deploying the application [page 41]

Next: Code listing for Microsoft Visual Basic tutorial [page 45]

3.7 Code listing for Microsoft Visual Basic tutorial

Following is the complete code for the tutorial program described in the preceding sections.

Imports Sap.Data.UltraLite
Public Class Form1
Dim Conn As ULConnection
Dim ids() As Integer
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As
System.EventArgs) Handles MyBase.Load
Try
Dim ConnString As String = "dbf=\Program Files\VBApp\VBApp.udb"
Conn = New ULConnection(ConnString)
Conn.Open()
Conn.DatabaseID = 1
RefreshListBox()
Catch
MsgBox("Exception: " + Err.Description)
End Try
End Sub
Private Sub RefreshListBox()
Try
Dim cmd As ULCommand = Conn.CreateCommand()
Dim I As Integer = 0
lbNames.Items.Clear()
cmd.CommandText = "SELECT ID, Name FROM Names"
Dim dr As ULDataReader = cmd.ExecuteReader()
ReDim ids(dr.RowCount)
While (dr.MoveNext)
lbNames.Items.Add(dr.GetString(1))
ids(I) = dr.GetInt32(0)
I = I + 1
End While
dr.Close()
txtName.Text = " "
Catch ex As Exception
MsgBox(ex.ToString)
End Try
End Sub
Private Sub btnInsert_Click(ByVal sender As System.Object, ByVal e As
System.EventArgs) Handles btnInsert.Click
Try
Dim RowsInserted As Long

UltraLite - .NET API Reference

Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET PUBLIC 45
 Dim cmd As ULCommand = Conn.CreateCommand()
cmd.CommandText = "INSERT INTO Names(name) VALUES (?)"
cmd.Parameters.Add("", txtName.Text)
RowsInserted = cmd.ExecuteNonQuery()
cmd.Dispose()
RefreshListBox()
Catch
MsgBox("Exception: " + Err.Description)
End Try
End Sub
Private Sub btnUpdate_Click(ByVal sender As System.Object, ByVal e As
System.EventArgs) Handles btnUpdate.Click
Try
Dim RowsUpdated As Long
Dim updateID As Integer = ids(lbNames.SelectedIndex)
Dim cmd As ULCommand = Conn.CreateCommand()
cmd.CommandText = "UPDATE Names SET name = ? WHERE id = ?"
cmd.Parameters.Add("", txtName.Text)
cmd.Parameters.Add("", updateID)
RowsUpdated = cmd.ExecuteNonQuery()
cmd.Dispose()
RefreshListBox()
Catch
MsgBox("Exception: " + Err.Description)
End Try
End Sub
Private Sub btnDelete_Click(ByVal sender As System.Object, ByVal e As
System.EventArgs) Handles btnDelete.Click
Try
Dim RowsDeleted As Long
Dim deleteID As Integer = ids(lbNames.SelectedIndex)
Dim cmd As ULCommand = Conn.CreateCommand()
cmd.CommandText = "DELETE From Names WHERE id = ?"
cmd.Parameters.Add("", deleteID)
RowsDeleted = cmd.ExecuteNonQuery()
cmd.Dispose()
RefreshListBox()
Catch
MsgBox("Exception: " + Err.Description)
End Try
End Sub
End Class

Parent topic: Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET [page 29]

Previous: Code listing for C# tutorial [page 43]

UltraLite - .NET API Reference

46 PUBLIC Tutorial: Building a Microsoft Windows Mobile application using UltraLite.NET
4 UltraLite .NET API reference

You can write .NET applications for UltraLite by using the API for the UltraLite.NET Data Provider for .NET
Framework 2.0 and .NET Compact Framework 2.0.

The following list describes some of the more commonly-used high level classes for the Sap.Data.UltraLite
namespace:

ULConnection

Each ULConnection object represents a connection to an UltraLite database. You can create one or more
ULConnection objects.
ULTable

Each ULTable object provides access to the data in a single table.

ULCommand object

Each ULCommand object holds a SQL statement to be executed against the database.
ULDataReader object

Each ULDataReader object holds the result set for a single query.
ULSyncParms

You use the ULSyncParms object to synchronize your UltraLite database with a MobiLink server.

Many of the properties and methods in this chapter are very similar to the .NET Framework Data Provider for
OLE DB (System.Data.OleDb). You can find more information and examples in the Microsoft .NET Framework
documentation.

In this section:

UltraLite .NET API [page 47]

Use the API for the UltraLite.NET Data Provider for .NET Framework 2.0 and .NET Compact Framework
2.0 to write .NET applications for UltraLite.

4.1 UltraLite .NET API

Use the API for the UltraLite.NET Data Provider for .NET Framework 2.0 and .NET Compact Framework 2.0 to
write .NET applications for UltraLite.

Namespace

Sap.Data.UltraLite

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 47
UltraLite.NET extensions that are not available in the SQL Anywhere Data Provider for ADO.NET are denoted in
this API reference with UL Ext.:.

To use the UltraLite Engine runtime of UltraLite.NET, set the RuntimeType property to the appropriate value
before using any other UltraLite.NET API.

The assembly uses a satellite resource assembly named Sap.Data.UltraLite.resources. The main assembly
searches for this resource assembly by culture, using the following order:

● CultureInfo.CurrentUICulture
● CultureInfo.CurrentCulture
● EN

In this section:

ULActiveSyncListener interface [page 51]

UL Ext: The listener interface for receiving ActiveSync events.

ULBulkCopy class [page 53]

Efficiently bulk loads an UltraLite table with data from another source.

ULBulkCopyColumnMapping class [page 68]

Defines the mapping between a column in a ULBulkCopy instance's data source and a column in the
instance's destination table.

ULBulkCopyColumnMappingCollection class [page 77]

A collection of ULBulkCopyColumnMapping objects that inherits from
System.Collections.CollectionBase.

ULCommand class [page 88]

Represents a pre-compiled SQL statement or query, with or without IN parameters.

ULCommandBuilder class [page 135]

Automatically generates single-table commands used to reconcile changes made to a
System.Data.DataSet with the associated database.

ULConnection class [page 151]

Represents a connection to an UltraLite.NET database.

ULConnectionParms class [page 216]

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

ULConnectionStringBuilder class [page 226]

Builds a connection string for opening a connection to an UltraLite database.

ULCreateParms class [page 243]

UL Ext: Builds a string of creation-time options for creating an UltraLite database.

ULCursorSchema class [page 255]

UL Ext: Represents the schema of an UltraLite.NET cursor.

ULDataAdapter class [page 267]

Represents a set of commands and a database connection used to fill a System.Data.DataSet and to
update a database.

ULDatabaseManager class [page 283]

UL Ext: Provides static methods for creating, deleting, and validating databases.

ULDatabaseSchema class [page 292]

UltraLite - .NET API Reference

48 PUBLIC UltraLite .NET API reference
 UL Ext: Represents the schema of an UltraLite.NET database.

ULDataReader class [page 302]

Represents a read-only bi-directional cursor in an UltraLite database.

ULException class [page 354]

Represents a SQL error returned by the UltraLite.NET database.

ULFactory class [page 356]

Represents a set of methods for creating instances of the Sap.Data.UltraLite provider's implementation
of the data source classes.

ULFileTransfer class [page 362]

UL Ext: Transfers a file from a remote database using the MobiLink server.

ULFileTransferProgressData class [page 383]

UL Ext: Returns file transfer progress monitoring data.

ULFileTransferProgressListener interface [page 386]

UL Ext: The listener interface for receiving file transfer progress events.

ULIndexSchema class [page 388]

UL Ext: Represents the schema of an UltraLite table index.

ULInfoMessageEventArgs class [page 398]

Provides data for the ULConnection.InfoMessage event.

ULMetaDataCollectionNames class [page 401]

Provides a list of constants for use with the ULConnection.GetSchema(String,String[]) method to
retrieve metadata collections.

ULParameter class [page 413]

Represents a parameter to a ULCommand object.

ULParameterCollection class [page 433]

Represents all parameters to a ULCommand object.

ULResultSet class [page 463]

UL Ext: Represents an editable result set in an UltraLite database.

ULResultSetSchema class [page 494]

UL Ext: Represents the schema of an UltraLite result set.

ULRowsCopiedEventArgs class [page 497]

Represents the set of arguments passed to the ULRowsCopiedEventHandler object.

ULRowUpdatedEventArgs class [page 499]

Provides data for the ULDataAdapter.RowUpdated event.

ULRowUpdatingEventArgs class [page 502]

Provides data for the ULDataAdapter.RowUpdating event.

ULServerSyncListener interface [page 505]

UL Ext: The listener interface for receiving server synchronization messages.

ULSqlProgressData class (Deprecated) [page 507]

UL Ext: Returns SQL passthrough script progress monitoring data.

ULSyncParms class [page 509]

UL Ext: Represents synchronization parameters that define how to synchronize an UltraLite database.

ULSyncProgressData class [page 525]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 49
 UL Ext: Returns synchronization progress monitoring data.

ULSyncProgressListener interface [page 540]

UL Ext: The listener interface for receiving synchronization progress events.

ULSyncResult class [page 542]

UL Ext: Represents the status of the last synchronization.

ULTable class [page 548]

UL Ext: Represents a table in an UltraLite database.

ULTableSchema class [page 578]

UL Ext: Represents the schema of an UltraLite table.

ULTransaction class [page 598]

Represents a SQL transaction.

ULInfoMessageEventHandler(object, ULInfoMessageEventArgs) delegate [page 603]

Represents the method that handles the ULConnection.InfoMessage event.

ULRowsCopiedEventHandler(object, ULRowsCopiedEventArgs) delegate [page 604]

Represents the method that handles the ULBulkCopy.ULRowsCopied event.

ULRowUpdatedEventHandler(object, ULRowUpdatedEventArgs) delegate [page 604]

Represents the method that handles the ULDataAdapter.RowUpdated event.

ULRowUpdatingEventHandler(object, ULRowUpdatingEventArgs) delegate [page 605]

Represents the method that handles the ULDataAdapter.RowUpdating event.

ULSyncProgressedDlg(IAsyncResult, ULSyncProgressData) delegate [page 606]

Represents the method that is invoked during synchronization with synchronization progress
information.

ULAuthStatusCode enumeration [page 607]

UL Ext: Enumerates the status codes that may be reported during MobiLink user authentication.

ULBulkCopyOptions enumeration [page 608]

A bitwise flag that specifies one or more options to use with an instance of the ULBulkCopy class.

ULDateOrder enumeration [page 609]

UL Ext: Enumerates the date orders that a database can support.

ULDbType enumeration [page 609]

Enumerates the UltraLite.NET database data types.

ULDBValid enumeration [page 612]

Enumerates the UltraLite.NET database validation methods

ULRuntimeType enumeration [page 613]

UL Ext: Enumerates the types of UltraLite.NET runtimes.

ULSqlProgressState enumeration [page 614]

UL Ext: Enumerates all the states that can occur while executing SQL passthrough scripts.

ULStreamType enumeration [page 615]

UL Ext: Enumerates the types of MobiLink synchronization streams to use for synchronization.

ULSyncProgressState enumeration [page 616]

UL Ext: Enumerates all the states that can occur while synchronizing.

UltraLite - .NET API Reference

50 PUBLIC UltraLite .NET API reference
4.1.1 ULActiveSyncListener interface

UL Ext: The listener interface for receiving ActiveSync events.

 Syntax

Visual Basic

Public Interface ULActiveSyncListener

C#

public interface ULActiveSyncListener

Members

All members of ULActiveSyncListener, including inherited members.

Methods

Modifier and Type Method Description

public void ActiveSyncInvoked(bool) [page 51] Invoked when the MobiLink provider for
ActiveSync calls the application to per­
form synchronization.

In this section:

ActiveSyncInvoked(bool) method [page 51]

Invoked when the MobiLink provider for ActiveSync calls the application to perform synchronization.

4.1.1.1 ActiveSyncInvoked(bool) method

Invoked when the MobiLink provider for ActiveSync calls the application to perform synchronization.

 Syntax

Visual Basic

Public Sub ActiveSyncInvoked (ByVal launchedByProvider As Boolean)

C#

public void ActiveSyncInvoked (bool launchedByProvider)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 51
Parameters

launchedByProvider True if the application was launched by the MobiLink provider to perform ActiveSync
synchronization. The application must then shut itself down after it has finished synchronizing. False if the
application was already running when called by the MobiLink provider for ActiveSync.

Remarks

This method is invoked by a separate thread. To avoid multi-threading issues, it should post an event to the UI.
If you are using multi-threading, use a separate connection and use the lock keyword to access any objects
shared with the rest of the application.

Once synchronization has completed, applications should call the ULDatabaseManager.SignalSyncIsComplete

method to signal the MobiLink provider for ActiveSync.

 Example

The following code fragments demonstrate how to receive an ActiveSync request and perform a
synchronization in the UI thread:

' Visual Basic

Imports Sap.Data.UltraLite
Public Class MainWindow
Inherits System.Windows.Forms.Form
Implements ULActiveSyncListener
Private conn As ULConnection
Public Sub New(ByVal args() As String)
MyBase.New()
' This call is required by the Windows Form Designer.
InitializeComponent()
' Add any initialization after the InitializeComponent call.
ULConnection.DatabaseManager.SetActiveSyncListener( _
"myCompany.myapp", Me _
)
' Create Connection
...
End Sub
Protected Overrides Sub OnClosing( _
ByVal e As System.ComponentModel.CancelEventArgs _
)
ULConnection.DatabaseManager.SetActiveSyncListener( _
Nothing, Nothing _
)
MyBase.OnClosing(e)
End Sub
Public Sub ActiveSyncInvoked( _
ByVal launchedByProvider As Boolean _
) Implements ULActiveSyncListener.ActiveSyncInvoked
Me.Invoke(New EventHandler(AddressOf Me.ActiveSyncAction))
End Sub
Public Sub ActiveSyncAction( _
ByVal sender As Object, ByVal e As EventArgs _
)
' Perform active sync.
conn.Synchronize()
ULConnection.DatabaseManager.SignalSyncIsComplete()
End Sub
End Class

UltraLite - .NET API Reference

52 PUBLIC UltraLite .NET API reference
 The following code is the C# language equivalent:

// C#
using Sap.Data.UltraLite;
public class Form1 : System.Windows.Forms.Form, ULActiveSyncListener
{
private System.Windows.Forms.MainMenu mainMenu1;
private ULConnection conn;
public Form1()
{
//
// Required for Windows Form Designer support.
// InitializeComponent();
//
// TODO: Add any constructor code after the
// InitializeComponent call.
//
ULDatabaseManager.SetActiveSyncListener(
"myCompany.myapp", this
);
// Create connection
...
}
protected override void Dispose( bool disposing )
{
base.Dispose( disposing );
}
protected override void OnClosing(
System.ComponentModel.CancelEventArgs e )
{
ULDatabaseManager.SetActiveSyncListener(null, null);
base.OnClosing(e);
}
public void ActiveSyncInvoked(bool launchedByProvider)
{
this.Invoke( new EventHandler( ActiveSyncHandler ) );
}
internal void ActiveSyncHandler(object sender, EventArgs e)
{
conn.Synchronize();
ULDatabaseManager.SignalSyncIsComplete();
}
}

Related Information

SignalSyncIsComplete() method [page 290]

4.1.2 ULBulkCopy class

Efficiently bulk loads an UltraLite table with data from another source.

 Syntax

Visual Basic

Public NotInheritable Class ULBulkCopy Implements System.IDisposable

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 53
 C#

public sealed class ULBulkCopy : System.IDisposable

Members

All members of ULBulkCopy, including inherited members.

Constructors

Modifier and Type Constructor Description

public ULBulkCopy [page 56] Initializes a ULBulkCopy object with the

specified ULConnection object.

Methods

Modifier and Type Method Description

public void Close() [page 60] Closes the ULBulkCopy object.

public void Dispose() [page 60] Disposes of the ULBulkCopy object.

public void WriteToServer [page 61] Copies all rows in the supplied array of
System.Data.DataRow objects to a des­
tination table specified by the Destina­
tionTableName field of the ULBulkCopy
object.

Properties

Modifier and Type Property Description

public int BatchSize [page 64] Gets or sets the number of rows in each
batch.

public int BulkCopyTimeout [page 65] Gets or sets the number of seconds for
the operation to complete before it
times out.

public ULBulkCopyColumnMappingCol­ ColumnMappings [page 65] Returns a collection of ULBulkCopyCo­

lection lumnMapping items.

public string DestinationTableName [page 66] Gets or sets the name of the destina­
tion table on the server.

public int NotifyAfter [page 67] Specifies the number of rows to be

processed before generating a notifica­
tion event.

Events

UltraLite - .NET API Reference

54 PUBLIC UltraLite .NET API reference
 Modifier and Type Event Description

public ULRowsCopiedEventHandler ULRowsCopied [page 67] This event occurs every time the num­
ber of rows specified by the NotifyAfter
property have been processed.

Remarks

The ULBulkCopy class is not available in the .NET Compact Framework 2.0.

In this section:

ULBulkCopy constructor [page 56]

Initializes a ULBulkCopy object with the specified ULConnection object.

Close() method [page 60]

Closes the ULBulkCopy object.

Dispose() method [page 60]

Disposes of the ULBulkCopy object.

WriteToServer method [page 61]

Copies all rows in the supplied array of System.Data.DataRow objects to a destination table specified
by the DestinationTableName field of the ULBulkCopy object.

BatchSize property [page 64]

Gets or sets the number of rows in each batch.

BulkCopyTimeout property [page 65]

Gets or sets the number of seconds for the operation to complete before it times out.

ColumnMappings property [page 65]

Returns a collection of ULBulkCopyColumnMapping items.

DestinationTableName property [page 66]

Gets or sets the name of the destination table on the server.

NotifyAfter property [page 67]

Specifies the number of rows to be processed before generating a notification event.

ULRowsCopied event [page 67]

This event occurs every time the number of rows specified by the NotifyAfter property have been
processed.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 55
4.1.2.1 ULBulkCopy constructor

Initializes a ULBulkCopy object with the specified ULConnection object.

Overload list

Modifier and Type Overload name Description

public ULBulkCopy(ULConnection) [page Initializes a ULBulkCopy object with the

56] specified ULConnection object.

public ULBulkCopy(ULConnection, ULBulkCo­ Initializes a ULBulkCopy object with the

pyOptions, ULTransaction) [page 57] specified ULConnection object, copy
options, and ULTransaction object.

public ULBulkCopy(string) [page 58] Initializes a ULBulkCopy object with the

specified connection string.

public ULBulkCopy(string, ULBulkCopyOp­ Initializes a ULBulkCopy object with the

tions) [page 59] specified connection string, and copy
options.

In this section:

ULBulkCopy(ULConnection) constructor [page 56]

Initializes a ULBulkCopy object with the specified ULConnection object.

ULBulkCopy(ULConnection, ULBulkCopyOptions, ULTransaction) constructor [page 57]

Initializes a ULBulkCopy object with the specified ULConnection object, copy options, and
ULTransaction object.

ULBulkCopy(string) constructor [page 58]

Initializes a ULBulkCopy object with the specified connection string.

ULBulkCopy(string, ULBulkCopyOptions) constructor [page 59]

Initializes a ULBulkCopy object with the specified connection string, and copy options.

4.1.2.1.1 ULBulkCopy(ULConnection) constructor

Initializes a ULBulkCopy object with the specified ULConnection object.

 Syntax

Visual Basic

Public Sub ULBulkCopy (ByVal connection As ULConnection)

C#

public ULBulkCopy (ULConnection connection)

UltraLite - .NET API Reference

56 PUBLIC UltraLite .NET API reference
Parameters

connection The ULConnection object that is used to perform the bulk-copy operation. If the connection is
not open, an exception is thrown during a WriteToServer method call.

Remarks

The ULBulkCopy class is not available in the .NET Compact Framework 2.0.

Related Information

ULConnection class [page 151]

4.1.2.1.2 ULBulkCopy(ULConnection, ULBulkCopyOptions,

ULTransaction) constructor

Initializes a ULBulkCopy object with the specified ULConnection object, copy options, and ULTransaction
object.

 Syntax

Visual Basic

Public Sub ULBulkCopy (

ByVal connection As ULConnection,
ByVal copyOptions As ULBulkCopyOptions,
ByVal externalTransaction As ULTransaction
)

C#

public ULBulkCopy (
ULConnection connection,
ULBulkCopyOptions copyOptions,
ULTransaction externalTransaction
)

Parameters

connection The ULConnection object that is used to perform the bulk-copy operation. If the connection is
not open, an exception is thrown during a WriteToServer method call.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 57
 copyOptions A combination of values from the ULBulkCopyOptions enumeration that determines how
data source rows are copied to the destination table.
externalTransaction An existing ULTransaction object under which the bulk copy occurs. If this value is not
a null reference (Nothing in Visual Basic), then the bulk-copy operation is done within it. It is an error to
specify both an external transaction and the ULBulkCopyOptions.UseInternalTransaction option.

Remarks

The ULBulkCopy class is not available in the .NET Compact Framework 2.0.

Related Information

ULConnection class [page 151]

ULTransaction class [page 598]

4.1.2.1.3 ULBulkCopy(string) constructor

Initializes a ULBulkCopy object with the specified connection string.

 Syntax

Visual Basic

Public Sub ULBulkCopy (ByVal connectionString As String)

C#

public ULBulkCopy (string connectionString)

Parameters

connectionString The string defining the connection to be opened for use by the ULBulkCopy object. A
connection string is a semicolon-separated list of keyword=value pairs.

Remarks

The ULBulkCopy class is not available in the .NET Compact Framework 2.0.

UltraLite - .NET API Reference

58 PUBLIC UltraLite .NET API reference
This syntax opens a connection during a WriteToServer method call with the connectionString value. The
connection is closed at the end of the WriteToServer call.

The connection string can be supplied using a ULConnectionParms object.

Related Information

ConnectionString property [page 206]

ULConnectionParms class [page 216]

4.1.2.1.4 ULBulkCopy(string, ULBulkCopyOptions)

constructor

Initializes a ULBulkCopy object with the specified connection string, and copy options.

 Syntax

Visual Basic

Public Sub ULBulkCopy (

ByVal connectionString As String,
ByVal copyOptions As ULBulkCopyOptions
)

C#

public ULBulkCopy (
string connectionString,
ULBulkCopyOptions copyOptions
)

Parameters

connectionString The string defining the connection to be opened for use by the ULBulkCopy object. A
connection string is a semicolon-separated list of keyword=value pairs.
copyOptions A combination of values from the ULBulkCopyOptions enumeration that determines how
data source rows are copied to the destination table.

Remarks

The ULBulkCopy class is not available in the .NET Compact Framework 2.0.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 59
This syntax opens a connection during a WriteToServer method call with the connectionString value. The
connection is closed at the end of the WriteToServer call.

Related Information

ConnectionString property [page 206]

ULBulkCopyOptions enumeration [page 608]

4.1.2.2 Close() method

Closes the ULBulkCopy object.

 Syntax

Visual Basic

Public Sub Close ()

C#

public void Close ()

4.1.2.3 Dispose() method

Disposes of the ULBulkCopy object.

 Syntax

Visual Basic

Public Sub Dispose ()

C#

public void Dispose ()

UltraLite - .NET API Reference

60 PUBLIC UltraLite .NET API reference
4.1.2.4 WriteToServer method

Copies all rows in the supplied array of System.Data.DataRow objects to a destination table specified by the
DestinationTableName field of the ULBulkCopy object.

Overload list

Modifier and Type Overload name Description

public void WriteToServer(DataRow[]) [page 62] Copies all rows in the supplied array of
System.Data.DataRow objects to a des­
tination table specified by the Destina­
tionTableName field of the ULBulkCopy
object.

public void WriteToServer(DataTable) [page 62] Copies all rows in the supplied Sys­
tem.Data.DataTable to a destination ta­
ble specified by the ULBulkCopy.Desti­
nationTableName property.

public void WriteToServer(DataTable, DataRow­ Copies all rows in the supplied Sys­
State) [page 63] tem.Data.DataTable with the specified
row state to a destination table speci­
fied by the ULBulkCopy.DestinationTa­
bleName property.

public void WriteToServer(IDataReader) [page 64] Copies all rows in the supplied Sys­
tem.Data.IDataReader to a destination
table specified by the ULBulkCopy.Des­
tinationTableName property.

In this section:

WriteToServer(DataRow[]) method [page 62]

Copies all rows in the supplied array of System.Data.DataRow objects to a destination table specified
by the DestinationTableName field of the ULBulkCopy object.

WriteToServer(DataTable) method [page 62]

Copies all rows in the supplied System.Data.DataTable to a destination table specified by the
ULBulkCopy.DestinationTableName property.

WriteToServer(DataTable, DataRowState) method [page 63]

Copies all rows in the supplied System.Data.DataTable with the specified row state to a destination
table specified by the ULBulkCopy.DestinationTableName property.

WriteToServer(IDataReader) method [page 64]

Copies all rows in the supplied System.Data.IDataReader to a destination table specified by the
ULBulkCopy.DestinationTableName property.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 61
4.1.2.4.1 WriteToServer(DataRow[]) method

Copies all rows in the supplied array of System.Data.DataRow objects to a destination table specified by the
DestinationTableName field of the ULBulkCopy object.

 Syntax

Visual Basic

Public Sub WriteToServer (ByVal rows As DataRow())

C#

public void WriteToServer (DataRow[] rows)

Parameters

rows An array of System.Data.DataRow objects to be copied to the destination table.

Related Information

DestinationTableName property [page 66]

4.1.2.4.2 WriteToServer(DataTable) method

Copies all rows in the supplied System.Data.DataTable to a destination table specified by the
ULBulkCopy.DestinationTableName property.

 Syntax

Visual Basic

Public Sub WriteToServer (ByVal table As DataTable)

C#

public void WriteToServer (DataTable table)

Parameters

table A System.Data.DataTable whose rows to be copied to the destination table.

UltraLite - .NET API Reference

62 PUBLIC UltraLite .NET API reference
Related Information

DestinationTableName property [page 66]

4.1.2.4.3 WriteToServer(DataTable, DataRowState) method

Copies all rows in the supplied System.Data.DataTable with the specified row state to a destination table
specified by the ULBulkCopy.DestinationTableName property.

 Syntax

Visual Basic

Public Sub WriteToServer (

ByVal table As DataTable,
ByVal rowState As DataRowState
)

C#

public void WriteToServer (

DataTable table,
DataRowState rowState
)

Parameters

table A System.Data.DataTable whose rows to be copied to the destination table.

rowState A value from the System.Data.DataRowState enumeration. Only rows matching the row state are
copied to the destination.

Remarks

If the rowState parameter is specified, then only those rows that have the same row state are copied.

Related Information

DestinationTableName property [page 66]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 63
4.1.2.4.4 WriteToServer(IDataReader) method

Copies all rows in the supplied System.Data.IDataReader to a destination table specified by the
ULBulkCopy.DestinationTableName property.

 Syntax

Visual Basic

Public Sub WriteToServer (ByVal reader As IDataReader)

C#

public void WriteToServer (IDataReader reader)

Parameters

reader A System.Data.IDataReader whose rows to be copied to the destination table.

Related Information

DestinationTableName property [page 66]

4.1.2.5 BatchSize property

Gets or sets the number of rows in each batch.

 Syntax

Visual Basic

Public Property BatchSize As Integer

C#

public int BatchSize {get;set;}

Remarks

At the end of each batch, the rows in the batch are sent to the server.

The number of rows in each batch. The default is 0.

UltraLite - .NET API Reference

64 PUBLIC UltraLite .NET API reference
Setting it to zero causes all the rows to be sent in one batch.

Setting it less than zero is an error.

If this value is changed while a batch is in progress, the current batch completes and any further batches use
the new value.

4.1.2.6 BulkCopyTimeout property

Gets or sets the number of seconds for the operation to complete before it times out.

 Syntax

Visual Basic

Public Property BulkCopyTimeout As Integer

C#

public int BulkCopyTimeout {get;set;}

Remarks

The default value is 30 seconds.

Setting a value of zero indicates no limit, which should be avoided because it may cause an indefinite wait.

If the operation times out, then all rows in the current transaction are rolled back and an SAException error is
thrown.

Setting a value that is less than zero would throw an error.

4.1.2.7 ColumnMappings property

Returns a collection of ULBulkCopyColumnMapping items.

 Syntax

Visual Basic

Public ReadOnly Property ColumnMappings As

ULBulkCopyColumnMappingCollection

C#

public ULBulkCopyColumnMappingCollection ColumnMappings {get;}

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 65
Remarks

Column mappings define the relationships between columns in the data source and columns in the destination.

By default, it is an empty collection.

The property cannot be modified while a WriteToServer method call is executing.

If the ColumnMappings object is empty when the WriteToServer method is executed, then the first column in
the source is mapped to the first column in the destination, the second is mapped to the second, and so on.
This takes place as long as the column types are convertible, there are at least as many destination columns as
source columns, and any extra destination columns are nullable.

Related Information

ULBulkCopyColumnMapping class [page 68]

4.1.2.8 DestinationTableName property

Gets or sets the name of the destination table on the server.

 Syntax

Visual Basic

Public Property DestinationTableName As String

C#

public string DestinationTableName {get;set;}

Remarks

The default value is a null reference (Nothing in Visual Basic).

If the value is changed while a WriteToServer call is executing, the change has no effect.

If the value has not been set before a call to the WriteToServer method, an InvalidOperationException error is
thrown.

It is an error to set the value to null (Nothing in Visual Basic) or the empty string.

UltraLite - .NET API Reference

66 PUBLIC UltraLite .NET API reference
4.1.2.9 NotifyAfter property

Specifies the number of rows to be processed before generating a notification event.

 Syntax

Visual Basic

Public Property NotifyAfter As Integer

C#

public int NotifyAfter {get;set;}

Remarks

An integer representing the number of rows to be processed before generating a notification event, or zero is if
the property has not been set.

Changes made to this property, while executing the WriteToServer method, do not take effect until after the
next notification.

Setting this value ta a value that is less than zero throws an error.

The values of NotifyAfter and BulkCopyTimeout properties are mutually exclusive, so the event can fire even if
no rows have been sent to the database or committed.

Related Information

BulkCopyTimeout property [page 65]

4.1.2.10 ULRowsCopied event

This event occurs every time the number of rows specified by the NotifyAfter property have been processed.

 Syntax

Visual Basic

Public Event ULRowsCopied As ULRowsCopiedEventHandler

C#

public ULRowsCopiedEventHandler ULRowsCopied;

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 67
Remarks

The receipt of a ULRowsCopied event does not imply that any rows have been committed. You cannot call the
Close method from this event.

Related Information

NotifyAfter property [page 67]

4.1.3 ULBulkCopyColumnMapping class

Defines the mapping between a column in a ULBulkCopy instance's data source and a column in the instance's
destination table.

 Syntax

Visual Basic

Public NotInheritable Class ULBulkCopyColumnMapping

C#

public sealed class ULBulkCopyColumnMapping

Members

All members of ULBulkCopyColumnMapping, including inherited members.

Constructors

Modifier and Type Constructor Description

public ULBulkCopyColumnMapping [page Creates a new column mapping.

69]

Properties

Modifier and Type Property Description

public string DestinationColumn [page 74] Specifies the name of the column in the
destination database table being map­
ped to.

public int DestinationOrdinal [page 75] Specifies the ordinal value of the col­
umn in the destination database table
being mapped to.

UltraLite - .NET API Reference

68 PUBLIC UltraLite .NET API reference
 Modifier and Type Property Description

public string SourceColumn [page 75] Specifies the name of the column being
mapped in the data source.

public int SourceOrdinal [page 76] Specifies the ordinal position of the
source column within the data source.

Remarks

The ULBulkCopyColumnMapping class is not available in the .NET Compact Framework 2.0.

In this section:

ULBulkCopyColumnMapping constructor [page 69]

Creates a new column mapping.

DestinationColumn property [page 74]

Specifies the name of the column in the destination database table being mapped to.

DestinationOrdinal property [page 75]

Specifies the ordinal value of the column in the destination database table being mapped to.

SourceColumn property [page 75]

Specifies the name of the column being mapped in the data source.

SourceOrdinal property [page 76]

Specifies the ordinal position of the source column within the data source.

Related Information

ULBulkCopy class [page 53]

4.1.3.1 ULBulkCopyColumnMapping constructor

Creates a new column mapping.

Overload list

Modifier and Type Overload name Description

public ULBulkCopyColumnMapping() [page Creates a new column mapping.

70]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 69
Modifier and Type Overload name Description

public ULBulkCopyColumnMapping(int, int) Creates a new column mapping, using

[page 71] column ordinals or names to refer to
source and destination columns.

public ULBulkCopyColumnMapping(int, Creates a new column mapping, using a

string) [page 72] column ordinal to refer to the source
column and a column name to refer to
the destination column.

public ULBulkCopyColumnMapping(string, Creates a new column mapping, using a

int) [page 72] column name to refer to the source col­
umn and a column ordinal to refer to
the destination the column.

public ULBulkCopyColumnMapping(string, Creates a new column mapping, using

string) [page 73] column names to refer to source and
destination columns.

In this section:

ULBulkCopyColumnMapping() constructor [page 70]

Creates a new column mapping.

ULBulkCopyColumnMapping(int, int) constructor [page 71]

Creates a new column mapping, using column ordinals or names to refer to source and destination
columns.

ULBulkCopyColumnMapping(int, string) constructor [page 72]

Creates a new column mapping, using a column ordinal to refer to the source column and a column
name to refer to the destination column.

ULBulkCopyColumnMapping(string, int) constructor [page 72]

Creates a new column mapping, using a column name to refer to the source column and a column
ordinal to refer to the destination the column.

ULBulkCopyColumnMapping(string, string) constructor [page 73]

Creates a new column mapping, using column names to refer to source and destination columns.

4.1.3.1.1 ULBulkCopyColumnMapping() constructor

Creates a new column mapping.

 Syntax

Visual Basic

Public Sub ULBulkCopyColumnMapping ()

C#

public ULBulkCopyColumnMapping ()

UltraLite - .NET API Reference

70 PUBLIC UltraLite .NET API reference
Remarks

The ULBulkCopyColumnMapping class is not available in the .NET Compact Framework 2.0.

4.1.3.1.2 ULBulkCopyColumnMapping(int, int) constructor

Creates a new column mapping, using column ordinals or names to refer to source and destination columns.

 Syntax

Visual Basic

Public Sub ULBulkCopyColumnMapping (

ByVal sourceColumnOrdinal As Integer,
ByVal destinationColumnOrdinal As Integer
)

C#

public ULBulkCopyColumnMapping (
int sourceColumnOrdinal,
int destinationColumnOrdinal
)

Parameters

sourceColumnOrdinal The ordinal position of the source column within the data source. The first column
in a data source has ordinal position zero.
destinationColumnOrdinal The ordinal position of the destination column within the destination table. The
first column in a table has ordinal position zero.

Remarks

The ULBulkCopyColumnMapping class is not available in the .NET Compact Framework 2.0.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 71
4.1.3.1.3 ULBulkCopyColumnMapping(int, string)
constructor

Creates a new column mapping, using a column ordinal to refer to the source column and a column name to
refer to the destination column.

 Syntax

Visual Basic

Public Sub ULBulkCopyColumnMapping (

ByVal sourceColumnOrdinal As Integer,
ByVal destinationColumn As String
)

C#

public ULBulkCopyColumnMapping (
int sourceColumnOrdinal,
string destinationColumn
)

Parameters

sourceColumnOrdinal The ordinal position of the source column within the data source. The first column
in a data source has ordinal position zero.
destinationColumn The name of the destination column within the destination table.

Remarks

The ULBulkCopyColumnMapping class is not available in the .NET Compact Framework 2.0.

4.1.3.1.4 ULBulkCopyColumnMapping(string, int)

constructor

Creates a new column mapping, using a column name to refer to the source column and a column ordinal to
refer to the destination the column.

 Syntax

Visual Basic

Public Sub ULBulkCopyColumnMapping (

ByVal sourceColumn As String,
ByVal destinationColumnOrdinal As Integer

UltraLite - .NET API Reference

72 PUBLIC UltraLite .NET API reference
 )

C#

public ULBulkCopyColumnMapping (
string sourceColumn,
int destinationColumnOrdinal
)

Parameters

sourceColumn The name of the source column within the data source.
destinationColumnOrdinal The ordinal position of the destination column within the destination table. The
first column in a table has ordinal position zero.

Remarks

The ULBulkCopyColumnMapping class is not available in the .NET Compact Framework 2.0.

4.1.3.1.5 ULBulkCopyColumnMapping(string, string)

constructor

Creates a new column mapping, using column names to refer to source and destination columns.

 Syntax

Visual Basic

Public Sub ULBulkCopyColumnMapping (

ByVal sourceColumn As String,
ByVal destinationColumn As String
)

C#

public ULBulkCopyColumnMapping (
string sourceColumn,
string destinationColumn
)

Parameters

sourceColumn The name of the source column within the data source.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 73
 destinationColumn The name of the destination column within the destination table.

Remarks

The ULBulkCopyColumnMapping class is not available in the .NET Compact Framework 2.0.

4.1.3.2 DestinationColumn property

Specifies the name of the column in the destination database table being mapped to.

 Syntax

Visual Basic

Public Property DestinationColumn As String

C#

public string DestinationColumn {get;set;}

Remarks

A string specifying the name of the column in the destination table or a null reference (Nothing in Visual Basic)
if the DestinationOrdinal property has priority.

The DestinationColumn and DestinationOrdinal properties are mutually exclusive. The most recently set value
takes priority.

Setting the DestinationColumn property causes the DestinationOrdinal property to be set to -1. Setting the
DestinationOrdinal property causes the DestinationColumn property to be set to a null reference (Nothing in
Visual Basic).

It is an error to set the DestinationColumn property to null or the empty string.

Related Information

DestinationOrdinal property [page 75]

DestinationOrdinal property [page 75]

UltraLite - .NET API Reference

74 PUBLIC UltraLite .NET API reference
4.1.3.3 DestinationOrdinal property

Specifies the ordinal value of the column in the destination database table being mapped to.

 Syntax

Visual Basic

Public Property DestinationOrdinal As Integer

C#

public int DestinationOrdinal {get;set;}

Remarks

An integer specifying the ordinal of the column being mapped to in the destination table or -1 if the property is
not set.

The DestinationColumn and DestinationOrdinal properties are mutually exclusive. The most recently set value
takes priority.

Setting the DestinationColumn property causes the DestinationOrdinal property to be set to -1. Setting the
DestinationOrdinal property causes the DestinationColumn property to be set to a null reference (Nothing in
Visual Basic).

Related Information

DestinationColumn property [page 74]

DestinationColumn property [page 74]

4.1.3.4 SourceColumn property

Specifies the name of the column being mapped in the data source.

 Syntax

Visual Basic

Public Property SourceColumn As String

C#

public string SourceColumn {get;set;}

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 75
Remarks

A string specifying the name of the column in the data source or a null reference (Nothing in Visual Basic) if the
SourceOrdinal has priority.

The SourceColumn and SourceOrdinal properties are mutually exclusive. The most recently set value takes
priority.

Setting the SourceColumn property causes the SourceOrdinal property to be set to -1. Setting the
SourceOrdinal property causes the SourceColumn property to be set to a null reference (Nothing in Visual
Basic).

It is an error to set the SourceColumn property to null or the empty string.

Related Information

SourceOrdinal property [page 76]

SourceOrdinal property [page 76]

4.1.3.5 SourceOrdinal property

Specifies the ordinal position of the source column within the data source.

 Syntax

Visual Basic

Public Property SourceOrdinal As Integer

C#

public int SourceOrdinal {get;set;}

Remarks

An integer specifying the ordinal of the column in the data source or -1 if the property is not set.

The SourceColumn and SourceOrdinal properties are mutually exclusive. The most recently set value takes
priority.

Setting the SourceColumn property causes the SourceOrdinal property to be set to -1. Setting the
SourceOrdinal property causes the SourceColumn property to be set to a null reference (Nothing in Visual
Basic).

UltraLite - .NET API Reference

76 PUBLIC UltraLite .NET API reference
Related Information

SourceColumn property [page 75]

4.1.4 ULBulkCopyColumnMappingCollection class

A collection of ULBulkCopyColumnMapping objects that inherits from System.Collections.CollectionBase.

 Syntax

Visual Basic

Public NotInheritable Class ULBulkCopyColumnMappingCollection Inherits

System.Collections.CollectionBase

C#

public sealed class ULBulkCopyColumnMappingCollection :

System.Collections.CollectionBase

Members

All members of ULBulkCopyColumnMappingCollection, including inherited members.

Methods

Modifier and Type Method Description

public ULBulkCopyColumnMapping Add [page 79] Adds the specified ULBulkCopyCo­

lumnMapping object to the collection.

public bool Contains(ULBulkCopyColumnMapping) Returns whether the specified ULBulk­

[page 85] CopyColumnMapping object exists in
the collection.

public void CopyTo(ULBulkCopyColumnMapping[], Copies the elements of the ULBulkCo­

int) [page 85] pyColumnMappingCollection object to
an array of ULBulkCopyColumnMap­
ping objects, starting at a particular in­
dex.

public int IndexOf(ULBulkCopyColumnMapping) Returns the index of the specified UL­

[page 86] BulkCopyColumnMapping object within
the collection.

public void Remove(ULBulkCopyColumnMapping) Removes the specified ULBulkCopyCo­

[page 87] lumnMapping object from the ULBulk­
CopyColumnMappingCollection object.

public new void RemoveAt(int) [page 87] Removes the mapping at the specified
index from the collection.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 77
Properties

Modifier and Type Property Description

public ULBulkCopyColumnMapping this[int index] [page 88] Gets the ULBulkCopyColumnMapping

object at the specified index.

Remarks

The ULBulkCopyColumnMappingCollection class is not available in the .NET Compact Framework 2.0.

In this section:

Add method [page 79]

Adds the specified ULBulkCopyColumnMapping object to the collection.

Contains(ULBulkCopyColumnMapping) method [page 85]

Returns whether the specified ULBulkCopyColumnMapping object exists in the collection.

CopyTo(ULBulkCopyColumnMapping[], int) method [page 85]

Copies the elements of the ULBulkCopyColumnMappingCollection object to an array of
ULBulkCopyColumnMapping objects, starting at a particular index.

IndexOf(ULBulkCopyColumnMapping) method [page 86]

Returns the index of the specified ULBulkCopyColumnMapping object within the collection.

Remove(ULBulkCopyColumnMapping) method [page 87]

Removes the specified ULBulkCopyColumnMapping object from the
ULBulkCopyColumnMappingCollection object.

RemoveAt(int) method [page 87]

Removes the mapping at the specified index from the collection.

this[int index] property [page 88]

Gets the ULBulkCopyColumnMapping object at the specified index.

Related Information

ULBulkCopyColumnMapping class [page 68]

UltraLite - .NET API Reference

78 PUBLIC UltraLite .NET API reference
4.1.4.1 Add method
Adds the specified ULBulkCopyColumnMapping object to the collection.

Overload list

Modifier and Type Overload name Description

public ULBulkCopyColumnMapping Add(ULBulkCopyColumnMapping) Adds the specified ULBulkCopyCo­

[page 80] lumnMapping object to the collection.

public ULBulkCopyColumnMapping Add(int, int) [page 81] Creates a new ULBulkCopyColumn­

Mapping object using ordinals to spec­
ify both source and destination col­
umns, and adds the mapping to the col­
lection.

public ULBulkCopyColumnMapping Add(int, string) [page 82] Creates a new ULBulkCopyColumn­

Mapping object using a column ordinal
to refer to the source column and a col­
umn name to refer to the destination
column, and adds mapping to the col­
lection.

public ULBulkCopyColumnMapping Add(string, int) [page 83] Creates a new ULBulkCopyColumn­

Mapping object using a column name
to refer to the source column and a col­
umn ordinal to refer to the destination
the column, and adds the mapping to
the collection.

public ULBulkCopyColumnMapping Add(string, string) [page 84] Creates a new ULBulkCopyColumn­

Mapping object using column names to
specify both source and destination
columns, and adds the mapping to the
collection.

In this section:

Add(ULBulkCopyColumnMapping) method [page 80]

Adds the specified ULBulkCopyColumnMapping object to the collection.

Add(int, int) method [page 81]

Creates a new ULBulkCopyColumnMapping object using ordinals to specify both source and
destination columns, and adds the mapping to the collection.

Add(int, string) method [page 82]

Creates a new ULBulkCopyColumnMapping object using a column ordinal to refer to the source column
and a column name to refer to the destination column, and adds mapping to the collection.

Add(string, int) method [page 83]

Creates a new ULBulkCopyColumnMapping object using a column name to refer to the source column
and a column ordinal to refer to the destination the column, and adds the mapping to the collection.

Add(string, string) method [page 84]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 79
 Creates a new ULBulkCopyColumnMapping object using column names to specify both source and
destination columns, and adds the mapping to the collection.

4.1.4.1.1 Add(ULBulkCopyColumnMapping) method

Adds the specified ULBulkCopyColumnMapping object to the collection.

 Syntax

Visual Basic

Public Function Add (ByVal bulkCopyColumnMapping As

ULBulkCopyColumnMapping) As ULBulkCopyColumnMapping

C#

public ULBulkCopyColumnMapping Add (ULBulkCopyColumnMapping

bulkCopyColumnMapping)

Parameters

bulkCopyColumnMapping The ULBulkCopyColumnMapping object that describes the mapping to be

added to the collection.

Remarks

The ULBulkCopyColumnMappingCollection class is not available in the .NET Compact Framework 2.0.

Related Information

ULBulkCopyColumnMapping class [page 68]

UltraLite - .NET API Reference

80 PUBLIC UltraLite .NET API reference
4.1.4.1.2 Add(int, int) method

Creates a new ULBulkCopyColumnMapping object using ordinals to specify both source and destination
columns, and adds the mapping to the collection.

 Syntax

Visual Basic

Public Function Add (

ByVal sourceColumnOrdinal As Integer,
ByVal destinationColumnOrdinal As Integer
) As ULBulkCopyColumnMapping

C#

public ULBulkCopyColumnMapping Add (

int sourceColumnOrdinal,
int destinationColumnOrdinal
)

Parameters

sourceColumnOrdinal The ordinal position of the source column within the data source. The first column
in a data source has ordinal position zero.
destinationColumnOrdinal The ordinal position of the destination column within the destination table. The
first column in a table has ordinal position zero.

Remarks

The ULBulkCopyColumnMappingCollection class is not available in the .NET Compact Framework 2.0.

Related Information

ULBulkCopyColumnMapping class [page 68]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 81
4.1.4.1.3 Add(int, string) method

Creates a new ULBulkCopyColumnMapping object using a column ordinal to refer to the source column and a
column name to refer to the destination column, and adds mapping to the collection.

 Syntax

Visual Basic

Public Function Add (

ByVal sourceColumnOrdinal As Integer,
ByVal destinationColumn As String
) As ULBulkCopyColumnMapping

C#

public ULBulkCopyColumnMapping Add (

int sourceColumnOrdinal,
string destinationColumn
)

Parameters

sourceColumnOrdinal The ordinal position of the source column within the data source. The first column
in a data source has ordinal position zero.
destinationColumn The name of the destination column within the destination table.

Remarks

The ULBulkCopyColumnMappingCollection class is not available in the .NET Compact Framework 2.0.

Related Information

ULBulkCopyColumnMapping class [page 68]

UltraLite - .NET API Reference

82 PUBLIC UltraLite .NET API reference
4.1.4.1.4 Add(string, int) method

Creates a new ULBulkCopyColumnMapping object using a column name to refer to the source column and a
column ordinal to refer to the destination the column, and adds the mapping to the collection.

 Syntax

Visual Basic

Public Function Add (

ByVal sourceColumn As String,
ByVal destinationColumnOrdinal As Integer
) As ULBulkCopyColumnMapping

C#

public ULBulkCopyColumnMapping Add (

string sourceColumn,
int destinationColumnOrdinal
)

Parameters

sourceColumn The name of the source column within the data source.
destinationColumnOrdinal The ordinal position of the destination column within the destination table. The
first column in a table has ordinal position zero.

Remarks

Creates a new column mapping, using column ordinals or names to refer to source and destination columns.

The ULBulkCopyColumnMappingCollection class is not available in the .NET Compact Framework 2.0.

Related Information

ULBulkCopyColumnMapping class [page 68]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 83
4.1.4.1.5 Add(string, string) method

Creates a new ULBulkCopyColumnMapping object using column names to specify both source and destination
columns, and adds the mapping to the collection.

 Syntax

Visual Basic

Public Function Add (

ByVal sourceColumn As String,
ByVal destinationColumn As String
) As ULBulkCopyColumnMapping

C#

public ULBulkCopyColumnMapping Add (

string sourceColumn,
string destinationColumn
)

Parameters

sourceColumn The name of the source column within the data source.
destinationColumn The name of the destination column within the destination table.

Remarks

The ULBulkCopyColumnMappingCollection class is not available in the .NET Compact Framework 2.0.

Related Information

ULBulkCopyColumnMapping class [page 68]

UltraLite - .NET API Reference

84 PUBLIC UltraLite .NET API reference
4.1.4.2 Contains(ULBulkCopyColumnMapping) method

Returns whether the specified ULBulkCopyColumnMapping object exists in the collection.

 Syntax

Visual Basic

Public Function Contains (ByVal value As ULBulkCopyColumnMapping) As

Boolean

C#

public bool Contains (ULBulkCopyColumnMapping value)

Parameters

value A valid ULBulkCopyColumnMapping object.

Returns

True if the specified mapping exists in the collection; otherwise, returns false.

Related Information

ULBulkCopyColumnMapping class [page 68]

4.1.4.3 CopyTo(ULBulkCopyColumnMapping[], int) method

Copies the elements of the ULBulkCopyColumnMappingCollection object to an array of

ULBulkCopyColumnMapping objects, starting at a particular index.

 Syntax

Visual Basic

Public Sub CopyTo (

ByVal array As ULBulkCopyColumnMapping(),
ByVal index As Integer
)

C#

public void CopyTo (

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 85
 ULBulkCopyColumnMapping[] array,
int index
)

Parameters

array The one-dimensional ULBulkCopyColumnMapping array that is the destination of the elements
copied from this ULBulkCopyColumnMappingCollection object. The array must have zero-based indexing.
index The zero-based index in the array at which copying begins.

Related Information

ULBulkCopyColumnMapping class [page 68]

4.1.4.4 IndexOf(ULBulkCopyColumnMapping) method

Returns the index of the specified ULBulkCopyColumnMapping object within the collection.

 Syntax

Visual Basic

Public Function IndexOf (ByVal value As ULBulkCopyColumnMapping) As Integer

C#

public int IndexOf (ULBulkCopyColumnMapping value)

Parameters

value The ULBulkCopyColumnMapping object to search for.

Returns

The zero-based index of the column mapping is returned, or -1 is returned if the column mapping is not found in
the collection.

UltraLite - .NET API Reference

86 PUBLIC UltraLite .NET API reference
Related Information

ULBulkCopyColumnMapping class [page 68]

4.1.4.5 Remove(ULBulkCopyColumnMapping) method

Removes the specified ULBulkCopyColumnMapping object from the ULBulkCopyColumnMappingCollection

object.

 Syntax

Visual Basic

Public Sub Remove (ByVal value As ULBulkCopyColumnMapping)

C#

public void Remove (ULBulkCopyColumnMapping value)

Parameters

value The ULBulkCopyColumnMapping object to be removed from the collection.

Related Information

ULBulkCopyColumnMapping class [page 68]

4.1.4.6 RemoveAt(int) method

Removes the mapping at the specified index from the collection.

 Syntax

Visual Basic

Public Shadows Sub RemoveAt (ByVal index As Integer)

C#

public new void RemoveAt (int index)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 87
Parameters

index The zero-based index of the ULBulkCopyColumnMapping object to be removed from the collection.

4.1.4.7 this[int index] property

Gets the ULBulkCopyColumnMapping object at the specified index.

 Syntax

Visual Basic

Public ReadOnly Property Item (ByVal indexAs Integer) As

ULBulkCopyColumnMapping

C#

public ULBulkCopyColumnMapping this[int index] {get;}

Remarks

An ULBulkCopyColumnMapping object is returned.

Related Information

ULBulkCopyColumnMapping class [page 68]

4.1.5 ULCommand class

Represents a pre-compiled SQL statement or query, with or without IN parameters.

 Syntax

Visual Basic

Public NotInheritable Class ULCommand Inherits

System.Data.Common.DbCommand Implements System.ICloneable

C#

public sealed class ULCommand : System.Data.Common.DbCommand,

System.ICloneable

UltraLite - .NET API Reference

88 PUBLIC UltraLite .NET API reference
Members

All members of ULCommand, including inherited members.

Constructors

Modifier and Type Constructor Description

public ULCommand [page 93] Initializes a ULCommand object.

Methods

Modifier and Type Method Description

public IAsyncResult BeginExecuteNonQuery [page 98] Initiates the asynchronous execution of

a SQL statement that is described by
this ULCommand object.

public IAsyncResult BeginExecuteReader [page 100] Initiates the asynchronous execution of

a SQL statement that is described by
this ULCommand object, and retrieves
the result set.

public override void Cancel() [page 105] This method is not supported in Ultra­
Lite.NET.

protected override DbParameter CreateDbParameter() [page 105]

public new ULParameter CreateParameter() [page 106] Provides a ULParameter object for sup­
plying parameters to ULCommand ob­
jects.

protected override void Dispose(bool) [page 106] Releases the unmanaged resources
used by the ULCommand object and
optionally releases the managed re­
sources.

public int EndExecuteNonQuery(IAsyncResult) Finishes asynchronous execution of a

[page 107] SQL statement.

public ULDataReader EndExecuteReader(IAsyncResult) Finishes asynchronous execution of a

[page 111] SQL statement, returning the re­
quested ULDataReader.

protected override DbDataReader ExecuteDbDataReader(CommandBe­

havior) [page 114]

public override unsafe int ExecuteNonQuery() [page 114] Executes a statement that does not re­
turn a result set, such as a SQL INSERT,
DELETE, or UPDATE statement.

public new ULDataReader ExecuteReader [page 115] Executes a SQL SELECT statement and
returns the result set.

public ULResultSet ExecuteResultSet [page 119] UL Ext: Executes a SQL SELECT state­
ment and returns the result set as a UL­
ResultSet object.

public override object ExecuteScalar() [page 122] Executes a SQL SELECT statement and
returns a single value.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 89
Modifier and Type Method Description

public ULTable ExecuteTable [page 123] UL Ext: Retrieves a database table in a

ULTable object for direct manipulation.

public override unsafe void Prepare() [page 126] Pre-compiles and stores the SQL state­
ment of this command.

Properties

Modifier and Type Property Description

public override string CommandText [page 127] Specifies the text of the SQL statement
or the name of the table when the UL­
Command.CommandType property is
System.Data.CommandType.TableDir­
ect.

public override int CommandTimeout [page 128] This feature is not supported by Ultra­
Lite.NET.

public override CommandType CommandType [page 129] Specifies the type of command to be
executed.

public new ULConnection Connection [page 130] The connection object on which to exe­
cute the ULCommand object.

protected override DbConnection DbConnection [page 130]

protected override DbParameterCollec­ DbParameterCollection [page 131]

tion

protected override DbTransaction DbTransaction [page 131]

public override bool DesignTimeVisible [page 131] Indicates if the ULCommand object
should be visible in a customized Win­
dows Form Designer control.

public string IndexName [page 132] UL Ext: Specifies the name of the index
to open (sort) the table with when the
ULCommand.CommandType property
is System.Data.CommandType.Table­
Direct.

public new ULParameterCollection Parameters [page 132] Specifies the parameters for the cur­
rent statement.

public unsafe string Plan [page 133] UL Ext: Returns the access plan Ultra­
Lite.NET uses to execute a query.

public new ULTransaction Transaction [page 134] Specifies the ULTransaction object in
which the ULCommand object exe­
cutes.

public override UpdateRowSource UpdatedRowSource [page 134] Specifies how command results are ap­
plied to the DataRow when used by the
ULDataAdapterUpdate method.

UltraLite - .NET API Reference

90 PUBLIC UltraLite .NET API reference
Remarks

This object can be used to execute a statement or query efficiently multiple times.

ULCommand objects can be created directly, or with the ULConnection.CreateCommand method. This method
ensures that the command has the correct transaction for executing statements on the given connection.

The ULCommand.Transaction method must be reset after the current transaction is committed or rolled back.

The ULCommand class features the following methods for executing commands on an UltraLite.NET database:

Method Description

ULCommand.ExecuteNonQuery Executes a statement that does not return a result set, such
as a SQL INSERT, DELETE, or UPDATE statement.

ULCommand.ExecuteReader() Executes a SQL SELECT statement and returns the result set
in a ULDataReader object. Use this method for creating
read-only result sets.

ULCommand.ExecuteResultSet() UL Ext: Executes a SQL SELECT statement and returns the

result set in a ULResultSet object. Use this method for creat­
ing mutable result sets.

ULCommand.ExecuteScalar Executes a SQL SELECT statement and returns a single

value.

ULCommand.ExecuteTable() UL Ext: Retrieves a database table in a ULTable object for di­

rect manipulation. The ULCommand.CommandText prop­
erty is interpreted as the name of the table and the ULCom­
mand.IndexName property can be used to specify a table
sorting order. The ULCommand.CommandType property
must be System.Data.CommandType.TableDirect.

You can reset most properties, including the ULCommand.CommandText property, and reuse the ULCommand
object.

For resource management reasons, you should explicitly dispose of commands when you are done with them.
In C#, you may use a using statement to automatically call the System.ComponentModel.Component.Dispose
method or explicitly call the System.ComponentModel.Component.Dispose method. In Visual Basic, you
always explicitly call the System.ComponentModel.Component.Dispose method.

In this section:

ULCommand constructor [page 93]

Initializes a ULCommand object.

BeginExecuteNonQuery method [page 98]

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object.

BeginExecuteReader method [page 100]

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object,
and retrieves the result set.

Cancel() method [page 105]

This method is not supported in UltraLite.NET.

CreateDbParameter() method [page 105]

CreateParameter() method [page 106]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 91
 Provides a ULParameter object for supplying parameters to ULCommand objects.

Dispose(bool) method [page 106]

Releases the unmanaged resources used by the ULCommand object and optionally releases the
managed resources.

EndExecuteNonQuery(IAsyncResult) method [page 107]

Finishes asynchronous execution of a SQL statement.

EndExecuteReader(IAsyncResult) method [page 111]

Finishes asynchronous execution of a SQL statement, returning the requested ULDataReader.

ExecuteDbDataReader(CommandBehavior) method [page 114]

ExecuteNonQuery() method [page 114]

Executes a statement that does not return a result set, such as a SQL INSERT, DELETE, or UPDATE
statement.

ExecuteReader method [page 115]

Executes a SQL SELECT statement and returns the result set.

ExecuteResultSet method [page 119]

UL Ext: Executes a SQL SELECT statement and returns the result set as a ULResultSet object.

ExecuteScalar() method [page 122]

Executes a SQL SELECT statement and returns a single value.

ExecuteTable method [page 123]

UL Ext: Retrieves a database table in a ULTable object for direct manipulation.

Prepare() method [page 126]

Pre-compiles and stores the SQL statement of this command.

CommandText property [page 127]

Specifies the text of the SQL statement or the name of the table when the ULCommand.CommandType
property is System.Data.CommandType.TableDirect.

CommandTimeout property [page 128]

This feature is not supported by UltraLite.NET.

CommandType property [page 129]

Specifies the type of command to be executed.

Connection property [page 130]

The connection object on which to execute the ULCommand object.

DbConnection property [page 130]

DbParameterCollection property [page 131]

DbTransaction property [page 131]

DesignTimeVisible property [page 131]

Indicates if the ULCommand object should be visible in a customized Windows Form Designer control.

IndexName property [page 132]

UL Ext: Specifies the name of the index to open (sort) the table with when the
ULCommand.CommandType property is System.Data.CommandType.TableDirect.

Parameters property [page 132]

Specifies the parameters for the current statement.

UltraLite - .NET API Reference

92 PUBLIC UltraLite .NET API reference
 Plan property [page 133]
UL Ext: Returns the access plan UltraLite.NET uses to execute a query.

Transaction property [page 134]

Specifies the ULTransaction object in which the ULCommand object executes.

UpdatedRowSource property [page 134]

Specifies how command results are applied to the DataRow when used by the ULDataAdapterUpdate
method.

Related Information

CreateCommand() method [page 172]

Transaction property [page 134]
ExecuteNonQuery() method [page 114]
ExecuteReader() method [page 116]
ExecuteResultSet() method [page 119]
ExecuteScalar() method [page 122]
ExecuteTable() method [page 124]
ULTable class [page 548]
CommandText property [page 127]
CommandType property [page 129]
IndexName property [page 132]
ULResultSet class [page 463]
ULDataReader class [page 302]

4.1.5.1 ULCommand constructor

Initializes a ULCommand object.

Overload list

Modifier and Type Overload name Description

public ULCommand() [page 94] Initializes a ULCommand object.

public ULCommand(string) [page 95] Initializes a ULCommand object with

the specified command text.

public ULCommand(string, ULConnection) Initializes a ULCommand object with

[page 96] the specified command text and con­
nection.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 93
Modifier and Type Overload name Description

public ULCommand(string, ULConnection, UL­ Initializes a ULCommand object with

Transaction) [page 97] the specified command text, connec­
tion, and transaction.

In this section:

ULCommand() constructor [page 94]

Initializes a ULCommand object.

ULCommand(string) constructor [page 95]

Initializes a ULCommand object with the specified command text.

ULCommand(string, ULConnection) constructor [page 96]

Initializes a ULCommand object with the specified command text and connection.

ULCommand(string, ULConnection, ULTransaction) constructor [page 97]

Initializes a ULCommand object with the specified command text, connection, and transaction.

4.1.5.1.1 ULCommand() constructor

Initializes a ULCommand object.

 Syntax

Visual Basic

Public Sub ULCommand ()

C#

public ULCommand ()

Remarks

The ULCommand object needs to have the ULCommand.CommandText, ULCommand.Connection, and

ULCommand.Transaction properties set before a statement can be executed.

Related Information

CreateCommand() method [page 172]

ULCommand class [page 88]
ULCommand class [page 88]
ULCommand class [page 88]

UltraLite - .NET API Reference

94 PUBLIC UltraLite .NET API reference
CommandText property [page 127]
Connection property [page 130]
Transaction property [page 134]

4.1.5.1.2 ULCommand(string) constructor

Initializes a ULCommand object with the specified command text.

 Syntax

Visual Basic

Public Sub ULCommand (ByVal cmdText As String)

C#

public ULCommand (string cmdText)

Parameters

cmdText The text of the SQL statement or name of the table when the ULCommand.CommandType
property is System.Data.CommandType.TableDirect. For parameterized statements, use a question mark
(?) placeholder to pass parameters.

Remarks

The ULCommand object needs to have the ULCommand.Connection and ULCommand.Transaction properties
set before a statement can be executed.

Related Information

CreateCommand() method [page 172]

ULCommand() constructor [page 94]
ULCommand class [page 88]
ULCommand class [page 88]
Connection property [page 130]
Transaction property [page 134]
CommandType property [page 129]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 95
4.1.5.1.3 ULCommand(string, ULConnection) constructor

Initializes a ULCommand object with the specified command text and connection.

 Syntax

Visual Basic

Public Sub ULCommand (

ByVal cmdText As String,
ByVal connection As ULConnection
)

C#

public ULCommand (
string cmdText,
ULConnection connection
)

Parameters

cmdText The text of the SQL statement or name of the table when the ULCommand.CommandType
property is System.Data.CommandType.TableDirect. For parameterized statements, use a question mark
(?) placeholder to pass parameters.
connection The ULConnection object representing the current connection.

Remarks

The ULCommand object may need to have the ULCommand.Transaction property set before a statement can
be executed.

Related Information

ULConnection class [page 151]

CreateCommand() method [page 172]
ULCommand() constructor [page 94]
ULCommand class [page 88]
ULCommand class [page 88]
Transaction property [page 134]
CommandType property [page 129]

UltraLite - .NET API Reference

96 PUBLIC UltraLite .NET API reference
4.1.5.1.4 ULCommand(string, ULConnection,
ULTransaction) constructor

Initializes a ULCommand object with the specified command text, connection, and transaction.

 Syntax

Visual Basic

Public Sub ULCommand (

ByVal cmdText As String,
ByVal connection As ULConnection,
ByVal transaction As ULTransaction
)

C#

public ULCommand (
string cmdText,
ULConnection connection,
ULTransaction transaction
)

Parameters

cmdText The text of the SQL statement or name of the table when the ULCommand.CommandType
property is System.Data.CommandType.TableDirect. For parameterized statements, use a question mark
(?) placeholder to pass parameters.
connection The ULConnection object representing the current connection.
transaction The ULTransaction object in which the ULCommand object executes.

Related Information

CreateCommand() method [page 172]

ULCommand() constructor [page 94]
ULCommand class [page 88]
ULCommand class [page 88]
CommandType property [page 129]
ULTransaction class [page 598]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 97
4.1.5.2 BeginExecuteNonQuery method

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object.

Overload list

Modifier and Type Overload name Description

public IAsyncResult BeginExecuteNonQuery() [page 98] Initiates the asynchronous execution of

a SQL statement that is described by
this ULCommand object.

public IAsyncResult BeginExecuteNonQuery(AsyncCall­ Initiates the asynchronous execution of

back, object) [page 99] a SQL statement that is described by
this ULCommand object, given a call­
back procedure and state information.

In this section:

BeginExecuteNonQuery() method [page 98]

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object.

BeginExecuteNonQuery(AsyncCallback, object) method [page 99]

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object,
given a callback procedure and state information.

4.1.5.2.1 BeginExecuteNonQuery() method

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object.

 Syntax

Visual Basic

Public Function BeginExecuteNonQuery () As IAsyncResult

C#

public IAsyncResult BeginExecuteNonQuery ()

Returns

A System.IAsyncResult that can be used to poll, wait for results, or both is returned; this value is also needed
when invoking the EndExecuteNonQuery(IAsyncResult) method, which returns the number of affected rows.

UltraLite - .NET API Reference

98 PUBLIC UltraLite .NET API reference
Exceptions

ULException class Any error that occurred while executing the command text.

Related Information

EndExecuteNonQuery(IAsyncResult) method [page 107]

EndExecuteNonQuery(IAsyncResult) method [page 107]

4.1.5.2.2 BeginExecuteNonQuery(AsyncCallback, object)

method

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object, given a
callback procedure and state information.

 Syntax

Visual Basic

Public Function BeginExecuteNonQuery (

ByVal callback As AsyncCallback,
ByVal stateObject As Object
) As IAsyncResult

C#

public IAsyncResult BeginExecuteNonQuery (

AsyncCallback callback,
object stateObject
)

Parameters

callback A System.AsyncCallback delegate that is invoked when the command's execution has completed.
Pass null (Nothing in Microsoft Visual Basic) to indicate that no callback is required.
stateObject A user­defined state object that is passed to the callback procedure. Retrieve this object from
within the callback procedure using the System.IAsyncResult.AsyncState property.

Returns

A System.IAsyncResult that can be used to poll, wait for results, or both is returned; this value is also needed
when invoking the EndExecuteNonQuery(IAsyncResult) method, which returns the number of affected rows.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 99
Exceptions

ULException class Any error that occurred while executing the command text.

Related Information

EndExecuteNonQuery(IAsyncResult) method [page 107]

4.1.5.3 BeginExecuteReader method

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object, and
retrieves the result set.

Overload list

Modifier and Type Overload name Description

public IAsyncResult BeginExecuteReader() [page 101] Initiates the asynchronous execution of

a SQL statement that is described by
this ULCommand object, and retrieves
the result set.

public IAsyncResult BeginExecuteReader(AsyncCallback, Initiates the asynchronous execution of

object) [page 102] a SQL statement that is described by
this ULCommand object, and retrieves
the result set, given a callback proce­
dure and state information.

public IAsyncResult BeginExecuteReader(AsyncCallback, Initiates the asynchronous execution of

object, CommandBehavior) [page 103] a SQL statement that is described by
this ULCommand object, using one of
the CommandBehavior values, and re­
trieves the result set, given a callback
procedure and state information.

public IAsyncResult BeginExecuteReader(CommandBehav­ Initiates the asynchronous execution of

ior) [page 104] a SQL statement that is described by
this ULCommand object, using one of
the CommandBehavior values, and re­
trieves the result set.

In this section:

BeginExecuteReader() method [page 101]

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object,
and retrieves the result set.

UltraLite - .NET API Reference

100 PUBLIC UltraLite .NET API reference
 BeginExecuteReader(AsyncCallback, object) method [page 102]
Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object,
and retrieves the result set, given a callback procedure and state information.

BeginExecuteReader(AsyncCallback, object, CommandBehavior) method [page 103]

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object,
using one of the CommandBehavior values, and retrieves the result set, given a callback procedure and
state information.

BeginExecuteReader(CommandBehavior) method [page 104]

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object,
using one of the CommandBehavior values, and retrieves the result set.

4.1.5.3.1 BeginExecuteReader() method

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object, and
retrieves the result set.

 Syntax

Visual Basic

Public Function BeginExecuteReader () As IAsyncResult

C#

public IAsyncResult BeginExecuteReader ()

Returns

An System.IAsyncResult that can be used to poll, wait for results, or both is returned; this value is also needed
when invoking the EndExecuteReader(IAsyncResult) method, which returns an ULDataReader object that can
be used to retrieve the returned rows.

Exceptions

ULException class Any error that occurred while executing the command text.

Related Information

EndExecuteReader(IAsyncResult) method [page 111]

ULDataReader class [page 302]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 101
4.1.5.3.2 BeginExecuteReader(AsyncCallback, object)
method

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object, and
retrieves the result set, given a callback procedure and state information.

 Syntax

Visual Basic

Public Function BeginExecuteReader (

ByVal callback As AsyncCallback,
ByVal stateObject As Object
) As IAsyncResult

C#

public IAsyncResult BeginExecuteReader (

AsyncCallback callback,
object stateObject
)

Parameters

callback An System.AsyncCallback delegate that is invoked when the command's execution has
completed. Pass null (Nothing in Microsoft Visual Basic) to indicate that no callback is required.
stateObject A user­defined state object that is passed to the callback procedure. Retrieve this object from
within the callback procedure using the System.IAsyncResult.AsyncState property.

Returns

A System.IAsyncResult that can be used to poll, wait for results, or both is returned; this value is also needed
when invoking the EndExecuteReader(IAsyncResult) method, which returns a ULDataReader object that can
be used to retrieve the returned rows.

Exceptions

ULException class Any error that occurred while executing the command text.

Related Information

ULDataReader class [page 302]

UltraLite - .NET API Reference

102 PUBLIC UltraLite .NET API reference
EndExecuteReader(IAsyncResult) method [page 111]
EndExecuteReader(IAsyncResult) method [page 111]

4.1.5.3.3 BeginExecuteReader(AsyncCallback, object,

CommandBehavior) method

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object, using
one of the CommandBehavior values, and retrieves the result set, given a callback procedure and state
information.

 Syntax

Visual Basic

Public Function BeginExecuteReader (

ByVal callback As AsyncCallback,
ByVal stateObject As Object,
ByVal cmdBehavior As CommandBehavior
) As IAsyncResult

C#

public IAsyncResult BeginExecuteReader (

AsyncCallback callback,
object stateObject,
CommandBehavior cmdBehavior
)

Parameters

callback A System.AsyncCallback delegate that is invoked when the command's execution has completed.
Pass null (Nothing in Microsoft Visual Basic) to indicate that no callback is required.
stateObject A user­defined state object that is passed to the callback procedure. Retrieve this object from
within the callback procedure using the System.IAsyncResult.AsyncState property.
cmdBehavior A bitwise combination of System.Data.CommandBehavior flags describing the results of the
query and its effect on the connection. UltraLite.NET respects only the
System.Data.CommandBehavior.Default, System.Data.CommandBehavior.CloseConnection, and
System.Data.CommandBehavior.SchemaOnly flags.

Returns

A System.IAsyncResult that can be used to poll, wait for results, or both is returned; this value is also needed
when invoking the EndExecuteReader(IAsyncResult) method, which returns a ULDataReader object that can
be used to retrieve the returned rows.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 103
Exceptions

ULException class Any error that occurred while executing the command text.

Related Information

EndExecuteReader(IAsyncResult) method [page 111]

ULDataReader class [page 302]

4.1.5.3.4 BeginExecuteReader(CommandBehavior) method

Initiates the asynchronous execution of a SQL statement that is described by this ULCommand object, using
one of the CommandBehavior values, and retrieves the result set.

 Syntax

Visual Basic

Public Function BeginExecuteReader (ByVal cmdBehavior As CommandBehavior)

As IAsyncResult

C#

public IAsyncResult BeginExecuteReader (CommandBehavior cmdBehavior)

Parameters

cmdBehavior A bitwise combination of System.Data.CommandBehavior flags describing the results of the

query and its effect on the connection. UltraLite.NET respects only the
System.Data.CommandBehavior.Default, System.Data.CommandBehavior.CloseConnection, and
System.Data.CommandBehavior.SchemaOnly flags.

Returns

An System.IAsyncResult that can be used to poll, wait for results, or both is returned; this value is also needed
when invoking the EndExecuteReader(IAsyncResult) method, which returns a ULDataReader object that can
be used to retrieve the returned rows.

UltraLite - .NET API Reference

104 PUBLIC UltraLite .NET API reference
Exceptions

ULException class Any error that occurred while executing the command text.

Related Information

EndExecuteReader(IAsyncResult) method [page 111]

ULDataReader class [page 302]

4.1.5.4 Cancel() method

This method is not supported in UltraLite.NET.

 Syntax

Visual Basic

Public Overrides Sub Cancel ()

C#

public override void Cancel ()

Remarks

This method does nothing. UltraLite.NET commands cannot be interrupted while they are executing.

4.1.5.5 CreateDbParameter() method

 Syntax

Visual Basic

Protected Overrides Function CreateDbParameter () As DbParameter

C#

protected override DbParameter CreateDbParameter ()

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 105
4.1.5.6 CreateParameter() method

Provides a ULParameter object for supplying parameters to ULCommand objects.

 Syntax

Visual Basic

Public Shadows Function CreateParameter () As ULParameter

C#

public new ULParameter CreateParameter ()

Returns

A new parameter, as a ULParameter object.

Remarks

Some SQL statements can take parameters, indicated in the text of a statement by a question mark (?). The
CreateParameter method provides a ULParameter object. You can set properties on the ULParameter object to
specify the value for the parameter.

This is the strongly-typed version of System.Data.IDbCommand.CreateParameter and

System.Data.Common.DbCommand.CreateParameter.

Related Information

ULParameter class [page 413]

4.1.5.7 Dispose(bool) method

Releases the unmanaged resources used by the ULCommand object and optionally releases the managed
resources.

 Syntax

Visual Basic

Protected Overrides Sub Dispose (ByVal disposing As Boolean)

UltraLite - .NET API Reference

106 PUBLIC UltraLite .NET API reference
 C#

protected override void Dispose (bool disposing)

Parameters

disposing When true, disposes of both the managed and unmanaged resources. When false, disposes of
only the unmanaged resources.

4.1.5.8 EndExecuteNonQuery(IAsyncResult) method

Finishes asynchronous execution of a SQL statement.

 Syntax

Visual Basic

Public Function EndExecuteNonQuery (ByVal asyncResult As IAsyncResult) As

Integer

C#

public int EndExecuteNonQuery (IAsyncResult asyncResult)

Parameters

asyncResult The System.IAsyncResult returned by the call to the BeginExecuteNonQuery method.

Returns

The number of rows affected, which is the same behavior as the ExecuteNonQuery method.

Exceptions

ArgumentException The asyncResult parameter is null (Nothing in Microsoft Visual Basic).

InvalidOperationException The EndExecuteNonQuery(IAsyncResult) method was called more than once
for a single command execution, or the method was mismatched against its execution method.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 107
Remarks

You must call the EndExecuteNonQuery method once for every BeginExecuteNonQuery call. The call must be
made after the BeginExecuteNonQuery call returns. ADO.NET is not thread safe; you must ensure that the
BeginExecuteNonQuery call has returned. The System.IAsyncResult passed to the EndExecuteNonQuery
method must be the same as the one returned from the BeginExecuteNonQuery call that is being completed. It
is an error to call the EndExecuteNonQuery method to end a call to the BeginExecuteReader method, and vice
versa.

If an error occurs while executing the command, the exception is thrown when the EndExecuteNonQuery
method is called.

There are four ways to wait for execution to complete:

Call EndExecuteNonQuery Calling EndExecuteNonQuery blocks until the command completes. For example:

' Visual Basic

Dim cmd As ULCommand = new ULCommand( _
"UPDATE Departments" _
+ " SET DepartmentName = 'Engineering'" _
+ " WHERE DepartmentID=100", _
conn _
)
Dim res As IAsyncResult res = _
cmd.BeginExecuteNonQuery()
' Perform other work.
' This blocks until the command completes.
Dim rowCount As Integer = _
cmd.EndExecuteNonQuery( res )

The following code is the C# language equivalent:

// C#
ULCommand cmd = new ULCommand(
"UPDATE Departments"
+ " SET DepartmentName = 'Engineering'"
+ " WHERE DepartmentID=100",
conn
);
IAsyncResult res = cmd.BeginExecuteNonQuery();
// Perform other work.
// This blocks until the command completes.
int rowCount = cmd.EndExecuteNonQuery( res );

Poll the IsCompleted property of the IAsyncResult You can poll the IsCompleted property of the
IAsyncResult. For example:

' Visual Basic

Dim cmd As ULCommand = new ULCommand( _
"UPDATE Departments" _
+ " SET DepartmentName = 'Engineering'" _
+ " WHERE DepartmentID=100", _
conn _
)
Dim res As IAsyncResult res = _
cmd.BeginExecuteNonQuery()
While( !res.IsCompleted )
' Perform other work.
End While
' This blocks until the command completes.
Dim rowCount As Integer = _

UltraLite - .NET API Reference

108 PUBLIC UltraLite .NET API reference
 cmd.EndExecuteNonQuery( res )

The following code is the C# language equivalent:

// C#
ULCommand cmd = new ULCommand(
"UPDATE Departments"
+ " SET DepartmentName = 'Engineering'"
+ " WHERE DepartmentID=100",
conn
);
IAsyncResult res = cmd.BeginExecuteNonQuery();
while( !res.IsCompleted ) {
// Perform other work.
}
// This blocks until the command completes.
int rowCount = cmd.EndExecuteNonQuery( res );

Use the IAsyncResult.AsyncWaitHandle property to get a synchronization object You can use the
IAsyncResult.AsyncWaitHandle property to get a synchronization object, and wait on that. For example:

' Visual Basic

Dim cmd As ULCommand = new ULCommand( _
"UPDATE Departments" _
+ " SET DepartmentName = 'Engineering'" _
+ " WHERE DepartmentID=100", _
conn _
)
Dim res As IAsyncResult res = _
cmd.BeginExecuteNonQuery()
' Perform other work.
Dim wh As WaitHandle = res.AsyncWaitHandle
wh.WaitOne()
' This does not block because the command is finished.
Dim rowCount As Integer = _
cmd.EndExecuteNonQuery( res )

The following code is the C# language equivalent:

// C#
ULCommand cmd = new ULCommand(
"UPDATE Departments"
+ " SET DepartmentName = 'Engineering'"
+ " WHERE DepartmentID=100",
conn
);
IAsyncResult res = cmd.BeginExecuteNonQuery();
// perform other work
WaitHandle wh = res.AsyncWaitHandle;
wh.WaitOne();
// This does not block because the command is finished.
int rowCount = cmd.EndExecuteNonQuery( res );

Specify a callback function when calling the BeginExecuteNonQuery method You can specify a callback
function when calling the BeginExecuteNonQuery method. For example:

' Visual Basic

Private Sub callbackFunction(ByVal ar As IAsyncResult)
Dim cmd As ULCommand = _
CType(ar.AsyncState, ULCommand)
' This won't block since the command has completed.
Dim rowCount As Integer = _
cmd.EndExecuteNonQuery( res )
End Sub

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 109
 ' Elsewhere in the code
Private Sub DoStuff()
Dim cmd As ULCommand = new ULCommand( _
"UPDATE Departments" _
+ " SET DepartmentName = 'Engineering'" _
+ " WHERE DepartmentID=100", _
conn _
)
Dim res As IAsyncResult = _
cmd.BeginExecuteNonQuery( _
callbackFunction, cmd _
)
' Perform other work. The callback function
' is called when the command completes.
End Sub

The following code is the C# language equivalent:

// C#
private void callbackFunction( IAsyncResult ar )
{
ULCommand cmd = (ULCommand) ar.AsyncState;
// This won't block since the command has completed.
int rowCount = cmd.EndExecuteNonQuery();
}
// Elsewhere in the code
private void DoStuff()
{
ULCommand cmd = new ULCommand(
"UPDATE Departments"
+ " SET DepartmentName = 'Engineering'"
+ " WHERE DepartmentID=100",
conn
);
IAsyncResult res = cmd.BeginExecuteNonQuery(
callbackFunction, cmd
);
// Perform other work. The callback function
// is called when the command completes.
}

The callback function executes in a separate thread, so the usual caveats related to updating the user interface
in a threaded program apply.

Related Information

BeginExecuteNonQuery() method [page 98]

UltraLite - .NET API Reference

110 PUBLIC UltraLite .NET API reference
4.1.5.9 EndExecuteReader(IAsyncResult) method

Finishes asynchronous execution of a SQL statement, returning the requested ULDataReader.

 Syntax

Visual Basic

Public Function EndExecuteReader (ByVal asyncResult As IAsyncResult) As

ULDataReader

C#

public ULDataReader EndExecuteReader (IAsyncResult asyncResult)

Parameters

asyncResult The System.IAsyncResult returned by the BeginExecuteReader call.

Returns

An ULDataReader object that can be used to retrieve the requested rows, which is the same behavior as the
ExecuteReader method.

Exceptions

ArgumentException The asyncResult parameter is null (Nothing in Microsoft Visual Basic)

InvalidOperationException The EndExecuteReader method was called more than once for a single
command execution, or the method was mismatched against its execution method.

Remarks

You must call the EndExecuteReader method once for every call to the BeginExecuteReader method. The call
must be after the BeginExecuteReader call returns. ADO.NET is not thread safe; it is your responsibility to
ensure that the BeginExecuteReader method has returned. The System.IAsyncResult passed to the
EndExecuteReader method must be the same as the one returned from the BeginExecuteReader call that is
being completed. It is an error to call the EndExecuteReader method to end a BeginExecuteNonQuery call, and
vice versa.

If an error occurs while executing the command, the exception is thrown when the EndExecuteReader method
is called.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 111
There are four ways to wait for execution to complete:

Call the EndExecuteReader method Calling the EndExecuteReader method blocks until the command
completes. For example:

' Visual Basic

Dim cmd As ULCommand = new ULCommand( _
"SELECT * FROM Departments", conn _
)
Dim res As IAsyncResult res = _
cmd.BeginExecuteReader()
' Perform other work
' This blocks until the command completes.
Dim reader As ULDataReader = _
cmd.EndExecuteReader( res )

The following code is the C# language equivalent:

// C#
ULCommand cmd = new ULCommand(
"SELECT * FROM Departments", conn
);
IAsyncResult res = cmd.BeginExecuteReader();
// Perform other work
// This blocks until the command completes
ULDataReader reader = cmd.EndExecuteReader( res );

Poll the IsCompleted property of the IAsyncResult You can poll the IsCompleted property of the
IAsyncResult. For example:

' Visual Basic

Dim cmd As ULCommand = new ULCommand( _
"SELECT * FROM Departments", conn _
)
Dim res As IAsyncResult res = _
cmd.BeginExecuteReader()
While( !res.IsCompleted )
' Perform other work
End While
' This blocks until the command completes.
Dim reader As ULDataReader = _
cmd.EndExecuteReader( res )
// C#
ULCommand cmd = new ULCommand(
"SELECT * FROM Departments", conn
);
IAsyncResult res = cmd.BeginExecuteReader();
while( !res.IsCompleted ) {
// Perform other work.
}
// This blocks until the command completes.
ULDataReader reader = cmd.EndExecuteReader( res );

Use the IAsyncResult.AsyncWaitHandle property to get a synchronization object You can use the
IAsyncResult.AsyncWaitHandle property to get a synchronization object, and wait on that. For example:

' Visual Basic

Dim cmd As ULCommand = new ULCommand( _
"SELECT * FROM Departments", conn _
)
Dim res As IAsyncResult res = _
cmd.BeginExecuteReader()
' Perform other work.
Dim wh As WaitHandle = res.AsyncWaitHandle

UltraLite - .NET API Reference

112 PUBLIC UltraLite .NET API reference
 wh.WaitOne()
' This does not block because the command is finished.
Dim reader As ULDataReader = _
cmd.EndExecuteReader( res )

The following code is the C# language equivalent:

// C#
ULCommand cmd = new ULCommand(
"SELECT * FROM Departments", conn
);
IAsyncResult res = cmd.BeginExecuteReader();
// Perform other work.
WaitHandle wh = res.AsyncWaitHandle;
wh.WaitOne();
// This does not block because the command is finished.
ULDataReader reader = cmd.EndExecuteReader( res );

Specify a callback function when calling the BeginExecuteReader method You can specify a callback function
when calling the BeginExecuteReader method. For example:

' Visual Basic

Private Sub callbackFunction(ByVal ar As IAsyncResult)
Dim cmd As ULCommand = _
CType(ar.AsyncState, ULCommand)
' This won't block since the command has completed.
Dim reader As ULDataReader = cmd.EndExecuteReader()
End Sub
' Elsewhere in the code
Private Sub DoStuff()
Dim cmd As ULCommand = new ULCommand( _
"SELECT * FROM Departments", conn _
)
Dim res As IAsyncResult = _
cmd.BeginExecuteReader( _
callbackFunction, cmd _
)
' Perform other work. The callback function
' is called when the command completes.
End Sub

The following code is the C# language equivalent:

// C#
private void callbackFunction( IAsyncResult ar )
{
ULCommand cmd = (ULCommand) ar.AsyncState;
// This won't block since the command has completed.
ULDataReader reader = cmd.EndExecuteReader();
}
// Elsewhere in the code.
private void DoStuff()
{
ULCommand cmd = new ULCommand(
"SELECT * FROM Departments", conn
);
IAsyncResult res = cmd.BeginExecuteReader(callbackFunction, cmd);
// Perform other work. The callback function
// is called when the command completes.
}

The callback function executes in a separate thread, so the usual caveats related to updating the user interface
in a threaded program apply.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 113
Related Information

BeginExecuteReader() method [page 101]

ULDataReader class [page 302]

4.1.5.10 ExecuteDbDataReader(CommandBehavior) method

 Syntax

Visual Basic

Protected Overrides Function ExecuteDbDataReader (ByVal cmdBehavior As

CommandBehavior) As DbDataReader

C#

protected override DbDataReader ExecuteDbDataReader (CommandBehavior

cmdBehavior)

4.1.5.11 ExecuteNonQuery() method

Executes a statement that does not return a result set, such as a SQL INSERT, DELETE, or UPDATE statement.

 Syntax

Visual Basic

Public Overrides Function ExecuteNonQuery () As Integer

C#

public override unsafe int ExecuteNonQuery ()

Returns

The number of rows affected.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

114 PUBLIC UltraLite .NET API reference
 InvalidOperationException The command is in an invalid state. Either the ULCommand.Connection object
is missing or closed, the ULCommand.Transaction value does not match the current transaction state of
the connection, or the ULCommand.CommandText value is invalid.

Remarks

The statement is the current ULCommand object, with the ULCommand.CommandText and
ULCommand.Parameters values as required.

For UPDATE, INSERT, and DELETE statements, the return value is the number of rows affected by the
command. For all other types of statements, and for rollbacks, the return value is -1.

The ULCommand.CommandType property cannot be System.Data.CommandType.TableDirect.

Related Information

CommandText property [page 127]

CommandType property [page 129]
Connection property [page 130]
Parameters property [page 132]
Transaction property [page 134]

4.1.5.12 ExecuteReader method

Executes a SQL SELECT statement and returns the result set.

Overload list

Modifier and Type Overload name Description

public new ULDataReader ExecuteReader() [page 116] Executes a SQL SELECT statement and
returns the result set.

public new ULDataReader ExecuteReader(CommandBehavior) Executes a SQL SELECT statement with

[page 117] the specified command behavior and
returns the result set.

In this section:

ExecuteReader() method [page 116]

Executes a SQL SELECT statement and returns the result set.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 115
 ExecuteReader(CommandBehavior) method [page 117]
Executes a SQL SELECT statement with the specified command behavior and returns the result set.

4.1.5.12.1 ExecuteReader() method

Executes a SQL SELECT statement and returns the result set.

 Syntax

Visual Basic

Public Shadows Function ExecuteReader () As ULDataReader

C#

public new ULDataReader ExecuteReader ()

Returns

The result set as a ULDataReader object.

Exceptions

ULException class A SQL error occurred.

InvalidOperationException The command is in an invalid state. Either the ULCommand.Connection value
is missing or closed, the ULCommand.Transaction value does not match the current transaction state of
the connection, or the ULCommand.CommandText value is invalid.

Remarks

The statement is the current ULCommand object, with the ULCommand.CommandText and any
ULCommand.Parameters values as required. The ULDataReader object is a read-only result set. For editable
result sets, use the ULCommand.ExecuteResultSet method, the ULCommand.ExecuteTable method, or a
ULDataAdapter object.

If the ULCommand.CommandType value is System.Data.CommandType.TableDirect, the ExecuteReader

method performs a ULCommand.ExecuteTable call and returns a ULTable object downcast as a ULDataReader
object.

SELECT statements are marked as read-only by default for performance reasons. If the query is going to be
used to make updates, the statement must end with " FOR UPDATE".

UltraLite - .NET API Reference

116 PUBLIC UltraLite .NET API reference
This is the strongly-typed version of the System.Data.IDbCommand.ExecuteReader and
System.Data.Common.DbCommand.ExecuteReader methods.

Related Information

CommandText property [page 127]

CommandType property [page 129]
Connection property [page 130]
Parameters property [page 132]
ExecuteResultSet() method [page 119]
ExecuteTable() method [page 124]
Transaction property [page 134]
ULDataAdapter class [page 267]
ULDataReader class [page 302]
ULTable class [page 548]

4.1.5.12.2 ExecuteReader(CommandBehavior) method

Executes a SQL SELECT statement with the specified command behavior and returns the result set.

 Syntax

Visual Basic

Public Shadows Function ExecuteReader (ByVal cmdBehavior As

CommandBehavior) As ULDataReader

C#

public new ULDataReader ExecuteReader (CommandBehavior cmdBehavior)

Parameters

cmdBehavior A bitwise combination of System.Data.CommandBehavior flags describing the results of the

query and its effect on the connection. UltraLite.NET respects only the
System.Data.CommandBehavior.Default, System.Data.CommandBehavior.CloseConnection, and
System.Data.CommandBehavior.SchemaOnly flags.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 117
Returns

The result set as a ULDataReader object.

Exceptions

ULException class A SQL error occurred.

InvalidOperationException The command is in an invalid state. Either the ULCommand.Connection value
is missing or closed, the ULCommand.Transaction value does not match the current transaction state of
the connection, or the ULCommand.CommandText value is invalid.

Remarks

The statement is the current ULCommand object, with the ULCommand.CommandText and any
ULCommand.Parameters values as required. The ULDataReader object is a read-only result set. For editable
result sets, use the ULCommand.ExecuteResultSet(CommandBehavior) method, the
ULCommand.ExecuteTable(CommandBehavior) method, or a ULDataAdapter object.

If the ULCommand.CommandType is System.Data.CommandType.TableDirect, the ExecuteReader method

performs a ULCommand.ExecuteTable(CommandBehavior) call and returns a ULTable object downcast as a
ULDataReader object.

SELECT statements are marked as read-only by default for performance reasons. If the query is going to be
used to make updates, the statement must end with " FOR UPDATE".

This is the strongly-typed version of the

System.Data.IDbCommand.ExecuteReader(System.Data.CommandBehavior) and
System.Data.Common.DbCommand.ExecuteReader(System.Data.CommandBehavior) methods.

Related Information

CommandText property [page 127]

Connection property [page 130]
ExecuteReader() method [page 116]
ExecuteResultSet(CommandBehavior) method [page 121]
ExecuteTable(CommandBehavior) method [page 125]
Parameters property [page 132]
Transaction property [page 134]
ULDataAdapter class [page 267]
ULDataReader class [page 302]
ULTable class [page 548]
ULDataReader class [page 302]

UltraLite - .NET API Reference

118 PUBLIC UltraLite .NET API reference
4.1.5.13 ExecuteResultSet method

UL Ext: Executes a SQL SELECT statement and returns the result set as a ULResultSet object.

Overload list

Modifier and Type Overload name Description

public ULResultSet ExecuteResultSet() [page 119] UL Ext: Executes a SQL SELECT state­
ment and returns the result set as a UL­
ResultSet object.

public ULResultSet ExecuteResultSet(CommandBehavior) UL Ext: Executes a SQL SELECT state­

[page 121] ment with the specified command be­
havior and returns the result set as a
ULResultSet object.

In this section:

ExecuteResultSet() method [page 119]

UL Ext: Executes a SQL SELECT statement and returns the result set as a ULResultSet object.

ExecuteResultSet(CommandBehavior) method [page 121]

UL Ext: Executes a SQL SELECT statement with the specified command behavior and returns the result
set as a ULResultSet object.

4.1.5.13.1 ExecuteResultSet() method

UL Ext: Executes a SQL SELECT statement and returns the result set as a ULResultSet object.

 Syntax

Visual Basic

Public Function ExecuteResultSet () As ULResultSet

C#

public ULResultSet ExecuteResultSet ()

Returns

The result set as a ULResultSet object.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 119
Exceptions

ULException class A SQL error occurred.

InvalidOperationException The command is in an invalid state. Either the ULCommand.Connection value
is missing or closed, the ULCommand.Transaction value does not match the current transaction state of
the connection, or the ULCommand.CommandText value is invalid.

Remarks

The statement is the current ULCommand object, with the ULCommand.CommandText and any
ULCommand.Parameters values as required. The ULResultSet object is an editable result set on which you can
perform positioned updates and deletes. For fully editable result sets, use the ULCommand.ExecuteTable
method or a ULDataAdapter object.

If the ULCommand.CommandType value is System.Data.CommandType.TableDirect, the ExecuteReader

method performs a ULCommand.ExecuteTable call and returns a ULTable object downcast as a ULResultSet
object.

This method supports positioned updates and deletes with Dynamic SQL.

 Example

cmd.CommandText = "SELECT id, season, price FROM OurProducts";

ULResultSet rs = cmd.ExecuteResultSet();
while( rs.Read() ) {
string season = rs.GetString( 1 );
double price = rs.GetDouble( 2 );
if( season.Equals( "summer" ) ) {
rs.UpdateBegin();
rs.SetDouble( 2, price * .5 );
rs.Update();
}
if( season.Equals( "discontinued" ) ) {
rs.Delete();
}
}
rs.Close();

Related Information

ULCommand class [page 88]

CommandText property [page 127]
Parameters property [page 132]
CommandType property [page 129]
ULResultSet class [page 463]
ULTable class [page 548]

UltraLite - .NET API Reference

120 PUBLIC UltraLite .NET API reference
4.1.5.13.2 ExecuteResultSet(CommandBehavior) method

UL Ext: Executes a SQL SELECT statement with the specified command behavior and returns the result set as
a ULResultSet object.

 Syntax

Visual Basic

Public Function ExecuteResultSet (ByVal cmdBehavior As CommandBehavior) As

ULResultSet

C#

public ULResultSet ExecuteResultSet (CommandBehavior cmdBehavior)

Parameters

cmdBehavior A bitwise combination of System.Data.CommandBehavior flags describing the results of the

query and its effect on the connection. UltraLite.NET respects only the
System.Data.CommandBehavior.Default, System.Data.CommandBehavior.CloseConnection, and
System.Data.CommandBehavior.SchemaOnly flags.

Returns

The result set as a ULResultSet object.

Exceptions

ULException class A SQL error occurred.

InvalidOperationException The command is in an invalid state. Either the ULCommand.Connection value
is missing or closed, the ULCommand.Transaction value does not match the current transaction state of
the connection, or the ULCommand.CommandText value is invalid.

Remarks

The statement is the current ULCommand object, with the ULCommand.CommandText value and any
ULCommand.Parameters value as required. The ULResultSet object is an editable result set on which you can
perform positioned updates and deletes. For fully editable result sets, use the
ULCommand.ExecuteTable(CommandBehavior) method or a ULDataAdapter object.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 121
If the ULCommand.CommandType value is System.Data.CommandType.TableDirect, the ExecuteReader
method performs a ULCommand.ExecuteTable(CommandBehavior) call and returns a ULTable object
downcast as a ULResultSet object.

This method supports positioned updates and deletes with Dynamic SQL.

Related Information

ULResultSet class [page 463]

CommandText property [page 127]
CommandType property [page 129]
Connection property [page 130]
ExecuteReader() method [page 116]
ExecuteTable(CommandBehavior) method [page 125]
Parameters property [page 132]
Transaction property [page 134]
ULDataAdapter class [page 267]
ULTable class [page 548]

4.1.5.14 ExecuteScalar() method

Executes a SQL SELECT statement and returns a single value.

 Syntax

Visual Basic

Public Overrides Function ExecuteScalar () As Object

C#

public override object ExecuteScalar ()

Returns

The first column of the first row in the result set, or a null reference (Nothing in Visual Basic) if the result set is
empty.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

122 PUBLIC UltraLite .NET API reference
 InvalidOperationException The command is in an invalid state. Either the ULCommand.Connection value
is missing or closed, the ULCommand.Transaction value does not match the current transaction state of
the connection, or the ULCommand.CommandText value is invalid.

Remarks

The statement is the current ULCommand object, with the ULCommand.CommandText value and any
ULCommand.Parameters value as required.

If this method is called on a query that returns multiple rows and columns, only the first column of the first row
is returned.

If the ULCommand.CommandType value is System.Data.CommandType.TableDirect, the ExecuteScalar

method performs a ULCommand.ExecuteTable call and returns the first column of the first row.

SELECT statements are marked as read-only by default for performance reasons. If the query is going to be
used to make updates, the statement must end with " FOR UPDATE".

Related Information

CommandText property [page 127]

CommandType property [page 129]
Connection property [page 130]
IndexName property [page 132]
Parameters property [page 132]
Transaction property [page 134]

4.1.5.15 ExecuteTable method

UL Ext: Retrieves a database table in a ULTable object for direct manipulation.

Overload list

Modifier and Type Overload name Description

public ULTable ExecuteTable() [page 124] UL Ext: Retrieves a database table in a

ULTable object for direct manipulation.

public ULTable ExecuteTable(CommandBehavior) UL Ext: Retrieves, with the specified

[page 125] command behavior, a database table
for direct manipulation.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 123
In this section:

ExecuteTable() method [page 124]

UL Ext: Retrieves a database table in a ULTable object for direct manipulation.

ExecuteTable(CommandBehavior) method [page 125]

UL Ext: Retrieves, with the specified command behavior, a database table for direct manipulation.

4.1.5.15.1 ExecuteTable() method

UL Ext: Retrieves a database table in a ULTable object for direct manipulation.

 Syntax

Visual Basic

Public Function ExecuteTable () As ULTable

C#

public ULTable ExecuteTable ()

Returns

The table as a ULTable object.

Exceptions

ULException class A SQL error occurred.

InvalidOperationException The command is in an invalid state. Either the ULCommand.Connection value
is missing or closed, the ULCommand.Transaction value does not match the current transaction state of
the connection, or the ULCommand.CommandText value is invalid.

Remarks

The ULCommand.CommandText value is interpreted as the name of the table, and ULCommand.IndexName
value can be used to specify a table sorting order.

The ULCommand.CommandType value must be set to System.Data.CommandType.TableDirect.

If the ULCommand.IndexName value is a null reference (Nothing in Visual Basic), the primary key is used to
open the table. Otherwise, the table is opened using the ULCommand.IndexName value as the name of the
index by which to sort.

UltraLite - .NET API Reference

124 PUBLIC UltraLite .NET API reference
Related Information

CommandText property [page 127]

CommandType property [page 129]
Connection property [page 130]
IndexName property [page 132]
Transaction property [page 134]
ULTable class [page 548]

4.1.5.15.2 ExecuteTable(CommandBehavior) method

UL Ext: Retrieves, with the specified command behavior, a database table for direct manipulation.

 Syntax

Visual Basic

Public Function ExecuteTable (ByVal cmdBehavior As CommandBehavior) As

ULTable

C#

public ULTable ExecuteTable (CommandBehavior cmdBehavior)

Parameters

cmdBehavior A bitwise combination of System.Data.CommandBehavior flags describing the results of the

query and its effect on the connection. UltraLite.NET respects only the
System.Data.CommandBehavior.Default, System.Data.CommandBehavior.CloseConnection, and
System.Data.CommandBehavior.SchemaOnly flags.

Returns

The table as a ULTable object.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 125
 InvalidOperationException The command is in an invalid state. Either the ULCommand.Connection value
is missing or closed, the ULCommand.Transaction value does not match the current transaction state of
the connection, or the ULCommand.CommandText value is invalid.

Remarks

The ULCommand.CommandText value is interpreted as the name of the table, and ULCommand.IndexName
value can be used to specify a table sorting order.

The ULCommand.CommandType value must be set to System.Data.CommandType.TableDirect.

If the ULCommand.IndexName value is a null reference (Nothing in Visual Basic), the primary key is used to
open the table. Otherwise, the table is opened using the ULCommand.IndexName value as the name of the
index by which to sort.

Related Information

CommandText property [page 127]

CommandType property [page 129]
Connection property [page 130]
ExecuteTable() method [page 124]
IndexName property [page 132]
Transaction property [page 134]

4.1.5.16 Prepare() method

Pre-compiles and stores the SQL statement of this command.

 Syntax

Visual Basic

Public Overrides Sub Prepare ()

C#

public override unsafe void Prepare ()

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

126 PUBLIC UltraLite .NET API reference
 InvalidOperationException The command is in an invalid state. Either the ULCommand.Connection value
is missing or closed, the ULCommand.Transaction value does not match the current transaction state of
the connection, or the ULCommand.CommandText value is invalid.

Remarks

Pre-compiling statements allows for the efficient re-use of statements when just the parameter values are
changed. Changing any other property on this command unprepares the statement.

UltraLite.NET does not require you to explicitly prepare statements as all unprepared commands are prepared
on calls to the various Execute methods.

Related Information

Connection property [page 130]

Transaction property [page 134]
CommandText property [page 127]

4.1.5.17 CommandText property

Specifies the text of the SQL statement or the name of the table when the ULCommand.CommandType
property is System.Data.CommandType.TableDirect.

 Syntax

Visual Basic

Public Overrides Property CommandText As String

C#

public override string CommandText {get;set;}

Remarks

For parameterized statements, use a question mark (?) placeholder to pass parameters.

A string specifying the text of the SQL statement or the name of the table. The default is an empty string
(invalid command).

SELECT statements are marked as read-only by default for performance reasons. If the query is going to be
used to make updates, the statement must end with " FOR UPDATE".

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 127
  Example

' Visual Basic myCmd.CommandText = "SELECT * FROM Customers WHERE CustomerID = ?"

The following code is the C# language equivalent:

// C#
myCmd.CommandText = "SELECT * FROM Customers WHERE CustomerID = ?";

Related Information

ExecuteNonQuery() method [page 114]

ExecuteReader() method [page 116]
ExecuteResultSet() method [page 119]
ExecuteScalar() method [page 122]
ExecuteTable() method [page 124]
CommandType property [page 129]

4.1.5.18 CommandTimeout property

This feature is not supported by UltraLite.NET.

 Syntax

Visual Basic

Public Overrides Property CommandTimeout As Integer

C#

public override int CommandTimeout {get;set;}

Remarks

The value is always zero.

UltraLite - .NET API Reference

128 PUBLIC UltraLite .NET API reference
4.1.5.19 CommandType property

Specifies the type of command to be executed.

 Syntax

Visual Basic

Public Overrides Property CommandType As CommandType

C#

public override CommandType CommandType {get;set;}

Remarks

One of the System.Data.CommandType values. The default value is System.Data.CommandType.Text.

Supported command types are as follows:

● System.Data.CommandType.TableDirect - UL Ext: When you specify this CommandType property, the

ULCommand.CommandText property must be the name of a database table. You can also specify the index
used to open (sort) the table with the ULCommand.IndexName property. Use the
ULCommand.ExecuteTable or ULCommand.ExecuteReader methods to access the table.
● System.Data.CommandType.Text - When you specify this CommandType property, the
ULCommand.CommandText property must be a SQL statement or query. Use the
ULCommand.ExecuteNonQuery method to execute a non-query SQL statement, and use either the
ULCommand.ExecuteReader or ULCommand.ExecuteScalar method to execute a query.

Related Information

CommandText property [page 127]

IndexName property [page 132]
ExecuteTable() method [page 124]
ExecuteReader() method [page 116]
CommandText property [page 127]
ExecuteNonQuery() method [page 114]
ExecuteReader() method [page 116]
ExecuteScalar() method [page 122]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 129
4.1.5.20 Connection property

The connection object on which to execute the ULCommand object.

 Syntax

Visual Basic

Public Shadows Property Connection As ULConnection

C#

public new ULConnection Connection {get;set;}

Remarks

The ULConnection object on which to execute the command.

ULCommand objects must have an open connection before they can be executed.

The default is a null reference (Nothing in Visual Basic).

This is the strongly-typed version of System.Data.IDbCommand.Connection and

System.Data.Common.DbCommand.Connection.

Related Information

ULConnection class [page 151]

4.1.5.21 DbConnection property

 Syntax

Visual Basic

Protected Overrides Property DbConnection As DbConnection

C#

protected override DbConnection DbConnection {get;set;}

UltraLite - .NET API Reference

130 PUBLIC UltraLite .NET API reference
4.1.5.22 DbParameterCollection property

 Syntax

Visual Basic

Protected ReadOnly Overrides Property DbParameterCollection As

DbParameterCollection

C#

protected override DbParameterCollection DbParameterCollection {get;}

4.1.5.23 DbTransaction property

 Syntax

Visual Basic

Protected Overrides Property DbTransaction As DbTransaction

C#

protected override DbTransaction DbTransaction {get;set;}

4.1.5.24 DesignTimeVisible property

Indicates if the ULCommand object should be visible in a customized Windows Form Designer control.

 Syntax

Visual Basic

Public Overrides Property DesignTimeVisible As Boolean

C#

public override bool DesignTimeVisible {get;set;}

Remarks

True if this ULCommand object should be visible, false if this object should not be visible. The default is false.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 131
4.1.5.25 IndexName property

UL Ext: Specifies the name of the index to open (sort) the table with when the ULCommand.CommandType
property is System.Data.CommandType.TableDirect.

 Syntax

Visual Basic

Public Property IndexName As String

C#

public string IndexName {get;set;}

Remarks

A string specifying the name of the index. The default is a null reference (Nothing in Visual Basic), meaning the
table is opened with its primary key.

Related Information

ExecuteTable() method [page 124]

ExecuteReader() method [page 116]
CommandType property [page 129]

4.1.5.26 Parameters property

Specifies the parameters for the current statement.

 Syntax

Visual Basic

Public ReadOnly Shadows Property Parameters As ULParameterCollection

C#

public new ULParameterCollection Parameters {get;}

UltraLite - .NET API Reference

132 PUBLIC UltraLite .NET API reference
Remarks

A ULParameterCollection object holding the parameters of the SQL statement. The default value is the empty
collection.

Use question marks in ULCommand.CommandText property value to indicate parameters. The parameters in
the collection are specified in the same order as the question mark placeholders. For example, the first
parameter in the collection corresponds to the first question mark in the SQL statement, the second parameter
in the collection corresponds to the second question mark in the SQL statement, and so on. There must be at
least as many question marks in the ULCommand.CommandText property as there are parameters in this
collection.

This is the strongly-typed version of System.Data.IDbCommand.Parameters and

System.Data.Common.DbCommand.Parameters.

Related Information

ULParameterCollection class [page 433]

ULParameter class [page 413]
CommandText property [page 127]

4.1.5.27 Plan property

UL Ext: Returns the access plan UltraLite.NET uses to execute a query.

 Syntax

Visual Basic

Public ReadOnly Property Plan As String

C#

public unsafe string Plan {get;}

Remarks

This property is intended primarily for use during development.

A string containing the text-based description of the query execution plan.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 133
4.1.5.28 Transaction property

Specifies the ULTransaction object in which the ULCommand object executes.

 Syntax

Visual Basic

Public Shadows Property Transaction As ULTransaction

C#

public new ULTransaction Transaction {get;set;}

Remarks

The ULTransaction object in which the ULCommand object executes. This should be the current transaction of
the connection specified by the ULCommand.Connection object. The default is a null reference (Nothing in
Visual Basic).

If a command is reused after a transaction has been committed or rolled back, this property needs to be reset.

This is the strongly-typed version of System.Data.IDbCommand.Transaction and

System.Data.Common.DbCommand.Transaction.

Related Information

BeginTransaction() method [page 164]

ULTransaction class [page 598]
Connection property [page 130]

4.1.5.29 UpdatedRowSource property

Specifies how command results are applied to the DataRow when used by the ULDataAdapterUpdate method.

 Syntax

Visual Basic

Public Overrides Property UpdatedRowSource As UpdateRowSource

C#

public override UpdateRowSource UpdatedRowSource {get;set;}

UltraLite - .NET API Reference

134 PUBLIC UltraLite .NET API reference
Remarks

One of the System.Data.UpdateRowSource values. The default value is System.Data.UpdateRowSource.Both.

4.1.6 ULCommandBuilder class

Automatically generates single-table commands used to reconcile changes made to a System.Data.DataSet

with the associated database.

 Syntax

Visual Basic

Public Class ULCommandBuilder Inherits System.Data.Common.DbCommandBuilder

C#

public class ULCommandBuilder : System.Data.Common.DbCommandBuilder

Members

All members of ULCommandBuilder, including inherited members.

Constructors

Modifier and Type Constructor Description

public ULCommandBuilder [page 138] Initializes a ULCommandBuilder object.

Methods

Modifier and Type Method Description

protected override void ApplyParameterInfo(DbParameter, Da­

taRow, StatementType, bool) [page
139]

public new ULCommand GetDeleteCommand [page 140] Gets the automatically generated UL­
Command object required to perform
deletions on the database.

public new ULCommand GetInsertCommand [page 143] Gets the automatically generated UL­
Command object required to perform
insertions on the database.

protected override string GetParameterName [page 145] See individual topics

protected override string GetParameterPlaceholder(int) [page

146]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 135
Modifier and Type Method Description

public new ULCommand GetUpdateCommand [page 147] Gets the automatically generated UL­
Command object required to perform
updates on the database.

protected override DbCommand InitializeCommand(DbCommand)

[page 150]

protected override void SetRowUpdatingHandler(DbDataAdap­

ter) [page 150]

Properties

Modifier and Type Property Description

public new ULDataAdapter DataAdapter [page 150] Gets or sets a ULDataAdapter object
for which SQL statements are automat­
ically generated.

Remarks

The ULDataAdapter object does not automatically generate the SQL statements required to reconcile changes
made to a System.Data.DataSet with the associated data source. However, you can create a
ULCommandBuilder object to automatically generate SQL statements for single-table updates if you set the
SelectCommand property of the ULDataAdapter object. Then, any additional SQL statements that you do not
set are generated by the ULCommandBuilder object.

 Example

The following example uses the ULCommand object, along with the ULDataAdapter and ULConnection
objects, to select rows from a data source. The example is passed a connection string, a query string that is
a SQL SELECT statement, and a string that is the name of the database table. The example then creates a
ULCommandBuilder object.

' Visual Basic

Public Shared Function SelectULRows(ByVal connectionString As String, _
ByVal queryString As String, ByVal tableName As String)
Dim connection As ULConnection = New ULConnection(connectionString)
Dim adapter As ULDataAdapter = New ULDataAdapter()
adapter.SelectCommand = New ULCommand(queryString, connection)
Dim builder As ULCommandBuilder = New ULCommandBuilder(adapter)
connection.Open()
Dim dataSet As DataSet = New DataSet()
adapter.Fill(dataSet, tableName)
'Insert code to modify data in DataSet.
'Without the ULCommandBuilder this line would fail
adapter.Update(dataSet, tableName)
Return dataSet
End Function

The following code is the C# language equivalent:

// C#
public static DataSet SelectULRows(string connectionString,
string queryString, string tableName)

UltraLite - .NET API Reference

136 PUBLIC UltraLite .NET API reference
 {
using (ULConnection connection = new ULConnection(connectionString))
{
ULDataAdapter adapter = new ULDataAdapter();
adapter.SelectCommand = new ULCommand(queryString, connection);
ULCommandBuilder builder = new ULCommandBuilder(adapter);
connection.Open();
DataSet dataSet = new DataSet();
adapter.Fill(dataSet, tableName);
// Insert code to modify data in DataSet.
// Without the ULCommandBuilder this line would fail
adapter.Update(dataSet, tableName);
return dataSet;
}
}

In this section:

ULCommandBuilder constructor [page 138]

Initializes a ULCommandBuilder object.

ApplyParameterInfo(DbParameter, DataRow, StatementType, bool) method [page 139]

GetDeleteCommand method [page 140]

Gets the automatically generated ULCommand object required to perform deletions on the database.

GetInsertCommand method [page 143]

Gets the automatically generated ULCommand object required to perform insertions on the database.

GetParameterName method [page 145]

GetParameterPlaceholder(int) method [page 146]

GetUpdateCommand method [page 147]

Gets the automatically generated ULCommand object required to perform updates on the database.

InitializeCommand(DbCommand) method [page 150]

SetRowUpdatingHandler(DbDataAdapter) method [page 150]

DataAdapter property [page 150]

Gets or sets a ULDataAdapter object for which SQL statements are automatically generated.

Related Information

ULCommand class [page 88]

ULConnection class [page 151]
ULDataAdapter class [page 267]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 137
4.1.6.1 ULCommandBuilder constructor

Initializes a ULCommandBuilder object.

Overload list

Modifier and Type Overload name Description

public ULCommandBuilder() [page 138] Initializes a ULCommandBuilder object.

public ULCommandBuilder(ULDataAdapter) Initializes a ULCommandBuilder object

[page 139] with the specified ULDataAdapter ob­
ject.

In this section:

ULCommandBuilder() constructor [page 138]

Initializes a ULCommandBuilder object.

ULCommandBuilder(ULDataAdapter) constructor [page 139]

Initializes a ULCommandBuilder object with the specified ULDataAdapter object.

4.1.6.1.1 ULCommandBuilder() constructor

Initializes a ULCommandBuilder object.

 Syntax

Visual Basic

Public Sub ULCommandBuilder ()

C#

public ULCommandBuilder ()

Related Information

ULCommandBuilder(ULDataAdapter) constructor [page 139]

UltraLite - .NET API Reference

138 PUBLIC UltraLite .NET API reference
4.1.6.1.2 ULCommandBuilder(ULDataAdapter) constructor

Initializes a ULCommandBuilder object with the specified ULDataAdapter object.

 Syntax

Visual Basic

Public Sub ULCommandBuilder (ByVal adapter As ULDataAdapter)

C#

public ULCommandBuilder (ULDataAdapter adapter)

Parameters

adapter A ULDataAdapter object.

Related Information

ULDataAdapter class [page 267]

4.1.6.2 ApplyParameterInfo(DbParameter, DataRow,

StatementType, bool) method

 Syntax

Visual Basic

Protected Overrides Sub ApplyParameterInfo (

ByVal parameter As DbParameter,
ByVal row As DataRow,
ByVal statementType As StatementType,
ByVal whereClause As Boolean
)

C#

protected override void ApplyParameterInfo (

DbParameter parameter,
DataRow row,
StatementType statementType,
bool whereClause
)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 139
4.1.6.3 GetDeleteCommand method

Gets the automatically generated ULCommand object required to perform deletions on the database.

Overload list

Modifier and Type Overload name Description

public new ULCommand GetDeleteCommand() [page 140] Gets the automatically generated UL­
Command object required to perform
deletions on the database.

public new ULCommand GetDeleteCommand(bool) [page 141] Gets the automatically generated UL­
Command object required to perform
deletions on the database.

In this section:

GetDeleteCommand() method [page 140]

Gets the automatically generated ULCommand object required to perform deletions on the database.

GetDeleteCommand(bool) method [page 141]

Gets the automatically generated ULCommand object required to perform deletions on the database.

4.1.6.3.1 GetDeleteCommand() method

Gets the automatically generated ULCommand object required to perform deletions on the database.

 Syntax

Visual Basic

Public Shadows Function GetDeleteCommand () As ULCommand

C#

public new ULCommand GetDeleteCommand ()

Returns

The automatically generated ULCommand object required to perform deletions.

UltraLite - .NET API Reference

140 PUBLIC UltraLite .NET API reference
Exceptions

InvalidOperationException The DbCommandBuilder.DataAdapter property has not been initialized.The

DataAdapter.SelectCommand property has not been initialized.The
DataAdapter.SelectCommand.Connection property has not been initialized.Dynamic SQL generation is not
supported against multiple base tables.Dynamic SQL generation is not supported against a
SelectCommand value that contains duplicate columns.Dynamic SQL generation for the DeleteCommand
property is not supported against a SelectCommand value that does not return any key column
information.

Remarks

After the SQL statement is first generated, the application must explicitly call the
DbCommandBuilder.RefreshSchema method if it changes the ULDataAdapter.SelectCommand value in any
way. Otherwise, the GetDeleteCommand method still uses information from the previous statement, which
might not be correct. The SQL statements are first generated when the application calls either the
DbDataAdapter.Update(System.Data.DataSet) or GetDeleteCommand methods.

Related Information

ULCommand class [page 88]

SelectCommand property [page 279]

4.1.6.3.2 GetDeleteCommand(bool) method

Gets the automatically generated ULCommand object required to perform deletions on the database.

 Syntax

Visual Basic

Public Shadows Function GetDeleteCommand (ByVal

useColumnsForParameterNames As Boolean) As ULCommand

C#

public new ULCommand GetDeleteCommand (bool useColumnsForParameterNames)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 141
Parameters

useColumnsForParameterNames If true, generate parameter names matching column names if possible.

If false, generate @p1, @p2, and so on.

Returns

The automatically generated ULCommand object required to perform deletions.

Exceptions

InvalidOperationException The DbCommandBuilder.DataAdapter property has not been initialized.The

DataAdapter.SelectCommand property has not been initialized.The
DataAdapter.SelectCommand.Connection property has not been initialized.Dynamic SQL generation is not
supported against multiple base tables.Dynamic SQL generation is not supported against a
SelectCommand value that contains duplicate columns.Dynamic SQL generation for the DeleteCommand
property is not supported against a SelectCommand value that does not return any key column
information.

Remarks

After the SQL statement is first generated, the application must explicitly call the
DbCommandBuilder.RefreshSchema method if it changes the ULDataAdapter.SelectCommand value in any
way. Otherwise, the GetDeleteCommand method still uses information from the previous statement, which
might not be correct. The SQL statements are first generated when the application calls either the
DbDataAdapter.Update(System.Data.DataSet) or GetDeleteCommand methods.

Related Information

ULCommand class [page 88]

SelectCommand property [page 279]

UltraLite - .NET API Reference

142 PUBLIC UltraLite .NET API reference
4.1.6.4 GetInsertCommand method

Gets the automatically generated ULCommand object required to perform insertions on the database.

Overload list

Modifier and Type Overload name Description

public new ULCommand GetInsertCommand() [page 143] Gets the automatically generated UL­
Command object required to perform
insertions on the database.

public new ULCommand GetInsertCommand(bool) [page 144] Gets the automatically generated UL­
Command object required to perform
insertions on the database.

In this section:

GetInsertCommand() method [page 143]

Gets the automatically generated ULCommand object required to perform insertions on the database.

GetInsertCommand(bool) method [page 144]

Gets the automatically generated ULCommand object required to perform insertions on the database.

4.1.6.4.1 GetInsertCommand() method

Gets the automatically generated ULCommand object required to perform insertions on the database.

 Syntax

Visual Basic

Public Shadows Function GetInsertCommand () As ULCommand

C#

public new ULCommand GetInsertCommand ()

Returns

The automatically generated ULCommand object required to perform insertions.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 143
Exceptions

InvalidOperationException The DbCommandBuilder.DataAdapter property has not been initialized.The

DataAdapter.SelectCommand property has not been initialized.The
DataAdapter.SelectCommand.Connection property has not been initialized.Dynamic SQL generation for
the InsertCommand property is not supported against a SelectCommand value that does not return any
modifiable columns.Dynamic SQL generation is not supported against multiple base tables.Dynamic SQL
generation is not supported against a SelectCommand value that contains duplicate columns.

Remarks

After the SQL statement is first generated, the application must explicitly call the
DbCommandBuilder.RefreshSchema method if it changes the ULDataAdapter.SelectCommand value in any
way. Otherwise, the GetInsertCommand method still uses information from the previous statement, which
might not be correct. The SQL statements are first generated when the application calls either the
DbDataAdapter.Update(System.Data.DataSet) or GetInsertCommand methods.

Related Information

ULCommand class [page 88]

SelectCommand property [page 279]

4.1.6.4.2 GetInsertCommand(bool) method

Gets the automatically generated ULCommand object required to perform insertions on the database.

 Syntax

Visual Basic

Public Shadows Function GetInsertCommand (ByVal

useColumnsForParameterNames As Boolean) As ULCommand

C#

public new ULCommand GetInsertCommand (bool useColumnsForParameterNames)

Parameters

useColumnsForParameterNames If true, generate parameter names matching column names if possible.

If false, generate @p1, @p2, and so on.

UltraLite - .NET API Reference

144 PUBLIC UltraLite .NET API reference
Returns

The automatically generated ULCommand object required to perform insertions.

Exceptions

InvalidOperationException The DbCommandBuilder.DataAdapter property has not been initialized.The

DataAdapter.SelectCommand property has not been initialized.The
DataAdapter.SelectCommand.Connection property has not been initialized.Dynamic SQL generation for
the InsertCommand property is not supported against a SelectCommand value that does not return any
modifiable columns.Dynamic SQL generation is not supported against multiple base tables.Dynamic SQL
generation is not supported against a SelectCommand value that contains duplicate columns.

Remarks

After the SQL statement is first generated, the application must explicitly call the
DbCommandBuilder.RefreshSchema method if it changes the ULDataAdapter.SelectCommand value in any
way. Otherwise, the GetInsertCommand method still uses information from the previous statement, which
might not be correct. The SQL statements are first generated when the application calls either the
DbDataAdapter.Update(System.Data.DataSet) or GetInsertCommand methods.

Related Information

ULCommand class [page 88]

SelectCommand property [page 279]

4.1.6.5 GetParameterName method

Overload list

Modifier and Type Overload name Description

protected override string GetParameterName(int) [page 146]

protected override string GetParameterName(string) [page 146]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 145
In this section:

GetParameterName(int) method [page 146]

GetParameterName(string) method [page 146]

4.1.6.5.1 GetParameterName(int) method

 Syntax

Visual Basic

Protected Overrides Function GetParameterName (ByVal index As Integer) As

String

C#

protected override string GetParameterName (int index)

4.1.6.5.2 GetParameterName(string) method

 Syntax

Visual Basic

Protected Overrides Function GetParameterName (ByVal parameterName As

String) As String

C#

protected override string GetParameterName (string parameterName)

4.1.6.6 GetParameterPlaceholder(int) method

 Syntax

Visual Basic

Protected Overrides Function GetParameterPlaceholder (ByVal index As

Integer) As String

C#

protected override string GetParameterPlaceholder (int index)

UltraLite - .NET API Reference

146 PUBLIC UltraLite .NET API reference
4.1.6.7 GetUpdateCommand method

Gets the automatically generated ULCommand object required to perform updates on the database.

Overload list

Modifier and Type Overload name Description

public new ULCommand GetUpdateCommand() [page 147] Gets the automatically generated UL­
Command object required to perform
updates on the database.

public new ULCommand GetUpdateCommand(bool) [page 148] Gets the automatically generated UL­
Command object required to perform
updates on the database.

In this section:

GetUpdateCommand() method [page 147]

Gets the automatically generated ULCommand object required to perform updates on the database.

GetUpdateCommand(bool) method [page 148]

Gets the automatically generated ULCommand object required to perform updates on the database.

4.1.6.7.1 GetUpdateCommand() method

Gets the automatically generated ULCommand object required to perform updates on the database.

 Syntax

Visual Basic

Public Shadows Function GetUpdateCommand () As ULCommand

C#

public new ULCommand GetUpdateCommand ()

Returns

The automatically generated ULCommand object required to perform updates.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 147
Exceptions

InvalidOperationException The DbCommandBuilder.DataAdapter property has not been initialized.The

DataAdapter.SelectCommand property has not been initialized.The
DataAdapter.SelectCommand.Connection property has not been initialized.Dynamic SQL generation for
the UpdateCommand property is not supported against a SelectCommand value that does not return any
modifiable columns.Dynamic SQL generation is not supported against multiple base tables.Dynamic SQL
generation is not supported against a SelectCommand value that contains duplicate columns.Dynamic
SQL generation for the UpdateCommand property is not supported against a SelectCommand value that
does not return any key column information.

Remarks

After the SQL statement is first generated, the application must explicitly call the
DbCommandBuilder.RefreshSchema method if it changes the ULDataAdapter.SelectCommand value in any
way. Otherwise, the GetUpdateCommand method still uses information from the previous statement, which
might not be correct. The SQL statements are first generated when the application calls either the
DbDataAdapter.Update(System.Data.DataSet) or GetUpdateCommand methods.

Related Information

ULCommand class [page 88]

SelectCommand property [page 279]

4.1.6.7.2 GetUpdateCommand(bool) method

Gets the automatically generated ULCommand object required to perform updates on the database.

 Syntax

Visual Basic

Public Shadows Function GetUpdateCommand (ByVal

useColumnsForParameterNames As Boolean) As ULCommand

C#

public new ULCommand GetUpdateCommand (bool useColumnsForParameterNames)

UltraLite - .NET API Reference

148 PUBLIC UltraLite .NET API reference
Parameters

useColumnsForParameterNames If true, generate parameter names matching column names if possible.

If false, generate @p1, @p2, and so on.

Returns

The automatically generated ULCommand object required to perform updates.

Exceptions

InvalidOperationException The DbCommandBuilder.DataAdapter property has not been initialized.The

DataAdapter.SelectCommand property has not been initialized.The
DataAdapter.SelectCommand.Connection property has not been initialized.Dynamic SQL generation for
the UpdateCommand property is not supported against a SelectCommand value that does not return any
modifiable columns.Dynamic SQL generation is not supported against multiple base tables.Dynamic SQL
generation is not supported against a SelectCommand value that contains duplicate columns.Dynamic
SQL generation for the UpdateCommand property is not supported against a SelectCommand value that
does not return any key column information.

Remarks

After the SQL statement is first generated, the application must explicitly call the
DbCommandBuilder.RefreshSchema if it changes the ULDataAdapter.SelectCommand in any way. Otherwise,
the GetUpdateCommand method still uses information from the previous statement, which might not be
correct. The SQL statements are first generated when the application calls either the
DbDataAdapter.Update(System.Data.DataSet) or GetUpdateCommand methods.

Related Information

ULCommand class [page 88]

SelectCommand property [page 279]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 149
4.1.6.8 InitializeCommand(DbCommand) method

 Syntax

Visual Basic

Protected Overrides Function InitializeCommand (ByVal command As

DbCommand) As DbCommand

C#

protected override DbCommand InitializeCommand (DbCommand command)

4.1.6.9 SetRowUpdatingHandler(DbDataAdapter) method

 Syntax

Visual Basic

Protected Overrides Sub SetRowUpdatingHandler (ByVal adapter As

DbDataAdapter)

C#

protected override void SetRowUpdatingHandler (DbDataAdapter adapter)

4.1.6.10 DataAdapter property

Gets or sets a ULDataAdapter object for which SQL statements are automatically generated.

 Syntax

Visual Basic

Public Shadows Property DataAdapter As ULDataAdapter

C#

public new ULDataAdapter DataAdapter {get;set;}

Remarks

A ULDataAdapter object.

UltraLite - .NET API Reference

150 PUBLIC UltraLite .NET API reference
Related Information

ULDataAdapter class [page 267]

4.1.7 ULConnection class

Represents a connection to an UltraLite.NET database.

 Syntax

Visual Basic

Public NotInheritable Class ULConnection Inherits

System.Data.Common.DbConnection

C#

public sealed class ULConnection : System.Data.Common.DbConnection

Members

All members of ULConnection, including inherited members.

Variables

Modifier and Type Variable Description

public const long INVALID_DATABASE_ID UL Ext: A database ID constant indicat­

ing that the ULConnection.DatabaseID
property has not been set.

public const String SYNC_ALL_DB Empty publication list, corresponding to

the entire database.

public const String SYNC_ALL_PUBS Publication name "*", corresponding to

all publications.

Constructors

Modifier and Type Constructor Description

public ULConnection [page 157] Initializes a ULConnection object.

Methods

Modifier and Type Method Description

protected override DbTransaction BeginDbTransaction(IsolationLevel)

[page 160]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 151
Modifier and Type Method Description

public IAsyncResult BeginSynchronize [page 160] UL Ext: Asynchronously launches a syn­

chronization using the current the Syn­
cParms object.

public new ULTransaction BeginTransaction [page 163] Returns a transaction object.

public unsafe int CancelGetNotification(string) [page UL Ext: Cancels any pending get­notifi­
166] cation calls on all queues matching the
given name.

public void CancelSynchronize(IAsyncResult) UL Ext: Causes a running synchroniza­

[page 167] tion to be canceled at the next opportu­
nity.

public override void ChangeDatabase(string) [page 168] Changes the current database for an
open connection.

public void ChangeEncryptionKey(string) [page UL Ext: Changes the database's encryp­

169] tion key to the specified new key.

public static void ChangePassword(string, string) [page Changes the password for the user indi­
169] cated in the connection string to the
supplied new password.

public override void Close() [page 170] Closes the database connection.

public unsafe long CountUploadRows(string, long) [page UL Ext: Returns the number of rows
171] that need to be uploaded when the next
synchronization takes place.

public new ULCommand CreateCommand() [page 172] Creates and initializes a ULCommand
object associated with this connection
and its current transaction.

protected override DbCommand CreateDbCommand() [page 172]

public void CreateNotificationQueue(string, string) UL Ext: Creates an event queue.

[page 173]

public void DeclareEvent(string) [page 174] UL Ext: Declares a named event.

public void DestroyNotificationQueue(string) [page UL Ext: Destroys an event queue.

175]

protected override unsafe void Dispose(bool) [page 176] Releases the unmanaged resources
used by the ULCommand object and
optionally releases the managed re­
sources.

public void EndSynchronize(IAsyncResult) [page UL Ext: Blocks until an asynchronously

176] launched synchronization terminates.

public ULTable ExecuteTable [page 177] UL Ext: Retrieves a database table in a

ULTable object for direct manipulation.

public unsafe DateTime GetLastDownloadTime(string) [page UL Ext: Returns the time of the most re­
183] cent download of the specified publica­
tion.

public unsafe Guid GetNewUUID() [page 184] UL Ext: Generates a new UUID (Sys­
tem.Guid).

UltraLite - .NET API Reference

152 PUBLIC UltraLite .NET API reference
 Modifier and Type Method Description

public string GetNotification(string, int) [page 184] UL Ext: Blocks for a notification or time­
out.

public string GetNotificationParameter(string, UL Ext: Gets the value of a parameter

string) [page 186] for an event that was just read by the
GetNotification method.

public override DataTable GetSchema [page 187] Returns the list of supported schema
collections.

public void GrantConnectTo(string, string) [page UL Ext: Grants access to an UltraLite

191] database for a user ID with a specified
password.

public override void Open() [page 192] Opens a connection to a database using
the previously­specified connection
string.

public void RegisterForEvent(string, string, string, UL Ext: Registers a queue to get events
bool) [page 192] from an object.

public void ResetLastDownloadTime(string) [page UL Ext: Resets the time of the most re­
194] cent download.

public void RevokeConnectFrom(string) [page UL Ext: Revokes access to an UltraLite

194] database from the specified user ID.

public void RollbackPartialDownload() [page 195] UL Ext: Rolls back outstanding changes
to the database from a partial down­
load.

public unsafe int SendNotification(string, string, string) UL Ext: Sends a notification to match­
[page 196] ing queues.

public void SetSyncListener(ULSyncProgressLis­ Specifies the listener object used to

tener) [page 197] process synchronization messages.

public void StartSynchronizationDelete() [page UL Ext: Marks all subsequent deletes

198] made by this connection for synchroni­
zation.

public void StopSynchronizationDelete() [page UL Ext: Prevents delete operations from

199] being synchronized.

public void Synchronize [page 200] UL Ext: Synchronizes the database us­
ing the current ULConnection.Syn­
cParms object.

public unsafe int TriggerEvent(string, string) [page 202] UL Ext: Triggers an event.

public void ValidateDatabase [page 203] UL Ext: Performs validation on the cur­
rent database.

Properties

Modifier and Type Property Description

public override string ConnectionString [page 206] Specifies the parameters to use for
opening a connection to an Ultra­
Lite.NET database.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 153
Modifier and Type Property Description

public override int ConnectionTimeout [page 207] This feature is not supported by Ultra­
Lite.NET.

public override string Database [page 207] Returns the name of the database to
which the connection opens.

public unsafe long DatabaseID [page 208] UL Ext: Specifies the Database ID value
to be used for global autoincrement col­
umns.

public override string DataSource [page 209] This feature is not supported by Ultra­
Lite.NET.

public unsafe short GlobalAutoIncrementUsage [page 209] UL Ext: Returns the percentage of avail­
able global autoincrement values that
have been used.

public unsafe ulong LastIdentity [page 210] UL Ext: Returns the most recent iden­
tity value used.

public ULDatabaseSchema Schema [page 210] UL Ext: Provides access to the schema
of the current database associated with
this connection.

public override string ServerVersion [page 211] This feature is not supported by Ultra­
Lite.NET.

public override ConnectionState State [page 212] Returns the current state of the con­
nection.

public ULSyncParms SyncParms [page 212] UL Ext: Specifies the synchronization

settings for this connection.

public ULSyncResult SyncResult [page 213] UL Ext: Returns the results of the last
synchronization for this connection.

Events

Modifier and Type Event Description

public ULInfoMessageEventHandler InfoMessage [page 213] Occurs when UltraLite.NET sends a

warning or an informational message
on this connection.

public override StateChangeEventHan­ StateChange [page 215] Occurs when this connection changes
dler state.

Remarks

To use the UltraLite Engine runtime of UltraLite.NET, set the ULDatabaseManager.RuntimeType property to the
appropriate value before using any other UltraLite.NET API.

A connection to an existing database is opened using the ULConnection.Open method.

You must open a connection before carrying out any other operation, and you must close the connection after
you have finished all operations on the connection and before your application terminates. In addition, you
must close all result sets and tables opened on a connection before closing the connection.

UltraLite - .NET API Reference

154 PUBLIC UltraLite .NET API reference
The schema of the database can be accessed using an open connection's ULConnection.Schema value.

In this section:

ULConnection constructor [page 157]

Initializes a ULConnection object.

BeginDbTransaction(IsolationLevel) method [page 160]

BeginSynchronize method [page 160]

UL Ext: Asynchronously launches a synchronization using the current the SyncParms object.

BeginTransaction method [page 163]

Returns a transaction object.

CancelGetNotification(string) method [page 166]

UL Ext: Cancels any pending get­notification calls on all queues matching the given name.

CancelSynchronize(IAsyncResult) method [page 167]

UL Ext: Causes a running synchronization to be canceled at the next opportunity.

ChangeDatabase(string) method [page 168]

Changes the current database for an open connection.

ChangeEncryptionKey(string) method [page 169]

UL Ext: Changes the database's encryption key to the specified new key.

ChangePassword(string, string) method [page 169]

Changes the password for the user indicated in the connection string to the supplied new password.

Close() method [page 170]

Closes the database connection.

CountUploadRows(string, long) method [page 171]

UL Ext: Returns the number of rows that need to be uploaded when the next synchronization takes
place.

CreateCommand() method [page 172]

Creates and initializes a ULCommand object associated with this connection and its current
transaction.

CreateDbCommand() method [page 172]

CreateNotificationQueue(string, string) method [page 173]

UL Ext: Creates an event queue.

DeclareEvent(string) method [page 174]

UL Ext: Declares a named event.

DestroyNotificationQueue(string) method [page 175]

UL Ext: Destroys an event queue.

Dispose(bool) method [page 176]

Releases the unmanaged resources used by the ULCommand object and optionally releases the
managed resources.

EndSynchronize(IAsyncResult) method [page 176]

UL Ext: Blocks until an asynchronously launched synchronization terminates.

ExecuteTable method [page 177]

UL Ext: Retrieves a database table in a ULTable object for direct manipulation.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 155
 GetLastDownloadTime(string) method [page 183]
UL Ext: Returns the time of the most recent download of the specified publication.

GetNewUUID() method [page 184]

UL Ext: Generates a new UUID (System.Guid).

GetNotification(string, int) method [page 184]

UL Ext: Blocks for a notification or timeout.

GetNotificationParameter(string, string) method [page 186]

UL Ext: Gets the value of a parameter for an event that was just read by the GetNotification method.

GetSchema method [page 187]

Returns the list of supported schema collections.

GrantConnectTo(string, string) method [page 191]

UL Ext: Grants access to an UltraLite database for a user ID with a specified password.

Open() method [page 192]

Opens a connection to a database using the previously­specified connection string.

RegisterForEvent(string, string, string, bool) method [page 192]

UL Ext: Registers a queue to get events from an object.

ResetLastDownloadTime(string) method [page 194]

UL Ext: Resets the time of the most recent download.

RevokeConnectFrom(string) method [page 194]

UL Ext: Revokes access to an UltraLite database from the specified user ID.

RollbackPartialDownload() method [page 195]

UL Ext: Rolls back outstanding changes to the database from a partial download.

SendNotification(string, string, string) method [page 196]

UL Ext: Sends a notification to matching queues.

SetSyncListener(ULSyncProgressListener) method [page 197]

Specifies the listener object used to process synchronization messages.

StartSynchronizationDelete() method [page 198]

UL Ext: Marks all subsequent deletes made by this connection for synchronization.

StopSynchronizationDelete() method [page 199]

UL Ext: Prevents delete operations from being synchronized.

Synchronize method [page 200]

UL Ext: Synchronizes the database using the current ULConnection.SyncParms object.

TriggerEvent(string, string) method [page 202]

UL Ext: Triggers an event.

ValidateDatabase method [page 203]

UL Ext: Performs validation on the current database.

ConnectionString property [page 206]

Specifies the parameters to use for opening a connection to an UltraLite.NET database.

ConnectionTimeout property [page 207]

This feature is not supported by UltraLite.NET.

Database property [page 207]

Returns the name of the database to which the connection opens.

UltraLite - .NET API Reference

156 PUBLIC UltraLite .NET API reference
 DatabaseID property [page 208]
UL Ext: Specifies the Database ID value to be used for global autoincrement columns.

DataSource property [page 209]

This feature is not supported by UltraLite.NET.

GlobalAutoIncrementUsage property [page 209]

UL Ext: Returns the percentage of available global autoincrement values that have been used.

LastIdentity property [page 210]

UL Ext: Returns the most recent identity value used.

Schema property [page 210]

UL Ext: Provides access to the schema of the current database associated with this connection.

ServerVersion property [page 211]

This feature is not supported by UltraLite.NET.

State property [page 212]

Returns the current state of the connection.

SyncParms property [page 212]

UL Ext: Specifies the synchronization settings for this connection.

SyncResult property [page 213]

UL Ext: Returns the results of the last synchronization for this connection.

InfoMessage event [page 213]

Occurs when UltraLite.NET sends a warning or an informational message on this connection.

StateChange event [page 215]

Occurs when this connection changes state.

Related Information

Open() method [page 192]

Schema property [page 210]

4.1.7.1 ULConnection constructor

Initializes a ULConnection object.

Overload list

Modifier and Type Overload name Description

public ULConnection() [page 158] Initializes a ULConnection object.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 157
Modifier and Type Overload name Description

public ULConnection(string) [page 159] Initializes a ULConnection object with

the specified connection string.

In this section:

ULConnection() constructor [page 158]

Initializes a ULConnection object.

ULConnection(string) constructor [page 159]

Initializes a ULConnection object with the specified connection string.

4.1.7.1.1 ULConnection() constructor

Initializes a ULConnection object.

 Syntax

Visual Basic

Public Sub ULConnection ()

C#

public ULConnection ()

Remarks

The connection must be opened before you can perform any operations against the database.

To use the UltraLite Engine runtime of UltraLite.NET, set ULDatabaseManager.RuntimeType property to the
appropriate value before using any other UltraLite.NET API.

The ULConnection object needs to have the ULConnection.ConnectionString property set before it can be
opened.

Related Information

Open() method [page 192]

ConnectionString property [page 206]

UltraLite - .NET API Reference

158 PUBLIC UltraLite .NET API reference
4.1.7.1.2 ULConnection(string) constructor

Initializes a ULConnection object with the specified connection string.

 Syntax

Visual Basic

Public Sub ULConnection (ByVal connectionString As String)

C#

public ULConnection (string connectionString)

Parameters

connectionString An UltraLite.NET connection string. A connection string is a semicolon-separated list of

keyword=value pairs.

Exceptions

ArgumentException The supplied connection string is invalid.

Remarks

The connection must be opened before you can perform any operations against the database.

To use the UltraLite Engine runtime of UltraLite.NET, set the ULDatabaseManager.RuntimeType property to the
appropriate value before using any other UltraLite.NET API.

The connection string can be supplied using a ULConnectionParms object.

 Example

The following code creates and opens a connection to the existing database \UltraLite\MyDatabase.udb on
a Windows Mobile device.

' Visual Basic

Dim openParms As ULConnectionParms = New ULConnectionParms
openParms.DatabaseOnDevice = "\UltraLite\MyDatabase.udb"
Dim conn As ULConnection = _
New ULConnection( openParms.ToString() )
conn.Open()

The following code is the C# language equivalent:

// C#

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 159
 ULConnectionParms openParms = new ULConnectionParms();
openParms.DatabaseOnDevice = @"\UltraLite\MyDatabase.udb";
ULConnection conn = new ULConnection( openParms.ToString() );
conn.Open();

Related Information

Open() method [page 192]

ULConnection() constructor [page 158]
ULConnectionParms class [page 216]
ConnectionString property [page 206]

4.1.7.2 BeginDbTransaction(IsolationLevel) method

 Syntax

Visual Basic

Protected Overrides Function BeginDbTransaction (ByVal isolationLevel As

IsolationLevel) As DbTransaction

C#

protected override DbTransaction BeginDbTransaction (IsolationLevel

isolationLevel)

4.1.7.3 BeginSynchronize method

UL Ext: Asynchronously launches a synchronization using the current the SyncParms object.

Overload list

Modifier and Type Overload name Description

public IAsyncResult BeginSynchronize() [page 161] UL Ext: Asynchronously launches a syn­

chronization using the current the Syn­
cParms object.

UltraLite - .NET API Reference

160 PUBLIC UltraLite .NET API reference
 Modifier and Type Overload name Description

public IAsyncResult BeginSynchronize(Control, ULSync­ UL Ext: Asynchronously launches a syn­

ProgressedDlg, object) [page 162] chronization using the current Syn­
cParms.

In this section:

BeginSynchronize() method [page 161]

UL Ext: Asynchronously launches a synchronization using the current the SyncParms object.

BeginSynchronize(Control, ULSyncProgressedDlg, object) method [page 162]

UL Ext: Asynchronously launches a synchronization using the current SyncParms.

4.1.7.3.1 BeginSynchronize() method

UL Ext: Asynchronously launches a synchronization using the current the SyncParms object.

 Syntax

Visual Basic

Public Function BeginSynchronize () As IAsyncResult

C#

public IAsyncResult BeginSynchronize ()

Returns

An IAsyncResult object that can be used to determine if the sync has completed or block until the sync has
finished.

Exceptions

ULException class A SQL error occurred.

Remarks

This method will create a new thread to do the synchronization and then return immediately. Call the
EndSynchronize method to block until the sync has completed.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 161
Related Information

BeginSynchronize(Control, ULSyncProgressedDlg, object) method [page 162]

EndSynchronize(IAsyncResult) method [page 176]
CancelSynchronize(IAsyncResult) method [page 167]
ULSyncProgressedDlg(IAsyncResult, ULSyncProgressData) delegate [page 606]

4.1.7.3.2 BeginSynchronize(Control,
ULSyncProgressedDlg, object) method

UL Ext: Asynchronously launches a synchronization using the current SyncParms.

 Syntax

Visual Basic

Public Function BeginSynchronize (

ByVal control As Control,
ByVal dlg As ULSyncProgressedDlg,
ByVal state As Object
) As IAsyncResult

C#

public IAsyncResult BeginSynchronize (

Control control,
ULSyncProgressedDlg dlg,
object state
)

Parameters

control A System.Windows.Forms.Control object the synchronization thread will use to invoke

ULSyncProgressedDlg calls.
dlg A ULSyncProgressedDlg method that will be invoked regularly with synchronization progress updates.
state This user context can be accessed in the ULSyncProgressedDlg method using
IAsyncResult.AsyncState.

Returns

An IAsyncResult object that can be used to determine if the sync has completed or block until the sync has
finished.

UltraLite - .NET API Reference

162 PUBLIC UltraLite .NET API reference
Exceptions

ULException class A SQL error occurred.

Remarks

This method creates a new thread to do the synchronization and then return immediately, invoking the
provided ULSyncProgressedDlg method regularly with synchronization progress updates. Call EndSynchronize
to block until the sync has completed.

Related Information

BeginSynchronize() method [page 161]

EndSynchronize(IAsyncResult) method [page 176]
CancelSynchronize(IAsyncResult) method [page 167]
ULSyncProgressedDlg(IAsyncResult, ULSyncProgressData) delegate [page 606]

4.1.7.4 BeginTransaction method

Returns a transaction object.

Overload list

Modifier and Type Overload name Description

public new ULTransaction BeginTransaction() [page 164] Returns a transaction object.

public new ULTransaction BeginTransaction(IsolationLevel) [page Returns a transaction object with the
165] specified isolation level.

In this section:

BeginTransaction() method [page 164]

Returns a transaction object.

BeginTransaction(IsolationLevel) method [page 165]

Returns a transaction object with the specified isolation level.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 163
4.1.7.4.1 BeginTransaction() method

Returns a transaction object.

 Syntax

Visual Basic

Public Shadows Function BeginTransaction () As ULTransaction

C#

public new ULTransaction BeginTransaction ()

Returns

A ULTransaction object representing the new transaction.

Exceptions

ULException class The connection is closed.

InvalidOperationException The ULConnection class does not support parallel transactions.

Remarks

Commands associated with a transaction object are executed as a single transaction. The transaction is
terminated with the ULTransaction.Commit or ULTransaction.Rollback methods.

The transaction is created with the IsolationLevel.ReadCommitted value.

To associate a command with a transaction object, use the ULCommand.Transaction property. The current
transaction is automatically associated to commands created by the ULConnection.CreateCommand method.

By default, the connection does not use transactions and all commands are automatically committed as they
are executed. Once the current transaction is committed or rolled back, the connection reverts to auto commit
mode and the previous isolation level until the next call to BeginTransaction method.

UltraLite's definition of each isolation level is slightly different than ADO.NET's documentation of IsolationLevel.

This is the strongly-typed version of the System.Data.IDbConnection.BeginTransaction and

System.Data.Common.DbConnection.BeginTransaction() methods.

UltraLite - .NET API Reference

164 PUBLIC UltraLite .NET API reference
Related Information

Commit() method [page 600]

Rollback() method [page 601]
Transaction property [page 134]
CreateCommand() method [page 172]

4.1.7.4.2 BeginTransaction(IsolationLevel) method

Returns a transaction object with the specified isolation level.

 Syntax

Visual Basic

Public Shadows Function BeginTransaction (ByVal isolationLevel As

IsolationLevel) As ULTransaction

C#

public new ULTransaction BeginTransaction (IsolationLevel isolationLevel)

Parameters

isolationLevel The required isolation level for the transaction. UltraLite.NET only supports the
System.Data.IsolationLevel.ReadUncommitted and ReadCommitted values.

Returns

A ULTransaction object representing the new transaction.

Exceptions

ULException class The connection is closed or an unsupported isolation level was specified.
InvalidOperationException The ULConnection class does not support parallel transactions.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 165
Remarks

Commands associated with a transaction object are executed as a single transaction. The transaction is
terminated with the ULTransaction.Commit or ULTransaction.Rollback methods.

To associate a command with a transaction object, use the ULCommand.Transaction property. The current
transaction is automatically associated to commands created by the ULConnection.CreateCommand method.

By default, the connection does not use transactions and all commands are automatically committed as they
are executed. Once the current transaction is committed or rolled back, the connection reverts to auto commit
mode and the previous isolation level until the next call to the BeginTransaction method.

UltraLite's definition of each isolation level is slightly different than ADO.NET's documentation of IsolationLevel.

This is the strongly-typed version of the

System.Data.IDbConnection.BeginTransaction(System.Data.IsolationLevel) and
System.Data.Common.DbConnection.BeginTransaction(System.Data.IsolationLevel) methods.

Related Information

ULTransaction class [page 598]

BeginTransaction() method [page 164]
Commit() method [page 600]
Rollback() method [page 601]
Transaction property [page 134]
CreateCommand() method [page 172]

4.1.7.5 CancelGetNotification(string) method

UL Ext: Cancels any pending get­notification calls on all queues matching the given name.

 Syntax

Visual Basic

Public Function CancelGetNotification (ByVal queueName As String) As

Integer

C#

public unsafe int CancelGetNotification (string queueName)

Parameters

queueName The expression to match queue names upon.

UltraLite - .NET API Reference

166 PUBLIC UltraLite .NET API reference
Returns

The number of affected queues (not the number of blocked reads necessarily).

Exceptions

ULException class A SQL error occurred.

Remarks

This method cancels any pending get­notification calls on all queues matching the given name.

Related Information

GetNotification(string, int) method [page 184]

ULException class [page 354]

4.1.7.6 CancelSynchronize(IAsyncResult) method

UL Ext: Causes a running synchronization to be canceled at the next opportunity.

 Syntax

Visual Basic

Public Sub CancelSynchronize (ByVal asyncResult As IAsyncResult)

C#

public void CancelSynchronize (IAsyncResult asyncResult)

Parameters

asyncResult The IAsyncResult returned from the BeginSynchronize method.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 167
Remarks

This method will inform the synchronization thread to terminate and returns immediately. Call the
EndSynchronize method to block until the sync has successfully terminated.

Related Information

BeginSynchronize() method [page 161]

BeginSynchronize(Control, ULSyncProgressedDlg, object) method [page 162]
EndSynchronize(IAsyncResult) method [page 176]

4.1.7.7 ChangeDatabase(string) method

Changes the current database for an open connection.

 Syntax

Visual Basic

Public Overrides Sub ChangeDatabase (ByVal connectionString As String)

C#

public override void ChangeDatabase (string connectionString)

Parameters

connectionString A complete connection string to open the connection to a new database.

Remarks

The connection to the current database is closed even if there are parameter errors.

UL Ext: connectionString is a full connection string, not a dbn or dbf value.

Related Information

ConnectionString property [page 206]

UltraLite - .NET API Reference

168 PUBLIC UltraLite .NET API reference
4.1.7.8 ChangeEncryptionKey(string) method

UL Ext: Changes the database's encryption key to the specified new key.

 Syntax

Visual Basic

Public Sub ChangeEncryptionKey (ByVal newKey As String)

C#

public void ChangeEncryptionKey (string newKey)

Parameters

newKey The new encryption key for the database.

Exceptions

ULException class A SQL error occurred.

Remarks

If the encryption key is lost, it is not possible to open the database.

Related Information

EncryptionKey property [page 224]

4.1.7.9 ChangePassword(string, string) method

Changes the password for the user indicated in the connection string to the supplied new password.

 Syntax

Visual Basic

Public Shared Sub ChangePassword (

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 169
 ByVal connectionString As String,
ByVal newPassword As String
)

C#

public static void ChangePassword (

string connectionString,
string newPassword
)

Parameters

connectionString The connection string that contains enough information to connect to the database that
you want. The connection string may contain the user ID and the current password.
newPassword The new password to set.

Exceptions

ArgumentNullException Either the connectionString or newPassword parameter is null.

ArgumentException The connection string includes the option to use integrated security.
ULException class A SQL error occurred while attempting to open the database.

4.1.7.10 Close() method

Closes the database connection.

 Syntax

Visual Basic

Public Overrides Sub Close ()

C#

public override void Close ()

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

170 PUBLIC UltraLite .NET API reference
Remarks

The Close method rolls back any pending transactions and then closes the connection. An application can call
this method multiple times.

4.1.7.11 CountUploadRows(string, long) method

UL Ext: Returns the number of rows that need to be uploaded when the next synchronization takes place.

 Syntax

Visual Basic

Public Function CountUploadRows (

ByVal pubs As String,
ByVal threshold As Long
) As Long

C#

public unsafe long CountUploadRows (

string pubs,
long threshold
)

Parameters

pubs A comma separated list of publications to check for rows.

threshold The maximum number of rows to count, limiting the amount of time taken by
CountUploadRows. A value of 0 corresponds to the maximum limit. A value of 1 determines if any rows
need to be synchronized.

Returns

The number of rows that need to be uploaded from the specified publication(s).

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 171
4.1.7.12 CreateCommand() method

Creates and initializes a ULCommand object associated with this connection and its current transaction.

 Syntax

Visual Basic

Public Shadows Function CreateCommand () As ULCommand

C#

public new ULCommand CreateCommand ()

Returns

A new ULCommand object.

Remarks

You can use the properties of the ULCommand object to control its behavior.

You must set the ULCommand.CommandText property before the command can be executed.

This is the strongly-typed version of the System.Data.IDbConnection.CreateCommand and

System.Data.Common.DbConnection.CreateCommand methods.

Related Information

ULCommand class [page 88]

CommandText property [page 127]

4.1.7.13 CreateDbCommand() method

 Syntax

Visual Basic

Protected Overrides Function CreateDbCommand () As DbCommand

UltraLite - .NET API Reference

172 PUBLIC UltraLite .NET API reference
 C#

protected override DbCommand CreateDbCommand ()

4.1.7.14 CreateNotificationQueue(string, string) method

UL Ext: Creates an event queue.

 Syntax

Visual Basic

Public Sub CreateNotificationQueue (

ByVal queueName As String,
ByVal parameters As String
)

C#

public void CreateNotificationQueue (

string queueName,
string parameters
)

Parameters

queueName The name of the new queue.

parameters Creation parameters; currently unused, set to NULL.

Exceptions

ULException class A SQL error occurred.

Remarks

This method create an event notification queue for this connection. Queue names are scoped per-connection,
so different connections can create queues with the same name. When an event notification is sent, all queues
in the database with a matching name receive (a separate instance of) the notification. Names are case
insensitive. A default queue is created on demand for each connection when calling the RegisterForEvent event
if no queue is specified.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 173
Related Information

DestroyNotificationQueue(string) method [page 175]

ULException class [page 354]

4.1.7.15 DeclareEvent(string) method

UL Ext: Declares a named event.

 Syntax

Visual Basic

Public Sub DeclareEvent (ByVal eventName As String)

C#

public void DeclareEvent (string eventName)

Parameters

eventName The event name.

Exceptions

ULException class A SQL error occurred.

Remarks

Declare an event which can then be registered for and triggered. UltraLite predefines some system events
triggered by operations on the database or the environment. The event name must be unique. Names are case
insensitive. Throws error if name already used or invalid

Related Information

CreateNotificationQueue(string, string) method [page 173]

ULException class [page 354]

UltraLite - .NET API Reference

174 PUBLIC UltraLite .NET API reference
4.1.7.16 DestroyNotificationQueue(string) method

UL Ext: Destroys an event queue.

 Syntax

Visual Basic

Public Sub DestroyNotificationQueue (ByVal queueName As String)

C#

public void DestroyNotificationQueue (string queueName)

Parameters

queueName The name of the queue.

Exceptions

ULException class A SQL error occurred.

Remarks

Destroy the given event notification queue. A warning is signaled if unread notifications remain in the queue.
Unread notifications are discarded. A connection's default event queue, if created, is destroyed when the
connection is closed.

Related Information

CreateNotificationQueue(string, string) method [page 173]

ULException class [page 354]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 175
4.1.7.17 Dispose(bool) method

Releases the unmanaged resources used by the ULCommand object and optionally releases the managed
resources.

 Syntax

Visual Basic

Protected Overrides Sub Dispose (ByVal disposing As Boolean)

C#

protected override unsafe void Dispose (bool disposing)

Parameters

disposing When true, dispose of both managed and unmanaged resources. When false, dispose of only the
unmanaged resources.

4.1.7.18 EndSynchronize(IAsyncResult) method

UL Ext: Blocks until an asynchronously launched synchronization terminates.

 Syntax

Visual Basic

Public Sub EndSynchronize (ByVal asyncResult As IAsyncResult)

C#

public void EndSynchronize (IAsyncResult asyncResult)

Parameters

asyncResult The IAsyncResult returned from the BeginSynchronize method.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

176 PUBLIC UltraLite .NET API reference
Remarks

If an error occurred during the synchronization, a ULException exception is thrown.

Related Information

BeginSynchronize() method [page 161]

BeginSynchronize(Control, ULSyncProgressedDlg, object) method [page 162]
CancelSynchronize(IAsyncResult) method [page 167]

4.1.7.19 ExecuteTable method

UL Ext: Retrieves a database table in a ULTable object for direct manipulation.

Overload list

Modifier and Type Overload name Description

public ULTable ExecuteTable(string) [page 178] UL Ext: Retrieves a database table in a

ULTable object for direct manipulation.

public ULTable ExecuteTable(string, string) [page 179] UL Ext: Retrieves a database table in a
ULTable object for direct manipulation.

public ULTable ExecuteTable(string, string, Command­ UL Ext: Retrieves, with the specified
Behavior) [page 181] command behavior, a database table
for direct manipulation.

In this section:

ExecuteTable(string) method [page 178]

UL Ext: Retrieves a database table in a ULTable object for direct manipulation.

ExecuteTable(string, string) method [page 179]

UL Ext: Retrieves a database table in a ULTable object for direct manipulation.

ExecuteTable(string, string, CommandBehavior) method [page 181]

UL Ext: Retrieves, with the specified command behavior, a database table for direct manipulation.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 177
4.1.7.19.1 ExecuteTable(string) method

UL Ext: Retrieves a database table in a ULTable object for direct manipulation.

 Syntax

Visual Basic

Public Function ExecuteTable (ByVal tableName As String) As ULTable

C#

public ULTable ExecuteTable (string tableName)

Parameters

tableName The name of the table to open.

Returns

The table as a ULTable object.

Exceptions

ULException class A SQL error occurred.

InvalidOperationException The tableName is invalid.

Remarks

The table is opened (sorted) using the table's primary key.

This method is a shortcut for the ULCommand.ExecuteTable method that does not require a ULCommand
object. It is provided to help users porting from earlier versions of UltraLite.NET (it replaces
Sap.UltraLite.Connection.GetTable and Sap.UltraLite.Table.Open methods).

 Example

The following code opens the table named MyTable using the table's primary key. It assumes an open
ULConnection instance called conn.

' Visual Basic

Dim t As ULTable = conn.ExecuteTable("MyTable")

UltraLite - .NET API Reference

178 PUBLIC UltraLite .NET API reference
 ' The line above is equivalent to
' Dim cmd As ULCommand = conn.CreateCommand()
' cmd.CommandText = "MyTable"
' cmd.CommandType = CommandType.TableDirect
' Dim t As ULTable = cmd.ExecuteTable()
' cmd.Dispose()

The following code is the C# language equivalent:

// C#
ULTable t = conn.ExecuteTable("MyTable");
// The line above is equivalent to
// ULTable t;
// using(ULCommand cmd = conn.CreateCommand())
// {
// cmd.CommandText = "MyTable";
// cmd.CommandType = CommandType.TableDirect;
// t = cmd.ExecuteTable();
// }

Related Information

ExecuteTable(string, string) method [page 179]

ULTable class [page 548]
ExecuteTable() method [page 124]
ULCommand class [page 88]

4.1.7.19.2 ExecuteTable(string, string) method

UL Ext: Retrieves a database table in a ULTable object for direct manipulation.

 Syntax

Visual Basic

Public Function ExecuteTable (

ByVal tableName As String,
ByVal indexName As String
) As ULTable

C#

public ULTable ExecuteTable (

string tableName,
string indexName
)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 179
Parameters

tableName The name of the table to open.

indexName The name of the index with which to open (sort) the table.

Returns

The table as a ULTable object.

Exceptions

ULException class A SQL error occurred.

InvalidOperationException The tableName is invalid.

Remarks

The table is opened (sorted) using the specified index.

This method is a shortcut for the ULCommand.ExecuteTable method that does not require a ULCommand
object. It is provided to help users porting from earlier versions of UltraLite.NET (it replaces
Sap.UltraLite.Connection.GetTable and Sap.UltraLite.Table.Open methods).

 Example

The following code opens the table named MyTable using the index named MyIndex. It assumes an open
ULConnection object called conn.

' Visual Basic

Dim t As ULTable = conn.ExecuteTable("MyTable", "MyIndex")
' The line above is equivalent to
' Dim cmd As ULCommand = conn.CreateCommand()
' cmd.CommandText = "MyTable"
' cmd.IndexName = "MyIndex"
' cmd.CommandType = CommandType.TableDirect
' Dim t As ULTable = cmd.ExecuteTable()
' cmd.Dispose()

The following code is the C# language equivalent:

// C#
ULTable t = conn.ExecuteTable("MyTable", "MyIndex");
// The line above is equivalent to
// ULTable t;
// using(ULCommand cmd = conn.CreateCommand())
// {
// cmd.CommandText = "MyTable";
// cmd.IndexName = "MyIndex";
// cmd.CommandType = CommandType.TableDirect;

UltraLite - .NET API Reference

180 PUBLIC UltraLite .NET API reference
 // t = cmd.ExecuteTable();
// }

Related Information

ExecuteTable(string) method [page 178]

ULTable class [page 548]
ExecuteTable() method [page 124]
ULCommand class [page 88]

4.1.7.19.3 ExecuteTable(string, string, CommandBehavior)

method

UL Ext: Retrieves, with the specified command behavior, a database table for direct manipulation.

 Syntax

Visual Basic

Public Function ExecuteTable (

ByVal tableName As String,
ByVal indexName As String,
ByVal cmdBehavior As CommandBehavior
) As ULTable

C#

public ULTable ExecuteTable (

string tableName,
string indexName,
CommandBehavior cmdBehavior
)

Parameters

tableName The name of the table to open.

indexName The name of the index with which to open (sort) the table.
cmdBehavior A bitwise combination of System.Data.CommandBehavior flags describing the results of the
query and its effect on the connection. UltraLite.NET respects only the
System.Data.CommandBehavior.Default, System.Data.CommandBehavior.CloseConnection, and
System.Data.CommandBehavior.SchemaOnly flags.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 181
Returns

The table as a ULTable object.

Exceptions

ULException class A SQL error occurred.

InvalidOperationException The tableName is invalid.

Remarks

The table is opened (sorted) using the specified index.

This method is a shortcut for the ULCommand.ExecuteTable(System.Data.CommandBehavior) method that

does not require a ULCommand object. It is provided to help users porting from earlier versions of
UltraLite.NET (it replaces Sap.UltraLite.Connection.GetTable and Sap.UltraLite.Table.Open methods).

 Example

The following code opens the table named MyTable using the index named MyIndex. It assumes an open
ULConnection object named conn.

' Visual Basic

Dim t As ULTable = conn.ExecuteTable( _
"MyTable", "MyIndex", CommandBehavior.Default _
)
' The line above is equivalent to the following code:
' Dim cmd As ULCommand = conn.CreateCommand()
' cmd.CommandText = "MyTable"
' cmd.IndexName = "MyIndex"
' cmd.CommandType = CommandType.TableDirect
' Dim t As ULTable = cmd.ExecuteTable(CommandBehavior.Default)
' cmd.Dispose()

The following code is the C# language equivalent:

// C#
ULTable t = conn.ExecuteTable(
"MyTable", "MyIndex", CommandBehavior.Default
);
// The line above is equivalent to the following code:
// ULTable t;
// using(ULCommand cmd = conn.CreateCommand())
// {
// cmd.CommandText = "MyTable";
// cmd.IndexName = "MyIndex";
// cmd.CommandType = CommandType.TableDirect;
// t = cmd.ExecuteTable(CommandBehavior.Default);
// }

UltraLite - .NET API Reference

182 PUBLIC UltraLite .NET API reference
Related Information

ExecuteTable(string) method [page 178]

ExecuteTable(string, string) method [page 179]
ULTable class [page 548]
ULCommand class [page 88]

4.1.7.20 GetLastDownloadTime(string) method

UL Ext: Returns the time of the most recent download of the specified publication.

 Syntax

Visual Basic

Public Function GetLastDownloadTime (ByVal publication As String) As Date

C#

public unsafe DateTime GetLastDownloadTime (string publication)

Parameters

publication The publication to check.

Returns

The timestamp of the last download. If the SYNC_ALL_DB constant is used for publication, returns the time of
the last download of the entire database.

Exceptions

ULException class A SQL error occurred.

Remarks

The parameter publication is a publication name to check.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 183
Related Information

ResetLastDownloadTime(string) method [page 194]

4.1.7.21 GetNewUUID() method

UL Ext: Generates a new UUID (System.Guid).

 Syntax

Visual Basic

Public Function GetNewUUID () As Guid

C#

public unsafe Guid GetNewUUID ()

Returns

A new UUID as a System.Guid.

Exceptions

ULException class A SQL error occurred.

Remarks

This method is provided here because it is not included in the .NET Compact Framework.

4.1.7.22 GetNotification(string, int) method

UL Ext: Blocks for a notification or timeout.

 Syntax

Visual Basic

Public Function GetNotification (

UltraLite - .NET API Reference

184 PUBLIC UltraLite .NET API reference
 ByVal queueName As String,
ByVal wait_ms As Integer
) As String

C#

public string GetNotification (

string queueName,
int wait_ms
)

Parameters

queueName The name of the queue to be waited upon.

wait_ms The time to wait, in milliseconds. Use System.Threading.Timeout.Infinite (-1) for an indefinite wait.

Returns

Null if wait period expired or was canceled; otherwise, returns the event name.

Exceptions

ULException class A SQL error occurred.

Remarks

This method reads an event notification. This call blocks until a notification is received or until the given wait
period expires. To wait indefinitely, pass System.Threading.Timeout.Infinite for the wait_ms parameter. To
cancel a wait, send another notification to the given queue or use the CancelGetNotification method. After
reading a notification, use the ReadNotificationParameter method to retrieve additional parameters.

Related Information

SendNotification(string, string, string) method [page 196]

GetNotificationParameter(string, string) method [page 186]
CancelGetNotification(string) method [page 166]
ULException class [page 354]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 185
4.1.7.23 GetNotificationParameter(string, string) method

UL Ext: Gets the value of a parameter for an event that was just read by the GetNotification method.

 Syntax

Visual Basic

Public Function GetNotificationParameter (

ByVal queueName As String,
ByVal parameterName As String
) As String

C#

public string GetNotificationParameter (

string queueName,
string parameterName
)

Parameters

queueName The name of the queue to be waited upon.

parameterName The name of the parameter whose value should be returned.

Returns

The parameter value if the parameter was found; otherwise, returns null.

Exceptions

ULException class A SQL error occurred.

Remarks

This method get the value of a parameter for the event notification just read by the ULGetNotification method.
Only the parameters from the most-recently read notification on the given queue are available.

UltraLite - .NET API Reference

186 PUBLIC UltraLite .NET API reference
Related Information

GetNotification(string, int) method [page 184]

ULException class [page 354]

4.1.7.24 GetSchema method

Returns the list of supported schema collections.

Overload list

Modifier and Type Overload name Description

public override DataTable GetSchema() [page 188] Returns the list of supported schema
collections.

public override DataTable GetSchema(string) [page 188] Returns information for the specified
metadata collection for this ULConnec­
tion object.

public override DataTable GetSchema(string, string[]) [page 189] Returns schema information for the
data source of this ULConnection ob­
ject and, if specified, uses the specified
string for the schema name and the
specified string array for the restriction
values.

In this section:

GetSchema() method [page 188]

Returns the list of supported schema collections.

GetSchema(string) method [page 188]

Returns information for the specified metadata collection for this ULConnection object.

GetSchema(string, string[]) method [page 189]

Returns schema information for the data source of this ULConnection object and, if specified, uses the
specified string for the schema name and the specified string array for the restriction values.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 187
4.1.7.24.1 GetSchema() method

Returns the list of supported schema collections.

 Syntax

Visual Basic

Public Overrides Function GetSchema () As DataTable

C#

public override DataTable GetSchema ()

4.1.7.24.2 GetSchema(string) method

Returns information for the specified metadata collection for this ULConnection object.

 Syntax

Visual Basic

Public Overrides Function GetSchema (ByVal collection As String) As

DataTable

C#

public override DataTable GetSchema (string collection)

Parameters

collection The name of the metadata collection. If no name is provided, the MetaDataCollections value is
used.

Related Information

GetSchema(string, string[]) method [page 189]

ULConnection class [page 151]

UltraLite - .NET API Reference

188 PUBLIC UltraLite .NET API reference
4.1.7.24.3 GetSchema(string, string[]) method

Returns schema information for the data source of this ULConnection object and, if specified, uses the
specified string for the schema name and the specified string array for the restriction values.

 Syntax

Visual Basic

Public Overrides Function GetSchema (

ByVal collection As String,
ByVal restrictions As String()
) As DataTable

C#

public override DataTable GetSchema (

string collection,
string[] restrictions
)

Parameters

collection The name of the metadata collection. If no name is provided, the MetaDataCollections is used.
restrictions A set of restriction values for the requested schema.

Returns

A DataTable object that contains schema information.

Remarks

This method is used to query the database for various metadata. Each type of metadata is given a collection
name, which must be passed to receive that data. The default collection name is MetaDataCollections.

You can query the .NET data provider to determine the list of supported schema collections by calling the
GetSchema method with no arguments, or with the schema collection name MetaDataCollections. This returns
a DataTable with a list of the supported schema collections (CollectionName), the number of restrictions that
they each support (NumberOfRestrictions), and the number of identifier parts that they use
(NumberOfIdentifierParts).

Collection Metadata

Columns Returns information about all columns in the database.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 189
Collection Metadata

DataSourceInformation Returns information about the database provider.

DataTypes Returns a list of supported data types.

ForeignKeys Returns information about all foreign keys in the database.

IndexColumns Returns information about all index columns in the database.

Indexes Returns information about all indexes in the database.

MetaDataCollections Returns a list of all collection names.

Publications Returns information about all publications in the database.

ReservedWords Returns a list of reserved words used by UltraLite.

Restrictions Returns information about restrictions used in GetSchema.

Tables Returns information about all tables in the database.

These collection names are also available as read-only properties in the ULMetaDataCollectionNames class.

The results returned can be filtered by specifying an array of restrictions in the call to the GetSchema method.

The restrictions available with each collection can be queried by calling:

GetSchema( "Restrictions" )

If the collection requires four restrictions, then the restrictions parameter must be either NULL, or a string with
four values.

To filter on a particular restriction, place the string to filter by in its place in the array and leave any unused
places NULL. For example, the Tables collection has three restrictions: Table, TableType, SyncType.

To filter the Table collection:

GetSchema( "Tables", new string[ ] { "my_table", NULL, NULL } ) Returns information about all tables named
my_table.

GetSchema( "Tables", new string[ ] { NULL, "User", NULL } ) Returns information about all user tables.

Related Information

ULConnection class [page 151]

ULMetaDataCollectionNames class [page 401]

UltraLite - .NET API Reference

190 PUBLIC UltraLite .NET API reference
4.1.7.25 GrantConnectTo(string, string) method

UL Ext: Grants access to an UltraLite database for a user ID with a specified password.

 Syntax

Visual Basic

Public Sub GrantConnectTo (

ByVal uid As String,
ByVal pwd As String
)

C#

public void GrantConnectTo (

string uid,
string pwd
)

Parameters

uid The user ID to receive access to the database.

pwd The password to be associated with the user ID.

Remarks

If an existing user ID is specified, this function updates the password for the user. UltraLite supports a
maximum of 4 users. This method is enabled only if user authentication was enabled when the connection was
opened.

Related Information

UserID property [page 225]

Password property [page 224]
ConnectionString property [page 206]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 191
4.1.7.26 Open() method

Opens a connection to a database using the previously­specified connection string.

 Syntax

Visual Basic

Public Overrides Sub Open ()

C#

public override void Open ()

Exceptions

InvalidOperationException The connection is already open or the connection string is not specified in the
ULConnection.ConnectionString property.
ULException class A SQL error occurred while attempting to open the database.

Remarks

You should explicitly close or dispose of the connection when you are done with it.

Related Information

ConnectionString property [page 206]

State property [page 212]

4.1.7.27 RegisterForEvent(string, string, string, bool) method

UL Ext: Registers a queue to get events from an object.

 Syntax

Visual Basic

Public Sub RegisterForEvent (

ByVal eventName As String,
ByVal objectName As String,
ByVal queueName As String,
ByVal registerNotUnReg As Boolean

UltraLite - .NET API Reference

192 PUBLIC UltraLite .NET API reference
 )

C#

public void RegisterForEvent (

string eventName,
string objectName,
string queueName,
bool registerNotUnReg
)

Parameters

eventName The event name.

objectName The object name to which event applies. For example, a table name.
queueName The event queue name to be used.
registerNotUnReg True to register; false to unregister.

Exceptions

ULException class A SQL error occurred.

Remarks

This method registers a queue to receive notifications of an event. The default connection queue is implied and
created if a queue name is not supplied. Certain system events allow specification of an object name to which
the event applies. For example, the TableModified event can specify the table name. Unlike the
SendNotification method, only the specific queue registered receives notifications of the event; other queues
with the same name on different connections do not (unless they are also explicit registered). This method
throws an error if the queue or event does not exist.

Related Information

DeclareEvent(string) method [page 174]

CreateNotificationQueue(string, string) method [page 173]
ULException class [page 354]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 193
4.1.7.28 ResetLastDownloadTime(string) method

UL Ext: Resets the time of the most recent download.

 Syntax

Visual Basic

Public Sub ResetLastDownloadTime (ByVal pubs As String)

C#

public void ResetLastDownloadTime (string pubs)

Exceptions

ULException class A SQL error occurred.

Related Information

GetLastDownloadTime(string) method [page 183]

4.1.7.29 RevokeConnectFrom(string) method

UL Ext: Revokes access to an UltraLite database from the specified user ID.

 Syntax

Visual Basic

Public Sub RevokeConnectFrom (ByVal uid As String)

C#

public void RevokeConnectFrom (string uid)

Parameters

uid The user ID whose access to the database is being revoked.

UltraLite - .NET API Reference

194 PUBLIC UltraLite .NET API reference
Exceptions

ULException class A SQL error occurred.

Related Information

GrantConnectTo(string, string) method [page 191]

4.1.7.30 RollbackPartialDownload() method

UL Ext: Rolls back outstanding changes to the database from a partial download.

 Syntax

Visual Basic

Public Sub RollbackPartialDownload ()

C#

public void RollbackPartialDownload ()

Exceptions

ULException class A SQL error occurred.

Related Information

KeepPartialDownload property [page 516]

ResumePartialDownload property [page 520]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 195
4.1.7.31 SendNotification(string, string, string) method

UL Ext: Sends a notification to matching queues.

 Syntax

Visual Basic

Public Function SendNotification (

ByVal queueName As String,
ByVal eventName As String,
ByVal parameters As String
) As Integer

C#

public unsafe int SendNotification (

string queueName,
string eventName,
string parameters
)

Parameters

queueName The event queue name to be used.

eventName The event name.
parameters Parameters to pass.

Returns

The number of notifications sent (the number of matching queues).

Exceptions

ULException class A SQL error occurred.

Remarks

Returns the number of matching queues.

This method send a notification to all queues matching the given name (including any such queue on the
current connection). This call does not block. Use the special queue name "*" to send to all queues.

UltraLite - .NET API Reference

196 PUBLIC UltraLite .NET API reference
Related Information

DeclareEvent(string) method [page 174]

RegisterForEvent(string, string, string, bool) method [page 192]
ULException class [page 354]

4.1.7.32 SetSyncListener(ULSyncProgressListener) method

Specifies the listener object used to process synchronization messages.

 Syntax

Visual Basic

Public Sub SetSyncListener (ByVal listener As ULSyncProgressListener)

C#

public void SetSyncListener (ULSyncProgressListener listener)

Parameters

listener The ULSyncProgressListener object that implements the SyncProgressed method, which is called
for synchronization messages on this connection.

Exceptions

ULException class A SQL error occurred.

Remarks

When the SYNCHRONIZE profileName SQL statement is executed, its progress messages are routed to a
syncListener object, if not null (Nothing in Visual Basic).

To remove the listener, pass a null reference in a call to the SetSyncListener method.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 197
Related Information

ULSyncProgressListener interface [page 540]

4.1.7.33 StartSynchronizationDelete() method

UL Ext: Marks all subsequent deletes made by this connection for synchronization.

 Syntax

Visual Basic

Public Sub StartSynchronizationDelete ()

C#

public void StartSynchronizationDelete ()

Exceptions

ULException class A SQL error occurred.

Remarks

When this method is called, all delete operations are again synchronized, causing the rows deleted from the
UltraLite database to be removed from the consolidated database as well.

Related Information

StopSynchronizationDelete() method [page 199]

Truncate() method [page 576]

UltraLite - .NET API Reference

198 PUBLIC UltraLite .NET API reference
4.1.7.34 StopSynchronizationDelete() method

UL Ext: Prevents delete operations from being synchronized.

 Syntax

Visual Basic

Public Sub StopSynchronizationDelete ()

C#

public void StopSynchronizationDelete ()

Exceptions

ULException class A SQL error occurred.

Remarks

This method is useful for deleting old information about an UltraLite database to save space, while not deleting
this information about the consolidated database.

Related Information

StartSynchronizationDelete() method [page 198]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 199
4.1.7.35 Synchronize method

UL Ext: Synchronizes the database using the current ULConnection.SyncParms object.

Overload list

Modifier and Type Overload name Description

public void Synchronize() [page 200] UL Ext: Synchronizes the database us­
ing the current ULConnection.Syn­
cParms object.

public void Synchronize(ULSyncProgressListener) UL Ext: Synchronizes the database us­

[page 201] ing the current ULConnection.Syn­
cParms object with progress events
posted to the specified listener.

In this section:

Synchronize() method [page 200]

UL Ext: Synchronizes the database using the current ULConnection.SyncParms object.

Synchronize(ULSyncProgressListener) method [page 201]

UL Ext: Synchronizes the database using the current ULConnection.SyncParms object with progress
events posted to the specified listener.

4.1.7.35.1 Synchronize() method

UL Ext: Synchronizes the database using the current ULConnection.SyncParms object.

 Syntax

Visual Basic

Public Sub Synchronize ()

C#

public void Synchronize ()

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

200 PUBLIC UltraLite .NET API reference
Remarks

A detailed result status is reported in this connection's ULConnection.SyncResult property.

Related Information

Synchronize(ULSyncProgressListener) method [page 201]

SyncParms property [page 212]
SyncResult property [page 213]

4.1.7.35.2 Synchronize(ULSyncProgressListener) method

UL Ext: Synchronizes the database using the current ULConnection.SyncParms object with progress events
posted to the specified listener.

 Syntax

Visual Basic

Public Sub Synchronize (ByVal listener As ULSyncProgressListener)

C#

public void Synchronize (ULSyncProgressListener listener)

Parameters

listener The object that receives synchronization progress events.

Exceptions

ULException class A SQL error occurred.

Remarks

Errors during synchronization are posted as a ULSyncProgressState.STATE_ERROR event, then thrown as a

ULException.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 201
A detailed result status is reported in this connection's ULConnection.SyncResult property.

Related Information

ULSyncProgressListener interface [page 540]

Synchronize() method [page 200]
SyncParms property [page 212]
ULException class [page 354]
SyncResult property [page 213]

4.1.7.36 TriggerEvent(string, string) method

UL Ext: Triggers an event.

 Syntax

Visual Basic

Public Function TriggerEvent (

ByVal eventName As String,
ByVal parameters As String
) As Integer

C#

public unsafe int TriggerEvent (

string eventName,
string parameters
)

Parameters

eventName The event name to be triggered.

parameters Parameters to pass.

Returns

The number of event notifications sent.

UltraLite - .NET API Reference

202 PUBLIC UltraLite .NET API reference
Exceptions

ULException class A SQL error occurred.

Remarks

Returns the number of notifications sent.

This method triggers an event (and send notification to all registered queues).

Related Information

DeclareEvent(string) method [page 174]

RegisterForEvent(string, string, string, bool) method [page 192]
ULException class [page 354]

4.1.7.37 ValidateDatabase method

UL Ext: Performs validation on the current database.

Overload list

Modifier and Type Overload name Description

public void ValidateDatabase(ULDBValid) [page UL Ext: Performs validation on the cur­

204] rent database.

public void ValidateDatabase(ULDBValid, string) UL Ext: Performs validation on the cur­

[page 205] rent database.

In this section:

ValidateDatabase(ULDBValid) method [page 204]

UL Ext: Performs validation on the current database.

ValidateDatabase(ULDBValid, string) method [page 205]

UL Ext: Performs validation on the current database.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 203
4.1.7.37.1 ValidateDatabase(ULDBValid) method

UL Ext: Performs validation on the current database.

 Syntax

Visual Basic

Public Sub ValidateDatabase (ByVal how As ULDBValid)

C#

public void ValidateDatabase (ULDBValid how)

Parameters

how Describes how to validate the database.

Exceptions

ULException class A SQLE_CORRUPT_ULTRALITE_INDEX or SQLE_CORRUPT_ULTRALITE_DATABASE

error may occur if the database is corrupt.

 Example

The following code validates the current database

' Visual Basic

conn.ValidateDatabase( Sap.Data.UltraLite.ULVF_INDEX )

The following code is the C# language equivalent:

// C#
conn.ValidateDatabase( Sap.Data.UltraLite.ULVF_INDEX )

Related Information

ValidateDatabase(string, ULDBValid) method [page 290]

ULDBValid enumeration [page 612]

UltraLite - .NET API Reference

204 PUBLIC UltraLite .NET API reference
4.1.7.37.2 ValidateDatabase(ULDBValid, string) method

UL Ext: Performs validation on the current database.

 Syntax

Visual Basic

Public Sub ValidateDatabase (

ByVal how As ULDBValid,
ByVal tableName As String
)

C#

public void ValidateDatabase (

ULDBValid how,
string tableName
)

Parameters

how Describes how to validate the database.

tableName If null (Nothing in Visual Basic), validate the entire database; otherwise, validate just the named
table.

Exceptions

ULException class A SQLE_CORRUPT_ULTRALITE_INDEX or SQLE_CORRUPT_ULTRALITE_DATABASE

error may occur if the database is corrupt.

 Example

The following code validates the current database

' Visual Basic

conn.ValidateDatabase( Sap.Data.UltraLite.ULVF_INDEX, Nothing )

The following code is the C# language equivalent:

// C#
conn.ValidateDatabase( Sap.Data.UltraLite.ULVF_INDEX, null )

Related Information

ValidateDatabase(string, ULDBValid) method [page 290]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 205
ULDBValid enumeration [page 612]

4.1.7.38 ConnectionString property

Specifies the parameters to use for opening a connection to an UltraLite.NET database.

 Syntax

Visual Basic

Public Overrides Property ConnectionString As String

C#

public override string ConnectionString {get;set;}

Remarks

The connection string can be supplied using a ULConnectionParms object.

The parameters used to open this connection should be a semicolon-separated list of keyword=value pairs.
The default is an empty string (an invalid connection string).

UL Ext: The parameters used by UltraLite.NET are specific to UltraLite databases and therefore the connection
string is not compatible with SQL Anywhere connection strings.

Parameter values can be quoted with either single quote characters or double quote characters provided that
the quoted contents do not contain quote characters of the same type. Values must be quoted if they contain
semicolons, begin with a quote, or require leading or trailing whitespace.

If you are not quoting parameter values, make sure that they do not contain semicolons, and that they begin
with either a single quote or a double quote character. Leading and trailing spaces in values are ignored.

By default, connections are opened with UID=DBA and PWD=sql. To make the database more secure, change
the user DBA's password or create new users (using the GrantConnectTo method) and remove the DBA user
(using RevokeConnectFrom).

 Example

The following code creates and opens a connection to the existing database \UltraLite\MyDatabase.udb on
a Windows Mobile device.

' Visual Basic

Dim openParms As ULConnectionParms = New ULConnectionParms
openParms.DatabaseOnDevice = "\UltraLite\MyDatabase.udb"
Dim conn As ULConnection = New ULConnection
conn.ConnectionString = openParms.ToString()
conn.Open()

The following code is the C# language equivalent:

// C#

UltraLite - .NET API Reference

206 PUBLIC UltraLite .NET API reference
 ULConnectionParms openParms = new ULConnectionParms();
openParms.DatabaseOnDevice = @"\UltraLite\MyDatabase.udb";
ULConnection conn = new ULConnection();
conn.ConnectionString = openParms.ToString();
conn.Open();

Related Information

Open() method [page 192]

ULConnectionParms class [page 216]
GrantConnectTo(string, string) method [page 191]

4.1.7.39 ConnectionTimeout property

This feature is not supported by UltraLite.NET.

 Syntax

Visual Basic

Public ReadOnly Overrides Property ConnectionTimeout As Integer

C#

public override int ConnectionTimeout {get;}

Remarks

The value is always zero.

4.1.7.40 Database property

Returns the name of the database to which the connection opens.

 Syntax

Visual Basic

Public ReadOnly Overrides Property Database As String

C#

public override string Database {get;}

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 207
Remarks

A string containing the name of the database.

On Windows Mobile devices, the ULConnection object looks in the connection string in the following order: dbn,
ce_file.

On desktop machines, the ULConnection object looks in the connection string in the following order: dbn,
nt_file.

4.1.7.41 DatabaseID property

UL Ext: Specifies the Database ID value to be used for global autoincrement columns.

 Syntax

Visual Basic

Public Property DatabaseID As Long

C#

public unsafe long DatabaseID {get;set;}

Remarks

The Database ID value of the current database.

The database ID value must be in the range [0,System.UInt32.MaxValue]. A value of

ULConnection.INVALID_DATABASE_ID is used to indicate that the database ID has not been set for the current
database.

Related Information

GetDatabaseProperty(string) method [page 294]

SetDatabaseOption(string, string) method [page 298]

UltraLite - .NET API Reference

208 PUBLIC UltraLite .NET API reference
4.1.7.42 DataSource property

This feature is not supported by UltraLite.NET.

 Syntax

Visual Basic

Public ReadOnly Overrides Property DataSource As String

C#

public override string DataSource {get;}

Remarks

The value is always the empty string.

4.1.7.43 GlobalAutoIncrementUsage property

UL Ext: Returns the percentage of available global autoincrement values that have been used.

 Syntax

Visual Basic

Public ReadOnly Property GlobalAutoIncrementUsage As Short

C#

public unsafe short GlobalAutoIncrementUsage {get;}

Remarks

The percentage of available global autoincrement values that have been used. It is an integer in the range
[0-100], inclusive.

If the percentage approaches 100, your application should set a new value for the global database ID using the
ULConnection.DatabaseID value.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 209
Related Information

ULDatabaseManager class [page 283]

DatabaseID property [page 208]

4.1.7.44 LastIdentity property

UL Ext: Returns the most recent identity value used.

 Syntax

Visual Basic

Public ReadOnly Property LastIdentity As ULong

C#

public unsafe ulong LastIdentity {get;}

Remarks

The most recently-used identity value as an unsigned long.

The most recent identity value used. This property is equivalent to the SQL Anywhere statement:

SELECT @identity

The LastIdentity property is particularly useful in the context of global autoincrement columns.

Since this property only allows you to determine the most recently assigned default value, you should retrieve
this value soon after executing the insert statement to avoid spurious results.

Occasionally, a single insert statement may include more than one column of type global autoincrement. In this
case, the LastIdentity property is one of the generated default values, but there is no reliable means to
determine from which column the value is. For this reason, you should design your database and write your
insert statements to avoid this situation.

4.1.7.45 Schema property

UL Ext: Provides access to the schema of the current database associated with this connection.

 Syntax

Visual Basic

Public ReadOnly Property Schema As ULDatabaseSchema

UltraLite - .NET API Reference

210 PUBLIC UltraLite .NET API reference
 C#

public ULDatabaseSchema Schema {get;}

Remarks

A reference to the ULDatabaseSchema object representing the schema of the database on which this
connection opens.

This property is only valid while its connection is open.

Related Information

ULDatabaseSchema class [page 292]

4.1.7.46 ServerVersion property

This feature is not supported by UltraLite.NET.

 Syntax

Visual Basic

Public ReadOnly Overrides Property ServerVersion As String

C#

public override string ServerVersion {get;}

Remarks

The value is always the empty string.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 211
4.1.7.47 State property

Returns the current state of the connection.

 Syntax

Visual Basic

Public ReadOnly Overrides Property State As ConnectionState

C#

public override ConnectionState State {get;}

Remarks

Returns System.Data.ConnectionState.Open if the connection is open, or

System.Data.ConnectionState.Closed if the connection is closed.

Related Information

StateChange event [page 215]

4.1.7.48 SyncParms property

UL Ext: Specifies the synchronization settings for this connection.

 Syntax

Visual Basic

Public ReadOnly Property SyncParms As ULSyncParms

C#

public ULSyncParms SyncParms {get;}

Remarks

A reference to the ULSyncParms object representing the parameters used for synchronization by this
connection. Modifications to the parameters affect the next synchronization made over this connection.

UltraLite - .NET API Reference

212 PUBLIC UltraLite .NET API reference
Related Information

Synchronize() method [page 200]

SyncResult property [page 213]
ULSyncParms class [page 509]

4.1.7.49 SyncResult property

UL Ext: Returns the results of the last synchronization for this connection.

 Syntax

Visual Basic

Public ReadOnly Property SyncResult As ULSyncResult

C#

public ULSyncResult SyncResult {get;}

Remarks

A reference to the ULSyncResult object representing the results of the last synchronization for this connection.

Related Information

Synchronize() method [page 200]

SyncParms property [page 212]

4.1.7.50 InfoMessage event

Occurs when UltraLite.NET sends a warning or an informational message on this connection.

 Syntax

Visual Basic

Public Event InfoMessage As ULInfoMessageEventHandler

C#

public ULInfoMessageEventHandler InfoMessage;

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 213
Remarks

To process UltraLite.NET warnings or informational messages, you must create a ULInfoMessageEventHandler

delegate and attach it to this event.

 Example

The following code defines an informational message event handler:

' Visual Basic

Private Sub MyInfoMessageHandler( _
obj As Object, args As ULInfoMessageEventArgs _
)
System.Console.WriteLine( _
"InfoMessageHandler: " + args.NativeError + ", " _
+ args.Message _
)
End Sub

The following code is the C# language equivalent:

// C#
private void MyInfoMessageHandler(
object obj, ULInfoMessageEventArgs args
)
{
System.Console.WriteLine(
"InfoMessageHandler: " + args.NativeError + ", "
+ args.Message
);
}

The following code adds the MyInfoMessageHandler method to the connection named conn.

' Visual Basic

AddHandler conn.InfoMessage, AddressOf MyInfoMessageHandler

The following code is the C# language equivalent:

// C#
conn.InfoMessage +=
new ULInfoMessageEventHandler(MyInfoMessageHandler);

Related Information

ULInfoMessageEventHandler(object, ULInfoMessageEventArgs) delegate [page 603]

UltraLite - .NET API Reference

214 PUBLIC UltraLite .NET API reference
4.1.7.51 StateChange event
Occurs when this connection changes state.

 Syntax

Visual Basic

Public Event StateChange As StateChangeEventHandler

C#

public override StateChangeEventHandler StateChange;

Remarks

To process state change messages, you must create a System.Data.StateChangeEventHandler delegate and
attach it to this event.

 Example

The following code defines a state change event handler.

' Visual Basic

Private Sub MyStateHandler( _
obj As Object, args As StateChangeEventArgs _
)
System.Console.WriteLine( _
"StateHandler: " + args.OriginalState + " to " _
+ args.CurrentState _
)
End Sub

The following code is the C# language equivalent:

// C#
private void MyStateHandler(
object obj, StateChangeEventArgs args
)
{
System.Console.WriteLine(
"StateHandler: " + args.OriginalState + " to "
+ args.CurrentState
);
}

The following code adds the MyStateHandler to the connection named conn.

' Visual Basic

AddHandler conn.StateChange, AddressOf MyStateHandler

The following code is the C# language equivalent:

// C#
conn.StateChange += new StateChangeEventHandler(MyStateHandler);

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 215
4.1.8 ULConnectionParms class

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

 Syntax

Visual Basic

Public Class ULConnectionParms Inherits System.ComponentModel.Component

C#

public class ULConnectionParms : System.ComponentModel.Component

Members

All members of ULConnectionParms, including inherited members.

Constructors

Modifier and Type Constructor Description

public ULConnectionParms() [page 219] Initializes a ULConnectionParms in­

stance with its default values.

Methods

Modifier and Type Method Description

public override string ToString() [page 219] Returns the string representation of
this instance.

Properties

Modifier and Type Property Description

public string AdditionalParms [page 220] Specifies additional parameters as a

semicolon-separated list of
name=value pairs.

public string CacheSize [page 221] Specifies the size of the cache.

public string ConnectionName [page 222] Specifies a name for the connection.

public string DatabaseOnDesktop [page 223] Specifies the path and file name of the
UltraLite database on Windows desktop
platforms.

public string DatabaseOnDevice [page 223] Specifies the path and file name of the
UltraLite database on Windows Mobile.

public string EncryptionKey [page 224] Specifies a key for encrypting the data­
base.

UltraLite - .NET API Reference

216 PUBLIC UltraLite .NET API reference
 Modifier and Type Property Description

public string Password [page 224] Specifies the password for the authenti­
cated user.

public string UserID [page 225] 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.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 217
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.

In this section:

ULConnectionParms() constructor [page 219]

Initializes a ULConnectionParms instance with its default values.

ToString() method [page 219]

Returns the string representation of this instance.

AdditionalParms property [page 220]

Specifies additional parameters as a semicolon-separated list of name=value pairs.

CacheSize property [page 221]

Specifies the size of the cache.

ConnectionName property [page 222]

Specifies a name for the connection.

DatabaseOnDesktop property [page 223]

Specifies the path and file name of the UltraLite database on Windows desktop platforms.

DatabaseOnDevice property [page 223]

Specifies the path and file name of the UltraLite database on Windows Mobile.

EncryptionKey property [page 224]

Specifies a key for encrypting the database.

Password property [page 224]

Specifies the password for the authenticated user.

UserID property [page 225]

Specifies an authenticated user for the database.

Related Information

Open() method [page 192]

DropDatabase(string) method [page 286]
ToString() method [page 219]
ULConnection class [page 151]
ULConnection class [page 151]
ConnectionString property [page 206]
UserID property [page 225]
Password property [page 224]
EncryptionKey property [page 224]

UltraLite - .NET API Reference

218 PUBLIC UltraLite .NET API reference
CacheSize property [page 221]
ConnectionName property [page 222]
AdditionalParms property [page 220]
RevokeConnectFrom(string) method [page 194]
GrantConnectTo(string, string) method [page 191]
ChangeEncryptionKey(string) method [page 169]

4.1.8.1 ULConnectionParms() constructor

Initializes a ULConnectionParms instance with its default values.

 Syntax

Visual Basic

Public Sub ULConnectionParms ()

C#

public ULConnectionParms ()

4.1.8.2 ToString() method

Returns the string representation of this instance.

 Syntax

Visual Basic

Public Overrides Function ToString () As String

C#

public override string ToString ()

Returns

The string representation of this instance as a semicolon-separated list keyword=value pairs.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 219
4.1.8.3 AdditionalParms property

Specifies additional parameters as a semicolon-separated list of name=value pairs.

 Syntax

Visual Basic

Public Property AdditionalParms As String

C#

public string AdditionalParms {get;set;}

Remarks

These parameters are used less frequently.

A semicolon-separated list of keyword=value additional parameters. Values of the keyword=value list must
conform to the rules for ULConnection.ConnectionString. The default is a null reference (Nothing in Visual
Basic).

The values for the page size and reserve size parameters are specified in units of bytes. Use the suffix k or K to
indicate units of kilobytes and the suffix m or M to indicate megabytes.

Additional parameters are:

Keyword Description

dbn Identifies a loaded database to which a connection needs to

be made. When a database is started, it is assigned a data­
base name, either explicitly with the dbn parameter, or by Ul­
traLite using the base of the file name with the extension and
path removed. When opening connections, UltraLite first
searches for a running database with a matching dbn value.
If one is not found, UltraLite starts a new database using the
appropriate database file name parameter (with the Databa­
seOnDevice or DatabaseOnDesktop properties). This param­
eter is required if the application (or UltraLite engine) needs
to access two different databases that have the same base
file name. This parameter is only used when opening a con­
nection with the ULConnection.Open method.

UltraLite - .NET API Reference

220 PUBLIC UltraLite .NET API reference
 Keyword Description

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 inserting any data. Reserving file system space can
improve performance slightly and also prevent out of mem­
ory failures. By default, the persistent storage file only grows
when required as the application updates the database. The
reserve_size parameter reserves file system space, which in­
cludes the metadata in the persistent store file, and not just
the raw data. The metadata overhead and data compression
must be considered when deriving the required file system
space from the amount of database data. 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 trun­
cated. The following parameter string ensures that the per­
sistent store file is at least 2 MB upon startup: create­
Parms.AdditionalParms = "reserve_size=2m" This parame­
ter is only used when opening a connection with the ULCon­
nection.Open method.

start Specifies the location and then starts the UltraLite engine.
Only supply a StartLine (START) connection parameter if
you are connecting to an engine that is not currently run­
ning. The location is only required when the UltraLite engine
is not in the system path.

Related Information

RuntimeType property [page 291]

ConnectionString property [page 206]
DatabaseOnDevice property [page 223]
DatabaseOnDesktop property [page 223]
Open() method [page 192]

4.1.8.4 CacheSize property

Specifies the size of the cache.

 Syntax

Visual Basic

Public Property CacheSize As String

C#

public string CacheSize {get;set;}

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 221
Remarks

A string specifying the cache size. The default is a null reference (Nothing in Visual Basic) meaning the default
of 16 pages is used.

The values for the cache size are specified in units of bytes. Use the suffix k or K to indicate units of kilobytes
and the suffix of m or M to indicate megabytes.

For example, the following sets the cache size to 128 KB.

connParms.CacheSize = "128k"

The default cache size is 16 pages. Using the default page size of 4 KB, the default cache size is therefore 64
KB. 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 cache size beyond the size of the database itself provides no performance improvement and
large cache sizes might interfere with the number of other applications you can use.

If the cache size is unspecified or improperly specified, the default size is used.

4.1.8.5 ConnectionName property

Specifies a name for the connection.

 Syntax

Visual Basic

Public Property ConnectionName As String

C#

public string ConnectionName {get;set;}

Remarks

This is only needed if you create more than one connection to the database.

A string specifying the name of the connection. The default is a null reference (Nothing in Visual Basic).

UltraLite - .NET API Reference

222 PUBLIC UltraLite .NET API reference
4.1.8.6 DatabaseOnDesktop property

Specifies the path and file name of the UltraLite database on Windows desktop platforms.

 Syntax

Visual Basic

Public Property DatabaseOnDesktop As String

C#

public string DatabaseOnDesktop {get;set;}

Remarks

A string specifying the absolute or relative path to the database. If the value is a null reference (Nothing in
Visual Basic), the database ulstore.udb is used. In C#, you must escape any backslash characters in paths or
use @-quoted string literals. The default is a null reference (Nothing in Visual Basic).

4.1.8.7 DatabaseOnDevice property

Specifies the path and file name of the UltraLite database on Windows Mobile.

 Syntax

Visual Basic

Public Property DatabaseOnDevice As String

C#

public string DatabaseOnDevice {get;set;}

Remarks

A string specifying the full path to the database. If the value is a null reference (Nothing in Visual Basic), the
database \UltraLiteDB\ulstore.udb is used. In C#, you must escape any backslash characters in paths or use
@-quoted string literals. The default is a null reference (Nothing in Visual Basic).

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 223
4.1.8.8 EncryptionKey property

Specifies a key for encrypting the database.

 Syntax

Visual Basic

Public Property EncryptionKey As String

C#

public string EncryptionKey {get;set;}

Remarks

A string specifying the encryption key. The default is a null reference (Nothing in Visual Basic) meaning no
encryption.

All connections must use the same key as was specified when the database was created. Lost or forgotten keys
result in completely inaccessible databases.

As with all passwords, it is best to choose a key value that cannot be easily guessed. The key can be of arbitrary
length, but generally the longer the key, the better, because a shorter key is easier to guess than a longer one.
Using a combination of numbers, letters, and special characters decreases the chances of someone guessing
the key.

Related Information

ChangeEncryptionKey(string) method [page 169]

4.1.8.9 Password property

Specifies the password for the authenticated user.

 Syntax

Microsoft Visual Basic

Public Property Password As String

C#

public string Password {get;set;}

UltraLite - .NET API Reference

224 PUBLIC UltraLite .NET API reference
Remarks

A string specifying a database user ID. The default is a null reference (Nothing in Microsoft Visual Basic).

Passwords are case sensitive.

Related Information

UserID property [page 225]

4.1.8.10 UserID property

Specifies an authenticated user for the database.

 Syntax

Visual Basic

Public Property UserID As String

C#

public string UserID {get;set;}

Remarks

A string specifying a database user ID. The default value is a null reference (Nothing in Visual Basic).

User IDs are case-insensitive.

Databases are initially created with a single authenticated user named DBA.

If both the user ID and password are not supplied, the user DBA with password sql are used. To make the
database more secure, change the user DBA's password or create new users (with the
ULConnection.GrantConnectTo method) and remove the DBA user (with the
ULConnection.RevokeConnectFrom method).

Related Information

Password property [page 224]

GrantConnectTo(string, string) method [page 191]
RevokeConnectFrom(string) method [page 194]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 225
4.1.9 ULConnectionStringBuilder class

Builds a connection string for opening a connection to an UltraLite database.

 Syntax

Visual Basic

Public NotInheritable Class ULConnectionStringBuilder Inherits

System.Data.Common.DbConnectionStringBuilder

C#

public sealed class ULConnectionStringBuilder :

System.Data.Common.DbConnectionStringBuilder

Members

All members of ULConnectionStringBuilder, including inherited members.

Constructors

Modifier and Type Constructor Description

public ULConnectionStringBuilder [page 230] Initializes a ULConnectionStringBuilder

object with its default values.

Methods

Modifier and Type Method Description

public override bool ContainsKey(string) [page 231] Determines whether the ULConnection­
StringBuilder object contains a specific
keyword.

public override bool EquivalentTo(DbConnectionString­ Compares the connection information

Builder) [page 232] in this ULConnectionStringBuilder ob­
ject with the connection information in
the supplied DbConnectionString­
Builder object.

public static string GetShortName(string) [page 232] Retrieves the short version of the sup­
plied keyword.

public override bool Remove(string) [page 233] Removes the entry with the specified
key from the ULConnectionString­
Builder object.

public override bool TryGetValue(string, out Object) [page Retrieves a value corresponding to the
233] supplied key from this ULConnection­
StringBuilder object.

Properties

UltraLite - .NET API Reference

226 PUBLIC UltraLite .NET API reference
 Modifier and Type Property Description

public string CacheSize [page 234] UL Ext: Specifies the size of the cache.

public string ConnectionName [page 235] Specifies a name for the connection.

public string DatabaseKey [page 236] Specifies a key for encrypting the data­
base.

public string DatabaseName [page 236] Specifies a name for the database or
the name of a loaded database to which
a connection needs to be made.

public string DatabaseOnDesktop [page 237] UL Ext: Specifies the path and file name
of the UltraLite database on Windows
desktop platforms.

public string DatabaseOnDevice [page 238] UL Ext: Specifies the path and file name
of the UltraLite database on Windows
Mobile.

public string OrderedTableScans [page 238] Specifies whether SQL queries without
ORDER BY clauses should perform or­
dered table scans by default.

public string Password [page 239] Specifies the password for the authenti­
cated user.

public string ReserveSize [page 239] UL Ext: Specifies the reserve file system
space for storage of UltraLite persistent
data.

public string StartLine [page 240] Specifies the location and then starts
the UltraLite engine.

public override object this[string keyword] [page 241] Specifies the value of the specified con­
nection keyword.

public string UserID [page 242] Specifies an authenticated user for the
database.

Remarks

The frequently-used connection parameters are individual properties on the ULConnectionStringBuilder

object.

The ULConnectionStringBuilder class is not available in the .NET Compact Framework 2.0.

A ULConnectionStringBuilder 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
ULConnectionStringBuilder object, you create a connection string using the
System.Data.Common.DbConnectionStringBuilder.ConnectionString. The resulting string is used to create a

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 227
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 ULConnectionStringBuilder = _
new ULConnectionStringBuilder
dbName.DatabaseOnDevice = "\UltraLite\mydb1.udb"
dbName.DatabaseOnDesktop = "somedir\mydb2.udb"

The following code is the C# language equivalent:

// C#
ULConnectionStringBuilder dbName = new ULConnectionStringBuilder();
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 ULConnectionStringBuilder.UserID value, a non-default ULConnectionStringBuilder.Password value, a
database ULConnectionStringBuilder.DatabaseKey value, and the ULConnectionStringBuilder.CacheSize
value. If your application is using multiple connections, you should provide a unique
ULConnectionStringBuilder.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, call the
ULConnection.RevokeConnectFrom method. To add a user or change a user's password, call 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.

In this section:

ULConnectionStringBuilder constructor [page 230]

Initializes a ULConnectionStringBuilder object with its default values.

ContainsKey(string) method [page 231]

Determines whether the ULConnectionStringBuilder object contains a specific keyword.

EquivalentTo(DbConnectionStringBuilder) method [page 232]

Compares the connection information in this ULConnectionStringBuilder object with the connection
information in the supplied DbConnectionStringBuilder object.

GetShortName(string) method [page 232]

UltraLite - .NET API Reference

228 PUBLIC UltraLite .NET API reference
 Retrieves the short version of the supplied keyword.

Remove(string) method [page 233]

Removes the entry with the specified key from the ULConnectionStringBuilder object.

TryGetValue(string, out Object) method [page 233]

Retrieves a value corresponding to the supplied key from this ULConnectionStringBuilder object.

CacheSize property [page 234]

UL Ext: Specifies the size of the cache.

ConnectionName property [page 235]

Specifies a name for the connection.

DatabaseKey property [page 236]

Specifies a key for encrypting the database.

DatabaseName property [page 236]

Specifies a name for the database or the name of a loaded database to which a connection needs to be
made.

DatabaseOnDesktop property [page 237]

UL Ext: Specifies the path and file name of the UltraLite database on Windows desktop platforms.

DatabaseOnDevice property [page 238]

UL Ext: Specifies the path and file name of the UltraLite database on Windows Mobile.

OrderedTableScans property [page 238]

Specifies whether SQL queries without ORDER BY clauses should perform ordered table scans by
default.

Password property [page 239]

Specifies the password for the authenticated user.

ReserveSize property [page 239]

UL Ext: Specifies the reserve file system space for storage of UltraLite persistent data.

StartLine property [page 240]

Specifies the location and then starts the UltraLite engine.

this[string keyword] property [page 241]

Specifies the value of the specified connection keyword.

UserID property [page 242]

Specifies an authenticated user for the database.

Related Information

Open() method [page 192]

DropDatabase(string) method [page 286]
ULConnection class [page 151]
ULConnection class [page 151]
ConnectionString property [page 206]
DatabaseName property [page 236]
UserID property [page 242]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 229
Password property [page 239]
DatabaseKey property [page 236]
CacheSize property [page 234]
ConnectionName property [page 235]
RevokeConnectFrom(string) method [page 194]
GrantConnectTo(string, string) method [page 191]
ChangeEncryptionKey(string) method [page 169]

4.1.9.1 ULConnectionStringBuilder constructor

Initializes a ULConnectionStringBuilder object with its default values.

Overload list

Modifier and Type Overload name Description

public ULConnectionStringBuilder() [page Initializes a ULConnectionStringBuilder

230] object with its default values.

public ULConnectionStringBuilder(string) Initializes a ULConnectionStringBuilder

[page 231] object with the specified connection
string.

In this section:

ULConnectionStringBuilder() constructor [page 230]

Initializes a ULConnectionStringBuilder object with its default values.

ULConnectionStringBuilder(string) constructor [page 231]

Initializes a ULConnectionStringBuilder object with the specified connection string.

4.1.9.1.1 ULConnectionStringBuilder() constructor

Initializes a ULConnectionStringBuilder object with its default values.

 Syntax

Visual Basic

Public Sub ULConnectionStringBuilder ()

C#

public ULConnectionStringBuilder ()

UltraLite - .NET API Reference

230 PUBLIC UltraLite .NET API reference
4.1.9.1.2 ULConnectionStringBuilder(string) constructor

Initializes a ULConnectionStringBuilder object with the specified connection string.

 Syntax

Visual Basic

Public Sub ULConnectionStringBuilder (ByVal connectionString As String)

C#

public ULConnectionStringBuilder (string connectionString)

Parameters

connectionString An UltraLite.NET connection string. A connection string is a semicolon-separated list of

keyword=value pairs.

4.1.9.2 ContainsKey(string) method

Determines whether the ULConnectionStringBuilder object contains a specific keyword.

 Syntax

Visual Basic

Public Overrides Function ContainsKey (ByVal keyword As String) As Boolean

C#

public override bool ContainsKey (string keyword)

Parameters

keyword The name of the connection keyword.

Returns

True if this connection string builder contains a value for the specified keyword, otherwise returns false.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 231
4.1.9.3 EquivalentTo(DbConnectionStringBuilder) method

Compares the connection information in this ULConnectionStringBuilder object with the connection
information in the supplied DbConnectionStringBuilder object.

 Syntax

Visual Basic

Public Overrides Function EquivalentTo (ByVal connectionStringBuilder As

DbConnectionStringBuilder) As Boolean

C#

public override bool EquivalentTo (DbConnectionStringBuilder

connectionStringBuilder)

Parameters

connectionStringBuilder The other DbConnectionStringBuilder object to compare this

ULConnectionStringBuilder object to.

Returns

True if this object is equivalent to the specified DbConnectionStringBuilder object; otherwise, returns false.

4.1.9.4 GetShortName(string) method

Retrieves the short version of the supplied keyword.

 Syntax

Visual Basic

Public Shared Function GetShortName (ByVal keyword As String) As String

C#

public static string GetShortName (string keyword)

UltraLite - .NET API Reference

232 PUBLIC UltraLite .NET API reference
Parameters

keyword The key of the item to retrieve.

Returns

The short version of the supplied keyword if keyword is recognized, null otherwise.

4.1.9.5 Remove(string) method

Removes the entry with the specified key from the ULConnectionStringBuilder object.

 Syntax

Visual Basic

Public Overrides Function Remove (ByVal keyword As String) As Boolean

C#

public override bool Remove (string keyword)

Parameters

keyword The name of the connection keyword.

Returns

True if the key existed within the connection string and was removed; false if the key did not exist.

4.1.9.6 TryGetValue(string, out Object) method

Retrieves a value corresponding to the supplied key from this ULConnectionStringBuilder object.

 Syntax

Visual Basic

Public Overrides Function TryGetValue (

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 233
 ByVal keyword As String,
ByVal value As Object
) As Boolean

C#

public override bool TryGetValue (

string keyword,
out Object value
)

Parameters

keyword The key of the item to retrieve.

value The value corresponding to the key.

Returns

True if keyword was found within the connection string, false otherwise.

Remarks

The TryGetValue method lets developers safely retrieve a value from a ULConnectionStringBuilder without
needing to first call the ContainsKey method. Because the TryGetValue method does not raise an exception
when you call it, passing in a nonexistent key, you do not have to look for a key before retrieving its value.
Calling TryGetValue with a nonexistent key places the null value (Nothing in Visual Basic) in the value
parameter.

4.1.9.7 CacheSize property

UL Ext: Specifies the size of the cache.

 Syntax

Visual Basic

Public Property CacheSize As String

C#

public string CacheSize {get;set;}

UltraLite - .NET API Reference

234 PUBLIC UltraLite .NET API reference
Remarks

A string specifying the cache size. The default is a null reference (Nothing in Visual Basic) meaning the default
of 16 pages is used.

The values for the cache size are specified in units of bytes. Use the suffix k or K to indicate units of kilobytes
and the suffix of m or M to indicate megabytes.

For example, the following sets the cache size to 128 KB.

connParms.CacheSize = "128k"

The default cache size is 16 pages. Using the default page size of 4 KB, the default cache size is therefore 64
KB. 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 cache size beyond the size of the database itself provides no performance improvement and
large cache sizes might interfere with the number of other applications you can use.

If the cache size is unspecified or improperly specified, the default size is used.

4.1.9.8 ConnectionName property

Specifies a name for the connection.

 Syntax

Visual Basic

Public Property ConnectionName As String

C#

public string ConnectionName {get;set;}

Remarks

This is only needed if you create more than one connection to the database.

A string specifying the name of the connection. The default is a null reference (Nothing in Visual Basic).

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 235
4.1.9.9 DatabaseKey property

Specifies a key for encrypting the database.

 Syntax

Visual Basic

Public Property DatabaseKey As String

C#

public string DatabaseKey {get;set;}

Remarks

A string specifying the encryption key. The default is a null reference (Nothing in Visual Basic) meaning no
encryption.

All connections must use the same key as was specified when the database was created. Lost or forgotten keys
result in completely inaccessible databases.

As with all passwords, it is best to choose a key value that cannot be easily guessed. The key can be of arbitrary
length, but generally the longer the key, the better, because a shorter key is easier to guess than a longer one.
Using a combination of numbers, letters, and special characters decreases the chances of someone guessing
the key.

Related Information

ChangeEncryptionKey(string) method [page 169]

4.1.9.10 DatabaseName property

Specifies a name for the database or the name of a loaded database to which a connection needs to be made.

 Syntax

Visual Basic

Public Property DatabaseName As String

C#

public string DatabaseName {get;set;}

UltraLite - .NET API Reference

236 PUBLIC UltraLite .NET API reference
Remarks

A string specifying the name of the database. The default is a null reference (Nothing in Visual Basic).

When a database is started, it is assigned a database name, either explicitly with the dbn parameter, or by
UltraLite using the base of the file name with the extension and path removed.

When opening connections, UltraLite first searches for a running database with a matching dbn parameter. If
one is not found, UltraLite starts a new database using the appropriate database file name parameter (the
DatabaseOnDevice or DatabaseOnDesktop properties).

This parameter is required if the application (or UltraLite engine) needs to access two different databases that
have the same base file name.

Related Information

DatabaseOnDevice property [page 238]

DatabaseOnDesktop property [page 237]

4.1.9.11 DatabaseOnDesktop property

UL Ext: Specifies the path and file name of the UltraLite database on Windows desktop platforms.

 Syntax

Visual Basic

Public Property DatabaseOnDesktop As String

C#

public string DatabaseOnDesktop {get;set;}

Remarks

A string specifying the absolute or relative path to the database. If the value is a null reference (Nothing in
Visual Basic), the database ulstore.udb is used. In C#, you must escape any backslash characters in paths or
use @-quoted string literals. The default is a null reference (Nothing in Visual Basic).

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 237
4.1.9.12 DatabaseOnDevice property

UL Ext: Specifies the path and file name of the UltraLite database on Windows Mobile.

 Syntax

Visual Basic

Public Property DatabaseOnDevice As String

C#

public string DatabaseOnDevice {get;set;}

Remarks

A string specifying the full path to the database. If the value is a null reference (Nothing in Visual Basic), the
database \UltraLiteDB\ulstore.udb is used. In C#, you must escape any backslash characters in paths or use
@-quoted string literals. The default is a null reference (Nothing in Visual Basic).

4.1.9.13 OrderedTableScans property

Specifies whether SQL queries without ORDER BY clauses should perform ordered table scans by default.

 Syntax

Visual Basic

Public Property OrderedTableScans As String

C#

public string OrderedTableScans {get;set;}

Remarks

A boolean string specifying whether to use ordered table scans or not. For example, true/false, yes/no, 1/0,
and so on. The default value is a null reference (Nothing in Visual Basic).

When using dynamic SQL in UltraLite, if order is not important for executing a query, UltraLite accesses the
rows directly from the database pages rather than using the primary key index. This improves performance of
fetching rows. To use this optimization, the query must be read only and must scan all the rows.

When rows are expected in a specific order, an ORDER BY statement should be included as part of the SQL
query. However, it's possible that some applications have come to rely on the behavior that defaults to

UltraLite - .NET API Reference

238 PUBLIC UltraLite .NET API reference
returning rows in the primary key order. In this case, users should set the OrderedTableScans parameter to 1
(true, yes, on) to revert to the old behavior when iterating over a table.

When the OrderedTableScans value is set to 1 (true, yes, on) and the user does not specify an ORDER BY
clause or if a query would not benefit from an index, UltraLite defaults to using the primary key.

4.1.9.14 Password property

Specifies the password for the authenticated user.

 Syntax

Visual Basic

Public Property Password As String

C#

public string Password {get;set;}

Remarks

A string specifying a database user ID. The default is a null reference (Nothing in Visual Basic).

Passwords are case sensitive.

When a database is created, the password for the DBA user ID is set to sql.

Related Information

UserID property [page 242]

4.1.9.15 ReserveSize property

UL Ext: Specifies the reserve file system space for storage of UltraLite persistent data.

 Syntax

Visual Basic

Public Property ReserveSize As String

C#

public string ReserveSize {get;set;}

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 239
Remarks

A string specifying the reserve size. The default is a null reference (Nothing in Visual Basic).

The values for the reserve size parameter is specified in units of bytes. Use the suffix k or K to indicate units of
kilobytes and the suffix m or M to indicate megabytes.

The reserve_size parameter allows you to pre-allocate the file system space required for your UltraLite
database without 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.

The reserve_size reserves file system space, which includes the metadata in the persistent store file, and not
just the raw data. The metadata overhead and data compression must be considered when deriving the
required file system space from the amount of database data.

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.

The following parameter string ensures that the persistent store file is at least 2 MB upon startup.

connParms.ReserveSize = "2m"

4.1.9.16 StartLine property

Specifies the location and then starts the UltraLite engine.

 Syntax

Visual Basic

Public Property StartLine As String

C#

public string StartLine {get;set;}

Remarks

A string specifying the location of the UltraLite engine executable. The default value is a null reference (Nothing
in Visual Basic).

Only supply a StartLine (START) connection parameter if you are connecting to an engine that is not currently
running.

UltraLite - .NET API Reference

240 PUBLIC UltraLite .NET API reference
Related Information

RuntimeType property [page 291]

4.1.9.17 this[string keyword] property

Specifies the value of the specified connection keyword.

 Syntax

Visual Basic

Public Overrides Property Item (ByVal keywordAs String) As Object

C#

public override object this[string keyword] {get;set;}

Remarks

An object representing the value of the specified connection keyword.

Connection keywords and the corresponding properties of the ULConnectionStringBuilder class are described
in the table below:

Keyword Corresponding Property

cache_size ULConnectionStringBuilder.CacheSize

ce_file ULConnectionStringBuilder.DatabaseOnDevice

con ULConnectionStringBuilder.ConnectionName

dbkey ULConnectionStringBuilder.DatabaseKey

dbn ULConnectionStringBuilder.DatabaseName

nt_file ULConnectionStringBuilder.DatabaseOnDesktop

pwd ULConnectionStringBuilder.Password

reserve_size ULConnectionStringBuilder.ReserveSize

start ULConnectionStringBuilder.StartLine

uid ULConnectionStringBuilder.UserID

Related Information

CacheSize property [page 234]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 241
DatabaseOnDevice property [page 238]
ConnectionName property [page 235]
DatabaseKey property [page 236]
DatabaseName property [page 236]
DatabaseOnDesktop property [page 237]
Password property [page 239]
ReserveSize property [page 239]
StartLine property [page 240]
UserID property [page 242]

4.1.9.18 UserID property

Specifies an authenticated user for the database.

 Syntax

Visual Basic

Public Property UserID As String

C#

public string UserID {get;set;}

Remarks

A string specifying a database user ID. The default value is a null reference (Nothing in Visual Basic).

User IDs are case-insensitive.

Databases are initially created with a single authenticated user named DBA.

If both the user ID and password are not supplied, the user DBA with password sql are used. To make the
database more secure, change the user DBA's password or create new users (with the
ULConnection.GrantConnectTo method) and remove the DBA user (with the
ULConnection.RevokeConnectFrom method).

Related Information

Password property [page 239]

GrantConnectTo(string, string) method [page 191]
RevokeConnectFrom(string) method [page 194]

UltraLite - .NET API Reference

242 PUBLIC UltraLite .NET API reference
4.1.10 ULCreateParms class

UL Ext: Builds a string of creation-time options for creating an UltraLite database.

 Syntax

Visual Basic

Public Class ULCreateParms

C#

public class ULCreateParms

Members

All members of ULCreateParms, including inherited members.

Constructors

Modifier and Type Constructor Description

public ULCreateParms() [page 246] Initializes a ULCreateParms object with

its default values.

Methods

Modifier and Type Method Description

public override string ToString() [page 247] Returns the string representation of
this instance.

Properties

Modifier and Type Property Description

public bool CaseSensitive [page 247] Specifies whether the new database
should be case sensitive when compar­
ing string values.

public int ChecksumLevel [page 248] Specifies the level of database page
checksums enabled for the new data­
base.

public string DateFormat [page 248] Specifies the date format used for
string conversions by the new data­
base.

public ULDateOrder DateOrder [page 249] Specifies the date order used for string
conversions by the new database.

public bool FIPS [page 249] Specifies whether the new database
should be using AES_FIPS encryption
or AES encryption.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 243
Modifier and Type Property Description

public int MaxHashSize [page 250] Specifies the default maximum number
of bytes to use for index hashing in the
new database.

public int NearestCentury [page 250] Specifies the nearest century used for
string conversions by the new data­
base.

public bool Obfuscate [page 251] Specifies whether the new database
should use obfuscation to encrypt the
database.

public int PageSize [page 251] Specifies the page size, in bytes or kilo­
bytes, of the new database.

public int Precision [page 252] Specifies the floating­point precision

used for string conversions by the new
database.

public int Scale [page 253] Specifies the minimum number of dig­
its after the decimal point when an
arithmetic result is truncated to the
maximum precision during string con­
versions by the new database.

public string TimeFormat [page 253] Specifies the time format used for
string conversions by the new data­
base.

public string TimestampFormat [page 254] Specifies the timestamp format used
for string conversions by the new data­
base.

public int TimestampIncrement [page 254] Specifies the minimum difference be­
tween two unique timestamps, in mi­
croseconds (1,000,000th of a second).

public bool UTF8Encoding [page 255] Specifies whether the new database
should be using the UTF8 character set
or the character set associated with the
collation.

Remarks

A ULCreateParms object is used to specify the parameters for creating a database with the
ULDatabaseManager.CreateDatabase method.

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

Once you have supplied all the creation parameters by setting the appropriate properties on a ULCreateParms
object, you create a creation parameters string using the ULCreateParms.ToString method. The resulting string
can then be used as the createParms parameter of the ULDatabaseManager.CreateDatabase method.

UltraLite - .NET API Reference

244 PUBLIC UltraLite .NET API reference
  Example

The following code creates the database \UltraLite\MyDatabase.udb on a Windows Mobile device. The
database is created case sensitive and with the UTF8 character set.

' Visual Basic

Dim createParms As ULCreateParms = New ULCreateParms
createParms.CaseSensitive = True
createParms.UTF8Encoding = True
Dim openParms As ULConnectionParms = New ULConnectionParms
openParms.DatabaseOnDevice = "\UltraLite\MyDatabase.udb"
ULConnection.DatabaseManager.CreateDatabase( _
openParms.ToString(), _
createParms.ToString() _
)
Dim conn As ULConnection = _
New ULConnection( openParms.ToString() )
conn.Open()

The following code is the C# language equivalent:

// C#
ULCreateParms createParms = new ULCreateParms();
createParms.CaseSensitive = true;
createParms.UTF8Encoding = true;
ULConnectionParms openParms = new ULConnectionParms();
openParms.DatabaseOnDevice = ".udb";
ULConnection.DatabaseManager.CreateDatabase(
openParms.ToString(),
createParms.ToString()
);
ULConnection conn = new ULConnection( openParms.ToString() );
conn.Open();

In this section:

ULCreateParms() constructor [page 246]

Initializes a ULCreateParms object with its default values.

ToString() method [page 247]

Returns the string representation of this instance.

CaseSensitive property [page 247]

Specifies whether the new database should be case sensitive when comparing string values.

ChecksumLevel property [page 248]

Specifies the level of database page checksums enabled for the new database. This topic has been
updated for 17.0 PL 41 Build 5745.

DateFormat property [page 248]

Specifies the date format used for string conversions by the new database.

DateOrder property [page 249]

Specifies the date order used for string conversions by the new database.

FIPS property [page 249]

Specifies whether the new database should be using AES_FIPS encryption or AES encryption.

MaxHashSize property [page 250]

Specifies the default maximum number of bytes to use for index hashing in the new database.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 245
 NearestCentury property [page 250]
Specifies the nearest century used for string conversions by the new database.

Obfuscate property [page 251]

Specifies whether the new database should use obfuscation to encrypt the database.

PageSize property [page 251]

Specifies the page size, in bytes or kilobytes, of the new database.

Precision property [page 252]

Specifies the floating­point precision used for string conversions by the new database.

Scale property [page 253]

Specifies the minimum number of digits after the decimal point when an arithmetic result is truncated
to the maximum precision during string conversions by the new database.

TimeFormat property [page 253]

Specifies the time format used for string conversions by the new database.

TimestampFormat property [page 254]

Specifies the timestamp format used for string conversions by the new database.

TimestampIncrement property [page 254]

Specifies the minimum difference between two unique timestamps, in microseconds (1,000,000th of a
second).

UTF8Encoding property [page 255]

Specifies whether the new database should be using the UTF8 character set or the character set
associated with the collation.

Related Information

GetDatabaseProperty(string) method [page 294]

CreateDatabase(string, string) method [page 284]
ToString() method [page 247]

4.1.10.1 ULCreateParms() constructor

Initializes a ULCreateParms object with its default values.

 Syntax

Visual Basic

Public Sub ULCreateParms ()

C#

public ULCreateParms ()

UltraLite - .NET API Reference

246 PUBLIC UltraLite .NET API reference
4.1.10.2 ToString() method

Returns the string representation of this instance.

 Syntax

Visual Basic

Public Overrides Function ToString () As String

C#

public override string ToString ()

Returns

The string representation of this instance as a semicolon-separated list keyword=value pairs.

4.1.10.3 CaseSensitive property

Specifies whether the new database should be case sensitive when comparing string values.

 Syntax

Visual Basic

Public Property CaseSensitive As Boolean

C#

public bool CaseSensitive {get;set;}

Remarks

True if the database should be case sensitive; false if the database should be case insensitive. The default is
false.

This method only affects how string data is compared and sorted. Database identifiers such as table names,
column names, index names, and connection user IDs are always case insensitive. Connection passwords and
database encryption keys are always case sensitive.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 247
4.1.10.4 ChecksumLevel property

Specifies the level of database page checksums enabled for the new database. This topic has been updated
for 17.0 PL 41 Build 5745.

 Syntax

Visual Basic

Public Property ChecksumLevel As Integer

C#

public int ChecksumLevel {get;set;}

Remarks

An integer specifying the checksum level. Valid values are 0, 1, and 2. The default is 2.

4.1.10.5 DateFormat property

Specifies the date format used for string conversions by the new database.

 Syntax

Visual Basic

Public Property DateFormat As String

C#

public string DateFormat {get;set;}

Remarks

A string specifying the date format. If the value is a null reference (Nothing in Visual Basic), the database uses
"YYYY-MM-DD". In C#, you must escape any backslash characters in paths or use @-quoted string literals. The
default is a null reference (Nothing in Visual Basic).

UltraLite - .NET API Reference

248 PUBLIC UltraLite .NET API reference
4.1.10.6 DateOrder property

Specifies the date order used for string conversions by the new database.

 Syntax

Visual Basic

Public Property DateOrder As ULDateOrder

C#

public ULDateOrder DateOrder {get;set;}

Remarks

A ULDateOrder value identifying the date order for string conversions. The default is YMD.

Related Information

ULDateOrder enumeration [page 609]

4.1.10.7 FIPS property

Specifies whether the new database should be using AES_FIPS encryption or AES encryption.

 Syntax

Visual Basic

Public Property FIPS As Boolean

C#

public bool FIPS {get;set;}

Remarks

True if the database should be encrypted using AES_FIPS, false if the database should be encrypted with AES.
The default is false.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 249
Encryption must be turned on by supplying a value for the EncryptionKey connection parameter when the new
database is created. If FIPS is true and no encryption key is supplied, the ULDatabaseManager.CreateDatabase
method fails with a missing encryption key error.

Related Information

EncryptionKey property [page 224]

CreateDatabase(string, string) method [page 284]

4.1.10.8 MaxHashSize property

Specifies the default maximum number of bytes to use for index hashing in the new database.

 Syntax

Visual Basic

Public Property MaxHashSize As Integer

C#

public int MaxHashSize {get;set;}

Remarks

An integer specifying the maximum hash size. The value must be in the range [0,32]. The default is 8.

4.1.10.9 NearestCentury property

Specifies the nearest century used for string conversions by the new database.

 Syntax

Visual Basic

Public Property NearestCentury As Integer

C#

public int NearestCentury {get;set;}

UltraLite - .NET API Reference

250 PUBLIC UltraLite .NET API reference
Remarks

An integer specifying the nearest century. The value must be in the range [0,100]. The default is 50.

4.1.10.10 Obfuscate property

Specifies whether the new database should use obfuscation to encrypt the database.

 Syntax

Visual Basic

Public Property Obfuscate As Boolean

C#

public bool Obfuscate {get;set;}

Remarks

True if the database should be encrypted using obfuscation, false if the database should not be obfuscated.
The default is false.

This option is ignored if FIPS encryption is turned on with the ULCreateParms.FIPS property. The encryption
key is ignored if obfuscation is turned on and a value is supplied for the EncryptionKey connection parameter
when the new database is created.

Related Information

FIPS property [page 249]

4.1.10.11 PageSize property

Specifies the page size, in bytes or kilobytes, of the new database.

 Syntax

Visual Basic

Public Property PageSize As Integer

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 251
 C#

public int PageSize {get;set;}

Remarks

An integer specifying the page size in bytes. Valid values are 1024 (1K), 2048 (2K), 4096 (4K), 8192 (8K), 16384
(16K). The default is 4096.

4.1.10.12 Precision property

Specifies the floating­point precision used for string conversions by the new database.

 Syntax

Visual Basic

Public Property Precision As Integer

C#

public int Precision {get;set;}

Remarks

An integer specifying the precision. The value must be in the range [1,127]. The default is 30.

Related Information

Scale property [page 253]

UltraLite - .NET API Reference

252 PUBLIC UltraLite .NET API reference
4.1.10.13 Scale property

Specifies the minimum number of digits after the decimal point when an arithmetic result is truncated to the
maximum precision during string conversions by the new database.

 Syntax

Visual Basic

Public Property Scale As Integer

C#

public int Scale {get;set;}

Remarks

An integer specifying the scale. The value must be in the range [0,127]. The default is 6.

The Scale value must be less than or equal to the Precision value; otherwise, an error occurs when creating the
database.

4.1.10.14 TimeFormat property

Specifies the time format used for string conversions by the new database.

 Syntax

Visual Basic

Public Property TimeFormat As String

C#

public string TimeFormat {get;set;}

Remarks

A string specifying the time format. If the value is a null reference (Nothing in Visual Basic), the database uses
"HH:NN:SS.SSS". In C#, you must escape any backslash characters in paths or use @-quoted string literals.
The default is a null reference (Nothing in Visual Basic).

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 253
4.1.10.15 TimestampFormat property

Specifies the timestamp format used for string conversions by the new database.

 Syntax

Visual Basic

Public Property TimestampFormat As String

C#

public string TimestampFormat {get;set;}

Remarks

A string specifying the timestamp format. If the value is a null reference (Nothing in Visual Basic), the database
uses "YYYY-MM-DD HH:NN:SS.SSS". In C#, you must escape any backslash characters in paths or use @-
quoted string literals. The default is a null reference (Nothing in Visual Basic).

4.1.10.16 TimestampIncrement property

Specifies the minimum difference between two unique timestamps, in microseconds (1,000,000th of a
second).

 Syntax

Visual Basic

Public Property TimestampIncrement As Integer

C#

public int TimestampIncrement {get;set;}

Remarks

An integer specifying the timestamp increment. The value must be in the range [1,60000000]. The default is 1.

UltraLite - .NET API Reference

254 PUBLIC UltraLite .NET API reference
4.1.10.17 UTF8Encoding property

Specifies whether the new database should be using the UTF8 character set or the character set associated
with the collation.

 Syntax

Visual Basic

Public Property UTF8Encoding As Boolean

C#

public bool UTF8Encoding {get;set;}

Remarks

True if the database should use the UTF8 character set, false if the database should use the character set
associated with the collation. The default is false.

Choose to use the UTF8 character set to store characters that are not in the character set associated with the
collation. For example, you create a database with the 1252LATIN1 collation because you want US sorting but
specify UTF8Encoding true because you want to store international addresses as they are spelled locally.

4.1.11 ULCursorSchema class

UL Ext: Represents the schema of an UltraLite.NET cursor.

 Syntax

Visual Basic

Public MustInherit Class ULCursorSchema

C#

public abstract class ULCursorSchema

Members

All members of ULCursorSchema, including inherited members.

Methods

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 255
Modifier and Type Method Description

protected unsafe void GetColumnCount() [page 258]

public unsafe short GetColumnID(string) [page 258] Returns the column ID of the named
column.

public string GetColumnName(int) [page 259] Returns the name of the column identi­
fied by the specified column ID.

public unsafe int GetColumnPrecision(int) [page 260] Returns the precision of the column
identified by the specified column ID if
the column is a numeric column (the
NUMERIC SQL type).

public unsafe int GetColumnScale(int) [page 261] Returns the scale of the column identi­
fied by the specified column ID if the
column is a numeric column (the NU­
MERIC SQL type).

public unsafe int GetColumnSize(int) [page 262] Returns the size of the column identi­
fied by the specified column ID if the
column is a sized column (the BINARY
or CHAR SQL types).

public string GetColumnSQLName(int) [page 263] Returns the name of the column identi­
fied by the specified column ID.

public unsafe ULDbType GetColumnULDbType(int) [page 264] Returns the UltraLite.NET data type of
the column identified by the specified
column ID.

public unsafe DataTable GetSchemaTable() [page 265] Returns a System.Data.DataTable that

describes the column schema of the
ULDataReader object.

protected virtual void VerifyOpen() [page 265]

Properties

Modifier and Type Property Description

public short ColumnCount [page 266] Returns the number of columns in the
cursor.

public bool IsOpen [page 266] Checks whether the cursor schema is
currently open.

public abstract string Name [page 267] Returns the name of the cursor.

Remarks

This class is an abstract base class of the ULTableSchema class and the ULResultSetSchema class.

 Note

For users porting from the Sap.UltraLite namespace, Column IDs are 0-based, not 1-based as they are in
the Sap.UltraLite namespace.

UltraLite - .NET API Reference

256 PUBLIC UltraLite .NET API reference
In this section:

GetColumnCount() method [page 258]

GetColumnID(string) method [page 258]

Returns the column ID of the named column.

GetColumnName(int) method [page 259]

Returns the name of the column identified by the specified column ID.

GetColumnPrecision(int) method [page 260]

Returns the precision of the column identified by the specified column ID if the column is a numeric
column (the NUMERIC SQL type).

GetColumnScale(int) method [page 261]

Returns the scale of the column identified by the specified column ID if the column is a numeric column
(the NUMERIC SQL type).

GetColumnSize(int) method [page 262]

Returns the size of the column identified by the specified column ID if the column is a sized column (the
BINARY or CHAR SQL types).

GetColumnSQLName(int) method [page 263]

Returns the name of the column identified by the specified column ID.

GetColumnULDbType(int) method [page 264]

Returns the UltraLite.NET data type of the column identified by the specified column ID.

GetSchemaTable() method [page 265]

Returns a System.Data.DataTable that describes the column schema of the ULDataReader object.

VerifyOpen() method [page 265]

ColumnCount property [page 266]

Returns the number of columns in the cursor.

IsOpen property [page 266]

Checks whether the cursor schema is currently open.

Name property [page 267]

Returns the name of the cursor.

Related Information

ULTableSchema class [page 578]

ULResultSetSchema class [page 494]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 257
4.1.11.1 GetColumnCount() method

 Syntax

Visual Basic

Protected Sub GetColumnCount ()

C#

protected unsafe void GetColumnCount ()

4.1.11.2 GetColumnID(string) method

Returns the column ID of the named column.

 Syntax

Visual Basic

Public Function GetColumnID (ByVal name As String) As Short

C#

public unsafe short GetColumnID (string name)

Parameters

name The name of the column.

Returns

The column ID of the named column.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

258 PUBLIC UltraLite .NET API reference
Remarks

Column IDs range from 0 to ColumnCount-1, inclusive.

In result sets, not all columns have names and not all column names are unique. If you are not using aliases, the
name of a non-computed column is prefixed with the name of the table the column is from. For example,
MyTable.ID is the name of the only column in the result set for the query "SELECT ID FROM MyTable".

Column IDs and counts might change during a schema upgrade. To correctly identify a column, access it by
name or refresh the cached IDs and counts after a schema upgrade.

Related Information

ColumnCount property [page 266]

ColumnCount property [page 266]

4.1.11.3 GetColumnName(int) method

Returns the name of the column identified by the specified column ID.

 Syntax

Visual Basic

Public Function GetColumnName (ByVal columnID As Integer) As String

C#

public string GetColumnName (int columnID)

Parameters

columnID The ID of the column. The value must be in the range [0,ColumnCount-1].

Returns

The name of the column or a null reference (Nothing in Visual Basic) if the column has no name. If the column
is aliased in the SQL query, the alias is returned.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 259
Exceptions

ULException class A SQL error occurred.

Remarks

In result sets, not all columns have names and not all column names are unique. If you are not using aliases, the
name of a non-computed column is prefixed with the name of the table the column is from. For example,
MyTable.ID is the name of the only column in the result set for the query "SELECT ID FROM MyTable".

Column IDs and count may change during a schema upgrade. To correctly identify a column, access it by name
or refresh the cached IDs and counts after a schema upgrade.

Related Information

ColumnCount property [page 266]

ColumnCount property [page 266]

4.1.11.4 GetColumnPrecision(int) method

Returns the precision of the column identified by the specified column ID if the column is a numeric column
(the NUMERIC SQL type).

 Syntax

Visual Basic

Public Function GetColumnPrecision (ByVal columnID As Integer) As Integer

C#

public unsafe int GetColumnPrecision (int columnID)

Parameters

columnID The ID of the column. The value must be in the range [0,ColumnCount-1].

UltraLite - .NET API Reference

260 PUBLIC UltraLite .NET API reference
Returns

The precision of the specified numeric column.

Exceptions

ULException class A SQL error occurred.

Related Information

GetColumnULDbType(int) method [page 264]

ColumnCount property [page 266]

4.1.11.5 GetColumnScale(int) method

Returns the scale of the column identified by the specified column ID if the column is a numeric column (the
NUMERIC SQL type).

 Syntax

Visual Basic

Public Function GetColumnScale (ByVal columnID As Integer) As Integer

C#

public unsafe int GetColumnScale (int columnID)

Parameters

columnID The ID of the column. The value must be in the range [0,ColumnCount-1].

Returns

The scale of the specified numeric column.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 261
Exceptions

ULException class A SQL error occurred.

Related Information

GetColumnULDbType(int) method [page 264]

ColumnCount property [page 266]

4.1.11.6 GetColumnSize(int) method

Returns the size of the column identified by the specified column ID if the column is a sized column (the
BINARY or CHAR SQL types).

 Syntax

Visual Basic

Public Function GetColumnSize (ByVal columnID As Integer) As Integer

C#

public unsafe int GetColumnSize (int columnID)

Parameters

columnID The ID of the column. The value must be in the range [0,ColumnCount-1].

Returns

The size of the specified sized column.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

262 PUBLIC UltraLite .NET API reference
Related Information

GetColumnULDbType(int) method [page 264]

ColumnCount property [page 266]

4.1.11.7 GetColumnSQLName(int) method

Returns the name of the column identified by the specified column ID.

 Syntax

Visual Basic

Public Function GetColumnSQLName (ByVal columnID As Integer) As String

C#

public string GetColumnSQLName (int columnID)

Parameters

columnID The ID of the column. The value must be in the range [0,ColumnCount-1].

Returns

The name of the column or a null reference (Nothing in Visual Basic) if the column has no name. If the column
is aliased in the SQL query, the alias is returned.

Exceptions

ULException class A SQL error occurred.

Remarks

In result sets, not all columns have names and not all column names are unique. If you are using aliases, the
name of the column is the alias.

The GetColumnSQLName method differs from the GetColumnName method because the
GetColumnSQLName method always returns just the name of the column (without the table name as a prefix)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 263
for non-aliased, non-computed columns. While this behavior more closely resembles the behavior of other
ADO.NET providers, it is more likely to produce non-unique names.

Column IDs and count may change during a schema upgrade. To correctly identify a column, access it by name
or refresh the cached IDs and counts after a schema upgrade.

Related Information

ColumnCount property [page 266]

GetColumnName(int) method [page 259]
ColumnCount property [page 266]

4.1.11.8 GetColumnULDbType(int) method

Returns the UltraLite.NET data type of the column identified by the specified column ID.

 Syntax

Visual Basic

Public Function GetColumnULDbType (ByVal columnID As Integer) As ULDbType

C#

public unsafe ULDbType GetColumnULDbType (int columnID)

Parameters

columnID The ID of the column. The value must be in the range [0,ColumnCount-1].

Returns

A ULDbType enumerated integer.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

264 PUBLIC UltraLite .NET API reference
Related Information

ColumnCount property [page 266]

ColumnCount property [page 266]
ULDbType enumeration [page 609]

4.1.11.9 GetSchemaTable() method

Returns a System.Data.DataTable that describes the column schema of the ULDataReader object.

 Syntax

Visual Basic

Public Function GetSchemaTable () As DataTable

C#

public unsafe DataTable GetSchemaTable ()

Returns

A System.Data.DataTable that describes the column schema.

Related Information

GetSchemaTable() method [page 330]

ULDataReader class [page 302]

4.1.11.10 VerifyOpen() method

 Syntax

Visual Basic

Protected Overridable Sub VerifyOpen ()

C#

protected virtual void VerifyOpen ()

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 265
4.1.11.11 ColumnCount property

Returns the number of columns in the cursor.

 Syntax

Visual Basic

Public ReadOnly Property ColumnCount As Short

C#

public short ColumnCount {get;}

Remarks

The number of columns in the cursor or 0 if the cursor schema is closed.

Column IDs range from 0 to ColumnCount-1, inclusive.

Column IDs and count might change during a schema upgrade. To correctly identify a column, access it by
name or refresh the cached IDs and counts after a schema upgrade.

4.1.11.12 IsOpen property

Checks whether the cursor schema is currently open.

 Syntax

Visual Basic

Public ReadOnly Property IsOpen As Boolean

C#

public bool IsOpen {get;}

Remarks

True if the cursor schema is currently open; false if the cursor schema is closed.

UltraLite - .NET API Reference

266 PUBLIC UltraLite .NET API reference
4.1.11.13 Name property

Returns the name of the cursor.

 Syntax

Visual Basic

Public ReadOnly Property Name As String

C#

public abstract string Name {get;}

Remarks

The name of the cursor as a string.

4.1.12 ULDataAdapter class

Represents a set of commands and a database connection used to fill a System.Data.DataSet and to update a
database.

 Syntax

Visual Basic

Public NotInheritable Class ULDataAdapter Inherits

System.Data.Common.DbDataAdapter Implements System.ICloneable

C#

public sealed class ULDataAdapter : System.Data.Common.DbDataAdapter,

System.ICloneable

Members

All members of ULDataAdapter, including inherited members.

Constructors

Modifier and Type Constructor Description

public ULDataAdapter [page 270] Initializes a ULDataAdapter object.

Methods

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 267
Modifier and Type Method Description

protected override void Dispose(bool) [page 273] Releases the unmanaged resources
used by the ULDataAdapter object and
optionally releases the managed re­
sources.

protected override int Fill [page 274] See individual topics

protected override DataTable[] FillSchema [page 275] See individual topics

public new ULParameter[] GetFillParameters() [page 277] Returns the parameters set by the user
when executing a SELECT statement.

protected override int Update(DataRow[], DataTableMapping)

[page 277]

Properties

Modifier and Type Property Description

public new ULCommand DeleteCommand [page 278] Specifies a ULCommand object that is
executed against the database when
the DbDataAdapter.Update method is
called to delete rows in the database
that correspond to deleted rows in the
System.Data.DataSet.

public new ULCommand InsertCommand [page 278] Specifies a ULCommand object that is
executed against the database when
the DbDataAdapter.Update method is
called to insert rows in the database
that correspond to inserted rows in the
System.Data.DataSet.

public new ULCommand SelectCommand [page 279] Specifies a ULCommand that is used
during the System.Data.Com­
mon.DbDataAdapter.Fill(Sys­
tem.Data.DataSet) or Sys­
tem.Data.Common.DbDataAdapter.Fill­
Schema(System.Data.DataSet,Sys­
tem.Data.SchemaType) method calls to
obtain a result set from the database
for copying into a System.Data.Data­
Set.

public new DataTableMappingCollec­ TableMappings [page 280] Returns a collection that provides the
tion master mapping between a source ta­
ble and a System.Data.DataTable

public new ULCommand UpdateCommand [page 281] Specifies a ULCommand object that is
executed against the database when
the System.Data.Common.DbDataA­
dapter.Update method is called to up­
date rows in the database that corre­
spond to updated rows in the Sys­
tem.Data.DataSet.

Events

UltraLite - .NET API Reference

268 PUBLIC UltraLite .NET API reference
 Modifier and Type Event Description

public ULRowUpdatedEventHandler RowUpdated [page 281] Occurs during an update after a com­
mand is executed against the data
source.

public ULRowUpdatingEventHandler RowUpdating [page 282] Occurs during an update before a com­
mand is executed against the data
source.

Remarks

The System.Data.DataSet provides a way to work with data offline; that is, away from your UltraLite database.
The ULDataAdapter class provides methods to associate a System.Data.DataSet with a set of SQL statements.

Since UltraLite is a local database and MobiLink has conflict resolution, the use of the ULDataAdapter is
limited. For most purposes, the ULDataReader or ULTable classes provide more efficient access to data.

In this section:

ULDataAdapter constructor [page 270]

Initializes a ULDataAdapter object.

Dispose(bool) method [page 273]

Releases the unmanaged resources used by the ULDataAdapter object and optionally releases the
managed resources.

Fill method [page 274]

FillSchema method [page 275]

GetFillParameters() method [page 277]

Returns the parameters set by the user when executing a SELECT statement.

Update(DataRow[], DataTableMapping) method [page 277]

DeleteCommand property [page 278]

Specifies a ULCommand object that is executed against the database when the DbDataAdapter.Update
method is called to delete rows in the database that correspond to deleted rows in the
System.Data.DataSet.

InsertCommand property [page 278]

Specifies a ULCommand object that is executed against the database when the DbDataAdapter.Update
method is called to insert rows in the database that correspond to inserted rows in the
System.Data.DataSet.

SelectCommand property [page 279]

Specifies a ULCommand that is used during the
System.Data.Common.DbDataAdapter.Fill(System.Data.DataSet) or
System.Data.Common.DbDataAdapter.FillSchema(System.Data.DataSet,System.Data.SchemaType)
method calls to obtain a result set from the database for copying into a System.Data.DataSet.

TableMappings property [page 280]

Returns a collection that provides the master mapping between a source table and a
System.Data.DataTable

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 269
 UpdateCommand property [page 281]
Specifies a ULCommand object that is executed against the database when the
System.Data.Common.DbDataAdapter.Update method is called to update rows in the database that
correspond to updated rows in the System.Data.DataSet.

RowUpdated event [page 281]

Occurs during an update after a command is executed against the data source.

RowUpdating event [page 282]

Occurs during an update before a command is executed against the data source.

Related Information

ULDataReader class [page 302]

ULTable class [page 548]

4.1.12.1 ULDataAdapter constructor

Initializes a ULDataAdapter object.

Overload list

Modifier and Type Overload name Description

public ULDataAdapter() [page 271] Initializes a ULDataAdapter object.

public ULDataAdapter(ULCommand) [page Initializes a ULDataAdapter object with

271] the specified SELECT statement.

public ULDataAdapter(string, ULConnection) Initializes a ULDataAdapter object with

[page 272] the specified SELECT statement and
connection.

public ULDataAdapter(string, string) [page Initializes a ULDataAdapter object with

273] the specified SELECT statement and
connection string.

In this section:

ULDataAdapter() constructor [page 271]

Initializes a ULDataAdapter object.

ULDataAdapter(ULCommand) constructor [page 271]

Initializes a ULDataAdapter object with the specified SELECT statement.

ULDataAdapter(string, ULConnection) constructor [page 272]

Initializes a ULDataAdapter object with the specified SELECT statement and connection.

UltraLite - .NET API Reference

270 PUBLIC UltraLite .NET API reference
 ULDataAdapter(string, string) constructor [page 273]
Initializes a ULDataAdapter object with the specified SELECT statement and connection string.

4.1.12.1.1 ULDataAdapter() constructor

Initializes a ULDataAdapter object.

 Syntax

Visual Basic

Public Sub ULDataAdapter ()

C#

public ULDataAdapter ()

Related Information

ULDataAdapter(ULCommand) constructor [page 271]

ULDataAdapter(string, ULConnection) constructor [page 272]
ULDataAdapter(string, string) constructor [page 273]

4.1.12.1.2 ULDataAdapter(ULCommand) constructor

Initializes a ULDataAdapter object with the specified SELECT statement.

 Syntax

Visual Basic

Public Sub ULDataAdapter (ByVal selectCommand As ULCommand)

C#

public ULDataAdapter (ULCommand selectCommand)

Parameters

selectCommand A ULCommand object that is used during

System.Data.Common.DbDataAdapter.Fill(System.Data.DataSet) to select records from the data source
for placement in the System.Data.DataSet.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 271
Related Information

ULDataAdapter() constructor [page 271]

ULDataAdapter(string, ULConnection) constructor [page 272]
ULDataAdapter(string, string) constructor [page 273]
ULCommand class [page 88]

4.1.12.1.3 ULDataAdapter(string, ULConnection) constructor

Initializes a ULDataAdapter object with the specified SELECT statement and connection.

 Syntax

Visual Basic

Public Sub ULDataAdapter (

ByVal selectCommandText As String,
ByVal selectConnection As ULConnection
)

C#

public ULDataAdapter (
string selectCommandText,
ULConnection selectConnection
)

Parameters

selectCommandText A SELECT statement to be used by the ULDataAdapter.SelectCommand method of

the ULDataAdapter object.
selectConnection A ULConnection object that defines a connection to a database.

Related Information

ULDataAdapter() constructor [page 271]

ULDataAdapter(ULCommand) constructor [page 271]
ULDataAdapter(string, string) constructor [page 273]
SelectCommand property [page 279]
ULConnection class [page 151]

UltraLite - .NET API Reference

272 PUBLIC UltraLite .NET API reference
4.1.12.1.4 ULDataAdapter(string, string) constructor
Initializes a ULDataAdapter object with the specified SELECT statement and connection string.

 Syntax

Visual Basic

Public Sub ULDataAdapter (

ByVal selectCommandText As String,
ByVal selectConnectionString As String
)

C#

public ULDataAdapter (
string selectCommandText,
string selectConnectionString
)

Parameters

selectCommandText A SELECT statement to be used by the ULDataAdapter.SelectCommand method.

selectConnectionString A connection string for an UltraLite.NET database.

Related Information

ULDataAdapter() constructor [page 271]

ULDataAdapter(ULCommand) constructor [page 271]
ULDataAdapter(string, ULConnection) constructor [page 272]
SelectCommand property [page 279]

4.1.12.2 Dispose(bool) method

Releases the unmanaged resources used by the ULDataAdapter object and optionally releases the managed
resources.

 Syntax

Visual Basic

Protected Overrides Sub Dispose (ByVal disposing As Boolean)

C#

protected override void Dispose (bool disposing)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 273
Parameters

disposing When true, disposes of both managed and unmanaged resources. When false, disposes of only
the unmanaged resources.

4.1.12.3 Fill method

Overload list

Modifier and Type Overload name Description

protected override int Fill(DataSet, int, int, string, IDbCom­

mand, CommandBehavior) [page 274]

protected override int Fill(DataTable[], int, int, IDbCommand,

CommandBehavior) [page 275]

In this section:

Fill(DataSet, int, int, string, IDbCommand, CommandBehavior) method [page 274]

Fill(DataTable[], int, int, IDbCommand, CommandBehavior) method [page 275]

4.1.12.3.1 Fill(DataSet, int, int, string, IDbCommand,

CommandBehavior) method

 Syntax

Visual Basic

Protected Overrides Function Fill (

ByVal dataSet As DataSet,
ByVal startRecord As Integer,
ByVal maxRecords As Integer,
ByVal srcTable As String,
ByVal cmd As IDbCommand,
ByVal behavior As CommandBehavior
) As Integer

C#

protected override int Fill (

DataSet dataSet,
int startRecord,
int maxRecords,
string srcTable,

UltraLite - .NET API Reference

274 PUBLIC UltraLite .NET API reference
 IDbCommand cmd,
CommandBehavior behavior
)

4.1.12.3.2 Fill(DataTable[], int, int, IDbCommand,

CommandBehavior) method

 Syntax

Visual Basic

Protected Overrides Function Fill (

ByVal dataTables As DataTable(),
ByVal startRecord As Integer,
ByVal maxRecords As Integer,
ByVal cmd As IDbCommand,
ByVal behavior As CommandBehavior
) As Integer

C#

protected override int Fill (

DataTable[] dataTables,
int startRecord,
int maxRecords,
IDbCommand cmd,
CommandBehavior behavior
)

4.1.12.4 FillSchema method

Overload list

Modifier and Type Overload name Description

protected override DataTable[] FillSchema(DataSet, SchemaType, IDb­

Command, string, CommandBehavior)
[page 276]

protected override DataTable FillSchema(DataTable, SchemaType,

IDbCommand, CommandBehavior)
[page 276]

In this section:

FillSchema(DataSet, SchemaType, IDbCommand, string, CommandBehavior) method [page 276]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 275
 FillSchema(DataTable, SchemaType, IDbCommand, CommandBehavior) method [page 276]

4.1.12.4.1 FillSchema(DataSet, SchemaType, IDbCommand,

string, CommandBehavior) method

 Syntax

Visual Basic

Protected Overrides Function FillSchema (

ByVal dataSet As DataSet,
ByVal schemaType As SchemaType,
ByVal cmd As IDbCommand,
ByVal srcTable As String,
ByVal behavior As CommandBehavior
) As DataTable()

C#

protected override DataTable[] FillSchema (

DataSet dataSet,
SchemaType schemaType,
IDbCommand cmd,
string srcTable,
CommandBehavior behavior
)

4.1.12.4.2 FillSchema(DataTable, SchemaType, IDbCommand,

CommandBehavior) method

 Syntax

Visual Basic

Protected Overrides Function FillSchema (

ByVal dataTable As DataTable,
ByVal schemaType As SchemaType,
ByVal cmd As IDbCommand,
ByVal behavior As CommandBehavior
) As DataTable

C#

protected override DataTable FillSchema (

DataTable dataTable,
SchemaType schemaType,
IDbCommand cmd,
CommandBehavior behavior
)

UltraLite - .NET API Reference

276 PUBLIC UltraLite .NET API reference
4.1.12.5 GetFillParameters() method

Returns the parameters set by the user when executing a SELECT statement.

 Syntax

Visual Basic

Public Shadows Function GetFillParameters () As ULParameter()

C#

public new ULParameter[] GetFillParameters ()

Returns

An array of ULParameter objects that contains the parameters set by the user.

Remarks

This is the strongly-typed version of the System.Data.Common.DbDataAdapter.GetFillParameters method.

Related Information

ULParameter class [page 413]

4.1.12.6 Update(DataRow[], DataTableMapping) method

 Syntax

Visual Basic

Protected Overrides Function Update (

ByVal dataRows As DataRow(),
ByVal tm As DataTableMapping
) As Integer

C#

protected override int Update (

DataRow[] dataRows,
DataTableMapping tm

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 277
 )

4.1.12.7 DeleteCommand property

Specifies a ULCommand object that is executed against the database when the DbDataAdapter.Update
method is called to delete rows in the database that correspond to deleted rows in the System.Data.DataSet.

 Syntax

Visual Basic

Public Shadows Property DeleteCommand As ULCommand

C#

public new ULCommand DeleteCommand {get;set;}

Remarks

A ULCommand object that is executed to delete rows in the database that correspond to deleted rows in the
System.Data.DataSet.

When the DeleteCommand property is assigned to an existing ULCommand object, the ULCommand object is
not cloned. The DeleteCommand property maintains a reference to the existing ULCommand object.

This is the strongly-typed version of the System.Data.IDbDataAdapter.DeleteCommand and

System.Data.Common.DbDataAdapter.DeleteCommand properties.

Related Information

ULCommand class [page 88]

4.1.12.8 InsertCommand property

Specifies a ULCommand object that is executed against the database when the DbDataAdapter.Update
method is called to insert rows in the database that correspond to inserted rows in the System.Data.DataSet.

 Syntax

Visual Basic

Public Shadows Property InsertCommand As ULCommand

UltraLite - .NET API Reference

278 PUBLIC UltraLite .NET API reference
 C#

public new ULCommand InsertCommand {get;set;}

Remarks

A ULCommand object that is executed to insert rows in the database that correspond to inserted rows in the
System.Data.DataSet.

When the InsertCommand property is assigned to an existing ULCommand object, the ULCommand object is
not cloned. The InsertCommand property maintains a reference to the existing ULCommand object.

This is the strongly-typed version of System.Data.IDbDataAdapter.InsertCommand and

System.Data.Common.DbDataAdapter.InsertCommand properties.

Related Information

ULCommand class [page 88]

4.1.12.9 SelectCommand property

Specifies a ULCommand that is used during the

System.Data.Common.DbDataAdapter.Fill(System.Data.DataSet) or
System.Data.Common.DbDataAdapter.FillSchema(System.Data.DataSet,System.Data.SchemaType) method
calls to obtain a result set from the database for copying into a System.Data.DataSet.

 Syntax

Visual Basic

Public Shadows Property SelectCommand As ULCommand

C#

public new ULCommand SelectCommand {get;set;}

Remarks

A ULCommand object that is executed to fill the System.Data.DataSet.

When SelectCommand property is assigned to an existing ULCommand object, the ULCommand object is not
cloned. The SelectCommand property maintains a reference to the existing ULCommand object.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 279
If the SelectCommand property does not return any rows, then no tables are added to the
System.Data.DataSet, and no exception is raised. The SELECT statement can also be specified in the
ULDataAdapter(ULCommand), ULDataAdapter(String,ULConnection), or ULDataAdapter(String,String)
constructors.

This is the strongly-typed version of the System.Data.IDbDataAdapter.SelectCommand and

System.Data.Common.DbDataAdapter.SelectCommand properties.

Related Information

ULCommand class [page 88]

ULDataAdapter(ULCommand) constructor [page 271]
ULDataAdapter class [page 267]
ULDataAdapter class [page 267]

4.1.12.10 TableMappings property

Returns a collection that provides the master mapping between a source table and a System.Data.DataTable

 Syntax

Visual Basic

Public ReadOnly Shadows Property TableMappings As

DataTableMappingCollection

C#

public new DataTableMappingCollection TableMappings {get;}

Remarks

A collection of System.Data.Common.DataTableMapping objects providing the master mapping between

source tables and System.Data.DataTables. The default value is an empty collection.

When reconciling changes, the ULDataAdapter object uses the

System.Data.Common.DataTableMappingCollection collection to associate the column names used by the
data source with the column names used by the System.Data.DataSet object.

This is the strongly-typed version of the System.Data.IDataAdapter.TableMappings property.

UltraLite - .NET API Reference

280 PUBLIC UltraLite .NET API reference
4.1.12.11 UpdateCommand property

Specifies a ULCommand object that is executed against the database when the
System.Data.Common.DbDataAdapter.Update method is called to update rows in the database that
correspond to updated rows in the System.Data.DataSet.

 Syntax

Visual Basic

Public Shadows Property UpdateCommand As ULCommand

C#

public new ULCommand UpdateCommand {get;set;}

Remarks

A ULCommand object that is executed to update rows in the database that correspond to updated rows in the
System.Data.DataSet.

When UpdateCommand is assigned to an existing ULCommand object, the ULCommand object is not cloned.
The UpdateCommand property maintains a reference to the existing ULCommand object.

If execution of this command returns rows, these rows may be merged with the System.Data.DataSet
depending on how you set the ULCommand.UpdatedRowSource property of the ULCommand object.

This is the strongly-typed version of the System.Data.IDbDataAdapter.UpdateCommand and

System.Data.Common.DbDataAdapter.DeleteCommand properties.

Related Information

ULCommand class [page 88]

UpdatedRowSource property [page 134]

4.1.12.12 RowUpdated event

Occurs during an update after a command is executed against the data source.

 Syntax

Visual Basic

Public Event RowUpdated As ULRowUpdatedEventHandler

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 281
 C#

public ULRowUpdatedEventHandler RowUpdated;

Remarks

When an attempt to update is made, the event fires.

To process row updated events, you must create a ULRowUpdatedEventHandler delegate and attach it to this
event.

Related Information

ULRowUpdatedEventHandler(object, ULRowUpdatedEventArgs) delegate [page 604]

4.1.12.13 RowUpdating event

Occurs during an update before a command is executed against the data source.

 Syntax

Visual Basic

Public Event RowUpdating As ULRowUpdatingEventHandler

C#

public ULRowUpdatingEventHandler RowUpdating;

Remarks

When an attempt to update is made, the event fires.

To process row updating events, you must create a ULRowUpdatingEventHandler delegate and attach it to this
event.

Related Information

ULRowUpdatedEventHandler(object, ULRowUpdatedEventArgs) delegate [page 604]

UltraLite - .NET API Reference

282 PUBLIC UltraLite .NET API reference
4.1.13 ULDatabaseManager class
UL Ext: Provides static methods for creating, deleting, and validating databases.

 Syntax

Visual Basic

Public NotInheritable Class ULDatabaseManager

C#

public sealed class ULDatabaseManager

Members

All members of ULDatabaseManager, including inherited members.

Methods

Modifier and Type Method Description

public static void CreateDatabase(string, string) [page Creates a new UltraLite database.
284]

public static void DropDatabase(string) [page 286] Deletes the specified database.

public static void SetActiveSyncListener(string, ULActi­ Specifies the listener object used to
veSyncListener) [page 287] process ActiveSync calls from the Mo­
biLink provider for ActiveSync.

public static void SetServerSyncListener(string, string, Specifies the listener object used to
ULServerSyncListener) [page 288] process the specified server synchroni­
zation message.

public static void SignalSyncIsComplete() [page 290] Signals the MobiLink provider for Ac­
tiveSync that an application has com­
pleted synchronization.

public static void ValidateDatabase(string, ULDBValid) Performs low level and index validation
[page 290] on a database.

Properties

Modifier and Type Property Description

public ULRuntimeType RuntimeType [page 291] Specifies the UltraLite.NET runtime

type.

Remarks

To use the UltraLite Engine runtime of UltraLite.NET, set the ULDatabaseManager.RuntimeType property to the
appropriate value before using any other UltraLite.NET API.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 283
  Example

The following example selects the UltraLite Engine runtime and creates a connection:

' Visual Basic

ULDatabaseManager.RuntimeType = ULRuntimeType.UL_ENGINE_CLIENT
Dim conn As ULConnection = new ULConnection
' The RuntimeType is now locked

The following code is the C# language equivalent:

// C#
ULDatabaseManager.RuntimeType = ULRuntimeType.UL_ENGINE_CLIENT;
ULConnection conn = new ULConnection();
// The RuntimeType is now locked

In this section:

CreateDatabase(string, string) method [page 284]

Creates a new UltraLite database.

DropDatabase(string) method [page 286]

Deletes the specified database.

SetActiveSyncListener(string, ULActiveSyncListener) method [page 287]

Specifies the listener object used to process Microsoft ActiveSync calls from the MobiLink provider for
Microsoft ActiveSync.

SetServerSyncListener(string, string, ULServerSyncListener) method [page 288]

Specifies the listener object used to process the specified server synchronization message.

SignalSyncIsComplete() method [page 290]

Signals the MobiLink provider for ActiveSync that an application has completed synchronization.

ValidateDatabase(string, ULDBValid) method [page 290]

Performs low level and index validation on a database.

RuntimeType property [page 291]

Specifies the UltraLite.NET runtime type.

4.1.13.1 CreateDatabase(string, string) method

Creates a new UltraLite database.

 Syntax

Visual Basic

Public Shared Sub CreateDatabase (

ByVal connString As String,
ByVal createParms As String
)

C#

public static void CreateDatabase (

UltraLite - .NET API Reference

284 PUBLIC UltraLite .NET API reference
 string connString,
string createParms
)

Parameters

connString The parameters for identifying a database in the form of a semicolon-separated list of
keyword=value pairs.
createParms The parameters used to configure the new database in the form of a semicolon-separated list
of keyword=value pairs.

Exceptions

ULException class A SQL error occurred.

 Example

The following code creates the database \UltraLite\MyDatabase.udb on a Windows Mobile device then
opens a connection to it.

' Visual Basic

Dim openParms As ULConnectionParms = New ULConnectionParms
openParms.DatabaseOnDevice = ".udb"
ULDatabaseManager.CreateDatabase( _
openParms.ToString(), _
"" _
)
Dim conn As ULConnection = _
New ULConnection( openParms.ToString() )
conn.Open()

The following code is the C# language equivalent:

// C#
ULConnectionParms openParms = new ULConnectionParms();
openParms.DatabaseOnDevice = ".udb";
ULDatabaseManager.CreateDatabase(
openParms.ToString(),
""
);
ULConnection conn = new ULConnection( openParms.ToString() );
conn.Open();

Related Information

Open() method [page 192]

ULConnectionParms class [page 216]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 285
ULCreateParms class [page 243]

4.1.13.2 DropDatabase(string) method

Deletes the specified database.

 Syntax

Visual Basic

Public Shared Sub DropDatabase (ByVal connString As String)

C#

public static void DropDatabase (string connString)

Parameters

connString The parameters for identifying a database in the form of a semicolon-separated list of
keyword=value pairs.

Exceptions

ULException class A SQL error occurred.

Remarks

You cannot drop a database that has open connections.

 Example

The following code creates the database \UltraLite\MyDatabase.udb on a Windows Mobile device then
opens a connection to it:

' Visual Basic

Dim connParms As ULConnectionParms = New ULConnectionParms
connParms.DatabaseOnDevice = ".udb"
ULConnection.DatabaseManager.DropDatabase( _
connParms.ToString() _
)

The following code is the C# language equivalent:

// C#

UltraLite - .NET API Reference

286 PUBLIC UltraLite .NET API reference
 ULConnectionParms connParms = new ULConnectionParms();
connParms.DatabaseOnDevice = ".udb";
ULConnection.DatabaseManager.DropDatabase(
connParms.ToString()
);
ULConnection conn = new ULConnection( openParms.ToString() );
conn.Open();

Related Information

Open() method [page 192]

ULConnectionParms class [page 216]

4.1.13.3 SetActiveSyncListener(string,
ULActiveSyncListener) method

Specifies the listener object used to process Microsoft ActiveSync calls from the MobiLink provider for
Microsoft ActiveSync.

 Syntax

Microsoft Visual Basic

Public Shared Sub SetActiveSyncListener (

ByVal appClassName As String,
ByVal listener As ULActiveSyncListener
)

C#

public static void SetActiveSyncListener (

string appClassName,
ULActiveSyncListener listener
)

Parameters

appClassName The unique class name for the application. This is the class name used when the
application is registered for use with Microsoft ActiveSync.
listener The ULActiveSyncListener object. Use null (Nothing in Microsoft Visual Basic) to remove the
previous listener.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 287
Exceptions

ULException class A SQL error occurred.

Remarks

The appClassName parameter is the unique identifier used to identify the application. The application can only
use one appClassName value at a time. While a listener is registered with a particular appClassName value,
calls to the SetServerSyncListener or SetActiveSyncListener methods with a different appClassName value
fail.

To remove the Microsoft ActiveSync listener, call the SetActiveSyncListener method with a null reference
(Nothing in Microsoft Visual Basic) as the listener parameter.

To remove all listeners, call the SetServerSyncListener method with a null reference (Nothing in Microsoft
Visual Basic) for all parameters.

Applications should remove all listeners prior to exiting.

Related Information

SetServerSyncListener(string, string, ULServerSyncListener) method [page 288]

ULActiveSyncListener interface [page 51]
ActiveSyncInvoked(bool) method [page 51]

4.1.13.4 SetServerSyncListener(string, string,

ULServerSyncListener) method

Specifies the listener object used to process the specified server synchronization message.

 Syntax

Visual Basic

Public Shared Sub SetServerSyncListener (

ByVal messageName As String,
ByVal appClassName As String,
ByVal listener As ULServerSyncListener
)

C#

public static void SetServerSyncListener (

string messageName,
string appClassName,
ULServerSyncListener listener

UltraLite - .NET API Reference

288 PUBLIC UltraLite .NET API reference
 )

Parameters

messageName The name of the message.

appClassName The unique class name for the application. This is a unique identifier used to identify the
application.
listener The ULServerSyncListener object. Use null (Nothing in Visual Basic) to remove the previous
listener.

Exceptions

ULException class A SQL error occurred.

Remarks

The appClassName parameter is the unique identifier used to identify the application. The application may only
use one appClassName value at a time. While a listener is registered with a particular appClassName value,
calls to the SetServerSyncListener or SetActiveSyncListener methods with a different appClassName value
fail.

To remove the listener for a particular message, call the SetServerSyncListener method with a null reference
(Nothing in Visual Basic) as the listener parameter.

To remove all listeners, call the SetServerSyncListener method with a null reference (Nothing in Visual Basic)
for all parameters.

Applications should remove all listeners before exiting.

Related Information

SetActiveSyncListener(string, ULActiveSyncListener) method [page 287]

ServerSyncInvoked(string) method [page 505]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 289
4.1.13.5 SignalSyncIsComplete() method

Signals the MobiLink provider for ActiveSync that an application has completed synchronization.

 Syntax

Visual Basic

Public Shared Sub SignalSyncIsComplete ()

C#

public static void SignalSyncIsComplete ()

Related Information

ActiveSyncInvoked(bool) method [page 51]

4.1.13.6 ValidateDatabase(string, ULDBValid) method

Performs low level and index validation on a database.

 Syntax

Visual Basic

Public Shared Sub ValidateDatabase (

ByVal start_parms As String,
ByVal how As ULDBValid
)

C#

public static void ValidateDatabase (

string start_parms,
ULDBValid how
)

Parameters

start_parms The parameters for identifying a database in the form of a semicolon-separated list of
keyword=value pairs.
how Describes how to validate the database.

UltraLite - .NET API Reference

290 PUBLIC UltraLite .NET API reference
Exceptions

ULException class A SQL error occurred.

 Example

The following code validates indexes for the database \UltraLite\MyDatabase.udb under Windows Mobile:

' Visual Basic

Dim openParms As ULConnectionParms = New ULConnectionParms
openParms.DatabaseOnDevice = "\UltraLite\MyDatabase.udb"
ULConnection.DatabaseManager.ValidateDatabase( _
openParms.ToString(), Sap.Data.UltraLite.ULVF_INDEX )

The following code is the C# language equivalent:

// C#
ULConnectionParms openParms = new ULConnectionParms();
openParms.DatabaseOnDevice = ".udb";
ULConnection.DatabaseManager.ValidateDatabase(
openParms.ToString(), Sap.Data.UltraLite.ULVF_INDEX );

Related Information

ValidateDatabase(ULDBValid) method [page 204]

ValidateDatabase(ULDBValid, string) method [page 205]
ULDBValid enumeration [page 612]
ULConnectionParms class [page 216]

4.1.13.7 RuntimeType property

Specifies the UltraLite.NET runtime type.

 Syntax

Visual Basic

Public Shared Property RuntimeType As ULRuntimeType

C#

public ULRuntimeType RuntimeType {get;set;}

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 291
Remarks

The runtime type must be selected before using any other UltraLite.NET API.

A ULRuntimeType value identifying the type of the unmanaged UltraLite.NET runtime.

 Example

The following example selects the UltraLite Engine runtime and creates a connection:

' Visual Basic

ULDatabaseManager.RuntimeType = ULRuntimeType.UL_ENGINE_CLIENT
Dim conn As ULConnection = new ULConnection
' The RuntimeType is now locked

The following code is the C# language equivalent:

// C#
ULDatabaseManager.RuntimeType = ULRuntimeType.UL_ENGINE_CLIENT;
ULConnection conn = new ULConnection();
// The RuntimeType is now locked

Related Information

ULRuntimeType enumeration [page 613]

4.1.14 ULDatabaseSchema class

UL Ext: Represents the schema of an UltraLite.NET database.

 Syntax

Visual Basic

Public NotInheritable Class ULDatabaseSchema

C#

public sealed class ULDatabaseSchema

Members

All members of ULDatabaseSchema, including inherited members.

Methods

UltraLite - .NET API Reference

292 PUBLIC UltraLite .NET API reference
 Modifier and Type Method Description

public string GetDatabaseProperty(string) [page Returns the value of the specified data­
294] base property.

public string GetPublicationName(int) [page 296] Returns the name of the publication
identified by the specified publication
ID.

public string GetTableName(int) [page 297] Returns the name of the table identified
by the specified table ID.

public void SetDatabaseOption(string, string) Sets the value for the specified data­
[page 298] base option.

Properties

Modifier and Type Property Description

public unsafe bool IsCaseSensitive [page 300] Checks whether the database is case
sensitive.

public bool IsOpen [page 300] Determines whether the database

schema is open.

public unsafe int PublicationCount [page 301] Counts the number of publications in
the database.

public unsafe int TableCount [page 302] Counts the number of tables in the da­
tabase.

Remarks

There is no constructor for this class. A ULDatabaseSchema object is attached to a connection as its
ULConnection.Schema object and is only valid while that connection is open.

In this section:

GetDatabaseProperty(string) method [page 294]

Returns the value of the specified database property.

GetPublicationName(int) method [page 296]

Returns the name of the publication identified by the specified publication ID.

GetTableName(int) method [page 297]

Returns the name of the table identified by the specified table ID.

SetDatabaseOption(string, string) method [page 298]

Sets the value for the specified database option.

IsCaseSensitive property [page 300]

Checks whether the database is case sensitive.

IsOpen property [page 300]

Determines whether the database schema is open.

PublicationCount property [page 301]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 293
 Counts the number of publications in the database.

TableCount property [page 302]

Counts the number of tables in the database.

Related Information

Schema property [page 210]

4.1.14.1 GetDatabaseProperty(string) method

Returns the value of the specified database property.

 Syntax

Visual Basic

Public Function GetDatabaseProperty (ByVal name As String) As String

C#

public string GetDatabaseProperty (string name)

Parameters

name The name of the database property whose value you want to obtain. Property names are case
insensitive.

Returns

The value of the property as a string.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

294 PUBLIC UltraLite .NET API reference
Remarks

Recognized properties are:

Property Description

CaseSensitive The status of the case sensitivity feature. Returns ON if the

database is case sensitive. Otherwise, it returns OFF. Data­
base case sensitivity affects how indexes on tables and re­
sult sets are sorted. Case sensitivity does not affect how a
connection's ULConnectionParms.UserID and ULConnec­
tionParms.Password values are verified. User IDs are always
case insensitive and passwords are always case sensitive.

CharSet The character set of the database.

ChecksumLevel The level of database page checksums enabled for the data­
base.

Collation The name of the database's collation sequence.

ConnCount The number of connections to the database.

date_format The date format used for string conversions by the data­
base. This format is not necessarily the same as the one
used by System.DateTime.

date_order The date order used for string conversions by the database.

Encryption The type of encryption applied to the database. Returns

None, Simple, AES, or AES_FIPS.

File The file name of the database.

global_database_id The value of the global_database_id option used for global

autoincrement columns.

isolation_level The value of the isolation_level option used for controlling

the degree to which the operations in one transaction are
visible to the operations in other concurrent transactions.
This value is set on a per connection basis.

MaxHashSize The default maximum number of bytes to use for index

hashing. This property can be set on a per-index basis.

ml_remote_id The value of the ml_remote_id option used for identifying

the database during synchronization.

Name The name of the database (DBN).

nearest_century The nearest century used for string conversions by the data­
base.

PageSize The page size of the database, in bytes.

precision The floating­point precision used for string conversions by

the database.

scale The minimum number of digits after the decimal point when
an arithmetic result is truncated to the maximum PRECI­
SION value during string conversions by the database.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 295
Property Description

time_format The time format used for string conversions by the data­
base. This format is not necessarily the same as the one
used by System.TimeSpan.

timestamp_format The timestamp format used for string conversions by the da­
tabase. This format is not necessarily the same as the one
used by System.DateTime.

timestamp_increment The minimum difference between two unique timestamps, in

microseconds (1,000,000th of a second).

Related Information

SetDatabaseOption(string, string) method [page 298]

UserID property [page 225]
Password property [page 224]

4.1.14.2 GetPublicationName(int) method

Returns the name of the publication identified by the specified publication ID.

 Syntax

Visual Basic

Public Function GetPublicationName (ByVal pubID As Integer) As String

C#

public string GetPublicationName (int pubID)

Parameters

pubID The ID of the publication. The value must be in the range [1,PublicationCount].

Returns

The publication name as a string.

UltraLite - .NET API Reference

296 PUBLIC UltraLite .NET API reference
Exceptions

ULException class A SQL error occurred.

Remarks

 Note

Publication IDs and counts may change during a schema upgrade. To correctly identify a publication,
access it by name or refresh the cached IDs and counts after a schema upgrade.

Related Information

PublicationCount property [page 301]

PublicationCount property [page 301]

4.1.14.3 GetTableName(int) method

Returns the name of the table identified by the specified table ID.

 Syntax

Visual Basic

Public Function GetTableName (ByVal tableID As Integer) As String

C#

public string GetTableName (int tableID)

Parameters

tableID The ID of the table. The value must be in range [1,TableCount].

Returns

The table name as a string.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 297
Exceptions

ULException class A SQL error occurred.

Remarks

Table IDs may change during a schema upgrade. To correctly identify a table, access it by name or refresh the
cached IDs after a schema upgrade.

Related Information

TableCount property [page 302]

4.1.14.4 SetDatabaseOption(string, string) method

Sets the value for the specified database option.

 Syntax

Visual Basic

Public Sub SetDatabaseOption (

ByVal name As String,
ByVal value As String
)

C#

public void SetDatabaseOption (

string name,
string value
)

Parameters

name The name of the database option. Option names are case insensitive.
value The new value for the option.

UltraLite - .NET API Reference

298 PUBLIC UltraLite .NET API reference
Exceptions

ULException class A SQL error occurred.

Remarks

Setting a database option results in a commit being performed.

Using this method while a transaction is active may cause unpredictable results and is not recommended. The
call changes the isolation level of the connection, but does not update the ULTransaction.IsolationLevel value.

Recognized options are:

Option Description

global_database_id The value used for global autoincrement columns. The value
must be in the range [0,System.UInt32.MaxValue]. The de­
fault is the ULConnection.INVALID_DATABASE_ID value
(used to indicate that the database ID has not been set for
the current database).

isolation_level The value used to control the degree to which the operations
in one transaction are visible to the operations in other con­
current transactions. The value must be one of "read_un­
committed" or "read_committed". The default is "read_com­
mitted". Setting the isolation_level on a connection to
"read_uncommitted" is equivalent to wrapping all operations
on that connection with BeginTransaction(System.Data.Iso­
lationLevel.ReadUncommitted) and Commit() calls. Simi­
larly, "read_committed" is equivalent to System.Data.Isola­
tionLevel.ReadCommitted. SetDatabaseOption() should not
be used to set the current transaction's isolation level; use
BeginTransaction(IsolationLevel) instead. UltraLite's defini­
tion of each isolation level is slightly different than
ADO.NET's documentation of IsolationLevel. This value is set
on a per connection basis.

ml_remote_id The value used for identifying the database during synchro­
nization. Use a null reference (Nothing in Visual Basic) as the
value to remove the ml_remote_id option from the database.

Related Information

GetDatabaseProperty(string) method [page 294]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 299
4.1.14.5 IsCaseSensitive property

Checks whether the database is case sensitive.

 Syntax

Visual Basic

Public ReadOnly Property IsCaseSensitive As Boolean

C#

public unsafe bool IsCaseSensitive {get;}

Remarks

True if the database is case sensitive, and false if the database is case insensitive.

Database case sensitivity affects how indexes on tables and result sets are sorted. Case sensitivity also affects
how the ULConnectionParms.UserID and ULConnectionParms.Password values are verified.

Related Information

GetDatabaseProperty(string) method [page 294]

UserID property [page 225]
Password property [page 224]

4.1.14.6 IsOpen property

Determines whether the database schema is open.

 Syntax

Visual Basic

Public ReadOnly Property IsOpen As Boolean

C#

public bool IsOpen {get;}

UltraLite - .NET API Reference

300 PUBLIC UltraLite .NET API reference
Remarks

True if this database schema is currently open, false if this database schema is currently closed.

A ULDatabaseSchema object is open only if the connection it is attached to is open.

4.1.14.7 PublicationCount property

Counts the number of publications in the database.

 Syntax

Visual Basic

Public ReadOnly Property PublicationCount As Integer

C#

public unsafe int PublicationCount {get;}

Remarks

The number of publications in the database.

Publication IDs range from 1 to the PublicationCount value, inclusively.

 Note

Publication IDs and counts may change during a schema upgrade. To correctly identify a publication,
access it by name or refresh the cached IDs and counts after a schema upgrade.

Related Information

GetPublicationName(int) method [page 296]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 301
4.1.14.8 TableCount property

Counts the number of tables in the database.

 Syntax

Visual Basic

Public ReadOnly Property TableCount As Integer

C#

public unsafe int TableCount {get;}

Remarks

The number of tables in the database.

Table IDs range from 1 to the TableCount value, inclusively.

 Note

Table IDs and counts may change during a schema upgrade. To correctly identify a table, access it by name
or refresh the cached IDs and counts after a schema upgrade.

4.1.15 ULDataReader class

Represents a read-only bi-directional cursor in an UltraLite database.

 Syntax

Visual Basic

Public Class ULDataReader Inherits System.Data.Common.DbDataReader

Implements System.ComponentModel.IListSource

C#

public class ULDataReader : System.Data.Common.DbDataReader,

System.ComponentModel.IListSource

Members

All members of ULDataReader, including inherited members.

Methods

UltraLite - .NET API Reference

302 PUBLIC UltraLite .NET API reference
 Modifier and Type Method Description

public override void Close() [page 309] Closes the cursor.

protected override void Dispose(bool) [page 309]

public override unsafe bool GetBoolean(int) [page 310] Returns the value for the specified col­
umn as a System.Boolean.

public override unsafe byte GetByte(int) [page 311] Returns the value for the specified col­
umn as an unsigned 8-bit value (Sys­
tem.Byte).

public unsafe byte[] GetBytes [page 312] UL Ext: Returns the value for the speci­
fied column as an array of Sys­
tem.Bytes values.

public override char GetChar(int) [page 315] This method is not supported in Ultra­
Lite.NET.

public override unsafe long GetChars(int, long, char[], int, int) Copies a subset of the value for the
[page 316] specified ULDbType.LongVarchar col­
umn, beginning at the specified offset,
to the specified offset of the destination
System.Char array.

public override string GetDataTypeName(int) [page 317] Returns the name of the specified col­
umn's provider data type.

public override unsafe DateTime GetDateTime(int) [page 318] Returns the value for the specified col­
umn as a System.DateTime type with
millisecond accuracy.

protected override DbDataReader GetDbDataReader(int) [page 319]

public override decimal GetDecimal(int) [page 319] Returns the value for the specified col­
umn as a System.Decimal type.

public override unsafe double GetDouble(int) [page 320] Returns the value for the specified col­
umn as a System.Double type.

public override IEnumerator GetEnumerator() [page 321] Returns an System.Collections.IEnum­

erator value that iterates through the
ULDataReader object.

public override Type GetFieldType(int) [page 321] Returns the System.Type value most
appropriate for the specified column.

public override unsafe float GetFloat(int) [page 322] Returns the value for the specified col­
umn as a System.Single type.

public override unsafe Guid GetGuid(int) [page 323] Returns the value for the specified col­
umn as a UUID (System.Guid) type.

public override unsafe short GetInt16(int) [page 324] Returns the value for the specified col­
umn as a System.Int16 type.

public override unsafe int GetInt32(int) [page 325] Returns the value for the specified col­
umn as a System.Int32 type.

public override unsafe long GetInt64(int) [page 326] Returns the value for the specified col­
umn as a System.Int64 type.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 303
Modifier and Type Method Description

public override string GetName(int) [page 327] Returns the name of the specified col­
umn.

public override unsafe int GetOrdinal(string) [page 328] Returns the column ID of the named
column.

public unsafe int GetRowCount(int) [page 329] UL Ext: Returns the number of rows in
the cursor, within threshold.

public override DataTable GetSchemaTable() [page 330] Returns a System.Data.DataTable value

that describes the column metadata of
the ULDataReader object.

public override unsafe String GetString(int) [page 332] Returns the value for the specified col­
umn as a System.String type.

public unsafe TimeSpan GetTimeSpan(int) [page 333] Returns the value for the specified col­
umn as a System.TimeSpan type with
millisecond accuracy.

public unsafe ushort GetUInt16(int) [page 334] Returns the value for the specified col­
umn as a System.UInt16 type.

public unsafe uint GetUInt32(int) [page 335] Returns the value for the specified col­
umn as a System.UInt32 type.

public unsafe ulong GetUInt64(int) [page 336] Returns the value for the specified col­
umn as a System.UInt64 type.

public override object GetValue(int) [page 337] Returns the value of the specified col­
umn in its native format.

public override int GetValues(object[]) [page 338] Returns all the column values for the
current row.

public override unsafe bool IsDBNull(int) [page 339] Checks whether the value from the
specified column is NULL.

public void MoveAfterLast() [page 340] UL Ext: Positions the cursor to after the
last row of the cursor.

public void MoveBeforeFirst() [page 340] UL Ext: Positions the cursor to before
the first row of the cursor.

public unsafe bool MoveFirst() [page 341] UL Ext: Positions the cursor to the first
row of the cursor.

public unsafe bool MoveLast() [page 341] UL Ext: Positions the cursor to the last
row of the cursor.

public unsafe bool MoveNext() [page 342] UL Ext: Positions the cursor to the next
row or after the last row if the cursor
was already on the last row.

public unsafe bool MovePrevious() [page 343] UL Ext: Positions the cursor to the pre­
vious row or before the first row.

public unsafe bool MoveRelative(int) [page 343] UL Ext: Positions the cursor relative to
the current row.

UltraLite - .NET API Reference

304 PUBLIC UltraLite .NET API reference
 Modifier and Type Method Description

public override bool NextResult() [page 344] Advances the ULDataReader object to
the next result when reading the results
of batch SQL statements.

public override bool Read() [page 345] Positions the cursor to the next row, or
after the last row if the cursor was al­
ready on the last row.

protected void Validate [page 346] See individual topics

Properties

Modifier and Type Property Description

public override int Depth [page 347] Returns the depth of nesting for the
current row.

public override int FieldCount [page 347] Returns the number of columns in the
cursor.

public override unsafe bool HasRows [page 348] Checks whether the ULDataReader ob­
ject has one or more rows.

public unsafe bool IsBOF [page 348] UL Ext: Checks whether the current row
position is before the first row.

public override bool IsClosed [page 349] Checks whether the cursor is currently
open.

public unsafe bool IsEOF [page 349] UL Ext: Checks whether the current row
position is after the last row.

public override int RecordsAffected [page 350] Returns the number of rows changed,
inserted, or deleted by execution of the
SQL statement.

public int RowCount [page 350] UL Ext: Returns the number of rows in
the cursor.

public ULCursorSchema Schema [page 351] UL Ext: Holds the schema of this cursor.

public override object this [page 352] Returns the value of the specified col­
umn in its native format.

Remarks

Cursors are sets of rows from either a table or the result set from a query.

There is no constructor for the ULDataReader class. To get a ULDataReader object, execute a ULCommand
object:

' Visual Basic

Dim cmd As ULCommand = new ULCommand( _
"SELECT emp_id FROM employee", conn _
)
Dim reader As ULDataReader = cmd.ExecuteReader()

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 305
The following code is the C# language equivalent:

// C#
ULCommand cmd = new ULCommand(
"SELECT emp_id FROM employee", conn
);
ULDataReader reader = cmd.ExecuteReader();

UL Ext: The ADO.NET standard only requires forward-only motion through the result set, but ULDataReader
objects are bi-directional. ULDataReader's Move methods provide you with full flexibility when moving through
results.

A ULDataReader object is a read-only result set. If you need a more flexible object to manipulate results, use
the ULCommand.ExecuteResultSet method, the ULCommand.ExecuteTable method, or the ULDataAdapter
class. The ULDataReader class retrieves rows as needed, whereas the ULDataAdapter class must retrieve all
rows of a result set before you can carry out any action on the object. For large result sets, this difference gives
the ULDataReader class a much faster response time.

UL Ext: All columns of a ULDataReader object may be retrieved using the GetString method.

In this section:

Close() method [page 309]

Closes the cursor.

Dispose(bool) method [page 309]

GetBoolean(int) method [page 310]

Returns the value for the specified column as a System.Boolean.

GetByte(int) method [page 311]

Returns the value for the specified column as an unsigned 8-bit value (System.Byte).

GetBytes method [page 312]

UL Ext: Returns the value for the specified column as an array of System.Bytes values.

GetChar(int) method [page 315]

This method is not supported in UltraLite.NET.

GetChars(int, long, char[], int, int) method [page 316]

Copies a subset of the value for the specified ULDbType.LongVarchar column, beginning at the
specified offset, to the specified offset of the destination System.Char array.

GetDataTypeName(int) method [page 317]

Returns the name of the specified column's provider data type.

GetDateTime(int) method [page 318]

Returns the value for the specified column as a System.DateTime type with millisecond accuracy.

GetDbDataReader(int) method [page 319]

GetDecimal(int) method [page 319]

Returns the value for the specified column as a System.Decimal type.

GetDouble(int) method [page 320]

Returns the value for the specified column as a System.Double type.

GetEnumerator() method [page 321]

Returns an System.Collections.IEnumerator value that iterates through the ULDataReader object.

UltraLite - .NET API Reference

306 PUBLIC UltraLite .NET API reference
 GetFieldType(int) method [page 321]
Returns the System.Type value most appropriate for the specified column.

GetFloat(int) method [page 322]

Returns the value for the specified column as a System.Single type.

GetGuid(int) method [page 323]

Returns the value for the specified column as a UUID (System.Guid) type.

GetInt16(int) method [page 324]

Returns the value for the specified column as a System.Int16 type.

GetInt32(int) method [page 325]

Returns the value for the specified column as a System.Int32 type.

GetInt64(int) method [page 326]

Returns the value for the specified column as a System.Int64 type.

GetName(int) method [page 327]

Returns the name of the specified column.

GetOrdinal(string) method [page 328]

Returns the column ID of the named column.

GetRowCount(int) method [page 329]

UL Ext: Returns the number of rows in the cursor, within threshold.

GetSchemaTable() method [page 330]

Returns a System.Data.DataTable value that describes the column metadata of the ULDataReader
object.

GetString(int) method [page 332]

Returns the value for the specified column as a System.String type.

GetTimeSpan(int) method [page 333]

Returns the value for the specified column as a System.TimeSpan type with millisecond accuracy.

GetUInt16(int) method [page 334]

Returns the value for the specified column as a System.UInt16 type.

GetUInt32(int) method [page 335]

Returns the value for the specified column as a System.UInt32 type.

GetUInt64(int) method [page 336]

Returns the value for the specified column as a System.UInt64 type.

GetValue(int) method [page 337]

Returns the value of the specified column in its native format.

GetValues(object[]) method [page 338]

Returns all the column values for the current row.

IsDBNull(int) method [page 339]

Checks whether the value from the specified column is NULL.

MoveAfterLast() method [page 340]

UL Ext: Positions the cursor to after the last row of the cursor.

MoveBeforeFirst() method [page 340]

UL Ext: Positions the cursor to before the first row of the cursor.

MoveFirst() method [page 341]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 307
 UL Ext: Positions the cursor to the first row of the cursor.

MoveLast() method [page 341]

UL Ext: Positions the cursor to the last row of the cursor.

MoveNext() method [page 342]

UL Ext: Positions the cursor to the next row or after the last row if the cursor was already on the last
row.

MovePrevious() method [page 343]

UL Ext: Positions the cursor to the previous row or before the first row.

MoveRelative(int) method [page 343]

UL Ext: Positions the cursor relative to the current row.

NextResult() method [page 344]

Advances the ULDataReader object to the next result when reading the results of batch SQL
statements.

Read() method [page 345]

Positions the cursor to the next row, or after the last row if the cursor was already on the last row.

Validate method [page 346]

Depth property [page 347]

Returns the depth of nesting for the current row.

FieldCount property [page 347]

Returns the number of columns in the cursor.

HasRows property [page 348]

Checks whether the ULDataReader object has one or more rows.

IsBOF property [page 348]

UL Ext: Checks whether the current row position is before the first row.

IsClosed property [page 349]

Checks whether the cursor is currently open.

IsEOF property [page 349]

UL Ext: Checks whether the current row position is after the last row.

RecordsAffected property [page 350]

Returns the number of rows changed, inserted, or deleted by execution of the SQL statement.

RowCount property [page 350]

UL Ext: Returns the number of rows in the cursor.

Schema property [page 351]

UL Ext: Holds the schema of this cursor.

this property [page 352]

Returns the value of the specified column in its native format.

Related Information

ULCommand class [page 88]

ExecuteResultSet() method [page 119]

UltraLite - .NET API Reference

308 PUBLIC UltraLite .NET API reference
ExecuteTable() method [page 124]
ULDataAdapter class [page 267]
GetString(int) method [page 332]

4.1.15.1 Close() method

Closes the cursor.

 Syntax

Visual Basic

Public Overrides Sub Close ()

C#

public override void Close ()

Exceptions

ULException class A SQL error occurred.

Remarks

It is not an error to close a cursor that is already closed.

4.1.15.2 Dispose(bool) method

 Syntax

Visual Basic

Protected Overrides Sub Dispose (ByVal disposing As Boolean)

C#

protected override void Dispose (bool disposing)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 309
4.1.15.3 GetBoolean(int) method

Returns the value for the specified column as a System.Boolean.

 Syntax

Visual Basic

Public Overrides Function GetBoolean (ByVal colID As Integer) As Boolean

C#

public override unsafe bool GetBoolean (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

The column value as a System.Boolean.

Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
FieldCount property [page 347]

UltraLite - .NET API Reference

310 PUBLIC UltraLite .NET API reference
4.1.15.4 GetByte(int) method

Returns the value for the specified column as an unsigned 8-bit value (System.Byte).

 Syntax

Visual Basic

Public Overrides Function GetByte (ByVal colID As Integer) As Byte

C#

public override unsafe byte GetByte (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

The column value as a System.Byte.

Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
FieldCount property [page 347]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 311
4.1.15.5 GetBytes method

UL Ext: Returns the value for the specified column as an array of System.Bytes values.

Overload list

Modifier and Type Overload name Description

public unsafe byte[] GetBytes(int) [page 312] UL Ext: Returns the value for the speci­
fied column as an array of Sys­
tem.Bytes values.

public override unsafe long GetBytes(int, long, byte[], int, int) [page Copies a subset of the value for the
313] specified ULDbType.LongBinary col­
umn, beginning at the specified offset,
to the specified offset of the destination
System.Byte array.

In this section:

GetBytes(int) method [page 312]

UL Ext: Returns the value for the specified column as an array of System.Bytes values.

GetBytes(int, long, byte[], int, int) method [page 313]

Copies a subset of the value for the specified ULDbType.LongBinary column, beginning at the specified
offset, to the specified offset of the destination System.Byte array.

4.1.15.5.1 GetBytes(int) method

UL Ext: Returns the value for the specified column as an array of System.Bytes values.

 Syntax

Visual Basic

Public Function GetBytes (ByVal colID As Integer) As Byte()

C#

public unsafe byte[] GetBytes (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

UltraLite - .NET API Reference

312 PUBLIC UltraLite .NET API reference
Returns

The column value as an array of System.Bytes type.

Exceptions

ULException class A SQL error occurred.

Remarks

Only valid for columns of the ULDbType.Binary, ULDbType.LongBinary, or ULDbType.UniqueIdentifier types.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
GetBytes(int, long, byte[], int, int) method [page 313]

4.1.15.5.2 GetBytes(int, long, byte[], int, int) method

Copies a subset of the value for the specified ULDbType.LongBinary column, beginning at the specified offset,
to the specified offset of the destination System.Byte array.

 Syntax

Visual Basic

Public Overrides Function GetBytes (

ByVal colID As Integer,
ByVal srcOffset As Long,
ByVal dst As Byte(),
ByVal dstOffset As Integer,
ByVal count As Integer
) As Long

C#

public override unsafe long GetBytes (

int colID,
long srcOffset,
byte[] dst,
int dstOffset,
int count
)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 313
Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
srcOffset The start position in the column value. Zero is the beginning of the value.
dst The destination array.
dstOffset The start position in the destination array.
count The number of bytes to be copied.

Returns

The actual number of bytes copied.

Exceptions

ULException class A SQL error occurred.

Remarks

If you pass a dst buffer that is a null reference (Nothing in Visual Basic), the GetBytes method returns the
length of the field in bytes.

The bytes at the srcOffset through srcOffset +count -1 positions of the value are copied into the dstOffset
through dstOffset +count -1 positions, respectively, of the destination array. If the end of the value is
encountered before count bytes are copied, the remainder of the destination array is left unchanged.

If any of the following are true, a ULException object with code ULSQLCode.SQLE_INVALID_PARAMETER is
thrown and the destination is not modified:

● srcOffset is negative.
● dstOffset is negative.
● count is negative.
● dstOffset +count is greater than the dst length.

For other errors, a ULException object with the appropriate error code is thrown.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]

UltraLite - .NET API Reference

314 PUBLIC UltraLite .NET API reference
GetBytes(int) method [page 312]
ULException class [page 354]
FieldCount property [page 347]

4.1.15.6 GetChar(int) method

This method is not supported in UltraLite.NET.

 Syntax

Visual Basic

Public Overrides Function GetChar (ByVal colID As Integer) As Char

C#

public override char GetChar (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

This method is not supported in UltraLite.NET.

Exceptions

ULException class This method is not supported in UltraLite.NET.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
GetString(int) method [page 332]
FieldCount property [page 347]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 315
4.1.15.7 GetChars(int, long, char[], int, int) method

Copies a subset of the value for the specified ULDbType.LongVarchar column, beginning at the specified offset,
to the specified offset of the destination System.Char array.

 Syntax

Visual Basic

Public Overrides Function GetChars (

ByVal colID As Integer,
ByVal srcOffset As Long,
ByVal dst As Char(),
ByVal dstOffset As Integer,
ByVal count As Integer
) As Long

C#

public override unsafe long GetChars (

int colID,
long srcOffset,
char[] dst,
int dstOffset,
int count
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
srcOffset The start position in the column value. Zero is the beginning of the value.
dst The destination array.
dstOffset The start position in the destination array.
count The number of characters to be copied.

Returns

The actual number of characters copied.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

316 PUBLIC UltraLite .NET API reference
Remarks

If you pass a dst buffer that is a null reference (Nothing in Visual Basic), the GetChars method returns the
length of the field in characters.

The characters at the srcOffset through srcOffset +count -1 positions of the value are copied into the dstOffset
through dstOffset +count -1 positions, respectively, of the destination array. If the end of the value is
encountered before count characters are copied, the remainder of the destination array is left unchanged.

If any of the following instances are true, a ULException object with code
ULSQLCode.SQLE_INVALID_PARAMETER constant is thrown and the destination is not modified:

● The srcOffset value is negative.

● The dstOffset value is negative.
● The count value is negative.
● The dstOffset +count value is greater than the dst length.

For other errors, a ULException object with the appropriate error code is thrown.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
ULException class [page 354]
FieldCount property [page 347]

4.1.15.8 GetDataTypeName(int) method

Returns the name of the specified column's provider data type.

 Syntax

Visual Basic

Public Overrides Function GetDataTypeName (ByVal colID As Integer) As

String

C#

public override string GetDataTypeName (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 317
Returns

A string corresponding to the column's ULDbType type.

Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetColumnULDbType(int) method [page 264]
FieldCount property [page 347]
ULDbType enumeration [page 609]

4.1.15.9 GetDateTime(int) method

Returns the value for the specified column as a System.DateTime type with millisecond accuracy.

 Syntax

Visual Basic

Public Overrides Function GetDateTime (ByVal colID As Integer) As Date

C#

public override unsafe DateTime GetDateTime (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

The column value as a System.DateTime type.

UltraLite - .NET API Reference

318 PUBLIC UltraLite .NET API reference
Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
FieldCount property [page 347]

4.1.15.10 GetDbDataReader(int) method

 Syntax

Visual Basic

Protected Overrides Function GetDbDataReader (ByVal i As Integer) As

DbDataReader

C#

protected override DbDataReader GetDbDataReader (int i)

4.1.15.11 GetDecimal(int) method

Returns the value for the specified column as a System.Decimal type.

 Syntax

Visual Basic

Public Overrides Function GetDecimal (ByVal colID As Integer) As Decimal

C#

public override decimal GetDecimal (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 319
Returns

The column value as a System.Decimal type.

Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
FieldCount property [page 347]

4.1.15.12 GetDouble(int) method

Returns the value for the specified column as a System.Double type.

 Syntax

Visual Basic

Public Overrides Function GetDouble (ByVal colID As Integer) As Double

C#

public override unsafe double GetDouble (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

The column value as a System.Double type.

UltraLite - .NET API Reference

320 PUBLIC UltraLite .NET API reference
Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
FieldCount property [page 347]

4.1.15.13 GetEnumerator() method

Returns an System.Collections.IEnumerator value that iterates through the ULDataReader object.

 Syntax

Visual Basic

Public Overrides Function GetEnumerator () As

System.Collections.IEnumerator

C#

public override IEnumerator GetEnumerator ()

Returns

A System.Collections.IEnumerator for the ULDataReader object.

4.1.15.14 GetFieldType(int) method

Returns the System.Type value most appropriate for the specified column.

 Syntax

Visual Basic

Public Overrides Function GetFieldType (ByVal colID As Integer) As Type

C#

public override Type GetFieldType (int colID)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 321
Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

A System.Type value for the column.

Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetDataTypeName(int) method [page 317]
GetColumnULDbType(int) method [page 264]
FieldCount property [page 347]

4.1.15.15 GetFloat(int) method

Returns the value for the specified column as a System.Single type.

 Syntax

Visual Basic

Public Overrides Function GetFloat (ByVal colID As Integer) As Single

C#

public override unsafe float GetFloat (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

UltraLite - .NET API Reference

322 PUBLIC UltraLite .NET API reference
Returns

The column value as a System.Single type.

Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
FieldCount property [page 347]

4.1.15.16 GetGuid(int) method

Returns the value for the specified column as a UUID (System.Guid) type.

 Syntax

Visual Basic

Public Overrides Function GetGuid (ByVal colID As Integer) As Guid

C#

public override unsafe Guid GetGuid (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

The column value as a GUID type.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 323
Exceptions

ULException class A SQL error occurred.

Remarks

This method is only valid for columns of the ULDbType.UniqueIdentifier type or the ULDbType.Binary type with
length 16.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
GetColumnULDbType(int) method [page 264]
GetColumnSize(int) method [page 262]
FieldCount property [page 347]

4.1.15.17 GetInt16(int) method

Returns the value for the specified column as a System.Int16 type.

 Syntax

Visual Basic

Public Overrides Function GetInt16 (ByVal colID As Integer) As Short

C#

public override unsafe short GetInt16 (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

UltraLite - .NET API Reference

324 PUBLIC UltraLite .NET API reference
Returns

The column value as an System.Int16 type.

Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
FieldCount property [page 347]

4.1.15.18 GetInt32(int) method

Returns the value for the specified column as a System.Int32 type.

 Syntax

Visual Basic

Public Overrides Function GetInt32 (ByVal colID As Integer) As Integer

C#

public override unsafe int GetInt32 (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

The column value as a System.Int32 type.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 325
Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
FieldCount property [page 347]

4.1.15.19 GetInt64(int) method

Returns the value for the specified column as a System.Int64 type.

 Syntax

Visual Basic

Public Overrides Function GetInt64 (ByVal colID As Integer) As Long

C#

public override unsafe long GetInt64 (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

The column value as an System.Int64 type.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

326 PUBLIC UltraLite .NET API reference
Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
FieldCount property [page 347]

4.1.15.20 GetName(int) method

Returns the name of the specified column.

 Syntax

Visual Basic

Public Overrides Function GetName (ByVal colID As Integer) As String

C#

public override string GetName (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

The name of the column or a null reference (Nothing in Visual Basic) if the column has no name. If the column
is aliased in the SQL query, the alias is returned.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 327
Remarks

In result sets, not all columns have names and not all column names are unique. If you are not using aliases, the
name of a non-computed column is prefixed with the name of the table the column is from. For example, the
MyTable.ID value is the name of the only column in the result set for the "SELECT ID FROM MyTable" query.

This method is identical to the ULCursorSchema.GetColumnName method.

Related Information

FieldCount property [page 347]

GetSchemaTable() method [page 330]
GetColumnName(int) method [page 259]
FieldCount property [page 347]

4.1.15.21 GetOrdinal(string) method

Returns the column ID of the named column.

 Syntax

Visual Basic

Public Overrides Function GetOrdinal (ByVal columnName As String) As

Integer

C#

public override unsafe int GetOrdinal (string columnName)

Parameters

columnName The name of the column.

Returns

The column ID of the named column.

UltraLite - .NET API Reference

328 PUBLIC UltraLite .NET API reference
Exceptions

ULException class A SQL error occurred.

Remarks

Column IDs range from 0 to ULDataReader.FieldCount-1, inclusively.

In result sets, not all columns have names and not all column names are unique. If you are not using aliases, the
name of a non-computed column is prefixed with the name of the table the column is from. For example, the
MyTable.ID value is the name of the only column in the result set for the "SELECT ID FROM MyTable" query.

Column IDs and counts may change during a schema upgrade. To correctly identify a column, access it by
name or refresh the cached IDs and counts after a schema upgrade.

This method is identical to the ULCursorSchema.GetColumnID method.

Related Information

GetSchemaTable() method [page 330]

FieldCount property [page 347]
GetColumnID(string) method [page 258]

4.1.15.22 GetRowCount(int) method

UL Ext: Returns the number of rows in the cursor, within threshold.

 Syntax

Visual Basic

Public Function GetRowCount (ByVal threshold As Integer) As Integer

C#

public unsafe int GetRowCount (int threshold)

Parameters

threshold Threshold limit for row count.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 329
Exceptions

ULException class A SQL error occurred.

Remarks

The number of rows in the cursor.

The RowCount property is expensive with complex queries, as it requires passing through the cursor rows. By
using the GetRowCount( threshold ) method, the caller can determine if there are at least threshold rows. If the
number of rows is below the threshold, that number is returned; otherwise, threshold is returned. This can be
called again with a higher threshold.

If threshold is 0, returns the RowCount property.

Related Information

RowCount property [page 350]

4.1.15.23 GetSchemaTable() method

Returns a System.Data.DataTable value that describes the column metadata of the ULDataReader object.

 Syntax

Visual Basic

Public Overrides Function GetSchemaTable () As DataTable

C#

public override DataTable GetSchemaTable ()

Returns

A System.Data.DataTable describing the schema of each column in the ULDataReader.

UltraLite - .NET API Reference

330 PUBLIC UltraLite .NET API reference
Remarks

The GetSchemaTable method returns metadata about each column in the following order:

DataTable column Description

ColumnName The name of the column or a null reference (Nothing in Vis­

ual Basic) if the column has no name. If the column is aliased
in the SQL query, the alias is returned. In result sets, not all
columns have names and not all column names are unique.

ColumnOrdinal The ID of the column. The value is in the range [0,Field­

Count-1].

ColumnSize For sized columns, the maximum length of a value in the col­
umn. For other columns, this is the size in bytes of the data
type.

NumericPrecision The precision of a numeric column (ProviderType ULDb­

Type.Decimal or ULDbType.Numeric) or DBNull if the col­
umn is not numeric.

NumericScale The scale of a numeric column (ProviderType ULDb­

Type.Decimal or ULDbType.Numeric) or DBNull if the col­
umn is not numeric.

IsUnique True if the column is a non-computed unique column in the

table (BaseTableName) it is taken from.

IsKey True if the column is one of a set of columns in the result set
that taken together from a unique key for the result set. The
set of columns with the IsKey value set to true does not need
to be the minimal set that uniquely identifies a row in the re­
sult set.

BaseCatalogName The name of the catalog in the database that contains the
column. For UltraLite.NET, this value is always DBNull.

BaseColumnName The original name of the column in the BaseTableName table

of the database, or DBNull if the column is computed or if
this information cannot be determined.

BaseSchemaName The name of the schema in the database that contains the
column. For UltraLite.NET, this value is always DBNull.

BaseTableName The name of the table in the database that contains the col­
umn, or DBNull if column is computed or if this information
cannot be determined.

DataType The .NET data type that is most appropriate for this type of
column.

AllowDBNull True if the column is nullable, false if the column is not nulla­
ble or if this information cannot be determined.

ProviderType The ULDbType value of the column.

IsIdentity True if the column is an identity column, false if it is not an

identity column. For UltraLite.NET, this value is always false.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 331
DataTable column Description

IsAutoIncrement True if the column is an autoincrement or global autoincre­

ment column, false otherwise (or if this information cannot
be determined).

IsRowVersion True if the column contains a persistent row identifier that

cannot be written to, and has no meaningful value except to
identity the row. For UltraLite.NET, this value is always false.

IsLong True if the column is a ULDbType.LongVarchar or a ULDb­

Type.LongBinary column, false otherwise.

IsReadOnly True if the column is read-only, false if the column is modifia­

ble or if its access cannot be determined.

IsAliased True if the column name is an alias, false if it is not an alias.

IsExpression True if the column is an expression, false if it is a column

value.

Related Information

Schema property [page 351]

FieldCount property [page 347]
ULDbType enumeration [page 609]

4.1.15.24 GetString(int) method

Returns the value for the specified column as a System.String type.

 Syntax

Visual Basic

Public Overrides Function GetString (ByVal colID As Integer) As String

C#

public override unsafe String GetString (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

UltraLite - .NET API Reference

332 PUBLIC UltraLite .NET API reference
Returns

The column value as a System.String type.

Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
FieldCount property [page 347]

4.1.15.25 GetTimeSpan(int) method

Returns the value for the specified column as a System.TimeSpan type with millisecond accuracy.

 Syntax

Visual Basic

Public Function GetTimeSpan (ByVal colID As Integer) As TimeSpan

C#

public unsafe TimeSpan GetTimeSpan (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

The column value as a System.TimeSpan type.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 333
Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
FieldCount property [page 347]

4.1.15.26 GetUInt16(int) method

Returns the value for the specified column as a System.UInt16 type.

 Syntax

Visual Basic

Public Function GetUInt16 (ByVal colID As Integer) As UShort

C#

public unsafe ushort GetUInt16 (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

The column value as an System.UInt16 type.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

334 PUBLIC UltraLite .NET API reference
Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
FieldCount property [page 347]

4.1.15.27 GetUInt32(int) method

Returns the value for the specified column as a System.UInt32 type.

 Syntax

Visual Basic

Public Function GetUInt32 (ByVal colID As Integer) As UInteger

C#

public unsafe uint GetUInt32 (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

The column value as a System.UInt32 type.

Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 335
FieldCount property [page 347]

4.1.15.28 GetUInt64(int) method

Returns the value for the specified column as a System.UInt64 type.

 Syntax

Visual Basic

Public Function GetUInt64 (ByVal colID As Integer) As ULong

C#

public unsafe ulong GetUInt64 (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

The column value as a System.UInt64 type.

Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
FieldCount property [page 347]

UltraLite - .NET API Reference

336 PUBLIC UltraLite .NET API reference
4.1.15.29 GetValue(int) method

Returns the value of the specified column in its native format.

 Syntax

Visual Basic

Public Overrides Function GetValue (ByVal colID As Integer) As Object

C#

public override object GetValue (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

The column value as the .NET type most appropriate for the column or the DBNull type if column is NULL.

Exceptions

ULException class A SQL error occurred.

Remarks

This method is identical to using the ULDataReader.this[int] method.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
FieldCount property [page 347]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 337
4.1.15.30 GetValues(object[]) method

Returns all the column values for the current row.

 Syntax

Visual Basic

Public Overrides Function GetValues (ByVal values As Object()) As Integer

C#

public override int GetValues (object[] values)

Parameters

values The array of System.Objects to hold the entire row.

Returns

The number of column values retrieved. If the length of the array is greater than the number of columns
(ULDataReader.FieldCount), only FieldCount items are retrieved and the rest of the array is left unchanged.

Exceptions

ArgumentNullException The values array is NULL or has zero length.

ULException class A SQL error occurred.

Remarks

For most applications, the GetValues method provides an efficient means for retrieving all columns, rather than
retrieving each column individually.

You can pass an System.Object array that contains fewer than the number of columns contained in the
resulting row. Only the amount of data the System.Object array holds is copied to the array. You can also pass
an System.Object array whose length is more than the number of columns contained in the resulting row.

This method returns the DBNull type for NULL database columns. For other columns, it returns the value of the
column in its native format.

UltraLite - .NET API Reference

338 PUBLIC UltraLite .NET API reference
Related Information

FieldCount property [page 347]

GetFieldType(int) method [page 321]
GetValue(int) method [page 337]

4.1.15.31 IsDBNull(int) method

Checks whether the value from the specified column is NULL.

 Syntax

Visual Basic

Public Overrides Function IsDBNull (ByVal colID As Integer) As Boolean

C#

public override unsafe bool IsDBNull (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Returns

True if value is NULL, false if value is not NULL.

Exceptions

ULException class A SQL error occurred.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 339
FieldCount property [page 347]

4.1.15.32 MoveAfterLast() method

UL Ext: Positions the cursor to after the last row of the cursor.

 Syntax

Visual Basic

Public Sub MoveAfterLast ()

C#

public void MoveAfterLast ()

Exceptions

ULException class A SQL error occurred.

4.1.15.33 MoveBeforeFirst() method

UL Ext: Positions the cursor to before the first row of the cursor.

 Syntax

Visual Basic

Public Sub MoveBeforeFirst ()

C#

public void MoveBeforeFirst ()

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

340 PUBLIC UltraLite .NET API reference
4.1.15.34 MoveFirst() method

UL Ext: Positions the cursor to the first row of the cursor.

 Syntax

Visual Basic

Public Function MoveFirst () As Boolean

C#

public unsafe bool MoveFirst ()

Returns

True if successful, false otherwise. For example, the method fails if there are no rows.

Exceptions

ULException class A SQL error occurred.

4.1.15.35 MoveLast() method

UL Ext: Positions the cursor to the last row of the cursor.

 Syntax

Visual Basic

Public Function MoveLast () As Boolean

C#

public unsafe bool MoveLast ()

Returns

True if successful, false otherwise. For example, the method fails if there are no rows.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 341
Exceptions

ULException class A SQL error occurred.

4.1.15.36 MoveNext() method

UL Ext: Positions the cursor to the next row or after the last row if the cursor was already on the last row.

 Syntax

Visual Basic

Public Function MoveNext () As Boolean

C#

public unsafe bool MoveNext ()

Returns

True if successful, false otherwise. For example, the method fails if there are no more rows.

Exceptions

ULException class A SQL error occurred.

Remarks

This method is identical to the ULDataReader.Read method.

Related Information

Read() method [page 345]

UltraLite - .NET API Reference

342 PUBLIC UltraLite .NET API reference
4.1.15.37 MovePrevious() method

UL Ext: Positions the cursor to the previous row or before the first row.

 Syntax

Visual Basic

Public Function MovePrevious () As Boolean

C#

public unsafe bool MovePrevious ()

Returns

True if successful, false otherwise. For example, the method fails if there are no more rows.

Exceptions

ULException class A SQL error occurred.

4.1.15.38 MoveRelative(int) method

UL Ext: Positions the cursor relative to the current row.

 Syntax

Visual Basic

Public Function MoveRelative (ByVal offset As Integer) As Boolean

C#

public unsafe bool MoveRelative (int offset)

Parameters

offset The number of rows to move. Negative values correspond to moving backward.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 343
Returns

True if successful, false otherwise. For example, the method fails if it positions beyond the first or last row.

Exceptions

ULException class A SQL error occurred.

Remarks

If the row does not exist, the method returns false, and the cursor position is after the last row (the
ULDataReader.IsEOF method) if offset value is positive, and before the first row (the ULDataReader.IsBOF
method) if the offset value is negative.

Related Information

IsEOF property [page 349]

IsBOF property [page 348]

4.1.15.39 NextResult() method

Advances the ULDataReader object to the next result when reading the results of batch SQL statements.

 Syntax

Visual Basic

Public Overrides Function NextResult () As Boolean

C#

public override bool NextResult ()

Returns

True if there are more result sets, false otherwise. For UltraLite.NET, always returns false.

UltraLite - .NET API Reference

344 PUBLIC UltraLite .NET API reference
Exceptions

ULException class The ULDataReader object is not opened.

Remarks

UL Ext: UltraLite.NET does not support batches of SQL statements, so the ULDataReader object is always
positioned on the first and only result set. NextResult method calls have no effect.

4.1.15.40 Read() method

Positions the cursor to the next row, or after the last row if the cursor was already on the last row.

 Syntax

Visual Basic

Public Overrides Function Read () As Boolean

C#

public override bool Read ()

Returns

True if successful, false otherwise. For example, the method fails if there are no more rows.

Exceptions

ULException class A SQL error occurred.

Remarks

This method is identical to the ULDataReader.MoveNext method.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 345
Related Information

MoveNext() method [page 342]

4.1.15.41 Validate method

Overload list

Modifier and Type Overload name Description

protected void Validate() [page 346]

protected void Validate(int) [page 346]

In this section:

Validate() method [page 346]

Validate(int) method [page 346]

4.1.15.41.1 Validate() method

 Syntax

Visual Basic

Protected Sub Validate ()

C#

protected void Validate ()

4.1.15.41.2 Validate(int) method

 Syntax

Visual Basic

Protected Sub Validate (ByVal colID As Integer)

UltraLite - .NET API Reference

346 PUBLIC UltraLite .NET API reference
 C#

protected void Validate (int colID)

4.1.15.42 Depth property

Returns the depth of nesting for the current row.

 Syntax

Visual Basic

Public ReadOnly Overrides Property Depth As Integer

C#

public override int Depth {get;}

Remarks

The outermost table has a depth of zero.

All UltraLite.NET result sets have a depth of zero.

4.1.15.43 FieldCount property

Returns the number of columns in the cursor.

 Syntax

Visual Basic

Public ReadOnly Overrides Property FieldCount As Integer

C#

public override int FieldCount {get;}

Returns

The number of columns in the cursor as an integer. Returns 0 if the cursor is closed.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 347
Remarks

This method is identical to the ULCursorSchema.ColumnCount method.

Related Information

ColumnCount property [page 266]

4.1.15.44 HasRows property

Checks whether the ULDataReader object has one or more rows.

 Syntax

Visual Basic

Public ReadOnly Overrides Property HasRows As Boolean

C#

public override unsafe bool HasRows {get;}

Remarks

True if the result set has at least one row, false if there are no rows.

4.1.15.45 IsBOF property

UL Ext: Checks whether the current row position is before the first row.

 Syntax

Visual Basic

Public ReadOnly Property IsBOF As Boolean

C#

public unsafe bool IsBOF {get;}

UltraLite - .NET API Reference

348 PUBLIC UltraLite .NET API reference
Remarks

True if the current row position is before the first row, false otherwise.

4.1.15.46 IsClosed property

Checks whether the cursor is currently open.

 Syntax

Visual Basic

Public ReadOnly Overrides Property IsClosed As Boolean

C#

public override bool IsClosed {get;}

Remarks

True if the cursor is currently open, false if the cursor is closed.

4.1.15.47 IsEOF property

UL Ext: Checks whether the current row position is after the last row.

 Syntax

Visual Basic

Public ReadOnly Property IsEOF As Boolean

C#

public unsafe bool IsEOF {get;}

Remarks

True if the current row position is after the last row, false otherwise.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 349
4.1.15.48 RecordsAffected property

Returns the number of rows changed, inserted, or deleted by execution of the SQL statement.

 Syntax

Visual Basic

Public ReadOnly Overrides Property RecordsAffected As Integer

C#

public override int RecordsAffected {get;}

Remarks

For SELECT statements or CommandType.TableDirect tables, this value is -1.

The number of rows changed, inserted, or deleted by execution of the SQL statement.

4.1.15.49 RowCount property

UL Ext: Returns the number of rows in the cursor.

 Syntax

Visual Basic

Public ReadOnly Property RowCount As Integer

C#

public int RowCount {get;}

Remarks

The number of rows in the cursor.

You can use the RowCount method to decide when to delete old rows to save space. Old rows can be deleted
from the UltraLite database without being deleted from the consolidated database using the
ULConnection.StopSynchronizationDelete method.

UltraLite - .NET API Reference

350 PUBLIC UltraLite .NET API reference
Related Information

StartSynchronizationDelete() method [page 198]

StopSynchronizationDelete() method [page 199]

4.1.15.50 Schema property

UL Ext: Holds the schema of this cursor.

 Syntax

Visual Basic

Public ReadOnly Property Schema As ULCursorSchema

C#

public ULCursorSchema Schema {get;}

Remarks

For result sets, the ULResultSetSchema object representing the schema of the result set. For tables, the
ULTableSchema object representing the schema of the table.

This property represents the complete schema of the cursor, including UltraLite.NET extended information
which is not represented in the results from the ULDataReader.GetSchemaTable method.

Related Information

ULTableSchema class [page 578]

GetSchemaTable() method [page 330]
ULResultSetSchema class [page 494]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 351
4.1.15.51 this property

Returns the value of the specified column in its native format.

Overload list

Modifier and Type Overload name Description

public override object this[int colID] [page 352] Returns the value of the specified col­
umn in its native format.

public override object this[string name] [page 353] Returns the value of the specified
named column in its native format.

In this section:

this[int colID] property [page 352]

Returns the value of the specified column in its native format.

this[string name] property [page 353]

Returns the value of the specified named column in its native format.

4.1.15.51.1 this[int colID] property

Returns the value of the specified column in its native format.

 Syntax

Visual Basic

Public ReadOnly Overrides Property Item (ByVal colIDAs Integer) As Object

C#

public override object this[int colID] {get;}

Returns

The column value as the .NET type most appropriate for the column or DBNull if column is NULL.

UltraLite - .NET API Reference

352 PUBLIC UltraLite .NET API reference
Remarks

In C#, this property is the indexer for the ULDataReader class.

This method is identical in functionality to the ULDataReader.GetValue(int) method.

Related Information

GetFieldType(int) method [page 321]

GetValue(int) method [page 337]
FieldCount property [page 347]

4.1.15.51.2 this[string name] property

Returns the value of the specified named column in its native format.

 Syntax

Visual Basic

Public ReadOnly Overrides Property Item (ByVal nameAs String) As Object

C#

public override object this[string name] {get;}

Returns

The column value as the .NET type most appropriate for the column or DBNull if column is NULL.

Remarks

In C#, this property is the indexer for the ULDataReader object.

In result sets, not all columns have names and not all column names are unique. If you are not using aliases, the
name of a non-computed column is prefixed with the name of the table the column is from. For example, the
MyTable.ID value is the name of the only column in the result set for the query "SELECT ID FROM MyTable".

When accessing columns multiple times, it is more efficient to access columns by column ID than by name.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 353
This method is equivalent to:

dataReader.GetValue( dataReader.GetOrdinal( name ) )

Related Information

GetOrdinal(string) method [page 328]

GetValue(int) method [page 337]
GetFieldType(int) method [page 321]

4.1.16 ULException class

Represents a SQL error returned by the UltraLite.NET database.

 Syntax

Visual Basic

Public NotInheritable Class ULException Inherits

System.ApplicationException

C#

public sealed class ULException : System.ApplicationException

Members

All members of ULException, including inherited members.

Properties

Modifier and Type Property Description

public ULSQLCode NativeError [page 355] Returns the SQLCODE value returned
by the database.

public override string Source [page 355] Returns the name of the provider that
generated the error.

Remarks

The SQLCODE denoting the error is returned in the NativeError property.

This class is not serializable under the .NET Compact Framework.

UltraLite - .NET API Reference

354 PUBLIC UltraLite .NET API reference
In this section:

NativeError property [page 355]

Returns the SQLCODE value returned by the database.

Source property [page 355]

Returns the name of the provider that generated the error.

Related Information

NativeError property [page 355]

4.1.16.1 NativeError property

Returns the SQLCODE value returned by the database.

 Syntax

Visual Basic

Public ReadOnly Property NativeError As ULSQLCode

C#

public ULSQLCode NativeError {get;}

Remarks

The ULSQLCode value returned by the database.

4.1.16.2 Source property

Returns the name of the provider that generated the error.

 Syntax

Visual Basic

Public ReadOnly Overrides Property Source As String

C#

public override string Source {get;}

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 355
Remarks

The string value identifying UltraLite.NET as the provider.

4.1.17 ULFactory class

Represents a set of methods for creating instances of the Sap.Data.UltraLite provider's implementation of the
data source classes.

 Syntax

Visual Basic

Public Class ULFactory Inherits System.Data.Common.DbProviderFactory

C#

public class ULFactory : System.Data.Common.DbProviderFactory

Members

All members of ULFactory, including inherited members.

Variables

Modifier and Type Variable Description

public static readonly ULFactory Instance Represents the singleton instance of

the ULFactory class.

The ULFactory class is not available in

the .NET Compact Framework 2.0.

ULFactory is a singleton class, which

means only this instance of this class
can exist.

Normally you would not use this field di­

rectly. Instead, you get a reference to
this instance of the ULFactory class us­
ing the System.Data.Common.DbProvi­
derFactories.GetFactory(String)
method.

Methods

UltraLite - .NET API Reference

356 PUBLIC UltraLite .NET API reference
 Modifier and Type Method Description

public override DbCommand CreateCommand() [page 358] Returns a strongly typed Sys­
tem.Data.Common.DbCommand in­
stance.

public override DbCommandBuilder CreateCommandBuilder() [page 359] Returns a strongly typed Sys­
tem.Data.Common.DbCommand­
Builder instance.

public override DbConnection CreateConnection() [page 359] Returns a strongly typed Sys­
tem.Data.Common.DbConnection in­
stance.

public override DbConnectionString­ CreateConnectionStringBuilder() [page Returns a strongly typed Sys­

Builder 360] tem.Data.Common.DbConnection­
StringBuilder instance.

public override DbDataAdapter CreateDataAdapter() [page 360] Returns a strongly typed Sys­
tem.Data.Common.DbDataAdapter in­
stance.

public override DbParameter CreateParameter() [page 361] Returns a strongly typed Sys­
tem.Data.Common.DbParameter in­
stance.

Properties

Modifier and Type Property Description

public override bool CanCreateDataSourceEnumerator Returns false to indicate the Ultra­

[page 361] Lite.NET does not support the DbData­
SourceEnumerator class.

Remarks

The ULFactory class is not available in the .NET Compact Framework 2.0.

ADO.NET 2.0 adds two new classes, the System.Data.Common.DbProviderFactories class and the
System.Data.Common.DbProviderFactory class, to make provider independent code easier to write. To use
them with UltraLite.NET specify Sap.Data.UltraLite as the provider invariant name passed to the GetFactory
method. For example:

' Visual Basic

Dim factory As DbProviderFactory = _
DbProviderFactories.GetFactory( "Sap.Data.UltraLite" )
Dim conn As DbConnection = _
factory.CreateConnection()

The following code is the C# language equivalent:

// C#
DbProviderFactory factory =
DbProviderFactories.GetFactory( "Sap.Data.UltraLite" );
DbConnection conn = factory.CreateConnection();

In this example, conn is created as an ULConnection object.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 357
For an explanation of provider factories and generic programming in ADO.NET 2.0, see . UltraLite.NET does not
support the CreateCommandBuilder, CreateDataSourceEnumerator, and CreatePermission methods. Custom
Attribute: sealed

In this section:

CreateCommand() method [page 358]

Returns a strongly typed System.Data.Common.DbCommand instance.

CreateCommandBuilder() method [page 359]

Returns a strongly typed System.Data.Common.DbCommandBuilder instance.

CreateConnection() method [page 359]

Returns a strongly typed System.Data.Common.DbConnection instance.

CreateConnectionStringBuilder() method [page 360]

Returns a strongly typed System.Data.Common.DbConnectionStringBuilder instance.

CreateDataAdapter() method [page 360]

Returns a strongly typed System.Data.Common.DbDataAdapter instance.

CreateParameter() method [page 361]

Returns a strongly typed System.Data.Common.DbParameter instance.

CanCreateDataSourceEnumerator property [page 361]

Returns false to indicate the UltraLite.NET does not support the DbDataSourceEnumerator class.

4.1.17.1 CreateCommand() method

Returns a strongly typed System.Data.Common.DbCommand instance.

 Syntax

Visual Basic

Public Overrides Function CreateCommand () As DbCommand

C#

public override DbCommand CreateCommand ()

Returns

A new ULCommand instance typed as DbCommand.

Related Information

ULCommand class [page 88]

UltraLite - .NET API Reference

358 PUBLIC UltraLite .NET API reference
4.1.17.2 CreateCommandBuilder() method

Returns a strongly typed System.Data.Common.DbCommandBuilder instance.

 Syntax

Visual Basic

Public Overrides Function CreateCommandBuilder () As DbCommandBuilder

C#

public override DbCommandBuilder CreateCommandBuilder ()

Returns

A new ULCommandBuilder instance typed as DbCommandBuilder.

Related Information

ULCommandBuilder class [page 135]

4.1.17.3 CreateConnection() method

Returns a strongly typed System.Data.Common.DbConnection instance.

 Syntax

Visual Basic

Public Overrides Function CreateConnection () As DbConnection

C#

public override DbConnection CreateConnection ()

Returns

A new ULConnection instance typed as DbConnection.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 359
Related Information

ULConnection class [page 151]

4.1.17.4 CreateConnectionStringBuilder() method

Returns a strongly typed System.Data.Common.DbConnectionStringBuilder instance.

 Syntax

Visual Basic

Public Overrides Function CreateConnectionStringBuilder () As

DbConnectionStringBuilder

C#

public override DbConnectionStringBuilder CreateConnectionStringBuilder ()

Returns

A new ULConnectionStringBuilder instance typed as DbConnectionStringBuilder.

Related Information

ULConnectionStringBuilder class [page 226]

4.1.17.5 CreateDataAdapter() method

Returns a strongly typed System.Data.Common.DbDataAdapter instance.

 Syntax

Visual Basic

Public Overrides Function CreateDataAdapter () As DbDataAdapter

C#

public override DbDataAdapter CreateDataAdapter ()

UltraLite - .NET API Reference

360 PUBLIC UltraLite .NET API reference
Returns

A new ULDataAdapter instance typed as DbDataAdapter.

Related Information

ULDataAdapter class [page 267]

4.1.17.6 CreateParameter() method

Returns a strongly typed System.Data.Common.DbParameter instance.

 Syntax

Visual Basic

Public Overrides Function CreateParameter () As DbParameter

C#

public override DbParameter CreateParameter ()

Returns

A new ULParameter instance typed as DbParameter.

Related Information

ULParameter class [page 413]

4.1.17.7 CanCreateDataSourceEnumerator property

Returns false to indicate the UltraLite.NET does not support the DbDataSourceEnumerator class.

 Syntax

Visual Basic

Public ReadOnly Overrides Property CanCreateDataSourceEnumerator As Boolean

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 361
 C#

public override bool CanCreateDataSourceEnumerator {get;}

Remarks

False to indicate that the ULFactory class does not implement the CreateDataSourceEnumerator method.

4.1.18 ULFileTransfer class

UL Ext: Transfers a file from a remote database using the MobiLink server.

 Syntax

Visual Basic

Public NotInheritable Class ULFileTransfer

C#

public sealed class ULFileTransfer

Members

All members of ULFileTransfer, including inherited members.

Constructors

Modifier and Type Constructor Description

public ULFileTransfer() [page 365] Initializes a ULFileTransfer object.

Methods

Modifier and Type Method Description

public bool DownloadFile [page 366] Download the file specified by the prop­
erties of this object.

public bool UploadFile [page 369] Upload the file specified by the proper­
ties of this object.

Properties

UltraLite - .NET API Reference

362 PUBLIC UltraLite .NET API reference
 Modifier and Type Property Description

public unsafe String[] AuthenticationParms [page 372] Specifies parameters for a custom user
authentication script (MobiLink authen­
ticate_parameters connection event).

public ULAuthStatusCode AuthStatus [page 373] Returns the authorization status code
for the last file transfer attempt.

public long AuthValue [page 373] Returns the return value from custom
user authentication synchronization
scripts.

public ushort FileAuthCode [page 374] Returns the return value from the au­
thenticate_file_transfer script for the
last file transfer attempt.

public string FileName [page 374] Specifies the name of the file to down­
load.

public string LocalFileName [page 375] Specifies the local file name for the
downloaded file.

public string LocalPath [page 376] Specifies where to download the file.

public string Password [page 376] The MobiLink password for the user
specified by the UserName value.

public string RemoteKey [page 377] The key that uniquely identifies the Mo­
biLink client to the MobiLink server.

public bool ResumePartialDownload [page 378] Specifies whether to resume or discard

a previous partial download.

public ULStreamType Stream [page 378] Specifies the MobiLink synchronization

stream to use for the file transfer.

public ULStreamErrorCode StreamErrorCode [page 379] Returns the error reported by the
stream itself for the last file transfer at­
tempt.

public int StreamErrorSystem [page 380] Returns the stream error system-spe­
cific code.

public string StreamParms [page 380] Specifies the parameters to configure

the synchronization stream.

public bool TransferredFile [page 381] Checks whether the file was actually
downloaded during the last file transfer
attempt.

public string UserName [page 382] The user name that identifies the Mobi­
Link client to the MobiLink server.

public string Version [page 382] Specifies which synchronization script

to use.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 363
Remarks

You do not need a database connection to perform a file transfer, however, if your application uses an UltraLite
database with the UltraLite Engine runtime, you must set the ULDatabaseManager.RuntimeType value to the
appropriate value before using this API or any other UltraLite.NET API.

To transfer a file you must set the ULFileTransfer.FileName, ULFileTransfer.Stream, ULFileTransfer.UserName,

and ULFileTransfer.Version values.

In this section:

ULFileTransfer() constructor [page 365]

Initializes a ULFileTransfer object.

DownloadFile method [page 366]

Download the file specified by the properties of this object.

UploadFile method [page 369]

Upload the file specified by the properties of this object.

AuthenticationParms property [page 372]

Specifies parameters for a custom user authentication script (MobiLink authenticate_parameters
connection event).

AuthStatus property [page 373]

Returns the authorization status code for the last file transfer attempt.

AuthValue property [page 373]

Returns the return value from custom user authentication synchronization scripts.

FileAuthCode property [page 374]

Returns the return value from the authenticate_file_transfer script for the last file transfer attempt.

FileName property [page 374]

Specifies the name of the file to download.

LocalFileName property [page 375]

Specifies the local file name for the downloaded file.

LocalPath property [page 376]

Specifies where to download the file.

Password property [page 376]

The MobiLink password for the user specified by the UserName value.

RemoteKey property [page 377]

The key that uniquely identifies the MobiLink client to the MobiLink server.

ResumePartialDownload property [page 378]

Specifies whether to resume or discard a previous partial download.

Stream property [page 378]

Specifies the MobiLink synchronization stream to use for the file transfer.

StreamErrorCode property [page 379]

Returns the error reported by the stream itself for the last file transfer attempt.

StreamErrorSystem property [page 380]

Returns the stream error system­specific code.

UltraLite - .NET API Reference

364 PUBLIC UltraLite .NET API reference
 StreamParms property [page 380]
Specifies the parameters to configure the synchronization stream.

TransferredFile property [page 381]

Checks whether the file was actually downloaded during the last file transfer attempt.

UserName property [page 382]

The user name that identifies the MobiLink client to the MobiLink server.

Version property [page 382]

Specifies which synchronization script to use.

Related Information

FileName property [page 374]

Stream property [page 378]
UserName property [page 382]
Version property [page 382]

4.1.18.1 ULFileTransfer() constructor

Initializes a ULFileTransfer object.

 Syntax

Visual Basic

Public Sub ULFileTransfer ()

C#

public ULFileTransfer ()

Remarks

The connection must be opened before you can perform any operations against the database.

You do not need a database connection to perform a file transfer, however, if your application uses an UltraLite
database with the UltraLite Engine runtime, you must set the ULDatabaseManager.RuntimeType value to the
appropriate value before using this API or any other UltraLite.NET API.

The ULFileTransfer object needs to have the ULFileTransfer.FileName, ULFileTransfer.Stream,

ULFileTransfer.UserName, and ULFileTransfer.Version values set before it can transfer a file.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 365
Related Information

DownloadFile() method [page 366]

UploadFile() method [page 370]
FileName property [page 374]
Stream property [page 378]
UserName property [page 382]
Version property [page 382]

4.1.18.2 DownloadFile method

Download the file specified by the properties of this object.

Overload list

Modifier and Type Overload name Description

public bool DownloadFile() [page 366] Download the file specified by the prop­
erties of this object.

public bool DownloadFile(ULFileTransferProgres­ Download the file specified by the prop­

sListener) [page 368] erties of this object with progress
events posted to the specified listener.

In this section:

DownloadFile() method [page 366]

Download the file specified by the properties of this object.

DownloadFile(ULFileTransferProgressListener) method [page 368]

Download the file specified by the properties of this object with progress events posted to the specified
listener.

4.1.18.2.1 DownloadFile() method

Download the file specified by the properties of this object.

 Syntax

Visual Basic

Public Function DownloadFile () As Boolean

UltraLite - .NET API Reference

366 PUBLIC UltraLite .NET API reference
 C#

public bool DownloadFile ()

Returns

True if successful, false otherwise (check the ULFileTransfer.StreamErrorCode value and other status
properties for reason).

Remarks

The file specified by the ULFileTransfer.FileName value is downloaded by the MobiLink server to the
ULFileTransfer.LocalPath value using the ULFileTransfer.Stream, ULFileTransfer.UserName,
ULFileTransfer.Password, and ULFileTransfer.Version values.

To avoid file corruption, UltraLite.NET downloads to a temporary file and only replaces the local file once the
download has completed. Other properties that affect the download are: ULFileTransfer.LocalFileName,
ULFileTransfer.AuthenticationParms, and ULFileTransfer.ResumePartialDownload.

A detailed result status is reported in this object's ULFileTransfer.AuthStatus, ULFileTransfer.AuthValue,

ULFileTransfer.FileAuthCode, ULFileTransfer.TransferredFile, ULFileTransfer.StreamErrorCode, and
ULFileTransfer.StreamErrorSystem values.

Related Information

DownloadFile(ULFileTransferProgressListener) method [page 368]

FileName property [page 374]
LocalPath property [page 376]
Stream property [page 378]
UserName property [page 382]
Password property [page 376]
Version property [page 382]
LocalFileName property [page 375]
AuthenticationParms property [page 372]
ResumePartialDownload property [page 378]
AuthStatus property [page 373]
AuthValue property [page 373]
FileAuthCode property [page 374]
TransferredFile property [page 381]
StreamErrorCode property [page 379]
StreamErrorSystem property [page 380]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 367
StreamErrorCode property [page 379]
UploadFile() method [page 370]

4.1.18.2.2 DownloadFile(ULFileTransferProgressListener)
method

Download the file specified by the properties of this object with progress events posted to the specified listener.

 Syntax

Visual Basic

Public Function DownloadFile (ByVal listener As

ULFileTransferProgressListener) As Boolean

C#

public bool DownloadFile (ULFileTransferProgressListener listener)

Parameters

listener The object that receives file transfer progress events.

Returns

True if successful, false otherwise (check the ULFileTransfer.StreamErrorCode value and other status
properties for reason).

Remarks

The file specified by the ULFileTransfer.FileName value is downloaded by the MobiLink server to the
ULFileTransfer.LocalPath value using the ULFileTransfer.Stream, ULFileTransfer.UserName,
ULFileTransfer.Password, and ULFileTransfer.Version values.

To avoid file corruption, UltraLite.NET downloads to a temporary file and only replaces the local file once the
download has completed. Other properties that affect the download are: ULFileTransfer.LocalFileName,
ULFileTransfer.AuthenticationParms, and ULFileTransfer.ResumePartialDownload.

A detailed result status is reported in this object's ULFileTransfer.AuthStatus, ULFileTransfer.AuthValue,

ULFileTransfer.FileAuthCode, ULFileTransfer.TransferredFile, ULFileTransfer.StreamErrorCode, and
ULFileTransfer.StreamErrorSystem values.

Errors may result in no data being sent to the listener.

UltraLite - .NET API Reference

368 PUBLIC UltraLite .NET API reference
Related Information

FileName property [page 374]

LocalPath property [page 376]
Stream property [page 378]
UserName property [page 382]
Password property [page 376]
Version property [page 382]
LocalFileName property [page 375]
AuthenticationParms property [page 372]
ResumePartialDownload property [page 378]
AuthStatus property [page 373]
AuthValue property [page 373]
FileAuthCode property [page 374]
TransferredFile property [page 381]
StreamErrorCode property [page 379]
StreamErrorSystem property [page 380]
StreamErrorCode property [page 379]
UploadFile() method [page 370]

4.1.18.3 UploadFile method

Upload the file specified by the properties of this object.

Overload list

Modifier and Type Overload name Description

public bool UploadFile() [page 370] Upload the file specified by the proper­
ties of this object.

public bool UploadFile(ULFileTransferProgressLis­ Upload the file specified by the proper­

tener) [page 371] ties of this object with progress events
posted to the specified listener.

In this section:

UploadFile() method [page 370]

Upload the file specified by the properties of this object.

UploadFile(ULFileTransferProgressListener) method [page 371]

Upload the file specified by the properties of this object with progress events posted to the specified
listener.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 369
4.1.18.3.1 UploadFile() method

Upload the file specified by the properties of this object.

 Syntax

Visual Basic

Public Function UploadFile () As Boolean

C#

public bool UploadFile ()

Returns

True if successful, false otherwise (check the ULFileTransfer.StreamErrorCode value and other status
properties for reason).

Remarks

The file specified by the ULFileTransfer.FileName value is uploaded to the MobiLink server from the
ULFileTransfer.LocalPath value using the ULFileTransfer.Stream, ULFileTransfer.UserName,
ULFileTransfer.Password, and ULFileTransfer.Version values.

A detailed result status is reported in this object's ULFileTransfer.AuthStatus, ULFileTransfer.AuthValue,

ULFileTransfer.FileAuthCode, ULFileTransfer.TransferredFile, ULFileTransfer.StreamErrorCode, and
ULFileTransfer.StreamErrorSystem values.

Related Information

UploadFile(ULFileTransferProgressListener) method [page 371]

FileName property [page 374]
LocalPath property [page 376]
Stream property [page 378]
UserName property [page 382]
Password property [page 376]
Version property [page 382]
LocalFileName property [page 375]
AuthenticationParms property [page 372]
ResumePartialDownload property [page 378]
AuthStatus property [page 373]

UltraLite - .NET API Reference

370 PUBLIC UltraLite .NET API reference
AuthValue property [page 373]
FileAuthCode property [page 374]
TransferredFile property [page 381]
StreamErrorCode property [page 379]
StreamErrorSystem property [page 380]
StreamErrorCode property [page 379]

4.1.18.3.2 UploadFile(ULFileTransferProgressListener)
method

Upload the file specified by the properties of this object with progress events posted to the specified listener.

 Syntax

Visual Basic

Public Function UploadFile (ByVal listener As

ULFileTransferProgressListener) As Boolean

C#

public bool UploadFile (ULFileTransferProgressListener listener)

Parameters

listener The object that receives file transfer progress events.

Returns

True if successful, false otherwise (check the ULFileTransfer.StreamErrorCode value and other status
properties for reason).

Remarks

The file specified by the ULFileTransfer.FileName value is uploaded to the MobiLink server from the
ULFileTransfer.LocalPath value using the ULFileTransfer.Stream, ULFileTransfer.UserName,
ULFileTransfer.Password, and ULFileTransfer.Version values.

A detailed result status is reported in this object's ULFileTransfer.AuthStatus, ULFileTransfer.AuthValue,

ULFileTransfer.FileAuthCode, ULFileTransfer.TransferredFile, ULFileTransfer.StreamErrorCode, and
ULFileTransfer.StreamErrorSystem values.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 371
Errors may result in no data being sent to the listener.

Related Information

UploadFile() method [page 370]

FileName property [page 374]
LocalPath property [page 376]
Stream property [page 378]
UserName property [page 382]
Password property [page 376]
Version property [page 382]
LocalFileName property [page 375]
AuthenticationParms property [page 372]
ResumePartialDownload property [page 378]
AuthStatus property [page 373]
AuthValue property [page 373]
FileAuthCode property [page 374]
TransferredFile property [page 381]
StreamErrorCode property [page 379]
StreamErrorSystem property [page 380]
StreamErrorCode property [page 379]

4.1.18.4 AuthenticationParms property

Specifies parameters for a custom user authentication script (MobiLink authenticate_parameters connection
event).

 Syntax

Visual Basic

Public Property AuthenticationParms As String()

C#

public unsafe String[] AuthenticationParms {get;set;}

Remarks

An array of strings, each containing an authentication parameter (null array entries result in a synchronization
error). The default is a null reference (Nothing in Visual Basic), meaning no authentication parameters.

UltraLite - .NET API Reference

372 PUBLIC UltraLite .NET API reference
Only the first 255 strings are used and each string should be no longer than the MobiLink server's limit for
authentication parameters (currently 4000 UTF8 bytes).

4.1.18.5 AuthStatus property

Returns the authorization status code for the last file transfer attempt.

 Syntax

Visual Basic

Public ReadOnly Property AuthStatus As ULAuthStatusCode

C#

public ULAuthStatusCode AuthStatus {get;}

Remarks

One of the ULAuthStatusCode values denoting the authorization status for the last file transfer attempt.

Related Information

ULAuthStatusCode enumeration [page 607]

4.1.18.6 AuthValue property

Returns the return value from custom user authentication synchronization scripts.

 Syntax

Visual Basic

Public ReadOnly Property AuthValue As Long

C#

public long AuthValue {get;}

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 373
Remarks

A long integer returned from custom user authentication synchronization scripts.

4.1.18.7 FileAuthCode property

Returns the return value from the authenticate_file_transfer script for the last file transfer attempt.

 Syntax

Visual Basic

Public ReadOnly Property FileAuthCode As UShort

C#

public ushort FileAuthCode {get;}

Remarks

An unsigned short integer returned from the authenticate_file_transfer script for the last file transfer attempt.

4.1.18.8 FileName property

Specifies the name of the file to download.

 Syntax

Visual Basic

Public Property FileName As String

C#

public string FileName {get;set;}

Remarks

A string specifying the name of the file as recognized by the MobiLink server. This property has no default
value, and must be explicitly set.

The FileName value is the name of the file on the server running MobiLink. MobiLink first searches for this file in
the UserName subdirectory and then in the root directory (the root directory is specified via the MobiLink

UltraLite - .NET API Reference

374 PUBLIC UltraLite .NET API reference
server's -ftr option). The FileName value must not include any drive or path information so that the MobiLink
server can find it. For example, "myfile.txt" is valid, but "somedir\myfile.txt", "..\myfile.txt", and "c:\myfile.txt"
are all invalid.

Related Information

LocalFileName property [page 375]

DownloadFile() method [page 366]
UploadFile() method [page 370]

4.1.18.9 LocalFileName property

Specifies the local file name for the downloaded file.

 Syntax

Visual Basic

Public Property LocalFileName As String

C#

public string LocalFileName {get;set;}

Remarks

A string specifying the local file name for the downloaded file. The FileName value is used if the value is a null
reference (Nothing in Visual Basic). The default is a null reference (Nothing in Visual Basic).

Related Information

FileName property [page 374]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 375
4.1.18.10 LocalPath property

Specifies where to download the file.

 Syntax

Visual Basic

Public Property LocalPath As String

C#

public string LocalPath {get;set;}

Remarks

A string specifying the local directory of the file. The default is a null reference (Nothing in Visual Basic).

The default local directory varies depending on the device's operating system:

● For Windows Mobile devices, if the LocalPath value is a null reference (Nothing in Visual Basic), the file is
stored in the root (\) directory.
● For desktop applications, if the LocalPath value is a null reference (Nothing in Visual Basic), the file is
stored in the current directory.

Related Information

DownloadFile() method [page 366]

UploadFile() method [page 370]

4.1.18.11 Password property

The MobiLink password for the user specified by the UserName value.

 Syntax

Visual Basic

Public Property Password As String

C#

public string Password {get;set;}

UltraLite - .NET API Reference

376 PUBLIC UltraLite .NET API reference
Remarks

A string specifying the MobiLink password. The default is a null reference (Nothing in Visual Basic), meaning no
password is specified.

The MobiLink user name and password are separate from any database user ID and password, and serve to
identify and authenticate the application to the MobiLink server.

Related Information

UserName property [page 382]

DownloadFile() method [page 366]
UploadFile() method [page 370]

4.1.18.12 RemoteKey property

The key that uniquely identifies the MobiLink client to the MobiLink server.

 Syntax

Visual Basic

Public Property RemoteKey As String

C#

public string RemoteKey {get;set;}

Remarks

A string specifying the remote key. This property has no default value, and must be explicitly set.

The MobiLink server passes this value to various scripts to uniquely identify this client.

Related Information

DownloadFile() method [page 366]

UploadFile() method [page 370]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 377
4.1.18.13 ResumePartialDownload property

Specifies whether to resume or discard a previous partial download.

 Syntax

Visual Basic

Public Property ResumePartialDownload As Boolean

C#

public bool ResumePartialDownload {get;set;}

Remarks

True to resume a previous partial download, false to discard a previous partial download. The default is false.

UltraLite.NET can use the ULFileTransferListener object to restart downloads that fail because of
communication errors or user aborts. UltraLite.NET processes the download as it is received. If a download is
interrupted, then the partially download file is retained and can be resumed during the next file transfer.

If the file has been updated on the server, a partial download is discarded and a new download starts.

Related Information

DownloadFile() method [page 366]

UploadFile() method [page 370]

4.1.18.14 Stream property

Specifies the MobiLink synchronization stream to use for the file transfer.

 Syntax

Visual Basic

Public Property Stream As ULStreamType

C#

public ULStreamType Stream {get;set;}

UltraLite - .NET API Reference

378 PUBLIC UltraLite .NET API reference
Remarks

One of the ULStreamType values specifying the type of synchronization stream to use. The default is the
ULStreamType.TCPIP value.

Most synchronization streams require parameters to identify the MobiLink server address and control other
behavior. These parameters are supplied by the ULFileTransfer.StreamParms value.

If the stream type is set to a value that is invalid for the platform, the stream type is set to the
ULStreamType.TCPIP value.

Related Information

ULStreamType enumeration [page 615]

StreamParms property [page 380]
DownloadFile() method [page 366]
UploadFile() method [page 370]

4.1.18.15 StreamErrorCode property

Returns the error reported by the stream itself for the last file transfer attempt.

 Syntax

Visual Basic

Public ReadOnly Property StreamErrorCode As ULStreamErrorCode

C#

public ULStreamErrorCode StreamErrorCode {get;}

Remarks

One of the ULStreamErrorCode values denoting the error reported by the stream itself. The
ULStreamErrorCode.NONE value if no error occurred.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 379
4.1.18.16 StreamErrorSystem property

Returns the stream error system­specific code.

 Syntax

Visual Basic

Public ReadOnly Property StreamErrorSystem As Integer

C#

public int StreamErrorSystem {get;}

Remarks

An integer denoting the stream error system­specific code.

4.1.18.17 StreamParms property

Specifies the parameters to configure the synchronization stream.

 Syntax

Visual Basic

Public Property StreamParms As String

C#

public string StreamParms {get;set;}

Remarks

A string, in the form of a semicolon-separated list of keyword=value pairs, specifying the parameters for the
stream. The default is a null reference. (Nothing in Visual Basic)

The StreamParms value is a string containing all the parameters used for synchronization streams. Parameters
are specified as a semicolon-separated list of name=value pairs ("param1=value1;param2=value2").

UltraLite - .NET API Reference

380 PUBLIC UltraLite .NET API reference
Related Information

Stream property [page 378]

DownloadFile() method [page 366]
UploadFile() method [page 370]
ULStreamType enumeration [page 615]

4.1.18.18 TransferredFile property

Checks whether the file was actually downloaded during the last file transfer attempt.

 Syntax

Visual Basic

Public ReadOnly Property TransferredFile As Boolean

C#

public bool TransferredFile {get;}

Remarks

True if the file was downloaded, false otherwise.

If the file is already up-to-date when the DownloadFile or UploadFile method is invoked, it returns true, but
TransferredFile is false. If an error occurs and the DownloadFile or UploadFile method returns false, then
TransferredFile is false.

Related Information

DownloadFile() method [page 366]

UploadFile() method [page 370]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 381
4.1.18.19 UserName property

The user name that identifies the MobiLink client to the MobiLink server.

 Syntax

Visual Basic

Public Property UserName As String

C#

public string UserName {get;set;}

Remarks

A string specifying the user name. This property has no default value, and must be explicitly set.

The MobiLink server uses this value to locate the file to download. The MobiLink user name and password are
separate from any database user ID and password, and serve to identify and authenticate the application to the
MobiLink server.

Related Information

Password property [page 376]

DownloadFile() method [page 366]
UploadFile() method [page 370]

4.1.18.20 Version property

Specifies which synchronization script to use.

 Syntax

Visual Basic

Public Property Version As String

C#

public string Version {get;set;}

UltraLite - .NET API Reference

382 PUBLIC UltraLite .NET API reference
Remarks

A string specifying the version of the synchronization script to use. This property has no default value, and
must be explicitly set.

Each synchronization script in the consolidated database is marked with a version string. The version string
allows an UltraLite application to choose from a set of synchronization scripts.

Related Information

DownloadFile() method [page 366]

UploadFile() method [page 370]

4.1.19 ULFileTransferProgressData class

UL Ext: Returns file transfer progress monitoring data.

 Syntax

Visual Basic

Public Class ULFileTransferProgressData

C#

public class ULFileTransferProgressData

Members

All members of ULFileTransferProgressData, including inherited members.

Variables

Modifier and Type Variable Description

public const int FLAG_IS_BLOCKING A flag indicating that the file transfer is
blocked awaiting a response from the
MobiLink server.

Properties

Modifier and Type Property Description

public ulong BytesReceived [page 384] Returns the number of bytes received
so far.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 383
Modifier and Type Property Description

public ulong FileSize [page 385] Returns the size of the file being trans­
ferred.

public int Flags [page 385] Returns the current file transfer flags
indicating additional information relat­
ing to the current state.

public ulong ResumedAtSize [page 386] Returns the point in the file where the
transfer was resumed.

In this section:

BytesReceived property [page 384]

Returns the number of bytes received so far.

FileSize property [page 385]

Returns the size of the file being transferred.

Flags property [page 385]

Returns the current file transfer flags indicating additional information relating to the current state.

ResumedAtSize property [page 386]

Returns the point in the file where the transfer was resumed.

Related Information

ULFileTransferProgressListener interface [page 386]

4.1.19.1 BytesReceived property

Returns the number of bytes received so far.

 Syntax

Visual Basic

Public ReadOnly Property BytesReceived As ULong

C#

public ulong BytesReceived {get;}

Remarks

The number of bytes received so far.

UltraLite - .NET API Reference

384 PUBLIC UltraLite .NET API reference
4.1.19.2 FileSize property

Returns the size of the file being transferred.

 Syntax

Visual Basic

Public ReadOnly Property FileSize As ULong

C#

public ulong FileSize {get;}

Remarks

The size of the file in bytes.

4.1.19.3 Flags property

Returns the current file transfer flags indicating additional information relating to the current state.

 Syntax

Visual Basic

Public ReadOnly Property Flags As Integer

C#

public int Flags {get;}

Remarks

An integer containing a combination of flags or'ed together.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 385
4.1.19.4 ResumedAtSize property

Returns the point in the file where the transfer was resumed.

 Syntax

Visual Basic

Public ReadOnly Property ResumedAtSize As ULong

C#

public ulong ResumedAtSize {get;}

Remarks

The number of bytes transferred previously.

4.1.20 ULFileTransferProgressListener interface

UL Ext: The listener interface for receiving file transfer progress events.

 Syntax

Visual Basic

Public Interface ULFileTransferProgressListener

C#

public interface ULFileTransferProgressListener

Members

All members of ULFileTransferProgressListener, including inherited members.

Methods

Modifier and Type Method Description

public bool FileTransferProgressed(ULFileTransfer­ Invoked during a file transfer to inform

ProgressData) [page 387] the user of progress.

In this section:

UltraLite - .NET API Reference

386 PUBLIC UltraLite .NET API reference
 FileTransferProgressed(ULFileTransferProgressData) method [page 387]
Invoked during a file transfer to inform the user of progress.

Related Information

DownloadFile(ULFileTransferProgressListener) method [page 368]

4.1.20.1 FileTransferProgressed(ULFileTransferProgressData)
method

Invoked during a file transfer to inform the user of progress.

 Syntax

Visual Basic

Public Function FileTransferProgressed (ByVal data As

ULFileTransferProgressData) As Boolean

C#

public bool FileTransferProgressed (ULFileTransferProgressData data)

Parameters

data A ULFileTransferProgressData object containing the latest file transfer progress data.

Returns

This method should return true to cancel the transfer or return false to continue.

Remarks

This method should return true to cancel the transfer or return false to continue.

No UltraLite.NET API methods should be invoked during a FileTransferProgressed call.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 387
Related Information

ULFileTransferProgressData class [page 383]

4.1.21 ULIndexSchema class

UL Ext: Represents the schema of an UltraLite table index.

 Syntax

Visual Basic

Public NotInheritable Class ULIndexSchema

C#

public sealed class ULIndexSchema

Members

All members of ULIndexSchema, including inherited members.

Methods

Modifier and Type Method Description

public void Close() [page 390] Closes the ULIndexSchema object.

public unsafe string GetColumnName(short) [page 390] Returns the name of the colOrdinalInIn­
dex 'th column in this index.

public unsafe bool IsColumnDescending(string) [page Checks whether the named column is
391] used in descending order by the index.

Properties

Modifier and Type Property Description

public unsafe short ColumnCount [page 392] Returns the number of columns in the
index.

public unsafe bool IsForeignKey [page 393] Checks whether the index is a foreign
key.

public unsafe bool IsForeignKeyCheckOnCommit [page Checks whether referential integrity for
393] the foreign key is performed on com­
mits or on inserts and updates.

public unsafe bool IsForeignKeyNullable [page 394] Checks whether the foreign key is nulla­
ble.

UltraLite - .NET API Reference

388 PUBLIC UltraLite .NET API reference
 Modifier and Type Property Description

public bool IsOpen [page 394] Determines whether the index schema
is open or closed.

public unsafe bool IsPrimaryKey [page 395] Checks whether the index is the pri­
mary key.

public unsafe bool IsUniqueIndex [page 395] Checks whether the index is unique.

public unsafe bool IsUniqueKey [page 396] Checks whether the index is a unique
key.

public unsafe string Name [page 396] Returns the name of the index.

public unsafe string ReferencedIndexName [page 397] The name of the referenced primary in­
dex if the index is a foreign key.

public unsafe string ReferencedTableName [page 397] The name of the referenced primary ta­
ble if the index is a foreign key.

Remarks

There is no constructor for this class. Index schemas are created using the ULTableSchema.PrimaryKey,
ULTableSchema.GetIndex(string), and ULTableSchema.GetOptimalIndex(int) methods.

In this section:

Close() method [page 390]

Closes the ULIndexSchema object.

GetColumnName(short) method [page 390]

Returns the name of the colOrdinalInIndex 'th column in this index.

IsColumnDescending(string) method [page 391]

Checks whether the named column is used in descending order by the index.

ColumnCount property [page 392]

Returns the number of columns in the index.

IsForeignKey property [page 393]

Checks whether the index is a foreign key.

IsForeignKeyCheckOnCommit property [page 393]

Checks whether referential integrity for the foreign key is performed on commits or on inserts and
updates.

IsForeignKeyNullable property [page 394]

Checks whether the foreign key is nullable.

IsOpen property [page 394]

Determines whether the index schema is open or closed.

IsPrimaryKey property [page 395]

Checks whether the index is the primary key.

IsUniqueIndex property [page 395]

Checks whether the index is unique.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 389
 IsUniqueKey property [page 396]
Checks whether the index is a unique key.

Name property [page 396]

Returns the name of the index.

ReferencedIndexName property [page 397]

The name of the referenced primary index if the index is a foreign key.

ReferencedTableName property [page 397]

The name of the referenced primary table if the index is a foreign key.

Related Information

PrimaryKey property [page 597]

GetIndex(string) method [page 584]
GetOptimalIndex(int) method [page 585]
ULTableSchema class [page 578]

4.1.21.1 Close() method

Closes the ULIndexSchema object.

 Syntax

Visual Basic

Public Sub Close ()

C#

public void Close ()

4.1.21.2 GetColumnName(short) method

Returns the name of the colOrdinalInIndex 'th column in this index.

 Syntax

Visual Basic

Public Function GetColumnName (ByVal colOrdinalInIndex As Short) As String

C#

public unsafe string GetColumnName (short colOrdinalInIndex)

UltraLite - .NET API Reference

390 PUBLIC UltraLite .NET API reference
Parameters

colOrdinalInIndex The ordinal of the desired column in the index. The value must be in the range
[1,ColumnCount].

Returns

The name of the column.

Exceptions

ULException class A SQL error occurred.

Remarks

Column ordinals and count may change during a schema upgrade. Column ordinals from an index are different
than the column IDs in a table or another index, even if they refer to the same physical column in a particular
table.

Related Information

ColumnCount property [page 392]

ColumnCount property [page 392]

4.1.21.3 IsColumnDescending(string) method

Checks whether the named column is used in descending order by the index.

 Syntax

Visual Basic

Public Function IsColumnDescending (ByVal name As String) As Boolean

C#

public unsafe bool IsColumnDescending (string name)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 391
Parameters

name The name of the column.

Returns

True if the column is used in descending order, false if the column is used in ascending order.

Exceptions

ULException class A SQL error occurred.

Related Information

GetColumnName(short) method [page 390]

ColumnCount property [page 392]

4.1.21.4 ColumnCount property

Returns the number of columns in the index.

 Syntax

Visual Basic

Public ReadOnly Property ColumnCount As Short

C#

public unsafe short ColumnCount {get;}

Remarks

The number of columns in the index.

Column ordinals in indexes range from 1 to the ColumnCount value, inclusively.

UltraLite - .NET API Reference

392 PUBLIC UltraLite .NET API reference
Column ordinals and count may change during a schema upgrade. Column ordinals from an index are different
than the column IDs in a table or another index, even if they refer to the same physical column in a particular
table.

4.1.21.5 IsForeignKey property

Checks whether the index is a foreign key.

 Syntax

Visual Basic

Public ReadOnly Property IsForeignKey As Boolean

C#

public unsafe bool IsForeignKey {get;}

Remarks

True if the index is the foreign key, false if the index is not the foreign key.

Columns in a foreign key may reference another table's non-null, unique index.

4.1.21.6 IsForeignKeyCheckOnCommit property

Checks whether referential integrity for the foreign key is performed on commits or on inserts and updates.

 Syntax

Visual Basic

Public ReadOnly Property IsForeignKeyCheckOnCommit As Boolean

C#

public unsafe bool IsForeignKeyCheckOnCommit {get;}

Remarks

True if referential integrity is checked on commits, false if it is checked on inserts and updates.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 393
Related Information

IsForeignKey property [page 393]

4.1.21.7 IsForeignKeyNullable property

Checks whether the foreign key is nullable.

 Syntax

Visual Basic

Public ReadOnly Property IsForeignKeyNullable As Boolean

C#

public unsafe bool IsForeignKeyNullable {get;}

Remarks

True if the foreign key is nullable, false if the foreign key is not nullable.

Related Information

IsForeignKey property [page 393]

4.1.21.8 IsOpen property

Determines whether the index schema is open or closed.

 Syntax

Visual Basic

Public ReadOnly Property IsOpen As Boolean

C#

public bool IsOpen {get;}

UltraLite - .NET API Reference

394 PUBLIC UltraLite .NET API reference
Remarks

True if the index schema is open, otherwise false.

4.1.21.9 IsPrimaryKey property

Checks whether the index is the primary key.

 Syntax

Visual Basic

Public ReadOnly Property IsPrimaryKey As Boolean

C#

public unsafe bool IsPrimaryKey {get;}

Remarks

True if the index is the primary key, false if the index is not the primary key.

Columns in the primary key may not be null.

4.1.21.10 IsUniqueIndex property

Checks whether the index is unique.

 Syntax

Visual Basic

Public ReadOnly Property IsUniqueIndex As Boolean

C#

public unsafe bool IsUniqueIndex {get;}

Remarks

True if the index is unique, false if the index is not unique.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 395
Columns in a unique index may be null.

4.1.21.11 IsUniqueKey property

Checks whether the index is a unique key.

 Syntax

Visual Basic

Public ReadOnly Property IsUniqueKey As Boolean

C#

public unsafe bool IsUniqueKey {get;}

Remarks

True if the index is a unique key, false if the index is not a unique key.

Columns in a unique key may not be null.

4.1.21.12 Name property

Returns the name of the index.

 Syntax

Visual Basic

Public ReadOnly Property Name As String

C#

public unsafe string Name {get;}

Remarks

A string specifying the name of the index.

UltraLite - .NET API Reference

396 PUBLIC UltraLite .NET API reference
4.1.21.13 ReferencedIndexName property

The name of the referenced primary index if the index is a foreign key.

 Syntax

Visual Basic

Public ReadOnly Property ReferencedIndexName As String

C#

public unsafe string ReferencedIndexName {get;}

Remarks

A string specifying the name of the referenced primary index.

Related Information

IsForeignKey property [page 393]

4.1.21.14 ReferencedTableName property

The name of the referenced primary table if the index is a foreign key.

 Syntax

Visual Basic

Public ReadOnly Property ReferencedTableName As String

C#

public unsafe string ReferencedTableName {get;}

Remarks

A string specifying the name of the referenced primary table.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 397
Related Information

IsForeignKey property [page 393]

4.1.22 ULInfoMessageEventArgs class

Provides data for the ULConnection.InfoMessage event.

 Syntax

Visual Basic

Public NotInheritable Class ULInfoMessageEventArgs Inherits

System.EventArgs

C#

public sealed class ULInfoMessageEventArgs : System.EventArgs

Members

All members of ULInfoMessageEventArgs, including inherited members.

Methods

Modifier and Type Method Description

public override string ToString() [page 399] The string representation of the ULCon­
nection.InfoMessage event.

Properties

Modifier and Type Property Description

public string Message [page 400] The informational or warning message

string returned by the database.

public ULSQLCode NativeError [page 400] The SQLCODE corresponding to the in­
formational message or warning re­
turned by the database.

public string Source [page 401] The name of the ADO.NET data pro­
vider returning the message.

In this section:

ToString() method [page 399]

The string representation of the ULConnection.InfoMessage event.

Message property [page 400]

UltraLite - .NET API Reference

398 PUBLIC UltraLite .NET API reference
 The informational or warning message string returned by the database.

NativeError property [page 400]

The SQLCODE corresponding to the informational message or warning returned by the database.

Source property [page 401]

The name of the ADO.NET data provider returning the message.

Related Information

InfoMessage event [page 213]

4.1.22.1 ToString() method

The string representation of the ULConnection.InfoMessage event.

 Syntax

Visual Basic

Public Overrides Function ToString () As String

C#

public override string ToString ()

Returns

The informational or warning message string.

Remarks

A string representation of the ULConnection.InfoMessage event.

Related Information

InfoMessage event [page 213]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 399
4.1.22.2 Message property

The informational or warning message string returned by the database.

 Syntax

Visual Basic

Public ReadOnly Property Message As String

C#

public string Message {get;}

Remarks

A string containing the informational or warning message.

4.1.22.3 NativeError property

The SQLCODE corresponding to the informational message or warning returned by the database.

 Syntax

Visual Basic

Public ReadOnly Property NativeError As ULSQLCode

C#

public ULSQLCode NativeError {get;}

Remarks

An informational or warning ULSQLCode value.

UltraLite - .NET API Reference

400 PUBLIC UltraLite .NET API reference
4.1.22.4 Source property

The name of the ADO.NET data provider returning the message.

 Syntax

Visual Basic

Public ReadOnly Property Source As String

C#

public string Source {get;}

Remarks

The string "UltraLite.NET Data Provider".

4.1.23 ULMetaDataCollectionNames class

Provides a list of constants for use with the ULConnection.GetSchema(String,String[]) method to retrieve
metadata collections.

 Syntax

Visual Basic

Public NotInheritable Class ULMetaDataCollectionNames

C#

public sealed class ULMetaDataCollectionNames

Members

All members of ULMetaDataCollectionNames, including inherited members.

Properties

Modifier and Type Property Description

public string Columns [page 403] Provides a constant for use with the UL­
Connection.GetSchema(String)
method that represents the Columns
collection.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 401
Modifier and Type Property Description

public string DataSourceInformation [page 404] Provides a constant for use with the UL­
Connection.GetSchema(String)
method that represents the DataSour­
ceInformation collection.

public string DataTypes [page 405] Provides a constant for use with the UL­
Connection.GetSchema(String)
method that represents the DataTypes
collection.

public string ForeignKeys [page 406] Provides a constant for use with the UL­
Connection.GetSchema(String)
method that represents the Foreign­
Keys collection.

public string IndexColumns [page 407] Provides a constant for use with the UL­
Connection.GetSchema(String)
method that represents the IndexCol­
umns collection.

public string Indexes [page 408] Provides a constant for use with the UL­
Connection.GetSchema(String)
method that represents the Indexes col­
lection.

public string MetaDataCollections [page 409] Provides a constant for use with the UL­
Connection.GetSchema(String)
method that represents the MetaData­
Collections collection.

public string Publications [page 410] Provides a constant for use with the UL­
Connection.GetSchema(String)
method that represents the Publica­
tions collection.

public string ReservedWords [page 411] Provides a constant for use with the UL­
Connection.GetSchema(String)
method that represents the Reserved­
Words collection.

public string Restrictions [page 412] Provides a constant for use with the UL­
Connection.GetSchema(String)
method that represents the Restric­
tions collection.

public string Tables [page 413] Provides a constant for use with the UL­
Connection.GetSchema(String)
method that represents the Tables col­
lection.

In this section:

Columns property [page 403]

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
Columns collection.

DataSourceInformation property [page 404]

UltraLite - .NET API Reference

402 PUBLIC UltraLite .NET API reference
 Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
DataSourceInformation collection.

DataTypes property [page 405]

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
DataTypes collection.

ForeignKeys property [page 406]

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
ForeignKeys collection.

IndexColumns property [page 407]

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
IndexColumns collection.

Indexes property [page 408]

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
Indexes collection.

MetaDataCollections property [page 409]

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
MetaDataCollections collection.

Publications property [page 410]

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
Publications collection.

ReservedWords property [page 411]

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
ReservedWords collection.

Restrictions property [page 412]

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
Restrictions collection.

Tables property [page 413]

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
Tables collection.

4.1.23.1 Columns property

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the Columns
collection.

 Syntax

Visual Basic

Public Shared ReadOnly Property Columns As String

C#

public string Columns {get;}

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 403
Remarks

A string representing the name of the Columns collection.

 Example

The following code fills a DataTable object with the Columns collection.

' Visual Basic

Dim schema As DataTable = _
conn.GetSchema( ULMetaDataCollectionNames.Columns )

The following code is the C# language equivalent:

// C#
DataTable schema =
conn.GetSchema( ULMetaDataCollectionNames.Columns );

Related Information

GetSchema(string) method [page 188]

4.1.23.2 DataSourceInformation property

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
DataSourceInformation collection.

 Syntax

Visual Basic

Public Shared ReadOnly Property DataSourceInformation As String

C#

public string DataSourceInformation {get;}

Remarks

A string representing the name of the DataSourceInformation collection.

 Example

The following code fills a DataTable object with the DataSourceInformation collection.

' Visual Basic

UltraLite - .NET API Reference

404 PUBLIC UltraLite .NET API reference
 Dim schema As DataTable = _
conn.GetSchema( ULMetaDataCollectionNames.DataSourceInformation )

The following code is the C# language equivalent:

// C#
DataTable schema =
conn.GetSchema( ULMetaDataCollectionNames.DataSourceInformation );

Related Information

GetSchema(string) method [page 188]

4.1.23.3 DataTypes property

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the DataTypes
collection.

 Syntax

Visual Basic

Public Shared ReadOnly Property DataTypes As String

C#

public string DataTypes {get;}

Remarks

A string representing the name of the DataTypes collection.

 Example

The following code fills a DataTable object with the DataTypes collection.

' Visual Basic

Dim schema As DataTable = _
conn.GetSchema( ULMetaDataCollectionNames.DataTypes )

The following code is the C# language equivalent:

// C#
DataTable schema =
conn.GetSchema( ULMetaDataCollectionNames.DataTypes );

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 405
Related Information

GetSchema(string) method [page 188]

4.1.23.4 ForeignKeys property

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
ForeignKeys collection.

 Syntax

Visual Basic

Public Shared ReadOnly Property ForeignKeys As String

C#

public string ForeignKeys {get;}

Remarks

A string representing the name of the ForeignKeys collection.

 Example

The following code fills a DataTable object with the ForeignKeys collection.

' Visual Basic

Dim schema As DataTable = _
conn.GetSchema( ULMetaDataCollectionNames.ForeignKeys )

The following code is the C# language equivalent:

// C#
DataTable schema =
conn.GetSchema( ULMetaDataCollectionNames.ForeignKeys );

Related Information

GetSchema(string) method [page 188]

UltraLite - .NET API Reference

406 PUBLIC UltraLite .NET API reference
4.1.23.5 IndexColumns property

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
IndexColumns collection.

 Syntax

Visual Basic

Public Shared ReadOnly Property IndexColumns As String

C#

public string IndexColumns {get;}

Remarks

A string representing the name of the IndexColumns collection.

 Example

The following code fills a DataTable object with the IndexColumns collection.

' Visual Basic

Dim schema As DataTable = _
conn.GetSchema( ULMetaDataCollectionNames.IndexColumns )

The following code is the C# language equivalent:

// C#
DataTable schema =
conn.GetSchema( ULMetaDataCollectionNames.IndexColumns );

Related Information

GetSchema(string) method [page 188]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 407
4.1.23.6 Indexes property

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the Indexes
collection.

 Syntax

Visual Basic

Public Shared ReadOnly Property Indexes As String

C#

public string Indexes {get;}

Remarks

A string representing the name of the Indexes collection.

 Example

The following code fills a DataTable object with the Indexes collection.

' Visual Basic

Dim schema As DataTable = _
conn.GetSchema( ULMetaDataCollectionNames.Indexes )

The following code is the C# language equivalent:

// C#
DataTable schema =
conn.GetSchema( ULMetaDataCollectionNames.Indexes );

Related Information

GetSchema(string) method [page 188]

UltraLite - .NET API Reference

408 PUBLIC UltraLite .NET API reference
4.1.23.7 MetaDataCollections property

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
MetaDataCollections collection.

 Syntax

Visual Basic

Public Shared ReadOnly Property MetaDataCollections As String

C#

public string MetaDataCollections {get;}

Remarks

A string representing the name of the MetaDataCollections collection.

 Example

The following code fills a DataTable object with the MetaDataCollections collection.

' Visual Basic

Dim schema As DataTable = _
conn.GetSchema( ULMetaDataCollectionNames.MetaDataCollections )

The following code is the C# language equivalent:

// C#
DataTable schema =
conn.GetSchema( ULMetaDataCollectionNames.MetaDataCollections );

Related Information

GetSchema(string) method [page 188]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 409
4.1.23.8 Publications property

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
Publications collection.

 Syntax

Visual Basic

Public Shared ReadOnly Property Publications As String

C#

public string Publications {get;}

Remarks

A string representing the name of the Publications collection.

 Example

The following code fills a DataTable object with the Publications collection.

' Visual Basic

Dim schema As DataTable = _
conn.GetSchema( ULMetaDataCollectionNames.Publications )

The following code is the C# language equivalent:

// C#
DataTable schema =
conn.GetSchema( ULMetaDataCollectionNames.Publications );

Related Information

GetSchema(string) method [page 188]

UltraLite - .NET API Reference

410 PUBLIC UltraLite .NET API reference
4.1.23.9 ReservedWords property

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
ReservedWords collection.

 Syntax

Visual Basic

Public Shared ReadOnly Property ReservedWords As String

C#

public string ReservedWords {get;}

Remarks

A string representing the name of the ReservedWords collection.

 Example

The following code fills a DataTable object with the ReservedWords collection.

' Visual Basic

Dim schema As DataTable = _
conn.GetSchema( ULMetaDataCollectionNames.ReservedWords )

The following code is the C# language equivalent:

// C#
DataTable schema =
conn.GetSchema( ULMetaDataCollectionNames.ReservedWords );

Related Information

GetSchema(string) method [page 188]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 411
4.1.23.10 Restrictions property

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the
Restrictions collection.

 Syntax

Visual Basic

Public Shared ReadOnly Property Restrictions As String

C#

public string Restrictions {get;}

Remarks

A string representing the name of the Restrictions collection.

 Example

The following code fills a DataTable object with the Restrictions collection.

' Visual Basic

Dim schema As DataTable = _
conn.GetSchema( ULMetaDataCollectionNames.Restrictions )

The following code is the C# language equivalent:

// C#
DataTable schema =
conn.GetSchema( ULMetaDataCollectionNames.Restrictions );

Related Information

GetSchema(string) method [page 188]

UltraLite - .NET API Reference

412 PUBLIC UltraLite .NET API reference
4.1.23.11 Tables property

Provides a constant for use with the ULConnection.GetSchema(String) method that represents the Tables
collection.

 Syntax

Visual Basic

Public Shared ReadOnly Property Tables As String

C#

public string Tables {get;}

Remarks

A string representing the name of the Tables collection.

 Example

The following code fills a DataTable object with the Tables collection.

' Visual Basic

Dim schema As DataTable = _
conn.GetSchema( ULMetaDataCollectionNames.Tables )
// C#
DataTable schema =
conn.GetSchema( ULMetaDataCollectionNames.Tables );

Related Information

GetSchema(string) method [page 188]

4.1.24 ULParameter class

Represents a parameter to a ULCommand object.

 Syntax

Visual Basic

Public NotInheritable Class ULParameter Inherits

System.Data.Common.DbParameter Implements System.ICloneable

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 413
 C#

public sealed class ULParameter : System.Data.Common.DbParameter,

System.ICloneable

Members

All members of ULParameter, including inherited members.

Constructors

Modifier and Type Constructor Description

public ULParameter [page 417] Initializes a ULParameter object with

null (Nothing in Visual Basic) as its
value.

Methods

Modifier and Type Method Description

public override void ResetDbType() [page 424] This method is not supported in Ultra­
Lite.NET.

public override string ToString() [page 425] Returns the string representation of
this instance.

Properties

Modifier and Type Property Description

public override DbType DbType [page 425] Specifies the System.Data.DbType for
the parameter.

public override ParameterDirection Direction [page 426] A value indicating whether the parame­
ter is input-only, output-only, bidirec­
tional, or a stored procedure return
value parameter.

public override bool IsNullable [page 426] Specifies whether the parameter ac­
cepts null values.

public int Offset [page 427] Specifies the offset to the ULParame­
ter.Value.

public override string ParameterName [page 428] Specifies the name of the parameter.

public byte Precision [page 428] Specifies the maximum number of dig­
its used to represent the ULParame­
ter.Value property.

public byte Scale [page 429] Specifies the number of decimal places
to which ULParameter.Value property is
resolved.

public override int Size [page 430] Specifies the maximum size of the data
within the column.

UltraLite - .NET API Reference

414 PUBLIC UltraLite .NET API reference
 Modifier and Type Property Description

public override string SourceColumn [page 430] Specifies the name of the source col­
umn mapped to the DataSet object and
used for loading or returning the value.

public override bool SourceColumnNullMapping [page 431] Specifies whether the source column is
nullable.

public override DataRowVersion SourceVersion [page 432] The System.Data.DataRowVersion

value to use when loading the ULPara­
meter.Value property.

public ULDbType ULDbType [page 432] Specifies the Sap.Data.UltraLite.ULDb­

Type for the parameter.

public override object Value [page 433] Specifies the value of the parameter.

Remarks

A ULParameter object can be created directly using one of its many constructors, or using the
ULCommand.CreateParameter method. Because of the special treatment of the 0 and 0.0 constants and the
way overloaded methods are resolved, it is highly recommended that you explicitly cast constant values to the
object type when using the ULParameter(string,object) constructor. For example:

' Visual Basic

Dim p As ULParameter = New ULParameter( "", CType( 0, Object ) )

The following code is the C# language equivalent:

// C#
ULParameter p = new ULParameter( "", (object)0 );

Parameters (including those created by the ULCommand.CreateParameter method) must be added to a

ULCommand.Parameters collection to be used. All parameters are treated as positional parameters and are
used by a command in the order that they were added.

In UltraLite.NET, parameters can only be used as IN parameters and all mapping information is ignored. Only
the ULParameter.Value property is important.

In this section:

ULParameter constructor [page 417]

Initializes a ULParameter object with null (Nothing in Visual Basic) as its value.

ResetDbType() method [page 424]

This method is not supported in UltraLite.NET.

ToString() method [page 425]

Returns the string representation of this instance.

DbType property [page 425]

Specifies the System.Data.DbType for the parameter.

Direction property [page 426]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 415
 A value indicating whether the parameter is input-only, output-only, bidirectional, or a stored procedure
return value parameter.

IsNullable property [page 426]

Specifies whether the parameter accepts null values.

Offset property [page 427]

Specifies the offset to the ULParameter.Value.

ParameterName property [page 428]

Specifies the name of the parameter.

Precision property [page 428]

Specifies the maximum number of digits used to represent the ULParameter.Value property.

Scale property [page 429]

Specifies the number of decimal places to which ULParameter.Value property is resolved.

Size property [page 430]

Specifies the maximum size of the data within the column.

SourceColumn property [page 430]

Specifies the name of the source column mapped to the DataSet object and used for loading or
returning the value.

SourceColumnNullMapping property [page 431]

Specifies whether the source column is nullable.

SourceVersion property [page 432]

The System.Data.DataRowVersion value to use when loading the ULParameter.Value property.

ULDbType property [page 432]

Specifies the Sap.Data.UltraLite.ULDbType for the parameter.

Value property [page 433]

Specifies the value of the parameter.

Related Information

ULCommand class [page 88]

CreateParameter() method [page 106]
ULParameter(string, object) constructor [page 423]
Parameters property [page 132]
Value property [page 433]

UltraLite - .NET API Reference

416 PUBLIC UltraLite .NET API reference
4.1.24.1 ULParameter constructor

Initializes a ULParameter object with null (Nothing in Visual Basic) as its value.

Overload list

Modifier and Type Overload name Description

public ULParameter() [page 418] Initializes a ULParameter object with

null (Nothing in Visual Basic) as its
value.

public ULParameter(string, ULDbType) [page Initializes a ULParameter object with

418] the specified parameter name and data
type.

public ULParameter(string, ULDbType, int) Initializes a ULParameter object with

[page 419] the specified parameter name and data
type.

public ULParameter(string, ULDbType, int, Pa­ Initializes a ULParameter object with

rameterDirection, bool, byte, byte, the specified parameter name, data
string, DataRowVersion, object) [page type, length, direction, nullability, nu­
420] meric precision, numeric scale, source
column, source version, and value.

public ULParameter(string, ULDbType, int, Initializes a ULParameter object with

string) [page 422] the specified parameter name, data
type, and length.

public ULParameter(string, object) [page 423] Initializes a ULParameter object with

the specified parameter name and
value.

In this section:

ULParameter() constructor [page 418]

Initializes a ULParameter object with null (Nothing in Visual Basic) as its value.

ULParameter(string, ULDbType) constructor [page 418]

Initializes a ULParameter object with the specified parameter name and data type.

ULParameter(string, ULDbType, int) constructor [page 419]

Initializes a ULParameter object with the specified parameter name and data type.

ULParameter(string, ULDbType, int, ParameterDirection, bool, byte, byte, string, DataRowVersion, object)
constructor [page 420]
Initializes a ULParameter object with the specified parameter name, data type, length, direction,
nullability, numeric precision, numeric scale, source column, source version, and value.

ULParameter(string, ULDbType, int, string) constructor [page 422]

Initializes a ULParameter object with the specified parameter name, data type, and length.

ULParameter(string, object) constructor [page 423]

Initializes a ULParameter object with the specified parameter name and value.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 417
4.1.24.1.1 ULParameter() constructor

Initializes a ULParameter object with null (Nothing in Visual Basic) as its value.

 Syntax

Visual Basic

Public Sub ULParameter ()

C#

public ULParameter ()

 Example

The following code creates a ULParameter value of 3 and adds it to a ULCommand object named cmd.

' Visual Basic

Dim p As ULParameter = New ULParameter
p.Value = 3
cmd.Parameters.Add( p )

The following code is the C# language equivalent:

// C#
ULParameter p = new ULParameter();
p.Value = 3;
cmd.Parameters.Add( p );

Related Information

Value property [page 433]

ULParameter(string, object) constructor [page 423]
ULCommand class [page 88]

4.1.24.1.2 ULParameter(string, ULDbType) constructor

Initializes a ULParameter object with the specified parameter name and data type.

 Syntax

Visual Basic

Public Sub ULParameter (

ByVal parameterName As String,
ByVal dbType As ULDbType
)

UltraLite - .NET API Reference

418 PUBLIC UltraLite .NET API reference
 C#

public ULParameter (
string parameterName,
ULDbType dbType
)

Parameters

parameterName The name of the parameter. For unnamed parameters, use an empty string ("") or a null
reference (Nothing in Visual Basic) for this value. In UltraLite.NET, parameter names are not used by the
ULCommand object.
dbType One of the Sap.Data.UltraLite.ULDbType values.

Remarks

This constructor is not recommended; it is provided for compatibility with other data providers.

In UltraLite.NET parameters can only be used as IN parameters and all mapping information is ignored. Only
the ULParameter.Value property is important.

Related Information

ULParameter() constructor [page 418]

ULParameter(string, object) constructor [page 423]
Value property [page 433]
ULCommand class [page 88]

4.1.24.1.3 ULParameter(string, ULDbType, int) constructor

Initializes a ULParameter object with the specified parameter name and data type.

 Syntax

Visual Basic

Public Sub ULParameter (

ByVal parameterName As String,
ByVal dbType As ULDbType,
ByVal size As Integer
)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 419
 C#

public ULParameter (
string parameterName,
ULDbType dbType,
int size
)

Parameters

parameterName The name of the parameter. For unnamed parameters, use an empty string ("") or a null
reference (Nothing in Visual Basic) for this value. In UltraLite.NET, parameter names are not used by the
ULCommand object.
dbType One of the Sap.Data.UltraLite.ULDbType values.
size The length of the parameter.

Remarks

This constructor is not recommended; it is provided for compatibility with other data providers.

In UltraLite.NET parameters can only be used as IN parameters and all mapping information is ignored. Only
the ULParameter.Value property is important.

Related Information

ULParameter() constructor [page 418]

ULParameter(string, object) constructor [page 423]
Value property [page 433]

4.1.24.1.4 ULParameter(string, ULDbType, int,

ParameterDirection, bool, byte, byte, string,
DataRowVersion, object) constructor

Initializes a ULParameter object with the specified parameter name, data type, length, direction, nullability,
numeric precision, numeric scale, source column, source version, and value.

 Syntax

Visual Basic

Public Sub ULParameter (

UltraLite - .NET API Reference

420 PUBLIC UltraLite .NET API reference
 ByVal parameterName As String,
ByVal dbType As ULDbType,
ByVal size As Integer,
ByVal direction As ParameterDirection,
ByVal isNullable As Boolean,
ByVal precision As Byte,
ByVal scale As Byte,
ByVal sourceColumn As String,
ByVal sourceVersion As DataRowVersion,
ByVal value As Object
)

C#

public ULParameter (
string parameterName,
ULDbType dbType,
int size,
ParameterDirection direction,
bool isNullable,
byte precision,
byte scale,
string sourceColumn,
DataRowVersion sourceVersion,
object value
)

Parameters

parameterName The name of the parameter. For unnamed parameters, use an empty string ("") or a null
reference (Nothing in Visual Basic) for this value. In UltraLite.NET, parameter names are not used by the
ULCommand object.
dbType One of the Sap.Data.UltraLite.ULDbType values.
size The length of the parameter.
direction One of the System.Data.ParameterDirection values.
isNullable True if the value of the field can be null; otherwise, false.
precision The total number of digits to the left and right of the decimal point to which the Value property is
resolved.
scale The total number of decimal places to which the Value property is resolved.
sourceColumn The name of the source column to map.
sourceVersion One of the System.Data.DataRowVersion values.
value Pass a System.Object to produce the value of the parameter.

Exceptions

ULException class Only the System.Data.ParameterDirection.Input direction is supported in UltraLite.NET.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 421
Remarks

This constructor is not recommended; it is provided for compatibility with other data providers.

Related Information

ULParameter() constructor [page 418]

ULParameter(string, object) constructor [page 423]
ULCommand class [page 88]

4.1.24.1.5 ULParameter(string, ULDbType, int, string)

constructor

Initializes a ULParameter object with the specified parameter name, data type, and length.

 Syntax

Visual Basic

Public Sub ULParameter (

ByVal parameterName As String,
ByVal dbType As ULDbType,
ByVal size As Integer,
ByVal sourceColumn As String
)

C#

public ULParameter (
string parameterName,
ULDbType dbType,
int size,
string sourceColumn
)

Parameters

parameterName The name of the parameter. For unnamed parameters, use an empty string ("") or a null
reference (Nothing in Visual Basic) for this value. In UltraLite.NET, parameter names are not used by the
ULCommand object.
dbType One of the Sap.Data.UltraLite.ULDbType values.
size The length of the parameter.
sourceColumn The name of the source column to map.

UltraLite - .NET API Reference

422 PUBLIC UltraLite .NET API reference
Remarks

This constructor is not recommended; it is provided for compatibility with other data providers.

In UltraLite.NET parameters can only be used as IN parameters and all mapping information is ignored. Only
the ULParameter.Value property is important.

Related Information

ULParameter() constructor [page 418]

ULParameter(string, object) constructor [page 423]
Value property [page 433]
ULCommand class [page 88]

4.1.24.1.6 ULParameter(string, object) constructor

Initializes a ULParameter object with the specified parameter name and value.

 Syntax

Visual Basic

Public Sub ULParameter (

ByVal parameterName As String,
ByVal value As Object
)

C#

public ULParameter (
string parameterName,
object value
)

Parameters

parameterName The name of the parameter. For unnamed parameters, use an empty string ("") or a null
reference (Nothing in Visual Basic) for this value. In UltraLite.NET, parameter names are not used by the
ULCommand object.
value Pass a System.Object class to produce the value of the parameter.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 423
Remarks

Because of the special treatment of the 0 and 0.0 constants and the way overloaded methods are resolved, it is
highly recommended that you explicitly cast constant values to the object type when using this constructor.

 Example

The following code creates a ULParameter value of 0 and adds it to a ULCommand object named cmd.

' Visual Basic

cmd.Parameters.Add( New ULParameter( "", CType( 0, Object ) ) )

The following code is the C# language equivalent:

// C#
cmd.Parameters.Add( new ULParameter( "", (object)0 ) );

Related Information

ULParameter() constructor [page 418]

ULCommand class [page 88]

4.1.24.2 ResetDbType() method

This method is not supported in UltraLite.NET.

 Syntax

Visual Basic

Public Overrides Sub ResetDbType ()

C#

public override void ResetDbType ()

Remarks

In UltraLite.NET, parameters can only be used as IN parameters and all mapping information is ignored. Only
the ULParameter.Value property is important.

UltraLite - .NET API Reference

424 PUBLIC UltraLite .NET API reference
Related Information

Value property [page 433]

4.1.24.3 ToString() method

Returns the string representation of this instance.

 Syntax

Visual Basic

Public Overrides Function ToString () As String

C#

public override string ToString ()

Returns

The name of the parameter.

4.1.24.4 DbType property

Specifies the System.Data.DbType for the parameter.

 Syntax

Visual Basic

Public Overrides Property DbType As DbType

C#

public override DbType DbType {get;set;}

Remarks

One of the System.Data.DbType values.

The ULParameter.ULDbType and DbType properties are linked. Therefore, setting the DbType property
changes the ULParameter.ULDbType property to a supporting Sap.Data.UltraLite.ULDbType value.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 425
Related Information

ULDbType property [page 432]

4.1.24.5 Direction property

A value indicating whether the parameter is input-only, output-only, bidirectional, or a stored procedure return
value parameter.

 Syntax

Visual Basic

Public Overrides Property Direction As ParameterDirection

C#

public override ParameterDirection Direction {get;set;}

Remarks

One of the System.Data.ParameterDirection values.

In UltraLite.NET, parameters can only be used as IN parameters and all mapping information is ignored. Only
the ULParameter.Value property is important.

Related Information

Value property [page 433]

4.1.24.6 IsNullable property

Specifies whether the parameter accepts null values.

 Syntax

Visual Basic

Public Overrides Property IsNullable As Boolean

C#

public override bool IsNullable {get;set;}

UltraLite - .NET API Reference

426 PUBLIC UltraLite .NET API reference
Remarks

True if null values are accepted, false otherwise. The default is false. Null values are handled using the DBNull
class.

In UltraLite.NET, parameters can only be used as IN parameters and all mapping information is ignored. Only
the ULParameter.Value property is important.

Related Information

Value property [page 433]

4.1.24.7 Offset property

Specifies the offset to the ULParameter.Value.

 Syntax

Visual Basic

Public Property Offset As Integer

C#

public int Offset {get;set;}

Remarks

The offset to the value. The default is 0.

In UltraLite.NET parameters can only be used as IN parameters and all mapping information is ignored. Only
the ULParameter.Value property is important.

Related Information

Value property [page 433]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 427
4.1.24.8 ParameterName property

Specifies the name of the parameter.

 Syntax

Visual Basic

Public Overrides Property ParameterName As String

C#

public override string ParameterName {get;set;}

Remarks

A string representing the name of the parameter, or an empty string ("") for unnamed parameters. Specifying a
null reference (Nothing in Visual Basic) results in an empty string being used.

In UltraLite.NET, parameter names are not used by an ULCommand object. All parameters are treated as
positional parameters and are used by a command in the order that they were added.

Related Information

ULCommand class [page 88]

4.1.24.9 Precision property

Specifies the maximum number of digits used to represent the ULParameter.Value property.

 Syntax

Visual Basic

Public Property Precision As Byte

C#

public byte Precision {get;set;}

UltraLite - .NET API Reference

428 PUBLIC UltraLite .NET API reference
Remarks

The maximum number of digits used to represent the ULParameter.Value property. The default value is 0,
which indicates that the data provider sets the precision for the ULParameter.Value property.

In UltraLite.NET, parameters can only be used as IN parameters and all mapping information is ignored. Only
the ULParameter.Value property is important.

Related Information

Value property [page 433]

4.1.24.10 Scale property

Specifies the number of decimal places to which ULParameter.Value property is resolved.

 Syntax

Visual Basic

Public Property Scale As Byte

C#

public byte Scale {get;set;}

Remarks

The number of decimal places to which ULParameter.Value property is resolved. The default is 0.

In UltraLite.NET, parameters can only be used as IN parameters and all mapping information is ignored. Only
the ULParameter.Value property is important.

Related Information

Value property [page 433]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 429
4.1.24.11 Size property

Specifies the maximum size of the data within the column.

 Syntax

Visual Basic

Public Overrides Property Size As Integer

C#

public override int Size {get;set;}

Remarks

The maximum size of the data within the column. The default value is inferred from the parameter value. The
Size property is used for binary and string types.

In UltraLite.NET, parameters can only be used as IN parameters and all mapping information is ignored. Only
the ULParameter.Value property is important.

Related Information

Value property [page 433]

4.1.24.12 SourceColumn property

Specifies the name of the source column mapped to the DataSet object and used for loading or returning the
value.

 Syntax

Visual Basic

Public Overrides Property SourceColumn As String

C#

public override string SourceColumn {get;set;}

UltraLite - .NET API Reference

430 PUBLIC UltraLite .NET API reference
Remarks

A string specifying the name of the source column mapped to the DataSet object and used for loading or
returning the value.

In UltraLite.NET, parameters can only be used as IN parameters and all mapping information is ignored. Only
the ULParameter.Value property is important.

Related Information

Value property [page 433]

4.1.24.13 SourceColumnNullMapping property

Specifies whether the source column is nullable.

 Syntax

Visual Basic

Public Overrides Property SourceColumnNullMapping As Boolean

C#

public override bool SourceColumnNullMapping {get;set;}

Remarks

True if the source column is nullable; false, otherwise.

In UltraLite.NET, parameters can only be used as IN parameters and all mapping information is ignored. Only
the ULParameter.Value property is important.

Related Information

Value property [page 433]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 431
4.1.24.14 SourceVersion property

The System.Data.DataRowVersion value to use when loading the ULParameter.Value property.

 Syntax

Visual Basic

Public Overrides Property SourceVersion As DataRowVersion

C#

public override DataRowVersion SourceVersion {get;set;}

Related Information

Value property [page 433]

4.1.24.15 ULDbType property

Specifies the Sap.Data.UltraLite.ULDbType for the parameter.

 Syntax

Visual Basic

Public Property ULDbType As ULDbType

C#

public ULDbType ULDbType {get;set;}

Remarks

One of the Sap.Data.UltraLite.ULDbType values.

The ULDbType and ULParameter.DbType properties are linked. Therefore, setting the ULDbType property
changes the ULParameter.DbType property to a supporting System.Data.DbType value.

In UltraLite.NET, parameters can only be used as IN parameters and all mapping information is ignored. Only
the ULParameter.Value property is important.

UltraLite - .NET API Reference

432 PUBLIC UltraLite .NET API reference
Related Information

Value property [page 433]

DbType property [page 425]

4.1.24.16 Value property

Specifies the value of the parameter.

 Syntax

Visual Basic

Public Overrides Property Value As Object

C#

public override object Value {get;set;}

Remarks

Pass a System.Object class that specifies the value of the parameter.

The value is sent as-is to the data provider without any type conversion or mapping. When the command is
executed, the command attempts to convert the value to the required type, signaling a ULException object with
ULSQLCode.SQLE_CONVERSION_ERROR if it cannot convert the value.

Related Information

ULException class [page 354]

4.1.25 ULParameterCollection class

Represents all parameters to a ULCommand object.

 Syntax

Visual Basic

Public NotInheritable Class ULParameterCollection Inherits

System.Data.Common.DbParameterCollection

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 433
 C#

public sealed class ULParameterCollection :

System.Data.Common.DbParameterCollection

Members

All members of ULParameterCollection, including inherited members.

Methods

Modifier and Type Method Description

public ULParameter Add [page 436] Adds a ULParameter object to the col­
lection.

public override void AddRange [page 445] Adds an array of values to the end of
the ULParameterCollection.

public override void Clear() [page 447] Removes all the parameters from the
collection.

public override bool Contains [page 447] Checks whether a ULParameter object
exists in the collection.

public override void CopyTo(Array, int) [page 449] Copies ULParameter objects from the
ULParameterCollection to the specified
array.

public override IEnumerator GetEnumerator() [page 450] Returns an enumerator for the collec­
tion.

protected override DbParameter GetParameter [page 450] See individual topics

public override int IndexOf [page 451] Returns the location of the ULParame­
ter object in the collection.

public override void Insert(int, object) [page 453] Inserts an ULParameter object in the
collection at the specified index.

public override void Remove(object) [page 454] Removes an ULParameter object from
the collection.

public override void RemoveAt [page 455] Removes the parameter at the specified
index in the collection.

protected override void SetParameter [page 457] See individual topics

Properties

Modifier and Type Property Description

public override int Count [page 458] Returns the number of ULParameter
objects in the collection.

public override bool IsFixedSize [page 459] Indicates whether the ULParameterCol­
lection object has a fixed size.

UltraLite - .NET API Reference

434 PUBLIC UltraLite .NET API reference
 Modifier and Type Property Description

public override bool IsReadOnly [page 459] Indicates whether the ULParameterCol­
lection object is read-only.

public override bool IsSynchronized [page 460] Indicates whether the ULParameterCol­
lection object is synchronized.

public override object SyncRoot [page 460] Returns an object that can be used to
synchronize access to the SAParame­
terCollection object.

public new ULParameter this [page 461] Returns the ULParameter object at the
specified index.

Remarks

All parameters in the collection are treated as positional parameters and are specified in the same order as the
question mark placeholders in the ULCommand.CommandText value. For example, the first parameter in the
collection corresponds to the first question mark in the SQL statement, the second parameter in the collection
corresponds to the second question mark in the SQL statement, and so on. There must be at least as many
question marks in the ULCommand.CommandText value as there are parameters in the collection. Nulls are
substituted for missing parameters.

There is no constructor for the ULParameterCollection class. You obtain a ULParameterCollection object from
the ULCommand.Parameters property.

In this section:

Add method [page 436]

Adds a ULParameter object to the collection.

AddRange method [page 445]

Adds an array of values to the end of the ULParameterCollection.

Clear() method [page 447]

Removes all the parameters from the collection.

Contains method [page 447]

Checks whether a ULParameter object exists in the collection.

CopyTo(Array, int) method [page 449]

Copies ULParameter objects from the ULParameterCollection to the specified array.

GetEnumerator() method [page 450]

Returns an enumerator for the collection.

GetParameter method [page 450]

IndexOf method [page 451]

Returns the location of the ULParameter object in the collection.

Insert(int, object) method [page 453]

Inserts an ULParameter object in the collection at the specified index.

Remove(object) method [page 454]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 435
 Removes an ULParameter object from the collection.

RemoveAt method [page 455]

Removes the parameter at the specified index in the collection.

SetParameter method [page 457]

Count property [page 458]

Returns the number of ULParameter objects in the collection.

IsFixedSize property [page 459]

Indicates whether the ULParameterCollection object has a fixed size.

IsReadOnly property [page 459]

Indicates whether the ULParameterCollection object is read-only.

IsSynchronized property [page 460]

Indicates whether the ULParameterCollection object is synchronized.

SyncRoot property [page 460]

Returns an object that can be used to synchronize access to the SAParameterCollection object.

this property [page 461]

Returns the ULParameter object at the specified index.

Related Information

ULCommand class [page 88]

CommandText property [page 127]
Parameters property [page 132]

4.1.25.1 Add method

Adds a ULParameter object to the collection.

Overload list

Modifier and Type Overload name Description

public ULParameter Add(ULParameter) [page 437] Adds a ULParameter object to the col­
lection.

public override int Add(object) [page 438] Adds a ULParameter object to the col­
lection.

public ULParameter Add(string, ULDbType) [page 440] Adds a new ULParameter object, cre­
ated using the specified parameter
name and data type, to the collection.

UltraLite - .NET API Reference

436 PUBLIC UltraLite .NET API reference
 Modifier and Type Overload name Description

public ULParameter Add(string, ULDbType, int) [page 441] Adds a new ULParameter object, cre­
ated using the specified parameter
name, data type, and length, to the col­
lection.

public ULParameter Add(string, ULDbType, int, string) [page Adds a new ULParameter object, cre­
442] ated using the specified parameter
name, data type, length, and source
column name, to the collection.

public ULParameter Add(string, object) [page 443] Adds a new ULParameter object, cre­
ated using the specified parameter
name and value, to the collection.

In this section:

Add(ULParameter) method [page 437]

Adds a ULParameter object to the collection.

Add(object) method [page 438]

Adds a ULParameter object to the collection.

Add(string, ULDbType) method [page 440]

Adds a new ULParameter object, created using the specified parameter name and data type, to the
collection.

Add(string, ULDbType, int) method [page 441]

Adds a new ULParameter object, created using the specified parameter name, data type, and length, to
the collection.

Add(string, ULDbType, int, string) method [page 442]

Adds a new ULParameter object, created using the specified parameter name, data type, length, and
source column name, to the collection.

Add(string, object) method [page 443]

Adds a new ULParameter object, created using the specified parameter name and value, to the
collection.

4.1.25.1.1 Add(ULParameter) method

Adds a ULParameter object to the collection.

 Syntax

Visual Basic

Public Function Add (ByVal value As ULParameter) As ULParameter

C#

public ULParameter Add (ULParameter value)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 437
Parameters

value The ULParameter object to add to the collection.

Returns

The new ULParameter object.

Exceptions

ArgumentNullException The value cannot be null (Nothing in Visual Basic).

ArgumentException The ULParameter object can only be added to the collection once.

Remarks

All parameters in the collection are treated as positional parameters and must be added to the collection in the
same order as the corresponding question mark placeholders in the ULCommand.CommandText value. For
example, the first parameter in the collection corresponds to the first question mark in the SQL statement, the
second parameter in the collection corresponds to the second question mark in the SQL statement, and so on.
There must be at least as many question marks in the ULCommand.CommandText value as there are
parameters in the collection. Nulls are substituted for missing parameters.

Related Information

Add(string, object) method [page 443]

ULParameter class [page 413]
CommandText property [page 127]

4.1.25.1.2 Add(object) method

Adds a ULParameter object to the collection.

 Syntax

Visual Basic

Public Overrides Function Add (ByVal value As Object) As Integer

UltraLite - .NET API Reference

438 PUBLIC UltraLite .NET API reference
 C#

public override int Add (object value)

Parameters

value The ULParameter object to add to the collection.

Returns

The index of the new ULParameter object.

Exceptions

ArgumentNullException The value cannot be null (Nothing in Visual Basic).

InvalidCastException The value specified must be a ULParameter object.
ArgumentException The ULParameter object can only be added to the collection once.

Remarks

All parameters in the collection are treated as positional parameters and must be added to the collection in the
same order as the corresponding question mark placeholders in the ULCommand.CommandText value. For
example, the first parameter in the collection corresponds to the first question mark in the SQL statement, the
second parameter in the collection corresponds to the second question mark in the SQL statement, and so on.
There must be at least as many question marks in the ULCommand.CommandText value as there are
parameters in the collection. Nulls are substituted for missing parameters.

Related Information

Add(ULParameter) method [page 437]

Add(string, object) method [page 443]
CommandText property [page 127]
ULParameter class [page 413]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 439
4.1.25.1.3 Add(string, ULDbType) method

Adds a new ULParameter object, created using the specified parameter name and data type, to the collection.

 Syntax

Visual Basic

Public Function Add (

ByVal parameterName As String,
ByVal ulDbType As ULDbType
) As ULParameter

C#

public ULParameter Add (

string parameterName,
ULDbType ulDbType
)

Parameters

parameterName The name of the parameter. For unnamed parameters, use an empty string ("") or a null
reference (Nothing in Visual Basic) for this value. In UltraLite.NET, parameter names are not used by the
ULCommand object.
ulDbType One of the Sap.Data.UltraLite.ULDbType values.

Returns

The new ULParameter object.

Remarks

All parameters in the collection are treated as positional parameters and must be added to the collection in the
same order as the corresponding question mark placeholders in the ULCommand.CommandText value. For
example, the first parameter in the collection corresponds to the first question mark in the SQL statement, the
second parameter in the collection corresponds to the second question mark in the SQL statement, and so on.
There must be at least as many question marks in the ULCommand.CommandText value as there are
parameters in the collection. Nulls are substituted for missing parameters.

UltraLite - .NET API Reference

440 PUBLIC UltraLite .NET API reference
Related Information

Add(ULParameter) method [page 437]

Add(string, object) method [page 443]
ULParameter class [page 413]
CommandText property [page 127]
ULCommand class [page 88]

4.1.25.1.4 Add(string, ULDbType, int) method

Adds a new ULParameter object, created using the specified parameter name, data type, and length, to the
collection.

 Syntax

Visual Basic

Public Function Add (

ByVal parameterName As String,
ByVal ulDbType As ULDbType,
ByVal size As Integer
) As ULParameter

C#

public ULParameter Add (

string parameterName,
ULDbType ulDbType,
int size
)

Parameters

parameterName The name of the parameter. For unnamed parameters, use an empty string ("") or a null
reference (Nothing in Visual Basic) for this value. In UltraLite.NET, parameter names are not used by the
ULCommand object.
ulDbType One of the Sap.Data.UltraLite.ULDbType values.
size The length of the parameter.

Returns

The new ULParameter object.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 441
Remarks

All parameters in the collection are treated as positional parameters and must be added to the collection in the
same order as the corresponding question mark placeholders in the ULCommand.CommandText value. For
example, the first parameter in the collection corresponds to the first question mark in the SQL statement, the
second parameter in the collection corresponds to the second question mark in the SQL statement, and so on.
There must be at least as many question marks in the ULCommand.CommandText value as there are
parameters in the collection. Nulls are substituted for missing parameters.

Related Information

Add(ULParameter) method [page 437]

Add(string, object) method [page 443]
ULParameter class [page 413]
CommandText property [page 127]
ULCommand class [page 88]

4.1.25.1.5 Add(string, ULDbType, int, string) method

Adds a new ULParameter object, created using the specified parameter name, data type, length, and source
column name, to the collection.

 Syntax

Visual Basic

Public Function Add (

ByVal parameterName As String,
ByVal ulDbType As ULDbType,
ByVal size As Integer,
ByVal sourceColumn As String
) As ULParameter

C#

public ULParameter Add (

string parameterName,
ULDbType ulDbType,
int size,
string sourceColumn
)

UltraLite - .NET API Reference

442 PUBLIC UltraLite .NET API reference
Parameters

parameterName The name of the parameter. For unnamed parameters, use an empty string ("") or a null
reference (Nothing in Visual Basic) for this value. In UltraLite.NET, parameter names are not used by the
ULCommand object.
ulDbType One of the Sap.Data.UltraLite.ULDbType values.
size The length of the parameter.
sourceColumn The name of the source column to map.

Returns

The new ULParameter object.

Remarks

All parameters in the collection are treated as positional parameters and must be added to the collection in the
same order as the corresponding question mark placeholders in the ULCommand.CommandText value. For
example, the first parameter in the collection corresponds to the first question mark in the SQL statement, the
second parameter in the collection corresponds to the second question mark in the SQL statement, and so on.
There must be at least as many question marks in the ULCommand.CommandText value as there are
parameters in the collection. Nulls are substituted for missing parameters.

Related Information

Add(ULParameter) method [page 437]

Add(string, object) method [page 443]
ULParameter class [page 413]
CommandText property [page 127]
ULCommand class [page 88]

4.1.25.1.6 Add(string, object) method

Adds a new ULParameter object, created using the specified parameter name and value, to the collection.

 Syntax

Visual Basic

Public Function Add (

ByVal parameterName As String,

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 443
 ByVal value As Object
) As ULParameter

C#

public ULParameter Add (

string parameterName,
object value
)

Parameters

parameterName The name of the parameter. For unnamed parameters, use an empty string ("") or a null
reference (Nothing in Visual Basic) for this value. In UltraLite.NET, parameter names are not used by the
ULCommand object.
value A System.Object that is to be the value of the parameter.

Returns

The new ULParameter object.

Remarks

All parameters in the collection are treated as positional parameters and must be added to the collection in the
same order as the corresponding question mark placeholders in the ULCommand.CommandText value. For
example, the first parameter in the collection corresponds to the first question mark in the SQL statement, the
second parameter in the collection corresponds to the second question mark in the SQL statement, and so on.
There must be at least as many question marks in the ULCommand.CommandText value as there are
parameters in the collection. Nulls are substituted for missing parameters.

Because of the special treatment of the 0 and 0.0 constants and the way overloaded methods are resolved, it is
highly recommended that you explicitly cast constant values to the object type when using this method.

 Example

The following code adds a ULParameter value of 0 to a ULCommand object named cmd.

' Visual Basic

cmd.Parameters.Add( "", CType( 0, Object ) )

The following code is the C# language equivalent:

// C#
cmd.Parameters.Add( "", (object)0 );

UltraLite - .NET API Reference

444 PUBLIC UltraLite .NET API reference
Related Information

Add(ULParameter) method [page 437]

ULParameter class [page 413]
CommandText property [page 127]
ULCommand class [page 88]

4.1.25.2 AddRange method

Adds an array of values to the end of the ULParameterCollection.

Overload list

Modifier and Type Overload name Description

public override void AddRange(Array) [page 445] Adds an array of values to the end of
the ULParameterCollection.

public void AddRange(ULParameter[]) [page 446] Adds an array of values to the end of
the ULParameterCollection.

In this section:

AddRange(Array) method [page 445]

Adds an array of values to the end of the ULParameterCollection.

AddRange(ULParameter[]) method [page 446]

Adds an array of values to the end of the ULParameterCollection.

4.1.25.2.1 AddRange(Array) method

Adds an array of values to the end of the ULParameterCollection.

 Syntax

Visual Basic

Public Overrides Sub AddRange (ByVal values As Array)

C#

public override void AddRange (Array values)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 445
Parameters

values An array of ULParameter objects to add to the end of this collection.

Related Information

ULParameter class [page 413]

4.1.25.2.2 AddRange(ULParameter[]) method

Adds an array of values to the end of the ULParameterCollection.

 Syntax

Visual Basic

Public Sub AddRange (ByVal values As ULParameter())

C#

public void AddRange (ULParameter[] values)

Parameters

values An array of ULParameter objects to add to the end of this collection.

Remarks

This is the strongly-typed version of the DbParameterCollection.AddRange(Array) method.

Related Information

ULParameter class [page 413]

ULParameterCollection class [page 433]

UltraLite - .NET API Reference

446 PUBLIC UltraLite .NET API reference
4.1.25.3 Clear() method

Removes all the parameters from the collection.

 Syntax

Visual Basic

Public Overrides Sub Clear ()

C#

public override void Clear ()

4.1.25.4 Contains method

Checks whether a ULParameter object exists in the collection.

Overload list

Modifier and Type Overload name Description

public override bool Contains(object) [page 447] Checks whether a ULParameter object
exists in the collection.

public override bool Contains(string) [page 448] Checks whether a ULParameter object
with the specified name exists in the
collection.

In this section:

Contains(object) method [page 447]

Checks whether a ULParameter object exists in the collection.

Contains(string) method [page 448]

Checks whether a ULParameter object with the specified name exists in the collection.

4.1.25.4.1 Contains(object) method

Checks whether a ULParameter object exists in the collection.

 Syntax

Visual Basic

Public Overrides Function Contains (ByVal value As Object) As Boolean

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 447
 C#

public override bool Contains (object value)

Parameters

value The ULParameter object to check for.

Returns

True if the collection contains the ULParameter object, false otherwise.

Related Information

Contains(string) method [page 448]

ULParameter class [page 413]

4.1.25.4.2 Contains(string) method

Checks whether a ULParameter object with the specified name exists in the collection.

 Syntax

Visual Basic

Public Overrides Function Contains (ByVal value As String) As Boolean

C#

public override bool Contains (string value)

Parameters

value The name of the parameter to search for.

UltraLite - .NET API Reference

448 PUBLIC UltraLite .NET API reference
Returns

True if the collection contains the ULParameter object, false otherwise.

Related Information

Contains(object) method [page 447]

ULParameter class [page 413]

4.1.25.5 CopyTo(Array, int) method

Copies ULParameter objects from the ULParameterCollection to the specified array.

 Syntax

Visual Basic

Public Overrides Sub CopyTo (

ByVal array As Array,
ByVal index As Integer
)

C#

public override void CopyTo (

Array array,
int index
)

Parameters

array The array into which to copy the ULParameter objects.

index The starting index of the array.

Related Information

ULParameter class [page 413]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 449
4.1.25.6 GetEnumerator() method

Returns an enumerator for the collection.

 Syntax

Visual Basic

Public Overrides Function GetEnumerator () As

System.Collections.IEnumerator

C#

public override IEnumerator GetEnumerator ()

Returns

An ArrayList enumerator enumerating the parameters in the collection.

4.1.25.7 GetParameter method

Overload list

Modifier and Type Overload name Description

protected override DbParameter GetParameter(int) [page 451]

protected override DbParameter GetParameter(string) [page 451]

In this section:

GetParameter(int) method [page 451]

GetParameter(string) method [page 451]

UltraLite - .NET API Reference

450 PUBLIC UltraLite .NET API reference
4.1.25.7.1 GetParameter(int) method

 Syntax

Visual Basic

Protected Overrides Function GetParameter (ByVal index As Integer) As

DbParameter

C#

protected override DbParameter GetParameter (int index)

4.1.25.7.2 GetParameter(string) method

 Syntax

Visual Basic

Protected Overrides Function GetParameter (ByVal parameterName As String)

As DbParameter

C#

protected override DbParameter GetParameter (string parameterName)

4.1.25.8 IndexOf method

Returns the location of the ULParameter object in the collection.

Overload list

Modifier and Type Overload name Description

public override int IndexOf(object) [page 452] Returns the location of the ULParame­
ter object in the collection.

public override int IndexOf(string) [page 453] Returns the location of the ULParame­
ter object with the specified name in
the collection.

In this section:

IndexOf(object) method [page 452]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 451
 Returns the location of the ULParameter object in the collection.

IndexOf(string) method [page 453]

Returns the location of the ULParameter object with the specified name in the collection.

4.1.25.8.1 IndexOf(object) method

Returns the location of the ULParameter object in the collection.

 Syntax

Visual Basic

Public Overrides Function IndexOf (ByVal value As Object) As Integer

C#

public override int IndexOf (object value)

Parameters

value The ULParameter object to locate.

Returns

The zero-based index of the ULParameter object in the collection or -1 if the parameter is not found.

Exceptions

InvalidCastException The value specified must be a ULParameter object.

Related Information

IndexOf(string) method [page 453]

ULParameter class [page 413]

UltraLite - .NET API Reference

452 PUBLIC UltraLite .NET API reference
4.1.25.8.2 IndexOf(string) method

Returns the location of the ULParameter object with the specified name in the collection.

 Syntax

Visual Basic

Public Overrides Function IndexOf (ByVal parameterName As String) As

Integer

C#

public override int IndexOf (string parameterName)

Parameters

parameterName The name of the parameter to locate.

Returns

The zero-based index of the ULParameter object in the collection or -1 if the parameter is not found.

Related Information

IndexOf(object) method [page 452]

ULParameter class [page 413]

4.1.25.9 Insert(int, object) method

Inserts an ULParameter object in the collection at the specified index.

 Syntax

Visual Basic

Public Overrides Sub Insert (

ByVal index As Integer,
ByVal value As Object
)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 453
 C#

public override void Insert (

int index,
object value
)

Parameters

index The zero-based index where the parameter is to be inserted within the collection.
value The ULParameter object to insert.

Exceptions

IndexOutOfRangeException The index is invalid.

ArgumentNullException You cannot set a parameter using a null reference (Nothing in Visual Basic).
InvalidCastException The value specified must be a ULParameter object.

Related Information

ULParameter class [page 413]

4.1.25.10 Remove(object) method

Removes an ULParameter object from the collection.

 Syntax

Visual Basic

Public Overrides Sub Remove (ByVal value As Object)

C#

public override void Remove (object value)

Parameters

value The ULParameter object to remove.

UltraLite - .NET API Reference

454 PUBLIC UltraLite .NET API reference
Exceptions

ArgumentNullException You cannot set a parameter using a null reference (Nothing in Visual Basic).
InvalidCastException The value specified must be a ULParameter object.
ArgumentException The collection does not contain the specified parameter.

Related Information

ULParameter class [page 413]

4.1.25.11 RemoveAt method

Removes the parameter at the specified index in the collection.

Overload list

Modifier and Type Overload name Description

public override void RemoveAt(int) [page 455] Removes the parameter at the specified
index in the collection.

public override void RemoveAt(string) [page 456] Removes the parameter with the speci­
fied name from the collection.

In this section:

RemoveAt(int) method [page 455]

Removes the parameter at the specified index in the collection.

RemoveAt(string) method [page 456]

Removes the parameter with the specified name from the collection.

4.1.25.11.1 RemoveAt(int) method

Removes the parameter at the specified index in the collection.

 Syntax

Visual Basic

Public Overrides Sub RemoveAt (ByVal index As Integer)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 455
 C#

public override void RemoveAt (int index)

Parameters

index The zero-based index of the parameter to remove. The value must be in the range
[0,ULParameterCollection.Count-1]. The first parameter in the collection has an index value of zero.

Exceptions

IndexOutOfRangeException The index is invalid.

Related Information

RemoveAt(string) method [page 456]

Count property [page 458]

4.1.25.11.2 RemoveAt(string) method

Removes the parameter with the specified name from the collection.

 Syntax

Visual Basic

Public Overrides Sub RemoveAt (ByVal parameterName As String)

C#

public override void RemoveAt (string parameterName)

Parameters

parameterName The name of the parameter to retrieve.

UltraLite - .NET API Reference

456 PUBLIC UltraLite .NET API reference
Exceptions

IndexOutOfRangeException There is no parameter with the specified name.

Related Information

RemoveAt(int) method [page 455]

4.1.25.12 SetParameter method

Overload list

Modifier and Type Overload name Description

protected override void SetParameter(int, DbParameter) [page

457]

protected override void SetParameter(string, DbParameter)

[page 458]

In this section:

SetParameter(int, DbParameter) method [page 457]

SetParameter(string, DbParameter) method [page 458]

4.1.25.12.1 SetParameter(int, DbParameter) method

 Syntax

Visual Basic

Protected Overrides Sub SetParameter (

ByVal index As Integer,
ByVal parm As DbParameter
)

C#

protected override void SetParameter (

int index,
DbParameter parm

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 457
 )

4.1.25.12.2 SetParameter(string, DbParameter) method

 Syntax

Visual Basic

Protected Overrides Sub SetParameter (

ByVal parameterName As String,
ByVal parm As DbParameter
)

C#

protected override void SetParameter (

string parameterName,
DbParameter parm
)

4.1.25.13 Count property

Returns the number of ULParameter objects in the collection.

 Syntax

Visual Basic

Public ReadOnly Overrides Property Count As Integer

C#

public override int Count {get;}

Remarks

The number of ULParameter objects in the collection.

UltraLite - .NET API Reference

458 PUBLIC UltraLite .NET API reference
4.1.25.14 IsFixedSize property

Indicates whether the ULParameterCollection object has a fixed size.

 Syntax

Visual Basic

Public ReadOnly Overrides Property IsFixedSize As Boolean

C#

public override bool IsFixedSize {get;}

Remarks

True if this collection has a fixed size, false otherwise.

4.1.25.15 IsReadOnly property

Indicates whether the ULParameterCollection object is read-only.

 Syntax

Visual Basic

Public ReadOnly Overrides Property IsReadOnly As Boolean

C#

public override bool IsReadOnly {get;}

Remarks

True if this collection is read-only, false otherwise.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 459
4.1.25.16 IsSynchronized property

Indicates whether the ULParameterCollection object is synchronized.

 Syntax

Visual Basic

Public ReadOnly Overrides Property IsSynchronized As Boolean

C#

public override bool IsSynchronized {get;}

Remarks

True if this collection is synchronized, false otherwise.

4.1.25.17 SyncRoot property

Returns an object that can be used to synchronize access to the SAParameterCollection object.

 Syntax

Visual Basic

Public ReadOnly Overrides Property SyncRoot As Object

C#

public override object SyncRoot {get;}

Remarks

The object to be used to synchronize access to this collection.

UltraLite - .NET API Reference

460 PUBLIC UltraLite .NET API reference
4.1.25.18 this property

Returns the ULParameter object at the specified index.

Overload list

Modifier and Type Overload name Description

public new ULParameter this[int index] [page 461] Returns the ULParameter object at the
specified index.

public new ULParameter this[string parameterName] [page 462] Returns the ULParameter object with
the specified name.

In this section:

this[int index] property [page 461]

Returns the ULParameter object at the specified index.

this[string parameterName] property [page 462]

Returns the ULParameter object with the specified name.

4.1.25.18.1 this[int index] property

Returns the ULParameter object at the specified index.

 Syntax

Visual Basic

Public Shadows Property Item (ByVal indexAs Integer) As ULParameter

C#

public new ULParameter this[int index] {get;set;}

Returns

The ULParameter object at the specified index.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 461
Remarks

In C#, this property is the indexer for the ULParameterCollection class.

This is the strongly-typed version of DbParameterCollection.this[int] property.

Related Information

ULParameter class [page 413]

4.1.25.18.2 this[string parameterName] property

Returns the ULParameter object with the specified name.

 Syntax

Visual Basic

Public Shadows Property Item (ByVal parameterNameAs String) As ULParameter

C#

public new ULParameter this[string parameterName] {get;set;}

Returns

The ULParameter object with the specified name.

Remarks

In C#, this property is the indexer for the ULParameterCollection class.

This is the strongly-typed version of DbParameterCollection.this[string] property.

Related Information

GetOrdinal(string) method [page 328]

GetValue(int) method [page 337]
GetFieldType(int) method [page 321]

UltraLite - .NET API Reference

462 PUBLIC UltraLite .NET API reference
ULParameter class [page 413]

4.1.26 ULResultSet class

UL Ext: Represents an editable result set in an UltraLite database.

 Syntax

Visual Basic

Public Class ULResultSet Inherits ULDataReader

C#

public class ULResultSet : ULDataReader

Members

All members of ULResultSet, including inherited members.

Methods

Modifier and Type Method Description

public unsafe void AppendBytes(int, byte[], int, int) [page Appends the specified subset of the
469] specified array of System.Bytes to the
new value for the specified ULDb­
Type.LongBinary column.

public unsafe void AppendChars(int, char[], int, int) [page Appends the specified subset of the
471] specified array of System.Chars to the
new value for the specified ULDb­
Type.LongVarchar column.

public void Delete() [page 472] Deletes the current row.

public void SetBoolean(int, bool) [page 473] Sets the value for the specified column
using a System.Boolean.

public void SetByte(int, byte) [page 474] Sets the value for the specified column
using a System.Byte (unsigned 8-bit in­
teger).

public unsafe void SetBytes(int, byte[]) [page 475] Sets the value for the specified column
using an array of System.Bytes.

public unsafe void SetDateTime(int, DateTime) [page Sets the value for the specified column
476] using a System.DateTime.

public void SetDBNull(int) [page 477] Sets a column to NULL.

public void SetDecimal(int, decimal) [page 478] Sets the value for the specified column
using a System.Decimal.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 463
Modifier and Type Method Description

public void SetDouble(int, double) [page 479] Sets the value for the specified column
using a System.Double.

public void SetFloat(int, float) [page 480] Sets the value for the specified column
using a System.Single.

public unsafe void SetGuid(int, Guid) [page 481] Sets the value for the specified column
using a System.Guid.

public void SetInt16(int, short) [page 483] Sets the value for the specified column
using a System.Int16.

public void SetInt32(int, int) [page 484] Sets the value for the specified column
using a System.Int32.

public void SetInt64(int, long) [page 485] Sets the value for the specified column
using an Int64.

public unsafe void SetString(int, string) [page 486] Sets the value for the specified column
using a System.String.

public unsafe void SetTimeSpan(int, TimeSpan) [page Sets the value for the specified column
487] using a System.TimeSpan.

public void SetToDefault(int) [page 488] Sets the value for the specified column
to its default value.

public void SetUInt16(int, ushort) [page 489] Sets the value for the specified column
using a System.UInt16.

public void SetUInt32(int, uint) [page 490] Sets the value for the specified column
using a System.UInt32.

public void SetUInt64(int, ulong) [page 492] Sets the value for the specified column
using a System.UInt64.

public void Update() [page 493] Updates the current row with the cur­
rent column values (specified using the
set methods).

public void UpdateBegin() [page 493] Prepares to update the current row.

Inherited members from ULDataReader

Modifier and Type Member Description

public override void Close() [page 309] Closes the cursor.

public override int Depth [page 347] Returns the depth of nesting for the
current row.

protected override void Dispose(bool) [page 309]

public override int FieldCount [page 347] Returns the number of columns in the
cursor.

public override unsafe bool GetBoolean(int) [page 310] Returns the value for the specified col­
umn as a System.Boolean.

public override unsafe byte GetByte(int) [page 311] Returns the value for the specified col­
umn as an unsigned 8-bit value (Sys­
tem.Byte).

UltraLite - .NET API Reference

464 PUBLIC UltraLite .NET API reference
 Modifier and Type Member Description

public unsafe byte[] GetBytes(int) [page 312] UL Ext: Returns the value for the speci­
fied column as an array of Sys­
tem.Bytes values.

public override unsafe long GetBytes(int, long, byte[], int, int) [page Copies a subset of the value for the
313] specified ULDbType.LongBinary col­
umn, beginning at the specified offset,
to the specified offset of the destination
System.Byte array.

public override char GetChar(int) [page 315] This method is not supported in Ultra­
Lite.NET.

public override unsafe long GetChars(int, long, char[], int, int) Copies a subset of the value for the
[page 316] specified ULDbType.LongVarchar col­
umn, beginning at the specified offset,
to the specified offset of the destination
System.Char array.

public override string GetDataTypeName(int) [page 317] Returns the name of the specified col­
umn's provider data type.

public override unsafe DateTime GetDateTime(int) [page 318] Returns the value for the specified col­
umn as a System.DateTime type with
millisecond accuracy.

protected override DbDataReader GetDbDataReader(int) [page 319]

public override decimal GetDecimal(int) [page 319] Returns the value for the specified col­
umn as a System.Decimal type.

public override unsafe double GetDouble(int) [page 320] Returns the value for the specified col­
umn as a System.Double type.

public override IEnumerator GetEnumerator() [page 321] Returns an System.Collections.IEnum­

erator value that iterates through the
ULDataReader object.

public override Type GetFieldType(int) [page 321] Returns the System.Type value most
appropriate for the specified column.

public override unsafe float GetFloat(int) [page 322] Returns the value for the specified col­
umn as a System.Single type.

public override unsafe Guid GetGuid(int) [page 323] Returns the value for the specified col­
umn as a UUID (System.Guid) type.

public override unsafe short GetInt16(int) [page 324] Returns the value for the specified col­
umn as a System.Int16 type.

public override unsafe int GetInt32(int) [page 325] Returns the value for the specified col­
umn as a System.Int32 type.

public override unsafe long GetInt64(int) [page 326] Returns the value for the specified col­
umn as a System.Int64 type.

public override string GetName(int) [page 327] Returns the name of the specified col­
umn.

public override unsafe int GetOrdinal(string) [page 328] Returns the column ID of the named
column.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 465
Modifier and Type Member Description

public unsafe int GetRowCount(int) [page 329] UL Ext: Returns the number of rows in
the cursor, within threshold.

public override DataTable GetSchemaTable() [page 330] Returns a System.Data.DataTable value

that describes the column metadata of
the ULDataReader object.

public override unsafe String GetString(int) [page 332] Returns the value for the specified col­
umn as a System.String type.

public unsafe TimeSpan GetTimeSpan(int) [page 333] Returns the value for the specified col­
umn as a System.TimeSpan type with
millisecond accuracy.

public unsafe ushort GetUInt16(int) [page 334] Returns the value for the specified col­
umn as a System.UInt16 type.

public unsafe uint GetUInt32(int) [page 335] Returns the value for the specified col­
umn as a System.UInt32 type.

public unsafe ulong GetUInt64(int) [page 336] Returns the value for the specified col­
umn as a System.UInt64 type.

public override object GetValue(int) [page 337] Returns the value of the specified col­
umn in its native format.

public override int GetValues(object[]) [page 338] Returns all the column values for the
current row.

public override unsafe bool HasRows [page 348] Checks whether the ULDataReader ob­
ject has one or more rows.

public unsafe bool IsBOF [page 348] UL Ext: Checks whether the current row
position is before the first row.

public override bool IsClosed [page 349] Checks whether the cursor is currently
open.

public override unsafe bool IsDBNull(int) [page 339] Checks whether the value from the
specified column is NULL.

public unsafe bool IsEOF [page 349] UL Ext: Checks whether the current row
position is after the last row.

public void MoveAfterLast() [page 340] UL Ext: Positions the cursor to after the
last row of the cursor.

public void MoveBeforeFirst() [page 340] UL Ext: Positions the cursor to before
the first row of the cursor.

public unsafe bool MoveFirst() [page 341] UL Ext: Positions the cursor to the first
row of the cursor.

public unsafe bool MoveLast() [page 341] UL Ext: Positions the cursor to the last
row of the cursor.

public unsafe bool MoveNext() [page 342] UL Ext: Positions the cursor to the next
row or after the last row if the cursor
was already on the last row.

public unsafe bool MovePrevious() [page 343] UL Ext: Positions the cursor to the pre­
vious row or before the first row.

UltraLite - .NET API Reference

466 PUBLIC UltraLite .NET API reference
 Modifier and Type Member Description

public unsafe bool MoveRelative(int) [page 343] UL Ext: Positions the cursor relative to
the current row.

public override bool NextResult() [page 344] Advances the ULDataReader object to
the next result when reading the results
of batch SQL statements.

public override bool Read() [page 345] Positions the cursor to the next row, or
after the last row if the cursor was al­
ready on the last row.

public override int RecordsAffected [page 350] Returns the number of rows changed,
inserted, or deleted by execution of the
SQL statement.

public int RowCount [page 350] UL Ext: Returns the number of rows in
the cursor.

public ULCursorSchema Schema [page 351] UL Ext: Holds the schema of this cursor.

public override object this[int colID] [page 352] Returns the value of the specified col­
umn in its native format.

public override object this[string name] [page 353] Returns the value of the specified
named column in its native format.

protected void Validate() [page 346]

protected void Validate(int) [page 346]

Remarks

There is no constructor for this class. Result sets are created using the ULCommand.ExecuteResultSet
method.

' Visual Basic

Dim cmd As ULCommand = new ULCommand( _
"SELECT emp_id FROM employee", conn _
)
Dim resultSet As ULResultSet = cmd.ExecuteResultSet()

The following code is the C# language equivalent:

// C#
ULCommand cmd = new ULCommand(
"SELECT emp_id FROM employee", conn
);
ULResultSet resultSet = cmd.ExecuteResultSet();

A ULResultSet object represents an editable result set on which you can perform positioned updates and
deletes. For fully editable result sets, use the ULCommand.ExecuteTable method or the ULDataAdapter class.

In this section:

AppendBytes(int, byte[], int, int) method [page 469]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 467
 Appends the specified subset of the specified array of System.Bytes to the new value for the specified
ULDbType.LongBinary column.

AppendChars(int, char[], int, int) method [page 471]

Appends the specified subset of the specified array of System.Chars to the new value for the specified
ULDbType.LongVarchar column.

Delete() method [page 472]

Deletes the current row.

SetBoolean(int, bool) method [page 473]

Sets the value for the specified column using a System.Boolean.

SetByte(int, byte) method [page 474]

Sets the value for the specified column using a System.Byte (unsigned 8-bit integer).

SetBytes(int, byte[]) method [page 475]

Sets the value for the specified column using an array of System.Bytes.

SetDateTime(int, DateTime) method [page 476]

Sets the value for the specified column using a System.DateTime.

SetDBNull(int) method [page 477]

Sets a column to NULL.

SetDecimal(int, decimal) method [page 478]

Sets the value for the specified column using a System.Decimal.

SetDouble(int, double) method [page 479]

Sets the value for the specified column using a System.Double.

SetFloat(int, float) method [page 480]

Sets the value for the specified column using a System.Single.

SetGuid(int, Guid) method [page 481]

Sets the value for the specified column using a System.Guid.

SetInt16(int, short) method [page 483]

Sets the value for the specified column using a System.Int16.

SetInt32(int, int) method [page 484]

Sets the value for the specified column using a System.Int32.

SetInt64(int, long) method [page 485]

Sets the value for the specified column using an Int64.

SetString(int, string) method [page 486]

Sets the value for the specified column using a System.String.

SetTimeSpan(int, TimeSpan) method [page 487]

Sets the value for the specified column using a System.TimeSpan.

SetToDefault(int) method [page 488]

Sets the value for the specified column to its default value.

SetUInt16(int, ushort) method [page 489]

Sets the value for the specified column using a System.UInt16.

SetUInt32(int, uint) method [page 490]

Sets the value for the specified column using a System.UInt32.

SetUInt64(int, ulong) method [page 492]

UltraLite - .NET API Reference

468 PUBLIC UltraLite .NET API reference
 Sets the value for the specified column using a System.UInt64.

Update() method [page 493]

Updates the current row with the current column values (specified using the set methods).

UpdateBegin() method [page 493]

Prepares to update the current row.

Related Information

ExecuteResultSet() method [page 119]

ULCommand class [page 88]
ExecuteTable() method [page 124]
ULDataAdapter class [page 267]
ULDataReader class [page 302]

4.1.26.1 AppendBytes(int, byte[], int, int) method

Appends the specified subset of the specified array of System.Bytes to the new value for the specified
ULDbType.LongBinary column.

 Syntax

Visual Basic

Public Sub AppendBytes (

ByVal colID As Integer,
ByVal val As Byte(),
ByVal srcOffset As Integer,
ByVal count As Integer
)

C#

public unsafe void AppendBytes (

int colID,
byte[] val,
int srcOffset,
int count
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The value to append to the current new value for the column.
srcOffset The start position in the source array.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 469
 count The number of bytes to be copied.

Exceptions

ULException class A SQL error occurred.

Remarks

The bytes at position srcOffset (starting from 0) through srcOffset +count -1 of the array val are appended to
the value for the specified column.

When inserting, ULTable.InsertBegin initializes the new value to the column's default value. The data in the row
is not actually changed until you execute an ULTable.Insert, and changes are not made permanent until
committed.

When updating, the first append on a column clears the current value prior to appending the new value.

If any of the following are true, a ULException with code ULSQLCode.SQLE_INVALID_PARAMETER is thrown
and the destination is not modified:

● val is null.
● srcOffset is negative.
● count is negative.
● srcOffset +count is greater than the val length.

For other errors, a ULException with the appropriate error code is thrown.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
InsertBegin() method [page 569]
Insert() method [page 568]
ULException class [page 354]
ULException class [page 354]
FieldCount property [page 347]

UltraLite - .NET API Reference

470 PUBLIC UltraLite .NET API reference
4.1.26.2 AppendChars(int, char[], int, int) method

Appends the specified subset of the specified array of System.Chars to the new value for the specified
ULDbType.LongVarchar column.

 Syntax

Visual Basic

Public Sub AppendChars (

ByVal colID As Integer,
ByVal val As Char(),
ByVal srcOffset As Integer,
ByVal count As Integer
)

C#

public unsafe void AppendChars (

int colID,
char[] val,
int srcOffset,
int count
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The value to append to the current new value for the column.
srcOffset The start position in the source array.
count The number of bytes to be copied.

Exceptions

ULException class A SQL error occurred.

Remarks

The characters at position srcOffset (starting from 0) through srcOffset +count -1 of the array val are appended
to the value for the specified column. When inserting, ULTable.InsertBegin initializes the new value to the
column's default value. The data in the row is not actually changed until you execute an ULTable.Insert, and
changes are not made permanent until committed.

When updating, the first append on a column clears the current value prior to appending the new value.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 471
If any of the following is true, a ULException with code ULSQLCode.SQLE_INVALID_PARAMETER is thrown and
the destination is not modified:

● val is null.
● srcOffset is negative.
● count is negative.
● srcOffset +count is greater than val length.

For other errors, a ULException with the appropriate error code is thrown.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
InsertBegin() method [page 569]
Insert() method [page 568]
ULException class [page 354]
FieldCount property [page 347]

4.1.26.3 Delete() method

Deletes the current row.

 Syntax

Visual Basic

Public Sub Delete ()

C#

public void Delete ()

Exceptions

ULException class A SQL error occurred.

Related Information

StartSynchronizationDelete() method [page 198]

UltraLite - .NET API Reference

472 PUBLIC UltraLite .NET API reference
StopSynchronizationDelete() method [page 199]

4.1.26.4 SetBoolean(int, bool) method

Sets the value for the specified column using a System.Boolean.

 Syntax

Visual Basic

Public Sub SetBoolean (

ByVal colID As Integer,
ByVal val As Boolean
)

C#

public void SetBoolean (

int colID,
bool val
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The new value for the column.

Exceptions

ULException class A SQL error occurred.

Remarks

The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 473
Schema property [page 351]
GetFieldType(int) method [page 321]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

4.1.26.5 SetByte(int, byte) method

Sets the value for the specified column using a System.Byte (unsigned 8-bit integer).

 Syntax

Visual Basic

Public Sub SetByte (

ByVal colID As Integer,
ByVal val As Byte
)

C#

public void SetByte (

int colID,
byte val
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The new value for the column.

Exceptions

ULException class A SQL error occurred.

Remarks

The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed.

UltraLite - .NET API Reference

474 PUBLIC UltraLite .NET API reference
Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

4.1.26.6 SetBytes(int, byte[]) method

Sets the value for the specified column using an array of System.Bytes.

 Syntax

Visual Basic

Public Sub SetBytes (

ByVal colID As Integer,
ByVal val As Byte()
)

C#

public unsafe void SetBytes (

int colID,
byte[] val
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The new value for the column.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 475
Remarks

Only suitable for columns of type ULDbType.Binary or ULDbType.LongBinary, or for columns of type
ULDbType.UniqueIdentifier when the value is of length 16. The data in the row is not actually changed until you
execute a ULTable.Insert or Update method, and changes are not made permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

4.1.26.7 SetDateTime(int, DateTime) method

Sets the value for the specified column using a System.DateTime.

 Syntax

Visual Basic

Public Sub SetDateTime (

ByVal colID As Integer,
ByVal val As Date
)

C#

public unsafe void SetDateTime (

int colID,
DateTime val
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The new value for the column.

UltraLite - .NET API Reference

476 PUBLIC UltraLite .NET API reference
Exceptions

ULException class A SQL error occurred.

Remarks

The set value is accurate to the millisecond. The data in the row is not actually changed until you execute a
ULTable.Insert or Update method, and changes are not made permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

4.1.26.8 SetDBNull(int) method

Sets a column to NULL.

 Syntax

Visual Basic

Public Sub SetDBNull (ByVal colID As Integer)

C#

public void SetDBNull (int colID)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 477
Exceptions

ULException class A SQL error occurred.

Remarks

The data is not actually changed until you execute an ULTable.Insert or Update, and changes are not made
permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
IsColumnNullable(int) method [page 594]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

4.1.26.9 SetDecimal(int, decimal) method

Sets the value for the specified column using a System.Decimal.

 Syntax

Visual Basic

Public Sub SetDecimal (

ByVal colID As Integer,
ByVal val As Decimal
)

C#

public void SetDecimal (

int colID,
decimal val
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

UltraLite - .NET API Reference

478 PUBLIC UltraLite .NET API reference
 val The new value for the column.

Exceptions

ULException class A SQL error occurred.

Remarks

The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

4.1.26.10 SetDouble(int, double) method

Sets the value for the specified column using a System.Double.

 Syntax

Visual Basic

Public Sub SetDouble (

ByVal colID As Integer,
ByVal val As Double
)

C#

public void SetDouble (

int colID,
double val
)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 479
Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The new value for the column.

Exceptions

ULException class A SQL error occurred.

Remarks

The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

4.1.26.11 SetFloat(int, float) method

Sets the value for the specified column using a System.Single.

 Syntax

Visual Basic

Public Sub SetFloat (

ByVal colID As Integer,
ByVal val As Single
)

C#

public void SetFloat (

int colID,
float val

UltraLite - .NET API Reference

480 PUBLIC UltraLite .NET API reference
 )

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The new value for the column.

Exceptions

ULException class A SQL error occurred.

Remarks

The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

4.1.26.12 SetGuid(int, Guid) method

Sets the value for the specified column using a System.Guid.

 Syntax

Visual Basic

Public Sub SetGuid (

ByVal colID As Integer,
ByVal val As Guid
)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 481
 C#

public unsafe void SetGuid (

int colID,
Guid val
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The new value for the column.

Exceptions

ULException class A SQL error occurred.

Remarks

The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed. Only valid for columns of type ULDbType.UniqueIdentifier or for
columns of type ULDbType.Binary with a length of 16.

Related Information

GetNewUUID() method [page 184]

GetOrdinal(string) method [page 328]
Schema property [page 351]
GetFieldType(int) method [page 321]
GetColumnSize(int) method [page 262]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

UltraLite - .NET API Reference

482 PUBLIC UltraLite .NET API reference
4.1.26.13 SetInt16(int, short) method

Sets the value for the specified column using a System.Int16.

 Syntax

Visual Basic

Public Sub SetInt16 (

ByVal colID As Integer,
ByVal val As Short
)

C#

public void SetInt16 (

int colID,
short val
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The new value for the column.

Exceptions

ULException class A SQL error occurred.

Remarks

The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
Insert() method [page 568]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 483
Update() method [page 493]
FieldCount property [page 347]

4.1.26.14 SetInt32(int, int) method

Sets the value for the specified column using a System.Int32.

 Syntax

Visual Basic

Public Sub SetInt32 (

ByVal colID As Integer,
ByVal val As Integer
)

C#

public void SetInt32 (

int colID,
int val
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The new value for the column.

Exceptions

ULException class A SQL error occurred.

Remarks

The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed.

UltraLite - .NET API Reference

484 PUBLIC UltraLite .NET API reference
Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

4.1.26.15 SetInt64(int, long) method

Sets the value for the specified column using an Int64.

 Syntax

Visual Basic

Public Sub SetInt64 (

ByVal colID As Integer,
ByVal val As Long
)

C#

public void SetInt64 (

int colID,
long val
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The new value for the column.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 485
Remarks

The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

4.1.26.16 SetString(int, string) method

Sets the value for the specified column using a System.String.

 Syntax

Visual Basic

Public Sub SetString (

ByVal colID As Integer,
ByVal val As String
)

C#

public unsafe void SetString (

int colID,
string val
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The new value for the column.

UltraLite - .NET API Reference

486 PUBLIC UltraLite .NET API reference
Exceptions

ULException class A SQL error occurred.

Remarks

The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

4.1.26.17 SetTimeSpan(int, TimeSpan) method

Sets the value for the specified column using a System.TimeSpan.

 Syntax

Visual Basic

Public Sub SetTimeSpan (

ByVal colID As Integer,
ByVal val As TimeSpan
)

C#

public unsafe void SetTimeSpan (

int colID,
TimeSpan val
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 487
 val The new value for the column.

Exceptions

ULException class A SQL error occurred.

Remarks

The set value is accurate to the millisecond and is normalized to a nonnegative value between 0 and 24 hours.
The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

4.1.26.18 SetToDefault(int) method

Sets the value for the specified column to its default value.

 Syntax

Visual Basic

Public Sub SetToDefault (ByVal colID As Integer)

C#

public void SetToDefault (int colID)

UltraLite - .NET API Reference

488 PUBLIC UltraLite .NET API reference
Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.

Exceptions

ULException class A SQL error occurred.

Remarks

The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
GetColumnDefaultValue(int) method [page 582]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

4.1.26.19 SetUInt16(int, ushort) method

Sets the value for the specified column using a System.UInt16.

 Syntax

Visual Basic

Public Sub SetUInt16 (

ByVal colID As Integer,
ByVal val As UShort
)

C#

public void SetUInt16 (

int colID,
ushort val

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 489
 )

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The new value for the column.

Exceptions

ULException class A SQL error occurred.

Remarks

The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

GetFieldType(int) method [page 321]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

4.1.26.20 SetUInt32(int, uint) method

Sets the value for the specified column using a System.UInt32.

 Syntax

Visual Basic

Public Sub SetUInt32 (

ByVal colID As Integer,
ByVal val As UInteger
)

UltraLite - .NET API Reference

490 PUBLIC UltraLite .NET API reference
 C#

public void SetUInt32 (

int colID,
uint val
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The new value for the column.

Exceptions

ULException class A SQL error occurred.

Remarks

The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
Insert() method [page 568]
Update() method [page 493]
FieldCount property [page 347]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 491
4.1.26.21 SetUInt64(int, ulong) method

Sets the value for the specified column using a System.UInt64.

 Syntax

Visual Basic

Public Sub SetUInt64 (

ByVal colID As Integer,
ByVal val As ULong
)

C#

public void SetUInt64 (

int colID,
ulong val
)

Parameters

colID The ID number of the column. The value must be in the range [0,ULDataReader.FieldCount-1]. The
first column in the cursor has an ID value of zero.
val The new value for the column.

Exceptions

ULException class A SQL error occurred.

Remarks

The data in the row is not actually changed until you execute a ULTable.Insert or Update method, and changes
are not made permanent until committed.

Related Information

GetOrdinal(string) method [page 328]

Schema property [page 351]
GetFieldType(int) method [page 321]
Insert() method [page 568]

UltraLite - .NET API Reference

492 PUBLIC UltraLite .NET API reference
Update() method [page 493]
FieldCount property [page 347]

4.1.26.22 Update() method

Updates the current row with the current column values (specified using the set methods).

 Syntax

Visual Basic

Public Sub Update ()

C#

public void Update ()

Exceptions

ULException class A SQL error occurred.

Related Information

UpdateBegin() method [page 493]

4.1.26.23 UpdateBegin() method

Prepares to update the current row.

 Syntax

Visual Basic

Public Sub UpdateBegin ()

C#

public void UpdateBegin ()

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 493
Exceptions

ULException class A SQL error occurred.

Remarks

Column values are modified by calling the appropriate setType or AppendType method(s). The first append on
a column clears the current column value prior to appending the new value.

The data in the row is not actually changed until you call the Update method, and changes are not made
permanent until committed.

Modifying columns in the index used to open the table affects active searches in unpredictable ways. Columns
in the primary key of the table can not be updated.

Related Information

Update() method [page 493]

4.1.27 ULResultSetSchema class

UL Ext: Represents the schema of an UltraLite result set.

 Syntax

Visual Basic

Public NotInheritable Class ULResultSetSchema Inherits ULCursorSchema

C#

public sealed class ULResultSetSchema : ULCursorSchema

Members

All members of ULResultSetSchema, including inherited members.

Methods

Modifier and Type Method Description

protected virtual override void VerifyOpen() [page 496]

UltraLite - .NET API Reference

494 PUBLIC UltraLite .NET API reference
Properties

Modifier and Type Property Description

public override string Name [page 496] Returns the name of the cursor.

Inherited members from ULCursorSchema

Modifier and Type Member Description

public short ColumnCount [page 266] Returns the number of columns in the
cursor.

protected unsafe void GetColumnCount() [page 258]

public unsafe short GetColumnID(string) [page 258] Returns the column ID of the named
column.

public string GetColumnName(int) [page 259] Returns the name of the column identi­
fied by the specified column ID.

public unsafe int GetColumnPrecision(int) [page 260] Returns the precision of the column
identified by the specified column ID if
the column is a numeric column (the
NUMERIC SQL type).

public unsafe int GetColumnScale(int) [page 261] Returns the scale of the column identi­
fied by the specified column ID if the
column is a numeric column (the NU­
MERIC SQL type).

public unsafe int GetColumnSize(int) [page 262] Returns the size of the column identi­
fied by the specified column ID if the
column is a sized column (the BINARY
or CHAR SQL types).

public string GetColumnSQLName(int) [page 263] Returns the name of the column identi­
fied by the specified column ID.

public unsafe ULDbType GetColumnULDbType(int) [page 264] Returns the UltraLite.NET data type of
the column identified by the specified
column ID.

public unsafe DataTable GetSchemaTable() [page 265] Returns a System.Data.DataTable that

describes the column schema of the
ULDataReader object.

public bool IsOpen [page 266] Checks whether the cursor schema is
currently open.

Remarks

There is no constructor for this class. A ULResultSetSchema object is attached to a result set as its
ULDataReader.Schema property.

A result set schema is only valid while the data reader is open.

In this section:

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 495
 VerifyOpen() method [page 496]

Name property [page 496]

Returns the name of the cursor.

Related Information

ULCommand class [page 88]

ULDataReader class [page 302]
Schema property [page 351]
ULCursorSchema class [page 255]

4.1.27.1 VerifyOpen() method

 Syntax

Visual Basic

Protected Overridable Overrides Sub VerifyOpen ()

C#

protected virtual override void VerifyOpen ()

4.1.27.2 Name property

Returns the name of the cursor.

 Syntax

Visual Basic

Public ReadOnly Overrides Property Name As String

C#

public override string Name {get;}

Remarks

The SQL statement that generated the ULResultSetSchema.

UltraLite - .NET API Reference

496 PUBLIC UltraLite .NET API reference
4.1.28 ULRowsCopiedEventArgs class

Represents the set of arguments passed to the ULRowsCopiedEventHandler object.

 Syntax

Visual Basic

Public NotInheritable Class ULRowsCopiedEventArgs

C#

public sealed class ULRowsCopiedEventArgs

Members

All members of ULRowsCopiedEventArgs, including inherited members.

Constructors

Modifier and Type Constructor Description

public ULRowsCopiedEventArgs(long) [page Creates a new instance of the ULRows­

498] CopiedEventArgs object.

Properties

Modifier and Type Property Description

public bool Abort [page 498] Gets or sets a value that indicates
whether the bulk-copy operation should
be aborted.

public long RowsCopied [page 499] Returns the number of rows copied dur­
ing the current bulk-copy operation.

Remarks

The ULRowsCopiedEventArgs class is not available in the .NET Compact Framework 2.0.

In this section:

ULRowsCopiedEventArgs(long) constructor [page 498]

Creates a new instance of the ULRowsCopiedEventArgs object.

Abort property [page 498]

Gets or sets a value that indicates whether the bulk-copy operation should be aborted.

RowsCopied property [page 499]

Returns the number of rows copied during the current bulk-copy operation.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 497
Related Information

ULRowsCopiedEventHandler(object, ULRowsCopiedEventArgs) delegate [page 604]

4.1.28.1 ULRowsCopiedEventArgs(long) constructor

Creates a new instance of the ULRowsCopiedEventArgs object.

 Syntax

Visual Basic

Public Sub ULRowsCopiedEventArgs (ByVal rowsCopied As Long)

C#

public ULRowsCopiedEventArgs (long rowsCopied)

Parameters

rowsCopied A 64-bit integer value that indicates the number of rows copied during the current bulk-copy
operation.

Remarks

The ULRowsCopiedEventArgs class is not available in the .NET Compact Framework 2.0.

4.1.28.2 Abort property

Gets or sets a value that indicates whether the bulk-copy operation should be aborted.

 Syntax

Visual Basic

Public Property Abort As Boolean

C#

public bool Abort {get;set;}

UltraLite - .NET API Reference

498 PUBLIC UltraLite .NET API reference
Remarks

The ULRowsCopiedEventArgs class is not available in the .NET Compact Framework 2.0.

4.1.28.3 RowsCopied property

Returns the number of rows copied during the current bulk-copy operation.

 Syntax

Visual Basic

Public ReadOnly Property RowsCopied As Long

C#

public long RowsCopied {get;}

Remarks

A long integer representing the number of rows copied.

The ULRowsCopiedEventArgs class is not available in the .NET Compact Framework 2.0.

4.1.29 ULRowUpdatedEventArgs class

Provides data for the ULDataAdapter.RowUpdated event.

 Syntax

Visual Basic

Public NotInheritable Class ULRowUpdatedEventArgs Inherits

System.Data.Common.RowUpdatedEventArgs

C#

public sealed class ULRowUpdatedEventArgs :

System.Data.Common.RowUpdatedEventArgs

Members

All members of ULRowUpdatedEventArgs, including inherited members.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 499
Constructors

Modifier and Type Constructor Description

public ULRowUpdatedEventArgs(DataRow, Initializes a new instance of the ULRo­

IDbCommand, StatementType, DataTa­ wUpdatedEventArgs class.
bleMapping) [page 500]

Properties

Modifier and Type Property Description

public new ULCommand Command [page 501] Returns the ULCommand object exe­
cuted when the DbDataAdapter.Update
method is called.

public new int RecordsAffected [page 502] Returns the number of rows changed,
inserted, or deleted by the execution of
the SQL statement.

In this section:

ULRowUpdatedEventArgs(DataRow, IDbCommand, StatementType, DataTableMapping) constructor

[page 500]
Initializes a new instance of the ULRowUpdatedEventArgs class.

Command property [page 501]

Returns the ULCommand object executed when the DbDataAdapter.Update method is called.

RecordsAffected property [page 502]

Returns the number of rows changed, inserted, or deleted by the execution of the SQL statement.

Related Information

RowUpdated event [page 281]

4.1.29.1 ULRowUpdatedEventArgs(DataRow, IDbCommand,

StatementType, DataTableMapping) constructor

Initializes a new instance of the ULRowUpdatedEventArgs class.

 Syntax

Visual Basic

Public Sub ULRowUpdatedEventArgs (

ByVal row As DataRow,
ByVal command As IDbCommand,
ByVal statementType As StatementType,
ByVal tableMapping As DataTableMapping
)

UltraLite - .NET API Reference

500 PUBLIC UltraLite .NET API reference
 C#

public ULRowUpdatedEventArgs (
DataRow row,
IDbCommand command,
StatementType statementType,
DataTableMapping tableMapping
)

Parameters

row The System.Data.DataRow sent through a DbDataAdapter.Update call.

command The System.Data.IDbCommand executed when the DbDataAdapter.Update method is called.
statementType One of the System.Data.StatementType values that specifies the type of query executed.
tableMapping The System.Data.Common.DataTableMapping sent through a DbDataAdapter.Update call.

4.1.29.2 Command property

Returns the ULCommand object executed when the DbDataAdapter.Update method is called.

 Syntax

Visual Basic

Public ReadOnly Shadows Property Command As ULCommand

C#

public new ULCommand Command {get;}

Remarks

The ULCommand object executed by the update.

This is the strongly-typed version of System.Data.Common.RowUpdatedEventArgs.Command.

Related Information

ULCommand class [page 88]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 501
4.1.29.3 RecordsAffected property

Returns the number of rows changed, inserted, or deleted by the execution of the SQL statement.

 Syntax

Visual Basic

Public ReadOnly Shadows Property RecordsAffected As Integer

C#

public new int RecordsAffected {get;}

Remarks

For SELECT statements this value is -1.

The number of rows changed, inserted, or deleted; 0 if no rows were affected or the statement failed; and -1 for
SELECT statements.

4.1.30 ULRowUpdatingEventArgs class

Provides data for the ULDataAdapter.RowUpdating event.

 Syntax

Visual Basic

Public NotInheritable Class ULRowUpdatingEventArgs Inherits

System.Data.Common.RowUpdatingEventArgs

C#

public sealed class ULRowUpdatingEventArgs :

System.Data.Common.RowUpdatingEventArgs

Members

All members of ULRowUpdatingEventArgs, including inherited members.

Constructors

UltraLite - .NET API Reference

502 PUBLIC UltraLite .NET API reference
 Modifier and Type Constructor Description

public ULRowUpdatingEventArgs(DataRow, Initializes a new instance of the ULRo­

IDbCommand, StatementType, DataTa­ wUpdatingEventArgs class.
bleMapping) [page 503]

Properties

Modifier and Type Property Description

public new ULCommand Command [page 504] Specifies the ULCommand object to ex­
ecute when performing the DbDataA­
dapter.Update method.

In this section:

ULRowUpdatingEventArgs(DataRow, IDbCommand, StatementType, DataTableMapping) constructor

[page 503]
Initializes a new instance of the ULRowUpdatingEventArgs class.

Command property [page 504]

Specifies the ULCommand object to execute when performing the DbDataAdapter.Update method.

Related Information

RowUpdating event [page 282]

4.1.30.1 ULRowUpdatingEventArgs(DataRow, IDbCommand,

StatementType, DataTableMapping) constructor

Initializes a new instance of the ULRowUpdatingEventArgs class.

 Syntax

Visual Basic

Public Sub ULRowUpdatingEventArgs (

ByVal row As DataRow,
ByVal command As IDbCommand,
ByVal statementType As StatementType,
ByVal tableMapping As DataTableMapping
)

C#

public ULRowUpdatingEventArgs (
DataRow row,
IDbCommand command,
StatementType statementType,
DataTableMapping tableMapping

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 503
 )

Parameters

row The System.Data.DataRow to update.

command The System.Data.IDbCommand to execute during the update.
statementType One of the System.Data.StatementType values that specifies the type of query executed.
tableMapping The System.Data.Common.DataTableMapping value sent through a DbDataAdapter.Update
call.

4.1.30.2 Command property

Specifies the ULCommand object to execute when performing the DbDataAdapter.Update method.

 Syntax

Visual Basic

Public Shadows Property Command As ULCommand

C#

public new ULCommand Command {get;set;}

Remarks

The ULCommand object to execute when updating.

This is the strongly-typed version of the System.Data.Common.RowUpdatingEventArgs.Command value.

Related Information

ULCommand class [page 88]

UltraLite - .NET API Reference

504 PUBLIC UltraLite .NET API reference
4.1.31 ULServerSyncListener interface

UL Ext: The listener interface for receiving server synchronization messages.

 Syntax

Visual Basic

Public Interface ULServerSyncListener

C#

public interface ULServerSyncListener

Members

All members of ULServerSyncListener, including inherited members.

Methods

Modifier and Type Method Description

public void ServerSyncInvoked(string) [page 505] Invoked when the MobiLink Listener for
server-initiated synchronizations calls
the application to perform synchroniza­
tion.

In this section:

ServerSyncInvoked(string) method [page 505]

Invoked when the MobiLink Listener for server-initiated synchronizations calls the application to
perform synchronization.

4.1.31.1 ServerSyncInvoked(string) method

Invoked when the MobiLink Listener for server-initiated synchronizations calls the application to perform
synchronization.

 Syntax

Visual Basic

Public Sub ServerSyncInvoked (ByVal messageName As String)

C#

public void ServerSyncInvoked (string messageName)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 505
Parameters

messageName The name of the message sent to the application.

Remarks

This method is invoked by a separate thread. To avoid multi-threading issues, it should post an event to the UI.
If you are using multi-threading, use a separate connection and use the lock keyword to access any objects
shared with the rest of the application.

 Example

Imports Sap.Data.UltraLite

Public Class MainWindow Inherits System.Windows.Forms.Form Implements ULServerSyncListener

Private conn As ULConnection

Public Sub New(ByVal args() As String) MyBase.New()

'This call is required by the Windows Form Designer. InitializeComponent()

'Add any initialization after the InitializeComponent() call

ULConnection.DatabaseManager.SetServerSyncListener( _ "myCompany.mymsg", "myCompany.myapp",
Me _ ) 'Create Connection ... End Sub

Protected Overrides Sub OnClosing( _ ByVal e As System.ComponentModel.CancelEventArgs _ )

ULConnection.DatabaseManager.SetServerSyncListener( _ Nothing, Nothing, Nothing _ )
MyBase.OnClosing(e) End Sub

Public Sub ServerSyncInvoked(ByVal messageName As String) _ Implements

ULServerSyncListener.ServerSyncInvoked

Me.Invoke(New EventHandler(AddressOf Me.ServerSyncAction)) End Sub

Public Sub ServerSyncAction( _ ByVal sender As Object, ByVal e As EventArgs _ ) ' Do Server sync
conn.Synchronize() End Sub End Class

The following C# code demonstrates how to receive a server synchronization request and perform a
synchronization in the UI thread.

using Sap.Data.UltraLite;
public class Form1 : System.Windows.Forms.Form, ULServerSyncListener
{
private System.Windows.Forms.MainMenu mainMenu1;
private ULConnection conn;
public Form1()
{
//
// Required for Windows Form Designer support
//
InitializeComponent();
//
// TODO: Add any constructor code after
// InitializeComponent call
//
ULConnection.DatabaseManager.SetServerSyncListener(

UltraLite - .NET API Reference

506 PUBLIC UltraLite .NET API reference
 "myCompany.mymsg", "myCompany.myapp", this
);
// Create connection
...
}
protected override void Dispose( bool disposing )
{
base.Dispose( disposing );
}
protected override void OnClosing(
System.ComponentModel.CancelEventArgs e)
{
ULConnection.DatabaseManager.SetServerSyncListener(
null, null, null
);
base.OnClosing(e);
}
public void ServerSyncInvoked( string messageName )
{
this.Invoke( new EventHandler( ServerSyncHandler ) );
}
internal void ServerSyncHandler(object sender, EventArgs e)
{
conn.Synchronize();
}
}

4.1.32 ULSqlProgressData class (Deprecated)

UL Ext: Returns SQL passthrough script progress monitoring data.

 Syntax

Microsoft Visual Basic

Public Class ULSqlProgressData

C#

public class ULSqlProgressData

Members

All members of ULSqlProgressData, including inherited members.

Properties

Modifier and Type Property Description

public long CurrentScript [page 508] The index of the scripts executed so far.

public long ScriptCount [page 508] Returns the number of scripts being
executed.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 507
Modifier and Type Property Description

public ULSqlProgressState State [page 509] Returns the current progress state.

In this section:

CurrentScript property [page 508]

The index of the scripts executed so far.

ScriptCount property [page 508]

Returns the number of scripts being executed.

State property [page 509]

Returns the current progress state.

4.1.32.1 CurrentScript property

The index of the scripts executed so far.

 Syntax

Visual Basic

Public ReadOnly Property CurrentScript As Long

C#

public long CurrentScript {get;}

Remarks

The current index of the scripts being executed.

4.1.32.2 ScriptCount property

Returns the number of scripts being executed.

 Syntax

Visual Basic

Public ReadOnly Property ScriptCount As Long

C#

public long ScriptCount {get;}

UltraLite - .NET API Reference

508 PUBLIC UltraLite .NET API reference
Remarks

The number of scripts being executed.

4.1.32.3 State property

Returns the current progress state.

 Syntax

Visual Basic

Public ReadOnly Property State As ULSqlProgressState

C#

public ULSqlProgressState State {get;}

Remarks

One of the ULSqlProgressState values specifying the current SQL passthrough callback state.

Related Information

ULSyncProgressState enumeration [page 616]

4.1.33 ULSyncParms class

UL Ext: Represents synchronization parameters that define how to synchronize an UltraLite database.

 Syntax

Visual Basic

Public NotInheritable Class ULSyncParms

C#

public sealed class ULSyncParms

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 509
Members

All members of ULSyncParms, including inherited members.

Methods

Modifier and Type Method Description

public void CopyFrom(ULSyncParms) [page 512] Copies the properties of the specified
ULSyncParms object to this ULSync­
Parms object.

public override string ToString() [page 513] Returns the string representation of
this instance.

Properties

Modifier and Type Property Description

public string AdditionalParms [page 513] Specifies additional synchronization

parameters as a semicolon-separated
list of name=value pairs.

public string[] AuthenticationParms [page 514] Specifies parameters for a custom user
authentication script (MobiLink authen­
ticate_parameters connection event).

public bool DownloadOnly [page 515] Specifies whether to disable or enable

uploads when synchronizing.

public bool KeepPartialDownload [page 516] Specifies whether to disable or enable

partial downloads when synchronizing.

public string NewPassword [page 517] Specifies a new MobiLink password for
the user specified with UserName.

public string Password [page 518] The MobiLink password for the user
specified by UserName.

public bool PingOnly [page 518] Specifies whether the client should only
ping the MobiLink server instead of per­
forming a real synchronization.

public string Publications [page 519] Specifies the publications to be

synchronized.

public bool ResumePartialDownload [page 520] Specifies whether to resume or discard

a previous partial download.

public bool SendDownloadAck [page 521] Specifies whether the client should
send a download acknowledgement to
the MobiLink server during synchroni­
zation.

public ULStreamType Stream [page 521] Specifies the MobiLink synchronization

stream to use for synchronization.

public string StreamParms [page 522] Specifies the parameters to configure

the synchronization stream.

public bool UploadOnly [page 523] Specifies whether to disable or enable

downloads when synchronizing.

UltraLite - .NET API Reference

510 PUBLIC UltraLite .NET API reference
 Modifier and Type Property Description

public string UserName [page 524] The user name that uniquely identifies
the MobiLink client to the MobiLink
server.

public string Version [page 525] Specifies which synchronization script

to use.

Remarks

There is no constructor for this class. Each connection has its own ULSyncParms instance, attached as its
ULConnection.SyncParms property.

At most, only one synchronization command (the ULSyncParms.DownloadOnly, ULSyncParms.PingOnly,

ULSyncParms.ResumePartialDownload, or ULSyncParms.UploadOnly property) can be specified at a time. If
more than one of these parameters is set to true, a ULSQLCode.SQLE_SYNC_INFO_INVALID SQLException is
thrown by the ULConnection.Synchronize method.

Other sources of ULSQLCode.SQLE_SYNC_INFO_INVALID errors include not specifying a

ULSyncParms.Stream value or a ULSyncParms.Version value.

In this section:

CopyFrom(ULSyncParms) method [page 512]

Copies the properties of the specified ULSyncParms object to this ULSyncParms object.

ToString() method [page 513]

Returns the string representation of this instance.

AdditionalParms property [page 513]

Specifies additional synchronization parameters as a semicolon-separated list of name=value pairs.

AuthenticationParms property [page 514]

Specifies parameters for a custom user authentication script (MobiLink authenticate_parameters
connection event).

DownloadOnly property [page 515]

Specifies whether to disable or enable uploads when synchronizing.

KeepPartialDownload property [page 516]

Specifies whether to disable or enable partial downloads when synchronizing.

NewPassword property [page 517]

Specifies a new MobiLink password for the user specified with UserName.

Password property [page 518]

The MobiLink password for the user specified by UserName.

PingOnly property [page 518]

Specifies whether the client should only ping the MobiLink server instead of performing a real
synchronization.

Publications property [page 519]

Specifies the publications to be synchronized.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 511
 ResumePartialDownload property [page 520]
Specifies whether to resume or discard a previous partial download.

SendDownloadAck property [page 521]

Specifies whether the client should send a download acknowledgement to the MobiLink server during
synchronization.

Stream property [page 521]

Specifies the MobiLink synchronization stream to use for synchronization.

StreamParms property [page 522]

Specifies the parameters to configure the synchronization stream.

UploadOnly property [page 523]

Specifies whether to disable or enable downloads when synchronizing.

UserName property [page 524]

The user name that uniquely identifies the MobiLink client to the MobiLink server.

Version property [page 525]

Specifies which synchronization script to use.

Related Information

ULConnection class [page 151]

SyncParms property [page 212]
Synchronize() method [page 200]
DownloadOnly property [page 515]
PingOnly property [page 518]
ResumePartialDownload property [page 520]
UploadOnly property [page 523]
Synchronize() method [page 200]
Stream property [page 521]
Version property [page 525]

4.1.33.1 CopyFrom(ULSyncParms) method

Copies the properties of the specified ULSyncParms object to this ULSyncParms object.

 Syntax

Visual Basic

Public Sub CopyFrom (ByVal src As ULSyncParms)

C#

public void CopyFrom (ULSyncParms src)

UltraLite - .NET API Reference

512 PUBLIC UltraLite .NET API reference
Parameters

src The object to copy from.

Related Information

ULSyncParms class [page 509]

4.1.33.2 ToString() method

Returns the string representation of this instance.

 Syntax

Visual Basic

Public Overrides Function ToString () As String

C#

public override string ToString ()

Returns

The string representation of this instance as a semicolon-separated list of keyword=value pairs.

4.1.33.3 AdditionalParms property

Specifies additional synchronization parameters as a semicolon-separated list of name=value pairs.

 Syntax

Visual Basic

Public Property AdditionalParms As String

C#

public string AdditionalParms {get;set;}

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 513
Returns

A string, in the form of a semicolon-separated list of name=value pairs.

Remarks

Use this property to specify several additional synchronization parameters that cannot be readily specified
using any other predefined parameters.

 Example

private ULSyncParms info;

// ...
info.AdditionalParms =
"AllowDownloadDupRows=1;
CheckpointStore=1;
DisableConcurrency=1;
TableOrder=Customer,Sales"

4.1.33.4 AuthenticationParms property

Specifies parameters for a custom user authentication script (MobiLink authenticate_parameters connection
event).

 Syntax

Visual Basic

Public Property AuthenticationParms As String()

C#

public string[] AuthenticationParms {get;set;}

Returns

An array of strings, each containing an authentication parameter (null array entries result in a synchronization
error). The default is a null reference (Nothing in Visual Basic), meaning no authentication parameters.

UltraLite - .NET API Reference

514 PUBLIC UltraLite .NET API reference
Remarks

Only the first 255 strings are used and each string should be no longer than the MobiLink server's limit for
authentication parameters (currently 4000 UTF8 bytes).

4.1.33.5 DownloadOnly property

Specifies whether to disable or enable uploads when synchronizing.

 Syntax

Visual Basic

Public Property DownloadOnly As Boolean

C#

public bool DownloadOnly {get;set;}

Returns

True to disable uploads when synchronizing, false to enable uploads. The default is false.

Remarks

At most, only one synchronization command (the ULSyncParms.DownloadOnly, ULSyncParms.PingOnly,

ULSyncParms.ResumePartialDownload, or ULSyncParms.UploadOnly property) can be specified at a time. If
more than one of these parameters is set to true, a ULSQLCode.SQLE_SYNC_INFO_INVALID SQLException is
thrown by the ULConnection.Synchronize method.

Related Information

UploadOnly property [page 523]

PingOnly property [page 518]
ResumePartialDownload property [page 520]
UploadOnly property [page 523]
Synchronize() method [page 200]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 515
4.1.33.6 KeepPartialDownload property

Specifies whether to disable or enable partial downloads when synchronizing.

 Syntax

Visual Basic

Public Property KeepPartialDownload As Boolean

C#

public bool KeepPartialDownload {get;set;}

Returns

Set to true to enable and save partial downloads while synchronizing; otherwise, set to false to disable partial
downloads and roll back downloads if any errors occur. The default is false.

Remarks

Using the ULSyncProgressListener object, UltraLite.NET can resume partial downloads that fail because of
communication errors or user aborts. UltraLite.NET processes the download as it is received. If a download is
interrupted, then the partial download transaction remains in the database and can be resumed during the
next synchronization.

If a partial download was kept, then the ULConnection.ULSyncResult.PartialDownloadRetained property is set

to true when the ULConnection.Synchronize method exits.

If the PartialDownloadRetained property is set, then you can resume a download. To do this, call the
ULConnection.Synchronize method with the ULConnection.ULSyncParms.ResumePartialDownload property
set to true. Keep the KeepPartialDownload property set to true in case another communications error occurs.
No upload is done if a download is skipped.

The download you receive during a resumed download is as old as when the download originally began. If you
need the most recent data, then you can do another download immediately after the resumed download
completes.

When resuming a download, many of the ULSyncParms properties are not relevant. For example, the
Publications property is not used. You receive the publications that you requested on the initial download. The
only properties that must be set are ResumePartialDownload and UserName. The KeepPartialDownload
property can be set if desired and functions as normal.

If you have a partial download that is no longer needed, call the ULConnection.RollbackPartialDownload
method to roll back the failed download transaction. If you attempt to synchronize again and do not specify the
ResumePartialDownload property, then the partial download is rolled back before the next synchronization
begins.

UltraLite - .NET API Reference

516 PUBLIC UltraLite .NET API reference
Related Information

PartialDownloadRetained property [page 545]

ResumePartialDownload property [page 520]
RollbackPartialDownload() method [page 195]
ResumePartialDownload property [page 520]
UserName property [page 524]
RollbackPartialDownload() method [page 195]

4.1.33.7 NewPassword property

Specifies a new MobiLink password for the user specified with UserName.

 Syntax

Visual Basic

Public Property NewPassword As String

C#

public string NewPassword {get;set;}

Returns

A string specifying a new MobiLink password. The default is a null reference (Nothing in Visual Basic), meaning
the password is not changed.

Remarks

A new password takes effect after the next synchronization.

Related Information

UserName property [page 524]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 517
4.1.33.8 Password property

The MobiLink password for the user specified by UserName.

 Syntax

Visual Basic

Public Property Password As String

C#

public string Password {get;set;}

Returns

A string specifying the MobiLink password. The default is a null reference (Nothing in Visual Basic), meaning no
password is specified.

Remarks

The MobiLink user name and password are separate from any database user ID and password, and serve to
identify and authenticate the application to the MobiLink server.

Related Information

NewPassword property [page 517]

UserName property [page 524]

4.1.33.9 PingOnly property

Specifies whether the client should only ping the MobiLink server instead of performing a real synchronization.

 Syntax

Visual Basic

Public Property PingOnly As Boolean

C#

public bool PingOnly {get;set;}

UltraLite - .NET API Reference

518 PUBLIC UltraLite .NET API reference
Returns

True to specify that the client should only ping the MobiLink server, false to specify the client should perform a
real synchronization. The default is false.

Remarks

At most, only one synchronization command (the ULSyncParms.DownloadOnly, ULSyncParms.PingOnly,

ULSyncParms.ResumePartialDownload, or ULSyncParms.UploadOnly property) can be specified at a time. If
more than one of these parameters is set to true, a ULSQLCode.SQLE_SYNC_INFO_INVALID SQLException is
thrown by the ULConnection.Synchronize method.

Related Information

DownloadOnly property [page 515]

ResumePartialDownload property [page 520]
UploadOnly property [page 523]
Synchronize() method [page 200]

4.1.33.10 Publications property

Specifies the publications to be synchronized.

 Syntax

Visual Basic

Public Property Publications As String

C#

public string Publications {get;set;}

Returns

A string containing a list of publication names, separated by comma (,); or the special value
ULConnection.SYNC_ALL_PUBS, or the special value ULConnection.SYNC_ALL_DB. The default is
ULConnection.SYNC_ALL_DB.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 519
4.1.33.11 ResumePartialDownload property

Specifies whether to resume or discard a previous partial download.

 Syntax

Visual Basic

Public Property ResumePartialDownload As Boolean

C#

public bool ResumePartialDownload {get;set;}

Returns

True to resume a previous partial download, false to discard a previous partial download. The default is false.

Remarks

Only at most one synchronization command (the ULSyncParms.DownloadOnly, ULSyncParms.PingOnly,

ULSyncParms.ResumePartialDownload, or ULSyncParms.UploadOnly property) can be specified at a time. If
more than one of these parameters is set to true, a ULSQLCode.SQLE_SYNC_INFO_INVALID SQLException is
thrown by the ULConnection.Synchronize method.

Related Information

KeepPartialDownload property [page 516]

DownloadOnly property [page 515]
PingOnly property [page 518]
UploadOnly property [page 523]
Synchronize() method [page 200]
PartialDownloadRetained property [page 545]

UltraLite - .NET API Reference

520 PUBLIC UltraLite .NET API reference
4.1.33.12 SendDownloadAck property

Specifies whether the client should send a download acknowledgement to the MobiLink server during
synchronization.

 Syntax

Visual Basic

Public Property SendDownloadAck As Boolean

C#

public bool SendDownloadAck {get;set;}

Returns

Set to true to specify that the client should send a download acknowledgement to the MobiLink server. Set to
false to specify that no download acknowledgement is sent. The default is false.

Remarks

The download acknowledgement is sent after the download has been fully applied and committed at the
remote (a positive acknowledgement) or after the download fails (a negative acknowledgement).

If the client sends a download acknowledgement, the MobiLink server database worker thread must wait for
the client to apply and commit the download. If the client does not sent a download acknowledgement, the
MobiLink server is freed up sooner for its next synchronization.

4.1.33.13 Stream property

Specifies the MobiLink synchronization stream to use for synchronization.

 Syntax

Visual Basic

Public Property Stream As ULStreamType

C#

public ULStreamType Stream {get;set;}

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 521
Returns

One of the ULStreamType values specifying the type of synchronization stream to use. The default value is
ULStreamType.TCPIP.

Remarks

Most synchronization streams require parameters to identify the MobiLink server address and control other
behavior. These parameters are supplied by the ULSyncParms.StreamParms property.

If the stream type is set to a value that is invalid for the platform, the stream type is set to ULStreamType.TCPIP.

Related Information

ULStreamType enumeration [page 615]

StreamParms property [page 522]

4.1.33.14 StreamParms property

Specifies the parameters to configure the synchronization stream.

 Syntax

Visual Basic

Public Property StreamParms As String

C#

public string StreamParms {get;set;}

Returns

A string, in the form of a semicolon-separated list of keyword=value pairs, specifying the parameters for the
stream. The default is a null reference (Nothing in Visual Basic).

UltraLite - .NET API Reference

522 PUBLIC UltraLite .NET API reference
Remarks

StreamParms is a string containing all the parameters used for synchronization streams. Parameters are
specified as a semicolon-separated list of name=value pairs ("param1=value1;param2=value2").

Related Information

Stream property [page 521]

ULStreamType enumeration [page 615]

4.1.33.15 UploadOnly property

Specifies whether to disable or enable downloads when synchronizing.

 Syntax

Visual Basic

Public Property UploadOnly As Boolean

C#

public bool UploadOnly {get;set;}

Returns

True to disable downloads, false to enable downloads. The default is false.

Remarks

At most, only one synchronization command (the ULSyncParms.DownloadOnly, ULSyncParms.PingOnly,

ULSyncParms.ResumePartialDownload, or ULSyncParms.UploadOnly property) can be specified at a time. If
more than one of these parameters is set to true, a ULSQLCode.SQLE_SYNC_INFO_INVALID SQLException is
thrown by the ULConnection.Synchronize method.

Related Information

DownloadOnly property [page 515]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 523
PingOnly property [page 518]
ResumePartialDownload property [page 520]
Synchronize() method [page 200]

4.1.33.16 UserName property

The user name that uniquely identifies the MobiLink client to the MobiLink server.

 Syntax

Visual Basic

Public Property UserName As String

C#

public string UserName {get;set;}

Returns

A string specifying the user name. This parameter has no default value, and must be explicitly set.

Remarks

The MobiLink server uses this value to determine the download content, to record the synchronization state,
and to recover from interruptions during synchronization. This user name and password are separate from any
database user ID and password, and serve to identify and authenticate the application to the MobiLink server.

Related Information

Password property [page 518]

UltraLite - .NET API Reference

524 PUBLIC UltraLite .NET API reference
4.1.33.17 Version property

Specifies which synchronization script to use.

 Syntax

Visual Basic

Public Property Version As String

C#

public string Version {get;set;}

Returns

A string specifying the version of the synchronization script to use. This parameter has no default value, and
must be explicitly set.

Remarks

Each synchronization script in the consolidated database is marked with a version string. For example, there
can be two different download_cursor scripts, with each one identified by a different version string. The version
string allows an UltraLite application to choose from a set of synchronization scripts.

4.1.34 ULSyncProgressData class

UL Ext: Returns synchronization progress monitoring data.

 Syntax

Visual Basic

Public Class ULSyncProgressData

C#

public class ULSyncProgressData

Members

All members of ULSyncProgressData, including inherited members.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 525
Variables

Modifier and Type Variable Description

public const int FLAG_IS_BLOCKING A flag indicating that the synchroniza­

tion is blocked awaiting a response
from the MobiLink server.

public const int FLAG_LAST_UPLOAD_RECEIVED A flag indicating whether the server re­
ceived the last upload.

If it did not, the upload will be resent the

next time the publications from the pre­
vious sync are synced again, which
could be during the current synchroni­
zation.

Properties

Modifier and Type Property Description

public int CurrentDownloadRowCount [page Returns the number of rows that have
528] been downloaded so far.

public int Flags [page 529] Returns the current synchronization

flags indicating additional information
relating to the current state.

public int IgnoredDeletes [page 529] Returns the number of rows received so
far that have already been deleted.

public int IgnoredUpdates [page 530] Returns the number of rows received so
far that have already been updated.

public bool IsFinalSyncProgress [page 530] Returns true if this is final synchroniza­
tion progress message.

public long ReceivedBytes [page 531] Returns the number of bytes received
so far.

public int ReceivedDeletes [page 532] Returns the number of deleted rows re­
ceived so far.

public int ReceivedInserts [page 532] Returns the number of inserted rows
received so far.

public int ReceivedUpdates [page 533] Returns the number of updated rows
received so far.

public long SentBytes [page 533] Returns the number of bytes sent so
far.

public int SentDeletes [page 534] Returns the number of deleted rows
sent so far.

public int SentInserts [page 535] Returns the number of inserted rows
sent so far.

public int SentUpdates [page 535] Returns the number of updated rows
sent so far.

public ULSyncProgressState State [page 536] Returns the current synchronization

state.

UltraLite - .NET API Reference

526 PUBLIC UltraLite .NET API reference
 Modifier and Type Property Description

public int SyncTableCount [page 536] Returns the number of tables being
synchronized.

public int SyncTableIndex [page 537] Returns the index of the table currently
being synchronized in the range from 1
to the total number of tables involved
with the synchronization.

public int TableID [page 538] Returns the database index of the table
currently being synchronized.

public string TableName [page 538] Returns the name of the current table
being uploaded or downloaded.

public int TotalDownloadRowCount [page 539] Returns the total number of rows to be
received in the download.

public int TruncateDeletes [page 539] Returns the number of rows that have
been deleted by a truncate operation.

In this section:

CurrentDownloadRowCount property [page 528]

Returns the number of rows that have been downloaded so far.

Flags property [page 529]

Returns the current synchronization flags indicating additional information relating to the current state.

IgnoredDeletes property [page 529]

Returns the number of rows received so far that have already been deleted.

IgnoredUpdates property [page 530]

Returns the number of rows received so far that have already been updated.

IsFinalSyncProgress property [page 530]

Returns true if this is final synchronization progress message.

ReceivedBytes property [page 531]

Returns the number of bytes received so far.

ReceivedDeletes property [page 532]

Returns the number of deleted rows received so far.

ReceivedInserts property [page 532]

Returns the number of inserted rows received so far.

ReceivedUpdates property [page 533]

Returns the number of updated rows received so far.

SentBytes property [page 533]

Returns the number of bytes sent so far.

SentDeletes property [page 534]

Returns the number of deleted rows sent so far.

SentInserts property [page 535]

Returns the number of inserted rows sent so far.

SentUpdates property [page 535]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 527
 Returns the number of updated rows sent so far.

State property [page 536]

Returns the current synchronization state.

SyncTableCount property [page 536]

Returns the number of tables being synchronized.

SyncTableIndex property [page 537]

Returns the index of the table currently being synchronized in the range from 1 to the total number of
tables involved with the synchronization.

TableID property [page 538]

Returns the database index of the table currently being synchronized.

TableName property [page 538]

Returns the name of the current table being uploaded or downloaded.

TotalDownloadRowCount property [page 539]

Returns the total number of rows to be received in the download.

TruncateDeletes property [page 539]

Returns the number of rows that have been deleted by a truncate operation.

Related Information

ULSyncProgressListener interface [page 540]

4.1.34.1 CurrentDownloadRowCount property

Returns the number of rows that have been downloaded so far.

 Syntax

Visual Basic

Public ReadOnly Property CurrentDownloadRowCount As Integer

C#

public int CurrentDownloadRowCount {get;}

Returns

The number of rows that have been downloaded so far.

UltraLite - .NET API Reference

528 PUBLIC UltraLite .NET API reference
Remarks

This number includes duplicate rows that aren't included in ReceivedInserts, ReceivedUpdates, or
ReceivedDeletes.

Related Information

ULSyncProgressState enumeration [page 616]

4.1.34.2 Flags property

Returns the current synchronization flags indicating additional information relating to the current state.

 Syntax

Visual Basic

Public ReadOnly Property Flags As Integer

C#

public int Flags {get;}

Returns

An integer containing a combination of flags or'ed together.

4.1.34.3 IgnoredDeletes property

Returns the number of rows received so far that have already been deleted.

 Syntax

Visual Basic

Public ReadOnly Property IgnoredDeletes As Integer

C#

public int IgnoredDeletes {get;}

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 529
Returns

The number of rows received so far that have already been deleted.

Related Information

ULSyncProgressState enumeration [page 616]

4.1.34.4 IgnoredUpdates property

Returns the number of rows received so far that have already been updated.

 Syntax

Visual Basic

Public ReadOnly Property IgnoredUpdates As Integer

C#

public int IgnoredUpdates {get;}

Returns

The number of rows received so far that have already been updated.

Related Information

ULSyncProgressState enumeration [page 616]

4.1.34.5 IsFinalSyncProgress property

Returns true if this is final synchronization progress message.

 Syntax

Visual Basic

Public ReadOnly Property IsFinalSyncProgress As Boolean

UltraLite - .NET API Reference

530 PUBLIC UltraLite .NET API reference
 C#

public bool IsFinalSyncProgress {get;}

Returns

True if this is the final synchronization progress message.

4.1.34.6 ReceivedBytes property

Returns the number of bytes received so far.

 Syntax

Visual Basic

Public ReadOnly Property ReceivedBytes As Long

C#

public long ReceivedBytes {get;}

Returns

The number of bytes received so far.

Remarks

This information is updated for all states.

Related Information

ULSyncProgressState enumeration [page 616]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 531
4.1.34.7 ReceivedDeletes property

Returns the number of deleted rows received so far.

 Syntax

Visual Basic

Public ReadOnly Property ReceivedDeletes As Integer

C#

public int ReceivedDeletes {get;}

Returns

The number of deleted rows received so far.

Related Information

ULSyncProgressState enumeration [page 616]

4.1.34.8 ReceivedInserts property

Returns the number of inserted rows received so far.

 Syntax

Visual Basic

Public ReadOnly Property ReceivedInserts As Integer

C#

public int ReceivedInserts {get;}

Returns

The number of inserted rows received so far.

UltraLite - .NET API Reference

532 PUBLIC UltraLite .NET API reference
Related Information

ULSyncProgressState enumeration [page 616]

4.1.34.9 ReceivedUpdates property

Returns the number of updated rows received so far.

 Syntax

Visual Basic

Public ReadOnly Property ReceivedUpdates As Integer

C#

public int ReceivedUpdates {get;}

Returns

The number of updated rows received so far.

Related Information

ULSyncProgressState enumeration [page 616]

4.1.34.10 SentBytes property

Returns the number of bytes sent so far.

 Syntax

Visual Basic

Public ReadOnly Property SentBytes As Long

C#

public long SentBytes {get;}

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 533
Returns

The number of bytes sent so far.

Remarks

This information is updated for all states.

Related Information

ULSyncProgressState enumeration [page 616]

4.1.34.11 SentDeletes property

Returns the number of deleted rows sent so far.

 Syntax

Visual Basic

Public ReadOnly Property SentDeletes As Integer

C#

public int SentDeletes {get;}

Returns

The number of deleted rows sent so far.

Related Information

ULSyncProgressState enumeration [page 616]

UltraLite - .NET API Reference

534 PUBLIC UltraLite .NET API reference
4.1.34.12 SentInserts property

Returns the number of inserted rows sent so far.

 Syntax

Visual Basic

Public ReadOnly Property SentInserts As Integer

C#

public int SentInserts {get;}

Returns

The number of inserted rows sent so far.

Related Information

ULSyncProgressState enumeration [page 616]

4.1.34.13 SentUpdates property

Returns the number of updated rows sent so far.

 Syntax

Visual Basic

Public ReadOnly Property SentUpdates As Integer

C#

public int SentUpdates {get;}

Returns

The number of updated rows sent so far.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 535
Related Information

ULSyncProgressState enumeration [page 616]

4.1.34.14 State property

Returns the current synchronization state.

 Syntax

Visual Basic

Public ReadOnly Property State As ULSyncProgressState

C#

public ULSyncProgressState State {get;}

Returns

One of the ULSyncProgressState values specifying the current synchronization state.

Related Information

ULSyncProgressState enumeration [page 616]

4.1.34.15 SyncTableCount property

Returns the number of tables being synchronized.

 Syntax

Visual Basic

Public ReadOnly Property SyncTableCount As Integer

C#

public int SyncTableCount {get;}

UltraLite - .NET API Reference

536 PUBLIC UltraLite .NET API reference
Returns

The number of tables being synchronized. For each table there is a sending and receiving phase, so this
number may be more than the number of tables being synchronized.

Related Information

ULSyncProgressState enumeration [page 616]

4.1.34.16 SyncTableIndex property

Returns the index of the table currently being synchronized in the range from 1 to the total number of tables
involved with the synchronization.

 Syntax

Visual Basic

Public ReadOnly Property SyncTableIndex As Integer

C#

public int SyncTableIndex {get;}

Returns

The index of the table currently being synchronized in the range from 1 to the SyncTableCount property value.

Related Information

ULSyncProgressState enumeration [page 616]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 537
4.1.34.17 TableID property

Returns the database index of the table currently being synchronized.

 Syntax

Visual Basic

Public ReadOnly Property TableID As Integer

C#

public int TableID {get;}

Returns

The database index, in the range from 1 to the ULDatabaseSchema.TableCount property value.

Related Information

ULSyncProgressState enumeration [page 616]

TableCount property [page 302]

4.1.34.18 TableName property

Returns the name of the current table being uploaded or downloaded.

 Syntax

Visual Basic

Public ReadOnly Property TableName As String

C#

public string TableName {get;}

Returns

Name of the current table being synchronized; null if not applicable.

UltraLite - .NET API Reference

538 PUBLIC UltraLite .NET API reference
4.1.34.19 TotalDownloadRowCount property

Returns the total number of rows to be received in the download.

 Syntax

Visual Basic

Public ReadOnly Property TotalDownloadRowCount As Integer

C#

public int TotalDownloadRowCount {get;}

Returns

The number of rows to be received in the download.

Remarks

This number includes duplicate rows that aren't included in ReceivedInserts, ReceivedUpdates, or
ReceivedDeletes. This value isn't set until the synchronization enters the STATE_RECEIVING_TABLE state for
the first table.

Related Information

ULSyncProgressState enumeration [page 616]

4.1.34.20 TruncateDeletes property

Returns the number of rows that have been deleted by a truncate operation.

 Syntax

Visual Basic

Public ReadOnly Property TruncateDeletes As Integer

C#

public int TruncateDeletes {get;}

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 539
Returns

The number of rows deleted by a truncate operation.

Related Information

ULSyncProgressState enumeration [page 616]

4.1.35 ULSyncProgressListener interface

UL Ext: The listener interface for receiving synchronization progress events.

 Syntax

Visual Basic

Public Interface ULSyncProgressListener

C#

public interface ULSyncProgressListener

Members

All members of ULSyncProgressListener, including inherited members.

Methods

Modifier and Type Method Description

public bool SyncProgressed(ULSyncProgressData) Invoked during synchronization to in­

[page 541] form the user of progress.

In this section:

SyncProgressed(ULSyncProgressData) method [page 541]

Invoked during synchronization to inform the user of progress.

Related Information

Synchronize(ULSyncProgressListener) method [page 201]

UltraLite - .NET API Reference

540 PUBLIC UltraLite .NET API reference
4.1.35.1 SyncProgressed(ULSyncProgressData) method

Invoked during synchronization to inform the user of progress.

 Syntax

Visual Basic

Public Function SyncProgressed (ByVal data As ULSyncProgressData) As

Boolean

C#

public bool SyncProgressed (ULSyncProgressData data)

Parameters

data A ULSyncProgressData object containing the latest synchronization progress data.

Returns

This method should return true to cancel synchronization or return false to continue.

Remarks

This method should return true to cancel synchronization or return false to continue.

No UltraLite.NET API methods should be invoked during a SyncProgressed call.

Related Information

ULSyncProgressData class [page 525]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 541
4.1.36 ULSyncResult class

UL Ext: Represents the status of the last synchronization.

 Syntax

Visual Basic

Public Class ULSyncResult

C#

public class ULSyncResult

Members

All members of ULSyncResult, including inherited members.

Properties

Modifier and Type Property Description

public ULAuthStatusCode AuthStatus [page 543] Returns the authorization status code
for the last synchronization attempt.

public long AuthValue [page 544] Returns the return value from custom
user authentication synchronization
scripts.

public bool IgnoredRows [page 544] Checks whether any uploaded rows
were ignored during the last synchroni­
zation.

public bool PartialDownloadRetained [page 545] Checks whether a partial download was
retained during the last synchroniza­
tion.

public ULStreamErrorCode StreamErrorCode [page 546] Returns the error reported by the
stream itself.

public string StreamErrorParameters [page 546] Returns a comma-separated list of

stream error parameters.

public int StreamErrorSystem [page 547] Returns the stream error system-spe­
cific code.

public DateTime Timestamp [page 547] Returns the timestamp of the last syn­
chronization.

public bool UploadOK [page 548] Checks whether the last upload syn­
chronization was successful.

UltraLite - .NET API Reference

542 PUBLIC UltraLite .NET API reference
Remarks

There is no constructor for this class. Each connection has its own ULSyncResult instance, attached as its
ULConnection.SyncResult property. A ULSyncResult instance is only valid while that connection is open.

In this section:

AuthStatus property [page 543]

Returns the authorization status code for the last synchronization attempt.

AuthValue property [page 544]

Returns the return value from custom user authentication synchronization scripts.

IgnoredRows property [page 544]

Checks whether any uploaded rows were ignored during the last synchronization.

PartialDownloadRetained property [page 545]

Checks whether a partial download was retained during the last synchronization.

StreamErrorCode property [page 546]

Returns the error reported by the stream itself.

StreamErrorParameters property [page 546]

Returns a comma-separated list of stream error parameters.

StreamErrorSystem property [page 547]

Returns the stream error system­specific code.

Timestamp property [page 547]

Returns the timestamp of the last synchronization.

UploadOK property [page 548]

Checks whether the last upload synchronization was successful.

Related Information

SyncResult property [page 213]

Synchronize() method [page 200]

4.1.36.1 AuthStatus property

Returns the authorization status code for the last synchronization attempt.

 Syntax

Visual Basic

Public ReadOnly Property AuthStatus As ULAuthStatusCode

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 543
 C#

public ULAuthStatusCode AuthStatus {get;}

Remarks

One of the ULAuthStatusCode values denoting the authorization status for the last synchronization attempt.

Related Information

ULAuthStatusCode enumeration [page 607]

4.1.36.2 AuthValue property

Returns the return value from custom user authentication synchronization scripts.

 Syntax

Visual Basic

Public ReadOnly Property AuthValue As Long

C#

public long AuthValue {get;}

Remarks

A long integer returned from custom user authentication synchronization scripts.

4.1.36.3 IgnoredRows property

Checks whether any uploaded rows were ignored during the last synchronization.

 Syntax

Visual Basic

Public ReadOnly Property IgnoredRows As Boolean

UltraLite - .NET API Reference

544 PUBLIC UltraLite .NET API reference
 C#

public bool IgnoredRows {get;}

Remarks

True if any uploaded rows were ignored during the last synchronization, false if no rows were ignored.

Related Information

DownloadOnly property [page 515]

4.1.36.4 PartialDownloadRetained property

Checks whether a partial download was retained during the last synchronization.

 Syntax

Visual Basic

Public ReadOnly Property PartialDownloadRetained As Boolean

C#

public bool PartialDownloadRetained {get;}

Remarks

True if a download was interrupted and the partial download was retained, false if the download was not
interrupted or if the partial download was rolled back.

Related Information

KeepPartialDownload property [page 516]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 545
4.1.36.5 StreamErrorCode property

Returns the error reported by the stream itself.

 Syntax

Visual Basic

Public ReadOnly Property StreamErrorCode As ULStreamErrorCode

C#

public ULStreamErrorCode StreamErrorCode {get;}

Remarks

One of the ULStreamErrorCode values denoting the error reported by the stream itself,
ULStreamErrorCode.NONE if no error occurred.

4.1.36.6 StreamErrorParameters property

Returns a comma-separated list of stream error parameters.

 Syntax

Visual Basic

Public ReadOnly Property StreamErrorParameters As String

C#

public string StreamErrorParameters {get;}

Remarks

Contains a comma separated list of error parameters for the stream error code reported in StreamErrorCode
property. This is an empty string either for errors with no parameters, or when no error has been set.

Related Information

StreamErrorCode property [page 379]

UltraLite - .NET API Reference

546 PUBLIC UltraLite .NET API reference
4.1.36.7 StreamErrorSystem property

Returns the stream error system­specific code.

 Syntax

Visual Basic

Public ReadOnly Property StreamErrorSystem As Integer

C#

public int StreamErrorSystem {get;}

Remarks

An integer denoting the stream error system­specific code.

4.1.36.8 Timestamp property

Returns the timestamp of the last synchronization.

 Syntax

Visual Basic

Public ReadOnly Property Timestamp As Date

C#

public DateTime Timestamp {get;}

Remarks

A System.DateTime structure specifying the timestamp of the last synchronization.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 547
4.1.36.9 UploadOK property

Checks whether the last upload synchronization was successful.

 Syntax

Visual Basic

Public ReadOnly Property UploadOK As Boolean

C#

public bool UploadOK {get;}

Remarks

True if the last upload synchronization was successful, false if the last upload synchronization was
unsuccessful.

4.1.37 ULTable class

UL Ext: Represents a table in an UltraLite database.

 Syntax

Visual Basic

Public Class ULTable Inherits ULResultSet

C#

public class ULTable : ULResultSet

Members

All members of ULTable, including inherited members.

Methods

Modifier and Type Method Description

public void DeleteAllRows() [page 555] Deletes all rows in the table.

public void FindBegin() [page 556] Prepares to perform a new Find on a ta­
ble.

UltraLite - .NET API Reference

548 PUBLIC UltraLite .NET API reference
 Modifier and Type Method Description

public bool FindFirst [page 557] Moves forward through the table from
the beginning, looking for a row that ex­
actly matches a value or full set of val­
ues in the current index.

public bool FindLast [page 560] Moves backward through the table from
the end, looking for a row that exactly
matches a value or full set of values in
the current index.

public bool FindNext [page 563] Continues a ULTable.FindFirst search

by moving forward through the table
from the current position, looking to
see if the next row exactly matches a
value or full set of values in the current
index.

public bool FindPrevious [page 566] Continues a ULTable.FindLast search by

moving backward through the table
from the current position, looking to
see if the previous row exactly matches
a value or full set of values in the cur­
rent index.

public void Insert() [page 568] Inserts a new row with the current col­
umn values (specified using the set
methods).

public void InsertBegin() [page 569] Prepares to insert a new row into the ta­
ble by setting all current column values
to their default values.

public bool LookupBackward [page 570] Moves backward through the table from
the end, looking for a row that matches
or is less than a value or full set of val­
ues in the current index.

public void LookupBegin() [page 573] Prepares to perform a new lookup on

the table.

public bool LookupForward [page 574] Moves forward through the table from
the beginning, looking for a row that
matches or is greater than a value or
full set of values in the current index.

public void Truncate() [page 576] Deletes all rows in the table while tem­
porarily activating a stop synchroniza­
tion delete.

Properties

Modifier and Type Property Description

public new ULTableSchema Schema [page 577] Holds the table schema.

Inherited members from ULResultSet

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 549
Modifier and Type Member Description

public unsafe void AppendBytes(int, byte[], int, int) [page Appends the specified subset of the
469] specified array of System.Bytes to the
new value for the specified ULDb­
Type.LongBinary column.

public unsafe void AppendChars(int, char[], int, int) [page Appends the specified subset of the
471] specified array of System.Chars to the
new value for the specified ULDb­
Type.LongVarchar column.

public void Delete() [page 472] Deletes the current row.

public void SetBoolean(int, bool) [page 473] Sets the value for the specified column
using a System.Boolean.

public void SetByte(int, byte) [page 474] Sets the value for the specified column
using a System.Byte (unsigned 8-bit in­
teger).

public unsafe void SetBytes(int, byte[]) [page 475] Sets the value for the specified column
using an array of System.Bytes.

public unsafe void SetDateTime(int, DateTime) [page 476] Sets the value for the specified column
using a System.DateTime.

public void SetDBNull(int) [page 477] Sets a column to NULL.

public void SetDecimal(int, decimal) [page 478] Sets the value for the specified column
using a System.Decimal.

public void SetDouble(int, double) [page 479] Sets the value for the specified column
using a System.Double.

public void SetFloat(int, float) [page 480] Sets the value for the specified column
using a System.Single.

public unsafe void SetGuid(int, Guid) [page 481] Sets the value for the specified column
using a System.Guid.

public void SetInt16(int, short) [page 483] Sets the value for the specified column
using a System.Int16.

public void SetInt32(int, int) [page 484] Sets the value for the specified column
using a System.Int32.

public void SetInt64(int, long) [page 485] Sets the value for the specified column
using an Int64.

public unsafe void SetString(int, string) [page 486] Sets the value for the specified column
using a System.String.

public unsafe void SetTimeSpan(int, TimeSpan) [page Sets the value for the specified column
487] using a System.TimeSpan.

public void SetToDefault(int) [page 488] Sets the value for the specified column
to its default value.

public void SetUInt16(int, ushort) [page 489] Sets the value for the specified column
using a System.UInt16.

public void SetUInt32(int, uint) [page 490] Sets the value for the specified column
using a System.UInt32.

UltraLite - .NET API Reference

550 PUBLIC UltraLite .NET API reference
 Modifier and Type Member Description

public void SetUInt64(int, ulong) [page 492] Sets the value for the specified column
using a System.UInt64.

public void Update() [page 493] Updates the current row with the cur­
rent column values (specified using the
set methods).

public void UpdateBegin() [page 493] Prepares to update the current row.

Inherited members from ULDataReader

Modifier and Type Member Description

public override void Close() [page 309] Closes the cursor.

public override int Depth [page 347] Returns the depth of nesting for the
current row.

protected override void Dispose(bool) [page 309]

public override int FieldCount [page 347] Returns the number of columns in the
cursor.

public override unsafe bool GetBoolean(int) [page 310] Returns the value for the specified col­
umn as a System.Boolean.

public override unsafe byte GetByte(int) [page 311] Returns the value for the specified col­
umn as an unsigned 8-bit value (Sys­
tem.Byte).

public unsafe byte[] GetBytes(int) [page 312] UL Ext: Returns the value for the speci­
fied column as an array of Sys­
tem.Bytes values.

public override unsafe long GetBytes(int, long, byte[], int, int) [page Copies a subset of the value for the
313] specified ULDbType.LongBinary col­
umn, beginning at the specified offset,
to the specified offset of the destination
System.Byte array.

public override char GetChar(int) [page 315] This method is not supported in Ultra­
Lite.NET.

public override unsafe long GetChars(int, long, char[], int, int) Copies a subset of the value for the
[page 316] specified ULDbType.LongVarchar col­
umn, beginning at the specified offset,
to the specified offset of the destination
System.Char array.

public override string GetDataTypeName(int) [page 317] Returns the name of the specified col­
umn's provider data type.

public override unsafe DateTime GetDateTime(int) [page 318] Returns the value for the specified col­
umn as a System.DateTime type with
millisecond accuracy.

protected override DbDataReader GetDbDataReader(int) [page 319]

public override decimal GetDecimal(int) [page 319] Returns the value for the specified col­
umn as a System.Decimal type.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 551
Modifier and Type Member Description

public override unsafe double GetDouble(int) [page 320] Returns the value for the specified col­
umn as a System.Double type.

public override IEnumerator GetEnumerator() [page 321] Returns an System.Collections.IEnum­

erator value that iterates through the
ULDataReader object.

public override Type GetFieldType(int) [page 321] Returns the System.Type value most
appropriate for the specified column.

public override unsafe float GetFloat(int) [page 322] Returns the value for the specified col­
umn as a System.Single type.

public override unsafe Guid GetGuid(int) [page 323] Returns the value for the specified col­
umn as a UUID (System.Guid) type.

public override unsafe short GetInt16(int) [page 324] Returns the value for the specified col­
umn as a System.Int16 type.

public override unsafe int GetInt32(int) [page 325] Returns the value for the specified col­
umn as a System.Int32 type.

public override unsafe long GetInt64(int) [page 326] Returns the value for the specified col­
umn as a System.Int64 type.

public override string GetName(int) [page 327] Returns the name of the specified col­
umn.

public override unsafe int GetOrdinal(string) [page 328] Returns the column ID of the named
column.

public unsafe int GetRowCount(int) [page 329] UL Ext: Returns the number of rows in
the cursor, within threshold.

public override DataTable GetSchemaTable() [page 330] Returns a System.Data.DataTable value

that describes the column metadata of
the ULDataReader object.

public override unsafe String GetString(int) [page 332] Returns the value for the specified col­
umn as a System.String type.

public unsafe TimeSpan GetTimeSpan(int) [page 333] Returns the value for the specified col­
umn as a System.TimeSpan type with
millisecond accuracy.

public unsafe ushort GetUInt16(int) [page 334] Returns the value for the specified col­
umn as a System.UInt16 type.

public unsafe uint GetUInt32(int) [page 335] Returns the value for the specified col­
umn as a System.UInt32 type.

public unsafe ulong GetUInt64(int) [page 336] Returns the value for the specified col­
umn as a System.UInt64 type.

public override object GetValue(int) [page 337] Returns the value of the specified col­
umn in its native format.

public override int GetValues(object[]) [page 338] Returns all the column values for the
current row.

public override unsafe bool HasRows [page 348] Checks whether the ULDataReader ob­
ject has one or more rows.

UltraLite - .NET API Reference

552 PUBLIC UltraLite .NET API reference
 Modifier and Type Member Description

public unsafe bool IsBOF [page 348] UL Ext: Checks whether the current row
position is before the first row.

public override bool IsClosed [page 349] Checks whether the cursor is currently
open.

public override unsafe bool IsDBNull(int) [page 339] Checks whether the value from the
specified column is NULL.

public unsafe bool IsEOF [page 349] UL Ext: Checks whether the current row
position is after the last row.

public void MoveAfterLast() [page 340] UL Ext: Positions the cursor to after the
last row of the cursor.

public void MoveBeforeFirst() [page 340] UL Ext: Positions the cursor to before
the first row of the cursor.

public unsafe bool MoveFirst() [page 341] UL Ext: Positions the cursor to the first
row of the cursor.

public unsafe bool MoveLast() [page 341] UL Ext: Positions the cursor to the last
row of the cursor.

public unsafe bool MoveNext() [page 342] UL Ext: Positions the cursor to the next
row or after the last row if the cursor
was already on the last row.

public unsafe bool MovePrevious() [page 343] UL Ext: Positions the cursor to the pre­
vious row or before the first row.

public unsafe bool MoveRelative(int) [page 343] UL Ext: Positions the cursor relative to
the current row.

public override bool NextResult() [page 344] Advances the ULDataReader object to
the next result when reading the results
of batch SQL statements.

public override bool Read() [page 345] Positions the cursor to the next row, or
after the last row if the cursor was al­
ready on the last row.

public override int RecordsAffected [page 350] Returns the number of rows changed,
inserted, or deleted by execution of the
SQL statement.

public int RowCount [page 350] UL Ext: Returns the number of rows in
the cursor.

public ULCursorSchema Schema [page 351] UL Ext: Holds the schema of this cursor.

public override object this[int colID] [page 352] Returns the value of the specified col­
umn in its native format.

public override object this[string name] [page 353] Returns the value of the specified
named column in its native format.

protected void Validate() [page 346]

protected void Validate(int) [page 346]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 553
Remarks

There is no constructor for this class. Tables are created using the ULCommand.ExecuteTable method.

In this section:

DeleteAllRows() method [page 555]

Deletes all rows in the table.

FindBegin() method [page 556]

Prepares to perform a new Find on a table.

FindFirst method [page 557]

Moves forward through the table from the beginning, looking for a row that exactly matches a value or
full set of values in the current index.

FindLast method [page 560]

Moves backward through the table from the end, looking for a row that exactly matches a value or full
set of values in the current index.

FindNext method [page 563]

Continues a ULTable.FindFirst search by moving forward through the table from the current position,
looking to see if the next row exactly matches a value or full set of values in the current index.

FindPrevious method [page 566]

Continues a ULTable.FindLast search by moving backward through the table from the current position,
looking to see if the previous row exactly matches a value or full set of values in the current index.

Insert() method [page 568]

Inserts a new row with the current column values (specified using the set methods).

InsertBegin() method [page 569]

Prepares to insert a new row into the table by setting all current column values to their default values.

LookupBackward method [page 570]

Moves backward through the table from the end, looking for a row that matches or is less than a value
or full set of values in the current index.

LookupBegin() method [page 573]

Prepares to perform a new lookup on the table.

LookupForward method [page 574]

Moves forward through the table from the beginning, looking for a row that matches or is greater than a
value or full set of values in the current index.

Truncate() method [page 576]

Deletes all rows in the table while temporarily activating a stop synchronization delete.

Schema property [page 577]

Holds the table schema.

Related Information

ExecuteTable() method [page 124]

UltraLite - .NET API Reference

554 PUBLIC UltraLite .NET API reference
ULCommand class [page 88]
ULResultSet class [page 463]

4.1.37.1 DeleteAllRows() method

Deletes all rows in the table.

 Syntax

Visual Basic

Public Sub DeleteAllRows ()

C#

public void DeleteAllRows ()

Exceptions

ULException class A SQL error occurred.

Remarks

In some applications, it can be useful to delete all rows from a table before downloading a new set of data into
the table. Rows can be deleted from the UltraLite database without being deleted from the consolidated
database using the ULConnection.StopSynchronizationDelete method.

Related Information

Truncate() method [page 576]

StopSynchronizationDelete() method [page 199]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 555
4.1.37.2 FindBegin() method

Prepares to perform a new Find on a table.

 Syntax

Visual Basic

Public Sub FindBegin ()

C#

public void FindBegin ()

Exceptions

ULException class A SQL error occurred.

Remarks

The value(s) for which to search are specified by calling the appropriate setType method(s) on the columns in
the index with which the table was opened.

Related Information

FindFirst() method [page 557]

FindFirst(short) method [page 558]
FindLast() method [page 560]
FindLast(short) method [page 561]

UltraLite - .NET API Reference

556 PUBLIC UltraLite .NET API reference
4.1.37.3 FindFirst method

Moves forward through the table from the beginning, looking for a row that exactly matches a value or full set of
values in the current index.

Overload list

Modifier and Type Overload name Description

public bool FindFirst() [page 557] Moves forward through the table from
the beginning, looking for a row that ex­
actly matches a value or full set of val­
ues in the current index.

public unsafe bool FindFirst(short) [page 558] Moves forward through the table from
the beginning, looking for a row that ex­
actly matches a value or partial set of
values in the current index.

In this section:

FindFirst() method [page 557]

Moves forward through the table from the beginning, looking for a row that exactly matches a value or
full set of values in the current index.

FindFirst(short) method [page 558]

Moves forward through the table from the beginning, looking for a row that exactly matches a value or
partial set of values in the current index.

4.1.37.3.1 FindFirst() method

Moves forward through the table from the beginning, looking for a row that exactly matches a value or full set of
values in the current index.

 Syntax

Visual Basic

Public Function FindFirst () As Boolean

C#

public bool FindFirst ()

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 557
Returns

True if successful, false otherwise.

Exceptions

ULException class A SQL error occurred.

Remarks

To specify the value for which to search, set the column value for each column in the index. The cursor is left on
the first row that exactly matches the index value. On failure, the cursor position is after the last row (as shown
by the ULDataReader.IsEOF property).

The FindBegin method must be called before each search.

Related Information

FindBegin() method [page 556]

FindNext() method [page 563]
FindPrevious() method [page 566]
FindFirst(short) method [page 558]
IsEOF property [page 349]
FindBegin() method [page 556]

4.1.37.3.2 FindFirst(short) method

Moves forward through the table from the beginning, looking for a row that exactly matches a value or partial
set of values in the current index.

 Syntax

Visual Basic

Public Function FindFirst (ByVal numColumns As Short) As Boolean

C#

public unsafe bool FindFirst (short numColumns)

UltraLite - .NET API Reference

558 PUBLIC UltraLite .NET API reference
Parameters

numColumns For composite indexes, the number of columns to use in the find. For example, if you have a
three column index and you want to look up a value that matches based on the first column only, you
should set the value for the first column, and then supply a value of 1.

Returns

True if successful, false otherwise.

Exceptions

ULException class A SQL error occurred.

Remarks

To specify the value for which to search, set the column value for each column in the index. The cursor is left on
the first row that exactly matches the index value. On failure, the cursor position is after the last row (as shown
by the ULDataReader.IsEOF property).

The FindBegin method must be called before each search.

Related Information

FindBegin() method [page 556]

FindNext(short) method [page 564]
FindPrevious(short) method [page 567]
FindFirst() method [page 557]
IsEOF property [page 349]
FindBegin() method [page 556]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 559
4.1.37.4 FindLast method

Moves backward through the table from the end, looking for a row that exactly matches a value or full set of
values in the current index.

Overload list

Modifier and Type Overload name Description

public bool FindLast() [page 560] Moves backward through the table from
the end, looking for a row that exactly
matches a value or full set of values in
the current index.

public unsafe bool FindLast(short) [page 561] Moves backward through the table from
the end, looking for a row that exactly
matches a value or partial set of values
in the current index.

In this section:

FindLast() method [page 560]

Moves backward through the table from the end, looking for a row that exactly matches a value or full
set of values in the current index.

FindLast(short) method [page 561]

Moves backward through the table from the end, looking for a row that exactly matches a value or
partial set of values in the current index.

4.1.37.4.1 FindLast() method

Moves backward through the table from the end, looking for a row that exactly matches a value or full set of
values in the current index.

 Syntax

Visual Basic

Public Function FindLast () As Boolean

C#

public bool FindLast ()

UltraLite - .NET API Reference

560 PUBLIC UltraLite .NET API reference
Returns

True if successful, false otherwise.

Exceptions

ULException class A SQL error occurred.

Remarks

To specify the value for which to search, set the column value for each column in the index. The cursor is left on
the first row found that exactly matches the index value. On failure, the cursor position is before the first row
(as shown by the ULDataReader.IsBOF property).

The FindBegin method must be called before each search.

Related Information

FindBegin() method [page 556]

FindNext() method [page 563]
FindPrevious() method [page 566]
FindLast(short) method [page 561]
IsBOF property [page 348]
FindBegin() method [page 556]

4.1.37.4.2 FindLast(short) method

Moves backward through the table from the end, looking for a row that exactly matches a value or partial set of
values in the current index.

 Syntax

Visual Basic

Public Function FindLast (ByVal numColumns As Short) As Boolean

C#

public unsafe bool FindLast (short numColumns)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 561
Parameters

numColumns For composite indexes, the number of columns to use in the find. For example, if you have a
three column index and you want to find a value that matches based on the first column only, you should
set the value for the first column, then supply a value of 1.

Returns

True if successful, false otherwise

Exceptions

ULException class A SQL error occurred.

Remarks

To specify the value for which to search, set the column value for each column in the index. The cursor is left on
the first row found that exactly matches the index value. On failure, the cursor position is before the first row
(as shown by the ULDataReader.IsBOF property).

The FindBegin method must be called before each search.

Related Information

FindBegin() method [page 556]

FindNext(short) method [page 564]
FindPrevious(short) method [page 567]
FindLast() method [page 560]
IsBOF property [page 348]
FindBegin() method [page 556]

UltraLite - .NET API Reference

562 PUBLIC UltraLite .NET API reference
4.1.37.5 FindNext method

Continues a ULTable.FindFirst search by moving forward through the table from the current position, looking to
see if the next row exactly matches a value or full set of values in the current index.

Overload list

Modifier and Type Overload name Description

public bool FindNext() [page 563] Continues a ULTable.FindFirst search

by moving forward through the table
from the current position, looking to
see if the next row exactly matches a
value or full set of values in the current
index.

public unsafe bool FindNext(short) [page 564] Continues a ULTable.FindFirst search

by moving forward through the table
from the current position, looking to
see if the next row exactly matches a
value or partial set of values in the cur­
rent index.

In this section:

FindNext() method [page 563]

Continues a ULTable.FindFirst search by moving forward through the table from the current position,
looking to see if the next row exactly matches a value or full set of values in the current index.

FindNext(short) method [page 564]

Continues a ULTable.FindFirst search by moving forward through the table from the current position,
looking to see if the next row exactly matches a value or partial set of values in the current index.

4.1.37.5.1 FindNext() method

Continues a ULTable.FindFirst search by moving forward through the table from the current position, looking to
see if the next row exactly matches a value or full set of values in the current index.

 Syntax

Visual Basic

Public Function FindNext () As Boolean

C#

public bool FindNext ()

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 563
Returns

True if successful, false otherwise.

Exceptions

ULException class A SQL error occurred.

Remarks

The cursor is left on the next row if it exactly matches the index value. On failure, the cursor position is after the
last row (as shown by the ULDataReader.IsEOF property).

FindNext method behavior is undefined if the column values being searched for are modified during a row
update.

Related Information

FindFirst() method [page 557]

FindNext(short) method [page 564]
IsEOF property [page 349]

4.1.37.5.2 FindNext(short) method

Continues a ULTable.FindFirst search by moving forward through the table from the current position, looking to
see if the next row exactly matches a value or partial set of values in the current index.

 Syntax

Visual Basic

Public Function FindNext (ByVal numColumns As Short) As Boolean

C#

public unsafe bool FindNext (short numColumns)

UltraLite - .NET API Reference

564 PUBLIC UltraLite .NET API reference
Parameters

numColumns For composite indexes, the number of columns to use in the find. For example, if you have a
three column index, and you want to find a value that matches based on the first column only, you should
set the value for the first column, and then supply a value of 1.

Returns

True if successful, false otherwise.

Exceptions

ULException class A SQL error occurred.

Remarks

The cursor is left on the next row if it exactly matches the index value. On failure, the cursor position is after the
last row (as shown by the ULDataReader.IsEOF property).

FindNext method behavior is undefined if the column values being searched for are modified during a row
update.

Related Information

FindFirst(short) method [page 558]

FindNext() method [page 563]
FindFirst() method [page 557]
IsEOF property [page 349]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 565
4.1.37.6 FindPrevious method

Continues a ULTable.FindLast search by moving backward through the table from the current position, looking
to see if the previous row exactly matches a value or full set of values in the current index.

Overload list

Modifier and Type Overload name Description

public bool FindPrevious() [page 566] Continues a ULTable.FindLast search by

moving backward through the table
from the current position, looking to
see if the previous row exactly matches
a value or full set of values in the cur­
rent index.

public unsafe bool FindPrevious(short) [page 567] Continues a ULTable.FindLast search by

moving backward through the table
from the current position, looking to
see if the previous row exactly matches
a value or partial set of values in the
current index.

In this section:

FindPrevious() method [page 566]

Continues a ULTable.FindLast search by moving backward through the table from the current position,
looking to see if the previous row exactly matches a value or full set of values in the current index.

FindPrevious(short) method [page 567]

Continues a ULTable.FindLast search by moving backward through the table from the current position,
looking to see if the previous row exactly matches a value or partial set of values in the current index.

4.1.37.6.1 FindPrevious() method

Continues a ULTable.FindLast search by moving backward through the table from the current position, looking
to see if the previous row exactly matches a value or full set of values in the current index.

 Syntax

Visual Basic

Public Function FindPrevious () As Boolean

C#

public bool FindPrevious ()

UltraLite - .NET API Reference

566 PUBLIC UltraLite .NET API reference
Returns

True if successful, false otherwise.

Exceptions

ULException class A SQL error occurred.

Remarks

The cursor is left on the previous row if it exactly matches the index value. On failure, the cursor position is
before the first row (as shown by the ULDataReader.IsBOF property).

FindPrevious method behavior is undefined if the column values being searched for are modified during a row
update.

Related Information

FindLast() method [page 560]

FindPrevious(short) method [page 567]
IsBOF property [page 348]

4.1.37.6.2 FindPrevious(short) method

Continues a ULTable.FindLast search by moving backward through the table from the current position, looking
to see if the previous row exactly matches a value or partial set of values in the current index.

 Syntax

Visual Basic

Public Function FindPrevious (ByVal numColumns As Short) As Boolean

C#

public unsafe bool FindPrevious (short numColumns)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 567
Parameters

numColumns For composite indexes, the number of columns to use in the find. For example, if you have a
three column index and you want to look up a value that matches based on the first column only, you
should set the value for the first column, then supply a value of 1.

Returns

True if successful, false otherwise.

Exceptions

ULException class A SQL error occurred.

Remarks

The cursor is left on the previous row if it exactly matches the index value. On failure, the cursor position is
before the first row (as shown by the ULDataReader.IsBOF property).

FindPrevious method behavior is undefined if the column values being searched for are modified during a row
update.

Related Information

FindLast() method [page 560]

FindLast(short) method [page 561]
FindPrevious() method [page 566]
IsBOF property [page 348]

4.1.37.7 Insert() method

Inserts a new row with the current column values (specified using the set methods).

 Syntax

Visual Basic

Public Sub Insert ()

UltraLite - .NET API Reference

568 PUBLIC UltraLite .NET API reference
 C#

public void Insert ()

Exceptions

ULException class A SQL error occurred.

Remarks

Each insert must be preceded by a call to the ULTable.InsertBegin method.

Related Information

InsertBegin() method [page 569]

4.1.37.8 InsertBegin() method

Prepares to insert a new row into the table by setting all current column values to their default values.

 Syntax

Visual Basic

Public Sub InsertBegin ()

C#

public void InsertBegin ()

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 569
Remarks

Call the appropriate SetType or AppendType method(s) to specify the non-default values that are to be
inserted.

The row is not actually inserted and the data in the row is not actually changed until you execute the Insert
method, and that change is not made permanent until it is committed.

Related Information

Insert() method [page 568]

Insert() method [page 568]

4.1.37.9 LookupBackward method

Moves backward through the table from the end, looking for a row that matches or is less than a value or full set
of values in the current index.

Overload list

Modifier and Type Overload name Description

public bool LookupBackward() [page 571] Moves backward through the table from
the end, looking for a row that matches
or is less than a value or full set of val­
ues in the current index.

public unsafe bool LookupBackward(short) [page 572] Moves backward through the table from
the end, looking for a row that matches
or is less than a value or partial set of
values in the current index.

In this section:

LookupBackward() method [page 571]

Moves backward through the table from the end, looking for a row that matches or is less than a value
or full set of values in the current index.

LookupBackward(short) method [page 572]

Moves backward through the table from the end, looking for a row that matches or is less than a value
or partial set of values in the current index.

UltraLite - .NET API Reference

570 PUBLIC UltraLite .NET API reference
4.1.37.9.1 LookupBackward() method

Moves backward through the table from the end, looking for a row that matches or is less than a value or full set
of values in the current index.

 Syntax

Visual Basic

Public Function LookupBackward () As Boolean

C#

public bool LookupBackward ()

Returns

True if successful, false otherwise.

Exceptions

ULException class A SQL error occurred.

Remarks

To specify the value for which to search, set the column value for each column in the index. The cursor is left on
the first row that matches or is less than the index value. On failure (no rows less than the value being looked
for), the cursor position is before the first row (as shown by the ULDataReader.IsBOF property).

The LookupBegin method must be called before each search.

Related Information

LookupBegin() method [page 573]

LookupBackward(short) method [page 572]
IsBOF property [page 348]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 571
4.1.37.9.2 LookupBackward(short) method

Moves backward through the table from the end, looking for a row that matches or is less than a value or partial
set of values in the current index.

 Syntax

Visual Basic

Public Function LookupBackward (ByVal numColumns As Short) As Boolean

C#

public unsafe bool LookupBackward (short numColumns)

Parameters

numColumns For composite indexes, the number of columns to use in the lookup. For example, if you have
a three column index, and you want to look up a value that matches based on the first column only, you
should set the value for the first column, and then supply a value of 1.

Returns

True if successful, false otherwise.

Exceptions

ULException class A SQL error occurred.

Remarks

To specify the value for which to search, set the column value for each column in the index. The cursor is left on
the first row that matches or is less than the index value. On failure (no rows less than the value being looked
for), the cursor position is before the first row (as shown by the ULDataReader.IsBOF property).

The LookupBegin method must be called before each search.

UltraLite - .NET API Reference

572 PUBLIC UltraLite .NET API reference
Related Information

LookupBegin() method [page 573]

IsBOF property [page 348]

4.1.37.10 LookupBegin() method

Prepares to perform a new lookup on the table.

 Syntax

Visual Basic

Public Sub LookupBegin ()

C#

public void LookupBegin ()

Exceptions

ULException class A SQL error occurred.

Remarks

The value(s) for which to search are specified by calling the appropriate setType method(s) on the columns in
the index with which the table was opened.

Related Information

LookupForward() method [page 574]

LookupForward(short) method [page 575]
LookupBackward() method [page 571]
LookupBackward(short) method [page 572]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 573
4.1.37.11 LookupForward method

Moves forward through the table from the beginning, looking for a row that matches or is greater than a value
or full set of values in the current index.

Overload list

Modifier and Type Overload name Description

public bool LookupForward() [page 574] Moves forward through the table from
the beginning, looking for a row that
matches or is greater than a value or
full set of values in the current index.

public unsafe bool LookupForward(short) [page 575] Moves forward through the table from
the beginning, looking for a row that
matches or is greater than a value or
partial set of values in the current index.

In this section:

LookupForward() method [page 574]

Moves forward through the table from the beginning, looking for a row that matches or is greater than a
value or full set of values in the current index.

LookupForward(short) method [page 575]

Moves forward through the table from the beginning, looking for a row that matches or is greater than a
value or partial set of values in the current index.

4.1.37.11.1 LookupForward() method

Moves forward through the table from the beginning, looking for a row that matches or is greater than a value
or full set of values in the current index.

 Syntax

Visual Basic

Public Function LookupForward () As Boolean

C#

public bool LookupForward ()

UltraLite - .NET API Reference

574 PUBLIC UltraLite .NET API reference
Returns

True if successful, false otherwise.

Exceptions

ULException class A SQL error occurred.

Remarks

To specify the value for which to search, set the column value for each column in the index. The cursor is left on
the first row that matches or is greater than the index value. On failure (no rows greater than the value being
looked for), the cursor position is after the last row (as shown by the ULDataReader.IsEOF property).

The LookupBegin method must be called before each search.

Related Information

LookupBegin() method [page 573]

LookupForward(short) method [page 575]
IsEOF property [page 349]

4.1.37.11.2 LookupForward(short) method

Moves forward through the table from the beginning, looking for a row that matches or is greater than a value
or partial set of values in the current index.

 Syntax

Visual Basic

Public Function LookupForward (ByVal numColumns As Short) As Boolean

C#

public unsafe bool LookupForward (short numColumns)

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 575
Parameters

numColumns For composite indexes, the number of columns to use in the lookup. For example, if you have
a three column index and you want to look up a value that matches based on the first column only, you
should set the value for the first column, and then supply a value of 1.

Returns

True if successful, false otherwise.

Exceptions

ULException class A SQL error occurred.

Remarks

To specify the value for which to search, set the column value for each column in the index. The cursor is left on
the first row that matches or is greater than the index value. On failure (no rows greater than the value being
looked for), the cursor position is after the last row (as shown by the ULDataReader.IsEOF property).

The LookupBegin method must be called before each search.

Related Information

LookupBegin() method [page 573]

LookupForward() method [page 574]
IsEOF property [page 349]
LookupBegin() method [page 573]

4.1.37.12 Truncate() method

Deletes all rows in the table while temporarily activating a stop synchronization delete.

 Syntax

Visual Basic

Public Sub Truncate ()

UltraLite - .NET API Reference

576 PUBLIC UltraLite .NET API reference
 C#

public void Truncate ()

Exceptions

ULException class A SQL error occurred.

Related Information

DeleteAllRows() method [page 555]

4.1.37.13 Schema property

Holds the table schema.

 Syntax

Visual Basic

Public ReadOnly Shadows Property Schema As ULTableSchema

C#

public new ULTableSchema Schema {get;}

Remarks

This property is only valid while its connection is open.

The ULTableSchema object representing the table schema.

This property represents the complete schema of the table, including UltraLite.NET extended information
which is not represented in the results from calling the ULDataReader.GetSchemaTable method.

Related Information

ULTableSchema class [page 578]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 577
4.1.38 ULTableSchema class

UL Ext: Represents the schema of an UltraLite table.

 Syntax

Visual Basic

Public NotInheritable Class ULTableSchema Inherits ULCursorSchema

C#

public sealed class ULTableSchema : ULCursorSchema

Members

All members of ULTableSchema, including inherited members.

Methods

Modifier and Type Method Description

public unsafe string GetColumnDefaultValue(int) [page Returns the default value of the speci­
582] fied column.

public unsafe ulong GetColumnPartitionSize(int) [page Returns the global autoincrement parti­
583] tion size assigned to the specified col­
umn.

public unsafe ULIndexSchema GetIndex(string) [page 584] Returns the index schema of the named
index.

public unsafe string GetIndexName(int) [page 584] Returns the name of the index identi­
fied by the specified index ID.

public unsafe string GetOptimalIndex(int) [page 585] The optimal index for searching a table
using the specified column.

public unsafe string GetPublicationPredicate(string) [page Returns the publication predicate for
586] this table in the named publication.

public unsafe bool IsColumnAutoIncrement(int) [page Checks whether the specified column's
587] default is set to autoincrement.

public unsafe bool IsColumnCurrentDate(int) [page 588] Checks whether the specified column's
default is set to the current date (a
ULDbType.Date value).

public unsafe bool IsColumnCurrentTime(int) [page 589] Checks whether the specified column's
default is set to the current time (a
ULDbType.Time value).

public unsafe bool IsColumnCurrentTimestamp(int) [page Checks whether the specified column's
590] default is set to the current timestamp
(a ULDbType.TimeStamp value).

UltraLite - .NET API Reference

578 PUBLIC UltraLite .NET API reference
 Modifier and Type Method Description

public unsafe bool IsColumnCurrentUTCTimestamp(int) Checks whether the specified column's

[page 591] default is set to the current UTC time­
stamp (a ULDbType.TimeStamp value).

public unsafe bool IsColumnGlobalAutoIncrement(int) Checks whether the specified column's

[page 592] default is set to global autoincrement.

public unsafe bool IsColumnNewUUID(int) [page 593] Checks whether the specified column's
default is set to a new UUID (a Sys­
tem.Guid value).

public unsafe bool IsColumnNullable(int) [page 594] Checks whether the specified column is
nullable.

public unsafe bool IsInPublication(string) [page 595] Checks whether the table is contained
in the named publication.

protected virtual override void VerifyOpen() [page 595]

Properties

Modifier and Type Property Description

public unsafe int IndexCount [page 596] Returns the number of indexes on the
table.

public unsafe bool IsNeverSynchronized [page 596] Checks whether the table is marked as
never being synchronized.

public override string Name [page 597] Returns the name of the table.

public unsafe ULIndexSchema PrimaryKey [page 597] Returns the index schema of the pri­
mary key for the table.

public unsafe bool UploadUnchangedRows [page 598] Checks whether the database uploads
rows that have not changed.

Inherited members from ULCursorSchema

Modifier and Type Member Description

public short ColumnCount [page 266] Returns the number of columns in the
cursor.

protected unsafe void GetColumnCount() [page 258]

public unsafe short GetColumnID(string) [page 258] Returns the column ID of the named
column.

public string GetColumnName(int) [page 259] Returns the name of the column identi­
fied by the specified column ID.

public unsafe int GetColumnPrecision(int) [page 260] Returns the precision of the column
identified by the specified column ID if
the column is a numeric column (the
NUMERIC SQL type).

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 579
Modifier and Type Member Description

public unsafe int GetColumnScale(int) [page 261] Returns the scale of the column identi­
fied by the specified column ID if the
column is a numeric column (the NU­
MERIC SQL type).

public unsafe int GetColumnSize(int) [page 262] Returns the size of the column identi­
fied by the specified column ID if the
column is a sized column (the BINARY
or CHAR SQL types).

public string GetColumnSQLName(int) [page 263] Returns the name of the column identi­
fied by the specified column ID.

public unsafe ULDbType GetColumnULDbType(int) [page 264] Returns the UltraLite.NET data type of
the column identified by the specified
column ID.

public unsafe DataTable GetSchemaTable() [page 265] Returns a System.Data.DataTable that

describes the column schema of the
ULDataReader object.

public bool IsOpen [page 266] Checks whether the cursor schema is
currently open.

Remarks

There is no constructor for this class. A ULTableSchema object is attached to a table as its ULTable.Schema
property.

In this section:

GetColumnDefaultValue(int) method [page 582]

Returns the default value of the specified column.

GetColumnPartitionSize(int) method [page 583]

Returns the global autoincrement partition size assigned to the specified column.

GetIndex(string) method [page 584]

Returns the index schema of the named index.

GetIndexName(int) method [page 584]

Returns the name of the index identified by the specified index ID.

GetOptimalIndex(int) method [page 585]

The optimal index for searching a table using the specified column.

GetPublicationPredicate(string) method [page 586]

Returns the publication predicate for this table in the named publication.

IsColumnAutoIncrement(int) method [page 587]

Checks whether the specified column's default is set to autoincrement.

IsColumnCurrentDate(int) method [page 588]

Checks whether the specified column's default is set to the current date (a ULDbType.Date value).

UltraLite - .NET API Reference

580 PUBLIC UltraLite .NET API reference
 IsColumnCurrentTime(int) method [page 589]
Checks whether the specified column's default is set to the current time (a ULDbType.Time value).

IsColumnCurrentTimestamp(int) method [page 590]

Checks whether the specified column's default is set to the current timestamp (a
ULDbType.TimeStamp value).

IsColumnCurrentUTCTimestamp(int) method [page 591]

Checks whether the specified column's default is set to the current UTC timestamp (a
ULDbType.TimeStamp value).

IsColumnGlobalAutoIncrement(int) method [page 592]

Checks whether the specified column's default is set to global autoincrement.

IsColumnNewUUID(int) method [page 593]

Checks whether the specified column's default is set to a new UUID (a System.Guid value).

IsColumnNullable(int) method [page 594]

Checks whether the specified column is nullable.

IsInPublication(string) method [page 595]

Checks whether the table is contained in the named publication.

VerifyOpen() method [page 595]

IndexCount property [page 596]

Returns the number of indexes on the table.

IsNeverSynchronized property [page 596]

Checks whether the table is marked as never being synchronized.

Name property [page 597]

Returns the name of the table.

PrimaryKey property [page 597]

Returns the index schema of the primary key for the table.

UploadUnchangedRows property [page 598]

Checks whether the database uploads rows that have not changed.

Related Information

Schema property [page 577]

ULCursorSchema class [page 255]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 581
4.1.38.1 GetColumnDefaultValue(int) method

Returns the default value of the specified column.

 Syntax

Visual Basic

Public Function GetColumnDefaultValue (ByVal columnID As Integer) As String

C#

public unsafe string GetColumnDefaultValue (int columnID)

Parameters

columnID The ID number of the column. The value must be in the range
[0,ULCursorSchema.ColumnCount-1]. The first column in a table has an ID value of zero.

Returns

The default value of the specified column as a string or a null reference (Nothing in Visual Basic) if the default
value is null.

Exceptions

ULException class A SQL error occurred.

Related Information

ColumnCount property [page 266]

UltraLite - .NET API Reference

582 PUBLIC UltraLite .NET API reference
4.1.38.2 GetColumnPartitionSize(int) method

Returns the global autoincrement partition size assigned to the specified column.

 Syntax

Visual Basic

Public Function GetColumnPartitionSize (ByVal columnID As Integer) As ULong

C#

public unsafe ulong GetColumnPartitionSize (int columnID)

Parameters

columnID The ID number of the column. The value must be in the range
[0,ULCursorSchema.ColumnCount-1]. The first column in the table has an ID value of zero.

Returns

The column's global autoincrement partition size as a System.UInt64 structure.

Exceptions

ULException class A SQL error occurred.

Remarks

All global autoincrement columns in a given table share the same global autoincrement partition.

Related Information

IsColumnGlobalAutoIncrement(int) method [page 592]

ColumnCount property [page 266]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 583
4.1.38.3 GetIndex(string) method

Returns the index schema of the named index.

 Syntax

Visual Basic

Public Function GetIndex (ByVal name As String) As ULIndexSchema

C#

public unsafe ULIndexSchema GetIndex (string name)

Parameters

name The name of the index.

Returns

A ULIndexSchema object representing the named index.

Exceptions

ULException class A SQL error occurred.

Related Information

ULIndexSchema class [page 388]

4.1.38.4 GetIndexName(int) method

Returns the name of the index identified by the specified index ID.

 Syntax

Visual Basic

Public Function GetIndexName (ByVal indexID As Integer) As String

UltraLite - .NET API Reference

584 PUBLIC UltraLite .NET API reference
 C#

public unsafe string GetIndexName (int indexID)

Parameters

indexID The ID of the index. The value must be in the range [1,IndexCount].

Returns

The name of the index as a string.

Exceptions

ULException class A SQL error occurred.

Remarks

Index IDs and counts may change during a schema upgrade. To correctly identify an index, access it by name or
refresh the cached IDs and counts after a schema upgrade.

Related Information

IndexCount property [page 596]

4.1.38.5 GetOptimalIndex(int) method

The optimal index for searching a table using the specified column.

 Syntax

Visual Basic

Public Function GetOptimalIndex (ByVal columnID As Integer) As String

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 585
 C#

public unsafe string GetOptimalIndex (int columnID)

Parameters

columnID The ID number of the column. The first column in the table has an ID value of zero.

Returns

A ULIndexSchema object representing the optimal index for the specified column.

Exceptions

ULException class A SQL error occurred.

Remarks

The specified column is the first column in the index, but the index may have more than one column.

Related Information

ColumnCount property [page 266]

ULIndexSchema class [page 388]

4.1.38.6 GetPublicationPredicate(string) method

Returns the publication predicate for this table in the named publication.

 Syntax

Visual Basic

Public Function GetPublicationPredicate (ByVal pubName As String) As String

UltraLite - .NET API Reference

586 PUBLIC UltraLite .NET API reference
 C#

public unsafe string GetPublicationPredicate (string pubName)

Parameters

pubName The name of the publication.

Returns

The publication predicate as a string.

Exceptions

ULException class A SQL error occurred.

4.1.38.7 IsColumnAutoIncrement(int) method

Checks whether the specified column's default is set to autoincrement.

 Syntax

Visual Basic

Public Function IsColumnAutoIncrement (ByVal columnID As Integer) As

Boolean

C#

public unsafe bool IsColumnAutoIncrement (int columnID)

Parameters

columnID The ID number of the column. The value must be in the range
[0,ULCursorSchema.ColumnCount-1]. The first column in the table has an ID value of zero.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 587
Returns

True if the column is autoincrementing, false if it is not autoincrementing.

Exceptions

ULException class A SQL error occurred.

Related Information

ColumnCount property [page 266]

4.1.38.8 IsColumnCurrentDate(int) method

Checks whether the specified column's default is set to the current date (a ULDbType.Date value).

 Syntax

Visual Basic

Public Function IsColumnCurrentDate (ByVal columnID As Integer) As Boolean

C#

public unsafe bool IsColumnCurrentDate (int columnID)

Parameters

columnID The ID number of the column. The value must be in the range
[0,ULCursorSchema.ColumnCount-1]. The first column in the table has an ID value of zero.

Returns

True if the column defaults to the current date, false if the column does not default to the current date.

UltraLite - .NET API Reference

588 PUBLIC UltraLite .NET API reference
Exceptions

ULException class A SQL error occurred.

Related Information

ColumnCount property [page 266]

4.1.38.9 IsColumnCurrentTime(int) method

Checks whether the specified column's default is set to the current time (a ULDbType.Time value).

 Syntax

Visual Basic

Public Function IsColumnCurrentTime (ByVal columnID As Integer) As Boolean

C#

public unsafe bool IsColumnCurrentTime (int columnID)

Parameters

columnID The ID number of the column. The value must be in the range
[0,ULCursorSchema.ColumnCount-1]. The first column in the table has an ID value of zero.

Returns

True if the column defaults to the current time, false if the column does not default to the current time.

Exceptions

ULException class A SQL error occurred.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 589
Related Information

ColumnCount property [page 266]

4.1.38.10 IsColumnCurrentTimestamp(int) method

Checks whether the specified column's default is set to the current timestamp (a ULDbType.TimeStamp
value).

 Syntax

Visual Basic

Public Function IsColumnCurrentTimestamp (ByVal columnID As Integer) As

Boolean

C#

public unsafe bool IsColumnCurrentTimestamp (int columnID)

Parameters

columnID The ID number of the column. The value must be in the range
[0,ULCursorSchema.ColumnCount-1]. The first column in the table has an ID value of zero.

Returns

True if the column defaults to the current timestamp, false if the column does not default to the current
timestamp.

Exceptions

ULException class A SQL error occurred.

Related Information

ColumnCount property [page 266]

UltraLite - .NET API Reference

590 PUBLIC UltraLite .NET API reference
4.1.38.11 IsColumnCurrentUTCTimestamp(int) method

Checks whether the specified column's default is set to the current UTC timestamp (a ULDbType.TimeStamp
value).

 Syntax

Visual Basic

Public Function IsColumnCurrentUTCTimestamp (ByVal columnID As Integer) As

Boolean

C#

public unsafe bool IsColumnCurrentUTCTimestamp (int columnID)

Parameters

columnID The ID number of the column. The value must be in the range
[0,ULCursorSchema.ColumnCount-1]. The first column in the table has an ID value of zero.

Returns

True if the column defaults to the current UTC timestamp, false if the column does not default to the current
UTC timestamp.

Exceptions

ULException class A SQL error occurred.

Related Information

ColumnCount property [page 266]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 591
4.1.38.12 IsColumnGlobalAutoIncrement(int) method

Checks whether the specified column's default is set to global autoincrement.

 Syntax

Visual Basic

Public Function IsColumnGlobalAutoIncrement (ByVal columnID As Integer) As

Boolean

C#

public unsafe bool IsColumnGlobalAutoIncrement (int columnID)

Parameters

columnID The ID number of the column. The value must be in the range
[0,ULCursorSchema.ColumnCount-1]. The first column in the table has an ID value of zero.

Returns

True if the column is global autoincrementing, false if it is not global autoincrementing.

Exceptions

ULException class A SQL error occurred.

Related Information

GetColumnPartitionSize(int) method [page 583]

DatabaseID property [page 208]
ColumnCount property [page 266]

UltraLite - .NET API Reference

592 PUBLIC UltraLite .NET API reference
4.1.38.13 IsColumnNewUUID(int) method

Checks whether the specified column's default is set to a new UUID (a System.Guid value).

 Syntax

Visual Basic

Public Function IsColumnNewUUID (ByVal columnID As Integer) As Boolean

C#

public unsafe bool IsColumnNewUUID (int columnID)

Parameters

columnID The ID number of the column. The value must be in the range
[0,ULCursorSchema.ColumnCount-1]. The first column in the table has an ID value of zero.

Returns

True if the column defaults to a new UUID, false if the column does not default to a new UUID.

Exceptions

ULException class A SQL error occurred.

Related Information

ColumnCount property [page 266]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 593
4.1.38.14 IsColumnNullable(int) method

Checks whether the specified column is nullable.

 Syntax

Visual Basic

Public Function IsColumnNullable (ByVal columnID As Integer) As Boolean

C#

public unsafe bool IsColumnNullable (int columnID)

Parameters

columnID The ID number of the column. The value must be in the range
[0,ULCursorSchema.ColumnCount-1]. The first column in the table has an ID value of zero.

Returns

True if the column is nullable, false if it is not nullable.

Exceptions

ULException class A SQL error occurred.

Related Information

ColumnCount property [page 266]

UltraLite - .NET API Reference

594 PUBLIC UltraLite .NET API reference
4.1.38.15 IsInPublication(string) method

Checks whether the table is contained in the named publication.

 Syntax

Visual Basic

Public Function IsInPublication (ByVal pubName As String) As Boolean

C#

public unsafe bool IsInPublication (string pubName)

Parameters

pubName The name of the publication.

Returns

True if the table is in the publication, false if the table is not in the publication.

Exceptions

ULException class A SQL error occurred.

4.1.38.16 VerifyOpen() method

 Syntax

Visual Basic

Protected Overridable Overrides Sub VerifyOpen ()

C#

protected virtual override void VerifyOpen ()

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 595
4.1.38.17 IndexCount property

Returns the number of indexes on the table.

 Syntax

Visual Basic

Public ReadOnly Property IndexCount As Integer

C#

public unsafe int IndexCount {get;}

Remarks

The number of indexes on the table or 0 if the table schema is closed.

Index IDs range from 1 to the IndexCount value, inclusively.

 Note

Index IDs and count may change during a schema upgrade. To correctly identify an index, access it by
name or refresh the cached IDs and counts after a schema upgrade.

4.1.38.18 IsNeverSynchronized property

Checks whether the table is marked as never being synchronized.

 Syntax

Visual Basic

Public ReadOnly Property IsNeverSynchronized As Boolean

C#

public unsafe bool IsNeverSynchronized {get;}

Remarks

True if the table is marked as never being synchronized, false otherwise.

Tables marked as never being synchronized are never synchronized, even if they are included in a publication.
These tables are sometimes referred to as "no sync" tables.

UltraLite - .NET API Reference

596 PUBLIC UltraLite .NET API reference
4.1.38.19 Name property

Returns the name of the table.

 Syntax

Visual Basic

Public ReadOnly Overrides Property Name As String

C#

public override string Name {get;}

Remarks

The name of the table as a string.

4.1.38.20 PrimaryKey property

Returns the index schema of the primary key for the table.

 Syntax

Visual Basic

Public ReadOnly Property PrimaryKey As ULIndexSchema

C#

public unsafe ULIndexSchema PrimaryKey {get;}

Remarks

A ULIndexSchema object representing the primary key for the table.

Related Information

ULIndexSchema class [page 388]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 597
4.1.38.21 UploadUnchangedRows property

Checks whether the database uploads rows that have not changed.

 Syntax

Visual Basic

Public ReadOnly Property UploadUnchangedRows As Boolean

C#

public unsafe bool UploadUnchangedRows {get;}

Remarks

True if the table is marked to always upload all rows during synchronization, false if the table is marked to
upload only changed rows.

Tables marked as such upload unchanged rows, as well as changed rows, when the table is synchronized.
These tables are sometimes referred to as "all sync" tables.

4.1.39 ULTransaction class

Represents a SQL transaction.

 Syntax

Visual Basic

Public NotInheritable Class ULTransaction Inherits

System.Data.Common.DbTransaction

C#

public sealed class ULTransaction : System.Data.Common.DbTransaction

Members

All members of ULTransaction, including inherited members.

Methods

UltraLite - .NET API Reference

598 PUBLIC UltraLite .NET API reference
 Modifier and Type Method Description

public override void Commit() [page 600] Commits the database transaction.

protected override void Dispose(bool) [page 600]

public override void Rollback() [page 601] Rolls back the transaction's outstand­
ing changes to the database.

Properties

Modifier and Type Property Description

public new ULConnection Connection [page 601] Returns the connection associated with
the transaction.

protected override DbConnection DbConnection [page 602]

public override IsolationLevel IsolationLevel [page 602] Returns the isolation level for the trans­
action.

Remarks

There is no constructor for the ULTransaction class. To obtain a ULTransaction object, use the
ULConnection.BeginTransaction method. To associate a command with a transaction, use the
ULCommand.Transaction property.

Once a transaction has been committed or rolled back, the connection reverts to automatically committing all
operations as they are executed. To group more operations together, a new transaction must be created.

In this section:

Commit() method [page 600]

Commits the database transaction.

Dispose(bool) method [page 600]

Rollback() method [page 601]

Rolls back the transaction's outstanding changes to the database.

Connection property [page 601]

Returns the connection associated with the transaction.

DbConnection property [page 602]

IsolationLevel property [page 602]

Returns the isolation level for the transaction.

Related Information

BeginTransaction() method [page 164]

Transaction property [page 134]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 599
4.1.39.1 Commit() method

Commits the database transaction.

 Syntax

Visual Basic

Public Overrides Sub Commit ()

C#

public override void Commit ()

Remarks

Once a transaction has been committed or rolled back, the connection reverts to automatically committing all
operations as they are executed. To group more operations together, a new transaction must be created.

If a Commit method call fails due to a database error (for example, a referential integrity error), the transaction
remains active. Correct the error and call the Commit method again or call the ULTransaction.Rollback method
to complete the transaction.

Related Information

Rollback() method [page 601]

4.1.39.2 Dispose(bool) method

 Syntax

Visual Basic

Protected Overrides Sub Dispose (ByVal disposing As Boolean)

C#

protected override void Dispose (bool disposing)

UltraLite - .NET API Reference

600 PUBLIC UltraLite .NET API reference
4.1.39.3 Rollback() method

Rolls back the transaction's outstanding changes to the database.

 Syntax

Visual Basic

Public Overrides Sub Rollback ()

C#

public override void Rollback ()

Remarks

Once a transaction has been committed or rolled back, the connection reverts to automatically committing all
operations as they are executed. To group more operations together, a new transaction must be created.

Related Information

Commit() method [page 600]

4.1.39.4 Connection property

Returns the connection associated with the transaction.

 Syntax

Visual Basic

Public ReadOnly Shadows Property Connection As ULConnection

C#

public new ULConnection Connection {get;}

Remarks

The ULConnection object associated with the transaction, or a null reference (Nothing in Visual Basic) if the
transaction is no longer valid.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 601
This is the strongly-typed version of the System.Data.IDbTransaction.Connection and
System.Data.Common.DbCommand.Connection properties.

Related Information

BeginTransaction() method [page 164]

ULConnection class [page 151]

4.1.39.5 DbConnection property

 Syntax

Visual Basic

Protected ReadOnly Overrides Property DbConnection As DbConnection

C#

protected override DbConnection DbConnection {get;}

4.1.39.6 IsolationLevel property

Returns the isolation level for the transaction.

 Syntax

Visual Basic

Public ReadOnly Overrides Property IsolationLevel As IsolationLevel

C#

public override IsolationLevel IsolationLevel {get;}

Remarks

One of the System.Data.IsolationLevel values. UltraLite.NET only supports the

System.Data.IsolationLevel.ReadUncommitted value.

UltraLite - .NET API Reference

602 PUBLIC UltraLite .NET API reference
Related Information

BeginTransaction() method [page 164]

4.1.40 ULInfoMessageEventHandler(object,
ULInfoMessageEventArgs) delegate

Represents the method that handles the ULConnection.InfoMessage event.

 Syntax

Visual Basic

Public Delegate Sub ULInfoMessageEventHandler (

ByVal obj As Object,
ByVal args As ULInfoMessageEventArgs
) As delegate void

C#

public delegate void ULInfoMessageEventHandler (

object obj,
ULInfoMessageEventArgs args
);

Parameters

obj The connection sending the event.

args The ULInfoMessageEventArgs object that contains the event data.

Related Information

InfoMessage event [page 213]

ULInfoMessageEventArgs class [page 398]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 603
4.1.41 ULRowsCopiedEventHandler(object,
ULRowsCopiedEventArgs) delegate

Represents the method that handles the ULBulkCopy.ULRowsCopied event.

 Syntax

Visual Basic

Public Delegate Sub ULRowsCopiedEventHandler (

ByVal sender As Object,
ByVal rowsCopiedEventArgs As ULRowsCopiedEventArgs
) As delegate void

C#

public delegate void ULRowsCopiedEventHandler (

object sender,
ULRowsCopiedEventArgs rowsCopiedEventArgs
);

Remarks

The ULRowsCopiedEventHandler delegate is not available in the .NET Compact Framework 2.0.

Related Information

ULRowsCopied event [page 67]

4.1.42 ULRowUpdatedEventHandler(object,
ULRowUpdatedEventArgs) delegate

Represents the method that handles the ULDataAdapter.RowUpdated event.

 Syntax

Visual Basic

Public Delegate Sub ULRowUpdatedEventHandler (

ByVal sender As Object,
ByVal e As ULRowUpdatedEventArgs
) As delegate void

C#

public delegate void ULRowUpdatedEventHandler (

object sender,

UltraLite - .NET API Reference

604 PUBLIC UltraLite .NET API reference
 ULRowUpdatedEventArgs e
);

Parameters

sender The connection sending the event.

e The ULRowUpdatedEventArgs object that contains the event data.

Related Information

RowUpdated event [page 281]

ULRowUpdatedEventArgs class [page 499]

4.1.43 ULRowUpdatingEventHandler(object,
ULRowUpdatingEventArgs) delegate

Represents the method that handles the ULDataAdapter.RowUpdating event.

 Syntax

Visual Basic

Public Delegate Sub ULRowUpdatingEventHandler (

ByVal sender As Object,
ByVal e As ULRowUpdatingEventArgs
) As delegate void

C#

public delegate void ULRowUpdatingEventHandler (

object sender,
ULRowUpdatingEventArgs e
);

Parameters

sender The connection sending the event.

e The ULRowUpdatingEventArgs object that contains the event data.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 605
Related Information

RowUpdating event [page 282]

ULRowUpdatingEventArgs class [page 502]

4.1.44 ULSyncProgressedDlg(IAsyncResult,
ULSyncProgressData) delegate

Represents the method that is invoked during synchronization with synchronization progress information.

 Syntax

Visual Basic

Public Delegate Sub ULSyncProgressedDlg (

ByVal result As IAsyncResult,
ByVal data As ULSyncProgressData
) As delegate void

C#

public delegate void ULSyncProgressedDlg (

IAsyncResult result,
ULSyncProgressData data
);

Parameters

result The IAsyncResult object returned from the BeginSynchronize method. Use result.AsyncState to
access the object provided to the BeginSynchronize method.
data A ULSyncProgressData object containing the latest synchronization progress data.

Remarks

It is safe to do GUI work or to make UltraLite.NET API calls in this method. The synchronization is not being
held up during calls to this method.

Related Information

BeginSynchronize(Control, ULSyncProgressedDlg, object) method [page 162]

ULSyncProgressData class [page 525]

UltraLite - .NET API Reference

606 PUBLIC UltraLite .NET API reference
4.1.45 ULAuthStatusCode enumeration

UL Ext: Enumerates the status codes that may be reported during MobiLink user authentication.

 Syntax

Visual Basic

Public Enum ULAuthStatusCode

C#

enum ULAuthStatusCode

Members

Member name Description Value

UNKNOWN Authorization status is unknown, possi­ 0

bly because the connection has not yet
performed a synchronization (UN­
KNOWN = 0).

VALID User ID and password were valid at time 1

of synchronization (VALID = 1).

VALID_BUT_EXPIRES_SOON User ID and password were valid at time 2

of synchronization, but expire soon
(VALID_BUT_EXPIRES_SOON = 2).

EXPIRED User ID or password has expired - au­ 3

thorization failed (EXPIRED = 3).

INVALID Bad user ID or password - authorization 4

failed (INVALID = 4).

IN_USE User ID is already in use - authorization 5

failed (IN_USE = 5).

Related Information

AuthStatus property [page 543]

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 607
4.1.46 ULBulkCopyOptions enumeration

A bitwise flag that specifies one or more options to use with an instance of the ULBulkCopy class.

 Syntax

Visual Basic

Public Enum ULBulkCopyOptions

C#

enum ULBulkCopyOptions

Members

Member name Description Value

Default Specifying only this causes the default 0x0

behavior to be used.

KeepIdentity When specified, the source values to be 0x1

copied into an identity column are pre­
served.

By default, new identity values are gen­

erated in the destination table.

UseInternalTransaction When specified, each batch of the bulk- 0x2

copy operation is executed within a
transaction.

When not specified, transactions aren't

used. If you indicate this option and
also provide a ULTransaction object to
the constructor, a System.ArgumentEx­
ception occurs.

Remarks

The ULBulkCopyOptions class is not available in the .NET Compact Framework 2.0.

The ULBulkCopyOptions enumeration is used when you construct a ULBulkCopy instance to specify how
WriteToServer methods behave.

UltraLite - .NET API Reference

608 PUBLIC UltraLite .NET API reference
Related Information

ULBulkCopy class [page 53]

4.1.47 ULDateOrder enumeration

UL Ext: Enumerates the date orders that a database can support.

 Syntax

Visual Basic

Public Enum ULDateOrder

C#

enum ULDateOrder

Members

Member name Description

YMD The year followed by month, followed by day of the month.

MDY The month followed by day of the month, followed by year.

DMY The day of the month followed by month, followed by year.

4.1.48 ULDbType enumeration

Enumerates the UltraLite.NET database data types.

 Syntax

Visual Basic

Public Enum ULDbType

C#

enum ULDbType

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 609
Members

Member name Description Value

BigInt Signed 64-bit integer. ULNET_TYPE_S_BIG

Binary Binary data, with a specified maximum ULNET_TYPE_BINARY

length.

The Binary and VarBinary enumeration

values are aliases of each other.

Bit 1-bit flag. ULNET_TYPE_BIT

Char Character data, with a specified length. ULNET_TYPE_FIXCHAR

In UltraLite.NET, this type always sup­

ports Unicode characters. The Char and
VarChar types are fully compatible.

Date Date information. ULNET_TYPE_DATE

DateTime Timestamp information (date, time). ULNET_TYPE_TIMESTAMP

The DateTime and TimeStamp enumer­

ation values are aliases of each other.

Decimal Exact numerical data, with a specified ULNET_TYPE_NUMERIC

precision and scale.

The Decimal and Numeric enumeration

values are aliases of each other.

Double Double precision floating­point number ULNET_TYPE_DOUBLE

(8 bytes).

Float Single precision floating­point number ULNET_TYPE_REAL

(4 bytes).

The Float and Real enumeration values

are aliases of each other.

Integer Unsigned 32-bit integer. ULNET_TYPE_S_LONG

LongBinary Binary data, with variable length. ULNET_TYPE_LONGBINARY

LongVarchar Character data, with variable length. ULNET_TYPE_LONGVARCHAR

In UltraLite.NET, this type always sup­

ports Unicode characters.

Numeric Exact numerical data, with a specified ULNET_TYPE_NUMERIC

precision and scale.

The Decimal and Numeric enumeration

values are aliases of each other.

UltraLite - .NET API Reference

610 PUBLIC UltraLite .NET API reference
 Member name Description Value

Real Single precision floating­point number ULNET_TYPE_REAL

(4 bytes).

The Float and Real enumeration values

are aliases of each other.

SmallInt Signed 16-bit integer. ULNET_TYPE_S_SHORT

STGeometry ST_Geometry information. ULNET_TYPE_ST_GEOMETRY

Time Time information. ULNET_TYPE_TIME

TimeStamp Timestamp information (date, time). ULNET_TYPE_TIMESTAMP

The DateTime and TimeStamp enumer­

ation values are aliases of each other.

TimeStampWithTimeZone Timestamp information (date, time) ULNET_TYPE_TIME­

along with the time zone offset. STAMP_WITH_TIME_ZONE

TinyInt Unsigned 8-bit integer. ULNET_TYPE_TINY

UniqueIdentifier Universally Unique Identifier (UUID/ ULNET_TYPE_UUID

GUID).

UnsignedBigInt Unsigned 64-bit integer. ULNET_TYPE_U_BIG

UnsignedInt Unsigned 32-bit integer. ULNET_TYPE_U_LONG

UnsignedSmallInt Unsigned 16-bit integer. ULNET_TYPE_U_SHORT

VarBinary Binary data, with a specified maximum ULNET_TYPE_BINARY

length.

The Binary and VarBinary enumeration

values are aliases of each other.

VarChar Character data, with a specified maxi­ ULNET_TYPE_CHAR

mum length.

In UltraLite.NET, this type always sup­

ports Unicode characters. The Char and
VarChar types are fully compatible.

Remarks

The table below lists which .NET types are compatible with each ULDbType. In the case of integral types, table
columns can always be set using smaller integer types, but can also be set using larger types as long as the
actual value is within the range of the type.

ULDbType Compatible .NET type C# built-in type Visual Basic built-in type

Binary, VarBinary System.Byte[], or Sys­ byte[] Byte()

tem.Guid if size is 16

Bit System.Boolean bool Boolean

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 611
ULDbType Compatible .NET type C# built-in type Visual Basic built-in type

Char, VarChar System.String String String

Date System.DateTime DateTime (no built-in type) Date

Double System.Double double Double

LongBinary System.Byte[] byte[] Byte()

LongVarchar System.String String String

Decimal, Numeric System.Decimal decimal Decimal

Float, Real System.Single float Single

BigInt System.Int64 long Long

Integer System.Int32 int Integer

SmallInt System.Int16 short Short

ST_Geometry System.String String String

Time System.TimeSpan TimeSpan (no built-in type) TimeSpan (no built-in type)

DateTime, TimeStamp System.DateTime DateTime (no built-in type) Date

TimeStampWithTimeZone System.String String String

TinyInt System.Byte byte Byte

UnsignedBigInt System.UInt64 ulong UInt64 (no built-in type)

UnsignedInt System.UInt32 uint UInt32 (no built-in type)

UnsignedSmallInt System.UInt16 ushort UInt16 (no built-in type)

UniqueIdentifier System.Guid Guid (no built-in type) Guid (no built-in type)

Binary columns of length 16 are fully compatible with the UniqueIdentifier type.

Related Information

GetFieldType(int) method [page 321]

GetDataTypeName(int) method [page 317]
GetColumnULDbType(int) method [page 264]

4.1.49 ULDBValid enumeration

Enumerates the UltraLite.NET database validation methods

 Syntax

Visual Basic

Public Enum ULDBValid

UltraLite - .NET API Reference

612 PUBLIC UltraLite .NET API reference
 C#

enum ULDBValid

Members

Member name Description Value

EXPRESS_VALIDATE Performs a faster, though less thor­ 0

ough, validation.

FULL_VALIDATE Validates tables, indexes, and all data­ 1

base pages.

Related Information

ValidateDatabase(string, ULDBValid) method [page 290]

ValidateDatabase(ULDBValid) method [page 204]
ValidateDatabase(ULDBValid, string) method [page 205]

4.1.50 ULRuntimeType enumeration

UL Ext: Enumerates the types of UltraLite.NET runtimes.

 Syntax

Visual Basic

Public Enum ULRuntimeType

C#

enum ULRuntimeType

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 613
Members

Member name Description Value

STANDALONE_UL Selects the standalone UltraLite.NET 0

runtime.

The standalone runtime accesses data­

bases directly. Databases are accessed
more quickly this way, but cannot be
shared.

UL_ENGINE_CLIENT Selects the UltraLite engine runtime. 1

The UltraLite.NET engine client com­

municates with the UltraLite engine to
access databases. Databases can be
shared by different applications.

Related Information

RuntimeType property [page 291]

4.1.51 ULSqlProgressState enumeration

UL Ext: Enumerates all the states that can occur while executing SQL passthrough scripts.

 Syntax

Visual Basic

Public Enum ULSqlProgressState

C#

enum ULSqlProgressState

Members

Member name Description Value

STATE_STARTING No scripts have been executed yet. 0

STATE_RUNNING_SCRIPT Currently running a SQL passthrough 1

script.

UltraLite - .NET API Reference

614 PUBLIC UltraLite .NET API reference
 Member name Description Value

STATE_DONE Scripts have successfully completed. 2

STATE_ERROR Scripts have completed, but an error 3

occurred.

Related Information

ULSqlProgressData class (Deprecated) [page 507]

4.1.52 ULStreamType enumeration

UL Ext: Enumerates the types of MobiLink synchronization streams to use for synchronization.

 Syntax

Visual Basic

Public Enum ULStreamType

C#

enum ULStreamType

Members

Member name Description

TCPIP Synchronize via TCP/IP.

HTTP Synchronize via HTTP.

The HTTP stream uses TCP/IP as its underlying transport.

UltraLite applications act as web browsers and the MobiLink
server acts as a web server. UltraLite applications send
POST requests to send data to the server and GET requests
to read data from the server.

HTTPS Synchronize via HTTPS (HTTP with transport-layer secur­

ity).

TLS Synchronize via TCP/IP with transport layer security.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 615
Related Information

Stream property [page 521]

4.1.53 ULSyncProgressState enumeration

UL Ext: Enumerates all the states that can occur while synchronizing.

 Syntax

Visual Basic

Public Enum ULSyncProgressState

C#

enum ULSyncProgressState

Members

Member name Description Value

STATE_STARTING No synchronization actions have been 0

taken yet.

STATE_CONNECTING The synchronization stream has been 1

built, but is not yet opened.

STATE_RESUMING_DOWNLOAD An optional state that is entered when 2

we are attempting to resume a partial
download.

On success, sync will proceed to the

STATE_RECEIVING_TABLE state, and
STATE_ERROR if we are unable to re­
sume.

STATE_SENDING_HEADER The synchronization stream has been 3

opened and the header is about to be
sent.

STATE_SENDING_CHECK_SYNC_RE­ The state of the last upload is unknown, 4

QUEST so a request to check its status is being
sent.

STATE_WAIT­ Waiting for the server to respond to the 5

ING_FOR_CHECK_SYNC_RESPONSE check sync request.

UltraLite - .NET API Reference

616 PUBLIC UltraLite .NET API reference
 Member name Description Value

STATE_PROCESS­ The response to the check sync request 6

ING_CHECK_SYNC_RESPONSE has been received and is being proc­
essed.

STATE_SENDING_TABLE A table is being sent. 7

Progress can be monitored using the

ULSyncProgressData.SyncTableIndex
and ULSyncProgressData.SyncTable­
Count properties.

STATE_SENDING_DATA Data for the current table is being sent. 8

The ULSyncProgressData.SentBytes,
ULSyncProgressData.SentInserts, UL­
SyncProgressData.SentUpdates, and
ULSyncProgressData.SentDeletes
properties have been updated.

STATE_FINISHING_UPLOAD The upload is completing. 9

The final count of rows sent is included

with this event.

STATE_WAITING_FOR_UPLOAD_ACK Waiting for the server to acknowledge 10

receiving our upload.

STATE_PROCESSING_UPLOAD_ACK The server has acknowledged receiving 11

our upload.

STATE_WAITING_FOR_DOWNLOAD Waiting for the server to start sending 12

the download.

STATE_RECEIVING_TABLE A table is being received. 13

Progress can be monitored using the

ULSyncProgressData.SyncTableIndex
and ULSyncProgressData.SyncTable­
Count properties.

STATE_RECEIVING_DATA Data for the current table is being re­ 14

ceived.

The ULSyncProgressData.Received­
Bytes, ULSyncProgressData.Receive­
dInserts, ULSyncProgressData.Receive­
dUpdates, and ULSyncProgress­
Data.ReceivedDeletes properties have
been updated.

STATE_COMMITTING_DOWNLOAD The download is being committed. 15

The final count of rows received is in­

cluded with this event.

UltraLite - .NET API Reference

UltraLite .NET API reference PUBLIC 617
Member name Description Value

STATE_ROLLING_BACK_DOWNLOAD Synchronization is rolling back the 16

download because an error was en­
countered during the download.

The error is reported with a subsequent

STATE_ERROR progress report.

STATE_SENDING_DOWNLOAD_ACK An acknowledgement of download 17

completion is being sent.

STATE_DISCONNECTING The synchronization stream is about to 18

be closed.

STATE_DONE Synchronization has successfully com­ 19

pleted.

STATE_ERROR Synchronization has completed, but an 20

error occurred.

STATE_CANCELLED Synchronization has been canceled. 21

Related Information

ULSyncProgressData class [page 525]

ReceivedBytes property [page 531]
ReceivedInserts property [page 532]
ReceivedUpdates property [page 533]
ReceivedDeletes property [page 532]
SentBytes property [page 533]
SentInserts property [page 535]
SentUpdates property [page 535]
SentDeletes property [page 534]
SyncTableIndex property [page 537]
SyncTableCount property [page 536]

UltraLite - .NET API Reference

618 PUBLIC UltraLite .NET API reference
Important Disclaimers and Legal Information

Hyperlinks
Some links are classified by an icon and/or a mouseover text. These links provide additional information.
About the icons:

● Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your
agreements with SAP) to this:

● The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.
● SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any
damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.

● Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering a SAP-hosted Web site. By using such
links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this
information.

Beta and Other Experimental Features

Experimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by
SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use
the experimental features in a live operating environment or with data that has not been sufficiently backed up.
The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your
feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.

Example Code
Any software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax
and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of
example code unless damages have been caused by SAP's gross negligence or willful misconduct.

Gender-Related Language
We try not to use gender­specific word forms and formulations. As appropriate for context and readability, SAP may use masculine word forms to refer to all genders.

UltraLite - .NET API Reference

Important Disclaimers and Legal Information PUBLIC 619
www.sap.com/contactsap

© 2019 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form

or for any purpose without the express permission of SAP SE or an SAP
affiliate company. The information contained herein may be changed
without prior notice.

Some software products marketed by SAP SE and its distributors

contain proprietary software components of other software vendors.
National product specifications may vary.

These materials are provided by SAP SE or an SAP affiliate company for

informational purposes only, without representation or warranty of any
kind, and SAP or its affiliated companies shall not be liable for errors or
omissions with respect to the materials. The only warranties for SAP or
SAP affiliate company products and services are those that are set forth
in the express warranty statements accompanying such products and
services, if any. Nothing herein should be construed as constituting an
additional warranty.

SAP and other SAP products and services mentioned herein as well as
their respective logos are trademarks or registered trademarks of SAP
SE (or an SAP affiliate company) in Germany and other countries. All
other product and service names mentioned are the trademarks of their
respective companies.

Please see https://www.sap.com/about/legal/trademark.html for

additional trademark information and notices.

THE BEST RUN