DBMS 將 長資料 定義為任何字元或二進位資料,大小超過某個字元,例如 254 個字元。 有時無法將整個長資料的項目儲存在記憶體中,例如當該項目代表長文字文件或點陣圖時。 由於此類資料無法儲存在單一緩衝區,資料來源會在執行該語句時,分段以 SQLPutData 傳送給驅動程式。 執行時傳送資料的參數稱為 執行時資料參數。
備註
應用程式實際上可以在執行時使用 SQLPutData 傳送任何類型的資料,儘管只能分段傳送字元和二進位資料。 然而,如果資料足夠小到能放入單一緩衝區,通常沒有理由使用 SQLPutData。 綁定緩衝區後讓驅動程式從緩衝區取回資料會簡單得多。
執行時傳送資料時,應用程式執行以下動作:
傳遞一個 32 位元的值,用於在 SQLBindParameter 的 ParameterValuePtr 參數中識別該參數,而不是傳遞緩衝區的位址。 這個數值不會被駕駛者分析。 之後會傳回至應用程式,因此應對應用程式有意義。 例如,它可以是參數的編號或包含資料的檔案的控制代碼。
傳遞 SQLBindParameterStrLen_or_IndPtr參數中長度/指示緩衝區的位址。
將SQL_DATA_AT_EXEC或SQL_LEN_DATA_AT_EXEC(長度)巨集結果儲存在長度/指示緩衝區中。 這兩個值都向驅動程式表示該參數的資料將隨 SQLPutData 一同傳送。 SQL_LEN_DATA_AT_EXEC(長度)用於將長資料傳送到需要知道將傳送多少位元組長資料以便預先分配空間的資料來源。 為了判斷資料來源是否需要此值,應用程式會呼叫 SQLGetInfo 並啟用 SQL_NEED_LONG_DATA_LEN 選項。 所有驅動程式都必須支援此巨集;如果資料來源不要求位元組長度,驅動程式可以忽略此設定。
呼叫 SQLExecute 或 SQLExecDirect。 驅動程式發現長度/指示緩衝區包含 SQL_DATA_AT_EXEC 值或 SQL_LEN_DATA_AT_EXEC(length)宏的結果,並回傳 SQL_NEED_DATA 作為函式的回傳值。
呼叫 SQLParamData ,回應 SQL_NEED_DATA 回傳值。 若需要傳送長資料, SQLParamData 會回傳 SQL_NEED_DATA。 在 ValuePtrPtr 參數所指向的緩衝區中,驅動程式回傳識別執行時資料參數的值。 若執行時資料參數多於一個,應用程式必須使用此值決定要傳送資料的參數;驅動程式無需以特定順序請求執行時資料參數資料。
呼叫 SQLPutData 將參數資料傳送給驅動程式。 如果參數資料無法放入單一緩衝區,如長資料常見的情況,應用程式會反覆呼叫 SQLPutData ,將資料分段傳送;重新組合資料的責任在於驅動程式與資料來源。 若應用程式傳遞了空終止字串資料,驅動程式或資料來源必須在重組過程中移除空終止字元。
再次呼叫 SQLParamData ,表示已傳送所有參數資料。 若有任何執行時參數的資料尚未傳送,驅動程式會回傳 SQL_NEED_DATA 及識別下一個參數的值;應用程式會返回步驟 6。 如果所有執行參數的資料都已傳送,則此語句會被執行。 SQLParamData 回傳 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO,且可回傳 SQLExecute 或 SQLExecDirect 能回傳的任何回傳值或診斷值。
在 SQLExecute 或 SQLExecDirect 回傳 SQL_NEED_DATA 後,且在最後一個執行時資料完全傳送完畢之前,該語句會處於 Need Data 狀態。 當語句處於 Need Data 狀態時,應用程式只能呼叫 SQLPutData、 SQLParamData、 SQLCancel、 SQLGetDiagField 或 SQLGetDiagRec;其他所有函式都會回傳 SQLSTATE HY010(函式序列錯誤)。 呼叫 SQLCancel 會取消該語句的執行,並將其回復到先前的狀態。 更多資訊請參閱 附錄B:ODBC狀態轉換表。
關於在執行時傳送資料的範例,請參見 SQLPutData 函式描述。