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(对于书签列),SQL_BINARY在 *DataTypePtr返回可变长度书签。 (如果 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 of SQL_HANDLE_STMT 和 StatementHandle 句柄调用 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。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY008 操作已取消 StatementHandle 启用了异步处理。 调用了该函数,在完成执行之前,对 StatementHandle 调用了 SQLCancel 或 SQLCancelHandle。 然后,在 StatementHandle再次调用该函数。

调用了函数,在完成执行之前,SQLCancel 或 SQLCancelHandle 从多线程应用程序中的不同线程调用 StatementHandle
HY010 函数序列错误 (DM) 在为 StatementHandle 调用 SQLPrepareSQLExecDirect 之前调用了函数

(DM) 为与 StatementHandle 关联的连接句柄调用异步执行函数。 调用 SQLDescribeParam 函数时,此异步函数仍在执行。

(DM) 为 StatementHandle 调用异步执行函数(而不是此函数),并在调用此函数时仍在执行。

(DM) 为 StatementHandle 调用了 SQLExecuteSQLExecDirectSQLBulkOperationsSQLSetPos,并返回了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 a 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 头文件