SQLDescribeParam-Funktion
Konformität
Version eingeführt: ODBC 1.0-Standardkonformität: ODBC
Zusammenfassung
SQLDescribeParam gibt die Beschreibung eines Parametermarkers zurück, der einer vorbereiteten SQL-Anweisung zugeordnet ist. Diese Informationen sind auch in den Feldern des 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 Parametermarkernummer wird sequenziell in steigender 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 Feld SQL_DESC_CONCISE_TYPE Datensatz der IPD gelesen. Dies ist einer der Werte im Abschnitt SQL-Datentypen des Anhangs D: Datentypen oder ein treiberspezifischer 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 zurückgegeben; in ODBC 2. x, SQL_DATE, SQL_TIME oder SQL_TIMESTAMP werden zurückgegeben. Der Treiber-Manager führt die erforderlichen Zuordnungen aus, wenn odbc 2. Die x-Anwendung arbeitet mit odbc 3. x-Treiber oder wenn odbc 3. Die x-Anwendung arbeitet mit odbc 2. x-Treiber .
Wenn ColumnNumber gleich 0 ist (für eine Lesezeichenspalte), wird SQL_BINARY in *DataTypePtr für Lesezeichen variabler Länge zurückgegeben. (SQL_INTEGER wird zurückgegeben, wenn Lesezeichen von odbc 3 verwendet werden. x-Anwendung , die mit odbc 2 arbeitet. x-Treiber oder von ODBC 2. x-Anwendung , die mit 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 Treiberdokumentation.
ParameterSizePtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Größe der Spalte oder des Ausdrucks des entsprechenden Parametermarkers in Zeichen zurückgegeben werden soll, wie von der Datenquelle definiert. Weitere Informationen zur Spaltengröße finden Sie unter Spaltengröße, Dezimalstellen, Oktettlänge übertragen und Anzeigegröße.
DecimalDigitsPtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Anzahl der Dezimalstellen der Spalte oder des Ausdrucks des entsprechenden Parameters zurückgegeben werden soll, wie von der Datenquelle definiert. Weitere Informationen zu Dezimalstellen finden Sie unter Spaltengröße, Dezimalstellen, 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 Feld SQL_DESC_NULLABLE 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 bestimmen, 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.
Diagnose
Wenn SQLDescribeParam SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle von StatementHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die in der Regel von SQLDescribeParam zurückgegeben werden, und die einzelnen Werte werden 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 | Fehler | BESCHREIBUNG |
|---|---|---|
| 01000 | Allgemeine Warnung | 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. Der Parametermarker war Teil einer Nicht-DML-Anweisung. Der Parametermarker 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 | Insert value list does not match column list | Die Anzahl der Parameter in der INSERT-Anweisung stimmte nicht mit der Anzahl der Spalten in der Tabelle überein, 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 seine Ursache. |
| HY001 | Fehler bei der Speicherbelegung | 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 vor Abschluss der Ausführung wurde SQLCancel oder SQLCancelHandle für statementHandle aufgerufen. Anschließend wurde die Funktion für die AnweisungHandle erneut aufgerufen. Die Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen wurde, wurde SQLCancel oder SQLCancelHandle für die StatementHandle aus einem anderen Thread in einer Multithreadanwendung aufgerufen. |
| HY010 | Funktionssequenzfehler | (DM) Die Funktion wurde aufgerufen, bevor SQLPrepare oder SQLExecDirect für statementHandle aufgerufen wurde. (DM) Eine asynchron ausgeführte Funktion wurde für das Verbindungshandle aufgerufen, das dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als die FUNKTION SQLDescribeParam 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 der Ausführungsparameter oder -spalten gesendet wurden. |
| HY013 | Fehler bei der Speicherverwaltung | Der Funktionsaufruf konnte nicht verarbeitet werden, weil auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von geringen Arbeitsspeicherbedingungen. |
| HY117 | Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur trenn- und schreibgeschützte Funktionen sind zulässig. | (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran-Funktion. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Treiber unterstützt diese Funktion nicht. | (DM) Der Der StatementHandle zugeordnete Treiber unterstützt die Funktion nicht. |
| IM017 | Abruf ist im asynchronen Benachrichtigungsmodus deaktiviert. | Wenn das Benachrichtigungsmodell verwendet wird, wird die Abfrage 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 Nachverarbeitung durchzuführen und den Vorgang abzuschließen. |
Kommentare
Parametermarker 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. Mit Ausnahme von 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 zur Eingabe einer SQL-Anweisung aufgefordert und anschließend diese Anweisung vorbereitet. Als Nächstes wird SQLNumParams aufgerufen, um zu bestimmen, ob die Anweisung Parameter enthält. Wenn die -Anweisung Parameter enthält, ruft sie SQLDescribeParam auf, um diese Parameter zu beschreiben, und SQLBindParameter , 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 an 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
| Informationen über | Finden Sie unter |
|---|---|
| Binden eines Puffers an einen Parameter | SQLBindParameter-Funktion |
| Abbrechen der Anweisungsverarbeitung | SQLCancel-Funktion |
| Ausführen einer vorbereiteten SQL-Anweisung | SQLExecute-Funktion |
| Vorbereiten einer Anweisung für die Ausführung | SQLPrepare-Funktion |