ODBC接口

1.系统概述

开放式数据库连接(ODBC)是一种广泛接受的应用程序编程接口(API)，适用于数据库访问。它基于数据库API Call-Level接口(CLI)和ISO/IEC中的规范，并使用结构化查询语言(SQL)作为数据库访问语言。

ODBC旨在实现最大的互操作性，即单个应用程序能够访问不同数据库管理系统(DBMSs)使用相同的源代码。数据库应用程序调用ODBC接口中的函数，这些函数在名为drivers的数据库特定模块中实现。驱动程序的使用将应用程序与特定于数据库的调用隔离开，其方式与打印机驱动程序将字处理程序与特定于打印机的命令隔离的方式相同。由于驱动程序是运行时加载的，因此用户只需添加新的驱动程序才能访问新的DBMS；不需要重新编译或重新链接应用程序。

2.创建数据源

2.1.Linux平台创建ODBC数据源

UXDB数据库ODBC驱动程序在Linux操作系统上的使用依赖于UnixODBC库，如果UnixODBC未安装在系统目录下，则为了能使uxdb odbc驱动程序找到需要的库文件，用户需要设置系统环境变量 LD_LIBRARY_PATH指向动态库。另外，如果安装的UnixODBC生成的动态库名称不是libodbcinst.so（如 libodbcinst.so.1.0.0 或者 libodbcinst.so.2.0.0 等），则需要对实际库文件建立符号链接。

2.1.1.安装UnixODBC

安装UnixODBC驱动程序管理器有如下几种方法。

• 二进制安装

  yum install unixODBC
  yum install unixODBC-devel
  

• rpm包安装

  在官网下载对应linux版本的odbc驱动包，并安装。

  如：下载linux7下的ODBC驱动包unixODBC-2.3.1-11.el7.x86_64.rpm，以root用户安装。

  rpm -ivh unixODBC-2.3.1-11.el7.x86_64.rpm
  

• 源码编译安装

  获取unixODBC-2.3.1.tar.gz，将其放到/usr/local目录下，执行如下命令。

  tar zxvf unixODBC-2.3.1.tar.gz
  cd unixODBC-2.3.1 
  ./configure --prefix=/usr/local/unixODBC-2.3.1 --includedir=/usr/include 
  --libdir=/usr/lib -bindir=/usr/bin --sysconfdir=/etc
  make
  make install
  

安装成功后，unixODBC所需的头文件都被安装到/usr/inlucde下，编译好的库文件安装到/usr/lib下，与unixODBC相关的可执行文件安装到/usr/bin下，配置文件安装到/etc下。

安装之后可运行如下命令查看是否安装成功。

[uxdb@local101:~]$ isql --v
unixODBC 2.3.1

2.1.2.安装uxdb数据库

下载需要的UXDB数据库软件包进行安装，安装成功之后，初始化并启动数据库实例。

2.1.3.安装uxdb odbc驱动程序

下载与数据库版本对应的uxdb数据库odbc驱动程序包（uxdb-odbc_linux_X86.tar.gz），进行解压，将解压之后的文件夹移动到数据库安装路径下，uxdb数据库安装路径为/home/uxdb/uxdbinstall。

2.1.4.连接测试

查看odbc配置文件，执行如下命令。

[uxdb@local101:~]$ odbcinst -j
unixODBC 2.3.1
DRIVERS............: /etc/odbcinst.ini
SYSTEM DATA SOURCES: /etc/odbc.ini
FILE DATA SOURCES..: /etc/ODBCDataSources
USER DATA SOURCES..: /home/uxdb/.odbc.ini
SQLULEN Size.......: 8
SQLLEN Size........: 8
SQLSETPOSIROW Size.: 8
[uxdb@local101:~]$ 

1. 根据实际情况修改配置文件。

   修改odbcinst.ini（配置驱动），如下所示。

   #uxdb odbc驱动库的位置
   
   [UXSQL]
   Driver=/home/uxdb/uxdbinstall/odbc/lib/uxsqlodbcw.so
   Setup=/home/uxdb/uxdbinstall/odbc/lib/uxsqlodbcw.so
   

   odbc.ini用于配置ODBC的数据源(DSN)，在UXDB数据源配置项中可配置的连接参数如下表所示。

   数据源配置项中可配置的连接参数

   参数名称	说明
   DRIVER	UXDB ODBC驱动名称：UXSQL
   SERVERNAME	目标服务器：ip 地址
   PORT	端口号
   DATABASE	数据库名
   USERNAME	用户名
   PASSWORD	密码

   配置odbc.ini文件，如下所示。

   sudo vim /etc/odbc.ini
   
   [uxdb]
   driver = UXSQL
   Servername = 192.72.1.54
   port = 5432
   database = uxdb
   username = uxdb
   password = 123456
   

2. 测试是否可以连接。

   isql –v uxdb（数据源名称）
   

   [uxdb@uxpool01 bin]$ ./isql -v uxdb
   +---------------------------------------+
   | Connected!                            |
   |                                       |
   | sql-statement                         |
   | help [tablename]                      |
   | quit                                  |
   |                                       |
   +---------------------------------------+
   

2.2.Windows平台创建ODBC数据源

1. 选择“开始”=>“设置”=>“控制面板”菜单，在弹出窗口中双击【管理工具】（win11版本下，双击控制面板中的【Windows 工具】）图标进入管理工具界面，双击【数据源(ODBC)】图标，打开ODBC数据源管理器。

2. 选择【系统DSN】选项卡，单击【添加(D)…】按钮，系统弹出【创建新数据源】对话框。

3. 在ODBC驱动器程序列表中，选择【UXsinoDB ANSI】或【UXsinoDB Unicode】，单击【完成】按钮，系统弹出【UXsinoDB ANSI/Unicode Driver (uxsqlODBC) Setup】对话框。

   ANSI配置对话框：

   Unicode配置对话框：

4. 配置示例。

   Database：要连接的数据库名，如 uxdb。

   Server：要连接服务端IP地址，如 192.168.1.82，连接本机安装的数据库可填回环地址 127.0.0.1。

   Port：要连接的集群port，数据库默认端口号为 52025。

   User Name：要连接的数据库用户，如 uxdb。

   Password：要连接的数据库的密码，如 123456。

   其他使用默认值。

5. 单击【Test】按钮可验证数据库连接状态，成功如下所示，确定后单击【Save】保存。

3.接口说明

本章节主要提供了ODBC接口，并详细描述接口参数信息等。

3.1.SQLAllocHandle

3.1.1.功能描述

SQLAllocHandle分配环境、连接、语句或描述符句柄。

3.1.2.语法

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

3.1.3.参数

• HandleType

  [输入]SQLAllocHandle要分配的句柄类型。必须是以下值之一。

  • SQL_HANDLE_DBC

  • SQL_HANDLE_DESC

  • SQL_HANDLE_ENV

  • SQL_HANDLE_STMT

• InputHandle

  [输入]要在这里分配新句柄，如果HandleType为SQL_HANDLE_ENV，则这个值是SQL_NULL_HANDLE，如果HandleType为SQL_HANDLE_DBC，则这一定是一个环境句柄，如果HandleType为SQL_HANDLE_STMT或者SQL_HANDLE_DESC，则是一个连接句柄。

• OutputHandlePtr

  [输出]指向缓冲区的指针，该缓冲区将句柄返回到新分配的数据结构。

3.1.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_INVALID_HANDLE或SQL_ERROR。

分配环境句柄外的其他句柄时，如果SQLAllocHandle返回SQL_ERROR，它会将OutputHandlePtr设置为SQL_NULL_HDBC、SQL_NULL_HSTMT或SQL_NULL_HDESC，具体取决于HandleType的值，除非输出参数为null指针。然后，应用程序可以从与InputHandle参数中的句柄关联的诊断数据结构获取其他信息。

3.1.5.环境处理分配错误

环境分配在驱动程序管理器内和每个驱动程序中发生。SQLAllocHandle返回的错误的HandleType为SQL_HANDLE_ENV取决于发生错误的级别。

如果在调用HandleType为SQL_HANDLE_ENV的SQLAllocHandle时驱动程序管理器无法为*OutputHandlePtr分配内存，或者应用程序为OutputHandlePtr提供null指针，则SQLAllocHandle将返回SQL_ERROR。驱动程序管理器将OutputHandlePtr SQL_NULL_HENV(除非应用程序提供了null指针，该指针返回SQL_ERROR)。没有用于关联其他诊断信息的句柄。

在应用程序调用SQLConnect、SQLBrowseConnect或SQLDriverConnect之前，驱动程序管理器不会调用驱动程序级环境句柄分配函数。如果驱动程序级SQLAllocHandle函数中发生错误，驱动程序管理器级SQLConnect、SQLBrowseConnect或SQLDriverConnect函数将返回SQL_ERROR。诊断数据结构包含SQLSTATE IM004(驱动程序的SQLAllocHandle失败)。错误在连接句柄上返回。

3.1.6.诊断

当SQLAllocHandle返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过调用SQLGetDiagRec，将相应的HandleType和Handle设置为InputHandle的值来获取关联的SQLSTATE值。SQL_SUCCESS_WITH_INFO(OutputHandle SQL_ERROR)返回非参数。下表列出了SQLAllocHandle通常返回的SQLSTATE值，并说明了此函数上下文中的每个值；标注为"(DM)"位于驱动程序管理器返回的SQLSTATEs说明之前。除非另有说明，否则将与每个SQLSTATE值关联的返回代码是SQL_ERROR。

SQLAllocHandle 诊断代码

3.2.SQLBindCol

3.2.1.功能描述

SQLBindCol将应用程序数据缓冲区绑定到结果集的列中。

3.2.2.语法

SQLRETURN SQLBindCol(  
    SQLHSTMT       StatementHandle,  
    SQLUSMALLINT   ColumnNumber,  
    SQLSMALLINT    TargetType,  
    SQLPOINTER     TargetValuePtr,  
	SQLINTEGER     BufferLength  
    SQLINTEGER *   Strlen_or_IndPtr);  

3.2.3.参数

• StatementHandle

  [输入]语句句柄。

• ColumnNumber

  [输入]要绑定结果集的列号。起始列号为0，以递增的顺序计算列号，第0列是书签列。若未设置书签页，则起始列号为1。

• TargetType

  [输出]缓冲区中C数据类型的标识符。

• TargetValuePtr

  [延迟输入/输出]指向要绑定到列的数据缓冲区的指针。SQLFetch和SQLFetchScroll返回此缓冲区的数据。当SQL_FETCH_BY_BOOKMARK操作时，SQLBulkOperations将返回此缓冲区中的数据；当操作SQL_ADD或SQL_UPDATE_BY_BOOKMARK时，它将从此缓冲区检索数据。当SQL_REFRESH操作时，SQLSetPos将返回此缓冲区中的数据；当SQL_UPDATE操作时，它将从该缓冲区检索数据。

  如果TargetValuePtr为空指针，驱动程序将取消列的数据缓冲区绑定。应用程序可以通过使用SQL_UNBIND选项调用SQLFreeStmt来取消所有列的绑定。如果调用SQLBindCol中的TargetValuePtr参数为null指针，但StrLen_or_IndPtr参数是有效的值，则应用程序可以取消列的数据缓冲区绑定，但仍为列绑定长度/指示器缓冲区。

• BufferLength

  [输入]*TargetValuePtr缓冲区的长度。

  驱动程序在返回可变长度的数据（如字符或二进制数据）时，使用BufferLength避免写入 *TargetValuePtr缓冲区的末尾。请注意，驱动程序在将字符数据返回到 *TargetValuePtr时对null终止字符进字段数。因此，TargetValuePtr必须包含null终止字符的空间，否则驱动程序将截断数据。

  当驱动程序返回固定长度的数据（如整数或日期结构）时，驱动程序将忽略BufferLength，并假定缓冲区足够大以容纳数据。因此，应用程序必须分配一个足够大的缓冲区用于固定长度的数据，否则驱动程序将写入缓冲区的末尾。

  当BufferLength小于0但当BufferLength为0时，SQLBindCol将返回SQLSTATE HY090(字符串或缓冲区长度无效)。但是，如果TargetType指定了字符类型，则应用程序不应将BufferLength设置为0，因为在这种情况下符合ISO CLI 的驱动程序将返回SQLSTATE HY090(无效的字符串或缓冲区长度)。

• StrLen_or_IndPtr

  [延迟输入/输出]指向要绑定到列的长度/指示器缓冲区的指针。SQLFetch和SQLFetchScroll返回此缓冲区中的值。当操作SQL_ADD、SQL_UPDATE_BY_BOOKMARK或SQL_DELETE_BY_BOOKMARK时，SQLBulkOperations从该缓冲区检索值。当SQL_FETCH_BY_BOOKMARK操作时，SQLBulkOperations将在此缓冲区中返回一个值。当SQL_REFRESH操作时，SQLSetPos将在此缓冲区中返回值；当SQL_UPDATE操作时，它将从此缓冲区检索值。

  SQLFetch、SQLFetchScroll、SQLBulkOperations和SQLSetPos可以在长度/指示器缓冲区中返回以下值：

  • 可返回的数据的长度

  • SQL_NO_TOTAL

  • SQL_NULL_DATA

  应用程序可以将以下值放在长度/指示器缓冲区中，以用于SQLBulkOperations或SQLSetPos：

  • SQL_NTS

  • SQL_NULL_DATA

  • SQL_DATA_AT_EXEC

  • SQL_LEN_DATA_AT_EXEC宏的结果

  • SQL_COLUMN_IGNORE

  如果指示器缓冲区和长度缓冲区是单独的缓冲区，则指示器缓冲区只能返回SQL_NULL_DATA，而长度缓冲区可以返回所有其他值。

  如果StrLen_or_IndPtr为空指针，则不使用长度或指示器值。提取数据且数据为NULL时，这是一个错误。

3.2.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

3.2.5.诊断

当SQLBindCol返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过调用具有SQL_HANDLE_STMT的HandleType和StatementHandle句柄的SQLGetDiagRec来获取关联的SQLSTATE值。下表列出了SQLBindCol通常返回的SQLSTATE值，并说明了此函数上下文中的每个值；标注为"(DM)"位于驱动程序管理器返回的SQLSTATEs说明之前。除非另有说明，否则将与每个SQLSTATE值关联的返回代码是SQL_ERROR。

SQLBindCol 诊断代码

3.3.SQLBindParameter

3.3.1.功能描述

SQLBindParameter将缓冲区绑定到SQL语句中的参数标记。SQLBindParameter支持绑定到unicode C数据类型，即使基础驱动程序不支持unicode数据。

3.3.2.语法

SQLRETURN SQLBindParameter(  
    SQLHSTMT        StatementHandle,  
    SQLUSMALLINT    ParameterNumber,  
    SQLSMALLINT     InputOutputType,  
    SQLSMALLINT     ValueType,  
    SQLSMALLINT     ParameterType,  
    SQLULEN         ColumnSize,  
    SQLSMALLINT     DecimalDigits,  
    SQLPOINTER      ParameterValuePtr,  
    SQLLEN          BufferLength,  
    SQLLEN *        StrLen_or_IndPtr);  

3.3.3.参数

• StatementHandle

  [输入]语句句柄。

• ParameterNumber

  [输入]参数编号，按递增参数顺序排序，从1开始。

• InputOutputType

  [输入]参数的类型。

• ValueType

  [输入]参数的C数据类型。

• ParameterType

  [输入]参数的SQL数据类型。

• ColumnSize

  [输入]列的大小或相应参数标记的表达式。

• DecimalDigits

  [输入]列的十进制数字或相应参数标记的表达式。

• ParameterValuePtr

  [延迟输入]指向参数数据缓冲区的指针。

• BufferLength

  [输入/输出]ParameterValuePtr缓冲区的长度。

• StrLen_or_IndPtr

  [输入]缓冲区的长度或指示器指针。若为空值，则未使用任何长度或指示器值。

3.3.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

3.3.5.诊断

当SQLBindParameter返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，通过调用SQLGetDiagRec函数，并将HandleType和Handle参数设置为SQL_HANDLE_STMT和StatementHandle，可得到一个相关的SQLSTATE值，通过SQLSTATE值可以查出调用此函数的具体信息。

SQLBindParameter 诊断代码

3.4.SQLBrowseConnect

3.4.1.功能描述

SQLBrowseConnect支持一种迭代方法，该方法发现和枚举连接到数据源所需的属性和属性值。对SQLBrowseConnect的每次调用都将返回属性和属性值的连续级别。枚举所有级别后，将完成到数据源的连接，并由SQLBrowseConnect返回完整的连接字符串。SQL_SUCCESS或SQL_SUCCESS_WITH_INFO的返回代码指示已指定所有连接信息，并且应用程序现在已连接到数据源。

3.4.2.语法

SQLRETURN SQLBrowseConnect(  
    SQLHDBC         ConnectionHandle,  
    SQLCHAR *       InConnectionString,  
    SQLSMALLINT     StringLength1,  
    SQLCHAR *       OutConnectionString,  
    SQLSMALLINT     BufferLength,  
    SQLSMALLINT *   StringLength2Ptr); 

3.4.3.参数

• ConnectionHandle

  [输入]连接句柄。

• InConnectionString

  [输入]浏览请求连接字符串。

• StringLength1

  [输出]*InConnectionString的长度。

• OutConnectionString

  [输出]一个缓冲区的指针，此缓冲区用于存放浏览结果连接字符串。

• BufferLength

  [输出]*InConnectionString的长度。

• StringLength2Ptr

  [输出]*OutConnectionString中返回的字节总数（不包括空值终止字节）。如果要返回的字节数大于等于BufferLength，那么 *OutConnectionString 中的连接字符串会被截断为BufferLength减去空值终止字符的长度。

3.4.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NEED_DATA、SQL_ERROR、SQL_INVALID_HANDLE或SQL_STILL_EXECUTING。

3.4.5.诊断

当SQLBrowseConnect返回SQL_ERROR、SQL_SUCCESS_WITH_INFO或SQL_NEED_DATA时，可以通过使用HandleType的SQL_HANDLE_STMT和句柄ConnectionHandle调用SQLGetDiagRec来获取关联的SQLSTATE值。下面的表格列出了由SQLBrowseConnect返回的SQLSTATE值，并对该函数的上下文中的每个值进行了说明；标注为“(DM)”位于驱动程序管理器返回的SQLSTATEs的说明之前。除非另有说明，否则与每个SQLSTATE值相关联的返回代码将SQL_ERROR。

SQLBrowseConnect 诊断代码

3.5.SQLBulkOperations

3.5.1.功能描述

SQLBulkOperations执行批量插入和批量书签操作，包括按书签更新、删除和提取。

3.5.2.语法

SQLRETURN SQLBulkOperations(  
    SQLHSTMT       StatementHandle,  
    SQLUSMALLINT   Operation); 

3.5.3.参数

• StatementHandle

  [输入]语句句柄。

• Operation

  [输入]要执行的操作：SQL_ADD、SQL_UPDATE_BY_BOOKMARK、SQL_DELETE_BY_BOOKMARK、​SQL_FETCH_BY_BOOKMARK。

3.5.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NEED_DATA、SQL_STILL_EXECUTING、​SQL_ERROR或SQL_INVALID_HANDLE。

3.5.5.诊断

当SQLBulkOperations返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过调用具有SQL_HANDLE_STMT的HandleType和StatementHandle句柄的SQLGetDiagRec来获取关联的SQLSTATE值。下面的表格列出了由SQLBulkOperations返回的SQLSTATE值，并解释了与这个函数相关的每个信息；标注为“(DM)”位于驱动程序管理器返回的SQLSTATEs说明之前。除非另有说明，否则将指定与每个SQLSTATE值SQL_ERROR返回代码。

对于所有那些可返回SQL_SUCCESS_WITH_INFO或SQL_ERROR（除了01xxx SQLSTATEs）的所有SQLSTATES，如果多行运算的一行或多行（但不是全部）发生错误，则返回SQL_SUCCESS_WITH_INFO；如果单行操作出错，则返回SQL_ERROR。

SQLBulkOperations 诊断代码

3.6.SQLCancel

3.6.1.功能描述

SQLCancel取消对语句的处理。

3.6.2.语法

SQLRETURN SQLCancel(  
    SQLHSTMT     StatementHandle); 

3.6.3.参数

• StatementHandle

  [输入]语句句柄。

3.6.4.返回值

SQL_SUCCESS SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

3.6.5.诊断

当 SQLCancel 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，通过调用SQLGetDiagRec 函数，且其 HandleType 和 Handle 参数分别设置为 SQL_HANDLE_STMT 和StatementHandle，可得到一个相关的SQLSTATE 值 。下面的表格列出了由 SQLCancel 返回的 SQLSTATE 值，并解释了与这个函数相关的每个信息；标注为“ (DM) ”的是对由 DriverM anager 返回的 SQLSTATE的描述。如果没有其他注释，那么与每个SQLSTATE 值相关的返回代码是 SQL_ERROR。

SQLCancel 诊断代码

3.7.SQLCancelHandle

3.7.1.功能描述

SQLCancelHandle取消对连接或语句的处理。当 HandleType 为 SQL_HANDLE_STMT时，驱动程序管理器会将对 SQLCancelHandle 的调用映射到对 SQLCancel的调用。

3.7.2.语法

SQLRETURN SQLCancelHandle(  
    SQLSMALLINT  HandleType,  
    SQLHANDLE    Handle); 

3.7.3.参数

• HandleType

  [输入]要对其取消处理。有效值为 SQL_HANDLE_DBC 或SQL_HANDLE_STMT。

• Handle

  [输入]要取消处理的句柄。

  如果句柄不是 HandleType 指定的类型的有效句柄，则 SQLCancelHandle 将返回SQL_INVALID_HANDLE。

3.7.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。

3.7.5.诊断

当 SQLCancelHandle 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO时，通过调用SQLGetDiagRec 函数，且其 HandleType 和 Handle 参数分别设置为 SQL_HANDLE_STMT和SQL_HANDLE_DBC，可得到一个相关的SQLSTATE 值。

下表列出了通常由 SQLCancelHandle 返回的 SQLSTATE 值，并对该函数的上下文中的每个值进行了说明：标注为 “(DM)”位于驱动程序管理器返回的 SQLSTATEs 的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是SQL_ERROR。

SQLCancelHandle 诊断代码

如果在将 HandleType 设置为 SQL_HANDLE_STMT 的情况下调用 SQLCancelHandle，则它可以返回函数SQLCancel 返回的任何 SQLSTATE。

3.8.SQLCloseCursor

3.8.1.功能描述

SQLCloseCursor关闭已在语句上打开的游标，并丢弃挂起的结果。

3.8.2.语法

SQLRETURN SQLCloseCursor(  
    SQLHSTMT     StatementHandle);  

3.8.3.参数

• StatementHandle

  [输入]语句句柄。

3.8.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

3.8.5.诊断

当 SQLCloseCursor 返回 SQL_ERROR 或SQL_SUCCESS_WITH_INFO时，通过调用具有SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句柄的 SQLGetDiagRec，可以获得关联的 SQLSTATE 值。下表列出了 SQLCloseCursor 通常返回的 SQLSTATE值，并说明了此函数上下文中的每个值；表示法“(DM) ”位于驱动程序管理器返回的 SQLSTATEs说明之前。除非另有说明，否则将指定与每个 SQLSTATE 值SQL_ERROR返回代码。

SQLCloseCursor 诊断代码

3.9.SQLColAttribute

3.9.1.功能描述

SQLColAttribute返回结果集中列的描述符信息。说明描述符信息，以字符串、描述符相关值或整数值的形式返回。

3.9.2.语法

SQLRETURN SQLColAttribute (  
		  SQLHSTMT        StatementHandle,  
		  SQLUSMALLINT    ColumnNumber,  
		  SQLUSMALLINT    FieldIdentifier,  
		  SQLPOINTER      CharacterAttributePtr,  
		  SQLSMALLINT     BufferLength,  
		  SQLSMALLINT *   StringLengthPtr,  
		  SQLLEN *        NumericAttributePtr); 

3.9.3.参数

• StatementHandle

  [输入]语句句柄。

• ColumnNumber

  [输入]要检索字段的列号，起始为1，依次递增。

• FieldIdentifier

  [输入]IRD中ColumnNumber行的字段。

• CharacterAttributePtr

  [输出]一个缓冲区指针，返回FieldIdentifier字段值。

• BufferLength

  [输入]如果FieldIdentifier是一个ODBC定义的字段，而且CharacterAttributePtr指向一个字符串或二进制缓冲区，则此参数为该缓冲区的长度。如果FieldIdentifier是一个ODBC定义的字段，而且CharacterAttributePtr指向一个整数，则会忽略该字段。

• StringLengthPtr

  [输出]缓冲区指针，存放*CharacterAttributePtr中字符类型数据的字节总数，对于非字符类型，忽略BufferLength的值。

• NumericAttributePtr

  [输出]指向一个整型缓冲区的指针，返回IRD中ColumnNumber行FieldIdentifier字段的值。

3.9.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.9.5.诊断

当SQLColAttribute返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，通过调用SQLGetDiagRec函数，并将HandleType和Handle参数设置为SQL_HANDLE_STMT和StatementHandle，可得到一个相关的SQLSTATE值，通过SQLSTATE值可以查出调用此函数的具体信息。

SQLColAttribute 诊断代码

当在 SQLPrepare 之后和 SQLExecute 之前调用时，SQLColAttribute 可以返回可由 SQLPrepare 或SQLExecute 返回的任何 SQLSTATE，具体取决于数据源评估与 StatementHandle 关联的 SQL 语句的时间。

出于性能方面的考虑，应用程序在执行语句之前不应调用 SQLColAttribute 。

3.10.SQLColumnPrivileges

3.10.1.功能描述

SQLColumnPrivileges返回指定表的列和相关权限的列表。驱动程序在指定的 StatementHandle上以结果集的形式返回该信息。

3.10.2.语法

SQLRETURN SQLColumnPrivileges(  
     SQLHSTMT      StatementHandle,  
     SQLCHAR *     CatalogName,  
     SQLSMALLINT   NameLength1,  
     SQLCHAR *     SchemaName,  
     SQLSMALLINT   NameLength2,  
     SQLCHAR *     TableName,  
     SQLSMALLINT   NameLength3,  
     SQLCHAR *     ColumnName,  
     SQLSMALLINT   NameLength4); 

3.10.3.参数

• StatementHandle

  [输入]语句句柄。

• CatalogName

  [输入]目录名称。如果驱动程序支持某些目录的名称，但不支持其他目录的名称（例如，当驱动程序从不同DBMS检索数据时），则空字符串("")表示没有名称的目录。CatalogName不能包含字符串搜索模式。

  如果SQL_ATTR_METADATA_ID语句特性设置为SQL_TRUE，则CatalogName被视为标识符，并且其大小写无意义。如果SQL_FALSE，则CatalogName是普通参数；它按原义处理，其大小写有意义。

• NameLength1

  [输入]*CatalogName中的字符的长度。

• SchemaName

  [输入]模式名称。如果驱动程序支持某些表的模式，而不支持其他表的模式（例如，当驱动程序从不同 DBMS 检索数据时），则空字符串 ("" ) 表示不具有模式的那些表。SchemaName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 SchemaName 被视为标识符。如果SQL_FALSE，则 SchemaName 是普通参数；它按原义处理，其大小写有意义。

• NameLength2

  [输入]*SchemaName中的字符的长度。

• TableName

  [输入]表名称。此参数不能为 null 指针。TableName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 TableName将被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 TableName为普通参数；它按原义处理，其大小写有意义。

• NameLength3

  [输入]*TableName的长度。

• ColumnName

  [输入]列名称的字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 ColumnName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 ColumnName为模式值参数；它按原义处理，其大小写有意义。

• NameLength4

  [输入]*ColumnName的长度。

3.10.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.10.5.诊断

当SQLColumnPrivileges返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，通过调用SQLGetDiagRec函数，且其HandleType和Handle参数分别设置为SQL_HANDLE_STMT和ConnectionHandle，可得到一个相关的SQLSTATE值。下面的表格列出了由SQLColumnPrivileges返回的SQLSTATE值，并解释了与这个函数相关的每个信息；标注为“(DM)”位于驱动程序管理器返回的SQLSTATEs说明之前。除非另有说明，否则将指定与每个SQLSTATE值SQL_ERROR返回代码。

SQLColumnPrivileges 诊断代码

3.11.SQLColumns

3.11.1.功能描述

SQLColumns返回指定表中的列名列表。驱动程序将此信息作为指定 StatementHandle 上的结果集返回。

3.11.2.语法

SQLRETURN SQLColumns(  
     SQLHSTMT       StatementHandle,  
     SQLCHAR *      CatalogName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      SchemaName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      TableName,  
     SQLSMALLINT    NameLength3,  
     SQLCHAR *      ColumnName,  
     SQLSMALLINT    NameLength4); 

3.11.3.参数

• StatementHandle

  [输入]语句句柄。

• CatalogName

  [输入]目录名称。如果驱动程序支持某些表的目录，但不支持其他表的目录，例如，当驱动程序从不同的 DBMS 中检索数据时，空字符串("") 指示没有目录的表。CatalogName 不能包含字符串搜索模式。

  注意

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 CatalogName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 CatalogName是普通参数；它按原义处理，其大小写有意义。

• NameLength1

  [输入]CatalogName中的字符的长度。

• SchemaName

  [输入]模式名称的字符串搜索模式。如果驱动程序支持某些表的模式，而不支持其他表的模式（例如，当驱动程序从不同 DBMS检索数据时），则空字符串 ( "" ) 指示不具有模式的那些表。

  注意

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 SchemaName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 SchemaName为模式值参数；它按原义处理，其大小写有意义。

• NameLength2

  [输入]SchemaName中的字符的长度。

• TableName

  [输入]表名的字符串搜索模式。

  注意

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 TableName将被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 TableName为模式值参数；它按原义处理，其大小写有意义。

• NameLength3

  [输入]TableName的长度。

• ColumnName

  [输入]列名称的字符串搜索模式。

  注意

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 ColumnName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 ColumnName为模式值参数；它按原义处理，其大小写有意义。

• NameLength4

  [输入]ColumnName的长度。

3.11.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.11.5.诊断

当 SQLColumns 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO时，通过调用SQLGetDiagRec 函数，且其 HandleType 和 Handle 参数分别设置为 SQL_HANDLE_STMT 和ConnectionHandle ，可得到一个相关的 SQLSTATE 值。下面的表格列出了由 SQLColumns 返回的SQLSTATE值，并解释了与这个函数相关的每个信息；标注为“(DM)”位于驱动程序管理器返回的 SQLSTATEs说明之前。除非另有说明，否则将指定与每个 SQLSTATE值SQL_ERROR返回代码。

SQLColumns 诊断代码

3.12.SQLConnect

3.12.1.功能描述

SQLConnect在驱动程序和数据源之间建立连接。连接上数据源之后，可以通过连接句柄访问到所有有关连接数据源的信息，包括程序运行状态、事务处理状态和错误信息。

3.12.2.语法

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

3.12.3.参数

• ConnectionHandle

  [输入]连接句柄。

• ServerName

  [输入]数据源名称。数据可以与程序位于同一台计算机上，也可以位于网络中某个位置的另一台计算机上。

• NameLength1

  [输入]*ServerName的长度。

• UserName

  [输入]用户标识符。

• NameLength2

  [输入]UserName的长度。

• Authentication

  [输入]数据源中数据库用户密码。

• NameLength3

  [输入]Authentication的长度。

3.12.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE 或SQL_STILL_EXECUTING。

3.12.5.诊断

当调用SQLConnect函数返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，通过调用SQLGetDiagRec函数，并将HandleType和Handle参数设置为SQL_HANDLE_DBC和ConnectionHandle，可得到一个相关的SQLSTATE值，通过SQLSTATE值可以查出调用此函数的具体信息。

SQLConnect 诊断代码

3.13.SQLCopyDesc

3.13.1.功能描述

SQLCopyDesc将描述符信息从一个描述符句柄复制到另一个描述符句柄。

3.13.2.语法

SQLRETURN SQLCopyDesc(  
     SQLHDESC     SourceDescHandle,  
     SQLHDESC     TargetDescHandle); 

3.13.3.参数

• SourceDescHandle

  [输入]源描述符句柄。

• TargetDescHandle

  [输入]目标描述符句柄。TargetDescHandle 参数可以是应用程序描述符或 IPD 的句柄。TargetDescHandle 不能设置为 IRD 的句柄，或者 SQLCopyDesc 将返回 SQLSTATE HY016(无法修改实现行描述符)。

3.13.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。

3.13.5.诊断

当 SQLCopyDesc 函数返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO时，通过调用SQLGetDiagRec 函数，且其 HandleType 和 Handle 参数分别设置为 SQL_HANDLE_DESC 和TargetDescHandle，可得到一个相关的 SQLSTATE 值。如果一个无效的 SourceDescHandle 传到函数中，会返回SQL_INVALID_HANDLE，并不返回 SQLSTATE。下面的表格列出了由 SQLCopyDesc 返回的 SQLSTATE值，并解释了与这个函数相关的每个信息；标注为“(DM)”位于驱动程序管理器返回的 SQLSTATEs说明之前。除非另有说明，否则将指定与每个 SQLSTATE 值SQL_ERROR返回代码。

当返回一个错误时，SQLCopyDesc 调用立即终止，且不定义TargetDescHandle 描述符字段的内容。

因为 SQLCopyDesc 可由 SQLGetDescField 和 SQLSetDescField 调用实现，所以 SQLCopy Desc可返回能由 SQLGetDescField 或 SQLSetDescField返回的所有 SQLSTATE 。

SQLCopyDesc 诊断代码

3.14.SQLDescribeCol

3.14.1.功能描述

SQLDescribeCol 将返回结果集中的一列的结果描述符-列名称、类型、列大小、十进制数字和是否为空。此信息还可用于 IRD 的字段。

3.14.2.语法

SQLRETURN SQLDescribeCol(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   ColumnNumber,  
      SQLCHAR *      ColumnName,  
      SQLSMALLINT    BufferLength,  
      SQLSMALLINT *  NameLengthPtr,  
      SQLSMALLINT *  DataTypePtr,  
      SQLULEN *      ColumnSizePtr,  
      SQLSMALLINT *  DecimalDigitsPtr,  
      SQLSMALLINT *  NullablePtr); 

3.14.3.参数

• StatementHandle

  [输入]语句句柄。

• ColumnNumber

  [输入]结果数据的列序号，以递增的列顺序排列，起始值为 1 。也可将ColumnNumber 参数设置为 0，来描述书签列。

• ColumnName

  [输出]一个缓冲区的指针，返回的列名存放到此缓冲区中。从 IRD 的SQL_DESC_NAME 字段中读取这个值。如果没有命名列， 或者不能确定列名，驱动程序会返回一个空字符串。

• BufferLength

  [输入]ColumnName缓冲区的长度。

• NameLengthPtr

  [输出]指向缓冲区的指针，将在此缓冲区中返回 (排除 null 终止)可在 ColumnName中返回的字符总数。如果可返回的字符数大于或等于BufferLength，则 ColumnName 中的列名称将截断为 * BufferLength 减去 null 终止字符的长度。

• DataTypePtr

  [输出]指向要返回列的数据类型SQL的缓冲区的指针。这个值从 IRD的 SQL_DESC_CONCISE_TYPE字段读取。这将是"数据类型"SQL中的值之一，或特定于驱动程序SQL数据类型。如果无法确定数据类型，驱动程序将返回SQL_UNKNOWN_TYPE。

  当 ColumnNumber 等于0时（书签列），QL_BINARY 在 * DataTypePtr 中返回可变长度书签的值。

• ColumnSizePtr

  [输出]指向缓冲区的指针，将在该缓冲区中返回数据源中列的大小 (以字符)。如果无法确定列的大小，则驱动程序将返回0。

• DecimalDigitsPtr

  [输出]指向缓冲区的指针，该缓冲区用于返回数据源中列的小数位数。如果小数位数不能确定或不适用，则驱动程序将返回0。

• NullablePtr

  [输出]指向缓冲区的指针，将在此缓冲区中返回一个值，该值指示列是否允许 NULL 值。此值从 IRD 的"SQL_DESC_NULLABLE" 字段读取。该值是下列值之一：

  • SQL_NO_NULLS：列不允许空值。

  • SQL_NULLABLE：列允许 NULL 值。

  • SQL_NULLABLE_UNKNOWN：驱动程序无法确定列是否允许 NULL 值。

3.14.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.14.5.诊断

当 SQLDescribeCol 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_STMT 和 StatementHandle 的句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了通常由 SQLDescribeCol 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为“(DM)”位于驱动程序管理器返回的SQLSTATEs 的说明之前。除非另有说明，否则将指定与每个 SQLSTATE 值SQL_ERROR返回代码。

SQLDescribeCol 诊断代码

SQLDescribeCol 可以返回 SQLPrepare 或 SQLExecute 在 SQLPrepare 之后调用时可以返回的任何SQLSTATE，具体取决于数据源计算与语句句柄关联的 SQL 语句的时间。

出于性能方面的考虑，应用程序在执行语句之前不应调用 SQLDescribeCol 。

3.15.SQLDescribeParam

3.15.1.功能描述

SQLDescribeParam返回一个参数标记的描述，此描述与一条准备好的SQL 语句相关。也可从 IPD 的字段中获得这个信息。

3.15.2.语法

SQLRETURN SQLDescribeParam(  
      SQLHSTMT        StatementHandle,  
      SQLUSMALLINT    ParameterNumber,  
      SQLSMALLINT *   DataTypePtr,  
      SQLULEN *       ParameterSizePtr,  
      SQLSMALLINT *   DecimalDigitsPtr,  
      SQLSMALLINT *   NullablePtr); 

3.15.3.参数

• StatementHandle

  [输入]语句句柄。

• ParameterNumber

  [输入]参数标记编号按递增参数顺序排序，从1开始。

• DataTypePtr

  [输出]一个指针，指向要在其中返回参数 SQL 数据类型的缓冲区。此值从 IPD 的SQL_DESC_CONCISE_TYPE 记录字段中读取。

  如果 ColumnNumber 等于书签列的0，则将在* DataTypePtr 中为可变长度书签返回 SQL_BINARY。

• ParameterSizePtr

  [输出]指向缓冲区的指针，该缓冲区用于返回数据源定义的相应参数标记的列或表达式的大小。

• DecimalDigitsPtr

  [输出]指向缓冲区的指针，该缓冲区用于返回数据源定义的相应参数的列或表达式的小数位数。

• NullablePtr

  [输出]指向缓冲区的指针，将在此缓冲区中返回一个值，该值指示参数是否允许 NULL 值。此值从 IPD 的SQL_DESC_NULLABLE 字段中读取。下列类型作之一：

  • SQL_NO_NULLS：该参数不允许 NULL 值 (这是) 的默认值。

  • SQL_NULLABLE：参数允许空值。

  • SQL_NULLABLE_UNKNOWN：驱动程序无法确定参数是否允许空值。

3.15.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.15.5.诊断

当 SQLDescribeParam 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO时，通过调用SQLGetDiagRec 函数，且其 HandleType 和 Handle 参数分别设置为 SQL_HANDLE_STMT 和StatementHandle ，可得到一个相关的SQLSTATE 值。下面的表格列出了由 SQLDescribeParam返回的SQLSTATE 值，并解释了与这个函数相关的每个信息 ；标注为“(DM)”位于驱动程序管理器返回的 SQLSTATEs的说明之前。如果没有其他注释，那么与每个 SQLSTATE 值相关的返回代码是 SQL_ERROR。

SQLDescribeParam 诊断代码

3.16.SQLDisconnect

3.16.1.功能描述

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

3.16.2.语法

SQLRETURN SQLDisconnect(  
    SQLHDBC     ConnectionHandle); 

3.16.3.参数

• ConnectionHandle

  [输入]连接句柄。

3.16.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE 或SQL_STILL_EXECUTING。

3.16.5.诊断

当 SQLDisconnect 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，通过调用SQLGetDiagRec 函数，且其 HandleType 和 Handle 参数分别设置 为 SQL_HANDLE_DBC 和ConnectionHandle ，可得到一个相关的 SQLSTATE 值。下面的表格列出了由 SQLDisconnect 返回的SQLSTATE 值，并解释了与这个函数相关的每个信息；标注为“(DM)”位于驱动程序管理器返回的 SQLSTATEs的说明之前。如果没有其他注释，那么与每个 SQLSTATE 值相关的返回代码是SQL_ERROR。

SQLDisconnect 诊断代码

3.17.SQLDriverConnect

3.17.1.功能描述

SQLDriverConnect是 SQLConnect的替代方法。它支持需要比 SQLConnect中的三个参数更多的连接信息的数据源、提示用户输入所有连接信息的对话框，以及系统信息中未定义的数据源。。

3.17.2.语法

SQLRETURN SQLDriverConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLHWND         WindowHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr,  
     SQLUSMALLINT    DriverCompletion); 

3.17.3.参数

• ConnectionHandle

  [输入]连接句柄。

• WindowHandle

  [输入]窗口句柄。如果可用，应用程序可以传送父窗口的句柄。如果窗口句柄不可用，或者 SQLDriverConnect函数不出现任何对话框，应用程序传送一个空指针。

• InConnectionString

  [输入]完整的连接字符串 ("Comments") 部分连接字符串或空字符串中的语法。

• StringLength1

  [输入]InConnectionString 的长度（如果字符串为 Unicode，则以字符为单位；如果字符串为 ANSI 或DBCS，则以字节为单位）。

• OutConnectionString

  [输出]指向已完成连接字符串的缓冲区的指针。成功连接到目标数据源后，此缓冲区包含已完成的连接字符串。应用程序应为此缓冲区至少分配1，024 个字符。

  如果 OutConnectionString 为 NULL，则 StringLength2Ptr 仍将返回字符总数 (不包括字符数据null 终止字符) 可在 OutConnectionString 指向的缓冲区中返回。

• BufferLength

  [输入]OutConnectionString 缓冲区的长度。

• StringLength2Ptr

  [输出]一个缓冲区的指针，此缓冲区存放返回给 OutConnectionString的可用字节总数（不包括空值终止字节）。如果返回的可用字节数大于等于BufferLength ，那么 *OutConnectionString 中已完成的连接字符串将截断为 BufferLength减去 null 终止字符的长度。

• DriverCompletion

  [输入]一个标志，它显示出驱动管理器或驱动程序是否必须提示更多的连接信息：SQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE、SQL_DRIVER_COMPLETE_REQUIRED 或SQL_DRIVER_NOPROMPT。

3.17.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR、SQL_INVALID_HANDLE或 SQL_STILL_EXECUTING。

3.17.5.诊断

当 SQLDriverConnect 返回 SQL_ERROR 或SQL_SUCCESS_WITH_INFO 时，通过调 用SQLGetDiagRec 函数，且其 fHandleType 和 hHandle 参数分别设置为 SQL_HANDLE_DBC和ConnectionHandle ，可得到一个相关的 SQLSTATE 值。下面的表格列出了由 SQLDriverConnect 返回的SQLSTATE 值，并解释了与这个函数相关的每个信息；标注为 “(DM)”位于驱动程序管理器返回的 SQLSTATEs说明之前。如果没有其他注释，那么与每个 SQLSTATE值相关的返回代码是 SQL_ERROR。

SQLDriverConnect 诊断代码

3.18.SQLEndTran

3.18.1.功能描述

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

3.18.2.语法

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

3.18.3.参数

• HandleType

  [输入]句柄类型标识符。如果 Handle（句柄）是一个环境句柄，那么包含SQL_HANDLE_ENV，如果Handle（句柄）是一个连接句柄，那么包含 SQL_HANDLE_DBC。

• Handle

  [输入]HandleType 显示类型的句柄，指示事务的范围。

• CompletionType

  [输入]两个值之一：SQL_COMMIT、SQL_ROLLBACK。

3.18.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE 或SQL_STILL_EXECUTING。

3.18.5.诊断

当 SQLEndtran 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可能通过使用相应的HandleType 和 Handle 调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。下面的表格列出了由SQLEndtran 返回的 SQLSTATE 值，并解释了与这个函数相关的每个信息；标注为“(DM)”位于驱动程序管理器返回的SQLSTATEs 说明之前。如果没有其他注释，那么与每个 SQLSTATE 值相关的返回代码是SQL_ERROR。

SQLEndTran 诊断代码

3.19.SQLExecDirect

3.19.1.功能描述

如果语句中有参数的话，SQLExecDirect 函数使用参数标记参数的当前值，执行一条准备好的语句。SQLExecDirect是提交用于一次性执行的 SQL 语句的最快方法。

3.19.2.语法

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

3.19.3.参数

• StatementHandle

  [输入]语句句柄。

• StatementText

  [输入]要执行SQL语句，不支持一次执行多条语句。

• TextLength

  [输入]*StatementText的长度。

3.19.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NEED_DATA、SQL_STILL_EXECUTING、SQL_ERROR、SQL_NO_DATA、SQL_INVALID_HANDLE 或 SQL_PARAM_DATA_AVAILABLE。

3.19.5.诊断

当 SQLExecDirect 函数返回 SQL_ERROR 或SQL_SUCCESS_WITH_INFO 时，通过调用SQLGetDiagRec 函数，且其HandleType 和 Handle 参数分别设置为 SQL_HANDLE_STMT 和StatementHandle，可得到一个相关的 SQLSTATE 值。下面的表格列出了由 SQLExecDirect 返回的 SQLSTATE值 ，并解释了与这个函数相关的每个信息；标注为 “(DM)” 位于驱动程序管理器返回的 SQLSTATEs 的说明之前。如果没有其他注释，那么与每个 SQLSTATE 值相关的返回代码是 SQL_ERROR 。

SQLExecDirect 诊断代码

3.20.SQLExecute

3.20.1.功能描述

如果语句中存在参数标记的话，SQLExecute函数使用参数标记参数的当前值，执行一条准备好的SQL语句。

3.20.2.语法

SQLRETURN SQLExecute(  
     SQLHSTMT     StatementHandle); 

3.20.3.参数

• StatementHandle

  [输入]语句句柄。

3.20.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NEED_DATA、SQL_STILL_EXECUTING、SQL_ERROR、SQL_NO_DATA、SQL_INVALID_HANDLE 或SQL_PARAM_DATA_AVAILABLE。

3.20.5.诊断

当 SQLExecute 函数返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，通过调用SQLGetDiagRec 函数，且其 HandleType 和 Handle 参数分别设置为 SQL_HANDLE_STMT 和StatementHandle，可得到一个相关的SQLSTATE 值。下面的表格列出了由 SQLExecute 返回的 SQLSTATE值，并解释了与这个函数相关的每个信息；标注为“(DM)”位于驱动程序管理器返回的 SQLSTATEs说明之前。如果没有其他注释，那么与每个 SQLSTATE 值相关的返回代码是SQL_ERROR。

SQLExecute 诊断代码

3.21.SQLFetch

3.21.1.功能描述

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

3.21.2.语法

SQLRETURN SQLFetch(  
     SQLHSTMT     StatementHandle); 

3.21.3.参数

• StatementHandle

  [输入]语句句柄。

3.21.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。

3.21.5.诊断

当调用SQLFetch函数返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，通过调用SQLGetDiagRec函数，并将HandleType和Handle参数设置为SQL_HANDLE_STMT和StatementHandle，可得到一个相关的SQLSTATE值，通过SQLSTATE值可以查出调用此函数的具体信息。

SQLFetch 诊断代码

3.22.SQLFetchScroll

3.22.1.功能描述

SQLFetchScroll从结果集提取指定的数据行集，并返回所有绑定列的数据。可在绝对或相对位置或按书签指定行集。

3.22.2.语法

SQLRETURN SQLFetchScroll( 
SQLHSTMT		StatementHandle, 
SQLSMALLINT 	FetchOrientation, 
SQLINTERGER 	FetchOffset); 

3.22.3.参数

• StatementHandle

  [输入]语句句柄。

• FetchOrientation

  [输入]提取类型，提取类型如下所示。

  • SQL_FETCH_NEXT

  • SQL_FETCH_PRIOR

  • SQL_FETCH_FIRST

  • SQL_FETCH_LAST

  • SQL_FETCH_ABSOLUTE

  • SQL_FETCH_RELATIVE

  • SQL_FETCH_BOOKMARK

• FetchOffset

  [输入]要提取的行数。此参数的解释取决于 FetchOrientation参数的值。

3.22.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR或 SQL_INVALID_HANDLE。

3.22.5.诊断

当 SQLFetchScroll 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用具有SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句柄的 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了 SQLFetchScroll 通常返回的 SQLSTATE值，并说明了此函数上下文中的每个值；标注为"(DM)"位于驱动程序管理器返回的 SQLSTATEs 说明之前。除非另有说明，否则将与每个 SQLSTATE 值关联的返回代码是SQL_ERROR。如果单个列上发生错误，可以使用的DiagIdentifier 调用 SQLGetDiagField SQL_DIAG_COLUMN_NUMBER以确定发生错误的列；和SQLGetDiagField 可以使用 SQL_DIAG_ROW_NUMBER 的 DiagIdentifier进行调用，以确定包含该列的行。

对于可以返回 SQL_SUCCESS_WITH_INFO 或 SQL_ERROR（除了 01xxx SQLSTATEs）的所有SQLSTATEs，如果多行运算的一个或多个（但不是全部）行发生错误，则返回SQL_SUCCESS_WITH_INFO；如果单行操作出错，则返回 SQL_ERROR。

SQLFetchScroll 诊断代码

3.23.SQLForeignKeys

3.23.1.功能描述

SQLForeignKeys可以返回：

• 指定表中的外键列表(指定表中的列，这些列引用其他表中的主键) 。

• 其他表中引用指定表中主键的外键列表。

驱动程序将每个列表作为指定语句的结果集返回。

3.23.2.语法

SQLRETURN SQLForeignKeys(  
     SQLHSTMT       StatementHandle,  
     SQLCHAR *      PKCatalogName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      PKSchemaName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      PKTableName,  
     SQLSMALLINT    NameLength3,  
     SQLCHAR *      FKCatalogName,  
     SQLSMALLINT    NameLength4,  
     SQLCHAR *      FKSchemaName,  
     SQLSMALLINT    NameLength5,  
     SQLCHAR *      FKTableName,  
     SQLSMALLINT    NameLength6);  

3.23.3.参数

• StatementHandle

  [输入]语句句柄。

• PKCatalogName

  [输入]主键表目录名称。如果驱动程序为某些表（而不是其他表）支持目录，例如当驱动程序从不同 DBMS检索数据时（例如，当驱动程序检索不同 DBMS 的数据时），则空字符串( "" ) 表示这些表没有目录。PKCatalogName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 PKCatalogName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 PKCatalogName是普通参数；它按原义处理，其大小写有意义。

• NameLength1

  [输入]*PKCatalogName的长度。

• PKSchemaName

  [输入]主键表模式名称。如果驱动程序支持某些表的模式，而不支持其他表的模式（例如，当驱动程序从不同 DBMS检索数据时），则空字符串 ( "" ) 表示不具有模式的那些表。PKSchemaName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 PKSchemaName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 PKSchemaName是普通参数；它按原义处理，其大小写有意义。

• NameLength2

  [输入]*PKSchemaName的长度。

• PKTableName

  [输入]主键表名称。PKTableName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 PKTableName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 PKTableName是普通参数；它按原义处理，其大小写有意义。

• NameLength3

  [输入]*PKTableName的长度。

• FKCatalogName

  [输入]外键表目录名称。如果驱动程序为某些表（而不是其他表）支持目录，例如当驱动程序从不同 DBMS检索数据时（例如，当驱动程序检索不同 DBMS 的数据时），则空字符串( "" ) 表示这些表没有目录。FKCatalogName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 FKCatalogName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 FKCatalogName是普通参数；它按原义处理，其大小写有意义。

• NameLength4

  [输入]*FKCatalogName的长度。

• FKSchemaName

  [输入]外键表模式名称。如果驱动程序支持某些表的模式，而不支持其他表的模式（例如，当驱动程序从不同 DBMS检索数据时），则空字符串 ( "" ) 表示不具有模式的那些表。FKSchemaName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 FKSchemaName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 FKSchemaName是普通参数；它按原义处理，其大小写有意义。

• NameLength5

  [输入]*FKSchemaName的长度。

• FKTableName

  [输入]外键表名。FKTableName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 FKTableName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 FKTableName是普通参数；它按原义处理，其大小写有意义。

• NameLength6

  [输入]*FKTableName的长度。

3.23.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.23.5.诊断

当 SQLForeignKeys 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_STMT 和 StatementHandle 的句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了通常由 SQLForeignKeys 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为 "(DM)" 位于驱动程序管理器返回的SQLSTATEs 的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是 SQL_ERROR。

SQLForeignKeys 诊断代码

3.24.SQLFreeHandle

3.24.1.功能描述

SQLFreeHandle释放与特定环境、连接、语句或描述符句柄关联的资源。

3.24.2.语法

SQLRETURN SQLFreeHandle(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle); 

3.24.3.参数

• HandleType

  [输入] SQLFreeHandle 要释放的句柄的类型。必须是以下值之一：

  • SQL_HANDLE_DBC

  • SQL_HANDLE_DBC_INFO_TOKEN

  • SQL_HANDLE_DESC

  • SQL_HANDLE_ENV

  • SQL_HANDLE_STMT

  SQL_HANDLE_DBC_INFO_TOKEN句柄仅由驱动程序管理器和驱动程序使用。应用程序不应使用此句柄类型。

  如果 HandleType 不是这些值之一 ，SQLFreeHandle 将返回SQL_INVALID_HANDLE。

• Handle

  [输入]要释放的句柄。

3.24.4.返回值

SQL_SUCCESS、SQL_ERROR或SQL_INVALID_HANDLE。

如果 SQLFreeHandle 返回SQL_ERROR，则句柄仍然有效。

3.24.5.诊断

当 SQLFreeHandle SQL_ERROR，可能会从 SQLFreeHandle 尝试释放但无法释放的句柄的诊断数据结构获取关联的SQLSTATE 值。下表列出了 SQLFreeHandle 通常返回的 SQLSTATE值，并说明了此函数上下文中的每个值；标注为“(DM)”位于驱动程序管理器返回的 SQLSTATEs 说明之前。除非另有说明，否则将与每个 SQLSTATE 值关联的返回代码是SQL_ERROR。

SQLFreeHandle 诊断代码

3.25.SQLFreeStmt

3.25.1.功能描述

SQLFreeStmt停止与特定语句关联的处理、关闭、任何打开的游标，放弃挂起的结果，还可以释放与该语句句柄关联的所有资源。

3.25.2.语法

SQLRETURN SQLFreeStmt(
  SQLHSTMT       StatementHandle,
  SQLUSMALLINT   Option);  

3.25.3.参数

• StatementHandle

  [输入]语句句柄。

• Option

  [输入]以下选项之一：

  • SQL_CLOSE：如果定义了一个游标，则关闭与该StatementHandle（关联的游标（如果） 定义），并放弃所有挂起的结果。稍后，应用程序可以使用相同或不同的参数值再次执行 SELECT 语句来重新打开此游标。如果没有打开的游标，则此选项不会影响应用程序。还可以调用SQLCloseCursor 以关闭游标。

  • SQL_DROP：不推荐使用此选项。使用 SQL_DROP 选项的调用 SQLFreeStmt 在驱动程序管理器中映射到SQLFreeHandle。

  • SQL_UNBIND：将 ARD 的 SQL_DESC_COUNT 字段设置为0，释放由 SQLBindCol绑定的针对给定 StatementHandle 的所有列缓冲区。这不取消绑定书签列；为此，"书签" 列ARD 的 "SQL_DESC_DATA_PTR" 字段设置为 NULL。请注意，如果在由多个语句共享的显式分配的描述符上执行此操作，则该操作将影响所有共享描述符的语句的绑定。

  • SQL_RESET_PARAMS：将 APD 的 SQL_DESC_COUNT 字段设置为0，释放由SQLBindParameter 为给定的 StatementHandle 设置的所有参数缓冲区。如果在由多个语句共享的显式分配的描述符上执行此操作，此操作将影响共享该描述符的所有语句的绑定。

3.25.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。

3.25.5.诊断

当 SQLFreeStmt 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_STMT 和 StatementHandle 的句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了通常由 SQLFreeStmt 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为“(DM)”位于驱动程序管理器返回的SQLSTATEs 的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是 SQL_ERROR。

SQLFreeStmt 诊断代码

3.26.SQLGetCursorName

3.26.1.功能描述

SQLGetCursorName返回与指定语句相关联的游标名称。

3.26.2.语法

SQLRETURN SQLGetCursorName(  
     SQLHSTMT        StatementHandle,  
     SQLCHAR *       CursorName,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   NameLengthPtr);  

3.26.3.参数

• StatementHandle

  [输入]语句句柄。

• CursorName

  [输出]指向缓冲区的指针，将在此缓冲区中返回游标名称。

• BufferLength

  [输入]*CursorName的长度。

• NameLengthPtr

  [输出]指向内存的指针，在该内存中要返回可返回到 * CursorName 中的字节总数 (不包括 NULL 终止字符)。如果可返回的字节数大于或等于BufferLength，* CursorName 中的的游标的名称被截断为BufferLength减去 NULL 终止字符的长度。

3.26.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。

3.26.5.诊断

当 SQLGetCursorName 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_STMT 和 StatementHandle 的句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了通常由 SQLGetCursorName 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为“(DM) ”位于驱动程序管理器返回的 SQLSTATEs的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是 SQL_ERROR。

SQLGetCursorName 诊断代码

3.27.SQLGetData

3.27.1.功能描述

SQLGetData返回结果集中某一列的数据。可以多次调用它来部分地检索可不定长度的数据。

3.27.2.语法

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

3.27.3.参数

• StatementHandle

  [输入]语句句柄。

• Col_or_Param_Num

  [输入]要返回数据的列号。结果集的列按增序从1开始编号。书签列的列号为0。

• TargetType

  [输入]* TargetValuePtr 缓冲中的 C 数据类型的类型标识符。如果 TargetType是SQL_ARD_TYPE ，驱动使用 ARD 的SQL_DESC_CONCISE_TYPE字段的类型标识符。如果它是SQL_C_DEFAULT，驱动根据源的 SQL数据类型选择缺省的 C 数据类型。

• TargetValuePtr

  [输出]指向要返回数据的缓冲区的指针。

  TargetValuePtr 不能为 NULL。

• BufferLength

  [输入]TargetValuePtr所指向缓冲区的长度。

• StrLen_or_IndPtr

  [输出]一个指针，指向要返回其长度或指示器值的缓冲区。如果这是 null指针，则不返回长度或指示器值。当提取的数据为空时，这将返回错误。

  SQLGetData可以返回长度/指示器缓冲区中的以下值：

  • 可供返回的数据的长度

  • SQL_NO_TOTAL

  • SQL_NULL_DATA

3.27.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。

3.27.5.诊断

当调用SQLGetData函数返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，通过调用SQLGetDiagRec函数，并将HandleType和Handle参数分别设置为SQL_HANDLE_STMT和StatementHandle，可得到一个相关的SQLSTATE值，通过SQLSTATE值可以查出调用此函数的具体信息。

SQLGetData 诊断代码

3.28.SQLGetDescField

3.28.1.功能描述

SQLGetDescField返回描述符记录的单个字段的当前设置或值。

3.28.2.语法

SQLRETURN SQLGetDescField(
  SQLHDESC        DescriptorHandle,
  SQLSMALLINT     RecNumber,
  SQLSMALLINT     FieldIdentifier,
  SQLPOINTER      ValuePtr,
  SQLINTEGER      BufferLength,
  SQLINTEGER *    StringLengthPtr); 

3.28.3.参数

• DescriptorHandle

  [输入]描述符句柄。

• RecNumber

  [输入]指示应用程序从中查找信息的描述符记录。描述符记录从0开始编号，记录号0为书签记录。如果 FieldIdentifier参数指示标头字段，则将忽略 RecNumber。如果 RecNumber 小于或等于 SQL_DESC_COUNT但行不包含列或参数的数据，则对 SQLGetDescField 的调用将返回字段的默认值。

• FieldIdentifier

  [输入]指示要返回其值的描述符字段。

• ValuePtr

  [输出]一个指针，指向要在其中返回描述符信息的缓冲区。数据类型取决于 FieldIdentifier 的值。

  如果将 valueptr 是整数类型，应用程序应使用SQLULEN生成的缓冲区并在调用此函数之前将值初始化为0，因为某些驱动程序只能写入缓冲区的较低32位或16位，并使高阶位保持不变。

  如果将 valueptr 为 NULL，则 StringLengthPtr 仍将返回 (排除字符数据的 NULL终止字符之外的总字节数)可在将 valueptr所指向的缓冲区中返回。

• BufferLength

  [输入]如果FieldIdentifier是一个ODBC定义的字段，而将valueptr指向某个字符串或二进制缓冲区，则此参数的长度应为 * 将 valueptr。如果FieldIdentifier是一个ODBC定义的字段，而 * 将valueptr是一个整数，则将忽略BufferLength。如果在调用SQLGetDescFieldW)时，* 将valueptr中的值为Unicode数据类型，则BufferLength参数必须是偶数。

  如果FieldIdentifier是驱动程序定义的字段，应用程序会通过设置BufferLength参数来指示该字段的特性。BufferLength可具有以下值：

  • 如果*将valueptr是指向字符串的指针，则BufferLength是字符串或SQL_NTS的长度。

  • 如果*将valueptr是一个指向二进制缓冲区的指针，则应用程序将SQL_LEN_BINARY_ATTR(LENGTH)宏的结果放置于BufferLength。这会在BufferLength中置入负值。

  • 如果*将valueptr是一个指向字符串或二进制字符串以外的值的指针，则BufferLength的值应SQL_IS_POINTER。

  • 如果*将valueptr包含固定长度的数据类型，则BufferLength SQL_IS_INTEGER、SQL_IS_UINTEGER、SQL_IS_SMALLINT或SQL_IS_USMALLINT，视情况而定。

• StringLengthPtr

  [输出]指向缓冲区的指针，将在此缓冲区中返回 null 终止字符所需的字节数排除 *将 valueptr 中可返回的字节数。

3.28.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA 或SQL_INVALID_HANDLE。

如果 RecNumber 大于当前说明符记录数，则返回 SQL_NO_DATA。

如果 DescriptorHandle 是 IRD 句柄，并且该语句处于已准备或已执行状态，但没有打开的游标，则返回SQL_NO_DATA。

3.28.5.诊断

当 SQLGetDescField 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_STMT 和 StatementHandle 的句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了通常由 SQLGetDescField 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为“(DM)” 位于驱动程序管理器返回的 SQLSTATEs的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是 SQL_ERROR。

SQLGetDescField 诊断代码

3.29.SQLGetDescRec

3.29.1.功能描述

SQLGetDescRec返回描述符记录的多个字段的当前设置或值。返回的字段描述列或参数数据的名称、数据类型和存储。

3.29.2.语法

SQLRETURN SQLGetDescRec(  
      SQLHDESC        DescriptorHandle,  
      SQLSMALLINT     RecNumber,  
      SQLCHAR *       Name,  
      SQLSMALLINT     BufferLength,  
      SQLSMALLINT *   StringLengthPtr,  
      SQLSMALLINT *   TypePtr,  
      SQLSMALLINT *   SubTypePtr,  
      SQLLEN *        LengthPtr,  
      SQLSMALLINT *   PrecisionPtr,  
      SQLSMALLINT *   ScalePtr,  
      SQLSMALLINT *   NullablePtr);  

3.29.3.参数

• DescriptorHandle

  [输入]描述符句柄。

• RecNumber

  [输入]指示应用程序从中查找信息的描述符记录。说明符记录的编号为1，记录号0为书签记录。RecNumber 参数必须小于或等于SQL_DESC_COUNT 的值。如果 RecNumber 小于或等于 SQL_DESC_COUNT但行不包含列或参数的数据，则对 SQLGetDescRec的调用将返回字段的默认值。

• Name

  [输出]指向缓冲区的指针，将在该缓冲区中返回描述符记录的 SQL_DESC_NAME 字段。

  如果 name 为 NULL，则 StringLengthPtr 仍将返回 (排除字符数据的 NULL 终止字符的总字符数)可在按名称指向的缓冲区中返回。

• BufferLength

  [输入]*name缓冲区的长度。

• StringLengthPtr

  [输出]指向缓冲区的指针，该缓冲区用于返回名称缓冲区中可返回的数据的字符数 * ，不包括 null 终止字符。如果字符数大于或等于BufferLength，则 Name 中的数据将截断为 * BufferLength 减去 null终止字符的长度，并且由驱动程序以 null 终止。

• TypePtr

  [输出]指向缓冲区的指针，该缓冲区用于返回描述符记录的 SQL_DESC_TYPE 字段的值。

• SubTypePtr

  [输出]对于类型为 SQL_DATETIME 或 SQL_INTERVAL 的记录，这是指向要在其中返回SQL_DESC_DATETIME_INTERVAL_CODE 字段值的缓冲区的指针。

• LengthPtr

  [输出]指向缓冲区的指针，该缓冲区用于返回描述符记录的 SQL_DESC_OCTET_LENGTH 字段的值。

• PrecisionPtr

  [输出]指向缓冲区的指针，该缓冲区用于返回描述符记录的 SQL_DESC_PRECISION 字段的值。

• ScalePtr

  [输出]指向缓冲区的指针，该缓冲区用于返回描述符记录的 SQL_DESC_SCALE 字段的值。

• NullablePtr

  [输出]指向缓冲区的指针，该缓冲区用于返回描述符记录的 SQL_DESC_NULLABLE 字段的值。

3.29.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA 或SQL_INVALID_HANDLE。

如果 RecNumber 大于当前说明符记录数，则返回 SQL_NO_DATA。

如果 DescriptorHandle 是 IRD 句柄，并且该语句处于已准备或已执行状态，但没有打开的游标，则返回SQL_NO_DATA。

3.29.5.诊断

当 SQLGetDescRec 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_DESC 和 DescriptorHandle 的句柄调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。下表列出了通常由 SQLGetDescRec 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为“(DM)” 位于驱动程序管理器返回的SQLSTATEs 的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是 SQL_ERROR。

SQLGetDescRec 诊断代码

3.30.SQLGetDiagField

3.30.1.功能描述

SQLGetDiagField 返回诊断数据结构的记录字段的当前值，与包含错误、警告和状态信息的指定句柄相关联。

3.30.2.语法

SQLRETURN SQLGetDiagField(
  SQLSMALLINT     HandleType,
  SQLHANDLE       Handle,
  SQLSMALLINT     RecNumber,
  SQLSMALLINT     DiagIdentifier, 
  SQLPOINTER      DiagInfoPtr,
  SQLSMALLINT     BufferLength,
  SQLSMALLINT *   StringLengthPtr);  

3.30.3.参数

• HandleType

  [输入]一个句柄类型标识符，描述需要诊断的句柄的类型。必须是下列选项之一：

  • SQL_HANDLE_DBC

  • SQL_HANDLE_DBC_INFO_TOKEN

  • SQL_HANDLE_DESC

  • SQL_HANDLE_ENV

  • SQL_HANDLE_STMT

  SQL_HANDLE_DBC_INFO_TOKEN 句柄仅由驱动程序管理器和驱动程序使用。应用程序不应使用此句柄类型。

• Handle

  [输入]HandleType 指示的类型的诊断数据结构的句柄。如果 SQL_HANDLE_ENV HandleType，则句柄可以是共享或非共享环境句柄。

• RecNumber

  [输入]指示应用程序从中查找信息的状态记录。状态记录从1开始编号。如果 DiagIdentifier参数指示诊断标头的任何字段，则将忽略 RecNumber 。如果不是，则它应大于0。

• DiagIdentifier

  [输入]指示要返回其值的诊断字段。

• DiagInfoPtr

  [输出]输出指向要返回诊断信息的缓冲区的指针。数据类型取决于 DiagIdentifier 的值。如果 DiagInfoPtr是整数类型，则在调用此函数之前，应用程序应使用 sqlulen生成的缓冲区并将值初始化为0，因为某些驱动程序只能写入缓冲区中的较低32位或16位，并使高阶位保持不变。

  如果 DiagInfoPtr 为 NULL，则 StringLengthPtr 仍将返回 (排除字符数据的 NULL终止字符之外的总字节数) 可在 DiagInfoPtr 所指向的缓冲区中返回。

• BufferLength

  [输入]如果 DiagIdentifier 是一个 ODBC 定义的诊断，并且 DiagInfoPtr指向某个字符串或二进制缓冲区，则此参数的长度应为 *DiagInfoPtr。如果 DiagIdentifier 是一个 ODBC 定义的字段，而 *DiagInfoPtr 是一个整数，则将忽略 BufferLength。如果在调用 SQLGetDiagFieldW)时， *DiagInfoPtr 中的值为 Unicode 字符串，则 BufferLength 参数必须是偶数。

  如果 DiagIdentifier 是驱动程序定义的字段，应用程序会通过设置 BufferLength 参数来指示该字段的特性。BufferLength 可具有以下值：

  • 如果 DiagInfoPtr 是指向字符串的指针，则 BufferLength 是字符串或 SQL_NTS 的长度。

  • 如果 DiagInfoPtr是一个指向二进制缓冲区的指针，则应用程序将SQL_LEN_BINARY_ATTR(LENGTH)宏的结果放置于BufferLength。这会在BufferLength 中置入负值。

  • 如果 DiagInfoPtr 是一个指向字符串或二进制字符串以外的其他值的指针，则 BufferLength 的值应SQL_IS_POINTER。

  • 如果 * DiagInfoPtr 包含固定 长度的数据类型，则相应地SQL_IS_INTEGER、SQL_IS_UINTEGER、SQL_IS_SMALLINT 或SQL_IS_USMALLINT。

• StringLengthPtr

  [输出]指向缓冲区的指针，该缓冲区返回的字节总数 (不包括 null 终止字符) 可在 DiagInfoPtr 中返回的字节数 *（对于字符数据）。如果可返回的字节数大于或等于 BufferLength，则 DiagInfoPtr 中的文本将被截断为 *BufferLength 减去 null 终止字符的长度。

3.30.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE 或SQL_NO_DATA。

3.30.5.诊断

SQLGetDiagField 不会为自身发布诊断记录。它使用以下返回值报告其自身执行的结果：

• SQL_SUCCESS：函数已成功返回诊断信息。

• SQL_SUCCESS_WITH_INFO：* DiagInfoPtr 太小，无法容纳请求的诊断字段。因此，诊断字段中的数据被截断。若要确定是否发生了截断，应用程序必须将BufferLength 与可用的实际字节数（写入*StringLengthPtr）进行比较。

• SQL_INVALID_HANDLE： HandleType 和句柄指示的句柄不是有效的句柄。

• SQL_ERROR：发生以下情况之一：

• DiagIdentifier 参数不是有效值之一。

• DiagIdentifier 参数SQL_DIAG_CURSOR_ROW_COUNT、SQL_DIAG_DYNAMIC_FUNCTION、SQL_DIAG_DYNAMIC_FUNCTION_CODE 或 SQL_DIAG_ROW_COUNT，但句柄不是语句句柄。(驱动程序管理器返回此诊断。)

• 当 DiagIdentifier 指示诊断记录中的字段时 ，RecNumber 参数为负数或0。对于标头字段，将忽略RecNumber 。

• 请求的值为字符串，BufferLength 小于零。

• 使用异步通知时，句柄上的异步操作不完整。

• SQL_NO_DATA：RecNumber 大于在 handle中指定的句柄所存在的诊断记录数。如果没有适用于句柄的诊断记录，该函数还将为任何正RecNumber 返回 SQL_NO_DATA。

3.31.SQLGetDiagRec

3.31.1.功能描述

SQLGetDiagRec返回包含错误、警告和状态信息的诊断记录的多个字段的当前值。不同于SQLGetDiagField，后者每次调用返回一个诊断字段，SQLGetDiagRec将返回诊断记录的几个常用字段，包括 SQLSTATE、本机错误代码和诊断消息文本。

3.31.2.语法

SQLRETURN SQLGetDiagRec(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLCHAR *       SQLState,  
     SQLINTEGER *    NativeErrorPtr,  
     SQLCHAR *       MessageText,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   TextLengthPtr);  

3.31.3.参数

• HandleType

  [输入]一个句柄类型标识符，描述需要诊断的句柄的类型。必须是下列选项之一：

  • SQL_HANDLE_DBC

  • SQL_HANDLE_DBC_INFO_TOKEN

  • SQL_HANDLE_DESC

  • SQL_HANDLE_ENV

  • SQL_HANDLE_STMT

  SQL_HANDLE_DBC_INFO_TOKEN句柄仅由驱动程序管理器和驱动程序使用。应用程序不应使用此句柄类型。

• Handle

  [输入]诊断数据结构的句柄，其类型由HandleType来指出。如果HandleType是SQL_HANDLE_ENV，Handle可以是共享的或非共享的环境句柄。

• RecNumber

  [输入]指示应用程序从中查找信息的状态记录。状态记录从1开始编号。

• SQLState

  [输出]指向缓冲区的指针，该缓冲区存储着有关RecNumber的五字符的SQLSTATE码。

• NativeErrorPtr

  [输出]指向缓冲区的指针，该缓冲区用于返回特定于数据源的本机错误代码。此信息包含在 SQL_DIAG_NATIVE诊断字段中。

• MessageText

  [输出]指向要返回诊断消息文本字符串的缓冲区的指针。此信息包含在 SQL_DIAG_MESSAGE_TEXT诊断字段中。

• BufferLength

  [输入]*MessageText的长度。

• TextLengthPtr

  [输出]指向缓冲区的指针，返回MessageText中的字节总数。如果返回字节数大于BufferLength，则MessageText中的诊断信息文本被截断成BufferLength减去NULL结尾字符的长度。

3.31.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。

3.31.5.诊断

• SQL_SUCCESS：函数已成功返回诊断信息。

• SQL_SUCCESS_WITH_INFO：* MessageText 缓冲区太小，无法容纳请求的诊断消息。未生成任何诊断记录。若要确定是否发生了截断，应用程序必须将 BufferLength 与可用的实际字节数（写入 *TextLengthPtr）进行比较。

• SQL_INVALID_HANDLE： HandleType 和句柄指示的句柄不是有效的句柄。

• SQL_ERROR：发生以下情况之一：

• RecNumber 为负数或0。

• BufferLength 小于零。

• 使用异步通知时，句柄上的异步操作不完整。

• SQL_NO_DATA：RecNumber 大于在 handle中指定的句柄所存在的诊断记录数。如果没有适用于句柄的诊断记录，该函数还将为任何正RecNumber 返回 SQL_NO_DATA。

3.32.SQLGetFunctions

3.32.1.功能描述

SQLGetFunctions返回有关驱动程序是否支持特定 ODBC函数的信息。此函数在驱动程序管理器中实现，还可以在驱动程序中实现。如果驱动程序实现SQLGetFunctions，驱动程序管理器将调用驱动程序中的函数；否则它将执行函数本身。

3.32.2.语法

SQLRETURN SQLGetFunctions(  
     SQLHDBC           ConnectionHandle,  
     SQLUSMALLINT      FunctionId,  
     SQLUSMALLINT *    SupportedPtr);  

3.32.3.参数

• ConnectionHandle

  [输入]连接句柄。

• FunctionId

  [输入]函数标识 #define ODBC函数的一个值；SQL_API_ODBC3_ALL_FUNCTIONS 或SQL_API_ALL_FUNCTIONS。

• SupportedPtr

  [输出]函数指针如果FunctionId标识单个ODBC函数，SupportedPtr将指向单个SQLUSMALLINT值SQL_TRUE，如果驱动程序支持指定函数，则指向SQL_FALSE。

  如果FunctionId SQL_API_ODBC3_ALL_FUNCTIONS，SupportedPtr将指向一个SQLSMALLINT数组，该数组具有多个等于SQL_API_ODBC3_ALL_FUNCTIONS_SIZE。如果为FunctionId SQL_API_ALL_FUNCTIONS，SupportedPtr将指向包含100个元素的SQLUSMALLINT数组。该数组由FunctionId #define 标识每个ODBC函数的一些索引;数组的一些元素未使用并保留供将来使用。

  如果SQL_FALSE标识驱动程序不支持的 ODBC 函数，或者未标识 ODBC 函数，则不支持此参数。

  SupportedPtr 中返回的数组使用从零开始编制索引。

3.32.4.返回值

SQL_SUCCESS SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

3.32.5.诊断

当 SQLGetFunctions 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用具有SQL_HANDLE_DBC 的 HandleType 和 ConnectionHandle 句柄的 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了 SQLGetFunctions 通常返回的 SQLSTATE值，并说明了此函数上下文中的每个值；标注为“(DM)” 位于驱动程序管理器返回的 SQLSTATEs说明之前。除非另有说明，否则将与每个 SQLSTATE 值关联的返回代码是SQL_ERROR。

SQLGetFunctions 诊断代码

3.33.SQLGetInfo

3.33.1.功能描述

SQLGetInfo返回与连接关联的驱动程序和数据源的常规信息。

3.33.2.语法

SQLRETURN SQLGetInfo(  
     SQLHDBC         ConnectionHandle,  
     SQLUSMALLINT    InfoType,  
     SQLPOINTER      InfoValuePtr,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLengthPtr);  

3.33.3.参数

• ConnectionHandle

  [输入]连接句柄。

• InfoType

  [输入]信息类型。

• InfoValuePtr

  [输出]一个缓冲区的指针，此缓冲区用于存放返回的信息。根据请求的 InfoType， 返回的信息将是下列信息之一：以 null结尾的字符串、SQLUSMALLINT 值、SQLUINTEGER 位掩码、SQLUINTEGER标志、SQLUINTEGER 二进制值或 SQLULEN 值。

  如果 InfoType 参数是SQL_DRIVER_HDESC或SQL_DRIVER_HSTMT， 则 InfoValuePtr参数既是输入参数，也是输出参数。

  如果 InfoValuePtr 为 NULL，则 StringLengthPtr 将返回总字节数 (不包括字符数据)，在InfoValuePtr 指向的缓冲区中返回的字符数据 null 终止字符。

• BufferLength

  [输入]* InfoValuePtr缓冲区的长度。如果 * InfoValuePtr中的值不是字符串，或者InfoValuePtr 是 null 指针，则忽略BufferLength 参数。驱动程序假定 * InfoValuePtr 的大小是 SQLUSMALLINT 或SQLUINTEGER，基于 InfoType。如果在调用 SQLGetInfo时，*InfoValuePtr是Unicode字符串，则 BufferLength参数必须是一个偶数；否则，将返回 SQLSTATE HY090(无效的字符串或缓冲区长度) 。

• StringLengthPtr

  [输出]指向缓冲区的指针，此缓冲区用于存放 *InfoValuePtr 中返回的字节总数 （对于字符数据，不包括空值终止字符）。

  对于字符数据，如果可返回的字节数大于或等于 BufferLength，则 *InfoValuePtr 中的信息将截断为BufferLength 字节减去 null 终止字符的长度，并且由驱动程序以 null 终止。

  对于所有其他类型的数据，BufferLength 的值将被忽略，驱动程序假定 * InfoValuePtr 的大小为SQLUSMALLINT 或 SQLUINTEGER，具体取决于 InfoType。

3.33.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。

3.33.5.诊断

当 SQLGetInfo 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用具有SQL_HANDLE_DBC 的 HandleType 和 ConnectionHandle 句柄的 SQLGetDiagRec来获取关联的SQLSTATE 值。下表列出了 SQLGetInfo 通常返回的 SQLSTATE值，并说明了此函数上下文中的每个值；标注为“(DM)”位于驱动程序管理器返回的 SQLSTATEs说明之前。除非另有说明，否则将与每个 SQLSTATE 值关联的返回代码是SQL_ERROR。

SQLGetInfo 诊断代码

3.34.SQLGetTypeInfo

3.34.1.功能描述

SQLGetTypeInfo返回有关数据源支持的数据类型的信息。驱动程序以 SQL结果集的形式返回该信息。数据类型用于数据定义语言（DDL）语句中。

3.34.2.语法

SQLRETURN SQLGetTypeInfo(
  SQLHSTMT      StatementHandle,  
  SQLSMALLINT   DataType);  

3.34.3.参数

• StatementHandle

  [输入]结果集的语句句柄。

• DataType

  [输入]SQL 数据类型，SQL_ALL_TYPES 指定应返回有关所有数据类型的信息。

3.34.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.34.5.诊断

SQLGetTypeInfo 诊断代码

3.35.SQLMoreResults

3.35.1.功能描述

SQLMoreResults确定是否在包含SELECT、UPDATE、INSERT 或 DELETE的语句上提供更多结果，如果是，则对这些结果初始化处理。

3.35.2.语法

SQLRETURN SQLMoreResults(
  SQLHSTMT     StatementHandle);  

3.35.3.参数

• StatementHandle

  [输入]语句句柄。

3.35.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_NO_DATA、SQL_ERROR、SQL_INVALID_HANDLE 或 SQL_PARAM_DATA_AVAILABLE。

3.35.5.诊断

当 SQLMoreResults 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_STMT 和 StatementHandle 的句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了通常由 SQLMoreResults 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为“(DM)”位于驱动程序管理器返回的 SQLSTATEs的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是 SQL_ERROR。

SQLMoreResults 诊断代码

3.36.SQLNativeSql

3.36.1.功能描述

SQLNativeSql返回驱动程序修改的 SQL 字符串。SQLNativeSql 不执行 SQL 语句。

3.36.2.语法

SQLRETURN SQLNativeSql(  
     SQLHDBC        ConnectionHandle,  
     SQLCHAR *      InStatementText,  
     SQLINTEGER     TextLength1,  
     SQLCHAR *      OutStatementText,  
     SQLINTEGER     BufferLength,  
     SQLINTEGER *   TextLength2Ptr);  

3.36.3.参数

• ConnectionHandle

  [输入]连接句柄。

• InStatementText

  [输入]要转换的SQL文本字符串。

• TextLength1

  [输入]InStatementText文本字符串的长度。

• OutStatementText

  [输出]指向缓冲区的指针，该缓冲区用于返回已翻译的 SQL 字符串。

  如果 OutStatementText 为 NULL，则TextLength2Ptr将返回除 null 终止字符以外的字符总数，可在OutStatementText 所指向的缓冲区中返回。

• BufferLength

  [输入]OutStatementText缓冲区中的字符数。如果在调用SQLNativeSqlW时，*InStatementText中返回的值为Unicode字符串，则 BufferLength参数必须是偶数。

• TextLength2Ptr

  [输出]指向缓冲区的指针，将在此缓冲区中返回OutStatementText中的除null终止字符以外的字符总数。如果可返回的字符数大于或等于BufferLength，则 OutStatementText 中的已转换SQL 字符串将截断为 BufferLength 减去null 终止字符的长度。

3.36.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。

3.36.5.诊断

当 SQLNativeSql 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_DBC 和 ConnectionHandle 的句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了通常由 SQLNativeSql 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为“(DM)”位于驱动程序管理器返回的SQLSTATEs 的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是 SQL_ERROR。

SQLNativeSql 诊断代码

3.37.SQLNumParams

3.37.1.功能描述

SQLNumParams返回 SQL 语句中参数的数目。

3.37.2.语法

SQLRETURN SQLNumParams(
  SQLHSTMT        StatementHandle,
  SQLSMALLINT *   ParameterCountPtr);  

3.37.3.参数

• StatementHandle

  [输入]语句句柄。

• ParameterCountPtr

  [输出]指向缓冲区的指针，将在此缓冲区中返回语句中的参数个数。

3.37.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.37.5.诊断

当 SQLNumParams 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_STMT 和 StatementHandle 的句柄调用 SQLGetDiagRec来获取关联SQLSTATE 值。下表列出了通常由 SQLNumParams 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为“(DM)”位于驱动程序管理器返回的SQLSTATEs 的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是 SQL_ERROR。

SQLNumParams 诊断代码

3.38.SQLParamData

3.38.1.功能描述

SQLParamData与SQLPutData一起用于在语句执行时提供参数数据，使用 SQLGetData 检索输出参数数据。

3.38.2.语法

SQLRETURN SQLParamData(
  SQLHSTMT       StatementHandle, 
  SQLPOINTER *   ValuePtrPtr);

3.38.3.参数

• StatementHandle

  [输入]语句句柄。

• ValuePtrPtr

  [输出]指向某个缓冲区的指针，该缓冲区用于返回在 SQLBindParameter 中为参数数据指定的ParameterValuePtr 缓冲区的地址 SQL_DESC_DATA_PTR，或者在 SQLBindCol中为列数据)指定的TargetValuePtr缓冲区的地址。

3.38.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NEED_DATA、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR、SQL_INVALID_HANDLE 或 SQL_PARAM_DATA_AVAILABLE。

3.38.5.诊断

当 SQLParamData 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_STMT 和 StatementHandle 的句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了通常由 SQLParamData 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为“(DM)”位于驱动程序管理器返回的SQLSTATEs 的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是 SQL_ERROR。

SQLParamData 诊断代码

3.39.SQLPrepare

3.39.1.功能描述

SQLPrepare准备要执行的SQL字符串。

3.39.2.语法

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

3.39.3.参数

• StatementHandle

  [输入]语句句柄。

• StatementText

  [输入]SQL文本字符串。

• TextLength

  [输入]*StatementText 的长度（以字节为单位）。

3.39.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.39.5.诊断

当 SQLPrepare 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用具有SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句柄的 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了 SQLPrepare 通常返回的 SQLSTATE值，并说明了此函数上下文中的每个值；标注为“(DM)”位于驱动程序管理器返回的 SQLSTATEs说明之前。除非另有说明，否则将与每个 SQLSTATE 值关联的返回代码是SQL_ERROR。

SQLPrepare 诊断代码

3.40.SQLPrimaryKeys

3.40.1.功能描述

SQLPrimaryKeys返回表主键的列名。驱动程序将信息作为结果集返回。这个函数不支持在单一调用中返回多表的主键。

3.40.2.语法

SQLRETURN SQLPrimaryKeys(  
     SQLHSTMT       StatementHandle,  
     SQLCHAR *      CatalogName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      SchemaName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      TableName,  
     SQLSMALLINT    NameLength3);  

3.40.3.参数

• StatementHandle

  [输入]语句句柄。

• CatalogName

  [输入]目录名称。如果驱动程序支持某些表的目录，但不支持其他表的目录，例如：当驱动程序从不同的DBMS中检索数据时，空字符串("")表示没有目录的表。CatalogName 不能包含字符串搜索模式。

  如果将 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE， 则 CatalogName将被视为标识符，其大小写没有意义。如果为 SQL_FALSE， 则 CatalogName为普通参数；它按字面处理，其大小写显著。

• NameLength1

  [输入]CatalogName 的长度。

• SchemaName

  [输入]模式名称。如果驱动程序支持某些表的模式，但不支持其他表的模式，例如，当驱动程序从不同的 DBMS 中检索数据时，空字符串("") 表示没有模式的表。SchemaName 不能包含字符串搜索模式。

  如果将 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE，则 SchemaName将被视为标识符，其大小写不明显。如果为 SQL_FALSE，则 SchemaName为普通参数；它按字面处理，其大小写不显著。

• NameLength2

  [输入]SchemaName 的长度。

• TableName

  [输入]表名。此参数不能为 null 指针。TableName 不能包含字符串搜索模式。

  如果将 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE，则 TableName将被视为标识符，其大小写没有意义。如果为 SQL_FALSE，则 TableName为普通参数；它按字面处理，其大小写不显著。

• NameLength3

  [输入]TableName 的长度。

3.40.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.40.5.诊断

当 SQLPrimaryKeys 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用具有SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句柄的 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了 SQLPrimaryKeys 通常返回的 SQLSTATE值，并说明了此函数上下文中的每个值；标注为" (DM) "位于驱动程序管理器返回的 SQLSTATEs说明之前。除非另有说明，否则将与每个 SQLSTATE 值关联的返回代码是SQL_ERROR。

SQLPrimaryKeys 诊断代码

3.41.SQLProcedure

3.41.1.功能描述

SQLProcedure返回存储在特定数据源中的过程名称的列表。Procedure是一种通用术语，用于描述可执行对象或可使用输入和输出参数调用的命名实体。

3.41.2.语法

SQLRETURN SQLProcedure(  
     SQLHSTMT       StatementHandle,  
     SQLCHAR *      CatalogName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      SchemaName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      ProcName,  
     SQLSMALLINT    NameLength3);  

3.41.3.参数

• StatementHandle

  [输入]语句句柄。

• CatalogName

  [输入]如果驱动程序为某些表支持目录，而不是其他表目录，例如当驱动程序从不同 Dbms 检索不同 Dbms 的数据时，则空字符串("") 表示这些表没有目录。CatalogName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 CatalogName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 CatalogName是普通参数；它按原义处理，其大小写有意义。

• NameLength1

  [输入]*CatalogName中的字符的长度。

• SchemaName

  [输入]过程模式名称的字符串搜索模式。如果驱动程序支持某些过程的模式，而不支持其他过程的模式，例如当驱动程序从不同 DBMS检索数据时，空字符串( "" ) 表示不具有模式的那些过程。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 SchemaName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 SchemaName为模式值参数；它按原义处理，其大小写有意义。

• NameLength2

  [输入]*SchemaName中的字符的长度。

• ProcName

  [输入]过程名称的字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 ProcName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 ProcName为模式值参数；它按原义处理，其大小写有意义。

• NameLength3

  [输入]*ProcName中的字符的长度。

3.41.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.41.5.诊断

当 SQLProcedure 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_STMT 和 StatementHandle 的句柄调用 SQLGetDiagRec来获取关联的SQLSTATE 值。下表列出了通常由 SQLProcedure 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为 "(DM)" 位于驱动程序管理器返回的SQLSTATEs 的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是 SQL_ERROR。

SQLProcedure 诊断代码

3.42.SQLProcedureColumns

3.42.1.功能描述

SQLProcedureColumns返回输入和输出参数的列表以及组成指定过程的结果集的列。驱动程序将信息作为指定语句的结果集返回。

3.42.2.语法

SQLRETURN SQLProcedureColumns(  
     SQLHSTMT      StatementHandle,  
     SQLCHAR *     CatalogName,  
     SQLSMALLINT   NameLength1,  
     SQLCHAR *     SchemaName,  
     SQLSMALLINT   NameLength2,  
     SQLCHAR *     ProcName,  
     SQLSMALLINT   NameLength3,  
     SQLCHAR *     ColumnName,  
     SQLSMALLINT   NameLength4); 

3.42.3.参数

• StatementHandle

  [输入]语句句柄。

• CatalogName

  [输入]过程目录名称。如果驱动支持某些过程的目录但不支持其他过程的，比如当驱动程序从不同的 DBMS 中检索数据时，一个空串("") 表明这些过程没有目录。CatalogName 不能包含串查找模式。

  如果将 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE，则 CatalogName将被视为标识符，其大小写没有意义。如果为 SQL_FALSE， 则 CatalogName为普通参数；它按字面处理，其大小写显著。

• NameLength1

  [输入]CatalogName 的长度。

• SchemaName

  [输入]过程模式名称的字符串搜索模式。如果驱动程序支持某些过程的模式，而不支持其他过程的，例如，当驱动程序从不同的 DBMS中检索数据时，空字符串 ("") 表示没有模式的过程。

  如果将 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE， 则 SchemaName将被视为标识符，其大小写不明显。如果已 SQL_FALSE，SchemaName是模式值参数；它按字面处理，其大小写显著。

• NameLength2

  [输入]SchemaName 的长度。

• ProcName

  [输入]过程名称的字符串搜索模式。

  如果将 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE， 则 ProcName将被视为标识符，其大小写不明显。如果为 SQL_FALSE， 则 ProcName是模式值参数；它按字面处理，其大小写显著。

• NameLength3

  [输入]ProcName 的长度。

• ColumnName

  [输入]列名的字符串搜索模式。

  如果将 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE，则 ColumnName将被视为标识符，其大小写不显著。如果已 SQL_FALSE，则 ColumnName是模式值参数；它按字面处理，其大小写显著。

• NameLength4

  [输入]ColumnName 的长度。

3.42.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.42.5.诊断

当 SQLProcedureColumns 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO时，可以通过调用具有 SQL_HANDLE_STMT 的 HandleType 和StatementHandle 句柄的 SQLGetDiagRec 来获取关联的 SQLSTATE 值。下表列出了SQLProcedureColumns 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值；标注为" (DM)"位于驱动程序管理器返回的 SQLSTATEs 说明之前。除非另有说明，否则将与每个 SQLSTATE值关联的返回代码是SQL_ERROR。

SQLProcedureColumns 诊断代码

3.43.SQLPutData

3.43.1.功能描述

SQLPutData 允许应用程序在语句执行时将参数或列的数据发送到驱动程序。此函数可用于将字符或二进制数据值以部件形式发送到具有字符、二进制或数据源特定数据类型的列(例如SQL_LONGVARBINARY 或 SQL_LONGVARCHAR 类型的)。SQLPutData 支持绑定到 UnicodeC 数据类型，即使基础驱动程序不支持 Unicode 数据。

3.43.2.语法

SQLRETURN SQLPutData(
  SQLHSTMT     StatementHandle,
  SQLPOINTER   DataPtr,
  SQLLEN       StrLen_or_Ind);  

3.43.3.参数

• StatementHandle

  [输入]语句句柄。

• DataPtr

  [输入]指向包含参数或列的实际数据的缓冲区的指针。数据必须在 C 数据类型，数据类型由 SQLB indParameter(参数数据 ) 或 SQLB indCol(字段数据) 的 ValueType 参数指定。

• StrLen_or_Ind

  [输入]* DataPtr 的长度。指定在调用 SQLPutData时发送的数据量。数据量可能因给定参数或列的每次调用而改变。StrLen_or_Ind，除非满足以下条件之一，否则将忽略此参数：

  • StrLen_or_Ind SQL_NTS SQL_NULL_DATA或SQL_DEFAULT_PARAM。

  • SQLBindParameter 或 SQLBindCol 中指定的 C数据类型SQL_C_CHAR或SQL_C_BINARY。

  • C 数据类型为 SQL_C_DEFAULT，并且指定数据类型的默认 C 数据类型SQL为 SQL_C_CHAR 或SQL_C_BINARY。

对于所有其他类型的 C 数据，如果 StrLen_or_Ind 不是 SQL_NULL_DATA 或SQL_DEFAULT_PARAM，则驱动程序 *DataPtr 缓冲区的大小是使用 ValueType 或 TargetType 指定的C 数据类型的大小，并发送整个数据值。

3.43.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.43.5.诊断

当 SQLPutData 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用具有SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句柄的 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了 SQLPutData 通常返回的 SQLSTATE值，并说明了此函数上下文中的每个值；标注为" (DM) "位于驱动程序管理器返回的 SQLSTATEs说明之前。除非另有说明，否则将与每个 SQLSTATE 值关联的返回代码是SQL_ERROR。

SQLPutData 诊断代码

如果在 SQL 语句中发送参数的数据时调用了 SQLPutData ，则它可以返回调用的函数可返回的任何 SQLSTATE，以执行语句(SQLExecute 或 SQLExecDirect) 。如果在发送使用 SQLBulkOperations更新或添加的列的数据时调用此方法，或者使用 SQLSetPos进行更新，则它可以返回 SQLBulkOperations 或 SQLSetPos 返回的任何 SQLSTATE。

3.44.SQLRowCount

3.44.1.功能描述

SQLRowCount返回受 UPDATE、INSERT 或DELETE 语句影响的行数；SQLBulkOperations 中的SQL_ADD、SQL_UPDATE_BY_BOOKMARK 或 SQL_DELETE_BY_BOOKMARK操作；SQLSetPos 中的 SQL_UPDATE或SQL_DELETE操作。

3.44.2.语法

SQLRETURN SQLRowCount(  
      SQLHSTMT   StatementHandle,  
      SQLLEN *   RowCountPtr); 

3.44.3.参数

• StatementHandle

  [输入]语句句柄。

• RowCountPtr

  [输出]指向要返回字段的缓冲区。对于 UPDATE、INSERT 和 DELETE 语句，对于 SQLBulkOperations中的 SQL_ADD、SQL_UPDATE_BY_BOOKMARK 和 SQL_DELETE_BY_BOOKMARK操作，以及 SQLSetPos 中的 SQL_UPDATE 或 SQL_DELETE 操作 ，RowCountPtr中返回的值是受请求影响的行数；如果受影响的行数不可用，则返回-1。

  调用 SQLExecute、SQLExecDirect、 SQLBulkOperations、SQLSetPos 或SQLMoreResults 时，诊断数据结构的 SQL_DIAG_ROW_COUNT字段设置为字段数，并且字段数以依赖实现的方式缓存。SQLRowCount返回缓存的字段数值。缓存字段数值有效，直到语句句柄设置回已准备或已分配状态、重新执行语句或 调用SQLCloseCursor。请注意，如果在设置 SQL_DIAG_ROW_COUNT字段后调用了函数，则 SQLRowCount 返回的值可能不同于SQL_DIAG_ROW_COUNT 字段中的值，因为任何函数调用都将 SQL_DIAG_ROW_COUNT 字段重置为0。

  对于其他语句和函数，驱动程序可以定义 * RowCountPtr 中返回的值。例如，某些数据源可能在提取行之前返回 SELECT语句或目录函数返回的行数。

注意

在提取结果集之前，许多数据源无法返回行数；为获得最大的互操作性，应用程序不应依赖此行为。

3.44.4.返回值

SQL_SUCCESS SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

3.44.5.诊断

当 SQLRowCount 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用具有SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句柄的 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了 SQLRowCount 通常返回的 SQLSTATE值，并说明了此函数上下文中的每个值；标注为"(DM) "位于驱动程序管理器返回的 SQLSTATEs说明之前。除非另有说明，否则将与每个 SQLSTATE 值关联的返回代码是SQL_ERROR。

SQLRowCount 诊断代码

3.45.SQLSetConnectAttr

3.45.1.功能描述

SQLSetConnectAttr设置控制连接的各项属性。

3.45.2.语法

SQLRETURN SQLSetConnectAttr(
  SQLHDBC       ConnectionHandle,
  SQLINTEGER    Attribute,
  SQLPOINTER    ValuePtr,
  SQLINTEGER    StringLength);  

3.45.3.参数

• ConnectionHandle

  [输入]连接句柄。

• Attribute

  [输入]要设置的属性，在"注释"中列出。

• ValuePtr

  [输入]指向要与属性关联的值的指针。根据 Attribute 的值，ValuePtr 将是无符号整数值，或将指向以 null结尾的字符串。请注意，Attribute 参数的整型类型不能固定长度。

• StringLength

  [输入]如果 Attribute 是 ODBC 定义的属性，并且 ValuePtr 指向字符串或二进制缓冲区，则此参数的长度应为 *ValuePtr。对于字符串数据，此参数应包含字符串中的字节数。

  如果 Attribute 是 ODBC 定义的属性，ValuePtr 是整数，则忽略 StringLength。

  如果 Attribute 是驱动程序定义的属性，则应用程序通过设置 StringLength参数向驱动程序管理器指示属性的性质。StringLength可以具有以下值：

  • 如果 ValuePtr 是指向字符串的指针，则 StringLength 是字符串或字符串SQL_NTS的长度。

  • 如果 ValuePtr是指向二进制缓冲区的指针，则应用程序将SQL_LEN_BINARY_ATTR(LENGTH)宏的结果放置于BufferLength。这会在StringLength 中设置负值。

  • 如果 ValuePtr 是指向字符串或二进制字符串外值的指针，则 StringLength的值应为SQL_IS_POINTER。

  • 如果 ValuePtr 包含固定长度的值，则根据实际情况将StringLength对应设置为SQL_IS_INTEGER 或SQL_IS_UINTEGER。

3.45.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE 或SQL_STILL_EXECUTING。

3.45.5.诊断

当 SQLSetConnectAttr 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，通过设置SQL_HANDLE_DBC 的HandleType和 State memtHandle 的句柄，调用 SQLGetDiagRec，可以获得相应的 SQLSTATE 值。下表列出了 SQLSetConnectAttr 通常返回的 SQLSTATE值，并说明了此函数上下文中的每个值；标注为“(DM)”优先于被驱动管理器返回的 SQLSTATE的描述。除非另有说明，否则将指定与每个 SQLSTATE 值联合返回的代码是SQL_ERROR。

驱动程序可以返回SQL_SUCCESS_WITH_INFO，以提供有关设置选项的结果的信息。

SQLSetConnectAttr 诊断代码

当 Attribute 是语句属性时 ，SQLSetConnectAttr 可以返回 SQLSetStmtAttr 返回的任何SQLSTATEs。

3.46.SQLSetCursorName

3.46.1.功能描述

SQLSetCursorName将游标名称与活动语句相关联。如果应用程序不调用 SQLSetCursorName，则驱动程序将根据需要为处理SQL 语句生成游标名称。

3.46.2.语法

SQLRETURN SQLSetCursorName(
  SQLHSTMT      StatementHandle,
  SQLCHAR *     CursorName,
  SQLSMALLINT   NameLength);

3.46.3.参数

• StatementHandle

  [输入]语句句柄。

• CursorName

  [输入]游标名称。为实现有效处理，游标名称不应在游标名称中包括任何前导空格或尾随空格，并且如果游标名称包含分隔的标识符，则分隔符应作为游标名称中的第一个字符定位。

• NameLength

  [输入] *CursorName中的字符的长度。

3.46.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。

3.46.5.诊断

当 SQLSetCursorName 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_STMT 和 StatementHandle 的句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了通常由 SQLSetCursorName 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为“(DM)”优先于被驱动管理器返回的 SQLSTATE的描述。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是SQL_ERROR。

SQLSetCursorName 诊断代码

3.47.SQLSetDescField

3.47.1.功能描述

SQLSetDescField设置描述符记录的单个字段的值。

3.47.2.语法

SQLRETURN SQLSetDescField(
  SQLHDESC      DescriptorHandle,
  SQLSMALLINT   RecNumber,
  SQLSMALLINT   FieldIdentifier,
  SQLPOINTER    ValuePtr,
  SQLINTEGER    BufferLength);

3.47.3.参数

• DescriptorHandle

  [输入]描述符句柄。

• RecNumber

  [输入]指示包含应用程序要设置的字段的描述符记录。描述符记录从 0 编号，记录编号 0 作为书签记录。对于标头字段，忽略RecNumber 参数。

• FieldIdentifier

  [输入]指示要设置其值的描述符的字段。

• ValuePtr

  [输入]指向包含描述符信息的缓冲区的指针，或整数值。数据类型取决于 FieldIdentifier 的值。如果 ValuePtr是整数值，则它可视为 8 个字节 (SQLLEN) 、4 个字节 (SQLINTEGER) 或 2 个字节(SQLSMALLINT)，具体取决于 FieldIdentifier 参数的值。

• BufferLength

  [输入]如果 FieldIdentifier 是 ODBC 定义的字段，并且 ValuePtr指向字符串或二进制缓冲区，则此参数的长度应为 *ValuePtr。对于字符串数据，此参数应包含字符串中的字节数。

  如果 FieldIdentifier 是 ODBC 定义的字段 ，ValuePtr 是整数，则忽略 BufferLength。

  如果 FieldIdentifier 是驱动程序定义的字段，则应用程序通过设置 BufferLength参数向驱动程序管理器指示字段的性质。BufferLength可以具有以下值：

  • 如果 ValuePtr 是指向字符串的指针，则 BufferLength 是字符串或字符串SQL_NTS的长度。

  • 如果 ValuePtr是指向二进制缓冲区的指针，则应用程序将SQL_LEN_BINARY_ATTR(LENGTH)宏的结果放置于BufferLength。这会在BufferLength 中设置负值。

  • 如果 ValuePtr 是指向除字符串或二进制字符串外的值的指针，则BufferLength 的值是SQL_IS_POINTER数值。

  • 如果 ValuePtr 包含固定长度的值，则根据实际情况，BufferLength 的值可以是 SQL_IS_INTERGER，SQL_IS_UINTEGER，SQL_IS_SMALLINT 或SQL_IS_USMALLINT 。

3.47.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。

3.47.5.诊断

当 SQLSetDescField 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用具有SQL_HANDLE_DESC 的 HandleType 和描述符 Handle 句柄的 SQLGetDiagRec 来获取关联的SQLSTATE 值。下表列出了 SQLSetDescField 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值；标注为"(DM) "优先于驱动程序管理器返回的 SQLSTATEs 描述。除非另有说明，否则与每个 SQLSTATE 值联合返回 SQL_ERROR。

SQLSetDescField 诊断代码

3.48.SQLSetEnvAttr

3.48.1.功能描述

SQLSetEnvAttr设置控制环境的各个方面的属性。

3.48.2.语法

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

3.48.3.参数

• EnvironmentHandle

  [输入]环境句柄。

• Attribute

  [输入]要设置的属性。

• ValuePtr

  [输入]指向要与属性关联的值的指针。ValuePtr 可能是32位整型值，或指向空结束字符串。

• StringLength

  [输入]如果 ValuePtr 指向字符串或二进制缓冲区，则此参数的长度应为 *ValuePtr。对于字符串数据，此参数应包含字符串中的字节数。

  如果将 valueptr 是整数，则将忽略 StringLength 。

3.48.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。

3.48.5.诊断

当 SQLSetEnvAttr 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_ENV 和 EnvironmentHandle 的句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了通常由 SQLSetEnvAttr 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为 "(DM)" 位于驱动程序管理器返回的SQLSTATEs 的说明之前。除非另有说明，否则与每个 SQLSTATE 值联合返回的代码是 SQL_ERROR。如果驱动程序不支持环境属性，则只能在连接时返回此错误。

SQLSetEnvAttr 诊断代码

3.49.SQLSetPos

3.49.1.功能描述

SQLSetPos设置行集的游标位置，并允许应用程序刷新行集的数据或更新、删除结果集内的数据。

3.49.2.语法

SQLRETURN SQLSetPos(
  SQLHSTMT        StatementHandle,
  SQLSETPOSIROW   RowNumber,
  SQLUSMALLINT    Operation,
  SQLUSMALLINT    LockType); 

3.49.3.参数

• StatementHandle

  [输入]语句句柄。

• RowNumber

  [输入]行集内要执行 Operation 参数指定的操作行的位置。如果 RowNumber 为 0，则操作将应用于行集的每一行。

• Operation

  [输入]要执行的操作：SQL_POSITION、SQL_REFRESH、SQL_UPDATE 、SQL_DELETE。

• LockType

  [输入]指示完成 Operation参数指定的操作之后，如何锁定行。

  SQL_LOCK_NO_CHANGE、SQL_LOCK_EXCLUSIVE、SQL_LOCK_UNLOCK。

3.49.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NEED_DATA、SQL_STILL_EXECUTING、SQL_ERROR 或 SQL_INVALID_HANDLE。

3.49.5.诊断

当 SQLSetPos 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可能会通过调用具有SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句柄的 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了 SQLSetPos 通常返回的 SQLSTATE值，并说明了此函数上下文中的每个值；标注为"(DM) "位于驱动程序管理器返回的SQLSTATEs 说明之前。除非另有说明，否则将指定与每个 SQLSTATE 值联合返回的代码是 SQL_ERROR。

对于可以返回 SQL_SUCCESS_WITH_INFO 或 SQL_ERROR (除了 01xxx SQLSTATE)的SQLSTATE），如果多行运算的一行或多行（但不是全部）发生错误，则返回SQL_SUCCESS_WITH_INFO；如果单行操作出错，则返回 SQL_ERROR。

SQLSetPos 诊断代码

3.49.6.RowNumber 参数

RowNumber 参数指定行集内要执行 Operation 参数指定的运算的行数。如果 RowNumber 为0，则操作将应用于行集的每一行。RowNumber 必须是从 0 到行集内行数的值。

注意

在 C 语言中，数组基于0，RowNumber 参数基于 1。例如，若要更新行集的第五行，应用程序将修改数组索引 4 中的行集缓冲区，但指定RowNumber 为 5。

所有操作将光标置于 RowNumber 指定的行上。以下操作需要光标位置：

• 定位的更新和删除语句。

• 对 SQLGetData 的调用。

• 使用 SQL_DELETE、SQL_REFRESH 和 SQL_UPDATE 选项调用 SQLSetPos。

例如，如果对 OPERATION 为 SQL_DELETE 的 SQLSetPos 的调用的 RowNumber 为2，则游标将定位在行集的第二行，该行将被删除。第二行的(SQL_ATTR_ROW_STATUS_PTR 语句属性所指向的)行状态数组中的SQL_ROW_DELETED更改为SQL_ROW_DELETED。

应用程序在调用 SQLSetPos 时可以指定光标位置。通常，它使用 SQL_POSITION 或 SQL_REFRESH 操作调用SQLSetPos， 以在执行定位的更新或删除语句或调用 SQLGetData 之前定位游标。

3.49.7.Operation 参数

Operation 参数支持以下操作。为了确定数据源支持哪些选项，应用程序使用SQL_DYNAMIC_CURSOR_ATTRIBUTES1、SQL_FORWARD_ONLY_CURSOR_ATTRIBUTES1、SQL_KEYSET_CURSOR_ATTRIBUTES1 或 SQL_STATIC_CURSOR_ATTRIBUTES1 信息类型(调用 SQLGetInfo， 具体取决于游标) 。

Operation 参数

3.49.8.LockType 参数

LockType 参数为应用程序提供了一种控制并发的方式。在大多数情况下，支持并发级别和事务的数据源将仅SQL_LOCK_NO_CHANGELockType 参数的默认值。LockType 参数通常仅用于基于文件的支持。

LockType 参数指定执行 SQLSetPos 后行的锁状态。如果驱动程序无法锁定行以执行请求的操作或满足 LockType参数，它将返回 SQL_ERROR 和 SQLSTATE 42000 (语法错误或访问) 。

尽管为单个语句指定了 LockType 参数，但锁对连接上的所有语句具有相同的特权。具体而言，一个连接上的一个语句获取的锁可以通过同一连接上的另一个语句解锁。

通过 SQLSetPos 锁定的行将保持锁定状态，直到应用程序为 LockType 设置为 SQL_LOCK_UNLOCK 的行调用SQLSetPos， 或者直到应用程序使用 SQL_CLOSE 选项为 语句或 SQLFreeStmt 调用 SQLFreeHandle。对于支持事务的驱动程序，当应用程序调用 SQLEndTran 提交或回滚连接 (上的事务时，如果游标在提交或回滚时关闭（如SQLGetInfo) 返回的 SQL_CURSOR_COMMIT_BEHAVIOR 和SQL_CURSOR_ROLLBACK_BEHAVIOR 信息类型所指示的，则通过 SQLSetPos 锁定的行将被解锁。

LockType 参数支持以下类型的锁。若要确定数据源支持哪些锁，应用程序使用SQL_DYNAMIC_CURSOR_ATTRIBUTES1、SQL_FORWARD_ONLY_CURSOR_ATTRIBUTES1、SQL_KEYSET_CURSOR_ATTRIBUTES1 或 SQL_STATIC_CURSOR_ATTRIBUTES1 信息类型(调用 SQLGetInfo， 具体取决于游标类型) 。

LockType 参数锁类型

如果驱动程序支持SQL_LOCK_EXCLUSIVE但不支持SQL_LOCK_UNLOCK，则锁定的行将保持锁定状态，直到发生上一段落中所述的函数调用之一。

如果驱动程序支持 SQL_LOCK_EXCLUSIVE 但不支持SQL_LOCK_UNLOCK，则锁定的行将保持锁定状态，直到应用程序使用SQL_CLOSE 选项为 语句调用 SQLFreeHandle 或 SQLFreeStmt。如果驱动程序支持事务，并且提交或回滚事务时关闭游标，则应用程序将调用SQLEndTran。

对于 SQLSetPos 中的更新和删除操作，应用程序使用 LockType 参数，如下所示：

• 为了保证行在检索后不会更改，应用程序调用 SQLSetPos， 将 Operation 设置为 SQL_REFRESH LockType 设置为 SQL_LOCK_EXCLUSIVE。

• 如果应用程序将 LockType SQL_LOCK_NO_CHANGE，则驱动程序保证只有在为SQL_ATTR_CONCURRENCY 语句属性指定的应用程序SQL_CONCUR_LOCK更新或删除操作才成功。

• 如果应用程序为 SQL_ATTR_CONCURRENCY 语句属性指定 SQL_CONCUR_ROWVER 或SQL_CONCUR_VALUES，则驱动程序将比较行版本或值，如果该行自应用程序提取行后已更改，则拒绝该操作。

• 如果应用程序为 SQL_CONCUR_READ_ONLY指定SQL_ATTR_CONCURRENCY，驱动程序将拒绝任何更新或删除操作。

有关语句属性SQL_ATTR_CONCURRENCY，请参见SQLSetStmtAttr。

3.50.SQLSetStmtAttr

3.50.1.功能描述

SQLSetStmtAttr设置与语句相关的属性。

3.50.2.语法

SQLRETURN SQLSetStmtAttr(
  SQLHSTMT      StatementHandle,
  SQLINTEGER    Attribute,
  SQLPOINTER    ValuePtr,
  SQLINTEGER    StringLength); 

3.50.3.参数

• StatementHandle

  [输入]语句句柄。

• Attribute

  [输入]要设置的选项。

• ValuePtr

  [输入]要与属性关联的值。根据 Attribute 的值，ValuePtr 将是下列值之一：

  • ODBC 描述符句柄。

  • SQLUINTEGER 值。

  • SQLULEN 值。

  • 指向以下项之一的指针：

  • 以 null 结尾的字符串。

  • 二进制缓冲区。

  • SQLLEN、SQLULEN 或 SQLUSMALLINT 类型的值或数组。

  • 驱动程序定义的值。

  如果 Attribute 参数是特定于驱动程序的值，则 ValuePtr 可能是有符号整数。

• StringLength

  [输入]如果 Attribute是 ODBC 定义的属性，并且 ValuePtr 指向字符串或二进制缓冲区，则此参数应为*ValuePtr 的长度。如果 Attribute 是 ODBC 定义的属性，ValuePtr 是整数，则忽略StringLength。

  • 如果 Attribute 是驱动程序定义的属性，则应用程序通过设置 StringLength参数向驱动程序管理器指示属性的性质。StringLength可以具有以下值：

  • 如果 ValuePtr 是指向字符串的指针，则 StringLength 是字符串或字符串SQL_NTS的长度。

  • 如果 ValuePtr是指向二进制缓冲区的指针，则应用程序将SQL_LEN_BINARY_ATTR(LENGTH)宏的结果放置于BufferLength。这会在StringLength 中设置负值。

  • 如果 ValuePtr 是指向字符串或二进制字符串外值的指针，则 StringLength的值应SQL_IS_POINTER。

  • 如果 ValuePtr 包含固定长度的值，根据实际情况，StringLength的值是 SQL_IS_INTEGER或SQL_IS_UINTEGER。

3.50.4.返回值

SQL_SUCCESS SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

3.50.5.诊断

当 SQLSetStmtAttr 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可能通过调用具有SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句柄的 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了 SQLSetStmtAttr 通常返回的 SQLSTATE值，并说明了此函数上下文中的每个值；标注为"(DM)"位于驱动程序管理器返回的 SQLSTATEs说明之前。除非另有说明，否则与每个 SQLSTATE 值联合返回的代码是 SQL_ERROR。

SQLSetStmtAttr 诊断代码

3.51.SQLSpecialColumns

3.51.1.功能描述

SQLSpecialColumns检索有关指定表中的列的下列信息：

• 唯一标识表中行的一组最佳列。

• 当事务更新行中的任何值时，自动更新的列。

3.51.2.语法

SQLRETURN SQLSpecialColumns(
  SQLHSTMT      StatementHandle, 
  SQLSMALLINT   IdentifierType,
  SQLCHAR *     CatalogName,
  SQLSMALLINT   NameLength1,
  SQLCHAR *     SchemaName,
  SQLSMALLINT   NameLength2,
  SQLCHAR *     TableName,
  SQLSMALLINT   NameLength3,
  SQLSMALLINT   Scope,
  SQLSMALLINT   Nullable); 

3.51.3.参数

• StatementHandle

  [输入]语句句柄。

• IdentifierType

  [输入]要返回的列的类型。必须是以下值之一：

  • SQL_BEST_ROWID：通过从一列或多列检索值来返回最优列或一组列，允许唯一标识指定表中的任何行。列可以是专门为此目的而设计的伪列 (如 Oracle ROWID 或 Ingres TID) 或表的任何唯一索引的一个或多个列。

  • SQL_ROWVER：返回指定表中的一个或多个列（如果有），当任何事务更新行中的任何值时，该列或列将由数据源自动更新， (如SQLBase ROWID 或 Sybase TIMESTAMP) 中所示。

• CatalogName

  [输入]表的目录名称。如果驱动程序为某些表（而不是其他表）支持目录，例如当驱动程序从不同 DBMS检索数据时（例如，当驱动程序检索不同 DBMS的数据时），则空字符串 ("") 表示这些表没有目录。CatalogName不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 CatalogName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 CatalogName是普通参数；它按原义处理，其大小写有意义。

• NameLength1

  [输入]*CatalogName中的字符的长度。

• SchemaName

  [输入]表的模式名称。如果驱动程序支持某些表的模式，而不支持其他表的模式（例如，当驱动程序从不同 DBMS 检索数据时），则空字符串("") 表示不具有模式的那些表。SchemaName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 SchemaName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 SchemaName是普通参数；它按原义处理，其大小写有意义。

• NameLength2

  [输入]*SchemaName中的字符的长度。

• TableName

  [输入]表名称。此参数不能为 null 指针。TableName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 TableName将被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 TableName为普通参数；它按原义处理，其大小写有意义。

• NameLength3

  [输入]*TableName的长度。

• Scope

  [输入]Rowid 所需的最小范围。返回的 rowid 的作用域可能更大。必须是下列选项之一：

  • SQL_SCOPE_CURROW：仅当定位在该行上时，rowid 才能保证有效。如果行已由其他事务更新或删除，则以后使用rowid 重新选择的可能不会返回一行。

  • SQL_SCOPE_TRANSACTION：保证 rowid 在当前事务的持续时间内有效。

  • SQL_SCOPE_SESSION：保证 rowid 在会话的持续时间内保持有效()的事务边界。

• Nullable

  [输入]确定是否返回可以具有 NULL 值的特殊列。必须是下列选项之一：

  • SQL_NO_NULLS：排除可以具有 NULL 值的特殊列。某些驱动程序无法支持 SQL_NO_NULLS，如果指定SQL_NO_NULLS，则这些驱动程序将返回空结果集。应用程序应为此情况做好准备，并且仅当绝对需要时才请求SQL_NO_NULLS。

  • SQL_NULLABLE：返回特殊列，即使它们可以具有 NULL 值也是如此。

3.51.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.51.5.诊断

当 SQLSpecialColumns 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_STMT 和 StatementHandle 的句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了通常由 SQLSpecialColumns 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为"(DM)"位于驱动程序管理器返回的 SQLSTATEs的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码为SQL_ERROR。

SQLSpecialColumns 诊断代码

3.52.SQLStatistics

3.52.1.功能描述

SQLStatistics 检索与表相关联的单个表和索引的统计信息列表。驱动程序将以结果集的形式返回该信息。

3.52.2.语法

SQLRETURN SQLStatistics(
  SQLHSTMT        StatementHandle,
  SQLCHAR *       CatalogName,
  SQLSMALLINT     NameLength1,
  SQLCHAR *       SchemaName,
  SQLSMALLINT     NameLength2,
  SQLCHAR *       TableName,
  SQLSMALLINT     NameLength3,
  SQLUSMALLINT    Unique,
  SQLUSMALLINT    Reserved); 

3.52.3.参数

• StatementHandle

  [输入]语句句柄。

• CatalogName

  [输入]目录名称。如果驱动程序为某些表（而不是其他表）支持目录，例如当驱动程序从不同 DBMS 检索数据时（例如，当驱动程序检索不同DBMS 的数据时），则空字符串( "" ) 指示这些表没有目录。CatalogName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 CatalogName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 CatalogName是普通参数；它按原义处理，其大小写有意义。

• NameLength1

  [输入]*CatalogName中的字符的长度。

• SchemaName

  [输入]模式名称。如果驱动程序支持某些表的模式，而不支持其他表的模式（例如，当驱动程序从不同 DBMS 检索数据时），则空字符串 ("") 指示不具有模式的那些表。SchemaName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 SchemaName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 SchemaName是普通参数；它按原义处理，其大小写有意义。

• NameLength2

  [输入]*SchemaName中的字符的长度。

• TableName

  [输入]表名称。此参数不能为 null 指针。SchemaName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 TableName将被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 TableName为普通参数；它按原义处理，其大小写有意义。

• NameLength3

  [输入]*TableName的长度。

• Unique

  [输入]索引的类型：SQL_INDEX_UNIQUE 或 SQL_INDEX_ALL。

• Reserved

  [输入]指示结果集中基数列和页列的重要性。以下选项只影响基数列和页列的返回值;即使未返回基数和页，也会返回索引信息。

  SQL_ENSURE 请求驱动程序无条件检索统计信息。仅符合开放组标准且不支持 ODBC 扩展的 (驱动程序将不能支持SQL_ENSURE。)

  SQL_QUICK 请求，驱动程序仅在服务器可轻松使用时才检索基数和页面。在这种情况下，驱动程序不能保证是最新值。

3.52.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.52.5.诊断

当 SQLStatistics 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_STMT 和 StatementHandle 的句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了通常由 SQLStatistics 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为 "(DM)" 位于驱动程序管理器返回的SQLSTATEs 的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是 SQL_ERROR。

SQLStatistics 诊断代码

3.53.SQLTablePrivileges

3.53.1.功能描述

SQLTablePrivileges返回表列表和与每个表关联的权限。驱动程序将该信息作为指定语句的结果集返回。

3.53.2.语法

SQLRETURN SQLTablePrivileges(
  SQLHSTMT      StatementHandle,
  SQLCHAR *     CatalogName,
  SQLSMALLINT   NameLength1,
  SQLCHAR *     SchemaName,
  SQLSMALLINT   NameLength2,
  SQLCHAR *     TableName,
  SQLSMALLINT   NameLength3); 

3.53.3.参数

• StatementHandle

  [输入]语句句柄。

• CatalogName

  [输入]表目录。如果驱动程序为某些表（而不是其他表）支持目录，例如当驱动程序从不同 DBMS 检索数据时（例如，当驱动程序检索不同DBMS 的数据时），则空字符串 ( "" ) 表示这些表没有目录。CatalogName 不能包含字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 CatalogName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 CatalogName是普通参数；它按原义处理，其大小写有意义。

• NameLength1

  [输入]*CatalogName中的字符的长度。

• SchemaName

  [输入]模式名称的字符串搜索模式。如果驱动程序支持某些表的模式，而不支持其他表的模式（例如，当驱动程序从不同 DBMS检索数据时），则空字符串( "" )表示不具有模式的那些表。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 SchemaName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 SchemaName为模式值参数；它按原义处理，其大小写有意义。

• NameLength2

  [输入]*SchemaName中的字符的长度。

• TableName

  [输入]表名的字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 TableName将被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 TableName为模式值参数；它按原义处理，其大小写有意义。

• NameLength3

  [输入]*TableName的长度。

3.53.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.53.5.诊断

当 SQLTablePrivileges 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用HandleType 的 SQL_HANDLE_STMT 和 StatementHandle 的句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了通常由 SQLTablePrivileges 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为 "(DM)" 位于驱动程序管理器返回的 SQLSTATEs的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是 SQL_ERROR。

SQLTablePrivileges 诊断代码

3.54.SQLTables

3.54.1.功能描述

SQLTables返回存储在特定数据源中的表、目录或模式名称以及表类型的列表。驱动程序将以结果集的形式返回该信息。

3.54.2.语法

SQLRETURN SQLTables(
  SQLHSTMT       StatementHandle,
  SQLCHAR *      CatalogName,
  SQLSMALLINT    NameLength1,
  SQLCHAR *      SchemaName,
  SQLSMALLINT    NameLength2,
  SQLCHAR *      TableName,
  SQLSMALLINT    NameLength3,
  SQLCHAR *      TableType,
  SQLSMALLINT    NameLength4); 

3.54.3.参数

• StatementHandle

  [输入]检索结果的语句句柄。

• CatalogName

  [输入]表的目录名。如果SQL_ODBC_VERSION环境属性SQL_OV_ODBC3，则CatalogName参数接受搜索模式;如果设置了SQL_OV_ODBC2，则它不接受搜索模式。如果驱动程序支持某些表目录，但不支持其他表的目录，例如当驱动程序从不同DBMS检索数据时，空字符串( "" )表示那些没有目录的表。

  如果SQL_ATTR_METADATA_ID语句属性设置为SQL_TRUE，则 CatalogName被视为标识符，其大小写没有意义。如果SQL_FALSE，则 CatalogName为模式值参数；按照字面意思处理处理，并且它的大小写是有意义的。

• NameLength1

  [输入]*CatalogName中的字符的长度。

• SchemaName

  [输入]模式名称的字符串搜索模式。如果驱动程序支持某些表的模式，而不支持其他表的模式（例如，当驱动程序从不同 DBMS检索数据时），则空字符串("")指示不具有模式的那些表。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 SchemaName被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 SchemaName为模式值参数；它按原义处理，其大小写有意义。

• NameLength2

  [输入]*SchemaName中的字符的长度。

• TableName

  [输入]表名的字符串搜索模式。

  如果 SQL_ATTR_METADATA_ID 语句特性设置为 SQL_TRUE，则 TableName将被视为标识符，并且其大小写无意义。如果 SQL_FALSE，则 TableName为模式值参数；它按原义处理，其大小写有意义。

• NameLength3

  [输入]*TableName的长度。

• TableType

  [输入]要匹配的表类型的列表。

  请注意，SQL_ATTR_METADATA_ID 语句特性对 TableType 参数无效。TableType是一个值列表参数，而不考虑 SQL_ATTR_METADATA_ID 的设置。

• NameLength4

  [输入]*TableType的长度。

3.54.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.54.5.诊断

当 SQLTables 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用 HandleType的 SQL_HANDLE_STMT 和 StatementHandle 的句柄调用 SQLGetDiagRec 来获取关联的SQLSTATE 值。下表列出了通常由 SQLTables 返回的 SQLSTATE值，并对该函数的上下文中的每个值进行了说明：标注为“(DM)”位于驱动程序管理器返回的 SQLSTATEs 的说明之前。除非另有说明，否则与每个 SQLSTATE 值相关联的返回代码是SQL_ERROR。

SQLTables 诊断代码

3.55.SQLGetConnectAttr

3.55.1.功能描述

SQLGetConnectAttr返回连接属性的当前设置。

3.55.2.语法

SQLRETURN SQLGetConnectAttr(
  SQLHDBC        ConnectionHandle,
  SQLINTEGER     Attribute,
  SQLPOINTER     ValuePtr,
  SQLINTEGER     BufferLength,
  SQLINTEGER *   StringLengthPtr);

3.55.3.参数

• ConnectionHandle

  [输入]连接句柄。

• Attribute

  [输入]要检索的属性。

• ValuePtr

  [输出]指向内存的指针，在内存中返回由 Attribute 指定的属性的当前值。对于整数类型属性，某些驱动程序可能只写入缓冲区的低32 位或 16 位，并保留高序位不变。因此，应用程序应在调用此函数之前使用 SQLULEN 的缓冲区，将值初始化为 0。

  如果 ValuePtr 为 NULL，则 StringLengthPtr 仍将返回总字节数 (不包括字符数据 null 终止字符) 可在ValuePtr 指向的缓冲区中返回。

• BufferLength

  [输入]如果 Attribute 是 ODBC 定义的属性，并且 ValuePtr 指向字符串或二进制缓冲区，则此参数应为 *ValuePtr 的长度。如果 Attribute 是 ODBC 定义的属性， *ValuePtr 是整数，则忽略BufferLength。如果 *ValuePtr 中的值为 Unicode 字符串， (调用 SQLGetConnectAttrW)时，BufferLength 参数必须是一个偶数。

  如果 Attribute 是驱动程序定义的属性，则应用程序通过设置 BufferLength参数向驱动程序管理器指示属性的性质。BufferLength可以具有以下值：

  • 如果 *ValuePtr 是指向字符串的指针，则 BufferLength 是字符串或SQL_NTS 的长度。

  • 如果 *ValuePtr是指向二进制缓冲区的指针，则应用程序将SQL_LEN_BINARY_ATTR(LENGTH)宏的结果放置于BufferLength。这会在 BufferLength 中设置负值。

  • 如果 *ValuePtr 是指向字符串或二进制字符串外值的指针，则 BufferLength的值是SQL_IS_POINTER。

  • 如果 *ValuePtr 包含固定长度的数据类型，BufferLength视实际而定为 SQL_IS_INTEGER或SQL_IS_UINTEGER的值。

• StringLengthPtr

  [输出]指向缓冲区的指针，在缓冲区中返回的字节总数 (Null 终止字符) *ValuePtr 中返回。如果属性值是字符串，并且可返回的字节数大于 BufferLength 减去 null终止字符的长度，则 *ValuePtr 中的数据将截断为 BufferLength 减去 null 终止字符的长度，并且驱动程序以null 结尾。

3.55.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR 或SQL_INVALID_HANDLE。

3.55.5.诊断

当 SQLGetConnectAttr 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用具有SQL_HANDLE_DBC 的HandleType 和 ConnectionHandle 句柄的 SQLGetDiagRec，从诊断数据结构获取关联的 SQLSTATE 值。下表列出了 SQLGetConnectAttr 通常返回的SQLSTATE 值，并说明了此函数上下文中的每个值；标注为"(DM) "位于驱动程序管理器返回的 SQLSTATEs 说明之前。除非另有说明，否则将指定与每个 SQLSTATE 值关联的返回代码是SQL_ERROR。

SQLGetConnectAttr 诊断代码

3.56.SQLGetEnvAttr

3.56.1.功能描述

SQLGetEnvAttrr返回环境属性的当前设置。

3.56.2.语法

SQLRETURN SQLGetEnvAttr(
  SQLHENV        EnvironmentHandle,
  SQLINTEGER     Attribute,
  SQLPOINTER     ValuePtr,
  SQLINTEGER     BufferLength,
  SQLINTEGER *   StringLengthPtr);  

3.56.3.参数

• EnvironmentHandle

  [输入]环境句柄。

• Attribute

  [输入]要检索的属性。

• ValuePtr

  [输出]指向缓冲区的指针，该缓冲区返回由 Attribute 指定的特性的当前值。

  如果 ValuePtr 为 NULL，则 StringLengthPtr 仍将返回总字节数 (不包括字符数据 null 终止字符)可在ValuePtr 指向的缓冲区中返回。

• BufferLength

  [输入]如果 ValuePtr 指向字符串，则此参数的长度应为 *ValuePtr。如果 *ValuePtr 是整数，则忽略BufferLength。如果 *ValuePtr 是一个 Unicode 字符串(调用 SQLGetEnvAttrW)时，BufferLength 参数必须是一个偶数。如果属性值不是字符串，则不使用 BufferLength。

• StringLengthPtr

  [输出]一个指向缓冲区的指针，在缓冲区中返回的字节总数 (null 终止字符) *ValuePtr 中返回。如果属性值是字符串，并且可返回的字节数大于或等于 BufferLength，则ValuePtr 中的数据将截断为 * BufferLength 减去 null 终止字符的长度，并且驱动程序以 null 结尾。

3.56.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR 或SQL_INVALID_HANDLE。

3.56.5.诊断

当 SQLGetEnvAttr 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用具有SQL_HANDLE_ENV 的 HandleType 和 EnvironmentHandle 句柄的 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了 SQLGetEnvAttr 通常返回的 SQLSTATE值，并说明了此函数上下文中的每个值；标注为" (DM) "位于驱动程序管理器返回的 SQLSTATEs说明之前。除非另有说明，否则将与每个 SQLSTATE 值关联的返回代码是SQL_ERROR。

SQLGetEnvAttr 诊断代码

3.57.SQLGetStmtAttr

3.57.1.功能描述

SQLGetStmtAttr返回语句属性的当前设置。

3.57.2.语法

SQLRETURN SQLGetStmtAttr(
  SQLHSTMT        StatementHandle,
  SQLINTEGER      Attribute,
  SQLPOINTER      ValuePtr,
  SQLINTEGER      BufferLength,
  SQLINTEGER *    StringLengthPtr);  

3.57.3.参数

• StatementHandle

  [输入]语句句柄。

• Attribut

  [输入]要检索的属性。

• ValuePtr

  [输出]指向缓冲区的指针，在缓冲区中返回 Attribute 中指定的属性的值。

  如果 ValuePtr 为 NULL， 则 StringLengthPtr 仍将返回总字节数(不包括字符数据 null 终止字符) 可在ValuePtr 指向的缓冲区中返回。

• BufferLength

  [输入]如果 Attribute 是 ODBC 定义的属性，并且 ValuePtr 指向字符串或二进制缓冲区，则此参数应为 *ValuePtr 的长度。如果 Attribute 是 ODBC 定义的属性， *ValuePtr 是整数，则忽略BufferLength。如果在调用 SQLGetStmtAttrW ( *ValuePtr 中返回的值是 Unicode 字符串，)BufferLength 参数必须是一个偶数。

  如果 Attribute 是驱动程序定义的属性，则应用程序通过设置 BufferLength参数向驱动程序管理器指示属性的性质。BufferLength可以具有以下值：

  • 如果 *ValuePtr 是指向字符串的指针，则BufferLength 参数就应是字符串或字符串SQL_NTS的长度。

  • 如果 *ValuePtr是指向二进制缓冲区的指针，则应用程序将SQL_LEN_BINARY_ATTR(LENGTH)宏的结果放置于BufferLength。这会在 BufferLength 中设置负值。

  • 如果 *ValuePtr 是指向字符串或二进制字符串外值的指针，则 BufferLength的值是SQL_IS_POINTER。

  • 如果 *ValuePtr 包含固定长度的数据类型，则 BufferLengthSQL_IS_INTEGER或SQL_IS_UINTEGER值。

• StringLengthPtr

  [输出]指向缓冲区的指针，在该缓冲区中存放 *ValuePtr中可返回的字节总数（不包括空终止字符）。如果ValuePtr是空指针，则不返回长度。如果属性值是字符串，并且可返回的字节数大于或等于BufferLength， *ValuePtr中的数据将被截断为BufferLength减去空终止字符的长度，并由驱动程序以空字符结尾。

3.57.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。

3.57.5.诊断

当 SQLGetStmtAttr 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，通过调用具有SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句柄的SQLGetDiagRec，可以获得关联的 SQLSTATE 值。下表列出了 SQLGetStmtAttr通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;标注为" (DM) "位于驱动程序管理器返回的SQLSTATEs 说明之前。除非另有说明，否则将与每个 SQLSTATE 值关联的返回代码是SQL_ERROR。

SQLGetStmtAttr 诊断代码

3.58.SQLNumResultCols

3.58.1.功能描述

SQLNumResultCols返回结果集的列数。

3.58.2.语法

SQLRETURN SQLNumResultCols(
  SQLHSTMT        StatementHandle,  
  SQLSMALLINT *   ColumnCountPtr);  

3.58.3.参数

• StatementHandle

  [输入]语句句柄。

• ColumnCountPtr

  [输出]指向要返回结果集内列数的缓冲区的指针。此计数不包括绑定书签列。

3.58.4.返回值

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或SQL_INVALID_HANDLE。

3.58.5.诊断

当 SQLNumResultCols 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用具有SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句柄的 SQLGetDiagRec来获取关联的 SQLSTATE 值。下表列出了 SQLNumResultCols 通常返回的 SQLSTATE值，并说明了此函数上下文中的每个值;标注为" (DM) "位于驱动程序管理器返回的 SQLSTATEs 说明之前。除非另有说明，否则将与每个 SQLSTATE 值关联的返回代码是SQL_ERROR。

SQLNumResultCols 诊断代码

当在 SQLPrepare 之前且在 SQLExecute 之后调用 SQLNumResultCols 时，SQLNumResultCols都可以返回SQLPrepare 或 SQLExecute 返回的任何 SQLSTATE ，具体取决于数据源何时计算与关联的SQL语句。

4.ODBC特性约束

4.1.数据类型的转换

• 列类型到C数据类型的转换

  调用SQLBindCol和SQLGetData时可以参照该表。

  如果表的列定义为某种类型，那么当调用SQLGetData或者SQLBindCol时，TargeType参数只能是该数据类型对应的一行中填有"Y"的C数据类型。

  例：当表中的列定义为date，那么调用SQLGetData或者SQLBindCol时，TargetType参数就可以是SQL_C_DEFAULT，SQL_C_CHAR，SQL_C_DATE，SQL_C_TIME，SQL_C_TIMESTAMP，而不能是SQL_C_TINYINT。

  注意

  如果应用程序在SQLBindCol、SQLGetData或SQLBindParameter中指定SQL_C_DEFAULT，则驱动程序假定输出或输入缓冲区的C数据类型对应于缓冲区绑定到的列或参数的数据类型。应用程序不应使用SQL_C_DEFAULT。相反，它们应始终指定所使用的缓冲区的C类型。驱动程序无法确定列或参数的原始SQL数据类型。因此，它无法确定相应的默认C数据类型。

  列类型转换C数据类型_1

  C数据类型	表中的列定义
  	SMALLINT	INTEGER	BIGINT	NUMERIC DECIMAL	FLOAT4 REAL	DOUBLE
  SQL_C_DEFAULT	Y	Y	Y	Y	Y	Y
  SQL_C_CHAR	Y	Y	Y	Y	Y	Y
  SQL_C_STINYINT	Y	Y	Y	Y	Y	Y
  SQL_C_TINYINT	Y	Y	Y	Y	Y	Y
  SQL_C_UTINYINT	Y	Y	Y	Y	Y	Y
  SQL_C_SSHORT	Y	Y	Y	Y	Y	Y
  SQL_C_SHORT	Y	Y	Y	Y	Y	Y
  SQL_C_USHORT	Y	Y	Y	Y	Y	Y
  SQL_C_SLONG	Y	Y	Y	Y	Y	Y
  SQL_C_LONG	Y	Y	Y	Y	Y	Y
  SQL_C_ULONG	Y	Y	Y	Y	Y	Y
  SQL_C_SBIGINT	Y	Y	Y	Y	Y	Y
  SQL_C_UBIGINT	Y	Y	Y	Y	Y	Y
  SQL_C_FLOAT	Y	Y	Y	Y	Y	Y
  SQL_C_DOUBLE	Y	Y	Y	Y	Y	Y
  SQL_C_BINARY
  SQL_C_BIT
  SQL_C_DATE
  SQL_C_TIME
  SQL_C_TIMESTAMP

  列类型转换C数据类型_2

  C数据类型	表中的列定义
  	BIT	BYTEA	BOOL BOOLEAN	DATE TIME TIMESTAMP INTERVAL	CHAR VARCHAR	TEXT
  SQL_C_DEFAULT				Y	Y	Y
  SQL_C_CHAR				Y	Y	Y
  SQL_C_STINYINT
  SQL_C_TINYINT
  SQL_C_UTINYINT
  SQL_C_SSHORT
  SQL_C_SHORT
  SQL_C_USHORT
  SQL_C_SLONG
  SQL_C_LONG
  SQL_C_ULONG
  SQL_C_SBIGINT
  SQL_C_UBIGINT
  SQL_C_FLOAT
  SQL_C_DOUBLE
  SQL_C_BINARY		Y
  SQL_C_BIT	Y		Y
  SQL_C_DATE				Y	Y
  SQL_C_TIME				Y	Y
  SQL_C_TIMESTAMP				Y	Y

• C数据类型到SQL数据类型的转换

  调用SQLBindParameter时可以参照该表。

  如果绑定参数的ValueType为某种C数据类型，那么当调用SQLBindParameter时，ParameterType参数只能是该C数据类型对应的一列中填有"Y"的SQL数据类型。

  例：如果绑定参数的ValueType为SQL_C_CHAR，那么调用SQLBindParameter时，ParameterType参数就可以是SQL_CHAR，SQL_VARCHAR，SQL_LONGVARCHAR，而不能是SQL_DECIMAL。

  C数据类型到SQL数据类型的转换_1

  C数据类型	SQL数据类型
  	SQL_DECIMAL SQL_NUMERIC	SQL_TINYINT SQL_SMALLINT SQL_BIGINT	SQL_INTEGER	SQL_REAL SQL_FLOAT SQL_DOUBLE	SQL_BINARY SQL_VARBINARY SQL_LONGVARBINARY
  SQL_C_DEFAULT	Y	Y	Y	Y	Y
  SQL_C_CHAR
  SQL_C_STINYINT	Y	Y	Y	Y
  SQL_C_TINYINT	Y	Y	Y	Y
  SQL_C_UTINYINT	Y	Y	Y	Y
  SQL_C_SSHORT	Y	Y	Y	Y
  SQL_C_SHORT	Y	Y	Y	Y
  SQL_C_USHORT	Y	Y	Y	Y
  SQL_C_SLONG	Y	Y	Y	Y
  SQL_C_LONG	Y	Y	Y	Y
  SQL_C_ULONG	Y	Y	Y	Y
  SQL_C_SBIGINT	Y	Y	Y	Y
  SQL_C_UBIGINT	Y	Y	Y	Y
  SQL_C_FLOAT	Y	Y		Y
  SQL_C_DOUBLE	Y	Y	Y	Y
  SQL_C_BINARY					Y
  SQL_C_BIT
  SQL_C_DATE
  SQL_C_TIME
  SQL_C_TIMESTAMP

  C数据类型到SQL数据类型的转换_2

  C数据类型	SQL数据类型
  	SQL_CHAR SQL_VARCHAR	SQL_LONGVARCHAR	SQL_BIT	SQL_TYPE_DATE SQL_TYPE_TIME SQL_TYPE_TIMESTAMP
  SQL_C_DEFAULT	Y	Y	Y	Y
  SQL_C_CHAR	Y	Y
  SQL_C_STINYINT	Y
  SQL_C_TINYINT	Y
  SQL_C_UTINYINT	Y
  SQL_C_SSHORT	Y
  SQL_C_SHORT	Y
  SQL_C_USHORT	Y
  SQL_C_SLONG	Y
  SQL_C_LONG	Y
  SQL_C_ULONG	Y
  SQL_C_SBIGINT	Y
  SQL_C_UBIGINT	Y
  SQL_C_FLOAT	Y
  SQL_C_DOUBLE	Y
  SQL_C_BINARY
  SQL_C_BIT			Y
  SQL_C_DATE	Y			Y
  SQL_C_TIME	Y			Y
  SQL_C_TIMESTAMP	Y			Y

• 列类型到SQL数据类型的映射

  下表列出了调用SQLBindParameter时表中的列定义数据类型与SQL类型的对应关系。

  当表中的数据类型定义为第一列的某种类型，那么当调用SQLBindParameter时，ParameterType只能为其对应行中的第二列的值。如：表中的列类型为INTEGER(INT)，那么对应的SQL数据类型只能为SQL_INTEGER，而不能为其它的SQL数据类型，否则数据转化将会出错。

  列定义数据类型与SQL类型的对应关系

  表中的列定义	可转换为如下SQL数据类型
  SMALLINT	SQL_SMALLINT
  INTEGER	SQL_INTEGER
  BIGINT	SQL_BIGINT
  NUMERIC DECIMAL	SQL_NUMERIC SQL_DECIMAL
  FLOAT4 REAL	SQL_REAL
  FLOAT8 DOUBLE	SQL_FLOAT SQL_DOUBLE
  BYTEA	SQL_BINARY SQL_VARBINARY
  BOOL BOOLEAN	SQL_BIT
  DATE	SQL_DATE SQL_TYPE_DATE
  TIME	SQL_TIME SQL_TYPE_TIME
  TIMESTAMP TIMESTAMPTZ	SQL_TIMESTAMP SQL_TYPE_TIMESTAMP
  INTERVAL	SQL_INTERVAL_MONTH SQL_INTERVAL_YEAR SQL_INTERVAL_YEAR_TO_MONTH SQL_INTERVAL_DAY SQL_INTERVAL_HOUR SQL_INTERVAL_MINUTE SQL_INTERVAL_SECOND SQL_INTERVAL_DAY_TO_HOUR SQL_INTERVAL_DAY_TO_MINUTE SQL_INTERVAL_DAY_TO_SECOND SQL_INTERVAL_HOUR_TO_MINUTE SQL_INTERVAL_HOUR_TO_SECOND SQL_INTERVAL_MINUTE_TO_SECOND
  CHAR VARCHAR	SQL_CHAR SQL_VARCHAR
  TEXT	SQL_LONGVARCHAR
  UUID	SQL_GUID