JetSetColumn 函式

適用于： Windows |Windows Server

JetSetColumn 函式

JetSetColumn 函式會修改所修改記錄中的單一資料行值，以插入或更新目前的記錄。 它可以覆寫現有的值、將新值新增至多重值資料行中的值序列、從多重值資料行中的值序列中移除值，或更新長值的所有或部分、類型 為 JET_coltypLongText 或 JET_coltypLongBinary的資料行。

    JET_ERR JET_API JetSetColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit,
      __in_opt      JET_SETINFO* psetinfo
    );

參數

sesid

要用於這個呼叫的會話。

tableid

要用於這個呼叫的資料指標。

columnid

要擷取之資料行 的JET_COLUMNID 。 或者，可以指定資料 行識別碼 值為 0 (零) 。 指定 columnid 0 (零) 時，所有標記的資料行、疏鬆和多重值資料行都會被視為單一資料行。 這有助於擷取記錄中的所有疏鬆資料行。

pvData

包含要用於資料行值的輸入緩衝區。

cbData

輸入緩衝區的位元組大小。

grbit

一組位，其中包含要用於此呼叫的選項，其中包含下列零個或多個內容：

值	意義
JET_bitSetAppendLV	此選項可用來將資料附加至類型 為 JET_coltypLongText 或 JET_coltypLongBinary的資料行。 藉由判斷現有 long 值的大小，並在psetinfo中指定ibLongValue，即可達成相同的行為。 不過，使用這個 grbit 比較簡單，因為知道現有資料行值的大小並非必要。
JET_bitSetOverwriteLV	此選項會使用新提供的資料取代現有的 long 值。 使用此選項時，它就像在設定新資料之前，現有的 long 值已設定為 0 (零) 長度。
JET_bitSetRevertToDefaultValue	此選項僅適用于已標記、疏鬆或多重值資料行。 它會導致資料行在後續擷取資料行作業上傳回預設資料行值。 移除所有現有的資料行值。
JET_bitSetSeparateLV	此選項可用來強制JET_coltypLongText或JET_coltypLongBinary類型的長值、資料行與記錄資料的其餘部分分開儲存。 當 long 值的大小防止其儲存剩餘的記錄資料時，通常會發生這種情況。 不過，這個選項可用來強制個別儲存長值。 請注意，較小的長值四個位元組大小不能強制分開。 在這種情況下，會忽略 選項。
JET_bitSetSizeLV	此選項可用來將輸入緩衝區解譯為整數位節數，以設定為指定 columnid 所描述之 long 值的長度，如果提供，則 psetinfo-itagSequence > 中的序號。 如果指定的大小大於現有的資料行值，資料行將會以 0s 擴充。 如果大小小於現有的資料行值，則會截斷該值。
JET_bitSetUniqueMultiValues	此選項可用來強制執行多重值資料行中的所有值都是相異的。 此選項會將來源資料行資料與其他現有的資料行值相比較，並在找到重複專案時傳回錯誤。 如果指定此選項，則JET_bitSetAppendLV，也無法指定JET_bitSetOverwriteLV和JET_bitSetSizeLV。
JET_bitSetUniqueNormalizedMultiValues	此選項可用來強制執行多重值資料行中的所有值都是相異的。 此選項會比較資料行資料的索引鍵正規化轉換，與其他類似的已轉換現有資料行值，並在找到重複專案時傳回錯誤。 如果指定此選項，則JET_bitSetAppendLV，也無法指定JET_bitSetOverwriteLV和JET_bitSetSizeLV。
JET_bitSetZeroLength	此選項可用來將值設定為零長度。 一般而言，資料行值會透過傳遞 0 (零) ，將資料行值設定為 Null 。 不過，對於某些類型，例如 JET_coltypText，資料行值可以是 0 (零) 長度，而不是 Null，而此選項可用來區分 Null 和 0 (零) 長度。 注意 一般而言，如果資料行是固定長度的資料行，則會忽略這個位，並將資料行設定為 Null。 不過，如果資料行是固定長度標記的資料行，則資料行長度會設定為 0。 當固定長度標記的資料行設定為 0 長度時，會嘗試使用 JetRetrieveColumn 或 JetRetrieveColumns 擷取資料行，但 cbActual 參數中傳回的實際長度為 0。
JET_bitSetIntrinsicLV	此選項可用來將整個長值儲存在記錄中。
JET_bitSetCompressed	此選項可用來在儲存資料時嘗試資料壓縮。 Windows 7： windows 7 中引進JET_bitSetCompressed。
JET_bitSetUncompressed	此選項不會在儲存資料時嘗試壓縮。 Windows 7： windows 7 中引進了JET_bitSetUnCompressed。

psetinfo

可使用 JET_SETINFO 結構為這個函式設定的選擇性輸入參數指標。

如果 psetinfo 指定為 Null ，則函式的行為就像是 1 的 itagSequence ，而 ibLongValue 為 0 (零) 。 這會導致資料行設定多重值資料行的第一個值，並設定從位移 0 開始的長資料 (零) 。

您可以為此參數設定下列選項：

值	意義
ibLongValue	二進位位移到應該開始設定資料的長資料行值。
itagSequence	要設定之所需多重值資料行值的序號。 如果 itagSequence 設定為 0 (零) ，則所提供的值應該附加至多重值值序列的結尾。 如果提供的序號大於最後一個現有的多重值值，則指定值會再次附加至值序列的結尾。 如果序號對應至現有的值，則會將該值取代為指定的值。

傳回值

此函式會傳回具有下列其中一個傳回碼 的JET_ERR 資料類型。 如需可能 ESE 錯誤的詳細資訊，請參閱 可延伸的儲存引擎錯誤 和 錯誤處理參數。

傳回碼	Description
JET_errSuccess	作業已成功完成。
JET_errBadColumnId	指定的資料行識別碼超出資料行識別碼的法律限制。
JET_errClientRequestToStopJetService	因為與會話相關聯的實例上的所有活動因為對 JetStopService的呼叫而停止，所以無法完成作業。
JET_errColumnNotFound	指定的 columnid 所描述的資料行不存在於資料表中。
JET_errColumnNotUpdatable	嘗試在插入複製刪除原始更新作業期間更新長值時發生不合法的嘗試。
JET_errColumnTooBig	輸入緩衝區中指定的指定資料行值資料超過固定長度資料行的自然大小限制，或設定為固定長度文字或二進位資料行。 當針對長資料行傳遞超過 1024 個位元組的資料，並設定JET_bitSetIntrinsicLV旗標時，也會傳回此錯誤。
JET_errInstanceUnavailable	無法完成作業，因為與會話相關聯的實例發生嚴重錯誤，要求撤銷所有資料的存取權以保護該資料的完整性。 Windowsxp： 此錯誤只會由 Windows XP 和更新版本傳回。
JET_errInvalidBufferSize	指定的資料行值資料大小不符合固定長度資料類型的自然值。
JET_errInvalidColumnType	嘗試在插入或更新作業期間更新自動遞增資料行，或在取代作業期間更新版本資料行。
JET_errInvalidgrbit	所提供的選項是未知或不合法的已知位設定組合。
JET_errInvalidParameter	指定的 psetinfo-cbStruct > 不是 JET_SETINFO 結構的有效大小。
JET_errMultiValuedDuplicate	設定資料行作業嘗試建立重複的值，並指定JET_bitSetUniqueMultiValues或JET_bitSetUniqueNormalizedMultiValues。
JET_errNotInitialized	無法完成作業，因為與會話相關聯的實例尚未初始化。
JET_errNotInTransaction	當呼叫會話不在交易中時，嘗試更新長資料行值。
JET_errNullInvalid	嘗試將非Null 資料行設定為 Null時發生不合法的嘗試。
JET_errColumnIllegalNull	與JET_errNullInvalid相同。
JET_errRecordTooBig	資料行值無法設定為輸入緩衝區中的值，因為它會導致記錄超過其頁面大小相關大小限制。 JET_coltypLongText或JET_coltypLongBinary類型的資料行可以與其余記錄資料分開儲存。 不過，其他資料行必須與記錄一起儲存，而且可能會導致超過記錄大小限制。 即使長資料行需要記錄內的 5 位元組空間做為連結，這也可能會導致傳回JET_errRecordTooBig。
JET_errRestoreInProgress	因為與會話相關聯的實例上正在進行還原作業，所以無法完成作業。
JET_errSessionSharingViolation	同一個會話不能同時用於多個執行緒。 Windowsxp： 此錯誤只會由 Windows XP 和更新版本傳回。
JET_errTermInProgress	因為與會話相關聯的實例正在關閉，所以無法完成作業。
JET_errUpdateNotPrepared	游標目前不在插入新記錄或更新現有記錄的程式中。
JET_errVersionStoreOutOfMemory	當版本存放區設定的大小不足，無法保存所有未完成的更新時，就會發生此錯誤。
JET_wrnColumnMaxTruncated	輸入緩衝區中的資料行值超過可變長度資料行的設定長度上限，而且已截斷。

成功時，指定資料行之資料行值所需的部分會設定為從輸入緩衝區複製的資料。 如果資料集超過為可變長度資料行指定的長度上限，則資料集可能會遭到截斷。

失敗時，資料指標位置會保持不變，而且複製緩衝區中不會更新任何資料行值資料。

備註

設定 long 值，只有在呼叫會話位於交易中時，才應該設定類型為 JET_coltypLongText或 JET_coltypLongBinary 的資料行JET_coltypLongBinary值。 如果呼叫會話不在交易中，即使稍後取消更新作業，也會完全認可個別儲存的 long 值。 如果呼叫的會話位於交易中，則可以取消更新並回復會話交易，以完整回復更新的效果。

索引更新不會因為 JetSetColumn 作業而執行。 相反地，只有在所有資料行修改完成且呼叫 JetUpdate 之後，才會更新索引。 當索引牽涉到一個以上的資料行遭到修改時，這允許最有效率的索引更新。

根據資料庫頁面大小限制記錄的大小。 如果記錄中的資料超出其限制，則大於五個位元組的記錄中的任何長值都會與記錄分開儲存，因為 JetSetColumn 作業所造成。 只有在所有可分隔的記錄資料行資料都與記錄分開儲存，且記錄仍然超過記錄大小限制之後，才會傳回錯誤JET_errRecordTooBig。

規格需求

需求	值
用戶端	需要 Windows Vista、Windows XP 或 Windows 2000 Professional。
Server	需要 Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。
標頭	在 Esent.h 中宣告。
程式庫	使用 ESENT.lib。
Dll	需要ESENT.dll。

另請參閱

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn
JetSetColumns