Fungsi SQLDescribeParam
Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 1.0: ODBC
Ringkasan
SQLDescribeParam mengembalikan deskripsi penanda parameter yang terkait dengan pernyataan SQL yang disiapkan. Informasi ini juga tersedia di bidang IPD.
Sintaks
SQLRETURN SQLDescribeParam(
SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT * DataTypePtr,
SQLULEN * ParameterSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
Argumen
StatementHandle
[Input] Handel pernyataan.
ParameterNumber
[Input] Nomor penanda parameter diurutkan secara berurutan dalam meningkatkan urutan parameter, mulai dari 1.
DataTypePtr
[Output] Penunjuk ke buffer untuk mengembalikan jenis data SQL parameter. Nilai ini dibaca dari bidang rekaman SQL_DESC_CONCISE_TYPE IPD. Ini akan menjadi salah satu nilai di bagian Jenis Data SQL dari Lampiran D: Jenis Data, atau jenis data SQL khusus driver.
Di ODBC 3.x, SQL_TYPE_DATE, SQL_TYPE_TIME, atau SQL_TYPE_TIMESTAMP akan dikembalikan dalam *DataTypePtr untuk data tanggal, waktu, atau tanda waktu, masing-masing; di ODBC 2.x, SQL_DATE, SQL_TIME, atau SQL_TIMESTAMP akan dikembalikan. Driver Manager melakukan pemetaan yang diperlukan saat ODBC 2.aplikasi x bekerja dengan ODBC 3.x driver atau ketika ODBC 3.aplikasi x bekerja dengan ODBC 2.x driver.
Ketika ColumnNumber sama dengan 0 (untuk kolom bookmark), SQL_BINARY dikembalikan dalam *DataTypePtr untuk bookmark panjang variabel. (SQL_INTEGER dikembalikan jika marka buku digunakan oleh ODBC 3.aplikasi x bekerja dengan ODBC 2.x driver atau oleh ODBC 2.aplikasi x bekerja dengan ODBC 3.x driver.)
Untuk informasi selengkapnya, lihat Jenis Data SQL di Lampiran D: Jenis Data. Untuk informasi tentang jenis data SQL khusus driver, lihat dokumentasi driver.
ParameterSizePtr
[Output] Penunjuk ke buffer untuk mengembalikan ukuran, dalam karakter, kolom atau ekspresi penanda parameter terkait seperti yang ditentukan oleh sumber data. Untuk informasi selengkapnya tentang ukuran kolom, lihat Ukuran Kolom, Digit Desimal, Panjang Oktet Transfer, dan Ukuran Tampilan.
DecimalDigitsPtr
[Output] Penunjuk ke buffer untuk mengembalikan jumlah digit desimal kolom atau ekspresi parameter terkait seperti yang ditentukan oleh sumber data. Untuk informasi selengkapnya tentang digit desimal, lihat Ukuran Kolom, Digit Desimal, Panjang Oktet Transfer, dan Ukuran Tampilan.
NullablePtr
[Output] Penunjuk ke buffer untuk mengembalikan nilai yang menunjukkan apakah parameter mengizinkan nilai NULL. Nilai ini dibaca dari bidang SQL_DESC_NULLABLE IPD. Salah satu dari berikut ini:
SQL_NO_NULLS: Parameter tidak mengizinkan nilai NULL (ini adalah nilai default).
SQL_NULLABLE: Parameter memungkinkan nilai NULL.
SQL_NULLABLE_UNKNOWN: Driver tidak dapat menentukan apakah parameter mengizinkan nilai NULL.
Mengembalikan
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Saat SQLDescribeParam 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 biasanya dikembalikan oleh SQLDescribeParam 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.) |
| 07009 | Indeks deskriptor tidak valid | (DM) Nilai yang ditentukan untuk parameter ParameterNumber kurang dari 1. Nilai yang ditentukan untuk parameter ParameterNumber lebih besar dari jumlah parameter dalam pernyataan SQL terkait. Penanda parameter adalah bagian dari pernyataan non-DML. Penanda parameter adalah bagian dari daftar SELECT . |
| 08S01 | Kegagalan tautan komunikasi | Tautan komunikasi antara driver dan sumber data tempat driver tersambung gagal sebelum fungsi selesai diproses. |
| 21S01 | Sisipkan daftar nilai tidak cocok dengan daftar kolom | Jumlah parameter dalam pernyataan INSERT tidak cocok dengan jumlah kolom dalam tabel bernama dalam pernyataan. |
| 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. |
| 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. |
| HY010 | Kesalahan urutan fungsi | (DM) Fungsi ini dipanggil sebelum memanggil SQLPrepare atau SQLExecDirect untuk StatementHandle. (DM) Fungsi eksekusi asinkron dipanggil untuk handel koneksi yang terkait dengan StatementHandle. Fungsi asinkron ini masih dijalankan ketika fungsi SQLDescribeParam dipanggil. (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. |
| HY013 | Kesalahan manajemen memori | Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah. |
| 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 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
Penanda parameter diberi nomor dalam meningkatkan urutan parameter, dimulai dengan 1, dalam urutan muncul dalam pernyataan SQL.
SQLDescribeParam tidak mengembalikan jenis (input, input/output, atau output) dari parameter dalam pernyataan SQL. Kecuali dalam panggilan ke prosedur, semua parameter dalam pernyataan SQL adalah parameter input. Untuk menentukan jenis setiap parameter dalam panggilan ke prosedur, aplikasi memanggil SQLProcedureColumns.
Untuk informasi selengkapnya, lihat Menjelaskan Parameter.
Contoh Kode
Contoh berikut meminta pernyataan SQL kepada pengguna lalu menyiapkan pernyataan tersebut. Selanjutnya, ia memanggil SQLNumParams untuk menentukan apakah pernyataan berisi parameter apa pun. Jika pernyataan berisi parameter, pernyataan memanggil SQLDescribeParam untuk menjelaskan parameter tersebut dan SQLBindParameter untuk mengikatnya. Terakhir, ini meminta pengguna untuk nilai parameter apa pun dan kemudian menjalankan pernyataan.
SQLCHAR Statement[100];
SQLSMALLINT NumParams, i, DataType, DecimalDigits, Nullable;
SQLUINTEGER ParamSize;
SQLHSTMT hstmt;
// Prompt the user for a SQL statement and prepare it.
GetSQLStatement(Statement);
SQLPrepare(hstmt, Statement, SQL_NTS);
// Check to see if there are any parameters. If so, process them.
SQLNumParams(hstmt, &NumParams);
if (NumParams) {
// Allocate memory for three arrays. The first holds pointers to buffers in which
// each parameter value will be stored in character form. The second contains the
// length of each buffer. The third contains the length/indicator value for each
// parameter.
SQLPOINTER * PtrArray = (SQLPOINTER *) malloc(NumParams * sizeof(SQLPOINTER));
SQLINTEGER * BufferLenArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
SQLINTEGER * LenOrIndArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
for (i = 0; i < NumParams; i++) {
// Describe the parameter.
SQLDescribeParam(hstmt, i + 1, &DataType, &ParamSize, &DecimalDigits, &Nullable);
// Call a helper function to allocate a buffer in which to store the parameter
// value in character form. The function determines the size of the buffer from
// the SQL data type and parameter size returned by SQLDescribeParam and returns
// a pointer to the buffer and the length of the buffer.
AllocParamBuffer(DataType, ParamSize, &PtrArray[i], &BufferLenArray[i]);
// Bind the memory to the parameter. Assume that we only have input parameters.
SQLBindParameter(hstmt, i + 1, SQL_PARAM_INPUT, SQL_C_CHAR, DataType, ParamSize,
DecimalDigits, PtrArray[i], BufferLenArray[i],
&LenOrIndArray[i]);
// Prompt the user for the value of the parameter and store it in the memory
// allocated earlier. For simplicity, this function does not check the value
// against the information returned by SQLDescribeParam. Instead, the driver does
// this when the statement is executed.
GetParamValue(PtrArray[i], BufferLenArray[i], &LenOrIndArray[i]);
}
}
// Execute the statement.
SQLExecute(hstmt);
// Process the statement further, such as retrieving results (if any) and closing the
// cursor (if any). Code not shown.
// Free the memory allocated for each parameter and the memory allocated for the arrays
// of pointers, buffer lengths, and length/indicator values.
for (i = 0; i < NumParams; i++) free(PtrArray[i]);
free(PtrArray);
free(BufferLenArray);
free(LenOrIndArray);
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengikat buffer ke parameter | Fungsi SQLBindParameter |
| Membatalkan pemrosesan pernyataan | Fungsi SQLCancel |
| Menjalankan pernyataan SQL yang disiapkan | Fungsi SQLExecute |
| Menyiapkan pernyataan untuk eksekusi | Fungsi SQLPrepare |