句柄说明
句柄是一个指向由XGCI分配的存储区域的不透明的指针，指针指向的内存区域存放着重要的上下文连接信息，XGCI 通过句柄来维护上下文的联系。在XGCI中一个服务句柄会记载虚谷数据库服务目标主机的IP地址及端口号等信息，一个连接句柄会保存服务句柄的指针地址，并额外存储虚谷数据库服务的数据库名称、用户名、用户登录口令等信息。XGCI通过句柄来保存访问虚谷数据库服务所需要的所有信息，句柄可以使得基于XGCI进行软件开发的工作更简单。
XGCI中定义的句柄类型和各个句柄类型相对应的C数据类型如表1所示。| Handle Type Constant | C Data Type | 说明 |
|---|---|---|
| HT_ENV | XGCIEnv | 分配C类型XGCIEnv的环境句柄 |
| HT_SERVER | XGCIServer | 分配C类型XGCIServer的服务句柄 |
| HT_SESSION | XGCISession | 分配C类型XGCISession的会话句柄 |
| HT_CONNPOOL | XGCIConnectPool | 分配C类型XGCIConnectPool连接池句柄 |
| HT_STATEMENT | XGCIStatement | 分配C类型XGCIStatement语句句柄 |
| HT_ERR | XGCIError | 分配C类型XGCIError错误句柄 |
| XGCI_DTYPE_PARAM | Param_ColsInfo | 分配C类型catalog描述句柄 |
XGCI中所有类型的句柄都通过句柄分配函数XGCIHandleAlloc()进行初始化，句柄类型包括：环境句柄、服务上下文句柄、会话句柄、语句句柄、错误句柄和连接池句柄等。说明：
分配句柄时，应用程序需要为一个特定的环境句柄分配所有上层的句柄，通常环境句柄作为一个参数传递至句柄分配函数。被分配的句柄即特定于当前环境句柄所属的环境。释放句柄时，应用程序需要按照“先进后出”的顺序对句柄进行释放，即释放句柄的顺序为语句句柄、连接句柄、服务句柄、环境句柄。
一个应用程序必须释放所有不再使用的句柄，XGCI中通过XGCIHandleFree()函数释放各个类型的句柄。
注意：
当一个父句柄被释放后，所有与之相关联的子句柄也应被释放并且保证其再也不能被使用。
句柄除了减少对全局变量的依赖外，还使得错误报告更容易。当接口调用出现返回值异常时，可通过调用函数 XGCIErrors() 来返回相关的错误和诊断信息。
XGCI各个类型句柄的层次如图1所示。