Fonction SQLDescribeParam

Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ODBC

Résumé
SQLDescribeParam retourne la description d’un marqueur de paramètre associé à une instruction SQL préparée. Ces informations sont également disponibles dans les champs de l’IPD.

Syntaxe

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

Arguments

StatementHandle
[Entrée] Handle d’instruction.

ParameterNumber
[Entrée] Numéro de marqueur de paramètre ordonné séquentiellement dans l’ordre croissant des paramètres, à partir de 1.

DataTypePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le type de données SQL du paramètre. Cette valeur est lue à partir du champ d’enregistrement SQL_DESC_CONCISE_TYPE de l’IPD. Il s’agit de l’une des valeurs de la section Types de données SQL de l’Annexe D : Types de données ou type de données SQL spécifique au pilote.

Dans ODBC 3.x, SQL_TYPE_DATE, SQL_TYPE_TIME ou SQL_TYPE_TIMESTAMP sont retournés dans *DataTypePtr pour les données de date, d’heure ou d’horodatage, respectivement ; dans ODBC 2.x, SQL_DATE, SQL_TIME ou SQL_TIMESTAMP seront retournés. Le Gestionnaire de pilotes effectue les mappages requis lorsqu’un ODBC 2.x application fonctionne avec ODBC 3.pilote x ou lorsqu’un ODBC 3.x application fonctionne avec ODBC 2.pilote x .

Lorsque ColumnNumber est égal à 0 (pour une colonne de signet), SQL_BINARY est retourné dans *DataTypePtr pour les signets de longueur variable. (SQL_INTEGER est retournée si les signets sont utilisés par un ODBC 3.x application fonctionnant avec ODBC 2.x driver or by an ODBC 2.x application fonctionnant avec ODBC 3.x driver.)

Pour plus d’informations, consultez Les types de données SQL dans l’annexe D : Types de données. Pour plus d’informations sur les types de données SQL spécifiques au pilote, consultez la documentation du pilote.

ParameterSizePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la taille, en caractères, de la colonne ou de l’expression du marqueur de paramètre correspondant tel que défini par la source de données. Pour plus d’informations sur la taille de colonne, consultez Taille de colonne, Chiffres décimaux, Longueur des octets de transfert et Taille d’affichage.

DecimalDigitsPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nombre de chiffres décimaux de la colonne ou de l’expression du paramètre correspondant tel que défini par la source de données. Pour plus d’informations sur les chiffres décimaux, consultez La taille des colonnes, les chiffres décimaux, la longueur des octets de transfert et la taille d’affichage.

NullablePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner une valeur qui indique si le paramètre autorise les valeurs NULL. Cette valeur est lue à partir du champ SQL_DESC_NULLABLE de l’IPD. Celui-ci peut avoir l'une des valeurs suivantes :

• SQL_NO_NULLS : le paramètre n’autorise pas les valeurs NULL (il s’agit de la valeur par défaut).

• SQL_NULLABLE : le paramètre autorise les valeurs NULL.

• SQL_NULLABLE_UNKNOWN : le pilote ne peut pas déterminer si le paramètre autorise les valeurs NULL.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLDescribeParam retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_STMT et un Handle of StatementHandle. Le tableau suivant répertorie les valeurs SQLSTATE généralement retournées par SQLDescribeParam et explique chacune d’elles dans le contexte de cette fonction ; la notation « (DM) » précède les descriptions de SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

Commentaires

Les marqueurs de paramètres sont numérotés dans l’ordre croissant des paramètres, à compter de 1, dans l’ordre dans lequel ils apparaissent dans l’instruction SQL.

SQLDescribeParam ne retourne pas le type (entrée, entrée/sortie ou sortie) d’un paramètre dans une instruction SQL. À l’exception des appels aux procédures, tous les paramètres des instructions SQL sont des paramètres d’entrée. Pour déterminer le type de chaque paramètre dans un appel à une procédure, une application appelle SQLProcedureColumns.

Pour plus d’informations, consultez Description des paramètres.

Exemple de code

L’exemple suivant invite l’utilisateur à entrer une instruction SQL, puis prépare cette instruction. Ensuite, il appelle SQLNumParams pour déterminer si l’instruction contient des paramètres. Si l’instruction contient des paramètres, elle appelle SQLDescribeParam pour décrire ces paramètres et SQLBindParameter pour les lier. Enfin, il invite l’utilisateur à entrer les valeurs de tous les paramètres, puis exécute l’instruction.

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

Fonctions connexes

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC