Long Data 和 SQLSetPos 和 SQLBulkOperations

如同 SQL 語句中的參數,使用 SQLBulkOperationsSQLSetPos 更新資料列,或插入 SQLBulkOperations 列時,可能會傳送長資料。 資料會分段傳送,並多次呼叫 SQLPutData。 在執行時傳送資料的欄位稱為 執行時資料欄位

備註

應用程式實際上可以在執行時使用 SQLPutData 傳送任何類型的資料,儘管只能分段傳送字元和二進位資料。 然而,如果資料足夠小到能放入單一緩衝區,通常沒有理由使用 SQLPutData。 綁定緩衝區後讓驅動程式從緩衝區取回資料會簡單得多。

由於長資料欄位通常不會被綁定,應用程式必須在呼叫 SQLBulkOperationsSQLSetPos 前先綁定該欄位,呼叫 SQLBulkOperationsSQLSetPos 後則解除綁定。 欄位必須綁定,因為 SQLBulkOperationsSQLSetPos 只對綁定欄位操作,且必須解綁,才能使用 SQLGetData 從欄位擷取資料。

執行時傳送資料時,應用程式會執行以下步驟:

  1. 在列集緩衝區中放置一個 32 位元的值,而非資料值。 這個值會在之後回傳給應用程式,因此應用程式應該將其設為有意義的值,例如包含資料的欄位編號或檔案的句柄。

  2. 將長度/指示緩衝區的值設為 SQL_LEN_DATA_AT_EXEC(長度)巨集的結果。 此值向驅動程式表示參數資料將隨 SQLPutData 一同傳送。 長度值用於將長資料傳送到需要知道將傳送多少位元組長資料以便預先分配空間的資料來源。 為了判斷資料來源是否需要此值,應用程式會呼叫帶有 SQL_NEED_LONG_DATA_LEN 選項的 SQLGetInfo 。 所有驅動程式都必須支援此巨集;如果資料來源不要求位元組長度,驅動程式可以忽略此設定。

  3. 呼叫 SQLBulkOperationsSQLSetPos。 驅動程式發現長度/指示器緩衝區包含SQL_LEN_DATA_AT_EXEC(長度)巨集的結果,並回傳SQL_NEED_DATA作為函式的返回值。

  4. 呼叫 SQLParamData ,回應 SQL_NEED_DATA 回傳值。 若需要傳送長資料, SQLParamData 會回傳 SQL_NEED_DATA。 在 ValuePtrPtr 參數所指向的緩衝區中,驅動程式回傳應用程式放置於列集緩衝區的唯一值。 如果執行時資料欄位不只一個,應用程式會用這個值來決定要傳送資料的欄位;驅動程式不需以特定順序請求執行時資料欄位的資料。

  5. 呼叫 SQLPutData 將欄位資料傳送給驅動程式。 如果欄位資料無法集中在單一緩衝區,如長資料常見情況,應用程式會反覆呼叫 SQLPutData ,將資料分段傳送;重新組合資料的責任在於驅動程式與資料來源。 若應用程式傳遞了空終止字串資料,驅動程式或資料來源必須在重組過程中移除空終止字元。

  6. 再次呼叫 SQLParamData ,表示已傳送該欄的所有資料。 如果存在尚未傳送資料的執行時資料欄位,驅動程式會回傳 SQL_NEED_DATA 並提供下一個執行時資料欄位的唯一值;應用程式將返回到步驟 5。 如果所有執行時資料欄位的資料都已傳送,該列的資料會傳送到資料來源。 SQLParamData 會回傳 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO,並且可以回傳任何 SQLBulkOperationsSQLSetPos 能回傳的 SQLSTATE。

SQLBulkOperationsSQLSetPos 回傳 SQL_NEED_DATA 後,且在最後一個執行時資料欄位的資料尚未完全傳送完畢之前,該語句會處於 Need Data 狀態。 在此狀態下,應用程式只能呼叫 SQLPutDataSQLParamDataSQLCancelSQLGetDiagFieldSQLGetDiagRec;其他所有函式都會回傳 SQLSTATE HY010(函式序列錯誤)。 呼叫 SQLCancel 會取消該語句的執行,並將其回復到先前的狀態。 更多資訊請參閱 附錄B:ODBC狀態轉換表