SQLDescribeParam 函数

一致性
引入的版本：ODBC 1.0 标准合规性：ODBC

摘要
SQLDescribeParam 返回与准备好的 SQL 语句关联的参数标记的说明。 此信息也可在 IPD 的字段中获取。

语法

  
SQLRETURN SQLDescribeParam(  
      SQLHSTMT        StatementHandle,  
      SQLUSMALLINT    ParameterNumber,  
      SQLSMALLINT *   DataTypePtr,  
      SQLULEN *       ParameterSizePtr,  
      SQLSMALLINT *   DecimalDigitsPtr,  
      SQLSMALLINT *   NullablePtr);  

参数

StatementHandle
[输入]语句句柄。

ParameterNumber
[输入]参数标记编号按顺序按顺序排序，从 1 开始递增参数。

DataTypePtr
[输出]指向要在其中返回参数的 SQL 数据类型的缓冲区的指针。 此值从 IPD 的“SQL_DESC_CONCISE_TYPE记录”字段读取。 这是附录 D： 数据类型的 SQL 数据类型 部分中的值之一，或特定于驱动程序的 SQL 数据类型。

在 ODBC 3 中。x、SQL_TYPE_DATE、SQL_TYPE_TIME或SQL_TYPE_TIMESTAMP将分别在 *DataTypePtr 中返回日期、时间或时间戳数据;在 ODBC 2 中。将返回 x、SQL_DATE、SQL_TIME 或 SQL_TIMESTAMP。 当 ODBC 2 时，驱动程序管理器执行所需的映射。x 应用程序正在使用 ODBC 3。x 驱动程序或当 ODBC 3 时。x 应用程序正在使用 ODBC 2。x 驱动程序。

当书签列) 的 ColumnNumber 等于 0 (时，将在 *DataTypePtr 中为可变长度书签返回SQL_BINARY。 如果 ODBC 3 使用书签，则返回 (SQL_INTEGER。使用 ODBC 2 的 x 应用程序。x 驱动程序或由 ODBC 2。使用 ODBC 3 的 x 应用程序。x driver.)

有关详细信息，请参阅附录 D 中的 SQL 数据类型 ：数据类型。 有关特定于驱动程序的 SQL 数据类型的信息，请参阅驱动程序的文档。

ParameterSizePtr
[输出]指向缓冲区的指针，其中返回数据源定义的相应参数标记的列或表达式的大小（以字符为单位）。 有关列大小的详细信息，请参阅 列大小、十进制数字、传输八进制长度和显示大小。

DecimalDigitsPtr
[输出]指向缓冲区的指针，在缓冲区中返回由数据源定义的相应参数的列或表达式的十进制位数。 有关十进制数字的详细信息，请参阅 列大小、十进制数字、传输八进制长度和显示大小。

NullablePtr
[输出]指向缓冲区的指针，在该缓冲区中返回一个值，该值指示参数是否允许 NULL 值。 此值从 IPD 的 SQL_DESC_NULLABLE 字段中读取。 下列情况之一：

• SQL_NO_NULLS：参数不允许 NULL 值， (这是) 默认值。

• SQL_NULLABLE：参数允许 NULL 值。

• SQL_NULLABLE_UNKNOWN：驱动程序无法确定 参数是否允许 NULL 值。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。

诊断

当 SQLDescribeParam 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过使用 handleType 为 SQL_HANDLE_STMT 和 Handle ofStatementHandle 调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLDescribeParam 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值：表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATE 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。

SQLSTATE	错误	说明
01000	常规警告	特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.)
07009	描述符索引无效	(DM) 为参数 ParameterNumber 指定的值小于 1。 为参数 ParameterNumber 指定的值大于关联的 SQL 语句中的参数数。 参数标记是非 DML 语句的一部分。 参数标记是 SELECT 列表的一部分。
08S01	通信链接失败	在函数完成处理之前，驱动程序与所连接的数据源之间的通信链接失败。
21S01	插入值列表与列列表不匹配	INSERT 语句中的参数数与语句中名为 的表中的列数不匹配。
HY000	常规错误	发生错误，其中没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec 在 *MessageText 缓冲区中返回的错误消息描述了错误及其原因。
HY001	内存分配错误	驱动程序无法分配支持执行或完成函数所需的内存。
HY008	操作已取消	已为 StatementHandle 启用异步处理。 调用了函数，在它完成执行之前，在 StatementHandle 上调用了 SQLCancel 或 SQLCancelHandle。 然后，在 StatementHandle 上再次调用函数。 函数已调用，在它完成执行之前，在 StatementHandle 上从多线程应用程序中的不同线程调用 SQLCancel 或 SQLCancelHandle。
HY010	函数序列错误	(DM) 在为 StatementHandle 调用 SQLPrepare 或 SQLExecDirect 之前调用了 函数。 (DM) 为与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLDescribeParam 函数时，此异步函数仍在执行。 (DM) 为 StatementHandle 调用了异步执行的函数， (不是此函数) ，在调用此函数时仍在执行。 (DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 已为 StatementHandle 调用，并返回SQL_NEED_DATA。 在针对所有数据执行参数或列发送数据之前调用了此函数。
HY013	内存管理错误	无法处理函数调用，因为无法访问基础内存对象，可能是由于内存不足。
HY117	由于事务状态未知，连接已暂停。 仅允许断开连接和只读函数。	(DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。
HYT01	超过连接超时时间	在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置。
IM001	驱动程序不支持此函数	(DM) 与 StatementHandle 关联的驱动程序不支持 函数。
IM017	在异步通知模式下禁用轮询	每当使用通知模型时，将禁用轮询。
IM018	尚未调用 SQLCompleteAsync 来完成此句柄上的上一个异步操作。	如果对句柄的上一个函数调用返回SQL_STILL_EXECUTING并且启用了通知模式，则必须在句柄上调用 SQLCompleteAsync 以执行后期处理并完成操作。

注释

参数标记按增加参数顺序进行编号，从 1 开始，按它们在 SQL 语句中出现的顺序进行编号。

SQLDescribeParam 不返回类型 (SQL 语句中参数的输入、输入/输出或输出) 。 除了在对过程的调用中，SQL 语句中的所有参数都是输入参数。 为了确定对过程调用中每个参数的类型，应用程序调用 SQLProcedureColumns。

有关详细信息，请参阅 描述参数。

代码示例

以下示例提示用户输入 SQL 语句，然后准备该语句。 接下来，它会调用 SQLNumParams 来确定语句是否包含任何参数。 如果语句包含参数，它将调用 SQLDescribeParam 来描述这些参数，并调用 SQLBindParameter 来绑定这些参数。 最后，它会提示用户输入任何参数的值，然后执行 语句。

SQLCHAR       Statement[100];  
SQLSMALLINT   NumParams, i, DataType, DecimalDigits, Nullable;  
SQLUINTEGER   ParamSize;  
SQLHSTMT      hstmt;  
  
// Prompt the user for an SQL statement and prepare it.  
GetSQLStatement(Statement);  
SQLPrepare(hstmt, Statement, SQL_NTS);  
  
// Check to see if there are any parameters. If so, process them.  
SQLNumParams(hstmt, &NumParams);  
if (NumParams) {  
   // Allocate memory for three arrays. The first holds pointers to buffers in which  
   // each parameter value will be stored in character form. The second contains the  
   // length of each buffer. The third contains the length/indicator value for each  
   // parameter.  
   SQLPOINTER * PtrArray = (SQLPOINTER *) malloc(NumParams * sizeof(SQLPOINTER));  
   SQLINTEGER * BufferLenArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));  
   SQLINTEGER * LenOrIndArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));  
  
   for (i = 0; i < NumParams; i++) {  
   // Describe the parameter.  
   SQLDescribeParam(hstmt, i + 1, &DataType, &ParamSize, &DecimalDigits, &Nullable);  
  
   // Call a helper function to allocate a buffer in which to store the parameter  
   // value in character form. The function determines the size of the buffer from  
   // the SQL data type and parameter size returned by SQLDescribeParam and returns  
   // a pointer to the buffer and the length of the buffer.  
   AllocParamBuffer(DataType, ParamSize, &PtrArray[i], &BufferLenArray[i]);  
  
   // Bind the memory to the parameter. Assume that we only have input parameters.  
   SQLBindParameter(hstmt, i + 1, SQL_PARAM_INPUT, SQL_C_CHAR, DataType, ParamSize,  
         DecimalDigits, PtrArray[i], BufferLenArray[i],  
         &LenOrIndArray[i]);  
  
   // Prompt the user for the value of the parameter and store it in the memory  
   // allocated earlier. For simplicity, this function does not check the value  
   // against the information returned by SQLDescribeParam. Instead, the driver does  
   // this when the statement is executed.  
   GetParamValue(PtrArray[i], BufferLenArray[i], &LenOrIndArray[i]);  
   }  
}  
  
// Execute the statement.  
SQLExecute(hstmt);  
  
// Process the statement further, such as retrieving results (if any) and closing the  
// cursor (if any). Code not shown.  
  
// Free the memory allocated for each parameter and the memory allocated for the arrays  
// of pointers, buffer lengths, and length/indicator values.  
for (i = 0; i < NumParams; i++) free(PtrArray[i]);  
free(PtrArray);  
free(BufferLenArray);  
free(LenOrIndArray);  

相关函数

有关以下方面的信息	请参阅
将缓冲区绑定到参数	SQLBindParameter 函数
取消语句处理	SQLCancel 函数
执行准备好的 SQL 语句	SQLExecute 函数
准备要执行的语句	SQLPrepare 函数

另请参阅

ODBC API 参考
ODBC 头文件