SQLAllocHandle 函数
一致性
引入的版本：ODBC 3.0 标准符合性：ISO 92
总结
SQLAllocHandle 分配环境、连接、语句或描述符句柄。
注意
此函数是用于分配用于替换 ODBC 2.0 函数 SQLAllocConnect、SQLAllocEnv 和 SQLAllocStmt 的句柄的泛型函数。 允许调用 SQLAllocHandle 的应用程序使用 ODBC 2。x 驱动程序，对 SQLAllocHandle 的调用会根据需要在驱动程序管理器中映射到 SQLAllocConnect、SQLAllocEnv 或 SQLAllocStmt。 有关详细信息，请参阅“注释”。有关 Driver Manager 将此函数映射到 ODBC 3 时的内容的详细信息。x 应用程序正在使用 ODBC 2。x 驱动程序，请参阅 映射替换函数以实现应用程序的向后兼容性。
语法
SQLRETURN SQLAllocHandle(
SQLSMALLINT HandleType,
SQLHANDLE InputHandle,
SQLHANDLE * OutputHandlePtr);
参数
HandleType
[输入]要由 SQLAllocHandle 分配的句柄的类型。 必须是以下值之一：
SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT
SQL_HANDLE_DBC_INFO_TOKEN句柄仅由驱动程序管理器和驱动程序使用。 应用程序不应使用此句柄类型。 有关SQL_HANDLE_DBC_INFO_TOKEN的详细信息，请参阅 在 ODBC 驱动程序中开发连接池感知。
InputHandle
[输入]要分配新句柄的上下文中的输入句柄。 如果 HandleType 是SQL_HANDLE_ENV，则这是SQL_NULL_HANDLE。 如果 HandleType 是SQL_HANDLE_DBC，则它必须是环境句柄，如果SQL_HANDLE_STMT或SQL_HANDLE_DESC，则它必须是连接句柄。
OutputHandlePtr
[输出]指向将句柄返回到新分配的数据结构的缓冲区的指针。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_INVALID_HANDLE或SQL_ERROR。
分配环境句柄以外的句柄时，如果 SQLAllocHandle 返回SQL_ERROR，则它将 OutputHandlePtr 设置为SQL_NULL_HDBC、SQL_NULL_HSTMT或SQL_NULL_HDESC，具体取决于 HandleType 的值，除非输出参数为 null 指针。 然后，应用程序可以从与 InputHandle 参数中的句柄关联的诊断数据结构获取其他信息。
环境处理分配错误
环境分配同时发生在驱动程序管理器和每个驱动程序中。 SQLAllocHandle 返回SQL_HANDLE_ENV HandleType 返回的错误取决于发生错误的级别。
如果在调用具有 handleType SQL_HANDLE_ENV 的 SQLAllocHandle 时驱动程序管理器无法为 *OutputHandlePtr 分配内存，或者应用程序为 OutputHandlePtr 提供空指针，SQLAllocHandle 将返回SQL_ERROR。 驱动程序管理器将 *OutputHandlePtr 设置为SQL_NULL_HENV（除非应用程序提供了返回SQL_ERROR的 null 指针）。 没有用于关联其他诊断信息的句柄。
在应用程序调用 SQLConnect、SQLBrowseConnect 或 SQLDriverConnect 之前，驱动程序管理器不会调用驱动程序级环境句柄分配函数。 如果在驱动程序级 SQLAllocHandle 函数中发生错误，驱动程序管理器级 SQLConnect、SQLBrowseConnect 或 SQLDriverConnect 函数将返回SQL_ERROR。 诊断数据结构包含 SQLSTATE IM004（驱动程序的 SQLAllocHandle 失败）。 错误在连接句柄上返回。
有关驱动程序管理器和驱动程序之间的函数调用流的详细信息，请参阅 SQLConnect 函数。
诊断
当 SQLAllocHandle 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过调用具有相应 HandleType 和 Handle 设置为 InputHandle 值的 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 可以为 OutputHandle 参数返回SQL_SUCCESS_WITH_INFO（但不能SQL_ERROR）。 下表列出了 SQLAllocHandle 通常返回的 SQLSTATE 值，并解释此函数上下文中的每个值;表示法“（DM）”位于驱动程序管理器返回的 SQLSTATE 的说明之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| 08003 | 连接未打开 | （DM） HandleType 参数SQL_HANDLE_STMT或SQL_HANDLE_DESC，但 InputHandle 参数指定的连接未打开。 连接过程必须成功完成（并且必须打开连接），驱动程序才能分配语句或描述符句柄。 |
| HY000 | 常规错误 | 发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。 |
| HY001 | 内存分配错误 | （DM） 驱动程序管理器无法为指定的句柄分配内存。 驱动程序无法为指定的句柄分配内存。 |
| HY009 | 无效使用 null 指针 | （DM） OutputHandlePtr 参数为空指针。 |
| HY010 | 函数序列错误 | （DM） HandleType 参数SQL_HANDLE_DBC，并且 尚未调用 SQLSetEnvAttr 来设置SQL_ODBC_VERSION环境属性。 （DM） 为 InputHandle 调用异步执行函数，并且仍在执行 SQLAllocHandle 函数时，将 HandleType 设置为SQL_HANDLE_STMT或SQL_HANDLE_DESC。 |
| HY013 | 内存管理错误 | HandleType 参数SQL_HANDLE_DBC、SQL_HANDLE_STMT或SQL_HANDLE_DESC;并且无法处理函数调用，因为基础内存对象无法访问，可能是由于内存条件低。 |
| HY014 | 超出句柄数的限制 | 已达到 HandleType 参数指示的句柄类型可分配的句柄数的驱动程序定义的限制。 |
| HY092 | 属性/选项标识符无效 | （DM） HandleType 参数不是：SQL_HANDLE_ENV、SQL_HANDLE_DBC、SQL_HANDLE_STMT或SQL_HANDLE_DESC。 |
| HY117 | 连接因未知事务状态而挂起。 仅允许断开连接和只读函数。 | （DM） 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYC00 | 未实现可选功能 | HandleType 参数SQL_HANDLE_DESC，驱动程序为 ODBC 2。x 驱动程序。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr 设置，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驱动程序不支持此函数 | （DM） HandleType 参数SQL_HANDLE_STMT，驱动程序不是有效的 ODBC 驱动程序。 （DM） HandleType 参数SQL_HANDLE_DESC，驱动程序不支持分配描述符句柄。 |
注释
SQLAllocHandle 用于为环境、连接、语句和描述符分配句柄，如以下部分所述。 有关句柄的一般信息，请参阅 句柄。
如果驱动程序支持多个分配，则应用程序一次可以分配多个环境、连接或语句句柄。 在 ODBC 中，不会对任何一次可以分配的环境、连接、语句或描述符句柄的数量定义任何限制。 驱动程序可能会对可以一次分配的特定类型的句柄的数量施加限制;有关详细信息，请参阅驱动程序文档。
如果应用程序调用 SQLAllocHandle 且 *OutputHandlePtr 设置为已存在的环境、连接、语句或描述符句柄，驱动程序将覆盖与 句柄关联的信息，除非应用程序正在使用连接池（请参阅本节后面的“分配连接池环境属性”）。 驱动程序管理器不会检查是否已使用 *OutputHandlePtr 中输入的句柄，也不会在覆盖句柄之前检查句柄以前的内容。
注意
ODBC 应用程序编程不正确，使用为 *OutputHandlePtr 定义的同一应用程序变量两次调用 SQLAllocHandle，而无需调用 SQLFreeHandle 释放句柄，然后再重新分配它。 以这种方式覆盖 ODBC 句柄可能会导致 ODBC 驱动程序的行为或错误不一致。
在支持多个线程的操作系统上，应用程序可以在不同的线程上使用相同的环境、连接、语句或描述符句柄。 因此，驱动程序必须支持对此信息的安全多线程访问;例如，实现此目的的一种方法是使用关键部分或信号灯。 有关线程处理的详细信息，请参阅 多线程处理。
当调用 SQLAllocHandle 来分配环境句柄时，SQLAllocHandle 不会设置SQL_ATTR_ODBC_VERSION环境属性;环境属性必须由应用程序设置，或者在调用 SQLAllocHandle 以分配连接句柄时返回 SQLSTATE HY010 （函数序列错误）。
对于符合标准的应用程序， SQLAllocHandle 在编译时映射到 SQLAllocHandleStd 。 这两个函数之间的区别在于 ，SQLAllocHandleStd 在调用时将 SQL_ATTR_ODBC_VERSION 环境属性设置为SQL_OV_ODBC3， 并将 HandleType 参数设置为SQL_HANDLE_ENV。 这样做是因为符合标准的应用程序始终是 ODBC 3。x 应用程序。 此外，标准不需要注册应用程序版本。 这是这两个函数的唯一区别;否则，它们是相同的。 SQLAllocHandleStd 映射到 驱动程序管理器内的 SQLAllocHandle 。 因此，第三方驱动程序不必实现 SQLAllocHandleStd。
ODBC 3.8 应用程序应使用：
SQLAllocHandle 而不是 SQLAllocHandleStd 来分配环境句柄。
SQLSetEnvAttr 将SQL_ATTR_ODBC_VERSION环境属性设置为SQL_OV_ODBC3_80。
分配环境句柄
环境句柄提供对全局信息（例如有效连接句柄和活动连接句柄）的访问。 有关环境句柄的一般信息，请参阅 环境句柄。
若要请求环境句柄，应用程序使用 handleType 为 SQL_HANDLE_ENV 和 SQL_NULL_HANDLE 的 InputHandle 调用 SQLAllocHandle。 驱动程序为环境信息分配内存，并在 *OutputHandlePtr 参数中传递关联的句柄的值。 应用程序在需要环境句柄参数的所有后续调用中传递 *OutputHandle 值。 有关详细信息，请参阅分配环境句柄。
在驱动程序管理器的环境句柄下，如果已存在驱动程序的环境句柄，则在建立连接时，不会在该驱动程序中调用具有 handleType of SQL_HANDLE_ENV 的 SQLAllocHandle，只有具有 handleType 的 SQLAllocHandle SQL_HANDLE_DBC。 如果驱动程序的环境句柄在驱动程序管理器的环境句柄下不存在，则当环境的第一个连接句柄连接到驱动程序时，在驱动程序中调用具有 handleType 为 SQL_HANDLE_ENV 的 SQLAllocHandle 和具有 handleType SQL_HANDLE_DBC 的 SQLAllocHandle。
当驱动程序管理器使用 handleType SQL_HANDLE_ENV 处理 SQLAllocHandle 函数时，它会检查系统信息的 [ODBC] 节中的 Trace 关键字。 如果设置为 1，驱动程序管理器将为当前应用程序启用跟踪。 如果设置了跟踪标志，则跟踪在分配第一个环境句柄时开始，并在释放最后一个环境句柄时结束。 有关详细信息，请参阅 配置数据源。
分配环境句柄后，应用程序必须在环境句柄上调用 SQLSetEnvAttr 来设置SQL_ATTR_ODBC_VERSION环境属性。 如果在调用 SQLAllocHandle 以在环境中分配连接句柄之前未设置此属性，则分配连接的调用将返回 SQLSTATE HY010 （函数序列错误）。 有关详细信息，请参阅 声明应用程序的 ODBC 版本。
为连接池分配共享环境
环境可以在单个进程中的多个组件之间共享。 共享环境可以同时由多个组件使用。 当组件使用共享环境时，它可以使用共用连接，从而允许它分配和使用现有连接，而无需重新创建该连接。
在分配可用于连接池的共享环境之前，应用程序必须调用 SQLSetEnvAttr 将SQL_ATTR_CONNECTION_POOLING环境属性设置为SQL_CP_ONE_PER_DRIVER或SQL_CP_ONE_PER_HENV。 在本例中，SQLSetEnvAttr 调用 EnvironmentHandle 设置为 null，这使得该属性成为进程级属性。
启用连接池后，应用程序调用 SQLAllocHandle ，并将 HandleType 参数设置为SQL_HANDLE_ENV。 此调用分配的环境将是隐式共享环境，因为已启用了连接池。
分配共享环境时，在调用具有 handleType 的 HandleType SQL_HANDLE_DBC 的 SQLAllocHandle 之前，不会确定将使用的环境。 此时，驱动程序管理器会尝试查找与应用程序请求的环境属性匹配的现有环境。 如果不存在此类环境，则会创建一个作为共享环境。 驱动程序管理器为每个共享环境维护引用计数;首次创建环境时，计数设置为 1。 如果找到匹配的环境，该环境的句柄将返回到应用程序，并递增引用计数。 以这种方式分配的环境句柄可用于接受环境句柄作为输入参数的任何 ODBC 函数。
分配连接句柄
连接句柄提供对连接上的有效语句和描述符句柄以及事务当前是否打开等信息的访问权限。 有关连接句柄的一般信息，请参阅 连接句柄。
若要请求连接句柄，应用程序使用 handleType SQL_HANDLE_DBC 调用 SQLAllocHandle。 InputHandle 参数设置为调用分配该句柄的 SQLAllocHandle 返回的环境句柄。 驱动程序为连接信息分配内存，并在 *OutputHandlePtr 中传递关联的句柄的值。 应用程序在需要连接句柄的所有后续调用中传递 *OutputHandlePtr 值。 有关详细信息，请参阅 分配连接句柄。
驱动程序管理器处理 SQLAllocHandle 函数，并在应用程序调用 SQLConnect、SQLBrowseConnect 或 SQLDriverConnect 时调用驱动程序的 SQLAllocHandle 函数。 （有关详细信息，请参阅 SQLConnect 函数。）
如果在调用 SQLAllocHandle 以在环境中分配连接句柄之前未设置SQL_ATTR_ODBC_VERSION环境属性，则分配连接的调用将返回 SQLSTATE HY010（函数序列错误）。
当应用程序调用将 InputHandle 参数设置为SQL_HANDLE_DBC并设置为共享环境句柄的 SQLAllocHandle 时，驱动程序管理器会尝试查找与应用程序设置的环境属性匹配的现有共享环境。 如果不存在此类环境，则会使用引用计数 1（由驱动程序管理器维护）创建一个环境。 如果找到匹配的共享环境，该句柄将返回到应用程序，并递增其引用计数。
在调用 SQLConnect 或 SQLDriverConnect 之前，驱动程序管理器不会确定要使用的实际连接。 驱动程序管理器使用对 SQLConnect 的调用中的连接选项（或者对 SQLDriverConnect 的调用中的连接关键字）以及连接分配后设置的连接属性，以确定应使用池中的哪个连接。 有关详细信息，请参阅 SQLConnect 函数。
分配语句句柄
语句句柄提供对语句信息的访问，例如错误消息、游标名称和 SQL 语句处理的状态信息。 有关语句句柄的一般信息，请参阅 语句句柄。
若要请求语句句柄，应用程序连接到数据源，然后在提交 SQL 语句之前调用 SQLAllocHandle 。 在此调用中，HandleType 应设置为SQL_HANDLE_STMT，InputHandle 应设置为调用分配该句柄的 SQLAllocHandle 返回的连接句柄。 驱动程序为语句信息分配内存，将语句句柄与指定的连接相关联，并在 *OutputHandlePtr 中传递关联的句柄的值。 应用程序在需要语句句柄的所有后续调用中传递 *OutputHandlePtr 值。 有关详细信息，请参阅 分配语句句柄。
分配语句句柄时，驱动程序会自动分配一组四个描述符，并将这些描述符的句柄分配给SQL_ATTR_APP_ROW_DESC、SQL_ATTR_APP_PARAM_DESC、SQL_ATTR_IMP_ROW_DESC和SQL_ATTR_IMP_PARAM_DESC语句属性。 这些描述符称为 隐式 分配的描述符。 若要显式分配应用程序描述符，请参阅以下部分“分配描述符句柄”。
分配描述符句柄
当应用程序使用 handleType 为 SQL_HANDLE_DESC 调用 SQLAllocHandle 时，驱动程序会分配应用程序描述符。 这些描述符称为 显式 分配的描述符。 应用程序通过调用具有SQL_ATTR_APP_ROW_DESC或SQL_ATTR_APP_PARAM_DESC属性的 SQLSetStmtAttr 函数，指示驱动程序使用显式分配的应用程序描述符，而不是为给定语句句柄自动分配的应用程序描述符。 无法显式分配实现描述符，也不能在 SQLSetStmtAttr 函数调用中指定实现描述符。
显式分配的描述符与连接句柄（如自动分配的描述符）相关联。 仅当应用程序实际连接到数据库时，描述符才会被分配。 由于显式分配的描述符与连接句柄相关联，因此应用程序可以将显式分配的描述符与连接中的多个语句相关联。 另一方面，隐式分配的应用程序描述符不能与多个语句句柄相关联。 （它不能与为其分配的语句句柄以外的任何语句句柄相关联。显式分配的描述符句柄可由应用程序显式释放，或者通过使用 handleType 为 SQL_HANDLE_DESC 调用 SQLFreeHandle，或者在连接关闭时隐式释放。
释放显式分配的描述符时，隐式分配的描述符将再次与该语句相关联。 （该语句的SQL_ATTR_APP_ROW_DESC或SQL_ATTR_APP_PARAM_DESC属性再次设置为隐式分配的描述符句柄。对于与连接上显式分配的描述符关联的所有语句都是如此。
有关描述符的详细信息，请参阅描述符。
代码示例
请参阅 示例 ODBC 程序、 SQLBrowseConnect 函数、 SQLConnect 函数和 SQLSetCursorName 函数。
相关函数
| 有关以下内容的信息 | 请参阅 |
|---|---|
| 执行 SQL 语句 | SQLExecDirect 函数 |
| 执行准备的 SQL 语句 | SQLExecute 函数 |
| 释放环境、连接、语句或描述符句柄 | SQLFreeHandle 函数 |
| 准备语句以供执行 | SQLPrepare 函数 |
| 设置连接属性 | SQLSetConnectAttr 函数 |
| 设置描述符字段 | SQLSetDescField 函数 |
| 设置环境属性 | SQLSetEnvAttr 函数 |
| 设置语句属性 | SQLSetStmtAttr 函数 |