SQLDescribeParam 函式

文章
08/21/2023

一致性
引進的版本：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 函式

另請參閱

ODBC API 參考
 ODBC 標頭檔

分享方式：

SQLDescribeParam 函式

語法

引數

傳回

診斷

註解

程式碼範例

另請參閱

意見反映

意見反映

更多資源

分享方式：

SQLDescribeParam 函式

語法

引數

傳回

診斷

註解

程式碼範例

相關函數

另請參閱

意見反映

意見反映

更多資源