ACIEnvNlsCreate()

ACIEnvNlsCreate()

作用：

分配并初始化ACI环境句柄

语法：

sword ACIEnvNlsCreate(ACIEnv **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,
                      ub2             charset,
                      ub2             ncharset);

参数：

• envhpp (out)

指向环境句柄的指针。

• mode (in)

初始化模式，取值如下：

ACI_DEFAULT：缺省模式

ACI_THREADED：多线程模式。在这种模式下，不暴露给用户的内部数据结构在多线程访问中被保护。

• 其他 -- 其他参数目前不使用，仅与Oracle OCI兼容

• charset (IN)

当前环境句柄的客户端字符集。 如果为0，则使用NLS_OSCAR_LANG设置。 ACI_UTF16ID是有效设置； 元数据和CHAR数据使用它。

• ncharset (IN)

当前环境句柄的客户端国家字符集。 如果为0，则使用NLS_OSCAR_LANG设置。 ACI_UTF16ID是有效设置； NCHAR数据使用它。

返回值：

ACI_SUCCESS-环境句柄已成功创建。

ACI_ERROR-发生错误。

说明：

使用ACIEnvNlsCreate（）创建环境句柄之后，绑定和定义句柄的实际长度以及返回的长度始终以字节数表示。 这适用于以下调用：

• ACIBindByName 、 ACIBindByName2

• ACIBindByPos 、 ACIBindByPos2

• ACIBindDynamic

• ACIDefineByPos 、 ACIDefineByPos2

• ACIDefineDynamic

此函数允许您在创建环境时设置charset和ncharset id。它是 ACIEnvCreate 函数的增强版本。

必须使用零或全部非零的charset和ncharset调用 ACIEnvNlsCreate 。 否则会导致错误（ORA-24820）。

此函数将非零charset和ncharset设置为客户端数据库和国家字符集，替换由NLS_OSCAR_LANG和NLS_OSCAR_LANG指定的字符集。 当charset和ncharset为0时，该函数的行为与 ACIEnvCreate 完全相同。 具体来说，charset控制元数据和具有隐式格式属性的数据的编码，而ncharset控制具有SQLCS_NCHAR格式属性的数据的编码。

尽管可以通过 ACIEnvNlsCreate 设置ACI_UTF16ID，但不能在NLS_OSCAR_LANG或NLS_OSCAR_LANG中设置它。 要访问NLS_OSCAR_LANG和NLS_OSCAR_LANG中的字符集ID，请使用 ACINlsEnvironmentVariableGet 。

此调用返回一个环境句柄，然后由其余的ACI函数使用。 ACI中可以有多个环境，每个环境都有自己的环境模式。 如果任何模式需要，此功能还可以执行任何进程级别的初始化。 例如，如果要将环境初始化为ACI_THREADED，则ACI使用的所有库也将在线程模式下初始化。