Tivoli Service Desk 6.0 Developer's Toolkit Script - Manuel de référence du langage TSD Script
Cette variable est un paramètre implicite contenant un numéro d'événement vers un gestionnaire d'événements (par exemple, un numéro de message tel que $MsgPaint etc.) pour l'appel courant du gestionnaire.
Non applicable.
Dans une application en fenêtres, TSD Script, les événements sont les principaux éléments de l'application. Ces événements sont générés à partir de plusieurs sources, notamment :
Les événements sont transmis par TSD Script aux gestionnaires d'événements. Différentes routines de TSD Script (comme celles servant à créer les fenêtres et les boîtes de dialogue), vous permettent de spécifier d'autres routines pour intercepter les événements et y réagir.
Le gestionnaire d'événements accède au paramètre intégré $Event. $Event contient soit l'une des constantes de message prédéfinie, soit l'une des constantes de message définie par le programmeur de TSD TSD Script. Chaque constate de message indique le type d'événement qui est transmis.
Pour plus d'informations sur les événements, reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit TSD Script - Guide de programmation.
Permet à un gestionnaire d'événements d'accéder aux autres paramètres inclus dans un message.
FUNCTION $EventParm(n: INTEGER, type: DATATYPE): DATATYPE;
Nom de l'argument | Description |
n | Cet argument permet d'identifier le paramètre de l'événement. Les paramètres d'événements sont numérotés à partir de 1. |
Type | Il s'agit d'un type de données prédéfinies ou définies par l'utilisateur, qui correspond au type de données du paramètre de référence. Si le type de données qui a été spécifié ne correspond pas à celui du paramètre transmis par l'expéditeur du message, un message d'erreur d'exécution s'affiche. |
Les gestionnaires TSD Script reçoivent toujours trois paramètres fixes. Le premier est une copie de l'enregistrement d'instance de la fenêtre. Ce paramètre apparaît explicitement dans la déclaration du gestionnaire d'événements. Les deux suivants, $Event et $Handle sont des paramètres implicites qui permettent d'identifier respectivement l'événement à traiter et la fenêtre qui génère l'événement.
Un gestionnaire d'événements peut recevoir plusieurs paramètres supplémentaires. Certains événements système (comme $MsgSize) s'accompagnent d'éléments d'information supplémentaires qui sont transmis en tant que paramètres supplémentaires.
Les messages définis par l'utilisateur envoyés par l'intermédiaire de l'instruction SendMessage peuvent transmettre des paramètres supplémentaires. L'expéditeur et le récepteur doivent se mettre d'accord sur le nombre, le type et la signification des paramètres. Un gestionnaire de paramètres peut avoir accès à ces paramètres d'événements via $EventParm.
$EventParm prend de deux arguments : un entier destiné à identifier le paramètre supplémentaire à récupérer et un type de donnée valide correspondant au type de données du paramètre envoyé. Bien qu'un certain nombre de paramètres supplémentaires puissent être envoyés à un gestionnaire d'événements, le nombre et le type de paramètres sont implicites dans le numéro de l'événement.
Par exemple, un événement défini par l'utilisateur peut être paramétré pour que toute fenêtre puisse demander son nom à n'importe quelle fenêtre. Ceci si l'on considère que le nom de champ existe dans les données d'instance de chaque fenêtre et est transmis par l'intermédiaire des données d'initialisation. Un message défini par l'utilisateur peut être paramétré en définissant une constante globale telle que :
CONSTANTS QUERY_WINDOW_NAME IS $MsgUser+1;
Ensuite, selon le descripteur de la fenêtre, vous pouvez obtenir le nom de cette fenêtre de la manière suivante :
VARIABLES window_name: String; ACTIONS SendMessage(some_window,QUERY_WINDOW_NAME,window_name);
Chaque fenêtre doit avoir le gestionnaire d'événements suivant :
ACTIONS WHEN $Event IS ... ... ELSWHEN QUERY_WINDOW_NAME THEN $EventParm (1,String):=myData.myName; ELSWHEN ...
EVENT MyEvent(REF r: MyRecord); VARIABLES width, height: INTEGER; ACTIONS WHEN $Event IS $MsgSize THEN width:=$EventParm(1,Integer); height:=$EventParm(2,Integer); ...
Pour plus d'informations sur les événements, reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit TSD Script - Guide de programmation.
Paramètre implicite transmis à chaque gestionnaire d'événements identifiant la fenêtre qui reçoit le message.
Attention : $Handle contient toujours le descripteur de la fenêtre qui reçoit l'événement courant. $Handle n'apparaît que dans un gestionnaire d'événements.
EVENT MyEvent(REF r: MyData); ACTIONS WHEN $Event IS $MsgCreate THEN WinSetIconBar($Handle,{'CREATE.ICO','DESTROY.ICO'}: LIST OF STRING); ...
Spécifie qu'il n'y a pas de traitement de l'événement pour une instruction nécessitant un gestionnaire d'événements.
EVENT $NullHandler{initializationData}: INTEGER;
Nom de l'argument | Description |
initilizationData | Cet argument est facultatif. S'il est utilisé, il provoque la création de données d'instance du même type que lui. Les données d'instance sont initialisées selon la valeur de cet argument. |
La syntaxe utilisée pour $NullHandler est la même que celle utilisée pour toutes les valeurs $ se servant d'un gestionnaire d'événements.
KNOWLEDGEBASE Desktop; ROUTINES PROCEDURE Example; PRIVATE ROUTINES (* Create a scroll window parented by the desktop with default event processing *) PROCEDURE Example IS VARIABLES whdl: WINDOW; ACTIONS WinCreateScrollWindow($Desktop,
(* Window is a child of (*OS/2 desktop *) whdl,
(* return handle of new window *) $NullHandler,
(* Default event processing *) 5, 5, 80, 20,
(* Window location and size *) 'Example',
(* Window title *) '',
(* Use default font *) 0,
(* Point size is ignored for default *) BitOr($WinTitle, $WinBorder, $WinSysMenu )); WinWait( whdl ); END;
Délègue le traitement d'un événement d'une routine à une autre.
FUNCTION DelegateEvent ( VAL handler: EVENT, [ REF userData: ANY ] ): INTEGER;
Nom de l'argument | Description |
handler | Nom de la fonction qui gère l'événement |
userData | Variable transmise en référence à la fonction qui gère l'événement. |
Attention : Les appels vers la fonction DelegateEvent doivent être dan la portée d'une routine de gestion d'événement.
Il arrive souvent que plusieurs boîtes de dialogue ou d'autres éléments destinés à la gestion des messages traitent les mêmes types de données et répondent à plusieurs messages identiques à la fois. La fonction DelegateEvent peut être utilisée pour éviter de répéter le même code dans les routines pour chacun de ses éléments.
DelegateEvent appelle la routine et transmet tous les pseudo paramètres du descripteur (par exemple $Event, $Handle et tous les paramètres de $EventParm). Si le descripteur en question comprend un paramètre explicite pour les données utilisateur et qu'elles ne sont pas spécifiées dans l'appel de DelegateEvent, les données utilisateur du descripteur sont transmises par défaut.
KNOWLEDGEBASE Test; ROUTINES PROCEDURE Main; PRIVATE TYPES BaseData IS RECORD f1: INTEGER; f2: STRING; END; DerivedData IS RECORD base: BaseData; f3: REAL; END; CONSTANTS MSG_ONE IS $MsgUser + 1; MSG_TWO IS $MsgUser + 2; MSG_THREE IS $MsgUser + 3; ROUTINES EVENT BaseHandler (REF userData: BaseData) IS ACTIONS WHEN $Event IS MSG_ONE THEN userData.f1 := $EventParm(1, INTEGER); WinWriteLn($Handle, 'f1 set to [' & userData.f1 &']'); ELSWHEN MSG_TWO THEN userData.f2 := $EventParm(1, STRING); WinWriteLn($Handle, 'f2 set to [' & userData.f2 & ']'); END; END; EVENT DerivedHandler (REF userData: DerivedData) IS ACTIONS WHEN $Event IS MSG_THREE THEN userData.f3 := $EventParm(1, REAL); WinWriteLn($Handle, 'f3 set to [' & userData.f3 & ']'); ELSE $Result := DelegateEvent(BaseHandler, userData.base); END; END; PROCEDURE Main IS VARIABLES w: WINDOW; ACTIONS IF 0 > WinCreateScrollWindow($Desktop, w, DerivedHandler, 10, 10, 80, 25, 'Test', $Courier, 8, $WinDefaultStyle) THEN EXIT; END; WinWriteLn(w, 'Ready to send MSG_ONE.'); SendMessage(w, MSG_ONE, 37); WinWriteLn(w, 'Ready to send MSG_TWO.'); SendMessage(w, MSG_TWO, 'I''m pink, therefore I''m Spam.'); WinWriteLn(w, 'Ready to send MSG_THREE.'); SendMessage(w, MSG_THREE, $Pi); WinWriteLn(w, 'Test complete.'); SendMessage(w, $MsgClose); END; END;
La valeur de l'entier retournée par DelegateEvent correspond à la valeur retournée par le gestionnaire d'événements appelé. La sémantique de la valeur retournée varie selon le message de $Event.
Affiche un message dans la fenêtre du gestionnaire d'événements.
PostMessage( VAL whdl: WINDOW, VAL message: INTEGER, [ VAL msgParm: ANY ... ] ): INTEGER;
Nom de l'argument | Description |
whdl | Descripteur d'un élément qui gère les événements, comme une fenêtre. |
message | PostMessage affiche un message dans une
fenêtre et retourne immédiatement un code d'erreur ou de réussite
sans attendre que le message ait été envoyé. Le message est ajouté à
la file d'attente de messages de la fenêtre cible. Il est envoyé vers
la fenêtre de destination lorsque l'application lance le gestionnaire
d'événement. Les instructions de Tivoli Service Desk Developer's Toolkit qui comprennent une boucle de traitement des messages, sont les suivantes :
|
messageParameters | Tous. C'est à celui qui affiche et à celui qui lit de se mettre d'accord sur les types, l'ordre et le nombre de paramètres de messages à transmettre. Les paramètres sont transmis par valeur. |
KNOWLEDGEBASE PostMsg; ROUTINES PROCEDURE PostMessageExample; PRIVATE CONSTANTS menuList IS { 'Options', 'Post message', 'Exit' }: LIST OF STRING; ROUTINES EVENT PostMessageEvent( REF whdlTarget: WINDOW ) IS VARIABLES i: INTEGER; ACTIONS WHEN $Event IS $MsgCreate THEN WinSetMenuBar( $Handle, menuList ); ELSWHEN $MsgMenu THEN WHEN $MenuSelection IS 101 THEN FOR i := 1 TO 5 DO WinWriteLN( $Handle, 'Posting message #' & i ); PostMessage( whdlTarget, $MsgUser + i ); END; WinWriteLN( $Handle ); WinWriteLN( $Handle, 'Wait in for 5 seconds' ); WinWriteLN( $Handle ); SysDelay( 5000 ); ELSWHEN 102 THEN SendMessage( $Handle, $MsgClose ); SendMessage( whdlTarget, $MsgClose ); END; ELSE IF $Event = $MsgUser THEN WinWriteLN( $Handle, 'Received target window handle' ); whdlTarget := $EventParm( 1, WINDOW ); ELSIF $Event > $MsgUser THEN WinWriteLN( $Handle, 'Received message #' & $Event - $MsgUser ); END; END; NOTHING; END; PROCEDURE PostMessageExample IS VARIABLES whdl1: WINDOW; whdl2: WINDOW; ACTIONS WinCreateScrollWindow( $Desktop, whdl1, PostMessageEvent{whdl1 }, 0, 0, 40, 25, 'Post message Window 1', $TimesRoman, 14, BitOr($WinBorder, $WinTitle, $WinMenu, $WinAutoPos ) ); WinCreateScrollWindow( $Desktop, whdl2, PostMessageEvent{ whdl2 }, 0, 0, 40, 25, 'Post message Window 1', $TimesRoman, 14, BitOr($WinBorder, $WinTitle, $WinMenu, $WinVScroll, $WinAutoPos ) ); PostMessage( whdl1, $MsgUser, whdl2 ); PostMessage( whdl2, $MsgUser, whdl1 ); WinWait( whdl1 ); END;
Code retour | Description |
>0 | Opération exécutée avec succès. |
0 | L'envoi du message a échoué. |
-1 | Le descripteur de fenêtre ne fait pas référence à une fenêtre valide. La fenêtre n'existe peut-être plus ou ne prend pas en charge la commande |
-2 | Valeur inconnue |
-9 | Syntaxe erronée |
-11 | Valeur hors de la plage admise |
Envoie un message vers une fenêtre ou une boîte de dialogue.
SendMessage( VAL whdl: WINDOW, VAL message: INTEGER, [ VAL or REF messageParm: ANY ... ] ): INTEGER;
Nom de l'argument | Description |
whdl | Descripteur d'un élément qui gère les événements, comme une fenêtre. |
Message | Message à envoyer. |
messageParm | Plusieurs expressions de différents types. Le gestionnaire d'événements récepteur peut accéder à ces expressions via la valeur $EventParm. |
TSD Script dispose d'une puissante architecture pour transmettre les messages. Les destinataires les plus courants des messages sont les gestionnaires d'événements associés à des fenêtres et des boîtes de dialogue.
SendMessage peut créer un événement dans un gestionnaire d'événements selon le descripteur de l'élément, (par exemple, un descripteur de fenêtre) utilisé par le gestionnaire. Le second argument de SendMessage est mappé vers le paramètre $Event du gestionnaire d'événements. Les paramètres suivants sont également mappés vers les paramètres de l'événement dans le gestionnaire.
Le gestionnaire d'événements accède à ses arguments en appelant $EventParm et fournit le numéro de l'argument (de 1 à n), ainsi que le type de données de l'argument. Si une valeur affectable (une variable par exemple), est transmise par l'expéditeur, elle est automatiquement transmise par référence. Sinon, elle est transmise par valeur. SendMessage fonctionne comme un appel de fonction étant donné que le contrôle n'est pas retourné à l'instruction qui suit l'appel SendMessage, jusqu'à ce que le gestionnaire d'événements ait traité le message et l'ait retourné.
La routine d'appel s'interrompt jusqu'à ce que le gestionnaire est retourné la valeur. Cette valeur est celle qui est retournée par SendMessage.
GLOBALS.KB ---------- CONSTANTS ADD_WINDOW_TO_LIST IS $MsgUser+1; REMOVE_WINDOW_FROM_LIST IS $MsgUser+2; VARIABLES mainWindow: WINDOW; SENDER.KB --------- USES Globals; ROUTINES EVENT MyEvent(REF r: MyRecord); ACTIONS WHEN $Event IS $MsgCreate THEN SendMessage(mainWindow,ADD_WINDOW_TO_LIST, $Handle); ELSWHEN $MsgDestroy THEN SendMessage(mainWindow, REMOVE_WINDOW_FROM_LIST,$Handle); ... MAIN.KB ------- USES Globals; TYPES MainRecord IS RECORD ... openList: LIST OF WINDOW; END; ROUTINES EVENT MainEvent(REF r: MainRecord); ACTIONS WHEN $Event IS ... ... ELSWHEN ADD_WINDOW_TO_LIST THEN ListInsert(r.openList,$EventParm(1,Window)); ELSWHEN REMOVE_WINDOW_FROM_LIST THEN ListDelete(r.openList,$EventParm(1,Window));
Code retour | Description |
Le gestionnaire d'événements a retourné la valeur | Cette valeur est celle qui est retournée par SendMessage. |
-1 | Le descripteur de fenêtre ne fait pas référence à une fenêtre valide. La fenêtre n'existe peut-être plus ou ne prend pas en charge la commande |
-2 | Valeur inconnue |
-9 | Syntaxe erronée |
-11 | Valeur hors de la plage admise |
Pour plus d'informations sur les gestionnaires d'événements, reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit TSD Script - Guide de programmation.
Tivoli Service Desk 6.0 Developer's Toolkit Script - Manuel de référence du langage TSD Script