C++中对ODBC的API详解和使用

本文构成：定义、API、实例，实例在最下面

一、ODBC

1、定义

即开放数据库连接（Open Database Connectivity，ODBC）是数据库API的规范。该API独立于任何一个DBMS或操作系统，是为解决异构数据库间的数据共享而产生的。

2、作用

ODBC为异构数据库访问提供统一接口，允许应用程序以SQL为数据存取标准，存取不同DBMS管理的数据； 使应用程序直接操纵DB中的数据，免除随DB的改变而改变。用ODBC可以访问各类计算机上的DB文件，甚至访问如Excel表和ASCII数据文件这类非数据库对象。

3、API

句柄介绍

3.1 句柄类型

类型	参数
申请环境句柄	SQL_HANDLE_ENV
申请连接句柄	SQL_HANDLE_DBC
申请描述符句柄	SQL_HANDLE_DESC
申请语句句柄	SQL_HANDLE_STMT

3.2 句柄分配

申请类型	提供类型
SQL_HANDLE_ENV	SQL_NULL_HANDLE
SQL_HANDLE_DBC	必须是环境句柄
SQL_HANDLE_STMT	必须是连接句柄
SQL_HANDLE_DESC	必须是连接句柄

SQLAllocHandle

分配句柄

SQLRETURN SQLAllocHandle(  
      SQLSMALLINT   HandleType,  
      SQLHANDLE     InputHandle,  
      SQLHANDLE *   OutputHandlePtr);  

参数	类型	含义
HandleType	输入变量	需要从句柄类型中选择一个参数
InputHandle	输入变量	要在其上下文中分配新句柄的输入句柄，按句柄分配规则
OutputHandlePtr	输出变量	指向缓冲区的指针，在该缓冲区中返回新分配数据结构的句柄。

SQLSetEnvAttr

设置数据库环境各个方面的属性

SQLRETURN SQLSetEnvAttr(  
     SQLHENV      EnvironmentHandle,  
     SQLINTEGER   Attribute,  
     SQLPOINTER   ValuePtr,  
     SQLINTEGER   StringLength);  

参数	类型	含义
EnvironmentHandle	输入参数	环境句柄
Attribute	输入参数	要设置的属性，列在“注释”中。
ValuePtr	输入参数	指向要与Attribute关联的值的指针。根据Attribute的值，ValuePtr将是一个 32 位整数值或指向一个以空字符结尾的字符串。
StringLength	输入参数	如果ValuePtr指向字符串或二进制缓冲区，则此参数应为 * ValuePtr的长度。对于字符串数据，此参数应包含字符串中的字节数。如果ValuePtr是整数，则忽略StringLength。

SQLConnect

建立到驱动程序和数据源的连接。连接句柄引用存储有关连接到数据源的所有信息，包括状态、事务状态和错误信息。

SQLRETURN SQLConnect(  
     SQLHDBC        ConnectionHandle,  
     SQLCHAR *      ServerName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      UserName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      Authentication,  
     SQLSMALLINT    NameLength3);  

参数	类型	含义
ConnectionHandle	输入参数	连接句柄
ServerName	输入参数	数据源名称。数据可能与程序位于同一台计算机上，也可能在另一台计算机上。
NameLength1、2、3	输入参数	ServerName、UserName、身份验证的字符长度
UserName	输入参数	用户标识符
Authentication	输入参数	身份验证字符串（通常是密码）

SQLSetConnectOption

在ODBC3.x中，ODBC2.0函数SQLSetConnectOption已被SQLSetConnectAttr取代，参阅SQLSetConnectAttr。

SQLExecDirect

执行一条准备的语句，如果语句中存在任何参数，则使用参数标记变量的当前值。SQLExecDirect是提交一次性执行的 SQL语句的最快方式。

SQLRETURN SQLExecDirect(  
     SQLHSTMT     StatementHandle,  
     SQLCHAR *    StatementText,  
     SQLINTEGER   TextLength);  

参数	类型	含义
StatementHandle	输入参数	语句句柄
StatementText	输入参数	要执行的 SQL 语句
TextLength	输入参数	StatementText的字符长度

SQLFetch

从结果集中获取下一个数据行集并返回所有绑定列的数据

SQLRETURN SQLFetch(  
     SQLHSTMT     StatementHandle); 

参数	类型	含义
StatementHandle	输入参数	语句句柄

SQLGetData

检索指定列的内容，并将结果返回给该函数的第4个参数（TargetValuePtr）

SQLRETURN SQLGetData(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   Col_or_Param_Num,  
      SQLSMALLINT    TargetType,  
      SQLPOINTER     TargetValuePtr,  
      SQLLEN         BufferLength,  
      SQLLEN *       StrLen_or_IndPtr);  

参数	类型	含义
StatementHandle	输入参数	句柄，使用连接句柄分配的OutputHandlePtr
Col_or_Param_Num	输入参数	对于检索列数据，它是要返回其数据的列数。 结果集列按从 1 开始增加列顺序进行编号。 书签列是列号 0;这只能在启用书签时指定。
TargetType	输入参数	TargetValuePtr 缓冲区的 C数据类型 的类型标识符。
TargetValuePtr	输出参数	指向要返回数据的缓冲区的指针， TargetValuePtr不能为NULL
BufferLength	输入参数	TargetValuePtr 缓冲区的长度（以字节为单位） 在返回可变长度的数据（如字符或二进制数据）时，驱动程序使用 BufferLength 避免写入 * TargetValuePtr 缓冲区的末尾。 请注意，将字符数据返回到 * TargetValuePtr 时，驱动程序会计算 null 终止字符。 因此，TargetValuePtr 必须包含 null 终止字符的空间，否则驱动程序将截断数据。 当驱动程序返回固定长度的数据（如整数或日期结构）时，驱动程序将忽略 BufferLength， 并假定缓冲区足够大以容纳数据。
StrLen_or_IndPt	输出参数	指向要返回长度或指示器值的缓冲区的指针 如果这是空指针，则不返回长度或指示器值。 当正在提取的数据为 NULL 时，这会返回错误。

SQLEndTran

请求对与连接关联的所有语句上的所有活动操作执行提交或回滚操作。 SQLEndTran还可以请求对与环境关联的所有连接执行提交或回滚操作。

SQLRETURN SQLEndTran(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle,  
     SQLSMALLINT   CompletionType);  

参数	类型	含义
HandleType	输入参数	句柄类型标识符。 包含 SQL_HANDLE_ENV（如果Handle是环境句柄）或 SQL_HANDLE_DBC（如果Handle是连接句柄）。
Handle	输入参数	句柄，类型由HandleType指示，表示事务的范围。
CompletionType	输入参数	可选： SQL_COMMIT（提交）、 SQL_ROLLBACK（回滚）

SQLFreeStmt

停止与特定语句关联的处理，关闭与该语句关联的所有打开的游标，丢弃挂起的结果，或者（可选）释放与语句句柄关联的所有资源。

SQLRETURN SQLFreeStmt(  
     SQLHSTMT       StatementHandle,  
     SQLUSMALLINT   Option);  

参数	类型	含义
StatementHandle	输入参数	语句句柄（连接句柄）
Option	输入参数	SQL_CLOSE、SQL_DROP、SQL_UNBIND、SQL_RESET_PARAMS（具体含义见下表）

Option参数选择详情解析

参数	含义
SQL_CLOSE	关闭与StatementHandle关联的游标（如果已定义）并丢弃所有未决结果。应用程序可以稍后通过使用相同或不同的参数值再次执行SELECT语句来重新打开此游标。如果未打开游标，则此选项对应用程序无效。也可以调用 SQLCloseCursor来关闭游标。
SQL_DROP	不推荐使用此选项。对带有SQL_DROP选项的SQLFreeStmt的调用在驱动程序管理器中映射到SQLFreeHandle。
SQL_UNBIND	将 ARD 的 SQL_DESC_COUNT 字段设置为 0，为给定的StatementHandle释放由SQLBindCol绑定的所有列缓冲区。这不会解除书签列的绑定。
SQL_RESET_PARAMS	将 APD 的 SQL_DESC_COUNT 字段设置为 0，释放SQLBindParameter为给定StatementHandle设置的所有参数缓冲区。如果在一个被多个语句共享的显式分配的描述符上执行此操作，则此操作将影响共享该描述符的所有语句的绑定。

SQLDisconnect

关闭与特定连接句柄关联的连接。

SQLRETURN SQLDisconnect(  
     SQLHDBC     ConnectionHandle);  

参数	类型	含义
ConnectionHandle	输入参数	分配的连接句柄

SQLFreeHandle

释放与特定环境、连接、语句或描述符句柄相关联的资源 此函数是用于释放句柄的通用函数，取代了 ODBC 2.0 函数SQLFreeConnect（用于释放连接句柄）和SQLFreeEnv（用于释放环境句柄）。 SQLFreeConnect和SQLFreeEnv在 ODBC 3*.x* 中均已弃用。 SQLFreeHandle还替换了 ODBC 2.0 函数SQLFreeStmt（带有 SQL_DROP Option）以释放语句句柄。

SQLRETURN SQLFreeHandle(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle);

参数	类型	含义
HandleType	输入参数	释放的句柄类型，和分配的句柄类型要求一致
Handle	输入参数	要释放的句柄

4、实例

· 准备工作，将数据库环境和连接设置完毕

	//环境句柄
	HANDLE henv=NULL;
	//连接句柄
	HANDLE hdbc=NULL;
	//创建环境句柄
	SQLAllocHandle(SQL_HANDLE_ENV,SQL_NULL_HANDLE,henv);
	//设置环境参数
	SQLSetEnvAttr(henv,SQL_ATTR_ODBC_VERSION,(SQLPOINTER)SQL_OV_ODBC3,SQL_IS_INTEGER);
	//创建连接句柄
	SQLAllocHandle(SQL_HANDLE_DBC,henv,&hdbc);
	//连接一个数据源（数据库名称(test数据库)，访问数据库的用户名root、密码123456）
	//SQL_NTS代表字符串长度
	SQLConnect(hdbc,"test",SQL_NTS,
		"root",SQL_NTS,"123456",SQL_NTS);
	//设置连接数据源的可选项，是否自动提交
	SQLSetConnectOption(hdbc, SQL_AUTOCOMMIT, SQL_AUTOCOMMIT_OFF);

· 开始数据库的增删改查操作

	//定义接受的结构体
	struct USER_INFO
	{	
		unsigned char Name;
		unsigned int ID;
	};
	//定义句柄
 	HANDLE hstmt;
 	//定义执行语句的返回值
 	int retcode;
 	//分配连接句柄
	SQLAllocHandle(SQL_HANDLE_STMT,hdbc,&hstmt);
	//拷贝sql语句到Statement
	strcpy((char *)Statement,"SELECT * FROM users");
	//执行数据库SQL语句
	SQLExecDirect(hstmt,Statement,SQL_NTS);
	while(TRUE)
	{
		//绑定数据访问的每一行
		retcode = SQLFetch(hstmt);
		//如果数据找不到，退出
		if(retcode==SQL_NO_DATA_FOUND)
		{
			break;
		}
		//查找数据成功
		if(retcode==SQL_SUCCESS||retcode==SQL_SUCCESS_WITH_INFO)
		{
			//定于接受数据的指针变量pUserInfo
			USER_INFO *pUserInfo = new USER_INFO;
			//初始化pUserInfo
			memset(pUserInfo, 0, sizeof(USER_INFO));
			//获取第一列的数据返回给pUserInfo->Name
			SQLGetData(hstmt,1,SQL_C_CHAR,pUserInfo->Name,SQL_NTS,&value);
			SQLGetData(hstmt,2,SQL_C_SLONG,&pUserInfo->GroupID,SQL_NTS,&value);
		}
	}
	//请求对与连接关联的所有语句上的所有活动操作执行提交
	SQLEndTran(SQL_HANDLE_DBC,hdbc,SQL_COMMIT);
	//停止与特定语句关联的处理，关闭与hstmt语句关联的所有打开的游标
	SQLFreeStmt(hstmt,SQL_CLOSE);
	if(hstmt!=NULL)
	{
		//释放与特定环境、连接、语句或描述符句柄相关联的资源
		SQLFreeHandle(SQL_HANDLE_STMT,hstmt);
	}
	return;

· 结束数据库操作，断开连接，释放内存

	//结束数据库操作
	if(hdbc!=NULL)
	{
		//断开连接
		SQLDisconnect(mibhandle.hdbc);
		//释放连接句柄
		SQLFreeHandle(SQL_HANDLE_DBC,hdbc);
	}
	if(henv!=NULL)
	{
		//释放环境句柄
		SQLFreeHandle(SQL_HANDLE_ENV,henv);
	}
	//重新初始化
	hdbc=NULL;
	henv=NULL;
	return;

Tip：其他的增加、删除、更新操作一致，只是SQL语句不同，不再重复

参考文献：Microsoft 开放式数据库连接 (ODBC)