华为云用户手册

  • 获取发布包、依赖库和头文件 libpq依赖的库和头文件从发布包中获取,包名为 GaussDB -Kernel-数据库版本号-操作系统版本号-64bit-Libpq.tar.gz。其中include文件夹下的头文件为所需的头文件,lib文件夹中为所需的libpq库文件。使用libpq的程序必须包括头文件“libpq-fe.h”并且必须与libpq库连接。 除libpq-fe.h外,include文件夹下默认还存在头文件postgres_ext.h、gs_thread.h、gs_threadlocal.h,这三个头文件是libpq-fe.h的依赖文件。 父主题: 开发步骤
  • 参数 表1 SQLSetStmtAttr参数 关键字 参数说明 StatementHandle 语句句柄。 Attribute 需设置的属性。 ValuePtr 指向对应Attribute的值。依赖于Attribute的值,ValuePtr可能是32位无符号整型值,或指向以空结束的字符串,二进制缓冲区,或者驱动定义值。注意,如果ValuePtr参数是驱动程序指定值。ValuePtr可能是有符号的整数。 StringLength 如果ValuePtr指向字符串或二进制缓冲区,这个参数是*ValuePtr长度,如果ValuePtr指向整型,忽略StringLength。
  • 原型 1 2 3 4 SQLRETURN SQLSetStmtAttr(SQLHSTMT StatementHandle SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER StringLength);
  • 参数 表1 SQLSetEnvAttr参数 关键字 参数说明 EnvironmentHandle 环境句柄。 Attribute 需设置的环境属性,可为如下值: SQL_ATTR_ODBC_VERSION:指定ODBC版本。 SQL_CONNECTION_POOLING:连接池属性。 SQL_OUTPUT_NTS:指明驱动器返回字符串的形式。 ValuePtr 指向对应Attribute的值。依赖于Attribute的值,ValuePtr可能是32位整型值,或为以空结束的字符串。 StringLength 如果ValuePtr指向字符串或二进制缓冲区,这个参数是*ValuePtr长度,如果ValuePtr指向整型,忽略StringLength。
  • 原型 1 2 3 4 SQLRETURN SQLSetEnvAttr(SQLHENV EnvironmentHandle SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER StringLength);
  • 参数 表1 SQLSetConnectAttr参数 关键字 参数说明 ConnectionHandle 连接句柄。 Attribute 设置属性。 ValuePtr 指向对应Attribute的值。依赖于Attribute的值,ValuePtr是32位无符号整型值或指向以空结束的字符串。注意,如果ValuePtr参数是驱动程序指定值。ValuePtr可能是有符号的整数。 StringLength 如果ValuePtr指向字符串或二进制缓冲区,这个参数是*ValuePtr长度,如果ValuePtr指向整型,忽略StringLength。
  • 原型 1 2 3 4 SQLRETURN SQLSetConnectAttr(SQLHDBC ConnectionHandle SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER StringLength);
  • 参数 表1 SQLGetDiagRec参数 关键字 参数说明 HandleType 句柄类型标识符,它说明诊断所要求的句柄类型。必须为下列值之一: SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT SQL_HANDLE_DESC Handle 诊断数据结构的句柄,其类型由HandleType来指出。如果HandleType是SQL_HANDLE_ENV,Handle可以是共享的或非共享的环境句柄。 RecNumber 指出应用从查找信息的状态记录。状态记录从1开始编号。 SQLState 输出参数:指向缓冲区的指针,该缓冲区存储着有关RecNumber的五字符的SQLSTATE码。 NativeErrorPtr 输出参数:指向缓冲区的指针,该缓冲区存储着本地的错误码。 MessageText 指向缓冲区的指针,该缓冲区存储着诊断信息文本串。 BufferLength MessageText的长度。 TextLengthPtr 输出参数:指向缓冲区的指针,返回MessageText中的字节总数。如果返回字节数大于BufferLength,则MessageText中的诊断信息文本被截断成BufferLength减去NULL结尾字符的长度。
  • 注意事项 SQLGetDiagRec不发布自己的诊断记录。它用下列返回值来报告它自己的执行结果: SQL_SUC CES S:函数成功返回诊断信息。 SQL_SUCCESS_WITH_INFO:MessageText太小以致不能容纳所请求的诊断信息。没有诊断记录生成。 SQL_INVALID_HANDLE:由HandType和Handle所指出的句柄是不合法句柄。 SQL_ERROR:RecNumber小于等于0或BufferLength小于0。 如果调用ODBC函数返回SQL_ERROR或SQL_SUCCESS_WITH_INFO,可调用SQLGetDiagRec返回诊断信息值SQLSTATE,SQLSTATE值的如下表。 表2 SQLSTATE值 SQLSATATE 错误 描述 HY000 一般错误 未定义特定的SQLSTATE所产生的一个错误。 HY001 内存分配错误 驱动程序不能分配所需要的内存来支持函数的执行或完成。 HY008 取消操作 调用SQLCancel取消执行语句后,依然在StatementHandle上调用函数。 HY010 函数系列错误 在为执行中的所有数据参数或列发送数据前就调用了执行函数。 HY013 内存管理错误 不能处理函数调用,可能由当前内存条件差引起。 HYT01 连接超时 数据源响应请求之前,连接超时。 IM001 驱动程序不支持此函数 调用了StatementHandle相关的驱动程序不支持的函数
  • 原型 1 2 3 4 5 6 7 8 SQLRETURN SQLGetDiagRec(SQLSMALLINT HandleType SQLHANDLE Handle, SQLSMALLINT RecNumber, SQLCHAR *SQLState, SQLINTEGER *NativeErrorPtr, SQLCHAR *MessageText, SQLSMALLINT BufferLength SQLSMALLINT *TextLengthPtr);
  • 原型 1 2 3 4 5 6 SQLRETURN SQLGetData(SQLHSTMT StatementHandle, SQLUSMALLINT Col_or_Param_Num, SQLSMALLINT TargetType, SQLPOINTER TargetValuePtr, SQLLEN BufferLength, SQLLEN *StrLen_or_IndPtr);
  • 参数 表1 SQLGetData参数 关键字 参数说明 StatementHandle 语句句柄,通过SQLAllocHandle获得。 Col_or_Param_Num 要返回数据的列号。结果集的列按增序从1开始编号。书签列的列号为0。 TargetType TargetValuePtr缓冲中的C数据类型的类型标识符。若TargetType为SQL_ARD_TYPE,驱动使用ARD中SQL_DESC_CONCISE_TYPE字段的类型标识符。若为SQL_C_DEFAULT,驱动根据源的SQL数据类型选择缺省的数据类型。 TargetValuePtr 输出参数:指向返回数据所在缓冲区的指针。 BufferLength TargetValuePtr所指向缓冲区的长度。 StrLen_or_IndPtr 输出参数:指向缓冲区的指针,在此缓冲区中返回长度或标识符的值。
  • 参数 表1 SQLFreeHandle参数 关键字 参数说明 HandleType SQLFreeHandle要释放的句柄类型。必须为下列值之一: SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT SQL_HANDLE_DESC 如果HandleType不是这些值之一,SQLFreeHandle返回SQL_INVALID_HANDLE。 Handle 要释放的句柄。
  • 返回值 SQL_SUCCESS:表示调用正确。 SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 SQL_NEED_DATA:表示在执行SQL语句前没有提供足够的参数。 SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 SQL_NO_DATA:表示SQL语句不返回结果集。 SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 SQL_STILL_EXECUTING:表示语句正在执行。
  • 返回值 SQL_SUCCESS:表示调用正确。 SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 SQL_NEED_DATA:在执行SQL语句前没有提供足够的参数。 SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 SQL_STILL_EXECUTING:表示语句正在执行。 SQL_NO_DATA:表示SQL语句不返回结果集。
  • 原型 1 2 3 4 5 6 7 SQLRETURN SQLConnect(SQLHDBC ConnectionHandle, SQLCHAR *ServerName, SQLSMALLINT NameLength1, SQLCHAR *UserName, SQLSMALLINT NameLength2, SQLCHAR *Authentication, SQLSMALLINT NameLength3);
  • 参数 表1 SQLConnect参数 关键字 参数说明 ConnectionHandle 连接句柄,通过SQLAllocHandle获得。 ServerName 要连接数据源的名称。 NameLength1 ServerName的长度。 UserName 数据源中数据库用户名。 NameLength2 UserName的长度。 Authentication 数据源中数据库用户密码。 NameLength3 Authentication的长度。
  • 参数 表1 SQLColAttribute参数 关键字 参数说明 StatementHandle 语句句柄。 ColumnNumber 要检索字段的列号,起始为1,依次递增。 FieldIdentifier IRD中ColumnNumber行的字段。 CharacterAttributePtr 输出参数:一个缓冲区指针,返回FieldIdentifier字段值。 BufferLength 如果FieldIdentifier是一个ODBC定义的字段,而且CharacterAttributePtr指向一个字符串或二进制缓冲区,则此参数为该缓冲区的长度。 如果FieldIdentifier是一个ODBC定义的字段,而且CharacterAttributePtr指向一个整数,则会忽略该字段。 StringLengthPtr 输出参数:缓冲区指针,存放*CharacterAttributePtr中字符类型数据的字节总数,对于非字符类型,忽略BufferLength的值。 NumericAttributePtr 输出参数:指向一个整型缓冲区的指针,返回IRD中ColumnNumber行FieldIdentifier字段的值。
  • 原型 1 2 3 4 5 6 7 SQLRETURN SQLColAttibute(SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLUSMALLINT FieldIdentifier, SQLPOINTER CharacterAtrriburePtr, SQLSMALLINT BufferLength, SQLSMALLINT *StringLengthPtr, SQLLEN *NumericAttributePtr);
  • 参数 表1 SQLBindParameter 关键词 参数说明 StatementHandle 语句句柄。 ParameterNumber 参数序号,起始为1,依次递增。 InputOutputType 输入输出参数类型。 ValueType 参数的C数据类型。 ParameterType 参数的SQL数据类型。 ColumnSize 列的大小或相应参数标记的表达式。 DecimalDigits 列的十进制数字或相应参数标记的表达式。 ParameterValuePtr 指向存储参数数据缓冲区的指针。 BufferLength ParameterValuePtr指向缓冲区的长度,以字节为单位。 StrLen_or_IndPtr 缓冲区的长度或指示器指针。若为空值,则未使用任何长度或指示器值。
  • 原型 1 2 3 4 5 6 7 8 9 10 SQLRETURN SQLBindParameter(SQLHSTMT StatementHandle, SQLUSMALLINT ParameterNumber, SQLSMALLINT InputOutputType, SQLSMALLINT ValuetType, SQLSMALLINT ParameterType, SQLULEN ColumnSize, SQLSMALLINT DecimalDigits, SQLPOINTER ParameterValuePtr, SQLLEN BufferLength, SQLLEN *StrLen_or_IndPtr);
  • 原型 1 2 3 4 5 6 SQLRETURN SQLBindCol(SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLSMALLINT TargetType, SQLPOINTER TargetValuePtr, SQLLEN BufferLength, SQLLEN *StrLen_or_IndPtr);
  • 参数 表1 SQLBindCol参数 关键字 参数说明 StatementHandle 语句句柄。 ColumnNumber 要绑定结果集的列号。起始列号为0,以递增的顺序计算列号,第0列是书签列。若未设置书签页,则起始列号为1。 TargetType 缓冲区中C数据类型的标识符。 TargetValuePtr 输出参数:指向与列绑定的数据缓冲区的指针。SQLFetch函数返回这个缓冲区中的数据。如果此参数为一个空指针,则StrLen_or_IndPtr是一个有效值。 BufferLength TargetValuePtr指向缓冲区的长度,以字节为单位。 StrLen_or_IndPtr 输出参数:缓冲区的长度或指示器指针。若为空值,则未使用任何长度或指示器值。
  • 参数 表1 SQLAllocHandle参数 关键字 参数说明 HandleType 由SQLAllocHandle分配的句柄类型。必须为下列值之一: SQL_HANDLE_ENV(环境句柄) SQL_HANDLE_DBC(连接句柄) SQL_HANDLE_STMT(语句句柄) SQL_HANDLE_DESC(描述句柄) 申请句柄顺序为,先申请环境句柄,再申请连接句柄,最后申请语句句柄,后申请的句柄都要依赖它前面申请的句柄。 InputHandle 将要分配的新句柄的类型。 如果HandleType为SQL_HANDLE_ENV,则这个值为SQL_NULL_HANDLE。 如果HandleType为SQL_HANDLE_DBC,则这一定是一个环境句柄。 如果HandleType为SQL_HANDLE_STMT或SQL_HANDLE_DESC,则它一定是一个连接句柄。 OutputHandlePtr 输出参数:一个缓冲区的指针,此缓冲区以新分配的数据结构存放返回的句柄。
  • 注意事项 当分配的句柄并非环境句柄时,如果SQLAllocHandle返回的值为SQL_ERROR,则它会将OutputHandlePtr的值设置为SQL_NULL_HDBC、SQL_NULL_HSTMT或SQL_NULL_HDESC。之后,通过调用带有适当参数的SQLGetDiagRec,其中HandleType和Handle被设置为IntputHandle的值,可得到相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。
  • ODBC接口参考 ODBC接口是一套提供给用户的API函数,本节将对部分常用接口做具体描述,若涉及其他接口可参考msdn(网址:https://msdn.microsoft.com/en-us/library/windows/desktop/ms714177(v=vs.85).aspx)中ODBC Programmer's Reference项的相关内容。 SQLAllocEnv SQLAllocConnect SQLAllocHandle SQLAllocStmt SQLBindCol SQLBindParameter SQLColAttribute SQLConnect SQLDisconnect SQLExecDirect SQLExecute SQLFetch SQLFreeStmt SQLFreeConnect SQLFreeHandle SQLFreeEnv SQLPrepare SQLGetData SQLGetDiagRec SQLSetConnectAttr SQLSetEnvAttr SQLSetStmtAttr 父主题: 基于ODBC开发
  • 关闭连接 ODBC关闭数据库连接,释放资源相关API如表1所示。 表1 相关API说明 功能 API 断开与数据源的连接 SQLDisconnect 释放句柄资源 SQLFreeHandle:释放句柄资源,可替代如下函数: SQLFreeEnv:释放环境句柄 SQLFreeConnect:释放连接句柄 SQLFreeStmt:释放语句句柄 示例如下(完整示例请参考获取和处理数据库中的数据): // 断开数据源连接并释放句柄资源。 SQLFreeHandle(SQL_HANDLE_STMT,V_OD_hstmt); SQLDisconnect(V_OD_hdbc); SQLFreeHandle(SQL_HANDLE_DBC,V_OD_hdbc); SQLFreeHandle(SQL_HANDLE_ENV, V_OD_Env); 父主题: 开发步骤
  • 处理结果集 ODBC处理结果集是从数据库中获取数据并将其提供给应用程序进行处理,作用包括但不限于:检索数据、数据展示、数据处理、数据传输和业务逻辑实现等。 ODBC提供处理结果集的相关API如表1所示。 表1 相关API说明 功能 API 绑定缓冲区到结果集的列中 SQLBindCol 结果集中取行集 SQLFetch 返回结果集中某一列的数据 SQLGetData 获取结果集中列的描述信息 SQLColAttribute 查看最近一次操作错误信息 SQLGetDiagRec 示例如下(完整示例请参考获取和处理数据库中的数据): // 在执行完成SQL语句后,获取结果集某一列的属性。 SQLColAttribute(V_OD_hstmt,1,SQL_DESC_TYPE,typename,100,NULL,NULL); printf("SQLColAtrribute %s\n",typename); // 绑定结果集。 SQLBindCol(V_OD_hstmt,1,SQL_C_SLONG, (SQLPOINTER)&V_OD_buffer,150, (SQLLEN *)&V_OD_err); // 通过SQLFetch取结果集中数据。 V_OD_erg=SQLFetch(V_OD_hstmt); // 通过SQLGetData获取并返回数据。 while(V_OD_erg != SQL_NO_DATA) { SQLGetData(V_OD_hstmt,1,SQL_C_SLONG,(SQLPOINTER)&V_OD_id,0,NULL); printf("SQLGetData ----ID = %d\n",V_OD_id); V_OD_erg=SQLFetch(V_OD_hstmt); }; printf("Done !\n"); 父主题: 开发步骤
  • 执行SQL语句 为了帮助用户实现与数据库的交互,ODBC提供执行SQL语句的相关API如表1所示。 表1 相关API说明 功能 API 设置语句属性 SQLSetStmtAttr 为执行SQL语句做准备 SQLPrepare 执行一条准备好的SQL语句 SQLExecute 绑定SQL语句的参数标志和缓冲区 SQLBindParameter 直接执行SQL语句 SQLExecDirect ODBC为应用程序与数据库的中心层,负责把应用程序发出的SQL指令传到数据库当中,自身并不解析SQL语法。故在应用程序中写入带有保密信息的SQL语句时(如明文密码),保密信息会被暴露在驱动日志中。 数据库中收到的一次执行请求(不在事务块中),如果含有多条语句,将会被打包成一个事务,如果其中有一个语句失败,那么整个请求都将会被回滚。 示例如下(完整示例请参考获取和处理数据库中的数据): // 设置语句属性。 SQLSetStmtAttr(V_OD_hstmt, SQL_ATTR_QUERY_TIMEOUT, (SQLPOINTER *)3, 0); // 申请语句句柄。 SQLAllocHandle(SQL_HANDLE_STMT, V_OD_hdbc, &V_OD_hstmt); // 直接执行SQL语句。 SQLExecDirect(V_OD_hstmt, "drop table IF EXISTS customer_t1", SQL_NTS); SQLExecDirect(V_OD_hstmt, "CREATE TABLE customer_t1(c_customer_sk INTEGER, c_customer_name VARCHAR(32));", SQL_NTS); SQLExecDirect(V_OD_hstmt, "insert into customer_t1 values(25, 'li')", SQL_NTS); // 准备执行。 SQLPrepare(V_OD_hstmt, "insert into customer_t1 values(?)", SQL_NTS); // 绑定参数。 SQLBindParameter(V_OD_hstmt,1, SQL_PA RAM _INPUT, SQL_C_SLONG, SQL_INTEGER, 0, 0, &value, 0, NULL); // 执行准备好的语句。 SQLExecute(V_OD_hstmt); SQLExecDirect(V_OD_hstmt, "select c_customer_sk from customer_t1", SQL_NTS); 父主题: 开发步骤
  • 连接数据库涉及的API 在测试连接数据库成功后,ODBC API提供了一组函数来连接数据库,如表1所示。 表1 相关API说明 功能 API 申请句柄资源 SQLAllocHandle:申请句柄资源,可替代如下函数: SQLAllocEnv:申请环境句柄 SQLAllocConnect:申请连接句柄 SQLAllocStmt:申请语句句柄 设置环境属性 SQLSetEnvAttr 设置连接属性 SQLSetConnectAttr 连接数据库 SQLConnect 以开发源程序DBtest.c为例(完整示例请参考获取和处理数据库中的数据): 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 // DBtest.c (compile with: libodbc.so) // 程序头文件和全局变量请参考完整示例 // 申请环境句柄。 V_OD_erg = SQLAllocHandle(SQL_HANDLE_ENV,SQL_NULL_HANDLE,&V_OD_Env); if ((V_OD_erg != SQL_SUCCESS) && (V_OD_erg != SQL_SUCCESS_WITH_INFO)) { printf("Error AllocHandle\n"); exit(0); } // 设置版本信息(环境属性)。 SQLSetEnvAttr(V_OD_Env, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, 0); // 申请连接句柄 。 V_OD_erg = SQLAllocHandle(SQL_HANDLE_DBC, V_OD_Env, &V_OD_hdbc); if ((V_OD_erg != SQL_SUCCESS) && (V_OD_erg != SQL_SUCCESS_WITH_INFO)) { SQLFreeHandle(SQL_HANDLE_ENV, V_OD_Env); exit(0); } // 获取用户名和用户密码。 char *userName; userName = getenv("EXAMPLE_USERNAME_ENV"); char *password; password = getenv("EXAMPLE_PASSWORD_ENV"); // 设置连接属性。 SQLSetConnectAttr(V_OD_hdbc, SQL_ATTR_AUTOCOMMIT,(SQLPOINTER *)SQL_AUTOCOMMIT_ON, 0); // 连接数据库,这里的userName与password分别表示连接数据库的用户名和用户密码。 // 如果odbc.ini文件中已经配置了用户名密码,那么这里可以留空("");但是不建议这么做,因为一旦odbc.ini权限管理不善,将导致数据库用户密码泄露。 V_OD_erg = SQLConnect(V_OD_hdbc, (SQLCHAR*) "MPPODBC", SQL_NTS, (SQLCHAR*) userName, SQL_NTS, (SQLCHAR*) password, SQL_NTS); if ((V_OD_erg != SQL_SUCCESS) && (V_OD_erg != SQL_SUCCESS_WITH_INFO)) { printf("Error SQLConnect %d\n",V_OD_erg); SQLFreeHandle(SQL_HANDLE_ENV, V_OD_Env); exit(0); } printf("Connected !\n"); 父主题: 连接数据库
共100000条