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.

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

ODBC-API-Referenz
ODBC-Headerdateien