JetSetColumn İşlevi

Şunlar için geçerlidir: Windows | Windows Server

JetSetColumn İşlevi

JetSetColumn işlevi, değiştirilen bir kayıttaki tek bir sütun değerini eklenecek veya geçerli kaydı güncelleştirmek için değiştirir. Var olan bir değerin üzerine yazabilir, çok değerli bir sütundaki bir değer dizisine yeni bir değer ekleyebilir, çok değerli bir sütundaki bir değer dizisinden bir değeri kaldırabilir veya uzun bir değerin tamamını veya bir bölümünü, JET_coltypLongText veya JET_coltypLongBinary türünde bir sütunu güncelleştirebilir.

    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
    );

Parametreler

sesid

Bu çağrı için kullanılacak oturum.

tableid

Bu çağrı için kullanılacak imleç.

columnid

Alınacak sütunun JET_COLUMNID . Alternatif olarak, 0 (sıfır) sütun kimliği değeri verilebilir. Columnid 0 (sıfır) verildiğinde, tüm etiketli sütunlar( seyrek ve çok değerli sütunlar) tek bir sütun olarak kabul edilir. Bu, bir kayıtta bulunan tüm seyrek sütunların alınmasını kolaylaştırır.

pvData

Sütun değeri için kullanılacak verileri içeren giriş arabelleği.

cbData

Giriş arabelleğinin bayt cinsinden boyutu.

grbit

Aşağıdakilerden sıfır veya daha fazlasını içeren, bu çağrı için kullanılacak seçenekleri içeren bir bit grubu:

Değer	Anlamı
JET_bitSetAppendLV	Bu seçenek, verileri JET_coltypLongText veyaJET_coltypLongBinary türünde bir sütuna eklemek için kullanılır. Aynı davranış, mevcut uzun değerin boyutunu belirleyerek ve psetinfo'daibLongValue belirterek elde edilebilir. Ancak, mevcut sütun değerinin boyutunu bilmek gerekli olmadığından bu grbiti kullanmak daha kolaydır.
JET_bitSetOverwriteLV	Bu seçenek, mevcut uzun değeri yeni sağlanan verilerle değiştirir. Bu seçenek kullanıldığında, yeni verileri ayarlamadan önce mevcut uzun değer 0 (sıfır) uzunluğa ayarlanmış gibi olur.
JET_bitSetRevertToDefaultValue	Bu seçenek yalnızca etiketli, seyrek veya çok değerli sütunlar için geçerlidir. Sütunun sonraki sütun alma işlemlerinde varsayılan sütun değerini döndürmesine neden olur. Tüm mevcut sütun değerleri kaldırılır.
JET_bitSetSeparateLV	Bu seçenek, JET_coltypLongText veya JET_coltypLongBinary türünde uzun bir değerin kayıt verilerinin geri kalanından ayrı olarak depolanmasını zorlamak için kullanılır. Bu, uzun değerin boyutu kalan kayıt verileriyle depolanmasını engellediğinde normal olarak oluşur. Ancak bu seçenek, uzun değerin ayrı olarak depolanmasını zorlamak için kullanılabilir. Daha küçük boyutlu dört baytlık uzun değerlerin ayrı olmaya zorlanamayacağını unutmayın. Böyle durumlarda seçenek yoksayılır.
JET_bitSetSizeLV	Bu seçenek, giriş arabelleğinin verilen columnid tarafından açıklanan uzun değerin uzunluğu olarak ayarlanacak bir tamsayı sayısı olarak ve sağlanırsa psetinfo-itagSequence> içindeki sıra numarasını yorumlamak için kullanılır. Verilen boyut mevcut sütun değerinden büyükse, sütun 0s ile genişletilir. Boyut mevcut sütun değerinden küçükse değer kesilir.
JET_bitSetUniqueMultiValues	Bu seçenek, çok değerli bir sütundaki tüm değerlerin ayrı olmasını zorunlu kılmak için kullanılır. Bu seçenek, dönüştürme olmadan kaynak sütun verilerini diğer mevcut sütun değerleriyle karşılaştırır ve yinelenen bir sütun bulunursa hata döndürülür. Bu seçenek verilirse JET_bitSetAppendLV, JET_bitSetOverwriteLV ve JET_bitSetSizeLV de verilemez.
JET_bitSetUniqueNormalizedMultiValues	Bu seçenek, çok değerli bir sütundaki tüm değerlerin ayrı olmasını zorunlu kılmak için kullanılır. Bu seçenek, sütun verilerinin anahtar normalleştirilmiş dönüşümünü benzer şekilde dönüştürülmüş diğer mevcut sütun değerleriyle karşılaştırır ve yinelenen sütun bulunursa bir hata döndürülür. Bu seçenek verilirse JET_bitSetAppendLV, JET_bitSetOverwriteLV ve JET_bitSetSizeLV de verilemez.
JET_bitSetZeroLength	Bu seçenek bir değeri sıfır uzunluğa ayarlamak için kullanılır. Normalde, cbMax değeri 0 (sıfır) geçirilerek sütun değeri NULL olarak ayarlanır. Ancak , JET_coltypText gibi bazı türlerde sütun değeri NULL yerine 0 (sıfır) uzunlukta olabilir ve bu seçenek NULL ile 0 (sıfır) uzunluğu birbirinden ayırmak için kullanılır. Not Genel olarak, sütun sabit uzunlukta bir sütunsa, bu bit yoksayılır ve sütun NULL olarak ayarlanır. Ancak sütun sabit uzunlukta etiketli bir sütunsa sütun uzunluğu 0 olarak ayarlanır. Sabit uzunluklu etiketli sütun 0 uzunluğa ayarlandığında JetRetrieveColumn veya JetRetrieveColumns ile sütunu alma girişimi başarılı olur, ancak cbActual parametresinde döndürülen gerçek uzunluk 0'dır.
JET_bitSetIntrinsicLV	Bu seçenek, uzun değerin tamamını kayıtta depolamak için kullanılır.
JET_bitSetCompressed	Bu seçenek, verileri depolarken veri sıkıştırmayı deneme amacıyla kullanılır. Windows 7: JET_bitSetCompressed Windows 7'de kullanıma sunulmuştur.
JET_bitSetUncompressed	Bu seçenek, verileri depolarken sıkıştırma girişiminde kullanılmaz. Windows 7: JET_bitSetUnCompressed Windows 7'de kullanıma sunulmuştur.

psetinfo

JET_SETINFO yapısı kullanılarak bu işlev için ayarlanabilen isteğe bağlı giriş parametrelerinin işaretçisi.

PsetinfoNULL olarak verilirse işlev itagSequence değeri 1 ve ibLongValue değeri 0 (sıfır) olarak verilmiş gibi davranır. Bu, sütun kümesinin çok değerli bir sütunun ilk değerini ayarlamasına ve 0 (sıfır) uzaklığından başlayarak uzun verileri ayarlamasına neden olur.

Bu parametre için aşağıdaki seçenekler ayarlanabilir:

Değer	Anlamı
ibLongValue	Küme verilerinin başlaması gereken uzun bir sütun değerine ikili uzaklık.
itagSequence	Ayarlanacağı çok değerli sütun değerinin sıra numarası. itagSequence değeri 0 (sıfır) olarak ayarlanırsa, sağlanan değer çok değerli değerler dizisinin sonuna eklenmelidir. Sağlanan sıra numarası, var olan son çok değerli değerden büyükse, verilen değer yine değer dizisinin sonuna eklenir. Sıra numarası mevcut bir değere karşılık geliyorsa, bu değer verilen değerle değiştirilir.

Dönüş Değeri

Bu işlev, aşağıdaki dönüş kodlarından biriyle JET_ERR veri türünü döndürür. Olası ESE hataları hakkında daha fazla bilgi için bkz. Genişletilebilir Depolama Altyapısı Hataları ve Hata İşleme Parametreleri.

İade kodu	Açıklama
JET_errSuccess	İşlem başarıyla tamamlandı.
JET_errBadColumnId	Verilen sütun kimliği, sütun kimliğinin yasal sınırlarının dışındadır.
JET_errClientRequestToStopJetService	Oturumla ilişkili örnekteki tüm etkinlik JetStopService çağrısının sonucu olarak sona erdiğinden işlemi tamamlamak mümkün değildir.
JET_errColumnNotFound	Verilen sütun kimliği tarafından açıklanan sütun tabloda yok.
JET_errColumnNotUpdatable	Ekleme kopyalama silme özgün güncelleştirme işlemi sırasında uzun bir değeri güncelleştirmek için geçersiz bir girişimde bulunuldu.
JET_errColumnTooBig	Giriş arabelleğinde verilen sütun değeri verileri, sabit uzunlukta bir sütun için doğal veya sabit uzunlukta metin veya ikili sütunlar için yapılandırılmış boyut sınırlamasını aşıyor. Bu hata, uzun bir sütun için 1024 bayttan fazla veri geçirilirken ve JET_bitSetIntrinsicLV bayrağı ayarlanırken de döndürülür.
JET_errÖrnekKullanılamıyor	Oturumla ilişkilendirilmiş örnek, bu verilerin bütünlüğünü korumak için tüm verilere erişimin iptal edilmesi gereken önemli bir hatayla karşılaştığından işlemi tamamlamak mümkün değildir. Windows XP: Bu hata yalnızca Windows XP ve sonraki sürümler tarafından döndürülür.
JET_errInvalidBufferSize	Verilen sütun değeri veri boyutu, sabit uzunluktaki veri türü için doğal olan değerle eşleşmiyor.
JET_errInvalidColumnType	Ekleme veya güncelleştirme işlemi sırasında otomatik artırma sütununu güncelleştirme ya da değiştirme işlemi sırasında sürüm sütununu güncelleştirme amacıyla geçersiz bir girişimde bulunuldu.
JET_errInvalidgrbit	Sağlanan seçenekler bilinmiyor veya bilinen bit ayarlarının geçersiz bir birleşimi.
JET_errInvalidParameter	Verilen psetinfo-cbStruct>, JET_SETINFO yapısı için geçerli bir boyut değil.
JET_errMultiValuedDuplicate	Sütun ayarlama işlemi yinelenen bir değer oluşturmaya çalıştı ve JET_bitSetUniqueMultiValues veya JET_bitSetUniqueNormalizedMultiValues belirtti.
JET_errNotInitialized	Oturumla ilişkili örnek henüz başlatılmadığından işlemi tamamlamak mümkün değildir.
JET_errNotInTransaction	Çağrı oturumu bir işlemde olmadığında uzun bir sütun değerini güncelleştirmek için geçersiz bir girişimde bulunuldu.
JET_errNullInvalid	NULL olmayan bir sütunu NULL olarak ayarlamak için geçersiz bir girişimde bulunuldu.
JET_errColumnIllegalNull	JET_errNullInvalid gibi.
JET_errRecordTooBig	Kaydın sayfa boyutuyla ilgili boyut sınırlamasını aşmasına neden olacağından sütun değeri giriş arabelleğindeki değere ayarlanamadı. JET_coltypLongText veya JET_coltypLongBinary türündeki sütunlar, kalan kayıt verilerinden ayrı olarak depolanabilir. Ancak, diğer sütunlar kayıtla birlikte depolanmalıdır ve kayıt boyutu sınırlamasının aşılmasına neden olabilir. Uzun sütunlar bile bağlantı olarak kayıt içinde 5 bayt alan gerektirir ve bu da JET_errRecordTooBig döndürülmesine neden olabilir.
JET_errRestoreInProgress	Oturumla ilişkili örnekte bir geri yükleme işlemi devam ettiğinden işlemi tamamlamak mümkün değildir.
JET_errSessionSharingViolation	Aynı oturum aynı anda birden fazla iş parçacığı için kullanılamaz. Windows XP: Bu hata yalnızca Windows XP ve sonraki sürümler tarafından döndürülür.
JET_errTermInProgress	Oturumla ilişkili örnek kapatıldığı için işlemi tamamlamak mümkün değildir.
JET_errUpdateNotPrepared	İmleç şu anda yeni kayıt ekleme veya var olan bir kaydı güncelleştirme sürecinde değildir.
JET_errVersionStoreOutOfMemory	Sürüm deposunun yapılandırılmış boyutu bekleyen tüm güncelleştirmeleri tutmak için yetersiz olduğunda bu hata oluşur.
JET_wrnColumnMaxTruncated	Giriş arabelleğindeki sütun değeri, değişken uzunluğu sütunu için yapılandırılan uzunluk üst sınırını aştı ve kesildi.

Başarılı olduğunda, belirtilen sütun için bir sütun değerinin istenen bölümü giriş arabelleğinden kopyalanan verilerle ayarlanır. Veri kümesi, değişken uzunluk sütunu için belirtilen uzunluk üst sınırını aştıysa kesilmiş olabilir.

Hata durumunda, imleç konumu değiştirilmeden bırakılır ve kopyalama arabelleğinde sütun değeri verileri güncelleştirilmez.

Açıklamalar

JET_coltypLongText veyaJET_coltypLongBinary türünde JET_coltypLongBinary uzun değerlerin, sütunların değerlerinin ayarlanması, yalnızca çağrı oturumu bir işlemde olduğunda yapılmalıdır. Çağrı oturumu bir işlemde değilse, ayrı olarak depolanan uzun değerlerde yapılan değişiklikler, güncelleştirme işlemi daha sonra iptal edildiğinde bile tamamen işlenebilir. Çağrı oturumu bir işlemdeyse, güncelleştirme iptal edilerek ve oturum işlemi geri alınarak güncelleştirmenin etkileri tamamen geri alınabilir.

Dizin güncelleştirmeleri JetSetColumn işlemlerinin bir sonucu olarak gerçekleştirilmiyor. Bunun yerine dizinler yalnızca tüm sütun değişiklikleri tamamlandıktan ve JetUpdate çağrıldıktan sonra güncelleştirilir. Bu, dizinler birden fazla sütunun değiştirilmesini içerdiğinde dizinlerin en verimli şekilde güncelleştirilmesini sağlar.

Bir kaydın boyutu veritabanı sayfa boyutuna göre sınırlıdır. Bir JetSetColumn işlemi sonucunda kayıttaki veriler sınırını aşarsa, kayıttaki beş bayttan büyük tüm uzun değerler kayıttan ayrı depolanır. Hata JET_errRecordTooBig yalnızca tüm ayrılabilir kayıt sütunu verileri kayıttan ayrı olarak depolandıktan ve kayıt yine de kayıt boyutu sınırını aştıktan sonra döndürülür.

Gereksinimler

Gereksinim	Değer
Müşteri	Windows Vista, Windows XP veya Windows 2000 Professional gerektirir.
Sunucu	Windows Server 2008, Windows Server 2003 veya Windows 2000 Server gerektirir.
Üstbilgi	Esent.h.'de bildirildi.
Kütüphane	ESENT.lib kullanın.
DLL	ESENT.dllgerektirir.

Ayrıca Bkz.

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn
jetsetcolumns