Partage via

Utilisation de tableaux de paramètres

  • Article

Pour utiliser des tableaux de paramètres, l’application appelle SQLSetStmtAttr avec un argument Attribute de SQL_ATTR_PARAMSET_SIZE pour spécifier le nombre de jeux de paramètres. Il appelle SQLSetStmtAttr avec un argument Attribute de SQL_ATTR_PARAMS_PROCESSED_PTR pour spécifier l’adresse d’une variable dans laquelle le pilote peut retourner le nombre de jeux de paramètres traités, y compris les jeux d’erreurs. Il appelle SQLSetStmtAttr avec un argument Attribute de SQL_ATTR_PARAM_STATUS_PTR pour pointer vers un tableau dans lequel retourner des informations d’état pour chaque ligne de valeurs de paramètre. Le pilote stocke ces adresses dans la structure qu’il gère pour l’instruction.

Remarque

Dans ODBC 2.x, SQLParamOptions a été appelé pour spécifier plusieurs valeurs pour un paramètre. Dans ODBC 3.x, l’appel à SQLParamOptions a été remplacé par des appels à SQLSetStmtAttr pour définir les attributs SQL_ATTR_PARAMSET_SIZE et SQL_ATTR_PARAMS_PROCESSED_ARRAY.

Avant d’exécuter l’instruction, l’application définit la valeur de chaque élément de chaque tableau lié. Lorsque l’instruction est exécutée, le pilote utilise les informations qu’il a stockées pour récupérer les valeurs des paramètres et les envoyer à la source de données ; si possible, le pilote doit envoyer ces valeurs sous forme de tableaux. Bien que l’utilisation de tableaux de paramètres soit mieux implémentée en exécutant l’instruction SQL avec tous les paramètres du tableau avec un seul appel à la source de données, cette fonctionnalité n’est pas largement disponible dans les SGBD aujourd’hui. Toutefois, les pilotes peuvent le simuler en exécutant une instruction SQL plusieurs fois, chacune avec un seul ensemble de paramètres.

Avant qu’une application utilise des tableaux de paramètres, il doit être sûr qu’elles sont prises en charge par les pilotes utilisés par l’application. Il existe deux façons d'effectuer cette opération :

  • Utilisez uniquement les pilotes connus pour prendre en charge les tableaux de paramètres. L’application peut coder en dur les noms de ces pilotes, ou l’utilisateur peut être invité à utiliser uniquement ces pilotes. Les applications personnalisées et les applications verticales utilisent généralement un ensemble limité de pilotes.

  • Vérifiez la prise en charge des tableaux de paramètres au moment de l’exécution. Un pilote prend en charge les tableaux de paramètres s’il est possible de définir l’attribut d’instruction SQL_ATTR_PARAMSET_SIZE sur une valeur supérieure à 1. Les applications génériques et les applications verticales vérifient généralement la prise en charge des tableaux de paramètres au moment de l’exécution.

La disponibilité des nombres de lignes et des jeux de résultats dans l’exécution paramétrable peut être déterminée en appelant SQLGetInfo avec les options SQL_PARAM_ARRAY_ROW_COUNTS et SQL_PARAM_ARRAY_SELECTS. Pour les instructions INSERT, UPDATE et DELETE , l’option SQL_PARAM_ARRAY_ROW_COUNTS indique si les nombres de lignes individuels (un pour chaque jeu de paramètres) sont disponibles (SQL_PARC_BATCH) ou si les nombres de lignes sont regroupés en un (SQL_PARC_NO_BATCH). Pour les instructions SELECT , l’option SQL_PARAM_ARRAY_SELECTS indique si un jeu de résultats est disponible pour chaque jeu de paramètres (SQL_PAS_BATCH) ou si un seul jeu de résultats est disponible (SQL_PAS_NO_BATCH). Si le pilote n’autorise pas l’exécution d’instructions de génération de jeux de résultats avec un tableau de paramètres, SQL_PARAM_ARRAY_SELECTS retourne SQL_PAS_NO_SELECT. Il est spécifique à la source de données si des tableaux de paramètres peuvent être utilisés avec d’autres types d’instructions, en particulier parce que l’utilisation de paramètres dans ces instructions serait spécifique à la source de données et ne suivreait pas la grammaire ODBC SQL.

Le tableau pointé par l’attribut d’instruction SQL_ATTR_PARAM_OPERATION_PTR peut être utilisé pour ignorer les lignes de paramètres. Si un élément du tableau est défini sur SQL_PARAM_IGNORE, l’ensemble de paramètres correspondant à cet élément est exclu de l’appel SQLExecute ou SQLExecDirect . Le tableau pointé par l’attribut SQL_ATTR_PARAM_OPERATION_PTR est alloué et renseigné par l’application et lu par le pilote. Si les lignes extraites sont utilisées comme paramètres d’entrée, les valeurs du tableau d’état de ligne peuvent être utilisées dans le tableau d’opérations de paramètre.

Erreur lors du traitement

Si une erreur se produit lors de l’exécution de l’instruction, la fonction d’exécution retourne une erreur et définit la variable numéro de ligne sur le nombre de lignes contenant l’erreur. Il s’agit d’une source de données spécifique si toutes les lignes sauf le jeu d’erreurs sont exécutées ou si toutes les lignes avant (mais pas après) le jeu d’erreurs sont exécutés. Étant donné qu’il traite des ensembles de paramètres, le pilote définit la mémoire tampon spécifiée par l’attribut d’instruction SQL_ATTR_PARAMS_PROCESSED_PTR sur le nombre de lignes en cours de traitement. Si tous les jeux à l’exception du jeu d’erreurs sont exécutés, le pilote définit cette mémoire tampon sur SQL_ATTR_PARAMSET_SIZE après le traitement de toutes les lignes.

Si l’attribut d’instruction SQL_ATTR_PARAM_STATUS_PTR a été défini, SQLExecute ou SQLExecDirect retourne le tableau d’état des paramètres, qui fournit l’état de chaque jeu de paramètres. Le tableau d’état des paramètres est alloué par l’application et renseigné par le pilote. Ses éléments indiquent si l’instruction SQL a été exécutée correctement pour la ligne de paramètres ou si une erreur s’est produite lors du traitement de l’ensemble de paramètres. Si une erreur s’est produite, le pilote définit la valeur correspondante dans le tableau d’état des paramètres sur SQL_PARAM_ERROR et retourne SQL_SUCCESS_WITH_INFO. L’application peut vérifier le tableau d’état pour déterminer les lignes qui ont été traitées. À l’aide du numéro de ligne, l’application peut souvent corriger l’erreur et reprendre le traitement.

La façon dont le tableau d’état des paramètres est utilisé est déterminée par les options SQL_PARAM_ARRAY_ROW_COUNTS et SQL_PARAM_ARRAY_SELECTS retournées par un appel à SQLGetInfo. Pour les instructions INSERT, UPDATE et DELETE , le tableau d’état des paramètres est rempli avec des informations d’état si SQL_PARC_BATCH est retourné pour SQL_PARAM_ARRAY_ROW_COUNTS, mais pas si SQL_PARC_NO_BATCH est retourné. Pour les instructions SELECT , le tableau d’état des paramètres est renseigné si SQL_PAS_BATCH est retourné pour SQL_PARAM_ARRAY_SELECT, mais pas si SQL_PAS_NO_BATCH ou SQL_PAS_NO_SELECT est retourné.

Paramètres de données au niveau de l’exécution

Si l’une des valeurs du tableau de longueur/indicateur est SQL_DATA_AT_EXEC ou si le résultat de la macro SQL_LEN_DATA_AT_EXEC(length), les données de ces valeurs sont envoyées avec SQLPutData de la manière habituelle. Les aspects suivants de ce processus portent un commentaire spécial, car ils ne sont pas facilement évidents :

  • Lorsque le pilote retourne SQL_NEED_DATA, il doit définir l’adresse de la variable numéro de ligne sur la ligne pour laquelle il a besoin de données. Comme dans le cas à valeur unique, l’application ne peut pas effectuer d’hypothèses sur l’ordre dans lequel le pilote demande des valeurs de paramètre dans un seul ensemble de paramètres. Si une erreur se produit dans l’exécution d’un paramètre de données au niveau de l’exécution, la mémoire tampon spécifiée par l’attribut d’instruction SQL_ATTR_PARAMS_PROCESSED_PTR est définie sur le nombre de lignes sur laquelle l’erreur s’est produite, l’état de la ligne dans le tableau d’état de ligne spécifié par l’attribut d’instruction SQL_ATTR_PARAM_STATUS_PTR est défini sur SQL_PARAM_ERROR, et l’appel à SQLExecute, SQLExecDirect, SQLParamData ou SQLPutData retourne SQL_ERROR. Le contenu de cette mémoire tampon n’est pas défini si SQLExecute, SQLExecDirect ou SQLParamData retourne SQL_STILL_EXECUTING.

  • Étant donné que le pilote n’interprète pas la valeur dans l’argument ParameterValuePtr de SQLBindParameter pour les paramètres de données au niveau de l’exécution, si l’application fournit un pointeur vers un tableau, SQLParamData n’extrait pas et retourne un élément de ce tableau à l’application. Au lieu de cela, elle retourne la valeur scalaire fournie par l’application. Cela signifie que la valeur retournée par SQLParamData n’est pas suffisante pour spécifier le paramètre pour lequel l’application doit envoyer des données ; l’application doit également prendre en compte le numéro de ligne actuel.

    Lorsque seuls certains éléments d’un tableau de paramètres sont des paramètres de données au niveau de l’exécution, l’application doit transmettre l’adresse d’un tableau dans ParameterValuePtr qui contient des éléments pour tous les paramètres. Ce tableau est interprété normalement pour les paramètres qui ne sont pas des paramètres de données au niveau de l’exécution. Pour les paramètres de données au niveau de l’exécution, la valeur que SQLParamData fournit à l’application, qui peut normalement être utilisée pour identifier les données demandées par le pilote à cette occasion, est toujours l’adresse du tableau.