句柄管理¶
句柄类型¶
句柄¶
句柄本质是一个结构，结构的成员被ACI隐藏，开发者不需要关心句柄结构中具体成员，因此句柄的内存分配和释放只能通过ACI接口进行。ACI支持的句柄如下：
| 句柄类型 | C语言类型 | 描述 | 父句柄 | 神通支持情况 |
|---|---|---|---|---|
| ACI_HTYPE_ENV | ACIEnv | 环境句柄 | 无 | 支持 |
| ACI_HTYPE_ERROR | ACIError | 错误句柄 | ACI_HTYPE_ENV | 支持 |
| ACI_HTYPE_SVCCTX | ACISvcCtx | 服务上下文句柄 | ACI_HTYPE_ENV | 支持 |
| ACI_HTYPE_STMT | ACIStmt | 语句句柄 | ACI_HTYPE_ENV | 支持 |
| ACI_HTYPE_BIND | ACIBind | 绑定句柄 | ACI_HTYPE_STMT | 支持 |
| ACI_HTYPE_DEFINE | ACIDefine | 定义句柄 | ACI_HTYPE_STMT | 支持 |
| ACI_HTYPE_DESCRIBE | ACIDescribe | 描述句柄 | ACI_HTYPE_ENV | 支持 |
| ACI_HTYPE_SERVER | ACIServer | 服务器句柄 | ACI_HTYPE_ENV | 支持 |
| ACI_HTYPE_SESSION | ACISession | 会话句柄 | ACI_HTYPE_ENV | 支持 |
| ACI_HTYPE_CPOOL | ACICPool | 连接池句柄 | ACI_HTYPE_ENV | 支持 |
| ACI_HTYPE_SPOOL | ACISPool | 会话池句柄 | ACI_HTYPE_ENV | 支持 |
| ACI_HTYPE_AUTHINFO | ACIAuthInfo | 认证信息句柄 | ACI_HTYPE_ENV | 支持 |
| ACI_HTYPE_BULKIMP | ACIHIMP | MPP数据加载句柄 | ACI_HTYPE_ENV | 支持 |
| ACI_HTYPE_BULK | ACIBulk | 数据库加载句柄 | ACI_HTYPE_ENV | 支持 |
| ACI_HTYPE_DIRPATH_CTX | ACIDirPathCtx | 直接路径加载上下文句柄 | ACI_HTYPE_ENV | 支持 |
| ACI_HTYPE_DIRPATH_COLUMN_ARRAY | ACIDirPathColArray | 直接路径加载列数组句柄 | ACI_HTYPE_DIRPATH_CTX | 支持 |
| ACI_HTYPE_DIRPATH_STREAM | ACIDirPathStream | 直接路径加载流句柄 | ACI_HTYPE_DIRPATH_CTX | 支持 |
| ACI_HTYPE_TRANS | ACITrans | 事务句柄 | ACI_HTYPE_ENV | 支持 |
ACI接口的句柄和描述符等数据结构需要指定的函数来分配，有些句柄是在函数调用中显式分配的，有一些结构是隐式分配的：
使用大部分句柄时需要显式分配 ACIHandleAlloc ，同时需要显式释放 ACIHandleFree ；而ACI_HTYPE_BIND和ACI_HTYPE_DEFINE这两种句柄，是隐式分配的，使用者不需要关心句柄结构的内存申请和释放。
上下文句柄及关联¶
ACI_HTYPE_SVCCTX上下文句柄用于与数据库服务端进行操作所需，它包含三个句柄，分别为：ACI_HTYPE_SERVER和ACI_HTYPE_SESSION及ACI_HTYPE_TRANS。
服务器句柄标识与数据库的物理网络连接，用于数据的网络传输；
用户句柄：定义用户的角色和权限；
事务句柄：定义在其中执行SQL操作的事务。
语句，绑定，定义句柄及关联¶
语句句柄是执行SQL或PL / SQL语句及其关联属性的结构，包含SQL参数信息、描述信息、结果集信息等，包含定义句柄和绑定句柄：
绑定句柄：存储输入(参数)和输出(out 参数)类型变量的绑定变量信息；ACI在调用 ACIBindByName 、 ACIBindByPos 为SQL语句中每个占位符分配一个绑定句柄；用户不得分配绑定句柄，它们由bind调用隐式分配。
定义句柄：根据绑定的变量类型，从查询结果中将数据转换到绑定变量中。 ACI库为使用 ACIDefineByPos 、 ACIDefineByPos2 定义的每个输出变量分配一个定义句柄，用户不得分配定义句柄，它们由define调用隐式分配。
显式分配绑定或定义句柄可能会导致内存泄漏。显式释放绑定或定义句柄可能会导致程序异常终止。
连接池句柄及关联¶
连接池句柄用于通过调用ACI函数将物理连接池化为虚拟连接的应用程序。通过连接池，可设置连接池的最小值，最大值、增长值等内容。
描述符¶
描述符主要用于复杂数据类型的存储和处理，神通数据库目前支持的句柄如下：
| 句柄类型 | C语言类型 | 描述 | 父句柄 |
|---|---|---|---|
| ACI_DTYPE_DATE | ACIDateTime | 时间日期描述符 | ACI_HTYPE_ENV |
| ACI_DTYPE_TIMESTAMP | ACIDateTime | 时间戳描述符 | ACI_HTYPE_ENV |
| ACI_DTYPE_TIMESTAMP_TZ | ACIDateTime | 带时区的时间戳描述符 | ACI_HTYPE_ENV |
| ACI_DTYPE_TIMESTAMP_LTZ | ACIDateTime | 本地时区的时间戳描述符 | ACI_HTYPE_ENV |
| ACI_DTYPE_INTERVAL_YM | ACIInterval | YM时间间隔描述符 | ACI_HTYPE_ENV |
| ACI_DTYPE_INTERVAL_DS | ACIInterval | DS时间间隔描述符 | ACI_HTYPE_ENV |
| ACI_DTYPE_LOB | ACILobLocator | 大对象描述符 | ACI_HTYPE_ENV |
| ACI_DTYPE_FILE | ACILobLocator | bfile文件描述符 | ACI_HTYPE_ENV |
| ACI_DTYPE_PARAM | ACIParam | 参数描述符 | 无 |
| ACI_DTYPE_JSON | ACIJson | Json描述符 | ACI_HTYPE_ENV |
| ACI_DTYPE_ROWID | ACIRowid | Rowid描述符 | ACI_HTYPE_ENV |
LOB和BFILE描述符¶
大对象（LOB）是一种神通数据库的数据类型，可以保存二进制大对象（BLOB）或字符大对象（CLOB）数据。在数据库中，LOB的地址称为定位器存储在数据库行的LOB列中，或存储在对象的LOB属性中。定位器充当指向实际LOB值的指针，该LOB值存储在单独的位置。ACI中的LOB和BFILE描述符用于存储lob的定位器，用户lob数据的操作。
ACI LOB定位器用于对LOB（BLOB或CLOB）或FILE（BFILE）执行ACI操作。 ACILobXXX函数采用LOB定位器参数而不是LOB值。 ACI LOB函数不使用实际的LOB数据作为参数。 他们将LOB定位器用作参数，并对它们引用的LOB数据进行操作。
通过传递ACI_DTYPE_LOB作为BLOB或CLOB的类型参数，传递ACI_DTYPE_FILE作为BFILE的LOB定位器，可以调用 ACIDescriptorAlloc 。
备注：根据您的应用程序，您可以为CLOB列绑定或定义字符数据，或者为BLOB列绑定或定义RAW数据，不一定用定位器的方式来操作大对象。
参数描述符¶
ACI应用程序使用参数描述符获取有关选择列表列或架构对象的信息。此信息是通过describe操作获得的。
参数描述符是唯一不使用 ACIDescriptorAlloc 分配的描述符类型。通过使用 ACIParamGet 调用从ACI_HTYPE_DESCRIBE描述句柄中获得指定位置的参数。
时间相关描述符¶
date，datetime、timestap、和interval描述符由使用日期，日期时间或间隔数据类型（ACIDate，ACIDateTime和ACIInterval）的应用程序使用。 这些描述符可用于绑定和定义，并作为参数传递给函数 ACIDescriptorAlloc 和 ACIDescriptorFree 以分配和释放内存。
句柄申请¶
- 句柄的分配
ACI_HTYPE_ENV类型的句柄申请有两种方式：
ACIEnvInit，淘汰方式，不推荐使用ACIEnvCreate或者ACIEnvNlsCreate，这是推荐使用的方式
其他父句柄类型为ACI_HTYPE_ENV的，都是通过 ACIHandleAlloc 进行申请的。
ACI_HTYPE_ERROR错误句柄时大部分接口调用所需，因此，ACI_HTYPE_ERROR的分配应该是在ACI_HTYPE_ENV分配后立即要做的事情。
- 描述符分配
描述符的申请方式为：通过 ACIDescriptorAlloc / ACIArrayDescriptorAlloc 分配；
句柄释放¶
显示申请的句柄的释放都是通过 ACIHandleFree 来进行释放的；描述符通过 ACIDescriptorFree / ACIArrayDescriptorFree 进行释放。
备注1：良好的编程习惯是句柄或描述符在需要的时候申请，不需要的时候及时释放，否则会导致内存泄漏；
备注2：父句柄的释放会自动释放子句柄，但不要完全依赖这种机制，按照”备注1”描述的规范编写；
备注3：隐式句柄不需要在应用程序中释放；由其所属父句柄释放时自动释放。
句柄属性设置¶
所有ACI句柄都有代表存储在该句柄中的数据的一些属性。您可以使用 ACIAttrGet 来读取句柄属性，也可以使用 ACIAttrSet 来更改属性。
示例代码：使用ACI_ATTR_USERNAME属性在会话句柄中设置用户名
text username[] = "hr";
err = ACIAttrSet ((void *) mysessp, ACI_HTYPE_SESSION, (void *)username,
(ub4) strlen((char *)username), ACI_ATTR_USERNAME, (ACIError *) myerrhp);
某些ACI函数要求在调用函数之前设置特定的句柄属性。 例如，当调用 ACISessionBegin 建立用户的登录会话时，必须在用户会话句柄中设置用户名和密码，然后才能进行调用。
其他ACI函数在函数执行完成后在句柄属性中提供有用的返回数据。 例如，当调用 ACIStmtExecute 执行SQL查询时，在语句句柄中返回与选择列表项有关的描述信息。例如：在语句句柄中返回与选择列表项有关的描述信息
ub4 parmcnt;
/* 获得查询列的个数*/
err = ACIAttrGet ((void *)stmhp, (ub4)ACI_HTYPE_STMT, (void *)
&parmcnt, (ub4 *) 0, (ub4)ACI_ATTR_PARAM_COUNT, errhp);