Fungsi JetRetrieveColumn

  • Artikel

Berlaku untuk: Windows | Windows Server

Fungsi JetRetrieveColumn

Fungsi JetRetrieveColumn mengambil nilai kolom tunggal dari rekaman saat ini. Rekaman adalah rekaman yang terkait dengan entri indeks pada posisi kursor saat ini. Atau, fungsi ini dapat mengambil kolom dari rekaman yang sedang dibuat di buffer salinan kursor. Fungsi ini juga dapat mengambil data kolom dari entri indeks yang mereferensikan rekaman saat ini. Selain mengambil nilai kolom aktual, JetRetrieveColumn juga dapat digunakan untuk mengambil ukuran kolom, sebelum mengambil data kolom itu sendiri sehingga buffer aplikasi dapat berukuran tepat.

    JET_ERR JET_API JetRetrieveColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __out_opt     void* pvData,
      __in          unsigned long cbData,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit,
      __in_out_opt  JET_RETINFO* pretinfo
    );

Parameter

sesid

Sesi yang digunakan untuk panggilan ini.

tableid

Kursor yang digunakan untuk panggilan ini.

columnid

JET_COLUMNID kolom yang akan diambil.

Nilai kolom 0 (nol) dapat diberikan yang tidak merujuk ke kolom individual mana pun. Saat kolom 0 (nol) diberikan, semua kolom yang ditandai, jarang, dan kolom multinilai diperlakukan sebagai kolom tunggal. Ini memfasilitasi pengambilan semua kolom jarang yang ada dalam rekaman.

pvData

Buffer output yang menerima nilai kolom.

cbData

Ukuran maksimum, dalam byte, dari buffer output.

pcbActual

Menerima ukuran aktual, dalam byte, dari nilai kolom.

Jika parameter ini ADALAH NULL, maka ukuran sebenarnya dari nilai kolom tidak akan dikembalikan.

grbit

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

Nilai

Makna

JET_bitRetrieveCopy

Bendera ini menyebabkan mengambil kolom untuk mengambil nilai yang dimodifikasi alih-alih nilai asli. Jika nilai belum dimodifikasi, maka nilai asli diambil. Dengan cara ini, nilai yang belum disisipkan atau diperbarui dapat diambil selama operasi menyisipkan atau memperbarui rekaman.

JET_bitRetrieveFromIndex

Opsi ini digunakan untuk mengambil nilai kolom dari indeks, jika memungkinkan, tanpa mengakses rekaman. Dengan cara ini, pemuatan rekaman yang tidak perlu dapat dihindari ketika data yang diperlukan tersedia dari entri indeks itu sendiri. Dalam kasus di mana nilai kolom asli tidak dapat diambil dari indeks, karena transformasi atau pemotokan data yang tidak dapat diubah, rekaman akan diakses dan data diambil seperti biasa. Ini adalah opsi performa dan hanya boleh ditentukan ketika kemungkinan nilai kolom dapat diambil dari indeks. Opsi ini tidak boleh ditentukan jika indeks saat ini adalah indeks berkluster, karena entri indeks untuk indeks berkluster, atau primer, adalah rekaman itu sendiri. Bit ini tidak dapat diatur jika JET_bitRetrieveFromPrimaryBookmark juga diatur.

JET_bitRetrieveFromPrimaryBookmark

Opsi ini digunakan untuk mengambil nilai kolom dari marka buku indeks, dan mungkin berbeda dari nilai indeks saat kolom muncul baik dalam indeks utama maupun indeks saat ini. Opsi ini tidak boleh ditentukan jika indeks saat ini adalah indeks terkluster, atau primer. Bit ini tidak dapat diatur jika JET_bitRetrieveFromIndex juga diatur.

JET_bitRetrieveTag

Opsi ini digunakan untuk mengambil nomor urutan nilai kolom multinilai dalam pretinfo-itagSequence>. Bidang itagSequence biasanya merupakan input untuk mengambil nilai kolom multinilai dari rekaman. Namun, saat mengambil nilai dari indeks, dimungkinkan juga untuk mengaitkan entri indeks dengan nomor urutan tertentu dan mengambil nomor urutan ini juga. Mengambil nomor urut dapat menjadi operasi yang mahal dan hanya boleh dilakukan jika perlu.

JET_bitRetrieveNull

Opsi ini digunakan untuk mengambil nilai NULL kolom multinilai. Jika opsi ini tidak ditentukan, nilai NULL kolom multinilai akan otomatis dilewati.

JET_bitRetrieveIgnoreDefault

Opsi ini hanya memengaruhi kolom multinilai dan menyebabkan nilai NULL dikembalikan saat nomor urutan yang diminta adalah 1 dan tidak ada nilai yang ditetapkan untuk kolom dalam rekaman.

JET_bitRetrieveLongId

Bendera ini hanya untuk penggunaan internal dan tidak dimaksudkan untuk digunakan dalam aplikasi Anda.

JET_bitRetrieveLongValueRefCount

Bendera ini hanya untuk penggunaan internal dan tidak dimaksudkan untuk digunakan dalam aplikasi Anda.

JET_bitRetrieveTuple

Bendera ini akan memungkinkan pengambilan segmen tuple indeks. Bit ini harus ditentukan dengan JET_bitRetrieveFromIndex.

pretinfo

Jika pretinfo diberikan sebagai NULL maka fungsi bertingkah seolah-olah itagSequence 1 dan ibLongValue 0 (nol) diberikan. Hal ini menyebabkan pengambilan kolom mengambil nilai pertama kolom multinilai, dan mengambil data panjang pada offset 0 (nol).

Parameter ini digunakan untuk menyediakan satu atau beberapa hal berikut:

Nilai

Makna

ibLongValue

Memberikan offset biner ke dalam nilai kolom yang panjang saat mengambil sebagian nilai kolom.

itagSequence

Memberikan nomor urut dari nilai kolom multinilai yang diinginkan. Perhatikan bahwa bidang ini hanya diatur jika JET_bitRetrieveTag ditentukan. Jika tidak, itu tidak dimodifikasi.

columnidNextTagged

Mengembalikan ID kolom dari nilai kolom yang dikembalikan saat mengambil semua kolom yang ditandai, jarang, dan multinilai, menggunakan columnid passing 0 (nol).

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_errBadItagSequence

Nilai nomor urutan kolom multinilai yang tidak valid telah diteruskan dalam pretinfo-itagSequence>. Nilai yang valid untuk nomor urutan nilai kolom multinilai adalah 1 atau lebih besar. Nilai 0 (nol) tidak valid untuk fungsi ini.

JET_errClientRequestToStopJetService

Tidak mungkin 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_errIndexTuplesCannotRetrieveFromIndex

Kolom yang diindeks sebagai substring tidak dapat diambil dari indeks, karena hanya sebagian kecil kolom yang biasanya ada di setiap entri indeks.

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. Kesalahan ini hanya akan dikembalikan oleh Windows XP dan rilis yang lebih baru.

JET_errInvalidBufferSize

Dalam beberapa kasus, buffer yang diberikan untuk kolom ambil harus berukuran cukup untuk mengembalikan jumlah nilai kolom apa pun. Misalnya, kolom escrow yang dapat diperbarui disesuaikan agar konsisten untuk konteks transaksional sesi panggilan dan penyesuaian ini memerlukan buffer yang disediakan oleh pemanggil. Jika ruang buffer tidak cukup disediakan, maka JET_errInvalidBufferSize dikembalikan dan tidak ada data kolom apa pun yang dikembalikan.

JET_errInvalidParameter

Satu atau beberapa parameter yang diberikan salah. Ini dapat terjadi jika retinfo.cbStruct lebih kecil dari ukuran JET_RETINFO.

JET_errInvalidgrbit

Opsi yang disediakan tidak diketahui atau kombinasi ilegal dari pengaturan bit yang diketahui.

JET_errNoCurrentRecord

Kursor tidak diposisikan pada rekaman. Ini dapat terjadi karena berbagai alasan. Misalnya, ini akan terjadi jika kursor saat ini diposisikan setelah rekaman terakhir pada indeks saat ini.

JET_errNotInitialized

Tidak dimungkinkan untuk menyelesaikan operasi karena instans yang terkait dengan sesi belum diinisialisasi.

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_wrnBufferTruncated

Seluruh nilai kolom tidak dapat diambil karena buffer yang diberikan lebih kecil dari ukuran kolom.

JET_wrnColumnNull

Nilai kolom yang diambil adalah NULL.

Jika berhasil, nilai kolom untuk kolom yang diberikan, disalin ke dalam buffer yang diberikan. Kurang dari semua nilai kolom disalin dengan JET_wrnBufferTruncated peringatan dikembalikan. Jika pcbActual diberikan, ukuran aktual nilai kolom dikembalikan. Perhatikan bahwa nilai NULL memiliki panjang 0 (nol) dan dengan demikian akan mengatur ukuran yang dikembalikan ke 0 (nol). Jika kolom yang diambil adalah kolom multinilai, dan pretinfo diberikan, dan JET_bitReturnTag diatur sebagai opsi, maka jumlah urutan nilai kolom dikembalikan dalam pretinfo-itagSequence>.

Jika gagal, lokasi kursor dibiarkan tidak berubah dan tidak ada data yang disalin ke dalam buffer yang disediakan.

Keterangan

Panggilan ini digunakan hanya sekali untuk mengambil data berukuran tetap atau diketahui untuk kolom non-multinilai. Namun, ketika data kolom berukuran tidak diketahui, panggilan ini biasanya digunakan dua kali. Ini dipanggil terlebih dahulu untuk menentukan ukuran data sehingga dapat mengalokasikan ruang penyimpanan yang diperlukan. Kemudian, panggilan yang sama dilakukan lagi untuk mengambil data kolom. Ketika jumlah nilai aktual tidak diketahui, karena kolom multinilai, panggilan biasanya digunakan tiga kali. Pertama untuk mendapatkan jumlah nilai dan kemudian dua kali lagi untuk mengalokasikan penyimpanan dan mengambil data aktual.

Mengambil semua nilai untuk kolom multinilai dapat dilakukan dengan berulang kali memanggil fungsi ini dengan nilai pretinfo-itagSequence> dimulai dari 1 dan meningkat pada setiap panggilan berikutnya. Nilai kolom terakhir diketahui diambil ketika JET_wrnColumnNull dikembalikan dari fungsi . Perhatikan bahwa metode ini tidak dapat dilakukan jika kolom multinilai memiliki nilai NULL eksplisit yang diatur dalam urutan nilainya, karena nilai ini akan dilewati. Jika aplikasi ingin mengambil semua nilai kolom multinilai, termasuk yang secara eksplisit diatur ke NULL, maka JetRetrieveColumns harus digunakan alih-alih JetRetrieveColumn. Perhatikan bahwa fungsi ini tidak mengembalikan jumlah nilai untuk fungsi multinilai saat nilai itagSequence 0 (nol) diberikan. Hanya JetRetrieveColumns yang akan mengembalikan jumlah nilai nilai kolom saat nilai itagSequence 0 (nol) diteruskan.

Jika fungsi ini dipanggil pada tingkat transaksi 0 (nol), misalnya, sesi panggilan tidak sendiri dalam transaksi, maka transaksi dibuka dan ditutup dalam fungsi. Tujuan dari ini adalah untuk mengembalikan hasil yang konsisten dalam kasus bahwa nilai panjang mencakup halaman database. Perhatikan bahwa transaksi dirilis antara panggilan fungsi dan serangkaian panggilan ke fungsi ini ketika sesi tidak dalam transaksi dapat mengembalikan data yang diperbarui setelah panggilan pertama ke fungsi ini.

Nilai kolom default akan diambil ketika kolom belum diatur secara eksplisit ke nilai lain, kecuali opsi JET_bitRetrieveIgnoreDefault diatur.

Mengambil nilai kolom autoincrement dari buffer salinan sebelum menyisipkan adalah cara umum untuk mengidentifikasi rekaman secara unik untuk tautan saat menyisipkan data yang dinormalisasi ke dalam beberapa tabel. Nilai autoincrement dialokasikan ketika operasi penyisipan dimulai dan dapat diambil dari penyangga salinan kapan saja hingga pembaruan selesai.

Saat mengambil semua kolom yang diberi tag, multinilai, dan jarang, dengan mengatur columnid ke 0 (nol), kolom diambil dalam urutan columnid dari columnid terendah ke columnid tertinggi. Urutan nilai kolom yang sama dikembalikan setiap kali nilai kolom diambil. Urutannya deterministik.

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_RETINFO
JetSetColumn
JetRetrieveColumns