使用長度與指標值

  • 發行項

長度/指標緩衝區是用來傳遞資料緩衝區中資料的位元組長度或特殊指標 (例如 SQL_Null_DATA)，該指標表示資料為 Null。 根據其中使用長度/指標緩衝區的函式而定，會將其定義為 SQLINTEGER 或 SQLSMALLINT。 因此，需要單一引數來描述它。 如果資料緩衝區是非延遲的輸入緩衝區，這個引數會包含資料本身的位元組長度或指標值。 它通常命名為 StrLen_or_Ind 或類似的名稱。 例如，下列程式碼會呼叫 SQLPutData，將完整資料傳遞給緩衝區；位元組長度 (ValueLen) 會直接傳遞，因為資料緩衝區 (ValuePtr) 是輸入緩衝區。

SQLCHAR      ValuePtr[50];  
SQLINTEGER   ValueLen;  
  
// Call local function to place data in ValuePtr. In ValueLen, return the  
// number of bytes of data placed in ValuePtr. If there is not enough  
// data, this will be less than 50.  
FillBuffer(ValuePtr, sizeof(ValuePtr), &ValueLen);  
  
// Call SQLPutData to send the data to the driver.  
SQLPutData(hstmt, ValuePtr, ValueLen);

如果資料緩衝區是延遲的輸入緩衝區、非延遲的輸出緩衝區，或者是輸出緩衝區，引數會包含長度/指標緩衝區的位址。 它通常命名為 StrLen_or_IndPtr 或類似的名稱。 例如，下列程式碼會呼叫 SQLGetData 來擷取具有完整資料的緩衝區；位元組長度會傳回至長度/指標緩衝區 (ValueLenOrInd) 中的應用程式，其位址會傳遞至 SQLGetData，因為對應的資料緩衝區 (ValuePtr) 是非推斷的輸出緩衝區。

SQLCHAR      ValuePtr[50];  
SQLINTEGER   ValueLenOrInd;  
SQLGetData(hstmt, 1, SQL_C_CHAR, ValuePtr, sizeof(ValuePtr), &ValueLenOrInd);

除非特別禁止，長度/指標緩衝區引數可以是 0 (如果為非推斷的輸入) 或是 null 指標(如果為輸出或延遲輸入)。 對於輸入緩衝區，這會導致驅動程式忽略資料的位元組長度。 這會在傳遞可變長度資料時傳回錯誤，但在傳遞非 Null、固定長度資料時很常見，因為兩者都不需要長度或指標值。 對於輸出緩衝區，這會導致驅動程式不會傳回資料的位元組長度或指標值。 如果驅動程式傳回的資料是 Null，就會發生此錯誤，但在擷取固定長度、不可為 Null 的資料時很常見，因為兩者都不需要長度或指標值。

如同將延遲資料緩衝區的位址傳遞至驅動程式時，延遲長度/指標緩衝區的位址必須維持有效狀態，直到緩衝區取消繫結為止。

下列長度有效為長度/指標值：

  • n，其中 n> 0。

  • SQL_NTS。 傳送至對應資料緩衝區中驅動程式的字串會以 null 結尾；這是讓 C 程式設計人員不必計算其位元組長度，即可傳遞字串的便利方式。 只有當應用程式將資料傳送至驅動程式時，此值才成立。 當驅動程式將資料傳回應用程式時，它一律會傳回資料的實際位元組長度。

下列值為有效的長度/指標值。 SQL_NULL_DATA 儲存在 [SQL_DESC_INDICATOR_PTR] 描述項欄位中；所有其他值則會儲存在 [SQL_DESC_OCTET_LENGTH_PTR] 描述項欄位中。

  • SQL_NULL_DATA。 該資料是 Null 資料值，而且會忽略對應資料緩衝區中的值。 這個值僅適用於傳送至驅動程式或從驅動程式擷取的 SQL 資料。

  • SQL_DATA_AT_EXEC。 資料緩衝區不包含任何資料。 相反地，在執行陳述式時或呼叫 SQLBulkOperations 或 SQLSetPos 時，將會使用 SQLPutData 傳送資料。 此值僅適用於傳送至驅動程式的 SQL 資料。 如需詳細資訊，請參閱 SQLBindParameter、SQLBulkOperations 和 SQLSetPos。

  • SQL_LEN_DATA_AT_EXEC(length) 巨集的結果。 這個值類似於 SQL_DATA_AT_EXEC。 如需詳細資訊，請參閱傳送長資料。

  • SQL_NO_TOTAL。 驅動程式無法判斷仍可在輸出緩衝區中傳回的長資料位元組數目。 此值僅適用於從驅動程式擷取的 SQL 資料。

  • SQL_DEFAULT_PARAM。 程序是使用程序中輸入參數的預設值，而不是對應資料緩衝區中的值。

  • SQL_COLUMN_IGNORE。 SQLBulkOperations 或 SQLSetPos 是忽略資料緩衝區中的值。 呼叫 SQLBulkOperations 或 SQLSetPos 來更新資料列時，資料行值不會變更。 藉由呼叫 SQLBulkOperations 插入新的資料列時，資料行值會設定為其預設值，如果資料行沒有預設值，則會設定為 Null。