SQLDescribeCol 函数SQLDescribeCol Function

符合性Conformance
版本引入了:ODBC 1.0 标准符合性:ISO 92Version Introduced: ODBC 1.0 Standards Compliance: ISO 92

摘要Summary
SQLDescribeCol为结果集中的一列返回的结果描述符的列名称、 类型、 列大小、 十进制数和为 null 性的。SQLDescribeCol returns the result descriptor - column name,type, column size, decimal digits, and nullability - for one column in the result set. 此信息也是可用的 IRD 字段中。This information also is available in the fields of the IRD.

语法Syntax

  
SQLRETURN SQLDescribeCol(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   ColumnNumber,  
      SQLCHAR *      ColumnName,  
      SQLSMALLINT    BufferLength,  
      SQLSMALLINT *  NameLengthPtr,  
      SQLSMALLINT *  DataTypePtr,  
      SQLULEN *      ColumnSizePtr,  
      SQLSMALLINT *  DecimalDigitsPtr,  
      SQLSMALLINT *  NullablePtr);  

参数Arguments

StatementHandleStatementHandle
[输入]语句句柄。[Input] Statement handle.

ColumnNumberColumnNumber
[输入]结果数据的列数在不断增加的列顺序,从 1 开始按顺序排序。[Input] Column number of result data, ordered sequentially in increasing column order, starting at 1. ColumnNumber参数还可以将设置为 0 来描述书签列。The ColumnNumber argument can also be set to 0 to describe the bookmark column.

ColumnNameColumnName
[输出]指向以 null 结尾的缓冲区中要返回的列名称。[Output] Pointer to a null-terminated buffer in which to return the column name. 从 IRD 的 SQL_DESC_NAME 字段读取此值。This value is read from the SQL_DESC_NAME field of the IRD. 如果列是未命名或不能确定列名称,该驱动程序将返回空字符串。If the column is unnamed or the column name cannot be determined, the driver returns an empty string.

如果ColumnName为 NULL, NameLengthPtr仍将返回的字符 (不包括字符数据的 null 终止字符) 总数可用于返回通过指向的缓冲区中ColumnNameIf ColumnName is NULL, NameLengthPtr will still return the total number of characters (excluding the null-termination character for character data) available to return in the buffer pointed to by ColumnName.

BufferLengthBufferLength
[输入]长度 *ColumnName缓冲区,以字符为单位。[Input] Length of the *ColumnName buffer, in characters.

NameLengthPtrNameLengthPtr
[输出]指向用于返回的字符 (不包括 null 终止) 总数的缓冲区可用于在中返回* ColumnName[Output] Pointer to a buffer in which to return the total number of characters (excluding the null termination) available to return in *ColumnName. 可用于返回的字符数是否大于或等于BufferLength中的列名称* ColumnName截断为BufferLength减去 null 终止字符的长度。If the number of characters available to return is greater than or equal to BufferLength, the column name in *ColumnName is truncated to BufferLength minus the length of a null-termination character.

DataTypePtrDataTypePtr
[输出]指向用于返回 SQL 数据类型的列的缓冲区的指针。[Output] Pointer to a buffer in which to return the SQL data type of the column. 从 IRD 的 SQL_DESC_CONCISE_TYPE 字段读取此值。This value is read from the SQL_DESC_CONCISE_TYPE field of the IRD. 这将是中的值之一SQL 数据类型,或特定于驱动程序的 SQL 数据类型。This will be one of the values in SQL Data Types, or a driver-specific SQL data type. 如果不确定的数据类型,该驱动程序返回 SQL_UNKNOWN_TYPE。If the data type cannot be determined, the driver returns SQL_UNKNOWN_TYPE.

在 ODBC 3。x,返回 SQL_TYPE_DATE、 SQL_TYPE_TIME 或 SQL_TYPE_TIMESTAMP *DataTypePtr日期、 时间或时间戳数据的 ODBC 2 中分别;。x,则返回 SQL_DATE、 SQL_TIME 或 SQL_TIMESTAMP。In ODBC 3.x, SQL_TYPE_DATE, SQL_TYPE_TIME, or SQL_TYPE_TIMESTAMP is returned in *DataTypePtr for date, time, or timestamp data, respectively; in ODBC 2.x, SQL_DATE, SQL_TIME, or SQL_TIMESTAMP is returned. 驱动程序管理器执行所需的映射时 ODBC 2。x应用程序使用 ODBC 3。x驱动程序或当 ODBC 3。x应用程序使用 ODBC 2。x驱动程序。The Driver Manager performs the required mappings when an ODBC 2.x application is working with an ODBC 3.x driver or when an ODBC 3.x application is working with an ODBC 2.x driver.

ColumnNumber等于 SQL_BINARY 中为 0 (表示书签列),则返回 *DataTypePtr长度可变的书签。When ColumnNumber is equal to 0 (for a bookmark column), SQL_BINARY is returned in *DataTypePtr for variable-length bookmarks. (如果书签由 ODBC 3,则返回 SQL_INTEGER。x应用程序使用 ODBC 2。x驱动程序或通过 ODBC 2。x应用程序使用 ODBC 3。x驱动程序。)(SQL_INTEGER is returned if bookmarks are used by an ODBC 3.x application working with an ODBC 2.x driver or by an ODBC 2.x application working with an ODBC 3.x driver.)

这些数据类型的详细信息,请参阅SQL 数据类型中附录 d:数据类型。For more information on these data types, see SQL Data Types in Appendix D: Data Types. 有关特定于驱动程序的 SQL 数据类型的信息,请参阅驱动程序的文档。For information about driver-specific SQL data types, see the driver's documentation.

ColumnSizePtrColumnSizePtr
[输出]指向在其上数据源返回的列的大小 (以字符为单位) 的缓冲区的指针。[Output] Pointer to a buffer in which to return the size (in characters) of the column on the data source. 如果无法确定列大小,该驱动程序将返回 0。If the column size cannot be determined, the driver returns 0. 列大小的详细信息,请参阅列的大小、 十进制数字、 传输八位字节长度和显示大小中附录 d:数据类型。For more information on column size, see Column Size, Decimal Digits, Transfer Octet Length, and Display Size in Appendix D: Data Types.

DecimalDigitsPtrDecimalDigitsPtr
[输出]指向在其上数据源返回的列的小数位数的缓冲区的指针。[Output] Pointer to a buffer in which to return the number of decimal digits of the column on the data source. 如果小数位数不能确定或不适用,则驱动程序将返回 0。If the number of decimal digits cannot be determined or is not applicable, the driver returns 0. 十进制数字的详细信息,请参阅列的大小、 十进制数字、 传输八位字节长度和显示大小中附录 d:数据类型。For more information on decimal digits, see Column Size, Decimal Digits, Transfer Octet Length, and Display Size in Appendix D: Data Types.

NullablePtrNullablePtr
[输出]指向用于返回一个值,指示列是否允许 NULL 值的缓冲区。[Output] Pointer to a buffer in which to return a value that indicates whether the column allows NULL values. 从 IRD 的 SQL_DESC_NULLABLE 字段读取此值。This value is read from the SQL_DESC_NULLABLE field of the IRD. 值为以下值之一:The value is one of the following:

SQL_NO_NULLS:此列不允许 NULL 值。SQL_NO_NULLS: The column does not allow NULL values.

SQL_NULLABLE:列允许 NULL 值。SQL_NULLABLE: The column allows NULL values.

SQL_NULLABLE_UNKNOWN:该驱动程序无法确定列是否允许 NULL 值。SQL_NULLABLE_UNKNOWN: The driver cannot determine if the column allows NULL values.

返回Returns

SQL_SUCCESS、 SQL_SUCCESS_WITH_INFO、 SQL_STILL_EXECUTING、 SQL_ERROR 或 SQL_INVALID_HANDLE。SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

诊断Diagnostics

SQLDescribeCol返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO,可以通过调用获取关联的 SQLSTATE 值SQLGetDiagRecHandleType设置为 SQL_HANDLE_STMT,和一个处理StatementHandleWhen SQLDescribeCol returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_STMT and a Handle of StatementHandle. 下表列出了通常返回的 SQLSTATE 值SQLDescribeCol ,并解释了此函数; 每个上下文中的表示法"(数据挖掘)"之前 SQLSTATEs 返回由驱动程序管理器的说明。The following table lists the SQLSTATE values commonly returned by SQLDescribeCol and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. 与每个 SQLSTATE 值关联的返回代码是 SQL_ERROR,除非另有说明。The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

SQLSTATESQLSTATE ErrorError 描述Description
0100001000 常规警告General warning 特定于驱动程序的信息性消息。Driver-specific informational message. (函数返回 SQL_SUCCESS_WITH_INFO。)(Function returns SQL_SUCCESS_WITH_INFO.)
0100401004 字符串数据,右截断String data, right truncated 缓冲区* ColumnName是否不足够大以返回整个列名称,因此列名称已被截断。The buffer *ColumnName was not large enough to return the entire column name, so the column name was truncated. 在返回未截断的列名称的长度 *NameLengthPtrThe length of the untruncated column name is returned in *NameLengthPtr. (函数返回 SQL_SUCCESS_WITH_INFO。)(Function returns SQL_SUCCESS_WITH_INFO.)
0700507005 预定义语句不游标规范Prepared statement not a cursor-specification 与相关的语句StatementHandle未返回结果集。The statement associated with the StatementHandle did not return a result set. 没有任何列来描述。There were no columns to describe.
0700907009 描述符索引无效Invalid descriptor index (DM) 的参数指定的值ColumnNumber等于 0,而 SQL_ATTR_USE_BOOKMARKS 语句选项是 SQL_UB_OFF。(DM) The value specified for the argument ColumnNumber was equal to 0, and the SQL_ATTR_USE_BOOKMARKS statement option was SQL_UB_OFF.

为参数指定的值ColumnNumber大于结果集中的列数。The value specified for the argument ColumnNumber was greater than the number of columns in the result set.
08S0108S01 通讯链接失败Communication link failure 该驱动程序和驱动程序已连接到数据源之间的通信链接失败之前函数已完成处理。The communication link between the driver and the data source to which the driver was connected failed before the function completed processing.
HY000HY000 常规错误General error 有关其中没有任何特定的 SQLSTATE 和为其定义任何特定于实现的 SQLSTATE 出错。An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. 返回的错误消息SQLGetDiagRec*MessageText缓冲区描述错误以及其原因。The error message returned by SQLGetDiagRec in the *MessageText buffer describes the error and its cause.
HY001HY001 内存分配失败Memory allocation failure 该驱动程序无法分配支持执行或完成该函数所需的内存。The driver was unable to allocate memory required to support execution or completion of the function.
HY008HY008 操作已取消Operation canceled 异步处理的已启用StatementHandleAsynchronous processing was enabled for the StatementHandle. 调用该函数,和之前执行完毕SQLCancelSQLCancelHandle上调用了StatementHandleThe function was called, and before it completed execution, SQLCancel or SQLCancelHandle was called on the StatementHandle. 然后在再次调用该函数StatementHandleThen the function was called again on the StatementHandle.

调用该函数,和之前执行完毕SQLCancelSQLCancelHandle上调用了StatementHandle来自不同线程中多线程应用程序。The function was called, and before it completed execution, SQLCancel or SQLCancelHandle was called on the StatementHandle from a different thread in a multithread application.
HY010HY010 函数序列错误Function sequence error (DM) 为与之关联的连接句柄调用以异步方式执行的函数StatementHandle(DM) An asynchronously executing function was called for the connection handle that is associated with the StatementHandle. 此异步函数仍在执行时SQLDescribeCol调用。This asynchronous function was still executing when SQLDescribeCol was called.

(数据挖掘) SQLExecuteSQLExecDirect,或SQLMoreResults曾为StatementHandle和返回 SQL_PARAM_DATA_可用。(DM) SQLExecute, SQLExecDirect, or SQLMoreResults was called for the StatementHandle and returned SQL_PARAM_DATA_AVAILABLE. 数据已检索到的所有经过流处理参数之前调用此函数。This function was called before data was retrieved for all streamed parameters.

(DM) 的调用以异步方式执行的函数 (不是此类似) StatementHandle和仍在执行时调用此函数。(DM) An asynchronously executing function (not this one) was called for the StatementHandle and was still executing when this function was called.

(DM) 在调用之前已调用函数SQLPrepareSQLExecute,或该语句句柄上的目录函数。(DM) The function was called prior to calling SQLPrepare, SQLExecute, or a catalog function on the statement handle.

(数据挖掘) SQLExecuteSQLExecDirectSQLBulkOperations,或者SQLSetPos曾为StatementHandle和返回 SQL_NEED_DATA。(DM) SQLExecute, SQLExecDirect, SQLBulkOperations, or SQLSetPos was called for the StatementHandle and returned SQL_NEED_DATA. 数据已发送的所有执行时数据参数或列之前调用此函数。This function was called before data was sent for all data-at-execution parameters or columns.
HY013HY013 内存管理错误Memory management error 无法处理函数调用,因为基础内存对象无法访问,可能是由于内存不足的情况。The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.
HY090HY090 字符串或缓冲区长度无效Invalid string or buffer length (DM) 为参数指定的值BufferLength小于 0。(DM) The value specified for argument BufferLength was less than 0.
HY117HY117 由于未知的事务状态而挂起连接。Connection is suspended due to unknown transaction state. 仅断开连接,并允许使用只读的函数。Only disconnect and read-only functions are allowed. (DM) 有关挂起状态的详细信息,请参阅SQLEndTran 函数(DM) For more information about suspended state, see SQLEndTran Function.
HYT01HYT01 连接超时时间已到Connection timeout expired 连接超时期限过期之前的数据源响应此请求。The connection timeout period expired before the data source responded to the request. 通过设置连接超时期SQLSetConnectAttr,SQL_ATTR_CONNECTION_TIMEOUT。The connection timeout period is set through SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001IM001 驱动程序不支持此函数Driver does not support this function (DM) 驱动程序与相关联StatementHandle不支持该函数。(DM) The driver associated with the StatementHandle does not support the function.
IM017IM017 轮询异步通知模式中禁用Polling is disabled in asynchronous notification mode 只要使用通知模型,将禁用轮询。Whenever the notification model is used, polling is disabled.
IM018IM018 SQLCompleteAsync尚未调用以完成此句柄上以前的异步操作。SQLCompleteAsync has not been called to complete the previous asynchronous operation on this handle. 如果句柄上的上一个函数调用返回 SQL_STILL_EXECUTING,如果启用通知模式,则SQLCompleteAsync必须要对其进行后期处理并完成该操作的句柄上调用。If the previous function call on the handle returns SQL_STILL_EXECUTING and if notification mode is enabled, SQLCompleteAsync must be called on the handle to do post-processing and complete the operation.

SQLDescribeCol可以返回任何可由返回的 SQLSTATE SQLPrepareSQLExecute时后,调用SQLPrepare之前SQLExecute,取决于当数据源的计算结果与语句句柄相关联的 SQL 语句。SQLDescribeCol can return any SQLSTATE that can be returned by SQLPrepare or SQLExecute when called after SQLPrepare and before SQLExecute, depending on when the data source evaluates the SQL statement associated with the statement handle.

出于性能原因,应用程序不应调用SQLDescribeCol语句之前执行。For performance reasons, an application should not call SQLDescribeCol before executing a statement.

注释Comments

应用程序通常会调用SQLDescribeCol后调用SQLPrepare和之前或之后对的关联调用SQLExecuteAn application typically calls SQLDescribeCol after a call to SQLPrepare and before or after the associated call to SQLExecute. 应用程序还可以调用SQLDescribeCol后调用SQLExecDirectAn application can also call SQLDescribeCol after a call to SQLExecDirect. 有关详细信息,请参阅结果集元数据For more information, see Result Set Metadata.

SQLDescribeCol检索的列名称、 类型和长度 パ选择语句。SQLDescribeCol retrieves the column name, type, and length generated by a SELECT statement. 如果列是表达式,*ColumnName是空字符串或驱动程序定义的名称。If the column is an expression, *ColumnName is either an empty string or a driver-defined name.

备注

ODBC 作为扩展,即使 Open Group 和 SQL 访问组调用级别接口规范未指定的选项都支持 SQL_NULLABLE_UNKNOWN SQLDescribeColODBC supports SQL_NULLABLE_UNKNOWN as an extension, even though the Open Group and SQL Access Group Call Level Interface specification does not specify the option for SQLDescribeCol.

有关信息For information about 请参阅See
将缓冲区绑定到结果集中的列Binding a buffer to a column in a result set SQLBindColSQLBindCol
取消语句处理Canceling statement processing SQLCancelSQLCancel
在结果集中返回列的相关信息Returning information about a column in a result set SQLColAttributeSQLColAttribute
正在提取多行数据Fetching multiple rows of data SQLFetchSQLFetch
返回数的结果集列Returning the number of result set columns SQLNumResultColsSQLNumResultCols
准备执行的语句Preparing a statement for execution SQLPrepareSQLPrepare

请参阅See Also

ODBC API 参考 ODBC API Reference
ODBC 头文件ODBC Header Files