创建 OCI环境
在编写OCI 程序的第一步就是创建 OCI 环境，然后分配需要的句柄，下面介绍创建 OCI 环境的函数。这是 OCI 程序第一个要调用的函数，名字叫做 OCIEnvCreate() 。看一下它的函数原型和参数。 sword OCIEnvCreate ( OCIEnv **envhpp, ub4 mode, const void *ctxp, const void *(*malocfp)(void *ctxp, size_t size), const void *(*ralocfp)(void *ctxp, void *memptr, size_t newsize), const void (*mfreefp)(void *ctxp, void *memptr) ， size_t xtramemsz, void **usrmempp ); envhpp 是一个输出参数，是一个指针的指针，为了要把创建的环境句柄带回来。后面的函数会用到这个句柄。 mode 是一个输入参数，指示创建 OCI 环境的模式。有几个主要的模式介绍一下，一般用到的是缺省模式 OCI_DEFAULT ，大部分程序用这个模式就够了。如果使用多线程调用 OCI 函数，那么就要用到线程模式 OCI_THREADED ，这样可以保证每个线程都有一份环境内存，不相互干扰，否则线程之间互相修改共享的环境内存，会造成 coredump 。如果使用 OCI 中的对象操作函数，就要用到 OCI_OBJECT 模式。 ctxp 是一个输入参数，指示用户定义的上下文指针，给回调函数用的，一般赋值为 NULL 就可以了。 malocfp 是一个输入参数，是一个函数指针，是用户定义的分配内存的函数，类似 C 语言中的 malloc() 函数，一般赋值为 NULL 。 ralocfp 是一个输入参数，是一个函数指针，是用户定义的再分配内存的函数，类似 C 语言中的 realloc() 函数，一般赋值为 NULL 。 mfreefp 是一个输入参数，是一个函数指针，是用户定义的释放内存的函数，类似 C 语言中的 free() 函数，一般赋值为 NULL 。由于创建 OCI 环境变量需要分配一定大小的内存，分配过程中就会用到内存分配函数，上面的三个函数指针就是为分配内存和释放内存准备的，让用户可以自己分配和释放内存，如果没有用户自己定义的函数，那么都赋值为 NULL ，创建 OCI 环境时就使用系统自己的分配和释放内存的函数。 xtramemsz 是一个输入参数，指示额外分配内存的大小，这个内存可以给用户使用，生命周期与 OCI 环境的生存期一样长，在释放环境内存时才一起释放掉。一般不用这个内存，可以赋值为 0 。 usrmempp 是一个输出参数，带回分配的用户内存的指针。这个参数与上一个参数是相关的，如果上一个参数大于 0 ，那么必须赋值把分配的用户内存指针带回来，如果上个参数为 0 ，这里赋值为 NULL 就可以了。 OCIEnvNlsCreate() 的返回值是一个 sword 类型的整数，实际上就是一个有符号的整数。所有的 OCI 函数返回值都是 sword 整数，绝大多数的时候返回值是 OCI_SUCCESS 或 OCI_ERROR ，表示函数执行成功或出错，特定的函数还会返回其他值，后面遇到时再介绍。 看一个实际的例子。
OCIEnv *envhp = NULL;
sword rc;
rc = OCIEnvCreate(
&envhp, /* envhpp */
OCI_DEFAULT, /* mode */
(void *)NULL, /* ctxp */
NULL,
NULL,
NULL,
(size_t)0,
(void **)NULL
);
if (rc != OCI_SUCCESS) {
fprintf(stderr, "OCIEnvCreate() - allocate OCI env handle error !\n");
return (-1);
}
这里返回的envhp 就是创建的 OCI 环境变量指针。
分配句柄
创建完OCI 环境之后，马上就要分配必须的句柄才能连接到数据库，分配句柄的函数叫做 OCIHandleAlloc() 。看一下它的原型和参数。 sword OCIHandleAlloc ( const void *parenth, void **hndlpp, ub4 type, size_t xtramem_sz, void **usrmempp ); parenth 是一个输入参数，表示被分配句柄的父句柄指针，一般会是 OCI 环境句柄。 hndlpp 是一个输出参数，带回被分配的句柄指针。 type 是一个输入参数，指示分配句柄的类型。句柄类型有很多，在后面用到时再一一介绍。 xtramem_sz 是输入参数，指示额外分配的跟句柄关联的用户内存大小，与创建 OCI 环境函数的最后两个参数意义相同。不想分配的话赋值为 0 。 usrmempp 是输出参数，带回分配的用户内存的指针。 一个实际的例子，在创建OCI 环境后，第一个要分配的句柄就是处理错误的句柄，类型为 OCI_HTYPE_ERROR ，我们来看一下。
sword rc;
rc = OCIHandleAlloc(
(const void *)envhp,
(void **)&errhp,
OCI_HTYPE_ERROR,
0,
(void **)NULL
);
if (rc != OCI_SUCCESS) {
fprintf(stderr, "OCIHandleAlloc() - allocate OCI error handle error !\n");
return (-1);
}
下一节我们再来看看还要分配哪些句柄，怎样连接到数据库。
