SQLAllocHandle 函数
一致性
引入的版本：ODBC 3.0 标准符合性：ISO 92
摘要
SQLAllocHandle 分配环境、连接、语句或描述符句柄。
注意
此函数是一个泛型函数，用于分配替换 ODBC 2.0 函数 SQLAllocConnect、 SQLAllocEnv 和 SQLAllocStmt 的句柄。 允许调用 SQLAllocHandle 的应用程序使用 ODBC 2。x 驱动程序，对 SQLAllocHandle 的 调用在驱动程序管理器中映射到 SQLAllocConnect、 SQLAllocEnv 或 SQLAllocStmt（视情况而定）。 有关详细信息，请参阅“注释”。有关驱动程序管理器将此函数映射到 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 驱动程序中开发Connection-Pool感知。
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 的值，除非 output 参数为 null 指针。 然后，应用程序可以从与 InputHandle 参数中的句柄关联的诊断数据结构中获取其他信息。
环境句柄分配错误
环境分配同时在驱动程序管理器和每个驱动程序中进行。 SQLAllocHandle 返回的 handleType 为 SQL_HANDLE_ENV 的错误取决于发生错误的级别。
如果在调用 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时，可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值，并将相应的 HandleType 和 Handle 设置为 InputHandle 的值。 可以为 OutputHandle 参数返回SQL_SUCCESS_WITH_INFO (但不返回SQL_ERROR) 。 下表列出了通常由 SQLAllocHandle 返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 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) 已SQL_HANDLE_DBC HandleType 参数，并且尚未调用 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 驱动程序的行为不一致或错误。
在支持多个线程的操作系统上，应用程序可以在不同的线程上使用相同的环境、连接、语句或描述符句柄。 因此，驱动程序必须支持对此信息的安全、多线程访问;例如，实现此目的的一种方法是使用关键部分或信号灯。 有关线程处理的详细信息，请参阅 多线程处理。
调用 SQL_ATTR_ODBC_VERSION 环境属性以分配环境句柄时，SQLAllocHandle 不会设置该属性;环境属性必须由应用程序设置，否则在调用 SQLAllocHandle 以分配连接句柄时，将返回 SQLSTATE HY010 (函数序列错误) 。
对于符合标准的应用程序， SQLAllocHandle 在编译时映射到 SQLAllocHandleStd 。 这两个函数的区别在于 ，SQLAllocHandleStd 将 SQL_ATTR_ODBC_VERSION environment 属性设置为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 且 InputHandle 为 SQL_NULL_HANDLE 调用 SQLAllocHandle。 驱动程序为环境信息分配内存，并在 *OutputHandlePtr 参数中传递回关联句柄的值。 应用程序在需要环境句柄参数的所有后续调用中传递 *OutputHandle 值。 有关详细信息，请参阅 分配环境句柄。
在驱动程序管理器的环境句柄下，如果已存在驱动程序的环境句柄，则在建立连接时，不会在该驱动程序中调用 handleType 为 SQL_HANDLE_ENV 的 SQLAllocHandle，仅调用 HandleType 为 SQL_HANDLE_DBC 的 SQLAllocHandle。 如果驱动程序的环境句柄下不存在驱动程序的环境句柄，则当环境的第一个连接句柄连接到驱动程序时，驱动程序中将调用 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 为 SQL_HANDLE_DBC 的 SQLAllocHandle 之前，不会确定要使用的环境。 此时，驱动程序管理器会尝试查找与应用程序请求的环境属性匹配的现有环境。 如果不存在此类环境，则会创建一个共享环境。 驱动程序管理器维护每个共享环境的引用计数;首次创建环境时， 计数设置为 1。 如果找到匹配的环境，该环境的句柄将返回到应用程序，并递增引用计数。 以这种方式分配的环境句柄可用于接受环境句柄作为输入参数的任何 ODBC 函数。
分配连接句柄
连接句柄提供对连接上的有效语句和描述符句柄以及事务当前是否打开等信息的访问权限。 有关连接句柄的一般信息，请参阅 连接句柄。
若要请求连接句柄，应用程序使用 handleType SQL_HANDLE_DBC 调用 SQLAllocHandle。 InputHandle 参数设置为由调用分配该句柄的 SQLAllocHandle 返回的环境句柄。 驱动程序为连接信息分配内存，并在 *OutputHandlePtr 中传递回关联句柄的值。 应用程序在需要连接句柄的所有后续调用中传递 *OutputHandlePtr 值。 有关详细信息，请参阅 分配连接句柄。
当应用程序调用 SQLConnect、SQLBrowseConnect 或 SQLDriverConnect 时，驱动程序管理器处理 SQLAllocHandle 函数并调用驱动程序的 SQLAllocHandle 函数。 (有关详细信息，请参阅 SQLConnect Function.)
如果在调用 SQLAllocHandle 以在环境中分配连接句柄之前未设置SQL_ATTR_ODBC_VERSION环境属性，则对分配连接的调用将返回 SQLSTATE HY010 (函数序列错误) 。
当应用程序调用 SQLAllocHandle 且 InputHandle 参数设置为 SQL_HANDLE_DBC 并且同时设置为共享环境句柄时，驱动程序管理器会尝试查找与应用程序设置的环境属性匹配的现有共享环境。 如果不存在此类环境，则会创建一个，其引用计数 (由驱动程序管理器维护，) 为 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 函数调用中指定实现描述符。
显式分配的描述符与连接句柄而不是语句句柄相关联， (因为) 自动分配的描述符。 仅当应用程序实际连接到数据库时，描述符才保持分配状态。 由于显式分配的描述符与连接句柄相关联，因此应用程序可以将显式分配的描述符与连接中的多个语句相关联。 另一方面，隐式分配的应用程序描述符不能与多个语句句柄相关联。 (它不能与为其分配的语句句柄之外的任何语句句柄相关联。) 显式分配的描述符句柄可以由应用程序显式释放，也可以通过调用 SQLFreeHandle 和 handleType 为 SQL_HANDLE_DESC，或者在关闭连接时隐式释放。
释放显式分配的描述符时，隐式分配的描述符再次与 语句相关联。 (该语句的 SQL_ATTR_APP_ROW_DESC 或 SQL_ATTR_APP_PARAM_DESC 属性再次设置为隐式分配的描述符 handle。) 这适用于与连接上显式分配的描述符关联的所有语句。
有关描述符的详细信息，请参阅 描述符。
代码示例
请参阅 示例 ODBC 程序、 SQLBrowseConnect 函数、 SQLConnect 函数和 SQLSetCursorName 函数。
相关函数
| 有关以下方面的信息 | 请参阅 |
|---|---|
| 执行 SQL 语句 | SQLExecDirect 函数 |
| 执行准备好的 SQL 语句 | SQLExecute 函数 |
| 释放环境、连接、语句或描述符句柄 | SQLFreeHandle 函数 |
| 准备语句以执行 | SQLPrepare 函数 |
| 设置连接属性 | SQLSetConnectAttr 函数 |
| 设置描述符字段 | SQLSetDescField 函数 |
| 设置环境属性 | SQLSetEnvAttr 函数 |
| 设置语句属性 | SQLSetStmtAttr 函数 |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈