傳送長資料

DBMS 會將「長資料」定義為超過特定大小的任何字元或二進位資料，例如超出 254 個字元。 整個長資料項目可能無法儲存在記憶體中，比方說該項目代表的是長篇文字文件或點陣圖。 由於這類資料無法儲存在單一緩衝區中，因此在執行陳述式時，資料來源會將資料與 SQLPutData 一起分段傳送至驅動程式。 在執行時間傳送資料所使用的參數就是所謂的「資料執行中參數」。

注意

雖然只有字元和二進位資料可以分段傳送，但是應用程式實際上還是可以使用 SQLPutData 在執行時間傳送任何類型的資料。 不過，如果資料夠小而足以容納在單一緩衝區中，通常就沒有理由使用 SQLPutData。 繫結緩衝區，並讓驅動程式從緩衝區擷取資料是更為容易的作法。

若要在執行時間傳送資料，應用程式會執行下列動作：

1. 傳遞 32 位值以識別 SQLBindParameter 中 ParameterValuePtr 引數中的參數，而不是傳遞緩衝區的位址。 驅動程式不會分析此值。 稍後會將該值傳回至應用程式，因此應是代表應用程式的某些項目。 例如，可能是參數的數目，或包含資料的檔案控制代碼。

2. 在 SQLBindParameter 的 StrLen_or_IndPtr 引數中傳遞長度/指標緩衝區的位址。

3. 將 SQL_DATA_AT_EXEC 或 SQL_LEN_DATA_AT_EXEC (長度) 巨集的結果儲存在長度/指標緩衝區中。 這兩個值都表示驅動程式會使用 SQLPutData 傳送參數的資料。 SQL_LEN_DATA_AT_EXEC (長度) 是在將長資料傳送至需要知道要傳送多少個長資料位元組的資料來源時使用，以便預先配置空間。 若要判斷資料來源是否需要此值，應用程式會使用 SQL_NEED_LONG_DATA_LEN 選項呼叫 SQLGetInfo。 所有驅動程式都必須支援此巨集；如果資料來源不需要位元組長度的值，則驅動程式可以忽略它。

4. 呼叫 SQLExecute 或 SQLExecDirect。 驅動程式發現長度/指標緩衝區包含值 SQL_DATA_AT_EXEC 或 SQL_LEN_DATA_AT_EXEC (長度) 巨集的結果，並傳回 SQL_NEED_DATA 作為函式的傳回值。

5. 呼叫 SQLParamData 以回應 SQL_NEED_DATA 傳回值。 如果需要傳送長資料，SQLParamData 會傳回 SQL_NEED_DATA。 在 ValuePtrPtr 引數所指向的緩衝區中，驅動程式會傳回可識別執行中資料參數的值。 如果有一個以上的資料執行中參數，則應用程式必須使用此值來判斷要傳送資料的參數；驅動程式不需要以任何特定順序要求資料執行中參數的資料。

6. 呼叫 SQLPutData 以將參數資料傳送至驅動程式。 如果單一緩衝區無法容納參數資料 (如同長資料的常見情況)，則應用程式會重複呼叫 SQLPutData 以分段傳送資料；由驅動程式和資料來源決定是否須將資料重新組合。 如果應用程式傳遞以 null 終止的字串資料，在重新組合的過程中，驅動程式或資料來源必須移除 null 終止字元。

7. 再次呼叫 SQLParamData 來指出已傳送該參數的所有資料。 如果有任何未傳送資料的資料執行中參數，驅動程式會傳回 SQL_NEED_DATA 以及用於識別下一個參數的值，應用程式會傳回步驟 6。 如果所有資料執行中參數的資料已傳送，則會執行陳述式。 SQLParamData 會傳回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO，並可傳回 SQLExecute 或 SQLExecDirect 所能傳回的任何傳回值或診斷。

在 SQLExecute 或 SQLExecDirect 傳回 SQL_NEED_DATA 之後，而在資料完全傳送給最後一個資料執行中參數之前，陳述式會處於「需要資料」狀態。 雖然陳述式處於「需要資料」狀態，但應用程式只能呼叫 SQLPutData、SQLParamData、SQLCancel、SQLGetDiagField 或 SQLGetDiagRec；所有其他函式都會傳回 SQLSTATE HY010 (函式序列錯誤)。 呼叫 SQLCancel 會取消陳述式的執行，並返回至其先前的狀態。 如需詳細資訊，請參閱附錄 B：ODBC 狀態轉換資料表。

如需在執行時間傳送資料的範例，請參閱 SQLPutData 函式描述。