Bagikan melalui

ISSAsynchStatus::GetStatus (Penyedia OLE DB Klien Asli)

  • Artikel

Berlaku untuk:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics AnalyticsPlatform System (PDW)

Penting

SQL Server Native Client (sering disingkat SNAC) telah dihapus dari SQL Server 2022 (16.x) dan SQL Server Management Studio 19 (SSMS). Penyedia SQL Server Native Client OLE DB (SQLNCLI atau SQLNCLI11) dan Penyedia Microsoft OLE DB warisan untuk SQL Server (SQLOLEDB) tidak direkomendasikan untuk pengembangan baru. Beralih ke Microsoft OLE DB Driver (MSOLEDBSQL) baru untuk SQL Server ke depannya.

Mengembalikan status operasi eksekusi asinkron.

Sintaks

  
HRESULT GetStatus(  
        HCHAPTER hChapter,  
        DBASYNCHOP eOperation,  
        DBCOUNTITEM *pulProgress,  
        DBCOUNTITEM *pulProgressMax,  
        DBASYNCHPHASE *peAsynchPhase,  
        LPOLESTR *ppwszStatusText);

Argumen

hChapter[in]
Handel bab. Jika objek yang dijajaki bukan objek set baris atau operasi tidak berlaku untuk bab, ini harus diatur ke DB_NULL_HCHAPTER, yang diabaikan oleh penyedia.

eOperation[in]
Operasi yang status asinkronnya sedang diminta. Ini harus menjadi nilai berikut:

DBASYNCHOP_OPEN-Konsumen meminta informasi tentang pembukaan asinkron atau populasi set baris atau tentang inisialisasi asinkron objek sumber data. Jika penyedia adalah penyedia yang mematuhi OLE DB 2.5 yang mendukung pengikatan URL langsung, konsumen meminta informasi tentang inisialisasi asinkron atau populasi sumber data, set baris, baris, atau objek aliran.

pulProgress[out]
Pointer ke memori untuk mengembalikan kemajuan operasi asinkron saat ini relatif terhadap maksimum yang diharapkan yang ditunjukkan dalam parameter pulProgressMax . Untuk informasi selengkapnya tentang arti pulProgress, lihat deskripsi peAsynchPhase.

Jika pulProgress adalah penunjuk null, tidak ada kemajuan yang dikembalikan.

pulProgressMax[out]
Pointer ke memori untuk mengembalikan nilai maksimum yang diharapkan dari parameter pulProgress . Nilai ini dapat berubah di seluruh panggilan ke metode ini. Untuk informasi selengkapnya tentang arti pulProgressMax, lihat deskripsi peAsynchPhase.

Jika pulProgressMax adalah pointer null, tidak ada nilai maksimum yang diharapkan yang dikembalikan.

peAsynchPhase[out]
Pointer ke memori untuk mengembalikan informasi tambahan mengenai kemajuan operasi asinkron. Nilai yang valid meliputi:

DBASYNCHPHASE_INITIALIZATION-Objek berada dalam fase inisialisasi. Argumen pulProgress dan pulProgressMax menunjukkan perkiraan rasio penyelesaian. Objek belum sepenuhnya terwujud. Mencoba memanggil antarmuka lain mungkin gagal, dan set lengkap antarmuka mungkin tidak tersedia pada objek. Jika operasi asinkron adalah hasil dari memanggil ICommand::Execute untuk perintah yang memperbarui, menghapus, atau menyisipkan baris dan jika cParamSets lebih besar dari 1, pulProgress dan pulProgressMax dapat menunjukkan kemajuan untuk satu set parameter atau untuk array lengkap set parameter.

DBASYNCHPHASE_POPULATION-Objek berada dalam fase populasi. Meskipun set baris sepenuhnya diinisialisasi dan berbagai antarmuka tersedia pada objek, mungkin ada baris tambahan yang belum diisi ke dalam set baris. Meskipun pulProgress dan pulProgressMax dapat didasarkan pada jumlah baris yang diisi, baris umumnya didasarkan pada waktu atau upaya yang diperlukan untuk mengisi set baris. Oleh karena itu, penelepon harus menggunakan informasi ini sebagai perkiraan kasar tentang berapa lama proses mungkin berlangsung, bukan jumlah baris akhir. Fase ini dikembalikan hanya selama populasi set baris; tidak pernah dikembalikan dalam inisialisasi objek sumber data atau dengan eksekusi perintah yang memperbarui, menghapus, atau menyisipkan baris.

DBASYNCHPHASE_COMPLETE-Semua pemrosesan asinkron objek telah selesai. ISSAsynchStatus::GetStatus mengembalikan HRESULT yang menunjukkan hasil operasi. Biasanya, ini akan menjadi HRESULT yang akan dikembalikan jika operasi dipanggil secara sinkron. Jika operasi asinkron adalah hasil dari memanggil ICommand::Execute untuk perintah yang memperbarui, menghapus, atau menyisipkan baris, pulProgress dan pulProgressMax sama dengan jumlah total baris yang terpengaruh oleh perintah. Jika cParamSets lebih besar dari 1, ini adalah jumlah total baris yang dipengaruhi oleh semua set parameter yang ditentukan dalam eksekusi. Jika peAsynchPhase adalah penunjuk null, tidak ada kode status yang dikembalikan.

pemrosesan objek DBASYNCHPHASE_CANCELED-Asinkron dibatalkan. ISSAsynchStatus::GetStatus mengembalikan DB_E_CANCELED. Jika operasi asinkron adalah hasil dari memanggil ICommand::Execute untuk perintah yang memperbarui, menghapus, atau menyisipkan baris, pulProgress sama dengan jumlah total baris, untuk semua set parameter, yang dipengaruhi oleh perintah sebelum pembatalan.

ppwszStatusText[in/out]
Pointer ke memori yang berisi informasi tambahan tentang operasi. Penyedia dapat menggunakan nilai ini untuk membedakan antara elemen operasi yang berbeda misalnya, sumber daya yang berbeda yang diakses. String ini dilokalkan sesuai dengan properti DBPROP_INIT_LCID pada objek sumber data.

Jika ppwszStatusText non-null pada input, penyedia mengembalikan status yang terkait dengan elemen tertentu yang diidentifikasi oleh ppwszStatusText. Jika ppwszStatusText tidak menunjukkan elemen eOperation, penyedia mengembalikan S_OK dengan pulProgress dan pulProgressMax yang diatur ke nilai yang sama. Jika penyedia tidak membedakan antara elemen berdasarkan pengidentifikasi tekstual, penyedia menetapkan ppwszStatusText ke NULL dan mengembalikan informasi tentang operasi secara keseluruhan; jika tidak, jika ppwszStatusText non-null pada input, penyedia meninggalkan ppwszStatusText tidak tersentuh.

Jika ppwszStatusText null pada input, penyedia mengatur ppwszStatusText ke nilai yang menunjukkan informasi lebih lanjut tentang operasi, atau ke NULL jika tidak ada informasi tersebut yang tersedia atau jika ISSAsynchStatus::GetStatus mengembalikan kesalahan. Ketika ppwszStatusText null pada input, penyedia mengalokasikan memori untuk string status dan mengembalikan alamat ke memori ini. Konsumen merilis memori ini dengan IMalloc::Free ketika tidak lagi membutuhkan string.

Jika ppwszStatusText adalah NULL pada input, tidak ada string status yang dikembalikan dan penyedia mengembalikan informasi tentang elemen operasi atau tentang operasi secara umum.

Mengembalikan Nilai Kode

S_OK
Metode berhasil ditampilkan.

  • Jika peAsynchPhase sama dengan DBASYNCHPHASE_INITIALIZATION, objek belum sepenuhnya diinisialisasi; mencoba memanggil antarmuka lain mungkin gagal, dan set lengkap antarmuka mungkin tidak tersedia pada objek.

  • Jika peAsynchPhase sama dengan DBASYNCHPHASE_POPULATION, set baris sepenuhnya diinisialisasi dan berbagai antarmuka tersedia pada objek; namun, mungkin ada baris tambahan yang belum diisi ke dalam set baris.

  • Jika peAsynchPhase sama dengan DBASYNCHPHASE_COMPLETE, semua pemrosesan asinkron objek telah selesai. Objek sepenuhnya diinisialisasi dan diisi.

DB_E_CANCELED
Pemrosesan asinkron dibatalkan selama populasi kumpulan baris. Populasi berhenti, tetapi set baris tetap valid untuk baris yang sudah diisi.

Pemrosesan asinkron dibatalkan selama inisialisasi objek sumber data. Objek sumber data dalam status tidak diinisialisasi.

E_INVALIDARG
Parameter hChapter salah.

E_UNEXPECTED
ISSAsynchStatus::GetStatus dipanggil pada objek sumber data, dan IDBInitialize::Initialize belum dipanggil pada objek sumber data.

ISSAsynchStatus::GetStatus dipanggil pada set baris, ITransaction::Commit atau ITransaction::Abort dipanggil, dan objek berada dalam keadaan zombie.

ISSAsynchStatus::GetStatus dipanggil pada set baris yang dibatalkan secara asinkron dalam fase inisialisasinya. Kumpulan baris berada dalam keadaan zombie.

E_FAIL
Terjadi kesalahan khusus penyedia.

Keterangan

Metode ISSAsynchStatus::GetStatus bertingkah persis seperti metode IDBAsynchStatus::GetStatus kecuali bahwa jika inisialisasi objek sumber data dibatalkan, E_UNEXPECTED dikembalikan daripada DB_E_CANCELED (meskipun ISSAsynchStatus::WaitForAsynchCompletion akan mengembalikan DB_E_CANCELED). Ini karena objek sumber data tidak dibiarkan dalam status zombie biasa setelah pembatalan, agar operasi inisialisasi lebih lanjut dapat dicoba.

Jika set baris diinisialisasi atau diisi secara asinkron, maka harus mendukung metode ini.

Selain nilai pengembalian yang tercantum, ISSAsynchStatus::GetStatus dapat mengembalikan HRESULT apa pun yang akan dikembalikan oleh metode yang memulai operasi asinkron, yang menunjukkan keberhasilan atau kegagalan operasi.

Beberapa operasi asinkron mungkin tidak dapat mengembalikan status apa pun selain "selesai" dan "belum selesai". Mereka harus mengatur pulProgressMax ke nilai 1, menunjukkan granularitas semua atau tidak sama sekali dari perkiraan mereka, sehingga jawabannya adalah 0/1 atau 1/1.

Penyedia dapat mengubah pulProgressMax dalam panggilan berturut-turut dan bahkan mengembalikan rasio yang lebih kecil dari sebelumnya, jika ini mencerminkan perkiraan yang meningkat dari tingkat penyelesaian tugas.

Penyedia tidak berkewajiban untuk menjamin akurasi lebih lanjut tetapi didorong untuk melakukannya dalam kasus di mana perkiraan penyelesaian yang wajar dimungkinkan. Upaya tersebut akan meningkatkan kualitas antarmuka pengguna karena penggunaan utama fungsi ini kemungkinan akan memberikan umpan balik kemajuan kepada pengguna. Kepuasan pengguna meningkat dengan kualitas umpan balik pada tugas yang tidak terlihat dan berjalan lama.

Memanggil ISSAsynchStatus::GetStatus pada objek sumber data yang diinisialisasi atau set baris yang diisi, atau meneruskan nilai untuk eOperasi selain DBASYNCHOP_OPEN, mengembalikan S_OK dengan pulProgress dan pulProgressMax yang diatur ke nilai yang sama. Jika ISSAsynchStatus::GetStatus dipanggil pada objek yang dibuat dari eksekusi perintah yang memperbarui, menghapus, atau menyisipkan baris, baik pulProgress maupun pulProgressMax menunjukkan jumlah total baris yang terpengaruh oleh perintah.

Lihat Juga

Melakukan Operasi Asinkron
ISSAsynchStatus (OLE DB)