Open Client Client-Library/C Reference Manual

Home

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Capabilities

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.


	Expand Search