共用方式為


使用長度與指標值

長度/指標緩衝區是用來傳遞資料緩衝區中資料的位元組長度或特殊指標 (例如 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。 資料緩衝區不包含任何資料。 相反地,在執行陳述式時或呼叫 SQLBulkOperationsSQLSetPos 時,將會使用 SQLPutData 傳送資料。 此值僅適用於傳送至驅動程式的 SQL 資料。 如需詳細資訊,請參閱 SQLBindParameterSQLBulkOperationsSQLSetPos

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

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

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

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