Fungsi JetSetColumn

Berlaku untuk: Windows | Windows Server

Fungsi JetSetColumn

Fungsi JetSetColumn memodifikasi nilai kolom tunggal dalam rekaman yang dimodifikasi untuk disisipkan atau untuk memperbarui rekaman saat ini. Ini dapat menimpa nilai yang ada, menambahkan nilai baru ke urutan nilai dalam kolom multinilai, menghapus nilai dari urutan nilai dalam kolom multinilai, atau memperbarui semua atau sebagian dari nilai panjang, kolom jenis JET_coltypLongText atau 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
    );

Parameter

sesid

Sesi yang digunakan untuk panggilan ini.

tableid

Kursor yang digunakan untuk panggilan ini.

columnid

JET_COLUMNID kolom yang akan diambil. Atau, nilai columnid 0 (nol) dapat diberikan. Saat columnid 0 (nol) diberikan, semua kolom yang diberi tag, kolom jarang dan multinilai, diperlakukan sebagai kolom tunggal. Ini memfasilitasi pengambilan semua kolom jarang yang ada dalam rekaman.

pvData

Buffer input yang berisi data yang akan digunakan untuk nilai kolom.

cbData

Ukuran dalam byte buffer input.

grbit

Sekelompok bit yang berisi opsi yang akan digunakan untuk panggilan ini, yang mencakup nol atau beberapa hal berikut:

Nilai	Makna
JET_bitSetAppendLV	Opsi ini digunakan untuk menambahkan data ke kolom jenis JET_coltypLongText atau JET_coltypLongBinary. Perilaku yang sama dapat dicapai dengan menentukan ukuran nilai panjang yang ada dan menentukan ibLongValue dalam psetinfo. Namun, lebih mudah untuk menggunakan grbit ini karena mengetahui ukuran nilai kolom yang ada tidak diperlukan.
JET_bitSetOverwriteLV	Opsi ini digunakan menggantikan nilai panjang yang ada dengan data yang baru disediakan. Ketika opsi ini digunakan, seolah-olah nilai panjang yang ada telah diatur ke panjang 0 (nol) sebelum mengatur data baru.
JET_bitSetRevertToDefaultValue	Opsi ini hanya berlaku untuk kolom bertag, jarang, atau multinilai. Ini menyebabkan kolom mengembalikan nilai kolom default pada operasi kolom ambil berikutnya. Semua nilai kolom yang ada dihapus.
JET_bitSetSeparateLV	Opsi ini digunakan untuk memaksa nilai panjang, kolom jenis JET_coltypLongText atau JET_coltypLongBinary, untuk disimpan secara terpisah dari sisa data rekaman. Ini terjadi secara normal ketika ukuran nilai panjang mencegahnya disimpan dengan data rekaman yang tersisa. Namun, opsi ini dapat digunakan untuk memaksa nilai panjang disimpan secara terpisah. Perhatikan bahwa nilai panjang berukuran empat byte yang lebih kecil tidak dapat dipaksa untuk dipisahkan. Dalam kasus seperti itu, opsi diabaikan.
JET_bitSetSizeLV	Opsi ini digunakan untuk menginterpretasikan buffer input sebagai jumlah bilangan bulat byte untuk diatur sebagai panjang nilai panjang yang dijelaskan oleh columnid yang diberikan dan jika disediakan, nomor urutan dalam psetinfo-itagSequence>. Jika ukuran yang diberikan lebih besar dari nilai kolom yang ada, kolom akan diperluas dengan 0 detik. Jika ukurannya lebih kecil dari nilai kolom yang ada, maka nilainya akan dipotong.
JET_bitSetUniqueMultiValues	Opsi ini digunakan untuk memberlakukan bahwa semua nilai dalam kolom multinilai berbeda. Opsi ini membandingkan data kolom sumber, tanpa transformasi apa pun, dengan nilai kolom lain yang sudah ada dan kesalahan dikembalikan jika duplikat ditemukan. Jika opsi ini diberikan, maka JET_bitSetAppendLV, JET_bitSetOverwriteLV, dan JET_bitSetSizeLV juga tidak dapat diberikan.
JET_bitSetUniqueNormalizedMultiValues	Opsi ini digunakan untuk memberlakukan bahwa semua nilai dalam kolom multinilai berbeda. Opsi ini membandingkan transformasi data kolom yang dinormalisasi kunci, dengan nilai kolom lain yang sama diubah dan kesalahan dikembalikan jika duplikat ditemukan. Jika opsi ini diberikan, maka JET_bitSetAppendLV, JET_bitSetOverwriteLV, dan JET_bitSetSizeLV juga tidak dapat diberikan.
JET_bitSetZeroLength	Opsi ini digunakan untuk mengatur nilai ke panjang nol. Biasanya, nilai kolom diatur ke NULL dengan meneruskan cbMax 0 (nol). Namun, untuk beberapa jenis, seperti JET_coltypText, nilai kolom dapat memiliki panjang 0 (nol) alih-alih NULL, dan opsi ini digunakan untuk membedakan antara panjang NULL dan 0 (nol). Catatan Secara umum, jika kolom adalah kolom panjang tetap, bit ini diabaikan dan kolom diatur ke NULL. Namun, jika kolom adalah kolom bertag panjang tetap, panjang kolom diatur ke 0. Ketika kolom bertag panjang tetap diatur ke panjang 0, upaya untuk mengambil kolom dengan JetRetrieveColumn atau JetRetrieveColumns akan berhasil, tetapi panjang aktual yang dikembalikan dalam parameter cbActual adalah 0.
JET_bitSetIntrinsicLV	Opsi ini digunakan untuk menyimpan seluruh nilai panjang dalam rekaman.
JET_bitSetCompressed	Opsi ini digunakan untuk mencoba pemadatan data saat menyimpan data. Windows 7: JET_bitSetCompressed diperkenalkan di Windows 7.
JET_bitSetUncompressed	Opsi ini digunakan tidak mencoba pemadatan saat menyimpan data. Windows 7: JET_bitSetUnCompressed diperkenalkan di Windows 7.

psetinfo

Arahkan ke parameter input opsional yang dapat diatur untuk fungsi ini menggunakan struktur JET_SETINFO .

Jika psetinfo diberikan sebagai NULL maka fungsi berperilaku seolah-olah itagSequence 1 dan ibLongValue 0 (nol) diberikan. Ini menyebabkan kolom diatur untuk mengatur nilai pertama kolom multinilai, dan mengatur data panjang yang dimulai pada offset 0 (nol).

Opsi berikut dapat diatur untuk parameter ini:

Nilai	Makna
ibLongValue	Offset biner ke dalam nilai kolom panjang di mana data yang ditetapkan harus dimulai.
itagSequence	Nomor urut dari nilai kolom multinilai yang diinginkan untuk diatur. Jika itagSequence diatur ke 0 (nol), maka nilai yang disediakan harus ditambahkan ke akhir urutan nilai multinilai. Jika nomor urut yang disediakan lebih besar dari nilai multinilai terakhir yang ada, maka sekali lagi nilai yang diberikan ditambahkan ke akhir urutan nilai. Jika nomor urut sesuai dengan nilai yang ada, maka nilai tersebut diganti dengan nilai yang diberikan.

Tampilkan Nilai

Fungsi ini mengembalikan jenis data JET_ERR dengan salah satu kode pengembalian berikut. Untuk informasi selengkapnya tentang kemungkinan kesalahan ESE, lihat Kesalahan Mesin Penyimpanan yang Dapat Diperluas dan Parameter Penanganan Kesalahan.

Menampilkan kode	Deskripsi
JET_errSuccess	Operasi berhasil diselesaikan.
JET_errBadColumnId	ID kolom yang diberikan berada di luar batas hukum ID kolom.
JET_errClientRequestToStopJetService	Tidak dimungkinkan untuk menyelesaikan operasi karena semua aktivitas pada instans yang terkait dengan sesi telah berhenti sebagai akibat dari panggilan ke JetStopService.
JET_errColumnNotFound	Kolom yang dijelaskan oleh columnid yang diberikan tidak ada dalam tabel.
JET_errColumnNotUpdatable	Upaya ilegal dilakukan untuk memperbarui nilai panjang selama operasi pembaruan asli penghapusan salinan sisipan.
JET_errColumnTooBig	Data nilai kolom yang diberikan dalam buffer input melebihi batasan ukuran baik alami untuk kolom panjang tetap atau dikonfigurasi untuk teks panjang tetap atau kolom biner. Kesalahan ini juga dikembalikan saat meneruskan lebih dari 1024 byte data untuk kolom panjang dan mengatur bendera JET_bitSetIntrinsicLV.
JET_errInstanceUnavailable	Tidak dimungkinkan untuk menyelesaikan operasi karena instans yang terkait dengan sesi telah mengalami kesalahan fatal yang mengharuskan akses ke semua data dicabut untuk melindungi integritas data tersebut. Windows XP: Kesalahan ini hanya akan dikembalikan oleh Windows XP dan rilis yang lebih baru.
JET_errInvalidBufferSize	Ukuran data nilai kolom yang diberikan tidak cocok dengan apa yang alami untuk jenis data panjang tetap.
JET_errInvalidColumnType	Upaya ilegal dilakukan untuk memperbarui kolom peningkatan otomatis baik selama operasi sisipkan atau perbarui, atau untuk memperbarui kolom versi selama operasi penggantian.
JET_errInvalidgrbit	Opsi yang disediakan tidak diketahui atau kombinasi ilegal dari pengaturan bit yang diketahui.
JET_errInvalidParameter	psetinfo-cbStruct> yang diberikan bukan ukuran yang valid untuk struktur JET_SETINFO .
JET_errMultiValuedDuplicate	Operasi set kolom mencoba membuat nilai duplikat dan ditentukan baik JET_bitSetUniqueMultiValues atau JET_bitSetUniqueNormalizedMultiValues.
JET_errNotInitialized	Tidak dimungkinkan untuk menyelesaikan operasi karena instans yang terkait dengan sesi belum diinisialisasi.
JET_errNotInTransaction	Upaya ilegal dilakukan untuk memperbarui nilai kolom panjang ketika sesi panggilan tidak dalam transaksi.
JET_errNullInvalid	Upaya ilegal dilakukan untuk mengatur kolom non-NULL ke NULL.
JET_errColumnIllegalNull	Sama seperti JET_errNullInvalid.
JET_errRecordTooBig	Nilai kolom tidak dapat diatur ke nilai dalam buffer input karena akan menyebabkan rekaman melebihi batasan ukuran terkait ukuran halamannya. Kolom jenis JET_coltypLongText atau JET_coltypLongBinary dapat disimpan secara terpisah dari data rekaman yang tersisa. Namun, kolom lain harus disimpan dengan rekaman dan dapat menyebabkan batasan ukuran rekaman terlampaui. Bahkan kolom panjang memerlukan ruang 5 byte dalam rekaman sebagai tautan dan ini juga dapat menyebabkan JET_errRecordTooBig dikembalikan.
JET_errRestoreInProgress	Tidak dimungkinkan untuk menyelesaikan operasi karena operasi pemulihan sedang berlangsung pada instans yang terkait dengan sesi.
JET_errSessionSharingViolation	Sesi yang sama tidak dapat digunakan untuk lebih dari satu utas secara bersamaan. Windows XP: Kesalahan ini hanya akan dikembalikan oleh Windows XP dan rilis yang lebih baru.
JET_errTermInProgress	Tidak dimungkinkan untuk menyelesaikan operasi karena instans yang terkait dengan sesi sedang dimatikan.
JET_errUpdateNotPrepared	Kursor saat ini tidak sedang dalam proses menyisipkan rekaman baru atau memperbarui rekaman yang sudah ada.
JET_errVersionStoreOutOfMemory	Kesalahan ini akan terjadi ketika ukuran penyimpanan versi yang dikonfigurasi tidak cukup untuk menahan semua pembaruan yang luar biasa.
JET_wrnColumnMaxTruncated	Nilai kolom dalam buffer input melebihi panjang maksimum yang dikonfigurasi untuk kolom panjang variabel dan dipotong.

Jika berhasil, bagian yang diinginkan dari nilai kolom untuk kolom tertentu diatur dengan data yang disalin dari buffer input. Himpunan data mungkin telah dipotong jika melebihi panjang maksimum yang ditentukan untuk kolom panjang variabel.

Jika gagal, lokasi kursor dibiarkan tidak berubah dan tidak ada data nilai kolom yang diperbarui dalam penyangga salinan.

Keterangan

Mengatur nilai panjang, nilai untuk kolom JET_coltypLongBinary jenis JET_coltypLongText atau JET_coltypLongBinary, harus dilakukan hanya ketika sesi panggilan dalam transaksi. Jika sesi panggilan tidak dalam transaksi, modifikasi pada nilai panjang yang disimpan secara terpisah dapat diterapkan sepenuhnya bahkan ketika operasi pembaruan kemudian dibatalkan. Jika sesi panggilan berada dalam transaksi, maka efek pembaruan dapat sepenuhnya digulung balik dengan membatalkan pembaruan dan mengembalikan transaksi sesi.

Pembaruan indeks tidak dilakukan sebagai akibat dari operasi JetSetColumn . Sebaliknya, indeks diperbarui hanya setelah semua modifikasi kolom selesai dan JetUpdate dipanggil. Ini memungkinkan pembaruan indeks yang paling efisien ketika indeks melibatkan lebih dari satu kolom yang dimodifikasi.

Rekaman dibatasi ukurannya berdasarkan ukuran halaman database. Nilai panjang apa pun dalam rekaman yang lebih besar dari lima byte akan disimpan terpisah dari rekaman jika data dalam rekaman melebihi batasnya sebagai akibat dari operasi JetSetColumn . Kesalahan JET_errRecordTooBig hanya akan dikembalikan setelah semua data kolom rekaman yang dapat dipisahkan disimpan secara terpisah dari rekaman dan rekaman masih melebihi batas ukuran rekaman.

Persyaratan

Persyaratan	Nilai
Klien	Memerlukan Windows Vista, Windows XP, atau Windows 2000 Professional.
Server	Memerlukan Windows Server 2008, Windows Server 2003, atau Windows 2000 Server.
Header	Dinyatakan dalam Esent.h.
Pustaka	Gunakan ESENT.lib.
DLL	Membutuhkan ESENT.dll.

Lihat juga

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn
JetSetColumns