Open Client Client-Library/C Reference Manual

Home

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Capabilities

Capabilities describe features that a client/server connection supports. In particular, capabilities describe the types of requests that an application sends on a specific connection and the types of server responses that a server returns on a specific connection.

Wide tables and larger page size

Open Client/Open Server 12.5 allow client applications to send and receive wide data and data for larger numbers of columns that are supported in Adaptive Server 12.5; that is, columns in excess of 255 bytes, and more than 255 columns per table.

Client-Library applications compiled on earlier versions of Client-Library must be recompiled with the Open Client/Open Server 12.5 libraries to enable the new limits.

Page size

Adaptive Server Enterprise 12.5 supports logical page sizes of 2K, 4K, 8K, and 16K. Open Client/Open Server uses the Bulk-Library (blklib) routines to populate these pages. Until the release of 12.5, blklib only supported the Adaptive Server page size of 2K.

Table 2-7 lists the new bulk library constants and their values.

Page size values
blk_pagesize	blk_maxdatarow	blk_maxcolsize	blk_maxcolno	blk_boundary
2K	1962	1960	1962	1960
4K	4010	4008	4010	4008
8K	8106	8104	8106	8104
16K	16298	16296	16298	16298

Increased page size limits allow for increased number of columns, depending upon the type of table. The limits are:

1024 for fixed-length columns in both all-pages locking (APL) and data-only locking (DOL) tables
254 for variable-length columns in an APL table
1024 for variable-length columns in an DOL table

No changes have been made to the existing blklib APIs, nor have any new APIs been added to accommodate the larger page size support in Adaptive Server 12.5.

Compatibility

Support for wide data and a larger number of columns is automatically enabled if:

The client is set to CS_VERSION_125 or higher,
It is linked with Open Client Server 125 library, and
The Adaptive Server to which it is connected has the capabilities to handle wide tables. To determine the version of Adaptive Server:
```
1> select @@version
```
```
2> go
```

If Open Client/Open Server 12.5 blklib is linked to a version 12.5 bcp application that communicates with a pre-12.5 Adaptive Server, the bcp utility assumes that Adaptive Server has the 2K page size.

If the blklib is linked to a bcp application that was built with a version of the utility earlier than 12.5 (the version string is not set to CS_VERSION_125), it cannot support the copy of large pages.

Wide tables

Adaptive Server Enterprise 12.5 supports tables with more than 255 columns and column sizes in excess of 255 bytes or 255-byte binary data. To accommodate the expanded table limits in Adaptive Server, Open Client/Open Server 12.5 can send and receive wider data and column information for tables with more columns.

Capability

To support wide tables, the client sends a login packet to the server along with a capability packet. Possible ct_capability parameters include:

CS_WIDETABLE - a request capability that a client sends to the server indicating the client has the capability to receive larger data table formats.
CS_NOWIDETABLE - a response capability that a client sends to the server to have the server disable wide table support for this particular connection.

If the version of the application is set to CS_VERSION_125, Client-Library always sends CS_WIDETABLE capability to the server; the application does not have control of the request capability. However, the application can set CS_NOWIDETABLE response capability before the connection is established to specifically request the server not to enable wide table capabilities.

The syntax of ct_capability is:

CS_RETCODE ct_capability (connection, action, type,
        capability, value)

   CS_CONNECTION              *connection;

   CS_INT                      action;

   CS_INT                      type;

   CS_INT                      capability;

   CS_VOID                     *value;

where the values of type are CS_WIDETABLES or CS_NOWIDETABLES.

If you do not want to enable wide table support, you can send the server a CS_NOWIDETABLE command to disable this feature.

...

CS_BOOL     boolv = CS_TRUE

...

 retcode = ct_capability ( *conn_ptr, CS_SET, CS_CAP_RESPONSE, 
     CS_NOWIDETABLES, &boolv);

...

ct_dynamic() with CS_CURSOR_DECLARE supports the flags CS_PREPARE, CS_EXECUTE, and CS_EXEC_IMMEDIATE to prepare and execute dynamic SQL statements that reference the 1024-column limit of Adaptive Server 12.5.

ct_param() can be used to pass as many as 1024 arguments to a dynamic SQL statement.

Changes in application program

If the column data you are retrieving is in excess of CS_MAX_CHAR (256 characters or 256 binary data), you must edit the CS_DATAFMT structure field datafmt.maxlength definition to the maximum length, in bytes, of the data that you are retrieving. Otherwise you get a truncation error.

If you expect wider columns in the client program, change the column array size in the application program.

For example, if the application expects a column that is 300 bytes wide, then the column should mention CS_CHAR col1[300] at an appropriate place. Assign an appropriate length-of-character datatype, to the maxlength parameter of the CS_DATAFMT structure for RPC applications if the column is more than 255 bytes. The following is recommended for the CS_DATAFMT parameter:

datafmt.datatype = CS_LONGCHAR_TYPE
datafmt.maxlength = sizeof(col1)

The following example is a small ctlib program using the pubs2 database.

Alter the authors table and add a column "comment" declare as a varchar(500):
```
1>alter table authors add comment varchar(500) null 
2>go
```

Update the new column within the table:

1>update authors set comment = replicate (substring(state,1,1), 500)
2>go 
/* This SQL command will update the comment column with a replicate of 500 times the first letter of the state for each row. */

Modify the example.h file to set the "new limits" capabilities.
```
#define EX_CTLIB_VERSION CS_VERSION_125
```
Update the exutils.h file and reset the MAX_CHAR_BUF to 16384 (16K).
Recompile and link ctlib using 12.5 headers and libraries.

Execute and test on a Adaptive Server version 12.5 Xk page size server.

If you set CS_VERSION_125, you see the following (only displays the last 2 rows):

Heather              McBadden                                 95688       CCCCCC
CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
CCCCCCCCCCCCCC
Anne                 Ringer                                   84152       UUUUUU
UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU
UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU
UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU
UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU
UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU
UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU
UUUUUUUUUUUUUU

Update the example.h file and reset ctlib to CS_VERSION_120. Recompile and link using OCS-12_5 headers and libraries.

If you execute the same program without setting CS_VERSION_125 first, you retrieve only the first 255 bytes of the comment column and cannot retrieve wide columns, even if you are using version 12.5 of Adaptive Server and OCS-12.5 libraries.

Open Client message:

Message number: LAYER = (1) ORIGIN = (4) SEVERITY = (1) NUMBER = (132)
Message String: ct_fetch(): user api layer: internal common library error: The bind of result set item 4 resulted in truncation.
Error on row 21.
Heather              McBadden                                 95688       CCCCCC
CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC

Open Client message:

Message number: LAYER = (1) ORIGIN = (4) SEVERITY = (1) NUMBER = (132)
Message String: ct_fetch(): user api layer: internal common library error: The bind of result set item 4 resulted in truncation.
Error on row 22.
Anne                 Ringer                                   84152       UUUUUU
UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU
UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU
UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU

Wide-table compatibility

Wide-table support is activated automatically if:

The client is set to CS_VERSION_125,
It is linked with Open Client Server 12.5 library, and
the Adaptive Server to which it is connected has the capabilities to handle wide tables.

If the Client-Library application's version string is not set to CS_VERSION_125, and it is linked to an Open Client/Open Server 12.5, the application does not support the extended limits and there is no behavioral change.

If the Open Client/Open Server version 12.5 connects to a pre-12.5 Adaptive Server, the server returns a capability bit of 0, indicating that it does not support wide tables; the connection is still made but there are no behavioral changes.

Likewise, if a pre-12.5 version of Open Client/Open Server connects to an Adaptive Server 12.5, the new limits are not enabled. However, if the Adaptive Server determines that it must send a wide-table format to an older client, the data is truncated and sent.

Adaptive Server 11.0.x and SQL Server return a mask length of 0 for any mask length in excess of 7 bytes. If the connection request receives a capability mask of 0, you see this error message:

ct_connect(): protocol specific layer: external error: "This server does not accept new larger cpability mask, the original cap mask will be used."

and the extended limits are not enabled.

unichar datatype

Open Client/Open Server 12.5 unichar supports two-byte characters, supporting multilingual client applications, and reducing the overhead associated with character-set conversions.

Designed the same as the Open Client/Open Server CS_CHAR datatype, CS_UNICHAR is a shared, C-programming datatype that can be used anywhere the CS_CHAR datatype is used. The CS_UNICHAR datatype stores character data in Unicode UCS Transformational Format 16-bit (UTF-16), which is two-byte characters.

The Open Client/Open Server CS_UNICHAR datatype corresponds to the Adaptive Server 12.5 UNICHAR fixed-width and UNIVARCHAR variable-width datatypes, which store two-byte characters in the Adaptive Server database.

As a standalone, Open Client 12.5 applications can use this new functionality to convert other datatypes to and from CS_UNICHAR at the client site, even if the server does not have the capability to process two-byte characters.

New datatypes and capabilities

To send and receive two-byte characters, the client specifies its preferred byte order during the login phase of the connection. Any necessary byte swapping is performed on the server site.

The Open Client ct_capability() parameters:

CS_DATA_UCHAR - is a request sent to the server to determine whether the server supports two-byte characters.
CS_DATA_NOUCHAR - is a parameter sent from the client to tell the server not to support unichar for this specific connection.

To access two-byte character data, Open Client/Open Server implements:

CS_UNICHAR- a datatype.
CS_UNICHAR_TYPE - a datatype constant to identify the data's datatype.

Setting the CS_DATAFMT parameter's datatype to CS_UNICHAR_TYPE allows you to use existing API calls, such as ct_bind, ct_describe, ct_param, and so on.

CS_UNICHAR uses the format bitmask field of CS_DATAFMT to describe the destination format.

For example, in the Client Library sample program, rpc.c, the BuildRpcCommand() function contains the section of code that describes the datatype:

...

strcpy (datafmt.name, "@charparam");

datafmt.namelen =CS_NULLTERM;

datafmt.datatype = CS_CHAR_TYPE;

datafmt.maxlength = CS_MAX_CHAR;

datafmt.status = CS_RETURN;

datafmt.locale = NULL;

...

In this example, from the new uni_rpc.c sample program, the character type is defined as

datafmt.datatype = CS_CHAR_TYPE

. Use an ASCII text editor to edit the datafmt.datatype field to:

...

strcpy (datafmt.name, "@charparam");

datafmt.namelen =CS_NULLTERM;

datafmt.datatype = CS_UNICHAR_TYPE;

datafmt.maxlength = CS_MAX_CHAR;

datafmt.status = CS_RETURN;

datafmt.locale = NULL;

...

Since CS_UNICHAR is a UTF-16 encoded Unicode character datatype that is stored in two bytes, the maximum length of CS_UNICHAR string parameter sent to the server is restricted to one-half the length of CS_CHAR, which is stored in one-byte format.

Table 2-8 lists the CS_DATAFMT bitmask fields.

CS_DATAFMT structure
Bitmask field	Description
CS_FMT_NULLTERM	The data is two-byte Unicode null-terminated (0x0000).
CS_FMT_PADBLANK	The data is padded with two-byte Unicode blanks to the full length of the destination variable (0x0020).
CS_FMT_PADNULL	The data is padded with two-byte Unicode nulls to the full length of the destination variable (0x0000).
CS_FMT_UNUSED	No format information is provided.

isql and bcp utilities

Both the isql and the bcp utilities automatically support unichar data if the server supports two-byte character data. bcp now supports 4K, 8K and 16K page sizes.

If the client's default character set is UTF-8, isql displays two-byte character data, and bcp saves two-byte character data in the UTF-8 format. Otherwise, the data is displayed or saved, respectively, in two-byte Unicode data in binary format.

Use

isql -Jutf8

to set the client character set for isql. Use

bcp
-Jutf8

to set the client character set for the bcp utility.

Limitations

The sever to which the Open Client/Open Server is connecting must support two-byte Unicode datatypes, and use UTF-8 as the default character set.

If the server does not support two-byte Unicode datatypes, the server returns an error message:

"Type
not found. Unichar/univarchar is not supported."

CS_UNICHAR does not support the conversion from UTF-8 to UTF-16 byte format for CS_BOUNDARY and CS_SENSITIVITY. All other datatype formats are convertible.

CS_UNICHAR does not provide C programming operations on UTF-16 encoded Unicode data such as Unicode character strings. For full support for Unicode character strings, you must use the Sybase product, Unilab. See the Unilib Reference Manual at The reference manual is part of the Sybase Unicode Developers Kit 2.0.

Capabilities and the connection's TDS level

Sybase clients and servers communicate using the Tabular Data Stream(TM) (TDS) protocol. Different TDS versions support different features. For example, 4.0 TDS is the earliest version that supports remote procedure calls.

The TDS version level is determined when a connection is established. When an application calls ct_connect to connect to a server, Client-Library presents the server with a preferred TDS level. If the server cannot support this TDS level, it negotiates with Client-Library to find a TDS level that is acceptable.

For example, when an 12.5 Client-Library application connects to SQL Server 11.0, the default TDS level that the application requests is 5.0 TDS. Because SQL Server 11.0 does not support 5.0 TDS, it replies with a request to use version 4.x of TDS instead. Because 4.x TDS is acceptable to 12.5 Client-Library, the connection is established with a TDS version level of CS_TDS_4x.

jConnect does not negotiate TDS version -- if the server doesn't support TDS 5.0 jConnect will terminate the connection.

Capabilities describe which client requests and which server responses are sent over a connection. By default, capabilities are based on the TDS version level, but a client application can be coded to further limit response capabilities and a server can be coded to further limit request capabilities.

When a Client-Library calls ct_capability:

Before opening a connection, it sets up the connection structure to tell a server not to send a particular type of response on a connection.
After opening a connection, it determines whether the connection supports a particular type of request or response.

For information on how an Open Server application sets or retrieves capabilities, see the Open Server Server-Library/C Reference Manual.

There are two types of capabilities:

CS_CAP_REQUEST capabilities, or request capabilities, describe the types of client requests that can be sent on a server connection.
CS_CAP_RESPONSE capabilities, or response capabilities, describe the types of server responses that a connection does not wish to receive.

For a list of capabilities, see the reference page for ct_capability.

Setting and retrieving capabilities

Before calling ct_connect, an application:

Retrieves request or response capabilities to determine what request and response features are normally supported at the connection's current TDS version level. A connection's TDS level defaults to the version level that the application requested in its call to ct_init. An application can change a connection's TDS level by calling ct_con_props with property as CS_TDS_VERSION (see "TDS version").
Sets response capabilities to indicate that a connection does not wish to receive particular types of responses. For example, an application sets a connection's TDS_RES_NOEED capability to CS_TRUE to indicate that the connection does not wish to receive extended error data.

After a connection is open, an application:

Retrieves request capabilities to find out what types of requests the connection will support
Retrieves response capabilities to find out whether the server has agreed to withhold the previously indicated response types from the connection

Setting and retrieving multiple capabilities

Gateway applications often need to set or retrieve all capabilities of a type category with a single call to ct_capability. To do this, an application calls ct_capability with:

type as the type category of interest
capability as CS_ALL_CAPS
value as a CS_CAP_TYPE structure

Client-Library provides the following macros to enable an application to set, clear, and test bits in a CS_CAP_TYPE structure:

CS_CLR_CAPMASK(mask, capability) - modifies the CS_CAP_TYPE structure mask by clearing the bits specified in capability..
CS_SET_CAPMASK(mask, capability) - modifies the CS_CAP_TYPE structure mask by setting the bits specified in capability.
CS_TST_CAPMASK(mask, capability) - determines whether the CS_CAP_TYPE mask includes the bits specified in capability.


	Expand Search