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 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 函式 |