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.
| SQLSTATE | Erreur | 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 de 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 du lien de communication | Le lien de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant l’achèvement du traitement de la fonction. |
| 21S01 | La liste des valeurs d’insertion ne correspond pas à la liste de colonnes | Le nombre de paramètres de 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 aucun SQLSTATE spécifique et pour lequel 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 de 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 StatementHandle. La fonction a été appelée et avant l’exécution terminée, SQLCancel ou SQLCancelHandle a été appelée sur StatementHandle. Ensuite, la fonction a été appelée à nouveau sur l’instructionHandle. La fonction a été appelée et avant qu’elle ait terminé l’exécution, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandle à partir d’un autre thread 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 StatementHandle. (DM) Une fonction en cours d’exécution asynchrone a été appelée pour le handle de connexion associé à StatementHandle. 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’instruction StatementHandle 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 retourné SQL_NEED_DATA. Cette fonction a été appelée avant que les données ne soient envoyées pour tous les paramètres ou colonnes de données à 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, éventuellement 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 la fonction SQLEndTran. |
| HYT01 | Délai d’attente de la connexion expiré | La période d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. La période d’expiration de connexion est définie via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Le pilote ne prend pas en charge cette fonction | (DM) Le pilote associé à StatementHandle 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 terminer 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 un post-traitement et terminer l’opération. |
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
| Pour plus d’informations sur | Consultez |
|---|---|
| Liaison d’une mémoire tampon à un paramètre | SQLBindParameter, fonction |
| 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 | SQLPrepare, fonction |
Voir aussi
Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC