長資料和 SQLSetPos 與 SQLBulkOperations

如同 SQL 陳述式中的參數，當透過 SQLBulkOperations 或 SQLSetPos 更新資料列，或是過 SQLBulkOperations 插入資料列時，可以傳送長資料。 資料會分成多段，並多次呼叫 SQLPutData 來傳送。 在執行時間傳送資料的資料行就是所謂的「資料執行中資料行」。

注意

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

因為長資料行通常不會繫結，所以應用程式必須在呼叫 SQLBulkOperations 或 SQLSetPos 之前繫結資料行，並在呼叫 SQLBulkOperations 或 SQLSetPos 之後解除繫結。 資料行必須繫結，因為 SQLBulkOperations 或 SQLSetPos 只會在繫結的資料行上運作，但也必須解除繫結，才能用 SQLGetData 從資料行擷取資料。

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

1. 在資料列集緩衝區中放置一個 32 位元值，而非資料值。 此值稍後會傳回給應用程式，因此應用程式應將其設為有意義的數值，如資料行數目或包含資料的檔案控制代碼。

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

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

4. 呼叫 SQLParamData 以回應 SQL_NEED_DATA 傳回值。 如果需要傳送長資料，SQLParamData 會傳回 SQL_NEED_DATA。 在 ValuePtrPtr 引數所指向的緩衝區中，驅動程式會傳回應用程式放在資料列集緩衝區中的唯一值。 如果資料執行中資料行有一個以上，則應用程式會利用此值來判斷要為哪個資料行傳送資料；驅動程式不需要以任何特定順序來要求資料執行中資料行的資料。

5. 呼叫 SQLPutData 以將資料行資料傳送至驅動程式。 如果資料行資料無法納入單一緩衝區 (長資料很常發生此情形)，則應用程式會重複呼叫 SQLPutData，以分段傳送資料；由驅動程式和資料來源來重新組合資料。 如果應用程式傳遞以 null 終止的字串資料，驅動程式或資料來源必須在重新組合流程中移除 null 終止字元。

6. 再次呼叫 SQLParamData 來指出已傳送資料行的所有資料。 如果還有未傳送資料的資料執行中資料行，驅動程式會傳回 SQL_NEED_DATA 和下一個資料執行中資料行的唯一值；應用程式會回到步驟 5。 如果所有資料執行中資料行皆已傳送資料，則表示資料列的資料已傳送至資料來源。 接下來，SQLParamData 會傳回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO，而且可以傳回 SQLBulkOperations 或 SQLSetPos 可傳回的任何 SQLSTATE。

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