:READ

Utilisez l'instruction de script :READ pour récupérer les données à partir du tampon de lecture. Le tampon de lecture conserve les variables, afin de rendre les valeurs disponibles pour un traitement ultérieur. La fonction de l'instruction :READ dépend du contexte dans lequel vous utilisez cette instruction de script.

Important ! N'utilisez pas de valeurs de texte avec des sauts de ligne dans le tampon de lecture. :READ ignore les caractères après le premier saut de ligne.

Lire des variables dans le tampon de lecture

Utilisez l'instruction :READ pour récupérer les données suivantes dans le tampon de lecture :

• Valeurs enregistrées au démarrage d'un objet avec ACTIVATE_UC_OBJECT
  Pour plus d'informations, voir :PUT_READ_BUFFER, :PUT_PROMPT_BUFFER
• Variables UC_CAUSE* conservées dans le tampon de lecture
  Pour plus d'informations, voir Liste des variables prédéfinies du tampon de lecture.

Lire les données conservées dans le tampon de lecture

Enregistrez une variable de script dans le tampon de lecture avec une instruction :PUT_READ_BUFFER. Activez un objet avec la fonction ACTIVATE_UC_OBJECT. Récupérez la valeur de la variable enregistrée dans le tampon de lecture avec une instruction :READ. Chaque variable de script du tampon ne peut être lue qu'une seule fois. La variable est supprimée du tampon après lecture.

Exemple

Dans l'exemple suivant, le nom de l'agent d'un job est conservé dans le tampon de lecture et active un objet Notification.

:SET &att_host# = GET_ATT(HOST)
:PUT_READ_BUFFER host# = '&att_host#'

:SET &ret# = ACTIVATE_UC_OBJECT('CALLOP')

Dans l'objet Notification, le script suivant récupère le nom de l'agent conservé par le script précédent :

:READ &host#,,

:PRINT "Agent: &host#"

L'exemple suivant illustre un script d'objet Notification. Le script lit les variables UC_CAUSE* pour récupérer les informations relatives à la tâche ayant activé la notification. Le script écrit les informations de la tâche dans le rapport d'activation :

:READ &UC_CAUSE_NAME,,
:READ &UC_CAUSE_NR,,
:READ &UC_CAUSE_STATE,,
:READ &UC_CAUSE_RETCODE,,

:PRINT "This notification was triggered by the following task:"
:PRINT "Name: &UC_CAUSE_NAME"
:PRINT "RunID: &UC_CAUSE_NR"
:PRINT "Status: &UC_CAUSE_STATE"
:PRINT "Return code: &UC_CAUSE_RETCODE"

Boîtes de dialogue utilisateur :READ

Écrivez l'instruction :READ entre une instruction :BEGINREAD et une instruction :ENDREAD pour afficher une boîte de dialogue de saisie utilisateur. Les données saisies par l'utilisateur sont conservées dans les variables et peuvent être utilisées pour un traitement ultérieur.

Les instructions :READ n'affichent les boîtes de dialogue que si l'une des conditions suivantes est vraie :

• Vous avez sélectionné l'option Générer la tâche à : Heure d'activation dans la page Attributs de l'objet. Pour plus d'informations, voir Générer à l'activation ou à l’exécution.
• Activez la tâche manuellement.

Les instructions :READ n'affichent pas les boîtes de dialogue dans les cas suivants et ce sont les valeurs par défaut qui sont utilisées à la place :

• Vous avez sélectionné l'option Générer la tâche à : Exécution dans la page Attributs de l'objet.
• Vous avez sélectionné l'option Générer la tâche à : Exécution pour le workflow dans lequel l'objet est exécuté.
• La tâche est exécutée dans un objet Schedule.
• La tâche s'active avec une fonction de script, par exemple ACTIVATE_UC_OBJECT.
• CallAPI démarre la tâche.
• La tâche est activée via un paramètre d'objet (par exemple dans l'onglet Postcondition d'une tâche de workflow).
• La tâche s'exécute dans un groupe faisant office de queue.

Conseil : Utilisez la fonction de script GET_ATT avec l'attribut DCMODUS pour déterminer si un script est, ou non, exécuté en un mode permettant d'afficher la boîte de dialogue.

Le rapport journalise automatiquement les valeurs qui sont saisies dans les boîtes de dialogue. Vous pouvez désactiver ce comportement pour les rapports de jobs dans les paramètres de l'instruction de script.

Lire la saisie utilisateur dans le tampon de lecture

Écrivez l'instruction :READ dans un bloc :BEGINREAD...:ENDREAD délimité pour l'invite utilisateur et enregistrer les valeurs dans le tampon de lecture.

Syntaxe

:REA[D] InVariable, [Input Check], [Message Text] [, Default Value] [, Input Handling]

Paramètres

• :READ
  Invite de saisie utilisateur

• InVariable
  Variable conservant la saisie utilisateur
  Important ! La valeur spécifiée doit être compatible avec le type de données de la variable cible (InVariable). Pour plus d'informations, voir Types de données des variable de script.
  Format : variable de script

• Input Check
  Valide la saisie utilisateur
  Format : littéral de script ou variable de script
  Longueur maximale : 1024 caractères, avec un maximum de 127 caractères par paramètre de saisie
  Exemple : chacune des variables utilisées pour les paramètres de saisie dans le script suivant est limitée à 127 caractères.
  :READ &INPUT#,'&var1#,&var2#,&var3#','Select a value',&var3#
  Valeurs autorisées :

  • 00
    Pas de validation (par défaut)
  • 01 - 99
    Nombre maximum de caractères que l'utilisateur peut saisir pour la valeur
  • N-M
    Nombre minimum et maximum de caractères que l'utilisateur peut saisir pour la valeur, N et M étant des entiers
    Exemple : 10-20
  • Format de date
    Formats de date et d'heure spécifiés
    Exemple : AAAAMMJJ
    Pour plus d'informations, voir Formats de date, d'heure et de période dans les scripts.
  • Valeur, Valeur1 - Valeur2
    Valeur ou plage de valeurs devant correspondre avec celle saisie par l'utilisateur

• Message Text
  Texte qui apparaît à l'utilisateur dans l'invite
  Format : littéral de script ou variable de script
  Défaut : "Indiquez la valeur pour la variable Nom de variable"

• Default Value
  Valeur proposée par défaut, qui s'affiche dans le champ de saisie
  Format : littéral de script ou variable de script
  Longueur maximale : 127 caractères
  Important ! La valeur par défaut ne peut être une chaîne de caractères vide. Un caractère espace doit être encadré de guillemets.

• Input Handling
  Format de saisie. Spécifie l'option déterminant le mode de traitement de la saisie
  Format : littéral de script ou variable de script
  Valeurs autorisées :

  • C
    (Si l'instruction READ est utilisée dans un bloc :BEGINREAD... :ENDREAD uniquement) Positionne le curseur dans ce champ de saisie 
  • D
    Affiche les caractères saisis sous forme d'astérisques (*)
    Ce paramètre est généralement utilisé pour les mots de passe.
    Remarque : Les valeurs saisies avec ce mode protégé apparaissent chiffrées dans les rapports.
    
  • I
    (Jobs uniquement) Supprime la documentation dans le rapport de l'objet Job généré
    Remarque : Sans cette option, les instructions :READ et la saisie utilisateur sont documentées dans l'objet Job généré sous forme de lignes REMARK.
  • K
    Autoriser les minuscules dans la saisie
    Remarque : sans cette option, la saisie se fait automatiquement en majuscules. Cette option affecte uniquement la saisie de l'interface utilisateur, et non le tampon de lecture.
  • M
    Le champ ne peut pas être vide
  • N
    Seuls des caractères numériques peuvent être saisis
  • O
    Permet à l'utilisateur de sélectionner une entrée dans une liste ou de saisir des entrées
  Remarque : Vous ne pouvez pas utiliser les options D et N ensemble. Pour configurer les entrées protégées qui doivent être numériques, utilisez le paramètre Vérification de la saisie.
  Exemple :
  :READ &PASS#,"1-99999999","Enter password (numerical)",,"DM"

Important !

• N'oubliez pas d'insérer les virgules correspondantes, quels que soient les paramètres Input Check et Message Text de l'instruction :READ.

• Si vous utilisez plusieurs valeurs par défaut (dans une liste déroulante, par exemple), chaque valeur ne doit pas contenir plus de 127 caractères. Les valeurs dépassant les 127 caractères entraînent une erreur d'exécution.
  Conseil : Utilisez des jeux d'invites pour les invites utilisateurs ayant plus d'options. Pour plus d'informations, voir Objets PromptSet (PRPT).

• Si :PUT_VAR est utilisée avant une instruction :READ et que la génération du script de :READ est interrompue manuellement (bouton Interrompre) ou pour cause de valeurs par défaut non valides, l'objet Variable contiendra toujours les valeurs définies avec l'instruction :PUT_VAR. Pour plus d'informations, voir Générer à l'activation ou à l’exécution.
  

Remarques :

• Lorsque l'utilisateur ne saisit, ni ne sélectionne aucune valeur, un espace vide (" ") est enregistré dans la variable de script.

• L'instruction de script écrit toutes les transactions ouvertes du script dans la base de données AE. Pour plus d'informations, voir Traitement du script.

• Afin de combiner les valeurs et plages de valeurs librement, séparez-les par des virgules.

• Dans la vérification de la saisie, vous pouvez utiliser des lettres ou des chiffres ou une combinaison des deux. Si vous combinez des lettres avec des chiffres, le nombre de caractères est vérifié.
  Exemple :Structurez le paramètre comme suit pour combiner lettres avec des chiffres.
  :READ &INPUT#, "A-F,1-9,01-99,001-999","Please select"

• Spécifiez les virgules et les traits d'union entre guillemets simples s'ils ne doivent pas être interprétés comme des séparateurs.
  Exemple : L'utilisateur peut sélectionner soit la valeur 1 à 5, soit la valeur 8,9.
  :READ &OPTION#,"'1-5','8,9'",'Please select','1-5'
  

La boîte de dialogue de saisie affiche le nom d'objet dans la barre de titre. Utilisez les paramètres d'instruction de script pour définir l'apparence et le contenu de la boîte de dialogue.

• Champ numérique
  Définissez une plage de valeurs numériques continue, telle que 0 à 255 avec l'option Input Check N pour afficher un champ de nombres avec des flèches vers le haut et vers le bas dans la boîte de dialogue .
• Zone de liste
  Définissez un jeu de valeurs fixe, tel que A,B,C dans le paramètre Vérification de la saisie pour afficher les valeurs dans une zone de liste.
• Champ texte
  Définissez une plage, telle que A,5-9 dans le paramètre Input Check pour afficher un champ de saisie.
  

Exemples

Le script de l'exemple suivant crée une boîte de dialogue demandant à l'utilisateur une ligne d'en-tête. La saisie de l'utilisateur n'est pas validée et les champs peuvent rester vides. Les caractères sont immédiatement convertis en majuscules.

:READ &HEADLINE#,"00","Please enter headline"

L'exemple suivant illustre aussi une demande de ligne d'en-tête à l'utilisateur. La boîte de dialogue ne propose pas de valeur par défaut et ne valide pas la saisie. La saisie de minuscules est possible.

:READ &HEADLINE#,,,,"K"

L'exemple suivant illustre une demande de chiffre à l'utilisateur. L'option Traitement de la saisie étant sur N, la boîte de dialogue contient un champ numérique. Seuls les nombres entre 0 et 5 sont acceptés.

:READ &NUMBER#,"0-5","Please enter number",,"N"

L'exemple suivant illustre une demande de date à l'utilisateur. La saisie doit être une date valide au format AAMMJJ et est obligatoire.

:READ &DATE1#,"YYMMDD","Please specify a date (YYMMDD)",,"M"

L'exemple suivant illustre une demande de signature à l'utilisateur. La valeur par défaut du champ de saisie est A. la valeur saisie dans le champ est validée pour vérifier si elle correspond aux valeurs autorisées de A, X et aux chiffres entre 5 et 9.

:READ &LKZ#,"A,X,5-9","Please enter List Signature","A"

Dans l'exemple suivant, le système demande à l'utilisateur de saisir un mot de passe de 8 caractères maximum. Les options Input Handling D, M et K déterminent que le champ est sécurisé, que les lettres ne sont pas converties en majuscules et que le champ doit être obligatoirement renseigné, dans l'ordre.

:READ &PASS#,"08","Please enter password (max. 8 characters)",,"DMK"

L'exemple suivant illustre une demande d'adresse email à l'utilisateur. L'utilisateur peut sélectionner trois adresses email. Pour que le trait d'union ne soit pas interprété en tant que plage de valeurs, la dernière adresse est entre guillemets simples.

:READ &USER#,"brown@automic.us,johnson@automic.us,'smith@late-night.com'", "Please select user"

Dans l'exemple suivant, le système demande à l'utilisateur de sélectionner une adresse ou d'en saisir une nouvelle.

:READ &USER#,"brown@automic.us,johnson@automic.us,'smith@late-night.com'", "Please select user",,"O"

Voir aussi :