SQLDescribeParam-Funktion
Konformität
Version eingeführt: ODBC 1.0-Standardscompliance: ODBC
Zusammenfassung
SQLDescribeParam gibt die Beschreibung einer Parametermarkierung zurück, die einer vorbereiteten SQL-Anweisung zugeordnet ist. Diese Informationen sind auch in den Feldern der IPD verfügbar.
Syntax
SQLRETURN SQLDescribeParam(
SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT * DataTypePtr,
SQLULEN * ParameterSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
Argumente
StatementHandle
[Eingabe] Anweisungshandle.
ParameterNumber
[Eingabe] Die Nummer der Parametermarkierung wird sequenziell in erhöhter Parameterreihenfolge sortiert, beginnend bei 1.
DataTypePtr
[Ausgabe] Zeiger auf einen Puffer, in dem der SQL-Datentyp des Parameters zurückgegeben werden soll. Dieser Wert wird aus dem SQL_DESC_CONCISE_TYPE Datensatzfeld der IPD gelesen. Hierbei handelt es sich um einen der Werte im Abschnitt "SQL-Datentypen " in Anhang D: Datentypen oder einen treiberspezifischen SQL-Datentyp.
In ODBC 3.x, SQL_TYPE_DATE, SQL_TYPE_TIME oder SQL_TYPE_TIMESTAMP werden in *DataTypePtr für Datums-, Uhrzeit- oder Zeitstempeldaten bzw. in ODBC 2 zurückgegeben.x, SQL_DATE, SQL_TIME oder SQL_TIMESTAMP werden zurückgegeben. Der Treiber-Manager führt die erforderlichen Zuordnungen aus, wenn ein ODBC 2 verwendet wird.x-Anwendung arbeitet mit einem ODBC 3.x-Treiber oder ein ODBC 3-Treiber.x-Anwendung arbeitet mit einem ODBC 2.x-Treiber .
Wenn ColumnNumber gleich 0 (für eine Textmarkespalte) ist, wird SQL_BINARY in *DataTypePtr für Textmarken mit variabler Länge zurückgegeben. (SQL_INTEGER wird zurückgegeben, wenn Lesezeichen von einem ODBC 3 verwendet werden.x-Anwendung , die mit einem ODBC 2 arbeitet.x-Treiber oder odbc 2.x-Anwendung , die mit einem ODBC 3 arbeitet.x-Treiber .)
Weitere Informationen finden Sie unter SQL-Datentypen in Anhang D: Datentypen. Informationen zu treiberspezifischen SQL-Datentypen finden Sie in der Dokumentation des Treibers.
ParameterSizePtr
[Ausgabe] Zeigen Sie auf einen Puffer, in dem die Größe der Spalte oder des Ausdrucks der entsprechenden Parametermarkierung in Zeichen zurückgegeben werden soll, wie von der Datenquelle definiert. Weitere Informationen zur Spaltengröße finden Sie unter "Spaltengröße", "Dezimalziffern", "Oktettlänge übertragen" und "Anzeigegröße".
DecimalDigitsPtr
[Ausgabe] Zeigen Sie auf einen Puffer, in dem die Anzahl der Dezimalziffern der Spalte oder des Ausdrucks des entsprechenden Parameters zurückgegeben werden soll, wie von der Datenquelle definiert. Weitere Informationen zu Dezimalziffern finden Sie unter "Spaltengröße", "Dezimalziffern", "Oktettlänge übertragen" und "Anzeigegröße".
NullablePtr
[Ausgabe] Zeiger auf einen Puffer, in dem ein Wert zurückgegeben werden soll, der angibt, ob der Parameter NULL-Werte zulässt. Dieser Wert wird aus dem SQL_DESC_NULLABLE Feld der IPD gelesen. Einer der folgenden:
SQL_NO_NULLS: Der Parameter lässt keine NULL-Werte zu (dies ist der Standardwert).
SQL_NULLABLE: Der Parameter lässt NULL-Werte zu.
SQL_NULLABLE_UNKNOWN: Der Treiber kann nicht ermitteln, ob der Parameter NULL-Werte zulässt.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.
Diagnostik
Wenn SQLDescribeParam SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle abgerufen werden. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die in der Regel von SQLDescribeParam zurückgegeben werden, und jede wird im Kontext dieser Funktion erläutert. Die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.
| SQLSTATE | Error | Beschreibung |
|---|---|---|
| 01000 | Allgemeiner Warnhinweis | Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 07009 | Ungültiger Deskriptorindex | (DM) Der für das Argument ParameterNumber angegebene Wert ist kleiner als 1. Der für das Argument ParameterNumber angegebene Wert war größer als die Anzahl der Parameter in der zugeordneten SQL-Anweisung. Die Parametermarkierung war Teil einer Nicht-DML-Anweisung. Die Parametermarkierung war Teil einer SELECT-Liste . |
| 08S01 | Kommunikationslinkfehler | Die Kommunikationsverbindung zwischen dem Treiber und der Datenquelle, mit der der Treiber verbunden wurde, ist fehlgeschlagen, bevor die Verarbeitung der Funktion abgeschlossen wurde. |
| 21S01 | Die Liste einzufügender Werte passt nicht zur Spaltenliste. | Die Anzahl der Parameter in der INSERT-Anweisung entspricht nicht der Anzahl der Spalten in der Tabelle, die in der Anweisung benannt ist. |
| HY000 | Allgemeiner Fehler | Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und dessen Ursache. |
| HY001 | Speicherzuweisungsfehler | Der Treiber konnte arbeitsspeicher nicht zuordnen, der zur Unterstützung der Ausführung oder Fertigstellung der Funktion erforderlich ist. |
| HY008 | Vorgang abgebrochen | Die asynchrone Verarbeitung wurde für " StatementHandle" aktiviert. Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für die Anweisungshandle aufgerufen. Anschließend wurde die Funktion erneut für " StatementHandle" aufgerufen. Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für das StatementHandle von einem anderen Thread in einer Multithreadanwendung aufgerufen. |
| HY010 | Funktionssequenzfehler | (DM) Die Funktion wurde vor dem Aufrufen von SQLPrepare oder SQLExecDirect für das StatementHandle aufgerufen. (DM) Eine asynchron ausgeführte Funktion wurde für den Verbindungshandle aufgerufen, der dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als die SQLDescribeParam-Funktion aufgerufen wurde. (DM) Eine asynchron ausgeführte Funktion (nicht diese) wurde für das StatementHandle aufgerufen und wurde noch ausgeführt, als diese Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für " StatementHandle " aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei ausführungsparametern oder -spalten gesendet wurden. |
| HY013 | Speicherverwaltungsfehler | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund geringer Arbeitsspeicherbedingungen. |
| HY117 | Die Verbindung wird aufgrund des unbekannten Transaktionsstatus angehalten. Es sind nur Trenn- und schreibgeschützte Funktionen zulässig. | (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran Function. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT festgelegt. |
| IM001 | Dieser Treiber unterstützt diese Funktion nicht. | (DM) Der dem StatementHandle zugeordnete Treiber unterstützt die Funktion nicht. |
| IM017 | Die Abrufung ist im asynchronen Benachrichtigungsmodus deaktiviert. | Immer wenn das Benachrichtigungsmodell verwendet wird, ist die Abrufung deaktiviert. |
| IM018 | SQLCompleteAsync wurde nicht aufgerufen, um den vorherigen asynchronen Vorgang für dieses Handle abzuschließen. | Wenn der vorherige Funktionsaufruf für das Handle SQL_STILL_EXECUTING zurückgibt und der Benachrichtigungsmodus aktiviert ist, muss SQLCompleteAsync für das Handle aufgerufen werden, um die Nachbearbeitung durchzuführen und den Vorgang abzuschließen. |
Kommentare
Parametermarkierungen werden in zunehmender Parameterreihenfolge nummeriert, beginnend mit 1, in der Reihenfolge, in der sie in der SQL-Anweisung angezeigt werden.
SQLDescribeParam gibt nicht den Typ (Eingabe, Eingabe/Ausgabe oder Ausgabe) eines Parameters in einer SQL-Anweisung zurück. Außer bei Aufrufen von Prozeduren sind alle Parameter in SQL-Anweisungen Eingabeparameter. Um den Typ der einzelnen Parameter in einem Aufruf einer Prozedur zu bestimmen, ruft eine Anwendung SQLProcedureColumns auf.
Weitere Informationen finden Sie unter "Beschreiben von Parametern".
Codebeispiel
Im folgenden Beispiel wird der Benutzer aufgefordert, eine SQL-Anweisung einzufordern und diese Anweisung vorzubereiten. Als Nächstes ruft sie SQLNumParams auf, um zu bestimmen, ob die Anweisung Parameter enthält. Wenn die Anweisung Parameter enthält, ruft sie SQLDescribeParam auf, um diese Parameter und SQLBindParameter zu beschreiben, um sie zu binden. Schließlich fordert er den Benutzer zur Eingabe der Werte aller Parameter auf und führt dann die Anweisung aus.
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);
Verwandte Funktionen
| Weitere Informationen zu | Siehe |
|---|---|
| Binden eines Puffers an einen Parameter | SQLBindParameter-Funktion |
| Abbrechen der Verarbeitung von Anweisungen | SQLCancel-Funktion |
| Ausführen einer vorbereiteten SQL-Anweisung | SQLExecute-Funktion |
| Vorbereiten einer Anweisung für die Ausführung | SQLPrepare-Funktion |