Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script
Retour à la table des matières
TSD Script offre un système de formulaires qui permet de créer des fenêtres à partir d'un fichier (ressource) de description.
Un formulaire est une fenêtre contenant un certain type de formulaire de saisie de données. Dans un environnement à interface graphique, le formulaire constitue le principal moyen d'interaction entre l'utilisateur et l'application. Le développeur y place des contrôles qu'il sélectionne à partir d'une barre d'outils. Les contrôles de formulaire sont les suivants :
Un contrôle de formulaire est un élément qui sert soit à obtenir des informations de l'utilisateur, soit à lui fournir des informations. Par exemple, un formulaire de saisie de données comprend généralement un ou plusieurs contrôles de type zone de texte, un bouton OK et un bouton Annuler (ou Annulation). Vous pouvez utiliser le module Interface Designer (concepteur d'interfaces) du Developer's Toolkit pour ajouter des contrôles à un formulaire (pour plus de détails, reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide du concepteur d'interfaces).
La liste suivante répertorie tous les contrôles de formulaire pris en charge par TSD Script.
Nom de contrôle | Description |
Sous-formulaire | Contrôle complexe qui englobe plusieurs autres contrôles. |
Zone de texte | Zone rectangulaire permettant à l'utilisateur de saisir une seule ligne d'informations. Si le texte entré dépasse la limite droite de la zone, celle-ci défile automatiquement. |
Zone de texte multiligne | Zone rectangulaire utilisée pour saisir plusieurs lignes de texte. Elle peut être configurée pour le renvoi automatique à la ligne. |
Boîte à liste | Boîte rectangulaire contenant une liste de choix déterminés. L'utilisateur ne peut pas y saisir de texte. |
Boîte mixte | Zone de texte à laquelle est associée une boîte à liste. L'utilisateur peut soit saisir une valeur dans la zone de texte, soit sélectionner un choix prédéfini dans la liste déroulante. La valeur sélectionnée apparaît dans la zone de texte, tandis que la liste se referme. |
Arbre | Contrôle qui affiche des données sous forme hiérarchique. |
Bouton d'option | Bouton utilisé pour sélectionner une option parmi plusieurs options qui s'excluent mutuellement. Le bouton sélectionné comporte un cercle noir. |
Case à cocher | Case correspondant à une option que l'utilisateur peut activer ou désactiver. Plusieurs cases peuvent être cochées en même temps. |
Curseur de défilement | Barre dont le déplacement est interactif. |
Bouton (de fonction) | Bouton rectangulaire déclenchant une action. |
Texte | Zone affichant un texte. L'utilisateur ne peut pas modifier ce texte. |
Horloge | Horloge horaire ou compteur de temps écoulé. |
Table | Données organisées en lignes et en colonnes. |
Hypertexte | Région affichant du texte dans un format hypertexte. |
Boîte d'option | Cadre rectangulaire qui regroupe plusieurs contrôles suivant la fonction de ces derniers. |
Image | Champ qui affiche une image issue d'un fichier. |
Les formulaires sont gérés en tant que ressources d'application séparées. Le Developer's Toolkit vous permet de créer un ensemble de spécifications de formulaire et de les stocker dans des fichiers identifiés par l'extension (ou suffixe) .df. Comme pour les fichiers de base de connaissances, il existe un fichier source et un fichier objet pour de telles spécifications. Un fichier .df autorise la spécification de menus, de barres d'outils et de chaînes.
Le Générateur d'interface est un programme TSD Script qui, à partir d'un fichier source .df, crée un fichier objet .dfc. Les fichiers .dfc sont chargés et affichés par le Developer's Toolkit au moment de l'exécution.
L'exemple suivant est un fragment de code TSD Script qui met en jeu un formulaire.
TYPES EmployeeRecord IS RECORD first, last, ssn : STRING; salary : REAL; department : STRING; END; VARIABLES employee: EmployeeRecord; ACTIONS IF DlgBox($Desktop,'EMPLOYEE.DFC[ADDFORM]', $NullHandler,employee) > 0 THEN SQLInsert('EMPLOYEES',employee); END;
Dans cet exemple, un nouveau type EmployeeRecord est déclaré dans la section TYPES. La section VARIABLES comporte également une variable de ce type. Le nom des champs d'enregistrement est identique au nom des contrôles de formulaire.
Voici ce que fait l'instruction DlgBox, dans la section ACTIONS :
En générale, les formulaires contiennent également des boutons OK et Annuler.
L'instruction DlgBox reçoit quatre arguments :
Titre d'argument | Description |
Fenêtre mère | Descripteur de la fenêtre mère du nouveau formulaire. |
Fichier formulaire | Nom d'un fichier de spécification de formulaire compilé.
Si celui-ci contient plusieurs spécifications de formulaire, le nom du formulaire souhaité doit être indiqué entre crochets à la suite du nom du fichier. |
Gestionnaire d'événements | Comme les fenêtres génériques décrites précédemment, tous les formulaires
ont un gestionnaire d'événements qui leur est associé.
Il est parfois souhaitable que le gestionnaire entreprenne l'action par défaut
pour chaque événement. Pour tous ces cas, vous pouvez Lorsque l'utilisateur choisit le bouton OK, TSD Script copie
automatiquement le contenu des contrôles du formulaire |
Variable résultat | Variable de type enregistrement dont les champs correspondent
chacun à un contrôle du formulaire. Lorsque l'utilisateur quitte le
formulaire en sélectionnant OK, le contenu de chaque contrôle est
copié dans |
Etudiez cet autre exemple :
TYPES EmployeeRecord IS RECORD first, last, ssn : STRING; salary : REAL; department : STRING; END; VARIABLES employee: EmployeeRecord; ACTIONS SQLSelectInto('SELECT * FROM EMPLOYEES WHERE SSN=305-33-4111',employee); IF DlgBox($Desktop,'EMPLOYEE.DFC[EDITFORM]', $NullHandler{employee},employee) >> 0 THEN SQLUpdate('EMPLOYEES','WHERE SSN=''' & employee.snn & '''',employee); END;
Dans cet exemple, le code procède aux opérations suivantes :
Deux modifications ont été apportées à cette instruction DlgBox :
Dans cet exemple, l'utilisateur voit s'afficher les données extraites de la table EMPLOYEES dans le formulaire, et il est en mesure d'accéder à n'importe quel contrôle et d'en modifier le contenu.
Pour mettre en oeuvre des fonctions avancées, telles qu'un bouton provoquant l'affichage de la photo d'un employé, ou encore la validation du format d'un numéro de sécurité sociale, vous devez faire appel à un gestionnaire d'événements. Il faut pour cela créer des gestionnaires d'événements de formulaire.
Cette section présente un formulaire fonctionnant avec un gestionnaire d'événements. L'exemple sur lequel elle s'appuie met en jeu une base de connaissances appelée Employees, qui implémente une seule fonction publique ayant pour nom AddEmployee. Le corps de AddEmployee est similaire à celui des exemples précédents, sauf qu'au lieu d'utiliser $NullHandler, il référence un gestionnaire d'événements appelé EmployeeEvent.
KNOWLEDGEBASE Employees; USES Globals; TYPES EmployeeRecord IS RECORD first, last, ssn : STRING; salary : REAL; department : STRING; END; ROUTINES FUNCTION AddEmployee: BOOLEAN; PRIVATE ROUTINES EVENT EmployeeEvent(REF employee: EmployeeRecord) IS ROUTINES
FUNCTION ValidSSN(VAL ssn: STRING): BOOLEAN IS VARIABLES i: INTEGER; ACTIONS IF StrLength(ssn) <> 11 THEN EXIT(FALSE); END; FOR i:=1 TO 11 DO IF (i = 4 OR i = 7) AND (ssn[i] <> '-') THEN EXIT(FALSE); ELSIF StrPos('0123456789',ssn[i]) = 0 THEN EXIT(FALSE); END; END; EXIT(TRUE); END (* Valid SSN *);
ACTIONS WHEN $Event IS $MsgSelect THEN WHEN $FieldName IS 'SSN' THEN IF NOT ValidSSN(employee.ssn) THEN Exit(0); END; ELSWHEN 'PICTURE_BUTTON' THEN ShowPicture(employee.last_name & '.BMP'); END; END; END (* Employee Event *);
FUNCTION AddEmployee: BOOLEAN IS VARIABLES employee: EmployeeRecord; ACTIONS IF DlgBox(mainWindow, 'EMPLOYEE.DFC[ADDFORM]', EmployeeEvent{employee},employee) > 0 THEN SQLInsert('EMPLOYEES',employee); EXIT(TRUE); ELSE EXIT(FALSE); END; END (* Add Employee *);
EmployeeEvent est un descripteur d'événements qui reçoit par référence un paramètre unique du même type que la variable de retour transmise dans DlgBox.
Le gestionnaire d'événements teste un seul événement, $MsgSelect. Il est
généré chaque fois que le formulaire est sur le point de faire sortir le curseur du contrôle en cours.
Si l'utilisateur tape une valeur dans un contrôle de type zone de texte et qu'il appuie ensuite
sur la touche de tabulation, un événement $MsgSelect est généré.
Le nom du contrôle que l'utilisateur est sur le point de quitter accompagne
l'événement dans un paramètre "invisible" appelé $FieldName.
Etudions plus en détail le corps du gestionnaire EmployeeEvent.
WHEN $Event IS $MsgSelect THEN WHEN $FieldName IS 'SSN' THEN IF NOT ValidSSN(employee.ssn) THEN Exit(0); END; ELSWHEN 'PICTURE_BUTTON' THEN ShowPicture(employee.last_name & '.BMP'); END; END;
Le comportement obtenu est le suivant :
Le résultat par défaut est "1", valeur qui indique le succès de l'opération. Il existe toutefois des cas où il est nécessaire de renvoyer une valeur différente.
Certains événements générés automatiquement par TSD Script sont refusés lorsque le gestionnaire d'événements sort (Exit) avec la valeur 0. $MsgSelect fait partie de ces événements.
EmployeeEvent traite l'événement $MsgSelect associé au champ SSN et, s'il détermine qu'un numéro de sécurité sociale non valide a été saisi, il sort avec la valeur 0.
On dit alors que l'événement est refusé. Ce refus a deux conséquences :
Généralement, l'événement $MsgSelect signale que quelque chose a changé dans le formulaire. Il peut être généré de trois manières :
Remarque : $MsgSelect est généré uniquement lorsque la nouvelle valeur insérée est différente de l'ancienne.
Remarque : Appuyer sur la touche Entrée revient à sélectionner le bouton de fonction par défaut, s'il y en a un de défini. Cela génère un événement $MsgAccept. Si aucun bouton par défaut n'est défini, un message $MsgSelect est généré.
Lorsque le gestionnaire d'événements reçoit l'événement $MsgSelect, les données d'instance de la fenêtre (que le gestionnaire référence avec son argument enregistrement) sont mises à jour pour refléter le changement. Par exemple, lorsque l'utilisateur tape une valeur dans la zone de texte SSN et appuie sur la touche de tabulation, la valeur saisie est copiée dans le champ SSN de la variable d'instance de la fenêtre et un événement $MsgSelect est généré. La précédente valeur du champ est disponible dans le premier paramètre sans nom de l'événement.
La valeur du contrôle est indéfinie tant que l'envoi du message Select n'est pas terminé. Par conséquent, elle ne peut pas être interrogée.
Les formulaires peuvent générer d'autres événements, dont voici la liste :
Evénement de formulaire | Description |
$MsgInitialize | Version spéciale de $MsgSelect qui est générée uniquement pendant la phase de création du formulaire. |
$MsgCreate | Reçu juste avant l'affichage du formulaire.
C'est le moment idéal pour opérer les initialisations telles que l'ajout de la liste des choix possibles à une boîte à liste, etc. |
$MsgDestroy | Reçu juste avant la fermeture du formulaire. |
$MsgAccept | Reçu lorsque l'utilisateur valide le formulaire, généralement en appuyant sur Entrée ou en sélectionnant OK. |
$MsgCancel | Reçu lorsque l'utilisateur annule le formulaire, généralement en appuyant sur Echap ou en choisissant Annuler. |
$MsgEnterField | Reçu lorsque le curseur est sur le point de désigner un nouveau contrôle.
$FieldName
contient le nom du nouveau contrôle. |
$MsgExitField | Reçu lorsque le curseur est sur le point de quitter un contrôle. Le nom de ce contrôle est contenu dans $FieldName. |
$MsgHelp | Reçu lorsque l'utilisateur choisit Aide ou appuie sur F1. |
$MsgMandField | Reçu lorsque l'utilisateur tente de valider un formulaire alors qu'une ou plusieurs
zones de texte obligatoires ne sont pas remplies.
$FieldName contient alors le nom de la première zone obligatoire vide.
Par défaut, le système affiche |
Chaque contrôle présent dans un formulaire porte un nom. Dans les exemples étudiés précédemment, un formulaire est utilisé pour obtenir les informations nécessaires au remplissage d'une variable de type EmployeeRecord. Etant donné que cet enregistrement comporte un champ appelé FIRST_NAME (prénom), le formulaire doit comporter un contrôle portant le même nom. Ainsi, lorsque l'utilisateur entre une valeur dans le contrôle FIRST_NAME, cette valeur est copiée dans le champ FIRST_NAME de l'enregistrement.
Remarque : Certains contrôles ne transportent pas de données. Par exemple, les boutons de fonction ne possèdent pas de valeur ; ils génèrent simplement des événements. C'est pourquoi il n'est pas nécessaire de prévoir des champs d'enregistrement pour ces boutons.
D'autres attributs peuvent être spécifiés pour les contrôles d'un formulaire :
Attribut | Description |
Read Only | La donnée du contrôle est initialisée par l'enregistrement d'instance de la fenêtre et ne peut pas être modifiée par l'utilisateur. |
Mandatory | L'utilisateur ne peut pas valider le formulaire tant qu'il n'a pas fourni une valeur pour chacun des contrôles possédant cet attribut (qui signifie "obligatoire"). |
Input Length | Indique le nombre de caractères que l'utilisateur peut entrer dans le contrôle, lorsqu'il s'agit d'une zone de texte. |
Il existe aussi d'autres attributs qui concernent uniquement certains contrôles. Par exemple, dans le cas des zones de texte multilignes, vous pouvez activer ou désactiver le renvoi automatique à la ligne.
Table est une fenêtre utilisée pour visualiser une table de résultats SQL, c'est-à-dire un ensemble de lignes et de colonnes.
Table est utilisé comme contrôle de formulaire. Il permet d'effectuer les opérations suivantes :
Les colonnes de Table sont redimensionnables.
Les colonnes sont séparées par une fine barre verticale, que l'utilisateur peut
déplacer pour changer leur largeur.
L'expression de sélection (SELECT...) peut être spécifiée dans le fichier .df ou
par programmation.
Instruction | Description |
DlgSQLSelect | Lorsqu'il reçoit cette instruction, TSD Script émet la requête SQL
spécifiée et met à jour le contenu du contrôle Table indiqué pour
y faire apparaître les résultats de cette requête.
Cette instruction prend trois arguments :
Il s'agit du moyen le plus efficace d'extraire des données d'une base de données pour les placer dans un contrôle de type table. |
DlgFieldValue | Peut être utilisée pour extraire une ligne sélectionnée. Cette instruction prend trois arguments :
Les colonnes de la ligne sont copiées dans les champs de l'enregistrement qui possèdent le même nom (par exemple, le contenu de la colonne "FIRST_NAME" est copié dans r.FIRST_NAME). |
DlgListBoxInsert | Insère une nouvelle ligne dans Table. Son rôle
n'est pas d'exécuter une instruction SQLInsert, mais d'ajouter
une nouvelle ligne au contrôle désigné. Cette instruction prend trois arguments :
Les valeurs des champs qui ont un homonyme dans le contrôle sont copiées dans les colonnes correspondantes, tandis que les champs auxquels aucune colonne ne correspond sont ignorés. |
DlgListBoxUpdate | Met à jour une ligne sélectionnée dans Table. Son
rôle n'est pas d'exécuter une instruction SQLUpdate, mais de mettre à jour les
informations dans le formulaire. Cette instruction prend trois arguments :
Les valeurs des champs qui ont un homonyme dans le contrôle sont copiées dans les colonnes correspondantes, tandis que les champs auxquels aucune colonne ne correspond sont ignorés. |
DlgListBoxDelete | Supprime la ligne sélectionnée dans le contrôle Table.
Son rôle n'est pas d'exécuter une instruction SQLDelete, mais de supprimer
une ligne du contrôle indiqué, dans le formulaire.
Cette instruction prend deux arguments :
|
Dans cet exemple, on crée une base de connaissances appelée Users, qui comporte une seule procédure publique nommée WorkWithUsers.
KNOWLEDGEBASE Users; TYPES UserRecord IS RECORD $Select : String; user_ID : String; user_name : String; user_rights : Integer; END; ROUTINES PROCEDURE WorkWithUsers; PRIVATE ROUTINES EVENT UserEvent(REF user: UserRecord) IS; VARIABLES i: Integer; ROUTINES PROCEDURE AddUser IS; VARIABLES newUser: UserRecord; ACTIONS IF DlgBox($Desktop,'USERS.DFC[ADDFORM]',$NullEvent, newUser) > 0 AND SQLInsert('USERS',newUser) > 0 THEN DlgListBoxInsert($Handle,'USERLIST',newUser); END; END (* Add User *);
PROCEDURE EditUser IS; ACTIONS IF DlgFieldValue($Handle,'USERLIST',user) > 0 AND DlgBox($Desktop,'USERS.DFC[ADDFORM]',$NullEvent {user},user) > 0 AND SQLUpdate('USERS','USER_ID=''' user.user_ID & '''',user) > 0 THEN DlgListBoxUpdate($Handle,'USERLIST',user); END; END (* Edit User *);
PROCEDURE DeleteUser IS; ACTIONS IF DlgFieldValue($Handle,'USERLIST',user) > 0 AND SQLDelete('USERS','USER_ID='''&user.user_ID&'''') > 0 THEN DlgListBoxDelete($Handle,'USERLIST',user); END; END (* Delete User *);
ACTIONS WHEN $Event IS $MsgCreate THEN DlgSQLSelect($Handle,'USERLIST',user.$select); ELSWHEN $MsgSelect THEN WHEN $FieldName IS 'ADD_BUTTON' THEN AddUser; ELSWHEN 'EDIT_BUTTON' THEN EditUser; ELSWHEN 'DELETE_BUTTON' THEN DeleteUser; END; END; END (* User Event *);
PROCEDURE WorkWithUsers IS; VARIABLES UserWindow: WINDOW; user: UserRecord; ACTIONS user.$select = 'SELECT * FROM USERS'; DlgCreate($Desktop,userWindow, 'USERS.DFC [WORKWITHUSERS]', UserEvent{user}); END (* Work With Users *);
Le rôle de WorkWithUsers est de créer un formulaire comportant les contrôles suivants :
Le gestionnaire d'événements UserEvent du formulaire traite les événements suivants :
~ Le message $MsgSelect est généré, le nom du bouton de fonction,
EDIT_BUTTON, étant transmis dans $FieldName.
~ Le gestionnaire d'événements appelle la procédure EditUser pour
traiter cet événement.
EditUser utilise d'abord l'instruction DlgFieldValue pour récupérer la valeur
de la ligne sélectionnée.
~ Elle utilise ensuite la spécification de formulaire EDITFORM, tirée du fichier USERS.DFC,
pour créer un formulaire dans lequel l'utilisateur pourra effectuer les modifications
souhaitées.
~ Lorsque l'utilisateur valide le formulaire, l'instruction SQLUpdate
est utilisée pour mettre à jour la ligne dans la table USERS,
tandis que l'instruction DlgListBoxUpdate
est utilisée pour mettre à jour la ligne correspondante dans le contrôle Table USERLIST.
Le contrôle Table détient seulement les informations spécifiées par la
description de ses colonnes.
Il peut s'agir d'un sous-ensemble des colonnes de la table de résultats SQL.
Lorsque vous utilisez l'instruction DlgFieldValue pour récupérer une ligne
du contrôle Table, seuls les champs correspondant aux colonnes présentes
dans ce contrôle sont renvoyés.
Pour compléter le reste de l'enregistrement, il se peut que vous deviez recourir aux opérations
SQLSelectInto ou SQLSelect.
Le processus de création d'un formulaire par TSD Script implique plusieurs étapes :
Remarque : Les données de la variable enregistrement d'instance supplantent les valeurs d'initialisation fournies dans le fichier de spécification de formulaire.
On dit d'un formulaire qu'il est modal lorsque le programme attend, avant de poursuivre, que l'utilisateur ait validé ou annulé le contenu de ce formulaire. Lorsqu'une boîte de dialogue modale est affichée, aucune autre fenêtre ne peut être sélectionnée.
Les formulaires modaux se créent à l'aide de l'instruction DlgBox. L'instruction qui fait suite à DlgBox n'est pas exécutée tant que l'utilisateur n'en a pas terminé avec le formulaire créé par DlgBox. Les informations spécifiées par l'utilisateur sont renvoyées dans le quatrième argument de DlgBox. Il s'agit de la variable enregistrement de sortie.
L'utilisation de formulaires modaux doit être réservée aux messages d'erreur importants ou aux boîtes de dialogue dans lesquelles l'utilisateur doit impérativement fournir une réponse. Il peut s'agir, par exemple, d'un message invitant l'utilisateur à confirmer la suppression de fichiers.
On dit d'un formulaire qu'il est non modal (ou amodal) lorsque l'application n'a pas besoin d'une réponse de l'utilisateur dans ce formulaire pour poursuivre son exécution. Cela signifie que l'utilisateur est en mesure de basculer vers d'autres fenêtres alors que le formulaire est affiché à l'écran.
Les formulaires non modaux se créent à l'aide de l'instruction DlgCreate. Un appel à l'instruction DlgCreate démarre le processus de création d'un formulaire. Cependant, l'exécution de l'instruction suivante se déroule simultanément.
Le nouveau formulaire possède sa propre interface utilisateur et son propre programme (son gestionnaire d'événements). Son existence dure jusqu'à ce que l'utilisateur le valide ou l'annule, ou jusqu'à ce qu'une autre partie de l'application lui envoie un message de fermeture ($MsgClose).
Remarque : En programmation événementielle, les formulaires non modaux sont préférés aux formulaires modaux.
TSD Script permet de créer des formulaires à onglets. Chaque onglet correspond à une page. Pour accéder à une page particulière, l'utilisateur clique simplement sur l'onglet correspondant.
Pour créer un formulaire à onglets dans le module Interface Designer (concepteur d'interfaces) du Developer's Toolkit, vous devez spécifier un ou plusieurs formulaires à combiner. A l'exécution, ces formulaires s'utilisent exactement comme les autres types de formulaires. Ils peuvent être créés soit avec l'instruction DlgBox, soit avec DlgCreate. Pour gérer leurs événements, vous pouvez créer un gestionnaire d'événements.
Lorsque vous travaillez sur des formulaires à onglets, tenez compte des points suivants :
Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script