緩衝區

  • 發行項

緩衝區是指用來在應用程式與驅動程式之間傳遞資料的任何應用程式記憶體。 例如，應用程式緩衝區可以與含 SQLBindCol 的結果集資料行相關聯，或繫結至該結果集資料行。 擷取每個資料列時，系統會針對這些緩衝區中的每個資料行傳回資料。 輸入緩衝區可用來將資料從應用程式傳遞至驅動程式；輸出緩衝區可用來將資料從驅動程式傳回至應用程式。

注意

如果 ODBC 函式傳回 SQL_ERROR，即代表該函式的任何輸出引數內容皆未定義。

此討論主要與不確定類型的緩衝區有關。 這些緩衝區的位址會顯示為 SQLPOINTER 類型的引數，例如 SQLBindCol 中的 TargetValuePtr 引數。 不過，此處討論的部分項目，例如搭配緩衝區使用的引數，也適用於用來將字串傳遞至驅動程式的引數，例如 SQLTables 中的 TableName 引數。

這些緩衝區通常會成對。 資料緩衝區可用來傳遞資料本身，而長度/指標緩衝區則用來傳遞資料緩衝區中的資料長度或 SQL_NULL_DATA 等特殊值，這表示資料為 Null。 資料緩衝區中的資料長度與資料緩衝區本身的長度不同。 下圖顯示資料緩衝區與長度/指標緩衝區之間的關係。

Data buffer and length/indicator buffer

當資料緩衝區包含可變長度的資料時，便需要長度/指標緩衝區，例如字元或二進位資料。 如果資料緩衝區包含固定長度的資料，例如整數或日期結構，由於已知資料長度，因此只需要長度/指標緩衝區即可傳遞指標值。 如果應用程式使用長度/指標緩衝區搭配固定長度的資料，驅動程式會忽略傳入的任何長度。

資料緩衝區及其包含的資料長度都是以位元組為單位來測量，而非字元。 對於使用 ANSI 字串的程式而言，由於位元組和字元的長度相同，因此這項區別並不重要。

當資料緩衝區代表驅動程式定義的描述項欄位、診斷欄位或屬性時，應用程式應向驅動程式管理員指出函式引數的本質，以說明欄位或屬性的值。 應用程式執行此操作的方法，是在所有將欄位或屬性設定為下列任一值的函式呼叫中設定長度引數。 (擷取欄位或屬性值的函式也是如此，但引數指向設定函式位於引數本身的值時除外。)

  • 如果函式引數指出欄位或屬性的值是字元字串的指標，則長度引數應為字串或 SQL_NTS 的長度。

  • 如果指出欄位或屬性值的函式引數是二進位緩衝區的指標，則應用程式會將 SQL_LEN_BINARY_ATTR (長度) 巨集的結果放在長度引數中。 此操作會在長度引數中放置負值。

  • 如果指出欄位或屬性值的函式引數是字元字串或二進位字串以外的值指標，則長度引數應具有 SQL_IS_POINTER 值。

  • 如果指出欄位或屬性值的函式引數包含固定長度的值，則長度引數為 SQL_IS_INTEGER、SQL_IS_UINTEGER、SQL_IS_SMALLINT 或 SQL_ISI_USMALLINT (視情況而定)。

此章節包含下列主題。