balise PARAM
Crée un paramètre d'entrée pour un script d'outil d'analyse et définit les conditions requises pour la valeur d'introduction.
Un paramètre d'entrée est un espace réservé qui permet à l'utilisateur de spécifier la valeur réelle lors de la planification ou de l'exécution d'un script d'outil d'analyse.
Syntaxe
//PARAM nom_variabletype <OPTIONAL> <MULTI> <SEPARATOR valeur> <QUALIFIER valeur> <VALUES liste_valeurs> libellé <description>
Paramètres
| Nom | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| nom_variable |
Le nom de la variable qui stocke la ou les valeurs d'introduction sélectionnées ou spécifiées par l'utilisateur. Utilisez nom_variable dans le script de l'outil d'analyse pour faire référence à la valeur d'introduction. Par exemple :
Sert également d'identifiant unique du paramètre. Remarque Lorsqu'un script d'outil d'analyse est exécuté, la variable est créée uniquement si l'utilisateur fournit une valeur d'introduction. Si un paramètre est facultatif et que l'utilisateur l'ignore, la variable n'est pas créée. Si la logique ultérieure du script d'outil d'analyse requiert l'existence de la variable, vous pouvez tester la présence de son existence et si elle n'existe pas, la créer et l'initialiser. Pour plus d'informations, consultez la section Conception de paramètres d'entrée facultatifs. Caractères non pris en charge dans le paramètre nom_variableN'insérez aucune espace dans nom_variable. N'utilisez pas les caractères suivants dans nom_variable. Ils ne sont pas pris en charge : ` ~ ! @ # $ % ^ & * ( ) - + = { } [ ] | \ : ; ' " < > , . / ?
|
||||||||||||
| type |
Type de données du paramètre, qui contrôle le type de valeurs d'introduction pouvant être saisies. Les types suivants peuvent être spécifiés à l'aide de lettres en majuscules :
Remarque Pour qu'un script d'outil d'analyse s'exécute correctement, il est nécessaire de qualifier des valeurs d'introduction de caractère. |
||||||||||||
| OPTIONAL optionnel |
Indique que le paramètre est facultatif et qu'il n'est pas nécessaire que l'utilisateur entre une valeur. Pour plus d'informations, consultez la section Conception de paramètres d'entrée facultatifs. |
||||||||||||
| MULTI optionnel |
Indique que le paramètre accepte plusieurs valeurs d'introduction. Remarque MULTI ne peut pas être utilisé si le type est L (logique) ou F (fichier). MULTI et VALUES MULTI peut être utilisée avec ou sans l'option VALUES :
Pour plus d'informations, consultez la section Résumé des options MULTI et VALUES. Plusieurs valeurs d'introduction caractères Si vous spécifiez MULTI et que le type est C (Caractère), vous pouvez aussi spécifier les options SEPARATOR et QUALIFIER pour insérer automatiquement des séparateurs (délimiteurs) et des identificateurs de texte dans une chaîne de valeurs d'introduction. Remarque Pour qu'un script d'outil d'analyse s'exécute correctement, il est nécessaire de délimiter et de qualifier plusieurs valeurs d'introduction caractères. Les séparateurs et identificateurs peuvent être insérés automatiquement ou manuellement par l'utilisateur. |
||||||||||||
| SEPARATOR valeur optionnel |
SEPARATOR peut être uniquement utilisé lorsque MULTI est spécifié et que le type est C (caractère). Indique qu'un séparateur caractère est inséré automatiquement entre plusieurs valeurs d'introduction caractères, créant une liste délimitée transmise au script d'outil d'analyse pour son traitement. valeur spécifie le séparateur caractère à utiliser. Un séparateur, ou délimiteur, couramment utilisé est la virgule ,. Si SEPARATOR est omis, une seule espace est utilisée comme séparateur par défaut. Le caractère espace ne peut pas être spécifié comme valeur. Pour plus d'informations, consultez la section Délimitation et identification des valeurs d'introduction de caractères. |
||||||||||||
| QUALIFIER valeur optionnel |
QUALIFIER peut uniquement être utilisé lorsque MULTI est spécifié et que le type est C (caractère). Indique qu'un caractère identificateur de texte est inséré automatiquement au début et à la fin de chaque valeur d'introduction caractère dans une liste délimitée transmise au script d'outil d'analyse pour son traitement. Tout texte inclus dans les caractères d'identificateur de texte est traité comme du texte brut. La valeur spécifie le caractère d'identificateur à utiliser. Un identificateur fréquemment utilisé est le guillemet simple '. Si QUALIFIER est ignoré, aucun identificateur par défaut n'est utilisé. Le caractère espace ne peut pas être spécifié comme valeur. Pour plus d'informations, consultez la section Délimitation et identification des valeurs d'introduction de caractères. Remarque Les paramètres d'entrée des outils d'analyse ne prennent actuellement pas en charge l'utilisation du double guillemet (") comme identificateur de texte. À la place, vous pouvez utiliser le guillemet simple ('). Spécifier un identificateur guillemet double entraînera le dysfonctionnement de la balise PARAM. |
||||||||||||
| VALUES liste_valeurs optionnel |
Liste de valeurs dans laquelle l'utilisateur peut faire sa sélection lors de l'exécution du script d'outil d'analyse. Utilisez la syntaxe suivante pour spécifier les valeurs : VALUES |Valeur 1|Valeur 2|Valeur 3|Valeur n| VALUES et MULTI VALUES peut être utilisée avec ou sans l'option MULTI :
Pour plus d'informations, consultez la section Résumé des options MULTI et VALUES. Format des valeurs dans liste_valeurs
|
||||||||||||
| libellé |
Libellé de l'interface utilisateur correspondant au paramètre. Dans Robots, libellé est affiché avec le champ d'entrée. |
||||||||||||
| description
optionnel |
Texte descriptif qui fournit des informations supplémentaires sur le paramètre. Dans Robots, description est affiché avec le champ d'entrée. Description peut fournir des instructions qui aident l'utilisateur. Par exemple, « Entrer la date de référence pour la période de paie ». La description doit être entrée sur la ligne suivant la balise PARAM associée. Le texte peut être contenu sur plusieurs lignes, mais aucune ligne ne peut être sautée. Les sauts de ligne ne sont pas conservés lorsque le texte est affiché dans Robots. |
Exemples
Exemples de base
Autorise l'utilisateur à éventuellement spécifier une plage de dates :
//PARAM v_date_début D OPTIONAL Date de début (facultatif)
Entrez la date de début de l'analyse
//PARAM v_date_fin D OPTIONAL Date de fin (facultatif)
Entrez la date de fin de l'analyse
Demande à l'utilisateur de sélectionner le nombre maximal de transactions à traiter :
//PARAM v_maxTrans N VALUES |250|500|750|1000| Transactions maximales à traiter
Demande à l'utilisateur de spécifier un ou plusieurs codes de catégories de marchands :
//PARAM v_codes C MULTI SEPARATOR , QUALIFIER ' MC Code(s) à inclure
Spécifier un ou plusieurs codes de catégories de marchands. Appuyez sur « Entrée » après chaque code pour que chacun d'entre eux se trouve sur une ligne distincte. N'entourez pas les codes de guillemets.
Demande à l'utilisateur de sélectionner un ou plusieurs codes de catégories de marchands :
//PARAM v_codes C MULTI SEPARATOR , QUALIFIER ' VALUES |4121 Taxis/Limousines|5812 Restaurants|5813 Cafés - Boissons alcoolisées|5814 Fast foods| MC Codes à inclure
Sélectionner un ou plusieurs codes de catégories de marchands.
Exemples avancés
Demander à un utilisateur de spécifier une plage de montants
Vous devez classer les enregistrements d'une table qui se trouvent compris entre une plage de montants minimums et maximums. Cette plage change occasionnellement ; vous fournissez donc les paramètres permettant à l'utilisateur exécutant le script d'outil d'analyse de définir la plage lors de la planification ou lors de l'exécution du script :
COMMENT
//ANALYTIC test_outil_analyse
//PARAM v_montant_min N Montant minimum
Saisissez un montant minimum
//PARAM v_montant_max N Montant maximum
Saisissez un montant maximum
END
CLASSIFY ON %v_ChampA% IF BETWEEN(AMOUNT; v_montant_min; v_montant_max) SUBTOTAL AMOUNT TO "Classée_%v_TableAnalyse%.FIL"
Autoriser l'utilisateur à éventuellement exclure un ou plusieurs numéros client
Vous devez classer les enregistrements d'une table, mais vous souhaitez donner à l'utilisateur la possibilité d'exclure certains clients de l'analyse.
Pour ce faire, vous fournissez un paramètre de type caractère facultatif. Votre script teste si oui ou non la valeur est fournie, et, si tel est le cas, les numéros de clients correspondants sont exclus de la commande Classer :
COMMENT
//ANALYTIC test_outil_analyse
//PARAM v_num_client C OPTIONAL MULTI SEPARATOR , QUALIFIER ' Numéros clients à exclure (facultatif)
Indiquez un ou plusieurs numéros clients. Appuyez sur « Entrée » après chaque numéro pour que chaque numéro se trouve sur une ligne distincte. N'entourez pas les numéros de guillemets.
END
IF FTYPE("v_num_client") = "U" v_num_client = ""
GROUP IF v_num_client = ""
CLASSIFY ON %v_ChampA% SUBTOTAL AMOUNT TO "Classée_%v_TableAnalyse%.FIL"
ELSE
CLASSIFY ON %v_ChampA% IF NOT MATCH(CUSTNO; %v_num_client%) SUBTOTAL AMOUNT TO "Classée_%v_TableAnalyse%.FIL"
END
Utilisation des valeurs par défaut pour des paramètres facultatifs
Vous créez un script d'outil d'analyse extrayant les enregistrements des transactions vers une table de résultats. Vous souhaitez donner à l'utilisateur exécutant le script la possibilité de fournir une plage de dates ainsi qu'une liste d'entités pour filtrer les enregistrements à extraire.
Pour ce faire, créez trois paramètres facultatifs :
- v_date_début
- v_date_fin
- v_liste_entités
Dans les lignes d'ouverture du script, vous testez si ces valeurs sont définies. Si elles ne sont pas définies, vous définissez les valeurs par défaut des dates minimale et maximale ainsi qu'un indicateur par défaut à rechercher par test avec v_liste_entités.
Dans la commande EXTRACT, utilisez les valeurs pour filtrer les enregistrements :
COMMENT
//ANALYTIC test
Ce script d'outil d'analyse teste PARAM
//RESULT TABLE t_résultats
//PARAM v_date_début D OPTIONAL Entrez la date de début
//PARAM v_date_fin D OPTIONAL Entrez la date de fin
//PARAM v_liste_entités C MULTI OPTIONAL |entité1|entité2|
END
IF NOT ISDEFINED("v_date_début") v_date_début = `19000101`
IF NOT ISDEFINED("v_date_fin") v_date_fin = `99991231`
IF NOT ISDEFINED("v_liste_entités") v_liste_entités = "'tous'"
EXTRACT FIELDS ALL TO t_résultats IF BETWEEN(date_transaction v_date_début v_date_fin) AND (MATCH(champ_entité %v_liste_entités%) OR v_liste_entités = "'tous'")
Remarques
Conception de paramètres d'entrée facultatifs
Si vous utilisez OPTIONAL avec la balise PARAM, la variable associée au paramètre d'entrée peut ou non être créée au moment de l'exécution du script d'outil d'analyse :
- variable créée automatiquement si l'utilisateur spécifie une valeur d'introduction
- variable non créée si l'utilisateur ignore le paramètre facultatif et qu'il ne précise pas de valeur d'introduction
Test de l'existence de la variable paramètre
Si la logique ultérieure du script d'outil d'analyse dépend de sa capacité à évaluer le contenu de la variable paramètre, y compris l'évaluation d'un état vide ou null, vous devez tester l'existence de la variable du paramètre. Si la variable paramètre n'existe pas, vous devez la créer et l'initialiser sur null.
Utilisez la commande IF avec la fonction FTYPE( ) ou la fonction ISDEFINED( ) pour effectuer le test et créer la variable si elle n'existe pas :
IF FTYPE("nom_var") = "U" nom_var = ""IF NOT ISDEFINED("nom_var") nom_var = ""
Quand effectuer le test
Effectuez le test après l'en-tête de l'outil d'analyse et avant toute logique de script Analytics qui dépend de l'existence de la variable du paramètre.
Résumé des options MULTI et VALUES
Le tableau ci-dessous résume l'effet des options MULTI et VALUES sur la commande de saisie de l'utilisateur dans l'interface utilisateur.
Délimitation et identification des valeurs d'introduction de caractères
Pour la bonne exécution d'un script d'outil d'analyse, s'il y a plusieurs valeurs d'introduction de caractère, elles doivent être délimitées par un séparateur et identifiées.
Éviter les identificateurs de texte imbriqués
Lorsque vous créez des paramètres d'entrée de caractère, et lorsque vous expliquez aux utilisateurs du script d'outil d'analyse comment saisir des valeurs d'introduction de caractère, vous devez veiller à éviter de créer des identificateurs de texte redondants et imbriqués (des identificateurs à l'intérieur d'identificateurs). Des identificateurs au texte redondant entraîneront un dysfonctionnement du paramètre d'entrée.
Méthodes d'insertion d'identificateurs de texte
Il existe quatre méthodes différentes permettant d'insérer des identificateurs de texte autour de valeurs d'introduction de caractère. En fonction de la méthode, un séparateur est également inséré entre les valeurs d'introduction.
Au fur et à mesure que vous développez un script d'outil d'analyse, vous devrez peut-être tester différentes méthodes pour trouver ce qui fonctionne le mieux pour les valeurs de type caractère que les utilisateurs saisiront.
Remarque
Il se peut qu'une ou plusieurs méthodes ne soient pas applicables, en fonction de votre utilisation des options MULTI et VALUES.
Chaque paramètre d'entrée ne doit utiliser qu'une seule de ces méthodes.
| Méthode | Description | |
|---|---|---|
| 1 | Utiliser SEPARATOR et QUALIFIER |
Incluez les options SEPARATOR et QUALIFIER dans la balise PARAM. Par exemple : //PARAM v_régions C MULTI SEPARATOR ; QUALIFIER ' Non applicable si vous utilisez VALUES sans MULTI. Astuce Utilisez cette méthode à chaque fois que cela est possible. C'est celle qui demande le moins de travail et qui générera le moins d'erreurs. |
| 2 | Spécifier manuellement les séparateurs et les identificateurs |
Nécessite que l'utilisateur du script d'outil d'analyse spécifie manuellement des séparateurs et des identificateurs en plus des valeurs d'introduction réelles. Par exemple : 'Amérique du Nord';'Europe';'Asie' Non applicable si vous utilisez VALUES avec ou sans MULTI. |
| 3 | Inclure les identificateurs dans la liste_valeurs |
Incluez les identificateurs avec chaque valeur dans la liste_valeurs spécifiée avec l'option VALUES. Par exemple : VALUES |'Asie'|'Europe'|'Moyen Orient'|'Amérique du Nord'| Non applicable si vous utilisez MULTI sans VALUES. |
| 4 | Insérer la variable du paramètre dans les identificateurs |
Dans la syntaxe du script Analytics, insérez la variable paramètre entre des identificateurs de texte Par exemple : IF MATCH(REGIONS; "%v_régions%") Utilisez cette méthode uniquement si vous utilisez VALUES sans MULTI. |
|
Remarque Les paramètres d'entrée des outils d'analyse ne prennent actuellement pas en charge l'utilisation du double guillemet (") comme identificateur de texte. Vous pouvez utiliser le guillemet simple (') plutôt que l'option QUALIFIER, dans la liste_valeurs, ou lorsque vous indiquez manuellement des identificateurs autour de valeurs d'introduction. Des guillemets doubles peuvent être utilisés en tant qu'identificateurs de texte dans le corps d'un script Analytics. |
||
Cas d'utilisation des différentes méthodes
Le tableau ci-dessous résume quand utiliser les différentes méthodes pour insérer des identificateurs de texte.
