ASA Programming Interfaces Guide

Chapter 5: The Open Client Interface

Chapter 5

The Open Client Interface

About this chapter

This chapter describes the Open Client programming interface for Adaptive Server Anywhere.

The primary documentation for Open Client application development is the Open Client documentation, available from Sybase. This chapter describes features specific to Adaptive Server Anywhere, but is not an exhaustive guide to Open Client application programming.

What you need to build Open Client applications

To run Open Client applications, you must install and configure Open Client components on the machine where the application is running. You may have these components present as part of your installation of other Sybase products, or you can optionally install these libraries with Adaptive Server Anywhere, subject to the terms of your license agreement.

Open Client applications do not need any Open Client components on the machine where the database server is running.

To build Open Client applications, you need the development version of Open Client, available from Sybase.

By default, Adaptive Server Anywhere databases are created as case-insensitive, while Adaptive Server Enterprise databases are case sensitive.

For more information on running Open Client applications with Adaptive Server Anywhere, see Adaptive Server Anywhere as an Open Server .

Data type mappings

Open Client has its own internal data types, which differ in some details from those available in Adaptive Server Anywhere. For this reason, Adaptive Server Anywhere internally maps some data types between those used by Open Client applications and those available in Adaptive Server Anywhere.

To build Open Client applications, you need the development version of Open Client. To use Open Client applications, the Open Client runtimes must be installed and configured on the computer where the application runs.

The Adaptive Server Anywhere server does not require any external communications runtime in order to support Open Client applications.

Each Open Client data type is mapped onto the equivalent Adaptive Server Anywhere data type. All Open Client data types are supported

Adaptive Server Anywhere data types with no direct counterpart in Open Client

The following table lists the mappings of data types supported in Adaptive Server Anywhere that have no direct counterpart in Open Client.

ASA data type	Open Client data type
unsigned short	int
unsigned int	bigint
unsigned bigint	bigint
date	smalldatetime
time	smalldatetime
serialization	longbinary
java	longbinary
string	varchar
timestamp struct	datetime

Range limitations in data type mapping

Some data types have different ranges in Adaptive Server Anywhere than in Open Client. In such cases, overflow errors can occur during retrieval or insertion of data.

The following table lists Open Client application data types that can be mapped to Adaptive Server Anywhere data types, but with some restriction in the range of possible values.

In most cases, the Open Client data type is mapped to a Adaptive Server Anywhere data type that has a greater range of possible values. As a result, it is possible to pass a value to Adaptive Server Anywhere that will be accepted and stored in a database, but one that is too large to be fetched by an Open Client application.

	Open Client Lower Range UpperRange	Adaptive Server Anywhere Lower Range UpperRange
MONEY	-922 377 203 685 477.5808	922 377 203 685 477.5807	-1e15+.0001	-1e15-.0001
SMALLMONEY	-214,748.3648	214,748.3647	-214,748.3648	214,748.3647
DATETIME	Jan 1, 1753	Dec 31, 9999	Jan 1, 0001	Dec 31, 9999
SMALLDATETIME	Jan 1, 1900	June 6, 2079	March 1, 1600	Dec 31, 7910

Example

For example, the Open Client MONEY and SMALLMONEY data types do not span the entire numeric range of their underlying Adaptive Server Anywhere implementations. Therefore it is possible to have a value in a Adaptive Server Anywhere column which exceeds the boundaries of the Open Client data type MONEY. When the client fetches any such offending values via Adaptive Server Anywhere, an error is generated.

Timestamps

The Adaptive Server Anywhere implementation of the Open Client TIMESTAMP data type, when such a value is passed in Adaptive Server Anywhere is different from that of Adaptive Server Enterprise. In Adaptive Server Anywhere the value is mapped to the Adaptive Server Anywhere DATETIME data type. The default value is NULL in Adaptive Server Anywhere, and no guarantee is made of its uniqueness. By contrast, Adaptive Server Enterprise ensures that the value is monotonically increasing in value, and so is unique.

By contrast, the Adaptive Server Anywhere TIMESTAMP data type contains year, month, day, hour, minute, second and fraction of second information, and the DATETIME data type has a greater range of possible values than the Open Client data types that are mapped to it by Adaptive Server Anywhere.

Using SQL in Open Client applications

This section provides a very brief introduction to using SQL in Open Client applications, with a particular focus on Adaptive Server Anywhere-specific issues.

For an introduction to the concepts, see Using SQL in Applications . For a complete description, see your Open Client documentation.

Executing SQL statements

You send SQL statements to a database by including them in Client Library function calls. For example, the following pair of calls executes a DELETE statement:

ret = ct_command(cmd, CS_LANG_CMD,
                  "DELETE FROM employee
                   WHERE emp_id=105"
                 CS_NULLTERM, 
                 CS_UNUSED);
ret = ct_send(cmd);

The

ct_command

function is used for a wide range of purposes.

Using prepared statements

The

ct_dynamic

function is used to manage prepared statements. This function takes a type parameter which describes the action you are taking.

To use a prepared statement in Open Client:

Prepare the statement using the

ct_dynamic

function, with a CS_PREPARE type parameter.

Set statement parameters using

ct_param

Execute the statement using

ct_dynamic

with a CS_EXECUTE type parameter.

Free the resources associated with the statement using

ct_dynamic

with a CS_DEALLOC type parameter.

For more information on using prepared statements in Open Client, see your Open Client documentation

Using cursors

The

ct_cursor

function is used to manage cursors. This function takes a type parameter which describes the action you are taking.

Supported cursor types

Not all the types of cursor that Adaptive Server Anywhere supports are available through the Open Client interface. You cannot use scroll cursors, dynamic scroll cursors, and insensitive cursors through Open Client.

Uniqueness and updateability are two properties of cursors. Cursors can be unique (each row carries primary key or uniqueness information, regardless of whether it is used by the application) or not. Cursors can be read only or updateable. If a cursor is updateable and not unique, performance may suffer, as no prefetching of rows is done in this case, regardless of the CS_CURSOR_ROWS setting (see below).

The steps in using cursors

In contrast to some other interfaces, such as Embedded SQL, Open Client associates a cursor with a SQL statement expressed as a string. Embedded SQL first prepares a statement, and then the cursor is declared using the statement handle.

To use cursors in Open Client:

To declare a cursor in Open Client, you use

ct_cursor

with CS_CURSOR_DECLARE as the type parameter.

After declaring a cursor, you can control how many rows are prefetched to the client side each time a row is fetched from the server by using

ct_cursor

with CS_CURSOR_ROWS as the type parameter.

Storing prefetched rows at the client side cuts down the number of calls to the server, and this improves overall throughput as well as turnaround time. Prefetched rows are not immediately passed on to the application, they are stored in a buffer at the client side ready for use.

The setting of the PREFETCH database option controls prefetching of rows for other interfaces. It is ignored by Open Client connections. The CS_CURSOR_ROWS setting is ignored for non-unique, updateable cursors.

To open a cursor in Open Client, you use

ct_cursor

with CS_CURSOR_OPEN as the type parameter.

To fetch each row in to the application, you use

ct_fetch

To close a cursor, you use ct_cursor with CS_CURSOR_CLOSE.

In Open Client, you also need to deallocate the resources associated with a cursor. You do this using ct_cursor with CS_CURSOR_DEALLOC. You can also use CS_CURSOR_CLOSE with the additional parameter CS_DEALLOC to carry out these operations in a single step.

Modifying rows through a cursor

With Open Client, you can delete or update rows in a cursor, as long as the cursor is for a single table. The user must have permissions to update the table and the cursor must be marked for update.

To modify rows through a cursor:

Instead of carrying out a fetch, you can delete or update the current row of the cursor using ct_cursor with CS_CURSOR_DELETE or CS_CURSOR_UPDATE, respectively.

You cannot insert rows through a cursor in Open Client applications.

Describing query results in Open Client

Open Client handles result sets in a different way from some other Adaptive Server Anywhere interfaces.

In Embedded SQL and ODBC, you describe a query or stored procedure in order to set up the proper number and types of variables to receive the results. The description is done on the statement itself.

In Open Client, you do not need to describe a statement. Instead, each row returned from the server can carry a description of its contents. If you use

ct_command

and

ct_send

to execute statements, you can use the

ct_results

function to handle all aspects of rows returned in queries.

If you do not wish to use this row-by-row method of handling result sets, you can use

ct_dynamic

to prepare a SQL statement, and use

ct_describe

to describe its result set. This corresponds more closely to the describing of SQL statements in other interfaces.

Known Open Client limitations of Adaptive Server Anywhere

Using the Open Client interface, you can use an Adaptive Server Anywhere database in much the same way as you would an Adaptive Server Enterprise database. There are some limitations, including the following:

Commit Service
Adaptive Server Anywhere does not support the Adaptive Server Enterprise Commit Service.
Capabilities
A client/server connection's capabilities determine the types of client requests and server responses permitted for that connection. The following capabilities are not supported:
- CS_REG_NOTIF
- CS_CSR_ABS
- CS_CSR_FIRST
- CS_CSR_LAST
- CS_CSR_PREV
- CS_CSR_REL
- CS_DATA_BOUNDARY
- CS_DATA_SENSITIVITY
- CS_PROTO_DYNPROC
- CS_REQ_BCP
Security options, such as SSL and encrypted passwords, are not supported.
Open Client applications may connect to Adaptive Server Anywhere using TCP/IP, or using local machine NamedPipes protocol, where available.
For more information on capabilities, see the Open Server Server-Library C Reference Manual.


	Expand Search