Open Client Client-Library/C Reference Manual

Home

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Types

Client-Library supports a wide range of datatypes. These datatypes are shared with Open Client CS-Library and Server-Library. In most cases, they correspond directly to Adaptive Server datatypes.

Table 2-32 lists Open Client/Server type constants, their corresponding C datatypes, and their corresponding Adaptive Server, if any.

Following Table 2-32 is a list of Open Client routines that are useful in manipulating datatypes and more detailed information about each datatype.

For additional information about datatypes, see Chapter 3, "Using Open Client/Server Datatypes," in the Open Client Client-Library/C Programmer's Guide.

Datatype summary

The following table lists Open Client/Server type constants, their corresponding C datatypes, and their corresponding Adaptive Server datatypes, if any:

Datatype summary
Type category	Open Client/Server type constant	Description	Corresponding C datatype	Corresponding server datatype
Binary types	CS_BINARY_TYPE	Binary type	CS_BINARY	binary,varbinary
	CS_LONGBINARY_TYPE	Long binary type	CS_LONGBINARY	None
	CS_VARBINARY_TYPE	Variable-length binary type	CS_VARBINARY	None
Bit types	CS_BIT_TYPE	Bit type	CS_BIT	bit
Character types	CS_CHAR_TYPE	Character type	CS_CHAR	char,varchar
	CS_LONGCHAR_TYPE	Long character type	CS_LONGCHAR	None
	CS_VARCHAR_TYPE	Variable-length character type	CS_VARCHAR	None
	CS_UNICHAR_TYPE	Fixed-length or variable-length character type	CS_UNICHAR	unichar univarchar
Datetime types	CS_DATETIME_TYPE	8-byte datetime type	CS_DATETIME	datetime
Datetime types	CS_DATETIME4_TYPE	4-byte datetime type	CS_DATETIME4	smalldatetime
Numeric types	CS_TINYINT_TYPE	1-byte unsigned integer type	CS_TINYINT	tinyint
	CS_SMALLINT_TYPE	2-byte integer type	CS_SMALLINT	smallint
	CS_INT_TYPE	4-byte integer type	CS_INT	int
	CS_DECIMAL_TYPE	Decimal type	CS_DECIMAL	decimal
	CS_NUMERIC_TYPE	Numeric type	CS_NUMERIC	numeric
	CS_FLOAT_TYPE	8-byte float type	CS_FLOAT	float
	CS_REAL_TYPE	4-byte float type	CS_REAL	real
Money types	CS_MONEY_TYPE	8-byte money type	CS_MONEY	money
Money types	CS_MONEY4_TYPE	4-byte money type	CS_MONEY4	smallmoney
Text and image types	CS_TEXT_TYPE	Text type	CS_TEXT	text
Text and image types	CS_IMAGE_TYPE	Image type	CS_IMAGE	image

Routines that manipulate datatypes

Open Client CS-Library provides several routines that are useful for manipulating datatypes. They include:

cs_calc, which performs arithmetic operations on decimal, money, and numeric datatypes
cs_cmp, which compares datetime, decimal, money, and numeric datatypes
cs_convert, which converts a data value from one datatype to another
cs_dt_crack, which converts a machine readable datetime value into a user-accessible format
cs_dt_info, which sets or retrieves language-specific datetime information
cs_strcmp, which compares two strings

These routines are documented in the Open Client and Open Server Common Libraries Reference Manual.

Open Client datatypes

This section describes the datatypes in Open Client, and provides definitions for the datatypes.

Binary types

Open Client has three binary types, CS_BINARY, CS_LONGBINARY, and CS_VARBINARY.

CS_BINARY corresponds to the Adaptive Server types binary and varbinary. That is, Client-Library interprets both the server binary and varbinary types as CS_BINARY. For example, ct_describe returns CS_BINARY_TYPE when describing a result column that has the server datatype varbinary.
CS_BINARY is defined as:
```
typedef unsigned char    CS_BINARY;    
```
Warning!
CS_LONGBINARY and CS_VARBINARY do not correspond to any SQL Server datatypes.
Some Open Server applications may support CS_LONGBINARY. An application uses the CS_DATA_LBIN capability to determine whether an Open Server connection supports CS_LONGBINARY. If it does, then ct_describe returns CS_LONGBINARY when describing a result data item.
A CS_LONGBINARY value has a maximum length of 2,147,483,647 bytes. CS_LONGBINARY is defined as:
```
typedef unsigned char    CS_LONGBINARY;
```
CS_VARBINARY does not correspond to any SQL Server type. For this reason, Open Client routines do not return CS_VARBINARY_TYPE. CS_VARBINARY is provided to enable non-C programming language veneers to be written for Open Client. Typical client applications will not use CS_VARBINARY.
CS_VARBINARY is defined as:
```
typedef struct _cs_varybin
```
```
 {
```
```
     CS_SMALLINT      len;
```
```
     CS_BYTE          array[CS_MAX_CHAR];
```
```
 } CS_VARBINARY;
```
where:
- len is the length of the binary array.
- array is the array itself.
  Although CS_VARBINARY variables are used to store variable-length values, CS_VARBINARY is considered to be a fixed-length type. This means that an application does not typically need to provide Client-Library with the length of a CS_VARBINARY variable. For example, ct_bind ignores the value of datafmt−>maxlength when binding to a CS_VARBINARY variable.

Bit types

Open Client supports a single bit type, CS_BIT. This type is intended to hold server bit (or boolean) values of 0 or 1. When converting other types to bit, all non-zero values are converted to 1:

typedef unsigned char    CS_BIT;

Character types

Open Client has three character types, CS_CHAR, CS_LONGCHAR, and CS_VARCHAR:

CS_CHAR corresponds to the Adaptive Server types char and varchar. That is, Client-Library interprets both the server char and varchar types as CS_CHAR. For example, ct_describe returns CS_CHAR_TYPE when describing a result column that has the server datatype varchar.
CS_CHAR is defined as:
```
typedef char    CS_CHAR;
```
Warning!
CS_LONGCHAR and CS_VARCHAR do not correspond to any SQL Server datatypes. Specifically, CS_VARCHAR does not correspond to the SQL Server datatype varchar.
CS_LONGCHAR does not correspond to any SQL Server type, but some Open Server applications may support CS_LONGCHAR. An application uses the CS_DATA_LCHAR capability to determine whether an Open Server connection supports CS_LONGCHAR. If it does, then ct_describe returns CS_LONGCHAR when describing a result data item.
A CS_LONGCHAR value has a maximum length of 2,147,483,647 bytes. CS_LONGCHAR is defined as:
```
typedef unsigned char    CS_LONGCHAR;
```
CS_VARCHAR does not correspond to any SQL Server type. For this reason, Open Client routines do not return CS_VARCHAR_TYPE. CS_VARCHAR is provided to enable non-C programming language veneers to be written for Open Client. Typical client applications will not use CS_VARCHAR.
CS_VARCHAR is defined as:
```
typedef struct _cs_varchar
```
```
 {
```
```
     CS_SMALLINT      len;
```
```
     CS_CHAR          str[CS_MAX_CHAR];
```
```
 } CS_VARCHAR;
```
where:
- len is the length of the string.
- str is the string itself. Note that str is not null-terminated.
  Although CS_VARCHAR variables are used to store variable-length values, CS_VARCHAR is considered to be a fixed-length type. This means that an application does not typically need to provide Client-Library with the length of a CS_VARCHAR variable. For example, ct_bind ignores the value of datafmt−>maxlength when binding to a CS_VARCHAR variable.

Datetime types

Open Client supports two datetime types, CS_DATETIME and CS_DATETIME4. These datatypes are intended to hold 8-byte and 4-byte datetime values, respectively.

An Open Client application uses the CS-Library routine cs_dt_crack to extract date parts (year, month, day, etc.) from a datetime structure.

CS_DATETIME corresponds to the Adaptive Server datetime datatype. The range of legal CS_DATETIME values is from January 1, 1753 to December 31, 9999, with a precision of 1/300th of a second (3.33 ms.). The definition of CS_DATETIME is:
```
typedef struct _cs_datetime
```
```
 {
```
```
     CS_INT    dtdays;
```
```
     CS_INT    dttime;
```
```
 } CS_DATETIME;
```
where:
- dtdays is the number of days since 1/1/1900.
- dttime is the number of 300ths of a second since midnight.
CS_DATETIME4 corresponds to the Adaptive Server smalldatetime datatype. The range of legal CS_DATETIME4 values is from January 1, 1900 to June 6, 2079, with a precision of 1 minute. The definition of CS_DATETIME is:
```
typedef struct _cs_datetime4
```
```
 {
```
```
     CS_USHORT    days;
```
```
     CS_USHORT    minutes;
```
```
 } CS_DATETIME4;            
```
where:
- days is the number of days since 1/1/1900.
- minutes is the number of minutes since midnight.

Numeric types

Open Client supports a wide range of numeric types.

Integer types include CS_TINYINT, a 1-byte integer; CS_SMALLINT, a 2-byte integer, and CS_INT, a 4-byte integer:
```
typedef unsigned char    CS_TINYINT;
```
```
typedef short            CS_SMALLINT;
```
```
typedef long             CS_INT;
```
CS_REAL corresponds to the Adaptive Server datatype real. It is implemented as a C-language float type:
```
typedef float    CS_REAL;
```
CS_FLOAT corresponds to the Adaptive Server datatype float. It is implemented as a C-language double type:
```
typedef double   CS_FLOAT;
```
CS_NUMERIC and CS_DECIMAL correspond to the Adaptive Server datatypes numeric and decimal. These types provide platform-independent support for numbers with precision and scale.
The Adaptive Server datatypes numeric and decimal are equivalent; and CS_DECIMAL is defined as CS_NUMERIC:
```
typedef struct_cs_numeric
```
```
 {
```
```
     CS_BYTE         precision;
```
```
     CS_BYTE         scale;
```
```
     CS_BYTE         array[CS_MAX_NUMLEN];
```
```
 } CS_NUMERIC;
```
```
 
```
```
 typedef CS_NUMERIC   CS_DECIMAL;
```
where:
- precision is the maximum number of decimal digits that are represented. At the current time, legal values for precision are from 1 to 77. The default precision is 18. CS_MIN_PREC, CS_MAX_PREC, and CS_DEF_PREC define the minimum, maximum, and default precision values, respectively.
- scale is the maximum number of digits to the right of the decimal point. At the current time, legal values for scale are from 0 to 77. The default scale is 0. CS_MIN_SCALE, CS_MAX_SCALE, and CS_DEF_PREC define the minimum, maximum, and default scale values, respectively.
- scale must be less than or equal to precision.
  CS_DECIMAL types use the same default values for precision and scale as CS_NUMERIC types.

Money types

Open Client supports two money types, CS_MONEY and CS_MONEY4. These datatypes are intended to hold 8-byte and 4-byte money values, respectively.

CS_MONEY corresponds to the Adaptive Server money datatype. The range of legal CS_MONEY values is between +$922,337,203,685,477.5807 and -$922,337,203,685,477.5807:
```
typedef struct _cs_money
```
```
 {
```
```
     CS_INT      mnyhigh;
```
```
     CS_UINT     mnylow;
```
```
 } CS_MONEY;
```
CS_MONEY4 corresponds to the Adaptive Server smallmoney datatype. The range of legal CS_MONEY4 values is between -$214,748.3648 and +$214,748.3647:
```
typedef struct _cs_money4
```
```
 {
```
```
     CS_INT    mny4;
```
```
 } CS_MONEY4;
```

text and image types

Open Client supports a text datatype, CS_TEXT, and an image datatype, CS_IMAGE.

CS_TEXT corresponds to the Adaptive Server datatype text, which describes a variable-length column containing up to 2,147,483,647 bytes of printable character data. CS_TEXT is defined as unsigned character:
```
typedef unsigned char    CS_TEXT;
```
CS_IMAGE corresponds to the Adaptive Server datatype image, which describes a variable-length column containing up to 2,147,483,647 bytes of binary data. CS_IMAGE is defined as unsigned character:
```
typedef unsigned char    CS_IMAGE;
```

Open Client user-defined datatypes

An application that needs to use a datatype that is not included in the standard Open Client type set may create a user-defined datatype.

A Client-Library application creates a user-defined type by declaring it:

typedef char    CODE_NAME;

The Open Client routines ct_bind and cs_set_convert use integer symbolic constants to identify datatypes, so it is often convenient for an application to declare a type constant for a user-defined type. User-defined types must be defined as greater than or equal to CS_USERTYPE:

#define CODE_NAME_TYPE    (CS_USERTYPE + 2)

Once a user-defined type has been created, an application:

Calls cs_set_convert to install custom conversion routines to convert between standard Open Client types and the user-defined type
Calls cs_setnull to define a null substitution value for the user-defined type.

After conversion routines are installed, an application binds server results to a user-defined type:

mydatafmt.datatype = CODE_NAME_TYPE;

 ct_bind(cmd, 1, &mydatafmt, mycodename, NULL,

     NULL);

Custom conversion routines are called transparently, whenever required, by ct_fetch (following a call to ct_bind specifying the conversion) and cs_convert.

Do not confuse Open Client user-defined types with Adaptive Server user-defined types. Open Client user-defined types are C-language types, declared within an application. Adaptive Server user-defined types are database column datatypes, created using the system stored procedure sp_addtype.


	Expand Search