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

另請參閱

ODBC API 參考
ODBC 標頭檔
使用 SQLGetData 擷取輸出參數