Fungsi SQLProcedureColumns
Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 1.0: ODBC
Ringkasan
SQLProcedureColumns mengembalikan daftar parameter input dan output, serta kolom yang membentuk hasil yang ditetapkan untuk prosedur yang ditentukan. Driver mengembalikan informasi sebagai hasil yang ditetapkan pada pernyataan yang ditentukan.
Sintaks
SQLRETURN SQLProcedureColumns(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * ProcName,
SQLSMALLINT NameLength3,
SQLCHAR * ColumnName,
SQLSMALLINT NameLength4);
Argumen
StatementHandle
[Input] Handel pernyataan.
CatalogName
[Input] Nama katalog prosedur. Jika driver mendukung katalog untuk beberapa prosedur tetapi tidak untuk yang lain, seperti ketika driver mengambil data dari DBMS yang berbeda, string kosong ("") menunjukkan prosedur yang tidak memiliki katalog. CatalogName tidak boleh berisi pola pencarian string.
Jika atribut pernyataan SQL_ATTR_METADATA_ID diatur ke SQL_TRUE, CatalogName diperlakukan sebagai pengidentifikasi dan kasusnya tidak signifikan. Jika SQL_FALSE, CatalogName adalah argumen biasa; itu diperlakukan secara harfiah, dan kasusnya signifikan. Untuk informasi selengkapnya, lihat Argumen di Fungsi Katalog.
NameLength1
[Input] Panjang karakter *CatalogName.
SchemaName
[Input] Pola pencarian string untuk nama skema prosedur. Jika driver mendukung skema untuk beberapa prosedur tetapi tidak untuk yang lain, seperti ketika driver mengambil data dari DBMS yang berbeda, string kosong ("") menunjukkan prosedur yang tidak memiliki skema.
Jika atribut pernyataan SQL_ATTR_METADATA_ID diatur ke SQL_TRUE, SchemaName diperlakukan sebagai pengidentifikasi dan kasusnya tidak signifikan. Jika SQL_FALSE, SchemaName adalah argumen nilai pola; itu diperlakukan secara harfiah, dan kasusnya signifikan.
NameLength2
[Input] Panjang karakter *SchemaName.
ProcName
[Input] Pola pencarian string untuk nama prosedur.
Jika atribut pernyataan SQL_ATTR_METADATA_ID diatur ke SQL_TRUE, ProcName diperlakukan sebagai pengidentifikasi dan kasusnya tidak signifikan. Jika SQL_FALSE, ProcName adalah argumen nilai pola; itu diperlakukan secara harfiah, dan kasusnya signifikan.
NameLength3
[Input] Panjang karakter *ProcName.
ColumnName
[Input] Pola pencarian string untuk nama kolom.
Jika atribut pernyataan SQL_ATTR_METADATA_ID diatur ke SQL_TRUE, ColumnName diperlakukan sebagai pengidentifikasi dan kasusnya tidak signifikan. Jika SQL_FALSE, ColumnName adalah argumen nilai pola; itu diperlakukan secara harfiah, dan kasusnya signifikan.
NameLength4
[Input] Panjang karakter *ColumnName.
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Ketika SQLProcedureColumns mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_STMT dan Handle of StatementHandle. Tabel berikut mencantumkan nilai SQLSTATE yang umumnya dikembalikan oleh SQLProcedureColumns 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.
| 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. |
| 24000 | Status kursor tidak valid | Kursor terbuka pada StatementHandle, dan SQLFetch atau SQLFetchScroll telah dipanggil. Kesalahan ini dikembalikan oleh Driver Manager jika SQLFetch atau SQLFetchScroll belum mengembalikan SQL_NO_DATA, dan dikembalikan oleh driver jika SQLFetch atau SQLFetchScroll telah mengembalikan SQL_NO_DATA. Kursor terbuka pada StatementHandle, tetapi SQLFetch atau SQLFetchScroll belum dipanggil. |
| 40001 | Kegagalan serialisasi | Transaksi digulung balik karena kebuntuan sumber daya dengan transaksi lain. |
| 40003 | Penyelesaian pernyataan tidak diketahui | Koneksi terkait gagal selama eksekusi fungsi ini, dan status transaksi tidak dapat ditentukan. |
| HY000 | Kesalahan umum | Terjadi kesalahan yang tidak ada SQLSTATE tertentu dan tidak ada SQLSTATE khusus implementasi yang ditentukan. Pesan kesalahan yang dikembalikan oleh SQLError di buffer *MessageText menjelaskan kesalahan dan penyebabnya. |
| HY001 | Kesalahan alokasi memori | Driver tidak dapat mengalokasikan memori yang diperlukan untuk mendukung eksekusi atau penyelesaian fungsi. |
| HY008 | Operasi dibatalkan | Pemrosesan asinkron diaktifkan untuk StatementHandle. Fungsi ini dipanggil, dan sebelum selesai dieksekusi, SQLCancel atau SQLCancelHandle dipanggil pada StatementHandle. Kemudian fungsi dipanggil lagi pada StatementHandle. Fungsi ini dipanggil, dan sebelum selesai dieksekusi, SQLCancel atau SQLCancelHandle dipanggil pada StatementHandle dari utas yang berbeda dalam aplikasi multithread. |
| HY009 | Penggunaan pointer null tidak valid | Atribut pernyataan SQL_ATTR_METADATA_ID diatur ke SQL_TRUE, argumen CatalogName adalah pointer null, dan infoType SQL_CATALOG_NAME mengembalikan bahwa nama katalog didukung. (DM) Atribut pernyataan SQL_ATTR_METADATA_ID diatur ke SQL_TRUE, dan argumen SchemaName, ProcName, atau ColumnName adalah pointer null. |
| HY010 | Kesalahan urutan fungsi | (DM) Fungsi eksekusi asinkron dipanggil untuk handel koneksi yang terkait dengan StatementHandle. Fungsi aynschronous ini masih dijalankan ketika fungsi SQLProcedureColumns dipanggil. (DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk StatementHandle dan dikembalikan SQL_PARAM_DATA_AVAILABLE. Fungsi ini dipanggil sebelum data diambil untuk semua parameter yang dialirkan. (DM) Fungsi eksekusi asinkron (bukan yang ini) dipanggil untuk StatementHandle dan masih dijalankan ketika fungsi ini dipanggil. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations, atau SQLSetPos dipanggil untuk StatementHandle dan dikembalikan SQL_NEED_DATA. Fungsi ini dipanggil sebelum data dikirim untuk semua parameter atau kolom data-at-execution. |
| HY090 | String atau panjang buffer tidak valid | (DM) Nilai salah satu argumen panjang nama kurang dari 0 tetapi tidak sama dengan SQL_NTS. Nilai salah satu argumen panjang nama melebihi nilai panjang maksimum untuk katalog, skema, prosedur, atau nama kolom yang sesuai. |
| 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. |
| HYC00 | Fitur opsional tidak diimplementasikan | Katalog prosedur ditentukan, dan driver atau sumber data tidak mendukung katalog. Skema prosedur ditentukan, dan driver atau sumber data tidak mendukung skema. Pola pencarian string ditentukan untuk skema prosedur, nama prosedur, atau nama kolom, dan sumber data tidak mendukung pola pencarian untuk satu atau beberapa argumen tersebut. Kombinasi pengaturan saat ini dari atribut pernyataan SQL_ATTR_CONCURRENCY dan SQL_ATTR_CURSOR_TYPE tidak didukung oleh driver atau sumber data. Atribut pernyataan SQL_ATTR_USE_BOOKMARKS diatur ke SQL_UB_VARIABLE, dan atribut pernyataan SQL_ATTR_CURSOR_TYPE diatur ke jenis kursor yang drivernya tidak mendukung marka buku. |
| HYT00 | Waktu habis kedaluwarsa | Periode batas waktu kedaluwarsa sebelum sumber data mengembalikan tataan hasil. Periode batas waktu diatur melalui SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| 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 StatementHandle tidak mendukung fungsi. |
| IM017 | Polling dinonaktifkan dalam mode pemberitahuan asinkron | Setiap kali model pemberitahuan digunakan, polling dinonaktifkan. |
| IM018 | SQLCompleteAsync belum dipanggil untuk menyelesaikan operasi asinkron sebelumnya pada handel ini. | Jika panggilan fungsi sebelumnya pada handel mengembalikan SQL_STILL_EXECUTING dan jika mode pemberitahuan diaktifkan, SQLCompleteAsync harus dipanggil pada handel untuk melakukan pasca-pemrosesan dan menyelesaikan operasi. |
Komentar
Fungsi ini biasanya digunakan sebelum eksekusi pernyataan untuk mengambil informasi tentang parameter prosedur dan kolom yang membentuk kumpulan hasil atau set yang dikembalikan oleh prosedur, jika ada. Untuk informasi selengkapnya, lihat Prosedur.
Catatan
SQLProcedureColumns mungkin tidak mengembalikan semua kolom yang digunakan oleh prosedur. Misalnya, driver mungkin hanya mengembalikan informasi tentang parameter yang digunakan oleh prosedur dan bukan kolom dalam tataan hasil yang dihasilkannya.
Argumen SchemaName, ProcName, dan ColumnName menerima pola pencarian. Untuk informasi selengkapnya tentang pola pencarian yang valid, lihat Argumen Nilai Pola.
Catatan
Untuk informasi selengkapnya tentang penggunaan umum, argumen, dan data fungsi katalog ODBC yang dikembalikan, lihat Fungsi Katalog.
SQLProcedureColumns mengembalikan hasil sebagai hasil standar yang ditetapkan, diurutkan berdasarkan PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME, dan COLUMN_TYPE. Nama kolom dikembalikan untuk setiap prosedur dalam urutan berikut: nama nilai yang dikembalikan, nama setiap parameter dalam pemanggilan prosedur (dalam urutan panggilan), lalu nama setiap kolom dalam tataan hasil yang dikembalikan oleh prosedur (dalam urutan kolom).
Aplikasi harus mengikat kolom khusus driver relatif terhadap akhir tataan hasil. Untuk informasi selengkapnya, lihat Data yang Dikembalikan oleh Fungsi Katalog.
Untuk menentukan panjang aktual kolom PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME, dan COLUMN_NAME, aplikasi dapat memanggil SQLGetInfo dengan opsi SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_PROCEDURE_NAME_LEN, dan SQL_MAX_COLUMN_NAME_LEN.
Kolom berikut telah diganti namanya menjadi ODBC 3.x. Perubahan nama kolom tidak memengaruhi kompatibilitas mundur karena aplikasi mengikat dengan nomor kolom.
| Kolom ODBC 2.0 | ODBC 3.kolom x |
|---|---|
| PROCEDURE_QUALIFIER | PROCEDURE_CAT |
| _OWNER PROSEDUR | PROCEDURE_SCHEM |
| PRESISI | COLUMN_SIZE |
| LENGTH | BUFFER_LENGTH |
| SKALA | DECIMAL_DIGITS |
| RADIX | NUM_PREC_RADIX |
Kolom berikut telah ditambahkan ke kumpulan hasil yang dikembalikan oleh SQLProcedureColumns untuk ODBC 3.x:
COLUMN_DEF
DATETIME_CODE
CHAR_OCTET_LENGTH
ORDINAL_POSITION
IS_NULLABLE
Tabel berikut mencantumkan kolom dalam tataan hasil. Kolom tambahan di luar kolom 19 (IS_NULLABLE) dapat ditentukan oleh driver. Aplikasi harus mendapatkan akses ke kolom khusus driver dengan menghitung mundur dari akhir tataan hasil daripada menentukan posisi ordinal eksplisit. Untuk informasi selengkapnya, lihat Data yang Dikembalikan oleh Fungsi Katalog.
| Nama kolom | Nomor kolom | Jenis Data | Komentar |
|---|---|---|---|
| PROCEDURE_CAT (ODBC 2.0) | 1 | Varchar | Nama katalog prosedur; NULL jika tidak berlaku untuk sumber data. Jika driver mendukung katalog untuk beberapa prosedur tetapi tidak untuk yang lain, seperti ketika driver mengambil data dari DBMS yang berbeda, driver mengembalikan string kosong ("") untuk prosedur yang tidak memiliki katalog. |
| PROCEDURE_SCHEM (ODBC 2.0) | 2 | Varchar | Nama skema prosedur; NULL jika tidak berlaku untuk sumber data. Jika driver mendukung skema untuk beberapa prosedur tetapi tidak untuk yang lain, seperti ketika driver mengambil data dari DBMS yang berbeda, driver mengembalikan string kosong ("") untuk prosedur yang tidak memiliki skema. |
| PROCEDURE_NAME (ODBC 2.0) | 3 | Varchar bukan NULL | Nama prosedur. String kosong dikembalikan untuk prosedur yang tidak memiliki nama. |
| COLUMN_NAME (ODBC 2.0) | 4 | Varchar bukan NULL | Nama kolom prosedur. Driver mengembalikan string kosong untuk kolom prosedur yang tidak memiliki nama. |
| COLUMN_TYPE (ODBC 2.0) | 5 | Smallint bukan NULL | Menentukan kolom prosedur sebagai parameter atau kolom tataan hasil: SQL_PARAM_TYPE_UNKNOWN: Kolom prosedur adalah parameter yang jenisnya tidak diketahui. (ODBC 1.0) SQL_PARAM_INPUT: Kolom prosedur adalah parameter input. (ODBC 1.0) SQL_PARAM_INPUT_OUTPUT: Kolom prosedur adalah parameter input/output. (ODBC 1.0) SQL_PARAM_OUTPUT: Kolom prosedur adalah parameter output. (ODBC 2.0) SQL_RETURN_VALUE: Kolom prosedur adalah nilai pengembalian prosedur. (ODBC 2.0) SQL_RESULT_COL: Kolom prosedur adalah kolom kumpulan hasil. (ODBC 1.0) |
| DATA_TYPE (ODBC 2.0) | 6 | Smallint bukan NULL | Jenis data SQL. Ini bisa berupa jenis data ODBC SQL atau jenis data SQL khusus driver. Untuk jenis data tanggalwaktu dan interval, kolom ini mengembalikan jenis data ringkas (misalnya, SQL_TYPE_TIME atau SQL_INTERVAL_YEAR_TO_MONTH). Untuk daftar tipe data ODBC SQL yang valid, lihat Jenis Data SQL di Lampiran D: Jenis Data. Untuk informasi tentang jenis data SQL khusus driver, lihat dokumentasi driver. |
| TYPE_NAME (ODBC 2.0) | 7 | Varchar bukan NULL | Nama jenis data yang bergantung pada sumber data; misalnya, "CHAR", "VARCHAR", "MONEY", "LONG VARBINARY", atau "CHAR ( ) FOR BIT DATA". |
| COLUMN_SIZE (ODBC 2.0) | 8 | Bilangan bulat | Ukuran kolom kolom prosedur pada sumber data. NULL dikembalikan untuk jenis data di mana ukuran kolom tidak berlaku. Untuk informasi selengkapnya tentang presisi, lihat Ukuran Kolom, Digit Desimal, Panjang Oktet Transfer, dan Ukuran Tampilan dalam Lampiran D: Jenis Data. |
| BUFFER_LENGTH (ODBC 2.0) | 9 | Bilangan bulat | Panjang byte data yang ditransfer pada operasi SQLGetData atau SQLFetch jika SQL_C_DEFAULT ditentukan. Untuk data numerik, ukuran ini mungkin berbeda dari ukuran data yang disimpan pada sumber data. Untuk informasi selengkapnya, lihat Ukuran Kolom, Digit Desimal, Panjang Oktet Transfer, dan Ukuran Tampilan, di Lampiran D: Jenis Data. |
| DECIMAL_DIGITS (ODBC 2.0) | 10 | Smallint | Digit desimal kolom prosedur pada sumber data. NULL dikembalikan untuk jenis data di mana digit desimal tidak berlaku. Untuk informasi selengkapnya tentang digit desimal, lihat Ukuran Kolom, Digit Desimal, Panjang Oktet Transfer, dan Ukuran Tampilan, di Lampiran D: Jenis Data. |
| NUM_PREC_RADIX (ODBC 2.0) | 11 | Smallint | Untuk jenis data numerik, baik 10 atau 2. Jika 10, nilai dalam COLUMN_SIZE dan DECIMAL_DIGITS memberikan jumlah digit desimal yang diizinkan untuk kolom. Misalnya, kolom DECIMAL(12,5) akan mengembalikan NUM_PREC_RADIX 10, COLUMN_SIZE 12, dan DECIMAL_DIGITS 5; kolom FLOAT dapat mengembalikan NUM_PREC_RADIX 10, COLUMN_SIZE 15, dan DECIMAL_DIGITS NULL. Jika 2, nilai dalam COLUMN_SIZE dan DECIMAL_DIGITS memberikan jumlah bit yang diizinkan dalam kolom. Misalnya, kolom FLOAT dapat mengembalikan NUM_PREC_RADIX 2, COLUMN_SIZE 53, dan DECIMAL_DIGITS NULL. NULL dikembalikan untuk jenis data di mana NUM_PREC_RADIX tidak berlaku. |
| NULLABLE (ODBC 2.0) | 12 | Smallint bukan NULL | Apakah kolom prosedur menerima nilai NULL: SQL_NO_NULLS: Kolom prosedur tidak menerima nilai NULL. SQL_NULLABLE: Kolom prosedur menerima nilai NULL. SQL_NULLABLE_UNKNOWN: Tidak diketahui apakah kolom prosedur menerima nilai NULL. |
| KETERANGAN (ODBC 2.0) | 13 | Varchar | Deskripsi kolom prosedur. |
| COLUMN_DEF (ODBC 3.0) | 14 | Varchar | Nilai default kolom. Jika NULL ditentukan sebagai nilai default, kolom ini adalah kata NULL, tidak diapit dalam tanda kutip. Jika nilai default tidak dapat diwakili tanpa pemotongan, kolom ini berisi TRUNCATED, tanpa menyertakan tanda kutip tunggal. Jika tidak ada nilai default yang ditentukan, kolom ini adalah NULL. Nilai COLUMN_DEF dapat digunakan dalam menghasilkan definisi kolom baru, kecuali ketika berisi nilai TRUNCATED. |
| SQL_DATA_TYPE (ODBC 3.0) | 15 | Smallint bukan NULL | Nilai jenis data SQL seperti yang muncul di bidang SQL_DESC_TYPE deskriptor. Kolom ini sama dengan kolom DATA_TYPE, kecuali untuk jenis data tanggalwaktu dan interval. Untuk jenis data tanggalwaktu dan interval, bidang SQL_DATA_TYPE dalam kumpulan hasil akan mengembalikan SQL_INTERVAL atau SQL_DATETIME, dan bidang SQL_DATETIME_SUB akan mengembalikan subkode untuk jenis data interval atau tanggalwaktu tertentu. (Lihat Lampiran D: Jenis Data.) |
| SQL_DATETIME_SUB (ODBC 3.0) | 16 | Smallint | Kode subjenis untuk jenis data tanggalwaktu dan interval. Untuk jenis data lainnya, kolom ini mengembalikan NULL. |
| CHAR_OCTET_LENGTH (ODBC 3.0) | 17 | Bilangan bulat | Panjang maksimum dalam byte dari kolom tipe data karakter atau biner. Untuk semua jenis data lainnya, kolom ini mengembalikan NULL. |
| ORDINAL_POSITION (ODBC 3.0) | 18 | Bilangan bulat bukan NULL | Untuk parameter input dan output, posisi ordinal parameter dalam definisi prosedur (dalam urutan parameter yang meningkat, mulai dari 1). Untuk nilai yang dikembalikan (jika ada), 0 dikembalikan. Untuk kolom tataan hasil, posisi ordinal kolom dalam tataan hasil, dengan kolom pertama dalam tataan hasil adalah angka 1. Jika ada beberapa tataan hasil, posisi ordinal kolom dikembalikan dengan cara khusus driver. |
| IS_NULLABLE (ODBC 3.0) | 19 | Varchar | "TIDAK" jika kolom tidak menyertakan NULL. "YA" jika kolom dapat menyertakan NULL. Kolom ini mengembalikan string panjang nol jika nullability tidak diketahui. Aturan ISO diikuti untuk menentukan nullability. DBMS yang mematuhi ISO SQL tidak dapat mengembalikan string kosong. Nilai yang dikembalikan untuk kolom ini berbeda dari nilai yang dikembalikan untuk kolom NULLABLE. (Lihat deskripsi kolom NULLABLE.) |
Contoh Kode
Lihat Panggilan Prosedur.
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengikat buffer ke kolom dalam tataan hasil | Fungsi SQLBindCol |
| Membatalkan pemrosesan pernyataan | Fungsi SQLCancel |
| Mengambil satu baris atau blok data dalam arah terusan saja | Fungsi SQLFetch |
| Mengambil blok data atau menggulir melalui kumpulan hasil | Fungsi SQLFetchScroll |
| Mengembalikan daftar prosedur dalam sumber data | Fungsi SQLProcedures |