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。x 應用程式使用 ODBC 2。x 驅動程式或 ODBC 2。x 應用程式使用 ODBC 3。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時，可以藉由呼叫 SQLGetDiagRec 搭配 SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句柄來取得相關聯的 SQLSTATE 值。 下表列出 SQLDescribeParam 通常傳回的 SQLSTATE 值，並說明此函式內容中的每個值;表示法 “（DM）” 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 07009 | 無效的描述元索引 | （DM） 為 argument ParameterNumber 指定的值小於 1。 為 argument ParameterNumber 指定的值大於相關聯 SQL 語句中的參數數目。 參數標記是非 DML 語句的一部分。 參數標記是 SELECT 清單的一部分。 |
| 08S01 | 通訊連結失敗 | 驅動程式與驅動程式連線的數據源之間的通訊連結在函式完成處理之前失敗。 |
| 21S01 | 插入值清單不符合資料列清單 | INSERT 語句中的參數數目與語句中名為的數據表中的數據行數目不符。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 作業已取消 | 已針對 StatementHandle 啟用異步處理。 已呼叫函式，並在完成執行之前，在 StatementHandle 上呼叫 SQLCancel 或 SQLCancelHandle。 然後在 StatementHandle 上再次呼叫函式。 呼叫函式，並在完成執行之前，從多線程應用程式中的不同線程呼叫語句Handle 或 SQLCancelHandle。 |
| HY010 | 函式順序錯誤 | （DM） 在呼叫 StatementHandle 的 SQLPrepare 或 SQLExecDirect 之前呼叫函式。 （DM） 已針對與 StatementHandle 相關聯的連接句柄呼叫異步執行函式。 呼叫 SQLDescribeParam 函式時，這個異步函式仍在執行中。 （DM） 呼叫 StatementHandle 的異步執行函式（而非此函式），並在呼叫此函式時仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，並傳回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 函式 |