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] 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);
Fonctions connexes
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