SQLParamData 函式
一致性
引進版本：ODBC 1.0 標準合規性：ISO 92
摘要
SQLParamData 會與 SQLPutData 搭配使用，以在語句運行時間提供參數數據，並使用 SQLGetData 來擷取數據流輸出參數數據。
語法
SQLRETURN SQLParamData(
SQLHSTMT StatementHandle,
SQLPOINTER * ValuePtrPtr);
引數
StatementHandle
[輸入]語句句柄。
ValuePtrPtr
[輸出]緩衝區的指標，這個緩衝區會傳回 SQLBindParameter 中指定的 ParameterValuePtr 緩衝區位址（適用於參數數據），或 SQLBindCol 中所指定之 TargetValuePtr 緩衝區位址（針對數據行數據），如SQL_DESC_DATA_PTR描述元記錄字段中所包含。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NEED_DATA、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR、SQL_INVALID_HANDLE或SQL_PARAM_DATA_AVAILABLE。
診斷
當 SQLParamData 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以使用SQL_HANDLE_STMT的 HandleType 和 StatementHandle 句柄呼叫 SQLGetDiagRec 來取得相關聯的 SQLSTATE 值。 下表列出 SQLParamData 通常傳回的 SQLSTATE 值，並說明此函式內容中的每個值;表示法 “（DM）” 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 07006 | 受限制的數據類型屬性違規 | 系結參數之 SQLBindParameter 中 ValueType 自變數所識別的數據值無法轉換成 SQLBindParameter 中 ParameterType 自變數所識別的數據類型。 系結為 SQL_PARAM_INPUT_OUTPUT 或 SQL_PARAM_OUTPUT 的參數所傳回的數據值無法轉換成 SQLBindParameter 中 ValueType 自變數所識別的數據類型。 （如果無法轉換一或多個數據列的數據值，但成功傳回一或多個數據列，則此函式會傳回SQL_SUCCESS_WITH_INFO。 |
| 08S01 | 通訊連結失敗 | 驅動程式與驅動程式連線的數據源之間的通訊連結在函式完成處理之前失敗。 |
| 22026 | 字串數據，長度不符 | SQLGetInfo 中的SQL_NEED_LONG_DATA_LEN資訊類型是 “Y”，而且會針對long 參數傳送的數據較少（數據類型是SQL_LONGVARCHAR、SQL_LONGVARBINARY或長數據源特定數據類型），而不是在 SQLBindParameter 中使用 StrLen_or_IndPtr 自變數所指定。 SQLGetInfo 中的SQL_NEED_LONG_DATA_LEN資訊類型是 “Y”，而且傳送的數據比使用 SQLBulkOperations 新增或更新 SQLBulkOperations 或 SQLSetPos 更新的數據列數據列中所指定的長度緩衝區還要少。數據類型SQL_LONGVARCHAR、SQL_LONGVARBINARY或長數據源特定數據類型。 |
| 40001 | 串行化失敗 | 交易因為與另一個交易發生資源死結而回復。 |
| 40003 | 語句完成未知 | 此函式執行期間相關聯的連接失敗，且無法判斷交易的狀態。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 作業已取消 | 已針對 StatementHandle 啟用異步處理。 已呼叫函式，並在完成執行之前，在 StatementHandle 上呼叫 SQLCancel 或 SQLCancelHandle;然後在 StatementHandle 上再次呼叫函式。 呼叫函式，並在完成執行之前，從多線程應用程式中的不同線程呼叫語句Handle 或 SQLCancelHandle。 |
| HY010 | 函式順序錯誤 | （DM） 先前的函數調用不是對 SQLExecDirect、SQLExecute、SQLBulkOperations 或 SQLSetPos 的呼叫，因為傳回碼是SQL_NEED_DATA，或先前的函數調用是 SQLPutData 的呼叫。 先前的函數調用是 SQLParamData 的呼叫。 （DM） 已針對與 StatementHandle 相關聯的連接句柄呼叫異步執行函式。 呼叫 SQLParamData 函式時，這個異步函式仍在執行中。 （DM） 呼叫 StatementHandle 的異步執行函式（而非此函式），並在呼叫此函式時仍在執行中。 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，並傳回SQL_NEED_DATA。 在針對所有數據執行中參數或數據行傳送數據之前，會呼叫 SQLCancel 。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY117 | 聯機因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式。 |
| HYT01 | 已超過連線逾時 | 在數據源回應要求之前，連線逾時期限已過期。 線上逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 對應至 StatementHandle 的驅動程式不支援 函式。 |
| IM017 | 在異步通知模式中停用輪詢 | 每當使用通知模型時，輪詢就會停用。 |
| IM018 | 尚未呼叫 SQLCompleteAsync ，以完成此句柄上的先前異步操作。 | 如果句柄上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式， 則必須在句柄上呼叫 SQLCompleteAsync ，才能執行後續處理並完成作業。 |
如果在 傳送 SQL 語句中參數的數據時呼叫 SQLParamData ，它可以傳回任何 SQLSTATE，此 SQLSTATE 可由呼叫的函式傳回來執行語句 （SQLExecute 或 SQLExecDirect）。 如果在傳送要更新或加入 SQLBulkOperations 的數據行數據或以 SQLSetPos 進行更新時呼叫，它可以傳回 SQLBulkOperations 或 SQLSetPos 可傳回的任何 SQLSTATE。
註解
您可以呼叫 SQLParamData 來提供兩個用途的數據執行中數據：呼叫 SQLExecute 或 SQLExecDirect 時所使用的參數數據，或呼叫 SQLSetPos 時所使用的數據行數據，或由 SQLBulkOperations 呼叫或更新時所使用的數據行數據。 在運行時間， SQLParamData 會傳回應用程式，指出驅動程式需要哪些數據。
當應用程式呼叫 SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 時，如果驅動程式需要數據執行時，就會傳回SQL_NEED_DATA。 然後，應用程式會呼叫 SQLParamData 來判斷要傳送的數據。 如果驅動程式需要參數數據，驅動程式會在 *ValuePtrPtr 輸出緩衝區中傳回應用程式放入數據列集緩衝區中的值。 應用程式可以使用此值來判斷驅動程式所要求的參數數據。 如果驅動程式需要數據行數據，驅動程式會在 *ValuePtrPtr 緩衝區中傳回原本系結數據行的位址，如下所示：
系結地址 + 系結位移 + （（列號 - 1） x 元素大小）
其中變數的定義如下表所示。
| 變數 | 描述 |
|---|---|
| 系結位址 | SQLBindCol 中使用 TargetValuePtr 自變數指定的位址。 |
| 系結位移 | 儲存在具有 SQL_ATTR_ROW_BIND_OFFSET_PTR 語句屬性之位址的值。 |
| 資料列號碼 | 數據列集中以 1 為起始的數據列數目。 如果是預設的單一數據列擷取，這是 1。 |
| 元素大小 | 數據與長度/指標緩衝區的 SQL_ATTR_ROW_BIND_TYPE 語句屬性值。 |
它也會傳回SQL_NEED_DATA，這是應用程式應該呼叫 SQLPutData 來傳送數據的指標。
應用程式 會視需要呼叫 SQLPutData ，以傳送數據行或參數的數據執行中數據。 針對數據行或參數傳送所有數據之後，應用程式會再次呼叫 SQLParamData 。 如果 SQLParamData 再次傳回SQL_NEED_DATA，則必須針對另一個參數或數據行傳送數據。 因此，應用程式會再次呼叫 SQLPutData。 如果已針對所有參數或數據行傳送所有數據執行中數據，則 SQLParamData 會傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，則會未定義 *ValuePtrPtr 中的值，而且可以執行 SQL 語句或 SQLBulkOperations 或 SQLSetPos 呼叫。
如果 SQLParamData 為不會影響數據源上任何數據列的搜尋更新或刪除語句提供參數數據，則對 SQLParamData 的呼叫會傳回SQL_NO_DATA。
如需如何在語句運行時間傳遞數據執行參數數據的詳細資訊，請參閱 SQLBindParameter 和傳送長數據中的。 如需如何更新或新增數據執行數據行數據的詳細資訊，請參閱 SQLSetPos 中的<使用 SQLSetPos>一節、SQLBulkOperations 中的，以及 Long Data 和 SQLSetPos 和 SQLBulkOperations。
您可以呼叫 SQLParamData 來擷取串流輸出參數。 當 SQLMoreResults、 SQLExecute、 SQLGetData 或 SQLExecDirect 傳回SQL_PARAM_DATA_AVAILABLE時，請呼叫 SQLParamData 來判斷哪個參數具有可用的值。 如需SQL_PARAM_DATA_AVAILABLE和串流輸出參數的詳細資訊，請參閱 使用 SQLGetData 擷取輸出參數。
程式碼範例
請參閱 SQLPutData。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至參數 | SQLBindParameter 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 傳回語句中參數的相關信息 | SQLDescribeParam 函式 |
| 執行 SQL 語句 | SQLExecDirect 函式 |
| 執行備妥的 SQL 語句 | SQLExecute 函式 |
| 在運行時間傳送參數數據 | SQLPutData 函式 |