Fungsi JetEnumerateColumns

  • Artikel

Berlaku untuk: Windows | Windows Server

Fungsi JetEnumerateColumns

Fungsi JetEnumerateColumns secara efisien mengambil sekumpulan kolom dan nilainya dari rekaman kursor saat ini atau penyangga salinan kursor tersebut. Kolom dan nilai yang diambil dapat dibatasi oleh daftar ID kolom, nomor itagSequence , dan karakteristik lainnya. API pengambilan kolom ini unik karena mengembalikan informasi dalam memori yang dialokasikan secara dinamis yang diperoleh menggunakan panggilan balik kompatibel realloc yang disediakan pengguna. Fleksibilitas baru ini memungkinkan pengambilan data kolom yang efisien dengan karakteristik tertentu (seperti ukuran dan perkalian) yang tidak diketahui oleh pemanggil. Ini menghilangkan kebutuhan akan penggunaan mode penemuan JetRetrieveColumn untuk menentukan karakteristik tersebut untuk menyiapkan panggilan akhir ke JetRetrieveColumn yang akan berhasil mengambil data yang diinginkan.

Windows XP: JetEnumerateColumns diperkenalkan di Windows XP.

    JET_ERR JET_API JetEnumerateColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          unsigned long cEnumColumnId,
      __in_opt      JET_ENUMCOLUMNID* rgEnumColumnId,
      __out         unsigned long* pcEnumColumn,
      __out         JET_ENUMCOLUMN** prgEnumColumn,
      __in          JET_PFNREALLOC pfnRealloc,
      __in          void* pvReallocContext,
      __in          unsigned long cbDataMost,
      __in          JET_GRBIT grbit
    );

Parameter

sesid

Sesi yang digunakan untuk panggilan ini.

tableid

Kursor yang digunakan untuk panggilan ini.

cEnumColumnId

Array ID kolom, masing-masing dengan array opsional dari angka itagSequence untuk dijumlahkan.

Jika cEnumColumnId adalah 0 (nol) maka rgEnumColumnId diabaikan dan semua nilai kolom dijumlahkan dan dikembalikan ke pemanggil. Jika elemen array ID kolom mengacu pada ID kolom 0 (nol) maka enumerasi kolom tersebut dilewati dan slot yang sesuai dalam output akan dihasilkan dengan status kolom JET_wrnColumnSkipped.

Jika ctagSequence adalah 0 (nol) untuk elemen tertentu dari array ID kolom, rgtagSequence diabaikan dan semua nilai kolom untuk ID kolom tersebut dihitung dan dikembalikan ke pemanggil. Jika elemen array angka itagSequence mengacu pada jumlah itagSequence 0 (nol) maka enumerasi angka itagSequence tersebut dilewati dan slot yang sesuai dalam output akan dihasilkan dengan status nilai kolom JET_wrnColumnSkipped.

rgEnumColumnId

Lihat cEnumColumnId.

pcEnumColumn

Mengembalikan array kolom yang dijumlahkan dan nilainya dalam memori yang dialokasikan melalui panggilan balik yang kompatibel dengan itagSequence yang disediakan.

Jika array ID kolom diminta pada input, urutan dan ukuran array output akan mencerminkan urutan dan ukuran array input. Demikian pula, jika array angka itagSequence diminta untuk ID kolom tertentu pada input, urutan dan ukuran array output nilai kolom untuk kolom tersebut akan mencerminkan urutan dan ukuran array input.

Parameter output diatur ke 0 (nol) dan NULL pada kesalahan apa pun kecuali untuk JET_errBadColumnId dan JET_errColumnNotFound. Ketika kesalahan ini dikembalikan, data output valid dan lengkap untuk semua kecuali ID kolom yang terpengaruh. Kode status untuk setiap ID kolom yang terpengaruh diatur ke salah satu kesalahan ini sehingga pemanggil dapat menentukan ID kolom mana yang buruk dan berpotensi mengambil tindakan korektif.

prgEnumColumn

Lihat pcEnumColumn.

pfnRealloc

Mengidentifikasi panggilan balik yang kompatibel dengan realloc dan penunjuk konteks opsional yang digunakan untuk mengalokasikan memori untuk array output kolom dan nilainya.

pvReallocContext

Lihat pfnRealloc.

cbDataMost

Mengatur batas pada jumlah data yang akan dikembalikan dari teks panjang atau kolom biner panjang.

Parameter ini dapat digunakan untuk mencegah enumerasi nilai kolom yang sangat besar. Biasanya, enumerasi seperti itu mungkin gagal dalam panggilan API dengan JET_errOutOfMemory. Jika nilai kolom besar dipotong singgah itu maka status nilai kolom akan JET_wrnColumnTruncated.

grbit

Sekelompok bit yang menentukan nol atau beberapa opsi berikut.

Nilai

Makna

JET_bitEnumerateCompressOutput

Saat menghitung nilai kolom, semua kolom yang kami ambil semua nilainya dan yang hanya memiliki satu nilai kolom non-NULL yang dapat dikembalikan dalam format terkompresi. Status untuk kolom tersebut akan diatur ke JET_wrnColumnSingleValue dan ukuran nilai kolom dan memori yang berisi nilai kolom akan dikembalikan langsung dalam struktur JET_ENUMCOLUMN . Tidak dijamin bahwa semua kolom yang memenuhi syarat dikompresi dengan cara ini. Lihat JET_ENUMCOLUMN untuk informasi selengkapnya.

JET_bitEnumerateCopy

Opsi ini menunjukkan bahwa nilai kolom rekaman yang dimodifikasi harus dijumlahkan daripada nilai kolom asli. Jika nilai kolom belum dimodifikasi, nilai kolom asli dijumlahkan. Dengan cara ini, nilai kolom yang belum disisipkan atau diperbarui dapat dijumlahkan saat menyisipkan atau memperbarui rekaman.

Opsi ini identik dengan JET_bitRetrieveCopy saat digunakan dengan JetRetrieveColumn atau JetRetrieveColumns.

JET_bitEnumerateIgnoreDefault

Jika kolom tertentu tidak ada dalam rekaman, maka tidak ada nilai kolom yang akan dikembalikan. Biasanya, nilai default untuk kolom, jika ada, akan dikembalikan dalam kasus ini. Dijamin bahwa jika kolom diatur ke nilai yang berbeda dari nilai default, nilai yang berbeda akan dikembalikan (yaitu, jika kolom dengan nilai default secara eksplisit diatur ke NULL maka NULL akan dikembalikan sebagai nilai untuk kolom tersebut). Perhatikan bahwa, bahkan jika opsi ini diminta, masih mungkin untuk melihat nilai kolom yang kebetulan sama dengan nilai default. Tidak ada upaya yang dilakukan untuk menghapus nilai kolom yang cocok dengan nilai defaultnya.

Penting untuk dicatat bahwa opsi ini memengaruhi output JetEnumerateColumns ketika digunakan dengan JET_bitEnumeratePresenceOnly atau JET_bitEnumerateTaggedOnly.

JET_bitEnumerateIgnoreUserDefinedDefault

Jika kolom tertentu tidak ada dalam rekaman dan memiliki nilai default yang ditentukan pengguna, maka tidak ada nilai kolom yang akan dikembalikan. Opsi ini akan mencegah panggilan balik yang menghitung nilai default yang ditentukan pengguna untuk kolom dipanggil saat menghitung nilai untuk kolom tersebut.

Windows Server 2003 dan yang lebih lama: Untuk rilis Windows Server 2003 dan yang lebih lama, operasi akan gagal dengan JET_errCallbackFailed.

Windows Server 2003 SP1: Nilai yang mungkin ini hanya tersedia untuk Windows Server 2003 SP1 dan sistem operasi yang lebih baru. Jika nilai yang mungkin ini ditentukan dan tabel berisi kolom yang memiliki nilai default yang ditentukan pengguna, maka operasi akan gagal dengan JET_errCallbackFailed.

JET_bitEnumeratePresenceOnly

Jika nilai non-NULL ada untuk nilai kolom atau kolom yang diminta, maka data terkait tidak dikembalikan. Sebagai gantinya, status terkait untuk nilai kolom atau kolom tersebut akan diatur ke JET_wrnColumnPresent. Jika nilai kolom atau kolom ADALAH NULL , JET_wrnColumnNull akan dikembalikan seperti biasa.

JET_bitEnumerateTaggedOnly

Saat menghitung semua nilai kolom dalam rekaman (misalnya, yaitu ketika cEnumColumnId adalah nol), hanya nilai kolom yang diberi tag yang akan dikembalikan. Opsi ini tidak diperbolehkan saat menghitung array ID kolom tertentu.

JET_bitEnumerateInRecordOnly

Windows 7: JET_bitEnumerateInRecordOnly diperkenalkan di Windows 7.

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. Kesalahan ini akan dikembalikan oleh JetEnumerateColumns jika id kolom tertentu diminta, salah satu id kolom tersebut tidak valid, dan ID kolom pertama yang tidak valid gagal dengan kesalahan ini untuk kode status kolomnya.

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 ID kolom yang diberikan tidak ada dalam tabel. Kesalahan ini akan dikembalikan oleh JetEnumerateColumns jika ID kolom tertentu diminta, salah satu ID kolom tersebut tidak valid, dan ID kolom pertama yang tidak valid gagal dengan kesalahan ini untuk kode status kolomnya.

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_errInvalidgrbit

Salah satu opsi yang diminta tidak valid atau tidak diimplementasikan. Kesalahan ini akan dikembalikan oleh JetEnumerateColumns ketika:

  • JET_bitEnumerateLocal ditentukan.

  • Grbit ilegal ditentukan.

JET_errInvalidParameter

Salah satu parameter yang disediakan berisi nilai yang tidak terduga atau berisi nilai yang tidak masuk akal ketika dikombinasikan dengan nilai parameter lain. Kesalahan ini akan dikembalikan oleh JetEnumerateColumns ketika:

  • pcEnumColumn adalah NULL.

  • prgEnumColumn adalah NULL.

  • pfnRealloc adalah NULL.

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_errRecordDeleted

Kursor diposisikan pada rekaman yang telah dihapus. Ini dapat terjadi karena berbagai alasan. Alasan paling umum adalah bahwa sesi tidak dalam transaksi, kursor diposisikan pada rekaman, rekaman itu dihapus, dan kemudian kursor mencoba mereferensikan rekaman tersebut.

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.

Jika berhasil, data yang diminta akan dikembalikan dalam buffer output. Pemanggil bertanggung jawab untuk membebaskan memori apa pun yang dialokasikan oleh panggilan balik ini dan dikembalikan dalam buffer output. Memori tersebut harus dikosongkan melalui panggilan balik yang kompatibel dengan realloc yang disediakan. Tidak ada perubahan pada status database yang akan terjadi.

Jika gagal, tidak ada data yang diminta yang akan dikembalikan. Memori apa pun yang dialokasikan selama panggilan akan dikosongkan secara otomatis menggunakan panggilan balik yang kompatibel dengan realloc yang disediakan. Tidak ada perubahan pada status database yang akan terjadi.

Keterangan

Jika Anda menghitung semua nilai kolom dalam rekaman dan tidak menentukan JET_bitEnumerateIgnoreDefaults maka Anda tidak dapat berasumsi bahwa Anda tidak akan pernah melihat nilai kolom atau kolom dengan kode status JET_wrnColumnNull. Anda dapat melihat kode status ini jika kolom memiliki nilai default dan secara eksplisit diatur ke NULL atau jika kolom adalah kolom yang tidak jarang (misalnya, kolom tetap atau variabel).

Parameter cbDataMost tidak berlaku untuk semua nilai kolom. Parameter ini hanya akan memotong teks panjang dan nilai kolom biner panjang yang sangat besar sehingga telah disimpan secara terpisah dari rekaman.

Jika JetEnumerateColumns mengembalikan data dalam parameter outputnya, pemanggil bertanggung jawab untuk membebaskan memori dalam array serta memori apa pun yang disebut oleh pointer yang disematkan dalam array tersebut.

Persyaratan

Persyaratan Nilai

Klien

Memerlukan Windows Vista atau Windows XP.

Server

Memerlukan Windows Server 2008 atau Windows Server 2003.

Header

Dinyatakan dalam Esent.h.

Pustaka

Gunakan ESENT.lib.

DLL

Membutuhkan ESENT.dll.

Lihat juga

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_ENUMCOLUMNID
JET_ENUMCOLUMN
JET_ENUMCOLUMNVALUE
JET_PFNREALLOC
realloc
JetRetrieveColumn
JetRetrieveColumns