Bagikan melalui


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);  
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

Lihat Juga

Referensi API ODBC
File Header ODBC