Fonction SQLDescribeParam

  • Article

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] Nombre de marqueurs de paramètre triés 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 d’un type de données SQL spécifique au pilote.

Dans ODBC 3. x, SQL_TYPE_DATE, SQL_TYPE_TIME ou SQL_TYPE_TIMESTAMP seront 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 sont retournés. Le Gestionnaire de pilotes effectue les mappages requis lorsqu’une instance ODBC 2. L’application x fonctionne avec odbc 3. pilote x ou quand odbc 3. L’application x fonctionne avec odbc 2. pilote x .

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

Pour plus d’informations, consultez 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 des colonnes, consultez Taille de colonne, Chiffres décimaux, Longueur d’octet 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 Taille de colonne, Chiffres décimaux, Longueur des octets de transfert et 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 de 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.

SQLSTATE Error Description
01000 Avertissement général Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
07009 Index de descripteur non valide (DM) La valeur spécifiée pour l’argument ParameterNumber est inférieure à 1.

La valeur spécifiée pour l’argument ParameterNumber était supérieure au nombre de paramètres dans l’instruction SQL associée.

Le marqueur de paramètre faisait partie d’une instruction non-DML.

Le marqueur de paramètre faisait partie d’une liste SELECT .
08S01 Échec de la liaison de communication Le lien de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant la fin du traitement de la fonction.
21S01 Insérer une liste de valeurs ne correspond pas à la liste de colonnes Le nombre de paramètres dans l’instruction INSERT ne correspondait pas au nombre de colonnes de la table nommée dans l’instruction .
HY000 Erreur générale Une erreur s’est produite pour laquelle il n’y avait pas de SQLSTATE spécifique et pour laquelle aucun SQLSTATE spécifique à l’implémentation n’a été défini. Le message d’erreur retourné par SQLGetDiagRec dans la mémoire tampon *MessageText décrit l’erreur et sa cause.
HY001 Erreur d’allocation de mémoire Le pilote n’a pas pu allouer la mémoire nécessaire pour prendre en charge l’exécution ou l’achèvement de la fonction.
HY008 Opération annulée Le traitement asynchrone a été activé pour l’InstructionHandle. La fonction a été appelée et, avant la fin de son exécution, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandle. Ensuite, la fonction a été appelée à nouveau sur l’InstructionHandle.

La fonction a été appelée et, avant la fin de son exécution, SQLCancel ou SQLCancelHandle a été appelé sur l’InstructionHandle à partir d’un thread différent dans une application multithread.
HY010 Erreur de séquence de fonction (DM) La fonction a été appelée avant d’appeler SQLPrepare ou SQLExecDirect pour l’InstructionHandle.

(DM) Une fonction en exécution asynchrone a été appelée pour le handle de connexion associé à l’InstructionHandle. Cette fonction asynchrone était toujours en cours d’exécution lorsque la fonction SQLDescribeParam a été appelée.

(DM) Une fonction en cours d’exécution asynchrone (et non celle-ci) a été appelée pour l’InstructionHandle et était toujours en cours d’exécution lorsque cette fonction a été appelée.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’InstructionHandle et a retourné SQL_NEED_DATA. Cette fonction a été appelée avant l’envoi des données pour toutes les colonnes ou paramètres de données au moment de l’exécution.
HY013 Erreur de gestion de la mémoire L’appel de fonction n’a pas pu être traité, car les objets de mémoire sous-jacents n’ont pas pu être accessibles, peut-être en raison de conditions de mémoire insuffisantes.
HY117 La connexion est suspendue en raison d’un état de transaction inconnu. Seules les fonctions de déconnexion et de lecture seule sont autorisées. (DM) Pour plus d’informations sur l’état suspendu, consultez Fonction SQLEndTran.
HYT01 Délai d’attente de la connexion expiré Le délai d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. Le délai d’expiration de connexion est défini via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Le pilote ne prend pas en charge cette fonction (DM) Le pilote associé à l’InstructionHandle ne prend pas en charge la fonction .
IM017 L’interrogation est désactivée en mode de notification asynchrone Chaque fois que le modèle de notification est utilisé, l’interrogation est désactivée.
IM018 SQLCompleteAsync n’a pas été appelé pour effectuer l’opération asynchrone précédente sur ce handle. Si l’appel de fonction précédent sur le handle retourne SQL_STILL_EXECUTING et si le mode de notification est activé, SQLCompleteAsync doit être appelé sur le handle pour effectuer le post-traitement et terminer l’opération.

Commentaires

Les marqueurs de paramètres sont numérotés dans l’ordre croissant des paramètres, en commençant par 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. Sauf dans les 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 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);
Pour obtenir des informations sur Consultez
Liaison d’une mémoire tampon à un paramètre Fonction SQLBindParameter
Annulation du traitement des instructions SQLCancel, fonction
Exécution d’une instruction SQL préparée SQLExecute, fonction
Préparation d’une instruction pour l’exécution Fonction SQLPrepare

Voir aussi

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