SQLDescribeParam-functie

Conformiteit
Versie geïntroduceerd: ODBC 1.0 Standaardnaleving: ODBC

Samenvatting
SQLDescribeParam geeft de beschrijving terug van een parametermarker die is gekoppeld aan een voorbereide SQL-instructie. Deze informatie is ook beschikbaar in de velden van de IPD.

Syntax

  
SQLRETURN SQLDescribeParam(  
      SQLHSTMT        StatementHandle,  
      SQLUSMALLINT    ParameterNumber,  
      SQLSMALLINT *   DataTypePtr,  
      SQLULEN *       ParameterSizePtr,  
      SQLSMALLINT *   DecimalDigitsPtr,  
      SQLSMALLINT *   NullablePtr);  

Arguments

StatementHandle
[Invoer] Instructiehandgreep.

ParameterNumber
[Invoer] Parametermarkernummer opeenvolgend gerangschikt in toenemende parametervolgorde, beginnend bij 1.

DataTypePtr
[Output] Wijs naar een buffer waarin het SQL-datatype van de parameter wordt teruggegeven. Deze waarde wordt gelezen uit het SQL_DESC_CONCISE_TYPE recordveld van de IPD. Dit zal een van de waarden zijn in de sectie SQL Data Types van Appendix D: Data Types, of een driver-specifiek SQL-datatype.

In ODBC 3. x, SQL_TYPE_DATE, SQL_TYPE_TIME of SQL_TYPE_TIMESTAMP worden respectievelijk teruggegeven in *DataTypePtr voor datum-, tijd- of tijdstempelgegevens; in ODBC 2. X, SQL_DATE, SQL_TIME of SQL_TIMESTAMP worden teruggegeven. De Driver Manager voert de vereiste mappings uit wanneer een ODBC 2 is. x applicatie werkt met een ODBC 3. x driver of wanneer een ODBC 3. x-applicatie werkt met een ODBC 2. X-bestuurder .

Wanneer ColumnNumber gelijk is aan 0 (voor een bladwijzerkolom), wordt SQL_BINARY teruggegeven in *DataTypePtr voor bladwijzers van variabele lengte. (SQL_INTEGER wordt teruggegeven als bladwijzers worden gebruikt door een ODBC 3. x applicatie die werkt met een ODBC 2. x driver of door een ODBC 2. x applicatie die werkt met een ODBC 3. X-bestuurder .)

Voor meer informatie, zie SQL Data Types in Appendix D: Data Types. Zie de documentatie van het stuurprogramma voor informatie over stuurprogrammaspecifieke SQL-gegevenstypen.

ParameterSizePtr
[Output] Wijs naar een buffer waarin de grootte, in tekens, van de kolom of expressie van de overeenkomstige parametermarker zoals gedefinieerd door de databron wordt teruggegeven. Voor meer informatie over kolomgrootte, zie Kolomgrootte, Decimale cijfers, Overdracht van de octelengte en Weergavegrootte.

DecimalDigitsPtr
[Output] Richt op een buffer waarin het aantal decimale cijfers van de kolom of uitdrukking van de overeenkomstige parameter wordt teruggegeven zoals gedefinieerd door de databron. Voor meer informatie over decimale cijfers, zie Kolomgrootte, Decimale cijfers, Transfer Octet Length en Display Size.

NullablePtr
[Output] Wijs naar een buffer waarin een waarde wordt teruggegeven die aangeeft of de parameter NULL-waarden toestaat. Deze waarde wordt gelezen uit het SQL_DESC_NULLABLE veld van de IPD. Een van de volgende:

• SQL_NO_NULLS: De parameter staat geen NULL-waarden toe (dit is de standaardwaarde).

• SQL_NULLABLE: De parameter staat NULL-waarden toe.

• SQL_NULLABLE_UNKNOWN: De driver kan niet bepalen of de parameter NULL-waarden toestaat.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR of SQL_INVALID_HANDLE.

Diagnostics

Wanneer SQLDescribeParam SQL_ERROR of SQL_SUCCESS_WITH_INFO teruggeeft, kan een bijbehorende SQLSTATE-waarde worden verkregen door SQLGetDiagRec aan te roepen met een HandleType van SQL_HANDLE_STMT en een Handle van StatementHandle. De volgende tabel geeft een overzicht van de SQLSTATE-waarden die typisch door SQLDescribeParam worden geretourneerd en legt elk uit in de context van deze functie; de notatie "(DM)" gaat vooraf aan de beschrijvingen van SQLSTATES die door de Driver Manager worden teruggegeven. De retourcode die is gekoppeld aan elke SQLSTATE-waarde is SQL_ERROR, tenzij anders vermeld.

Comments

Parametermarkers worden genummerd in toenemende parametervolgorde, beginnend met 1, in de volgorde waarin ze in de SQL-instructie voorkomen.

SQLDescribeParam geeft het type (input, input/output of output) van een parameter in een SQL-instructie niet terug. Behalve bij aanroepen van procedures zijn alle parameters in SQL-statements invoerparameters. Om het type van elke parameter in een aanroep van een procedure te bepalen, roept een applicatie SQLProcedureColumns aan.

Voor meer informatie, zie Parameters beschrijven.

Codevoorbeeld

Het volgende voorbeeld vraagt de gebruiker om een SQL-instructie en bereidt die vervolgens voor. Vervolgens roept het SQLNumParams aan om te bepalen of de instructie parameters bevat. Als de instructie parameters bevat, roept het SQLDescribeParam aan om die parameters te beschrijven en SQLBindParameter om ze te binden. Ten slotte vraagt het de gebruiker om de waarden van eventuele parameters en voert vervolgens de instructie uit.

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

Gerelateerde functies

Zie ook

ODBC-API-verwijzing
ODBC-headerbestanden