Sybase ct-lib API说明
一.Sybase的二种应用接口 2
二.Open Client / Server的编程接口 2
三.Open Client的函数库 2
1.头文件 3
2.库文件 3
3.控制结构 3
四.数据类型 4
五.接口处理流程 6
1.流程图 6
2. 查询操作流程 6
3. 插入操作流程 7
六.接口函数说明 7
1.分配环境结构空间cs_ctx_alloc 7
2.释放环境结构空间cs_ctx_drop 7
3. 初始化ct_init() 8
4. 分配联接结构ct_con_alloc 8
5. 设置/获取连接connection属性ct_con_props() 8
6. 释放一个CONNECTION结构ct_con_drop() 9
7. 设置或获取context属性ct_config() 9
8. 关闭联接ct_exit() 10
9. 分配command结构ct_cmd_alloc() 10
10. 设置/获取CS_COMMAND结构属性值ct_cmd_props 10
11. 初始化SQL串ct_command() 11
12. 向一个初始化好的SQL命令传递参数Ct_param()/ct_setparam() 12
14. 发送SQL命令ct_send() 13
15. 准备结果集ct_results() 13
16. 释放一个COMMAND结构Ct_cmd_drop 16
17. 获取结果集或命令信息ct_res_info() 16
18. 获取数据每一列的描述ct_describe() 17
19. Ct_options 18
20. 将结果集绑定给输出变量ct_bind() 18
21. 向下取一条记录ct_fetch() 18
22. 安装回叫函数Ct_callback()/cs_config() 19
23. 取消一个命令或清除一个结果集Ct_cancel() 20
24. 关闭一个连接ct_close() 20
25. 初始化一个cursor:ct_cursor() 20
一.Sybase的二种应用接口
SqlServer:是Sybase的数据库服务器,用它可管理一个或多个存储在DB中的信息。接口为T_SQL。
Isql –Uxxx –Pxxxx -Sxxxx
OpenServer:是提供建立一个用户服务器所需的工具与接口。接口为一组C/S的调用函数。又称为OpenServer应用。
二.Open Client / Server的编程接口
见图一
CT-LIB:Client-lib接口, 它需要CS-LIB支持
CS-LIB:Common-lib:包括:数据类型转换,算术运算,字符集转换,时间操作,排序操作,本地错误处理。
DB-LIB:是Sybase早期版本的接口:,它不需要CS-LIB支持
BulK-LIB:批量拷贝库。支持把数据批量存入数据库中。DB-LIB有自己的批量拷贝接口,所以不需要Bulk-Libs支持。
Sybase的库目录:
$(SYBASE)/devlib # for debug library versions
$(SYBASE)/lib # Sybase library directory
三.Open Client的函数库
1. Client-Lib:是提供对C/S体系结构定义的所有服务的完全访问。,这种访问以一种与查询语言和数据库无关的方式进行。可提供真正的异步接口。是Sybase提供的最新版本的API。以CT-作前缀
DB-Lib:提供建立SqlServer与OpenServer客户应用程序的模块。它提供对Sybase特有的应用服务的完全访问。它与SQL有关,但与Sybase Sql Server无关。 是sybase的早期接口,库文件为Libsybdb.a
2. CS-Lib:定义了实现数据类型转换,设置字符集,语言类型及核心的数据结构,所有这引起定义与Ct-lib/Server lib都是共享的。以CS-作前缀
3. Bulk-Lib:批量操作接口。
1.头文件
#include <ctpublic.h>
#include <cspublic.h>
#include < bkpublic.h> ---批量操作
2.库文件
Libct.a:ct-lib库
Libcs.a:Common-lib库
Libblk.a:批量操作库
Libtcl.a:通用网络库
Libinsck.a:TCP/IP Socket库
Libcomn.a:共享库
--------后三个是Sybase内部库,用户无法存取。
3.控制结构
控制结构是指应用程序在与SqlServer建立联接和执行命令之前必须分配一些结构。程序通过设置结构的属性值存储相关的环境配置、联接信息等以实现与Sybase的通讯,并控制程序对DB的操作动作。
1. Context 结构:上下文环境结构CS_CONTEXT
在应用程序初始化ct-lib时必须分配CS_CONTEXT结构,它存储了操作环境的配置信息,如语言类型等。
2. Connection结构:联结结构CS_CONNECTION
一个联接结构存储了与Sybase SQLServer一次联接的信息,如用户名,密码等。一个CS_CONNECTION结构与SqlServer一个进程对应。在一次联接中,一条命令的执行结果必须处理完才能发送另一条命令如果想要处理一条命令过程中执行另一条命令,则必须建立二个联接。
3. Command结构:命令结构CS_COMMAND
命令结构存储的是一系列送往Sybase Sql Server命令。
见图二
见图三
CS_CONTEXT ----> ct_config()/cs_config()
CS_CONNECTION ----> ct_con_props()
CS_COMMAND ----> ct_command() /ct_cmd_props()
控制的属性包括:
CS_MAX_CONNECTION:一个context结构中最多与Server建立联接的最大个数。
CS_NETIO: 指定context结构控制的联接是同步还是异步。
CS_TIMEOUT:建立联接的时限。
CS_USERNAME:连接用户名
CS_PASSWORD:用户名密码
CS_APPNAME:应用名
四.数据类型
类型 Open Client类型 Sybase类型 C类型 描述
Binary CS_BINARY Binary/varbinary 二进制类型
Bit CS_BIT boolean unsigned char BYTE 位类型
Character CS_CHAR Char/varchar Char 字符型
Datetime CS_DATETIME Datetime 8位日期
CS_DATETIME4 Smalldatetime 4位日期
数字类型 CS_TINYINT tinyint unsigned char BYTE 1位整型
CS_SMALLINT Smallint (最大32767) unsigned short int WORD 2位整型
CS_INT int unsigned long int DWORD 4位整型
CS_DECIMAL decimal
CS_NUMERIC Numeric
CS_FLOAT float 8位浮点型
CS_REAL real 4位浮点型
money CS_MONEY money 8位money型
CS_MONEY4 smallmoney 4位money型
text CS_TEXT text 文本型
CS_IMAGE image 图像型
五.接口处理流程
1.流程图
见图四
2. 查询操作流程
为处理一个select返回的结果,在程序中应增加以下功能
A. 建立一个循环,处理从server返回的结果
B. 描述server返回的不同类型的结果
C. 对于server返回的不同类型的结果分别进行处理
D. 把结果集中的数据捆绑到程序变量中输出
3. 插入操作流程
六.接口函数说明
1.分配环境结构空间cs_ctx_alloc
CS_RETCODE cs_ctx_alloc(CS_INT version, CS_CONTEXT **ctx_ptr);
说明:
Version:CT_LIB版本
CS_VERSION_100 sybase 10.0
CS_VERSION_110 sybase 11.1
CS_VERSION_120 sybase 12.0
CS_VERSION_125 sybase 12.5
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
CS _MEM_ERROR:失败,内存不足
2.释放环境结构空间cs_ctx_drop
CS_RETCODE cs_ctx_drop(CS_CONTEXT *ctx_ptr);
说明:
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
3. 初始化ct_init()
CS_RETCODE cs_init(CS_CONTEXT *ctx_ptr, CS_INT version);
说明:
Version:CT_LIB版本
CS_VERSION_100 sybase 10.0
CS_VERSION_110 sybase 11.1
CS_VERSION_120 sybase 12.0
CS_VERSION_125 sybase 12.5
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
CS _MEM_ERROR:失败,内存不足
4. 分配联接结构ct_con_alloc
CS_RETCODE ct_con_alloc(CS_CONTEXT *ctx_ptr, CS_CONNECTION **con_ptr)
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
5. 设置/获取连接connection属性ct_con_props()
CS_RETCODE ct_con_props(con_ptr, action, property , buffer,buflen, outlen)
CS_CONNECTION *con_ptr :连接指针
CS_INT action :动作
CS_INT property:属性名
CS_VOID *buffer:属性值变量缓冲
CS_INT buflen :属性值缓冲长度
CS_INT *outlen :
说明:
Action:
CS_SET:设置属性
CS_GET:获取属性
CS_CLEAR:设置本属性为默认值
Property:
属性名 buffer值 设置级别 说明
CS_ANSI_BINDS CS_TRUE/CS_FALSE Context /. connection 是否使用ansi格式绑定
CS_APPNAME 实际值串 Context /. connection 登录server的应用名
CS_BULK_LOGIN CS_TRUE/CS_FALSE connection 是否使用批量功能
CS_CON_STATUS CS_INT类型的变量 connection 获取连接状态
CS_HOSTNAME 实际值串 connection 客户端机器的主机名
CS_PASSWORD 实际值串 connection 连接用户的密码
CS_USERNAME 实际值串 connection 连接用户名
CS_SERVERNAME 实际值串 connection 连接的服务器名
CS_NETIO CS_SYNC_IO/CS_ASYNC_IO/
CS_DEFER_IO Context
connection 网络I/O是否是同步还是异步
CS_LOGIN_STATUS CS_TRUE/CS_FALSE connection 获取登录状态
Buflen:如果属性值buffer是个固定长度或一个变量时,则Buflen=CS_NULLTERM或CS_UNUSED
Outlen:如果是设置属性操作,=NULL
如果是获取属性操作,则为本属性的输出值字节数
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
CS_BUSY:在异步操作时表示本连接状态不可知。
6. 释放一个CONNECTION结构ct_con_drop()
CS_RETCODE ct_con_drop(CS_CONNECTION *conn_ptr)
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
CS_BUSY:在异步操作时表示本连接状态不可知。
7. 设置或获取context属性ct_config()
CS_RETCODE ct_config (cntx_ptr, action, property , buffer,buflen, outlen)
CS_CONTEXT * cntx _ptr :连接指针
CS_INT action :动作
CS_INT property:属性名
CS_VOID *buffer:属性值变量缓冲
CS_INT buflen :属性值缓冲长度
CS_INT *outlen :
说明:
Action:
CS_SET:设置属性
CS_GET:获取属性
CS_CLEAR:设置本属性为默认值
CS_SUPPORTED:
Property:同上
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
8. 关闭联接ct_exit()
CS_RETCODE ct_exit(CS_CONTEXT *cntx , CS_INT option)
说明:
Option:操作选项
CS_UNUSED:发送logout命令给server。
如果指定的context中还有尚存结果的联接,则返回CS_FAIL
如果没有尚存结果的联接,则关闭所有联接并释放所有资源。
CS_FORCE_EXIT:强制关闭所有联接,释放所有的资源。
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
9. 分配command结构ct_cmd_alloc()
CS_RETCODE ct_cmd_alloc(CS_CONNEXTION *conn_ptr, CS_COMMAND **cmd_ptr)
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
CS_BUSY:在异步操作时表示本连接状态不可知
10. 设置/获取CS_COMMAND结构属性值ct_cmd_props
CS_RETCODE ct_cmd_props(cmd_ptr, action, property, buffer, buflen, outlen)
CS_COMMAND * cmd _ptr :连接指针
CS_INT action :动作
CS_INT property:属性名
CS_VOID *buffer:属性值变量缓冲
CS_INT buflen :属性值缓冲长度
CS_INT *outlen :
说明:
Action:
CS_SET:设置属性
CS_GET:获取属性
CS_CLEAR:设置本属性为默认值
Property:
属性名 buffer值 设置级别 说明
CS_CUR_ID 一整值 command 读取Cursor的ID
CS_CUR_NAME 串 Command 读取Cursor的名
CS_CUR_ROWCOUNT 一整值 Command 读取cursor的行数
CS_CUR_STATUS 一CS_INT值 Command 读取Cursor的状态
CS_HAVE_BINDS CS_TRUE/CS_FAIL command 结果集是否绑定
CS_HAVE_CMD CS_TRUE/CS_FAIL Command 命令结构是否存在要发送的命令
CS_USERDATA 用户数据 Command
Command
command
11. 初始化SQL串ct_command()
CS_RETCODE ct_command(cmd_ptr, type, buffer, buflen, option)
CS_COMMAND *cmd_ptr
CS_INT type
CS_VOID *buffer
CS_INT buflen
CS_INT option
说明:
Type:初始化的命令类型,,TSQL命令,RPC命令,批数据命令等
Buffer:命令串。对于RPC,则为存储过程的名(不带参数)
Buflen:命令串长或CS_NILLTERM
Option:如果是TSQL命令则为CS_UNUSED
Type类型名 Option值 说明
CS_LANG_CMD
普通的TSQL命令 CS_MORE Buffer中的命令是全部命令的一部分
CS_END Buffer中的命令中全部命令的最后部分
CS_UNUSED 同CS_END
CS_RPC_CMD
执行存储过程命令 CS_RECOMPILE 在执行前重新编译此存储过程
CS_NO_RECOMPILE 在执行前不重新编译此存储过程
CS_UNUSED 同CS_NO_RECOMPILE
CS_SEND_DATA_CMD CS_COLUMN_DATA 用于文本或图像数据
CS_BULK_DATA 批量
CS_SEND_BULK_DATA
CS_BULK_INIT 初始化批量操作命令
CS_BULK_CONT 继续执行批量操作命令
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
CS_BUSY:在异步操作时表示本连接状态不可知。
12. 向一个初始化好的SQL命令传递参数Ct_param()/ct_setparam()
CS_RETCODE ct_param(cmd_ptr, datafmt, data, datalen, indicator)
CS_COMMAND *cmd_ptr
CS_DATAFMT *datafmt ---数据格式
CS_VOID *data --数据
CS_INT datalen ---数据长度
CS_SMALLINT indicator ---指示器
CS_RETCODE ct_setparam(cmd_ptr, datafmt, data, datalenp, indp)
CS_COMMAND *cmd_ptr
CS_DATAFMT *datafmt ---数据格式
CS_VOID *data --数据
CS_INT *datalenp ---数据长度
CS_SMALLINT *indp ---指示器
说明:
1. 在ct_send前调用。
2. 如果datafmt->datatype指示本变量是固定长度类型,则datalen可忽略.CS_VARBINARY和CS_VARCHAR可以认为是固定长度类型
3. Indicator:表示数据是否为空。=-1时表示为空值,此时data及datalen可以忽略
命令类型 Ct_param的作用 Datafmt->status值 Data, datalen is
Cursor定义 修改列 CS_UPDATECOL 修改列的名与长度
Language 传递参数值 CS_INPUTVALUE 值及值长度
RPC 传递参数值 CS_RETURN 返回值
CS_INPUTVALUE 非返回值
4. Datafmt的结构设置
结构成员名 设置值
Name 变量名
Namelen 变量名长度
Datatype 数据类型.
Status CS_INPUTVALUE
其他字段可忽略
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
CS_BUSY:在异步操作时表示本连接状态不可知
Ct_param与ct_setparam的区别
1.Ct_param()是直接将变量中的值传递给SQL,ct_setparam是传递地址,所以在再次ct_send时允许改变参数的值。
14. 发送SQL命令ct_send()
CS_RETCODE ct_send(CS_COMMAND *cmt_ptr)
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
CS_CANCEL:命令被取消
CS_PENDING:异步操作时状态不可知
CS_BUSY:在异步操作时表示本连接状态不可知
CS_RETCODE ct_results(CS_COMMAND *cmd_ptr, CS_INT *result_type)
说明:
Result_type:输出变量,表示结果类型。包括:
结果集的类型 Result_type值 说明 结果集内容
命令执行状态 CS_CMD_DONE 表示一个命令已经正常结束 无
CS_CMD_FAIL 命令执行有错误 无结果集
CS_CMD_SUCCEED 成功执行一个无结果集的命令,如insert命令 无结果集
Fetch状态 CS_COMPUTE_RESULT 统计结果集行数 结果集行数
CS_CURSOR_RESULT Cursor的处理结果 结果集行数
CS_PARAM_RESULT 返回存储过程的出参 出参的数值
CS_STATUS_RESULT 返回存储过程的状态 状态
CS_ROW_RESULT 返回记录行供处理 0或多条记录
Eg: select …. From …
Order by …
Compute sum() by …
返回值
CS_SUCCEED:结果集已准备好,应用可用
CS_END_RESULTS:所有的结果都已处理完毕
CS_FAIL:执行出错,结果集中的结果无效。
CS_CANCELED:结果集被取消
CS_PENDING/CS_BUSY:
处理的方式为:
while ((result_ok=ct_results(cmd_ptr,&result_type)) == CS_SUCCEED)
{
switch ((int)result_type)
{
case CS_ROW_RESULT: /*普通行*/
1. 绑定输出列 ct_bind
2. 取出结果集 ct_fetch
break;
case CS_CMD_DONE: /*所有结果处理完毕*/
break;
case CS_CMD_SUCCEED: /*命令执行无错误*/
break;
case CS_CMD_FAIL: /*命令执行有错误*/
break;
case CS_PARAM_RESULT: /*对于rpc,捆绑及取出输出参数*/
1. 绑定输出列 ct_bind
2. 取出结果集 ct_fetch
break;
case CS_STATUS_RESULT: /*对于rpc,捆绑及取出返回状态*/
1. 绑定返回状态(只有一列)ct_bind
2. 取出返回状态值ct_fetch
break;
case CS_COMPUTE_RESULT: /*取出计算数据*/
break;
case CS_CURSOR_RESULT: : /*游标结果集数据*/
1. 绑定输出列 ct_bind
2. 取出结果集 ct_fetch
break;
default:
break;
}
}
/*命令结束处理*/
switch (result_ok)
{
case CS_END_RESULTS: /*所有结果处理完毕*/
{
ret_code=CS_SUCCEED;
break;
}
case CS_FAIL:
{
ret_code=CS_FAIL;
break;
}
default:
{
ret_code=CS_FAIL;
break;
}
}
各种操作的ct_results返回值与返回类型的各值次序
result=ct_results(cmd_ptr,&result_type)
正确操作 说明
Result_type Result
Select操作 1.CS_ROW_RESULT 1CS_SUCCEED 可取结果集:ct_bind/ct_fetch
2.CS_CMD_DONE 2CS_SUCCEED 命令执行成功
3CS_END_RESULTS 命令结束
Insert操作 1.CS_CMD_SUCCEED 1CS_SUCCEED Update与delete同insert一样
2. CS_CMD_DONE 2CS_SUCCEED
3CS_END_RESULTS
RPC 1.CS_STATUS_RESULT 1. CS_SUCCEED 先得到RPC的返回值:
ct_bind/ct_fetch
2.CS_PARAM_RESULT 2 CS_SUCCEED 再得到RPC出参值
:ct_bind/ct_fetch
3. CS_CMD_SUCCEED 3. CS_SUCCEED
4 CS_CMD_DONE 4. CS_SUCCEED
5CS_END_RESULTS
CURSOR 1 CS_CMD_SUCCEED 1. CS_SUCCEED 定义cursor
2 CS_CMD_DONE 2 CS_SUCCEED
3 CS_CMD_SUCCEED 3. CS_SUCCEED 打开cursor
4 CS_CMD_DONE 4. CS_SUCCEED
5CS_CURSOR_RESULT 5. CS_SUCCEED 处理结果集: :ct_bind/ct_fetch
6 CS_CMD_DONE 6. CS_SUCCEED
7CS_END_RESULTS
错误的操作都是一样:
Result_type Result
1.CS_CMD_FAIL CS_SUCCEED
2.CS_CMD_DONE CS_SUCCEED
CS_END_RESULTS
16. 释放一个COMMAND结构Ct_cmd_drop
CS_RETCODE ct_cmd_drop(CS_COMMAND *cmd_ptr)
返回值
CS_SUCCEED:结果集已准备好,应用可用
CS_FAIL:执行出错,结果集中的结果无效
CS_BUSY:
17. 获取结果集或命令信息ct_res_info()
CS_RETCODE ct_res_info(cmd_ptr, type, buffer, buflen , outlen )
CS_COMMAND *cmd_ptr
CS_INT type
CS_VOID *buffer
CS_INT buflen
CS_INT *outlen
说明:
Type:
Value of type 返回给buffer的值 Ct_results后的result_type参数值 Buffer类型
CS_CMD_NUMBER 产生结果集的命令条数 任意值 CS_INT
CS_NUM_COMPUTERS 当前命令的computer子句个数 CS_COMPUTER_RESULT CS_INT
CS_NUMDATA 结果集的项目个数或列个数 CS_COMPUTER_RESULT
CS_ROW_RESULT
CS_PARAM_RESULT
CS_STATUS_RESULT
CS_ROWFMT_RESULT CS_INT
CS_NUMBERCOLS Order-by的列数 CS_ROW_RESULT CS_INT
CS_ROW_COUNT 本次命令涉及的记录行数 CS_CMD_DONE
CS_CMD_FAIL
CS_CMD_SUCCEED CS_INT
CS_TRANS_STATE 当前的事务状态 任何值 CS_INT
Eg:
/*** Find out how many columns there are in this result set. */
retcode = ct_res_info(cmd, CS_NUMDATA, &num_cols, CS_UNUSED, NULL);
if (retcode != CS_SUCCEED)
{
ex_error("FetchComputeResults: ct_res_info() failed");
return retcode;
}
for (i = 0; i < num_cols; i++)
{
/*
** Get the column description. ct_describe() fills the
** datafmt parameter with a description of the column.
*/
retcode = ct_describe(cmd, (i + 1), &datafmt );
if (retcode != CS_SUCCEED)
{
ex_error("FetchComputeResults: ct_describe() failed");
break;
}
retcode = ct_bind(cmd, (i + 1), &datafmt,
coldata.value, &coldata.valuelen,
(CS_SMALLINT *)&coldata.indicator);
if (retcode != CS_SUCCEED)
{
ex_error("FetchComputeResults: ct_describe() failed");
break;
}
}
18. 获取数据每一列的描述ct_describe()
CS_RETCODE ct_describe(cmd_ptr , item, *datafmt)
CS_COMMAND *cmd_ptr
CS_INT item ------列或返回值的序号,从1开始
CS_DATAFMT *datafmt; ----数据属性格式
说明:
Datafmt会填写以下字段:
字段名 类型 值
name 列名
namelen
Datatype 列类型 CS_XXX_TYPE
Format Not used
Maxlength 最大长度
Scale
Precision 浮点
Status 浮点
Count
usertype
Locale
19. Ct_options
20. 将结果集绑定给输出变量ct_bind()
CS_RETCODE ct_bind(cmd_ptr, item, datafmt, buffer , copied , ind)
CS_COMMAND *cmd_pte
CS_INT item ----绑定的列或参数位置,从1开始,存储过程返回值则按出参顺序从1开始
CS_DATAFMT *datafmt
CS_VOID *buffer ---绑定的输出变量数级组(按列绑定 char aa[col][列的最大长度])
CS_INT *copied ----拷贝的地址或NULL
CS_SMALLINT *ind ----指示器或NULL
说明:
Datafmt成员设置:
Name:不设
Namelen:不设
Datatype:设置成对应的类型CS_XXX_TYPE
Format:除了binary, text, image外设置为CS_FMT_UNUSED
Maxlength:对于固定长度的列可忽略
Scale:用于浮点数
Precision:用于浮点数
Status:不设
Count:每次绑定的记录个数,一般为1
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
CS_BUSY:在异步操作时表示本连接状态不可知
21. 向下取一条记录ct_fetch()
CS_RETCODE ct_fetch(cmd_ptr, type, offset , option , rows_read)
CS_COMMAND *cmd_ptr
CS_INT type ---CS_UNUSED
CS_INT offset ---CS_UNUSED
CS_INT option ---CS_UNUSED
CS_INT *rows_read ---一次fetch的行数
返回值:
CS_SUCCEED:本次fetch执行成功,读出的记录数为roaw_read
CS_END_DATA:全部数据fetch结束,应用程序应调用ct_results取下一个结果集
CS_ROW_FAIL: 一次处理中有部分记录是错误的,常用于数组绑定
CS_FAIL:操作失败
CS_CANCELED: 取消
CS_BUSY/CS_PENDING:在异步操作时表示本连接状态不可知
Eg:
While (((retcode = ct_fetch(cmd,CS_UNUSED, CS_UNUSED, CS_UNUSED,&rowsread)) == CS_SUCCEED)|| (retcode ==CS_ROW_FAIL))
{
If (retcode==CS_ROW_FAIL){printf(“error on row: %d”,rowsread);}
For (i=0; i<num_cols ; i++ )
{
按列取得每一行记录;
}
}
Switch (retcode)
{
Case CS_END_DATA: retcode=CS_SUCCEED; break;
Default : retcode CS_FAIL; break;
}
22. 安装回叫函数Ct_callback()/cs_config()
CS_RETCODE ct_callback(cntx_ptr, conn_ptr, action , type , func)
CS_CONTEXT *cntx_ptr
CS_CONNECTIOn *conn_ptr
CS_INT action == CS_SET / CS_GET
CS_INT type
CS_VOID *func ----回叫函数名
CS_RETCODE cs_config(cntx, action , property, buffer , buflen, outlen )
CS_CONTEXT *cntx;
CS_INT action ; == CS_SET / CS_GET/CS_CLEAR
CS_INT property :设置的属性值
CS_VOID *buffer ----回叫函数名
CS_INT buflen; ---CS_UNUSED
CS_INT *outlen; ---- NULL
说明
Ct_callback用来设置ct_lib的回叫函数
Type名 说明
CS_CLIENTMSG_CB 客户端的消息处理
CS_SERVERMSG_CB server端的消息处理
Cs_config用来设置cs_lib的回叫函数
Property值 说明
CS_MESSAGE_CB CS的消息处理
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
CS_BUSY:在异步操作时表示本连接状态不可知
23. 取消一个命令或清除一个结果集Ct_cancel()
CS_RETCODE ct_cancel(conn_ptr, cmd_ptr, type)
CS_CONNECTION *conn_ptr
CS_COMMAND *cmd_ptr
CS_INT type
说明:
1. 如果type= CS_CANCEL_CURRENT则conn_ptr=NULL
2. 如果type= CS_CANCEL_ALL则conn_ptr和cmd_ptr中有一个必须=NULL
Type 值
CS_CANCEL_CURRENT:仅取消当前的结果集,而不是整批数据。取消命令并没有被送到SQLServer。
CS_CANCEL_ALL::取消批命令中的所有结果。Server一收到取消命令,它就停止相应的处理工作。
24. 关闭一个连接ct_close()
CS_RETCODE ct_close(CS_CONNECTION *conn_ptr, CS_INT option )
Option:
=CS_FORCE_CLOSE:强制关闭
=CS_UNUSED:关闭前发消息给server等当前操作结束后关闭连接
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
CS_BUSY:在异步操作时表示本连接状态不可知
CS_PENDING
25. 初始化一个cursor:ct_cursor()
CS_RETCODE ct_cursor(cmd_ptr, type, name, namelen, text , textlen , option)
CS_COMMAND *cmd_ptr
CS_INT type :初始化操作类型
CS_CHAR name :cursor名
CS_INT namelen :CS_NULLTERM
CS_CHAR *text ----cursor对应的SQL操作语句
CS_INT textlen :CS_NULLTERM
CS_INT option
Type值 说明 Name值 Text值 Option值
CS_CURSOR_DECLARE 定义一个cursor Cursor名 对应的SQL语句 CS_UNUSED:是否修改则服务器决定
CS_READ_ONLY:只读cursor
CS_FOR_UPDATE:可修改cursor
CS_CURSOR_OPEN 打开一个cursor NULL NULL 首次打开时CS_UNUSED
CS_CURSOR_CLOSE 关闭 NULL NULL CS_UNUSED:只关闭cursor
CS_DEALLOC:关闭cursor同时释放资源
CS_CURSOR_OPTION 设置cursor属性 NULL NULL CS_UNUSED
CS_CURSOR_ROWS 设置cursor一次处理的行数 NULL NULL 一次处理的行数
CS_CURSOR_DELETE Cursor执行删除操作 对应的表名 NULL CS_UNUSED
CS_CURDOR_UPDATE Cursor执行修改操作 对应的表名 SQL语句 CS_UNUSED
CS_CURSOR_DEALLOC 释放一个cursor NULL NULL CS_UNUSED续
CS_RETCODE ct_results(CS_COMMAND *cmd_ptr, CS_INT *result_type)
说明:
Result_type:输出变量,表示结果类型。包括:
结果集的类型 Result_type值 说明 结果集内容
命令执行状态 CS_CMD_DONE 表示一个命令已经正常结束 无
CS_CMD_FAIL 命令执行有错误 无结果集
CS_CMD_SUCCEED 成功执行一个无结果集的命令,如insert命令 无结果集
Fetch状态 CS_COMPUTE_RESULT 统计结果集行数 结果集行数
CS_CURSOR_RESULT Cursor的处理结果 结果集行数
CS_PARAM_RESULT 返回存储过程的出参 出参的数值
CS_STATUS_RESULT 返回存储过程的状态 状态
CS_ROW_RESULT 返回记录行供处理 0或多条记录
Eg: select …. From …
Order by …
Compute sum() by …
返回值
CS_SUCCEED:结果集已准备好,应用可用
CS_END_RESULTS:所有的结果都已处理完毕
CS_FAIL:执行出错,结果集中的结果无效。
CS_CANCELED:结果集被取消
CS_PENDING/CS_BUSY:
处理的方式为:
while ((result_ok=ct_results(cmd_ptr,&result_type)) == CS_SUCCEED)
{
switch ((int)result_type)
{
case CS_ROW_RESULT: /*普通行*/
1. 绑定输出列 ct_bind
2. 取出结果集 ct_fetch
break;
case CS_CMD_DONE: /*所有结果处理完毕*/
break;
case CS_CMD_SUCCEED: /*命令执行无错误*/
break;
case CS_CMD_FAIL: /*命令执行有错误*/
break;
case CS_PARAM_RESULT: /*对于rpc,捆绑及取出输出参数*/
1. 绑定输出列 ct_bind
2. 取出结果集 ct_fetch
break;
case CS_STATUS_RESULT: /*对于rpc,捆绑及取出返回状态*/
1. 绑定返回状态(只有一列)ct_bind
2. 取出返回状态值ct_fetch
break;
case CS_COMPUTE_RESULT: /*取出计算数据*/
break;
case CS_CURSOR_RESULT: : /*游标结果集数据*/
1. 绑定输出列 ct_bind
2. 取出结果集 ct_fetch
break;
default:
break;
}
}
/*命令结束处理*/
switch (result_ok)
{
case CS_END_RESULTS: /*所有结果处理完毕*/
{
ret_code=CS_SUCCEED;
break;
}
case CS_FAIL:
{
ret_code=CS_FAIL;
break;
}
default:
{
ret_code=CS_FAIL;
break;
}
}
各种操作的ct_results返回值与返回类型的各值次序
result=ct_results(cmd_ptr,&result_type)
正确操作 说明
Result_type Result
Select操作 1.CS_ROW_RESULT 1CS_SUCCEED 可取结果集:ct_bind/ct_fetch
2.CS_CMD_DONE 2CS_SUCCEED 命令执行成功
3CS_END_RESULTS 命令结束
Insert操作 1.CS_CMD_SUCCEED 1CS_SUCCEED Update与delete同insert一样
2. CS_CMD_DONE 2CS_SUCCEED
3CS_END_RESULTS
RPC 1.CS_STATUS_RESULT 1. CS_SUCCEED 先得到RPC的返回值:
ct_bind/ct_fetch
2.CS_PARAM_RESULT 2 CS_SUCCEED 再得到RPC出参值
:ct_bind/ct_fetch
3. CS_CMD_SUCCEED 3. CS_SUCCEED
4 CS_CMD_DONE 4. CS_SUCCEED
5CS_END_RESULTS
CURSOR 1 CS_CMD_SUCCEED 1. CS_SUCCEED 定义cursor
2 CS_CMD_DONE 2 CS_SUCCEED
3 CS_CMD_SUCCEED 3. CS_SUCCEED 打开cursor
4 CS_CMD_DONE 4. CS_SUCCEED
5CS_CURSOR_RESULT 5. CS_SUCCEED 处理结果集: :ct_bind/ct_fetch
6 CS_CMD_DONE 6. CS_SUCCEED
7CS_END_RESULTS
错误的操作都是一样:
Result_type Result
1.CS_CMD_FAIL CS_SUCCEED
2.CS_CMD_DONE CS_SUCCEED
CS_END_RESULTS
16. 释放一个COMMAND结构Ct_cmd_drop
CS_RETCODE ct_cmd_drop(CS_COMMAND *cmd_ptr)
返回值
CS_SUCCEED:结果集已准备好,应用可用
CS_FAIL:执行出错,结果集中的结果无效
CS_BUSY:
17. 获取结果集或命令信息ct_res_info()
CS_RETCODE ct_res_info(cmd_ptr, type, buffer, buflen , outlen )
CS_COMMAND *cmd_ptr
CS_INT type
CS_VOID *buffer
CS_INT buflen
CS_INT *outlen
说明:
Type:
Value of type 返回给buffer的值 Ct_results后的result_type参数值 Buffer类型
CS_CMD_NUMBER 产生结果集的命令条数 任意值 CS_INT
CS_NUM_COMPUTERS 当前命令的computer子句个数 CS_COMPUTER_RESULT CS_INT
CS_NUMDATA 结果集的项目个数或列个数 CS_COMPUTER_RESULT
CS_ROW_RESULT
CS_PARAM_RESULT
CS_STATUS_RESULT
CS_ROWFMT_RESULT CS_INT
CS_NUMBERCOLS Order-by的列数 CS_ROW_RESULT CS_INT
CS_ROW_COUNT 本次命令涉及的记录行数 CS_CMD_DONE
CS_CMD_FAIL
CS_CMD_SUCCEED CS_INT
CS_TRANS_STATE 当前的事务状态 任何值 CS_INT
Eg:
/*** Find out how many columns there are in this result set. */
retcode = ct_res_info(cmd, CS_NUMDATA, &num_cols, CS_UNUSED, NULL);
if (retcode != CS_SUCCEED)
{
ex_error("FetchComputeResults: ct_res_info() failed");
return retcode;
}
for (i = 0; i < num_cols; i++)
{
/*
** Get the column description. ct_describe() fills the
** datafmt parameter with a description of the column.
*/
retcode = ct_describe(cmd, (i + 1), &datafmt );
if (retcode != CS_SUCCEED)
{
ex_error("FetchComputeResults: ct_describe() failed");
break;
}
retcode = ct_bind(cmd, (i + 1), &datafmt,
coldata.value, &coldata.valuelen,
(CS_SMALLINT *)&coldata.indicator);
if (retcode != CS_SUCCEED)
{
ex_error("FetchComputeResults: ct_describe() failed");
break;
}
}
18. 获取数据每一列的描述ct_describe()
CS_RETCODE ct_describe(cmd_ptr , item, *datafmt)
CS_COMMAND *cmd_ptr
CS_INT item ------列或返回值的序号,从1开始
CS_DATAFMT *datafmt; ----数据属性格式
说明:
Datafmt会填写以下字段:
字段名 类型 值
name 列名
namelen
Datatype 列类型 CS_XXX_TYPE
Format Not used
Maxlength 最大长度
Scale
Precision 浮点
Status 浮点
Count
usertype
Locale
19. Ct_options
20. 将结果集绑定给输出变量ct_bind()
CS_RETCODE ct_bind(cmd_ptr, item, datafmt, buffer , copied , ind)
CS_COMMAND *cmd_pte
CS_INT item ----绑定的列或参数位置,从1开始,存储过程返回值则按出参顺序从1开始
CS_DATAFMT *datafmt
CS_VOID *buffer ---绑定的输出变量数级组(按列绑定 char aa[col][列的最大长度])
CS_INT *copied ----拷贝的地址或NULL
CS_SMALLINT *ind ----指示器或NULL
说明:
Datafmt成员设置:
Name:不设
Namelen:不设
Datatype:设置成对应的类型CS_XXX_TYPE
Format:除了binary, text, image外设置为CS_FMT_UNUSED
Maxlength:对于固定长度的列可忽略
Scale:用于浮点数
Precision:用于浮点数
Status:不设
Count:每次绑定的记录个数,一般为1
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
CS_BUSY:在异步操作时表示本连接状态不可知
21. 向下取一条记录ct_fetch()
CS_RETCODE ct_fetch(cmd_ptr, type, offset , option , rows_read)
CS_COMMAND *cmd_ptr
CS_INT type ---CS_UNUSED
CS_INT offset ---CS_UNUSED
CS_INT option ---CS_UNUSED
CS_INT *rows_read ---一次fetch的行数
返回值:
CS_SUCCEED:本次fetch执行成功,读出的记录数为roaw_read
CS_END_DATA:全部数据fetch结束,应用程序应调用ct_results取下一个结果集
CS_ROW_FAIL: 一次处理中有部分记录是错误的,常用于数组绑定
CS_FAIL:操作失败
CS_CANCELED: 取消
CS_BUSY/CS_PENDING:在异步操作时表示本连接状态不可知
Eg:
While (((retcode = ct_fetch(cmd,CS_UNUSED, CS_UNUSED, CS_UNUSED,&rowsread)) == CS_SUCCEED)|| (retcode ==CS_ROW_FAIL))
{
If (retcode==CS_ROW_FAIL){printf(“error on row: %d”,rowsread);}
For (i=0; i<num_cols ; i++ )
{
按列取得每一行记录;
}
}
Switch (retcode)
{
Case CS_END_DATA: retcode=CS_SUCCEED; break;
Default : retcode CS_FAIL; break;
}
22. 安装回叫函数Ct_callback()/cs_config()
CS_RETCODE ct_callback(cntx_ptr, conn_ptr, action , type , func)
CS_CONTEXT *cntx_ptr
CS_CONNECTIOn *conn_ptr
CS_INT action == CS_SET / CS_GET
CS_INT type
CS_VOID *func ----回叫函数名
CS_RETCODE cs_config(cntx, action , property, buffer , buflen, outlen )
CS_CONTEXT *cntx;
CS_INT action ; == CS_SET / CS_GET/CS_CLEAR
CS_INT property :设置的属性值
CS_VOID *buffer ----回叫函数名
CS_INT buflen; ---CS_UNUSED
CS_INT *outlen; ---- NULL
说明
Ct_callback用来设置ct_lib的回叫函数
Type名 说明
CS_CLIENTMSG_CB 客户端的消息处理
CS_SERVERMSG_CB server端的消息处理
Cs_config用来设置cs_lib的回叫函数
Property值 说明
CS_MESSAGE_CB CS的消息处理
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
CS_BUSY:在异步操作时表示本连接状态不可知
23. 取消一个命令或清除一个结果集Ct_cancel()
CS_RETCODE ct_cancel(conn_ptr, cmd_ptr, type)
CS_CONNECTION *conn_ptr
CS_COMMAND *cmd_ptr
CS_INT type
说明:
1. 如果type= CS_CANCEL_CURRENT则conn_ptr=NULL
2. 如果type= CS_CANCEL_ALL则conn_ptr和cmd_ptr中有一个必须=NULL
Type 值
CS_CANCEL_CURRENT:仅取消当前的结果集,而不是整批数据。取消命令并没有被送到SQLServer。
CS_CANCEL_ALL::取消批命令中的所有结果。Server一收到取消命令,它就停止相应的处理工作。
24. 关闭一个连接ct_close()
CS_RETCODE ct_close(CS_CONNECTION *conn_ptr, CS_INT option )
Option:
=CS_FORCE_CLOSE:强制关闭
=CS_UNUSED:关闭前发消息给server等当前操作结束后关闭连接
返回值:
CS_SUCCEED:执行成功
CS_FAIL:执行失败
CS_BUSY:在异步操作时表示本连接状态不可知
CS_PENDING
25. 初始化一个cursor:ct_cursor()
CS_RETCODE ct_cursor(cmd_ptr, type, name, namelen, text , textlen , option)
CS_COMMAND *cmd_ptr
CS_INT type :初始化操作类型
CS_CHAR name :cursor名
CS_INT namelen :CS_NULLTERM
CS_CHAR *text ----cursor对应的SQL操作语句
CS_INT textlen :CS_NULLTERM
CS_INT option
Type值 说明 Name值 Text值 Option值
CS_CURSOR_DECLARE 定义一个cursor Cursor名 对应的SQL语句 CS_UNUSED:是否修改则服务器决定
CS_READ_ONLY:只读cursor
CS_FOR_UPDATE:可修改cursor
CS_CURSOR_OPEN 打开一个cursor NULL NULL 首次打开时CS_UNUSED
CS_CURSOR_CLOSE 关闭 NULL NULL CS_UNUSED:只关闭cursor
CS_DEALLOC:关闭cursor同时释放资源
CS_CURSOR_OPTION 设置cursor属性 NULL NULL CS_UNUSED
CS_CURSOR_ROWS 设置cursor一次处理的行数 NULL NULL 一次处理的行数
CS_CURSOR_DELETE Cursor执行删除操作 对应的表名 NULL CS_UNUSED
CS_CURDOR_UPDATE Cursor执行修改操作 对应的表名 SQL语句 CS_UNUSED
CS_CURSOR_DEALLOC 释放一个cursor NULL NULL CS_UNUSED续