Fungsi SQLCopyDesc
Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92
Ringkasan
SQLCopyDesc menyalin informasi deskriptor dari satu handel deskriptor ke yang lain.
Sintaks
SQLRETURN SQLCopyDesc(
SQLHDESC SourceDescHandle,
SQLHDESC TargetDescHandle);
Argumen
SourceDescHandle
[Input] Handel deskriptor sumber.
TargetDescHandle
[Input] Handel deskriptor target. Argumen TargetDescHandle dapat menjadi handel ke pendeskripsi aplikasi atau IPD. TargetDescHandle tidak dapat diatur ke handel ke IRD, atau SQLCopyDesc akan mengembalikan SQLSTATE HY016 (Tidak dapat mengubah deskriptor baris implementasi).
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Ketika SQLCopyDesc mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_DESC dan HandelTargetDescHandle. Jika SourceDescHandle yang tidak valid diteruskan dalam panggilan, SQL_INVALID_HANDLE akan dikembalikan tetapi tidak ada SQLSTATE yang akan dikembalikan. Tabel berikut mencantumkan nilai SQLSTATE yang umumnya dikembalikan oleh SQLCopyDesc dan menjelaskan masing-masing dalam konteks fungsi ini; notasi "(DM)" mendahului deskripsi SQLSTATEs yang dikembalikan oleh Driver Manager. Kode pengembalian yang terkait dengan setiap nilai SQLSTATE SQL_ERROR, kecuali disebutkan sebaliknya.
Ketika kesalahan dikembalikan, panggilan ke SQLCopyDesc segera dibatalkan, dan konten bidang dalam deskriptor TargetDescHandle tidak terdefinisi.
Karena SQLCopyDesc dapat diimplementasikan dengan memanggil SQLGetDescField dan SQLSetDescField, SQLCopyDesc dapat mengembalikan SQLSTATEs yang dikembalikan oleh SQLGetDescField atau SQLSetDescField.
| SQLSTATE | Kesalahan | Deskripsi |
|---|---|---|
| 01000 | Peringatan umum | Pesan informasi khusus driver. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Kegagalan tautan komunikasi | Tautan komunikasi antara driver dan sumber data tempat driver tersambung gagal sebelum fungsi selesai diproses. |
| HY000 | Kesalahan umum | Terjadi kesalahan yang tidak ada SQLSTATE tertentu dan tidak ada SQLSTATE khusus implementasi yang ditentukan. Pesan kesalahan yang dikembalikan oleh SQLGetDiagRec di buffer *MessageText menjelaskan kesalahan dan penyebabnya. |
| HY001 | Kesalahan alokasi memori | Driver tidak dapat mengalokasikan memori yang diperlukan untuk mendukung eksekusi atau penyelesaian fungsi. |
| HY007 | Pernyataan terkait tidak disiapkan | SourceDescHandle dikaitkan dengan IRD, dan handel pernyataan terkait tidak dalam status disiapkan atau dijalankan. |
| HY010 | Kesalahan urutan fungsi | (DM) Handel deskriptor di SourceDescHandle atau TargetDescHandle dikaitkan dengan StatementHandle yang fungsi eksekusinya secara asinkron (bukan yang ini) dipanggil dan masih dijalankan ketika fungsi ini dipanggil. (DM) Handel deskriptor di SourceDescHandle atau TargetDescHandle dikaitkan dengan StatementHandle tempat SQLExecute, SQLExecDirect, SQLBulkOperations, atau SQLSetPos dipanggil dan dikembalikan SQL_NEED_DATA. Fungsi ini dipanggil sebelum data dikirim untuk semua parameter atau kolom data-at-execution. (DM) Fungsi eksekusi asinkron dipanggil untuk handel koneksi yang terkait dengan SourceDescHandle atau TargetDescHandle. Fungsi asinkron ini masih dijalankan ketika fungsi SQLCopyDesc dipanggil. (DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk salah satu handel pernyataan yang terkait dengan SourceDescHandle atau TargetDescHandle dan dikembalikan SQL_PARAM_DATA_AVAILABLE. Fungsi ini dipanggil sebelum data diambil untuk semua parameter yang dialirkan. |
| HY013 | Kesalahan manajemen memori | Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah. |
| HY016 | Tidak dapat mengubah deskriptor baris implementasi | TargetDescHandle dikaitkan dengan IRD. |
| HY021 | Informasi deskriptor yang tidak konsisten | Informasi deskriptor yang diperiksa selama pemeriksaan konsistensi tidak konsisten. Untuk informasi selengkapnya, lihat "Pemeriksaan Konsistensi" di SQLSetDescField. |
| HY092 | Pengidentifikasi atribut/opsi tidak valid | Panggilan ke SQLCopyDesc meminta panggilan ke SQLSetDescField, tetapi *ValuePtr tidak valid untuk argumen FieldIdentifier pada TargetDescHandle. |
| HY117 | Koneksi ditangguhkan karena status transaksi yang tidak diketahui. Hanya fungsi putuskan sambungan dan baca-saja yang diizinkan. | (DM) Untuk informasi selengkapnya tentang status ditangguhkan, lihat Fungsi SQLEndTran. |
| HYT01 | Kesalahan waktu habis koneksi kedaluwarsa | Periode batas waktu koneksi kedaluwarsa sebelum sumber data merespons permintaan. Periode batas waktu koneksi diatur melalui SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Driver tidak mendukung fungsi ini | (DM) Driver yang terkait dengan SourceDescHandle atau TargetDescHandle tidak mendukung fungsi. |
Komentar
Panggilan ke SQLCopyDesc menyalin bidang handel deskriptor sumber ke handel deskriptor target. Bidang hanya dapat disalin ke deskriptor aplikasi atau IPD, tetapi tidak ke IRD. Bidang dapat disalin dari aplikasi atau pendeskripsi implementasi.
Bidang dapat disalin dari IRD hanya jika handel pernyataan dalam status disiapkan atau dijalankan; jika tidak, fungsi mengembalikan SQLSTATE HY007 (Pernyataan terkait tidak disiapkan).
Bidang dapat disalin dari IPD apakah pernyataan telah disiapkan atau belum. Jika pernyataan SQL dengan parameter dinamis telah disiapkan dan populasi otomatis IPD didukung dan diaktifkan, maka IPD diisi oleh driver. Ketika SQLCopyDesc dipanggil dengan IPD sebagai SourceDescHandle, bidang yang diisi disalin. Jika IPD tidak diisi oleh driver, konten bidang yang awalnya di IPD akan disalin.
Semua bidang deskriptor, kecuali SQL_DESC_ALLOC_TYPE (yang menentukan apakah handel deskriptor dialokasikan secara otomatis atau eksplisit), disalin, apakah bidang ditentukan untuk deskriptor tujuan atau tidak. Bidang yang disalin menimpa bidang yang ada.
Driver menyalin semua bidang deskriptor jika argumen SourceDescHandle dan TargetDescHandle dikaitkan dengan driver yang sama, bahkan jika driver berada di dua koneksi atau lingkungan yang berbeda. Jika argumen SourceDescHandle dan TargetDescHandle dikaitkan dengan driver yang berbeda, Driver Manager menyalin bidang yang ditentukan ODBC, tetapi tidak menyalin bidang atau bidang yang ditentukan driver yang tidak ditentukan oleh ODBC untuk jenis deskriptor.
Panggilan ke SQLCopyDesc segera dibatalkan jika terjadi kesalahan.
Saat bidang SQL_DESC_DATA_PTR disalin, pemeriksaan konsistensi dilakukan pada deskriptor target. Jika pemeriksaan konsistensi gagal, SQLSTATE HY021 (Informasi deskriptor tidak konsisten) dikembalikan dan panggilan ke SQLCopyDesc segera dibatalkan. Untuk informasi selengkapnya tentang pemeriksaan konsistensi, lihat "Pemeriksaan Konsistensi" di Fungsi SQLSetDescRec.
Handel deskriptor dapat disalin di seluruh koneksi bahkan jika koneksi berada di bawah lingkungan yang berbeda. Jika Manajer Driver mendeteksi bahwa sumber dan pendeskripsi tujuan menangani bukan milik koneksi yang sama dan dua koneksi milik driver terpisah, itu mengimplementasikan SQLCopyDesc dengan melakukan salinan bidang demi bidang menggunakan SQLGetDescField dan SQLSetDescField.
Ketika SQLCopyDesc dipanggil dengan SourceDescHandle pada satu driver dan TargetDescHandle pada driver lain, antrean kesalahan SourceDescHandle dihapus. Ini terjadi karena SQLCopyDesc dalam hal ini diimplementasikan oleh panggilan ke SQLGetDescField dan SQLSetDescField.
Catatan
Aplikasi mungkin dapat mengaitkan handel deskriptor yang dialokasikan secara eksplisit dengan StatementHandle, daripada memanggil SQLCopyDesc untuk menyalin bidang dari satu deskriptor ke deskriptor lainnya. Deskriptor yang dialokasikan secara eksplisit dapat dikaitkan dengan StatementHandle lain pada ConnectionHandle yang sama dengan mengatur atribut pernyataan SQL_ATTR_APP_ROW_DESC atau SQL_ATTR_APP_PARAM_DESC ke handel deskriptor yang dialokasikan secara eksplisit. Setelah ini selesai, SQLCopyDesc tidak harus dipanggil untuk menyalin nilai bidang deskriptor dari satu deskriptor ke deskriptor lainnya. Handel deskriptor tidak dapat dikaitkan dengan StatementHandle pada ConnectionHandle lain, namun; untuk menggunakan nilai bidang deskriptor yang sama pada StatementHandles pada ConnectionHandles yang berbeda, SQLCopyDesc harus dipanggil.
Untuk deskripsi bidang di header atau rekaman deskriptor, lihat Fungsi SQLSetDescField. Untuk informasi selengkapnya tentang deskriptor, lihat Deskriptor.
Menyalin Baris Antar Tabel
Aplikasi dapat menyalin data dari satu tabel ke tabel lain tanpa menyalin data di tingkat aplikasi. Untuk melakukan ini, aplikasi mengikat buffer data dan informasi deskriptor yang sama ke pernyataan yang mengambil data dan pernyataan yang menyisipkan data ke dalam salinan. Ini dapat dicapai baik dengan berbagi deskriptor aplikasi (mengikat deskriptor yang dialokasikan secara eksplisit sebagai ARD ke satu pernyataan dan APD di pernyataan lain) atau dengan menggunakan SQLCopyDesc untuk menyalin pengikatan antara ARD dan APD dari dua pernyataan. Jika pernyataan berada pada koneksi yang berbeda, SQLCopyDesc harus digunakan. Selain itu, SQLCopyDesc harus dipanggil untuk menyalin pengikatan antara IRD dan IPD dari dua pernyataan. Saat menyalin seluruh pernyataan pada koneksi yang sama, jenis informasi SQL_ACTIVE_STATEMENTS yang dikembalikan oleh driver untuk panggilan ke SQLGetInfo harus lebih besar dari 1 agar operasi ini berhasil. (Ini tidak terjadi saat menyalin di seluruh koneksi.)
Contoh Kode
Dalam contoh berikut, operasi deskriptor digunakan untuk menyalin bidang tabel PartsSource ke dalam tabel PartsCopy. Konten tabel PartsSource diambil ke dalam buffer set baris di hstmt0. Nilai-nilai ini digunakan sebagai parameter pernyataan INSERT pada hstmt1 untuk mengisi kolom tabel PartsCopy. Untuk melakukannya, bidang IRD hstmt0 disalin ke bidang IPD hstmt1, dan bidang ARD hstmt0disalin ke bidang APD hstmt1. Gunakan SQLSetDescField untuk mengatur atribut SQL_DESC_PARAMETER_TYPE IPD ke SQL_PARAM_INPUT saat Anda menyalin bidang IRD dari pernyataan dengan parameter output ke bidang IPD yang perlu menjadi parameter input.
#define ROWS 100
#define DESC_LEN 50
#define SQL_SUCCEEDED(rc) (rc == SQL_SUCCESS || rc == SQL_SUCCESS_WITH_INFO)
// Template for a row
typedef struct {
SQLINTEGER sPartID;
SQLINTEGER cbPartID;
SQLUCHAR szDescription[DESC_LENGTH];
SQLINTEGER cbDescription;
REAL sPrice;
SQLINTEGER cbPrice;
} PartsSource;
PartsSource rget[ROWS]; // rowset buffer
SQLUSMALLINT sts_ptr[ROWS]; // status pointer
SQLHSTMT hstmt0, hstmt1;
SQLHDESC hArd0, hIrd0, hApd1, hIpd1;
// ARD and IRD of hstmt0
SQLGetStmtAttr(hstmt0, SQL_ATTR_APP_ROW_DESC, &hArd0, 0, NULL);
SQLGetStmtAttr(hstmt0, SQL_ATTR_IMP_ROW_DESC, &hIrd0, 0, NULL);
// APD and IPD of hstmt1
SQLGetStmtAttr(hstmt1, SQL_ATTR_APP_PARAM_DESC, &hApd1, 0, NULL);
SQLGetStmtAttr(hstmt1, SQL_ATTR_IMP_PARAM_DESC, &hIpd1, 0, NULL);
// Use row-wise binding on hstmt0 to fetch rows
SQLSetStmtAttr(hstmt0, SQL_ATTR_ROW_BIND_TYPE, (SQLPOINTER) sizeof(PartsSource), 0);
// Set rowset size for hstmt0
SQLSetStmtAttr(hstmt0, SQL_ATTR_ROW_ARRAY_SIZE, (SQLPOINTER) ROWS, 0);
// Execute a select statement
SQLExecDirect(hstmt0, "SELECT PARTID, DESCRIPTION, PRICE FROM PARTS ORDER BY 3, 1, 2"",
SQL_NTS);
// Bind
SQLBindCol(hstmt0, 1, SQL_C_SLONG, rget[0].sPartID, 0,
&rget[0].cbPartID);
SQLBindCol(hstmt0, 2, SQL_C_CHAR, &rget[0].szDescription, DESC_LEN,
&rget[0].cbDescription);
SQLBindCol(hstmt0, 3, SQL_C_FLOAT, rget[0].sPrice,
0, &rget[0].cbPrice);
// Perform parameter bindings on hstmt1.
SQLCopyDesc(hArd0, hApd1);
SQLCopyDesc(hIrd0, hIpd1);
// Set the array status pointer of IRD
SQLSetStmtAttr(hstmt0, SQL_ATTR_ROW_STATUS_PTR, sts_ptr, SQL_IS_POINTER);
// Set the ARRAY_STATUS_PTR field of APD to be the same
// as that in IRD.
SQLSetStmtAttr(hstmt1, SQL_ATTR_PARAM_OPERATION_PTR, sts_ptr, SQL_IS_POINTER);
// Set the hIpd1 records as input parameters
rc = SQLSetDescField(hIpd1, 1, SQL_DESC_PARAMETER_TYPE, (SQLPOINTER)SQL_PARAM_INPUT, SQL_IS_INTEGER);
rc = SQLSetDescField(hIpd1, 2, SQL_DESC_PARAMETER_TYPE, (SQLPOINTER)SQL_PARAM_INPUT, SQL_IS_INTEGER);
rc = SQLSetDescField(hIpd1, 3, SQL_DESC_PARAMETER_TYPE, (SQLPOINTER)SQL_PARAM_INPUT, SQL_IS_INTEGER);
// Prepare an insert statement on hstmt1. PartsCopy is a copy of
// PartsSource
SQLPrepare(hstmt1, "INSERT INTO PARTS_COPY VALUES (?, ?, ?)", SQL_NTS);
// In a loop, fetch a rowset, and copy the fetched rowset to PARTS_COPY
rc = SQLFetchScroll(hstmt0, SQL_FETCH_NEXT, 0);
while (SQL_SUCCEEDED(rc)) {
// After the call to SQLFetchScroll, the status array has row
// statuses. This array is used as input status in the APD
// and hence determines which elements of the rowset buffer
// are inserted.
SQLExecute(hstmt1);
rc = SQLFetchScroll(hstmt0, SQL_FETCH_NEXT, 0);
} // while
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mendapatkan beberapa bidang deskriptor | Fungsi SQLGetDescRec |
| Mengatur bidang deskriptor tunggal | Fungsi SQLSetDescField |
| Mengatur beberapa bidang deskriptor | Fungsi SQLSetDescRec |
Lihat Juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk