Copie de Services Diva et Web

Les services Diva

Présentation des services

Définition
Un service Diva est un programme (écrit en Diva) qui s'exécute automatiquement lors du démarrage de l'ordinateur.
Les services Diva sont exécutés même si aucune session n'est ouverte sur le poste de travail.
Le comportement d'un service Diva est donc similaire à celui d'un service Windows.
Méthode
Pour créer des services Diva vous devez simplement :

• Ecrire un programme Diva.

• Ajouter une ligne dans le fichier paramètre dhsServices.txt pour demander le lancement de ce programme au démarrage de l'ordinateur.

Les services Diva sont lancés par le service « Divalto Services Diva ». Ce dernier est un service lancé par le système d'exploitation qui lit le fichier paramètre dhsServices.txt et qui lance les services Diva.
Interaction avec le bureau
En règle générale, un service est un programme qui tourne en tâche de fond sans interaction avec le bureau, c'est à dire qu'il n'effectue ni affichage, ni aucun dialogue avec l'utilisateur. Nous verrons qu'un service Diva peut tout de même ouvrir une fenêtre à partir du moment où une session utilisateur est ouverte sur le poste de travail.
Remarque : L'utilitaire Xtask.dhop permet de lancer un service Diva manuellement.

Fichier paramètre dhsServices.txt

Localisation du fichier
Le fichier paramètre dhsServices.txt doit se trouver dans le répertoire d'installation d'Harmony (/Divalto/Sys). S'il n'existe pas, vous pouvez le créer avec un éditeur de textes.
Le choix « Services Diva » du menu Harmony.dhop permet d'éditer ce fichier.
Format du fichier
Chaque service diva est décrit sur une et une seule ligne du fichier.
Les différents paramètres de la ligne respectent la syntaxe HMP, à savoir :

• un nom de paramètre entre < et >

• suivi de la valeur du paramètre.

Cette ligne est intégralement transmise au programme Diva qui est lancé. Elle pourra donc comporter des paramètres personnels.
Commentaires
Si le premier caractère significatif d'une ligne est le point-virgule, la ligne est considérée comme étant du commentaire.
Paramètres standard

Paramètres spécifiques
Vous pouvez ajouter d'autres paramètres à la ligne de commande. Votre programme peut récupérer l'intégralité de la ligne et ensuite extraire les paramètres par les fonctions HmpRead et HmpSeek.
Voir Programmation d'un service Diva

Exemple de fichier dhsServices.txt
; ceci est du commentaire
<nom>xbal<programme>xbal.dhop<tache>17-999<utilisateur>DEMO
<nom>monservice<programme>monprog.dhop<tache>17-999<utilisateur>MOI<fichieratraiter>fic.dhfi
La première ligne correspond au lancement du service Xbal d'Interlogiciel..
La seconde ligne lance un service Diva spécifique. Remarquez le paramètre <fichieratraiter> qui n'est pas un paramètre standard des services. Ce paramètre pourra être lu dans le programme Diva.
Voir également :
Programmation d'un service Diva
Rubrique "Harmony Markup Parameters HMP" de la documentation Xwin - Programmation.

Paramétrage du service "Divalto Services Diva"

Si vous désirez que l'un de vos services Diva puisse effectuer des affichages, vous devez paramétrer le service « Divalto Services Diva » pour autoriser l'interaction du service avec le bureau.
Dans le gestionnaire de services, sélectionnez la ligne « Divalto Services Diva », puis appelez les propriétés et cochez la case : Autoriser le service à interagir avec le bureau.
Si vous voulez que vos services s'exécutent avec un compte utilisateur Windows autre que le compte système, spécifiez le compte et le mot de passe depuis les gestionnaire des services. Pour le service Xbal, il est indispensable que le service soit lancé depuis un compte Windows standard, afin que le profil de messagerie soit défini.
Dans le cas où un compte spécifique est utilisé, le service ne pourra pas interagir avec le bureau.
Remarques

• Lorsque le service « Divalto Services Diva » est autorisé a interagir avec le bureau, votre service Diva peut effectuer des affichages, voir même des entrées clavier. Pour que la fenêtre soit visible il faut impérativement que le paramètre <windowShow> ne soit pas positionné à SW_HIDE.

• Les fenêtres apparaissent uniquement lorsqu'une session est ouverte sur l'ordinateur. S'il n'y a pas de session ouverte, le programme se déroule normalement et les affichages seront effectués lors de l'ouverture de la session.

• Si un service Diva tente de faire une entrée clavier (saisie de masque par exemple) alors que la fenêtre est cachée (SW_HIDE) ou que l'interaction avec le bureau n'est pas possible, le programme est arrêté. Un message est écrit dans le journal des événements et dans le journal Ferror.log.

• En cas d'erreur de lancement d'un service consultez le journal des événements de Windows et le fichier journal d'Harmony.

Programmation d'un service Diva

Un service Diva est un programme Diva ordinaire.
Il ne doit pas effectuer de saisie (sauf éventuellement en phase de mise au point).
Par contre, il peut afficher des messages (par l'instruction Display) pour indiquer les travaux qu'il est en train d'effectuer.
Récupération des paramètres
L'intégralité de la ligne paramètre du fichier dhsServices.txt est transmise au programme par la variable d'environnement HARMONYSERVICEPARAMETRES.
Pour la lire vous devez utiliser la fonction GetEnv.
Exemple :
1 param 512
param = GetEnv("HARMONYSERVICEPARAMETRES")
Vous pouvez ensuite extraire les différents paramètres par les instructions HmpSeek et HmpRead.
ProgramCall
Un service Diva peut exécuter des instructions ProgramCall. Les programmes sont lancés avec le même mode d'affichage (caché, visible etc…) que le programme courant. Les programmes lancés peuvent également accéder à la variable d'environnement HARMONYSERVICEPARAMETRES.

Voir également :
Rubrique "Harmony Markup Parameters HMP" de la documentation Xwin - Programmation.
Rubrique "GetEnv" de la documentation Xwin - Programmation.
Rubrique "ProgramCall" de la documentation Xwin - Programmation.

ServiceMode

La fonction Diva ServiceMode permet à un programme de savoir s'il a été lancé comme un service ou comme une tâche ordinaire.
La fonction ServiceMode renvoie une des valeurs suivantes :

XBal : Service de boite aux lettres

Présentation de Xbal

Le service XBAL lit la boîte aux lettres locale par MAPI et lance des programmes de traitement des messages reçus.
Le traitement à effectuer est codifié dans l'objet du message. L'objet du message est écrit en HMP dans lequel le paramètre <ACTION> définit le traitement à effectuer. Le traitement à effectuer fait référence à un fichier d'actions (XBALF.dhfi) qui contient le nom d'un programme Diva à exécuter.
Le programme de traitement de l'action est lancé par la fonction ProgramCall. XBAL lui envoie les paramètres du message à traiter par le tunnel.
Attention : pour que Xbal fonctionne avec Outlook, il faut que ce dernier soit correctement paramétré. Voir Paramétrage de Outlook .
Voir également :
Rubrique "Harmony Markup Parameters HMP" de la documentation Xwin - Programmation.
Rubrique "Tunnels" de la documentation Xwin - Programmation.
Rubrique "ProgramCall" de la documentation Xwin - Programmation.

Paramètres du service Xbal

XBAL est lancé comme un service par « Divalto Services Diva » (Voir le paramétrage des services Diva). En plus des paramètres généraux valables pour tous les services, les paramètres spécifiques de XBAL du fichier paramètres des services dhsServices.txt sont les suivants :

Exemple :
<nom>xbal<programme>xbal.dhop<tache>17-999<windowshow>SW_HIDE<utilisateur>BAL<profil>monprofil<pw>monmotdepasse<log> <attente>120
Remarque : Le service XBAL ne fonctionne pas si son fichier Xlogf.dhfi se trouve sur un serveur Xlan sécurisé. Voir Paramétrage des utilisateurs réseau

Voir également :
Rubrique "Harmony Markup Parameters HMP" de la documentation Xwin - Programmation.
Les services Diva

Algorithme général de XBAL

XBAL lit la boîte de réception des messages. Il ne traite que les messages non lus. Il récupère l'objet du message qui doit contenir une chaîne de commande de type HMP.
Le paramètre <Action> permet de préciser l'action à exécuter pour ce message. Il fait référence à une action décrite dans le fichier paramètres des actions (xbalf.dhfi). Ce fichier contient pour chaque action :

• Un commentaire décrivant l'action.

• Un indicateur de validité de l'action. Celui-ci permet de suspendre provisoirement l'exécution d'une action. En cas de problème lors de l'exécution d'une action le programme XBAL invalide l'action en positionnant cet indicateur qui devra ensuite être repositionné manuellement.

• Le nom du programme Diva qui traite le message.

• Le code utilisateur sous lequel le programme Diva doit s'exécuter.

• Les paramètres de l'action sous forme de chaîne de commande HMP.

Lorsque XBAL lit un message dont l'objet contient le paramètre <Action>, il effectue les opérations suivantes.

• Recherche de l'action dans le fichier des actions. Si l'action n'est pas active, le message n'est pas traité.

• Chargement des droits et des chemins implicites de l'utilisateur lié à l'action. S'il n'est pas renseigné, le programme s'exécute avec le code utilisateur du service XBAL. En cas d'erreur lors du changement de code utilisateur, l'action est désactivée.

• Envoi par le tunnel des paramètres du message.

• Exécution du traitement par la fonction "ProgramCall".

• XBAL attend l'acquittement du traitement par la fonction "PongReceive" de "Xbal_Status". Quatre cas sont pris en compte :

• • Xbal reçoit un acquittement positif (valeur 0). Le message est supprimé.

  • Xbal reçoit un acquittement négatif grave (valeur 1). L'action est invalidée.

  • Xbal reçoit un acquittement négatif (valeur 2). Le message est transféré dans le dossier des messages en erreur ou est marqué comme étant lu.

  • Xbal ne reçoit pas d'acquittement. L'action est invalidée.

Lorsque tous les messages de la boîte de réception sont traités, XBAL s'endort, soit jusqu'à l'arrivée d'un nouveau message avec l'interface Extended MAPI ou pendant une minute (par défaut voir le paramètre Attente) avec l'interface Simple MAPI avant de consulter à nouveau la boîte de réception.
Remarques :

• En cas d'erreur de traitement d'un message, XBAL le transfère dans le dossier des messages en erreur. Pour que ces messages soient à nouveau traités, la cause de l'erreur doit être corrigée par un opérateur, puis ces messages doivent être transférés à nouveau dans la boîte de réception et marqués comme étant non lus.

• XBAL ne traite que les messages "Non lus". Dans certains cas d'erreur de traitement, lorsque l'interface MAPI ne permet pas le transfert dans un autre dossier, XBAL marque le message comme étant lu. Il ne sera plus donc plus traité par XBAL à moins d'être remis dans l'état "non lu" dans la boîte de réception par un opérateur après correction de la cause de l'erreur consignée dans le journal des erreurs.

• Lorsque le paramètre général <log> est actif, XBAL consigne les erreurs dans un journal.

• Lorsque le paramètre général <logMessage> est actif, XBAL consigne une trace des messages traités avec succès dans le journal des messages.

Voir également :
Rubrique "Tunnels" de la documentation Xwin - Programmation.
Rubrique "PingReceive - PongReceive - PingLocalReceive" de la documentation Xwin - Programmation.
Services Diva

Paramètres du traitement des messages

XBAL envoie les paramètres du message à traiter à travers le tunnel. Le programme de traitement les récupère par la fonction PingReceive.

Traitement des pièces jointes
Les pièces jointes sont stockées dans des fichiers temporaires. Le programme de traitement des messages doit supprimer ces fichiers avec la fonction WinDeleteFile.
Valeurs de retour du programme de traitement
Le programme de traitement, s'il est appelé en mode synchrone, doit acquitter le message par la fonction Pong avec le paramètre "Xbal_Status" et les valeurs suivantes :

Voir également :
Rubrique "Tunnels" de la documentation Xwin - Programmation.
Rubrique "PingReceive - PongReceive - PingLocalReceive" de la documentation Xwin - Programmation.

Le paramétrage de XBAL

Le fichier paramètres des actions traitées par XBAL est géré par le choix "Actions des services" du menu Harmony.dhop. Il s'agit d'un zoom sur le fichier XBALF.dhfi.
Chaque action est identifiée par un nom d'action et contient les informations suivantes :

• Un commentaire décrivant l'action.

• Un indicateur de validité de l'action. Celui-ci permet de suspendre provisoirement l'exécution d'une action. En cas de problème lors de l'exécution d'une action le programme XBAL invalide l'action en positionnant cet indicateur.

• Pour les services web : un indicateur permettant de garder le programme XwebServices en résident. (voir Services Web résidents)

• Le nom du programme Diva qui traite le message.

• Le code utilisateur sous lequel le programme doit s'exécuter.

• Les paramètres de l'action sous forme de chaîne de commande HMP.

Paramétrage de Outlook

Xbal accède à la messagerie par l'interface MAPI. Pour que la lecture des messages soit accessible sans que le logiciel Outlook ne soit ouvert dans une session, Outlook 98 et Outlook 2000 doivent être configurés pour le service «Société ou Groupe de travail». Pour vérifier la configuration, il faut cliquer sur l'élément de menu «Aide» d'Outlook, puis sélectionner «À propos de Microsoft Outlook», la mention "Société ou groupe de travail" doit apparaître.
Si cette option n'est pas active, il faut modifier la configuration d'Outlook 98. Pour cela, il faut relancer l'installation d'Outlook 98 en exécutant «Ajouter/supprimer les programmes» dans le Panneau de configuration. Sélectionnez «Outlook 98» puis cliquez sur «Ajout/suppression de programmes». Dans la boîte de dialogue «Options du service de messagerie» il faut choisir «Société ou groupe de travail».
Pour Outlook 2000, dans le choix «Outils» du menu, il faut sélectionner «Options», choisir l'onglet «Remise du courrier» puis cliquer sur le bouton «Reconfigurez la remise du courrier…» et enfin sélectionner l'option «Société ou groupe de travail».
Outlook 97 et Outlook 2002 n'intègrent pas le concept du service «Société ou Groupe de travail».
Pour une utilisation avec Outlook Express, il faut impérativement ouvrir une session et charger le logiciel.

Exemple de programme de traitement

;___________________________________________________________________________
;Description : Programme de traitement de message pour l'action "MonAction"
;___________________________________________________________________________
1 MessageObjet 255 ;Objet du message
1 MessageDate 10 ;Date d'émission
1 MessageEmetteurLong 256 ;Emetteur Nom Long
1 MessageTexte 32000 ;Texte du message
1 MessageNbPieces 5,0 ;Nbre de pièces jointes
1 MessageNomFic 256*10 ;Noms des fichiers joints
1 Param 256
1 i x
1 Status 1,0

main
; récupération des paramètres
pingReceive("Xbal_Objet" ,MessageObjet)
pingReceive("Xbal_Date" ,MessageDate)
pingReceive("Xbal_Emetteur" ,MessageEmetteurLong)
pingReceive("Xbal_Message" ,MessageTexte)
pingReceive("Xbal_Param" ,Param)
pingReceive("Xbal_Nbre" ,MessageNbPieces)
MessageNbPieces = Min(MessageNbPieces,Index(MessageNomFic(),1))
for i = 1 to MessageNbPieces
pingReceive("Xbal_Fichier" & nospaces(tostring),MessageNomFic)
next
...
...
; suppression des fichiers temporaires de pièces jointes
for i = 1 to MessageNbPieces
Windeletefile(Left(MessageNomFic))
next
; Acquittement du message
; status = 0 c'est ok le message a été traité. Il sera supprimé.
; status = 1 il y a un pb grave, l'action est invalidée. Les pièces jointes sont supprimées
; status = 2 il y a un problème, le message est marqué lu. Les pièces jointes sont supprimées
pong("Xbal_Status",Status)
ProgramExit

Voir également :
Rubrique "Harmony Markup Parameters HMP" de la documentation Xwin - Programmation.
Rubrique "Tunnels" de la documentation Xwin - Programmation.
Rubrique "PingReceive - PongReceive - PingLocalReceive" de la documentation Xwin - Programmation.

Services Web

Service

Définition
Un service Web est un composant applicatif accessible sur le Web par une interface standard en utilisant des protocoles de communication basés sur le XML indépendamment du système d'exploitation et des langages de programmation utilisés.
Le service Web met à disposition des fonctions (méthodes) sur un serveur HTTP.
Le client du service Web peut invoquer la méthode du serveur aussi simplement que s'il s'agissait d'une fonction locale. Il faut spécifier l'URL du service Web auquel on désire accéder, ainsi que les paramètres d'entrée de la méthode.
WebServiceDIva
WebServiceDiva est une méthode générique permettant d'exécuter une action sur le serveur Web. L'action correspond à un programme Diva. Celui-ci récupère les paramètres (généralement une chaîne <hmp>), effectue le traitement et renvoie un résultat.
Le service est exécuté par le serveur HTTP IIS de Microsoft.

Architecture

WebServiceDiva

WebServiceDiva est un service Web générique qui sert à lancer tous les services Web Diva. La page générique WebserviceDiva.asmx est hébergée sur le serveur IIS de Microsoft. Elle contient la méthode WebServiceDiva qui permet d'exécuter un programme Diva sur le serveur en lui passant des paramètres
Int WebServiceDiva(string action,string param,out string retour)

• Action : une chaîne au format <HMP>,

• Param : généralement une chaîne au format <HMP>

• Retour : généralement une chaîne au format <HMP>

Il peut être appelé depuis un programme Diva et depuis n'importe quelle autre application cliente de services Web.
Il exécute le programme XWebServices.dhop
Remarque :
Pour l'appel d'un service Web Diva depuis un programme Diva il faut utiliser la fonction WebServiceDivaExecute.

XwebServices

Le programme XwebServices.dhop est exécuté à chaque invocation d'un service Web Diva. C'est lui qui lance le programme Diva correspondant à l'action demandée.
Le programme de traitement de l'action est lancé par la fonction ProgramGoto. XwebServices.dhop lui envoie les paramètres par le tunnel.
Actions des services Web
Le paramètre <Action> permet de préciser l'action à exécuter pour ce message. Ce paramètre est obligatoirement une chaîne HMP dans laquelle le paramètre <ACTION> définit le traitement à effectuer. Il fait référence à une action décrite dans le fichier paramètres des actions. Ce fichier contient pour chaque action :

• Un commentaire décrivant l'action.

• Un indicateur de validité de l'action. Celui-ci permet de d'interdire provisoirement l'exécution d'une action.

• Un indicateur permettant de garder le programme XwebServices en résident. (voir Services Web résidents)

• Le nom du programme Diva qui traite l'action.

• Le code utilisateur sous lequel le programme Diva doit s'exécuter.

• Des paramètres complémentaires de l'action sous forme de chaîne de commandes HMP.

Algorithme général de XwebServices.dhop
Lorsque XwebServices.dhop est invoqué, il effectue les opérations suivantes.

• Recherche de l'action dans le fichier des actions. Si l'action est absente ou bien n'est pas active, il renvoie un code d'erreur avec un message dans le paramètre de retour.

• Chargement des droits et des chemins implicites de l'utilisateur lié à l'action. S'il n'est pas renseigné, le programme s'exécute avec le code utilisateur $WEBSERVICE.

• Envoi des paramètres du service Web, ainsi que des paramètres complémentaires en provenance du fichier des actions au programme Diva par le tunnel.

• Exécution du traitement

• • par l'instruction "ProgramGoto" si l'action est paramétrée comme résidente.

  • par la fonction "ProgramCall" avec attente de la fin du traitement si l'action n'est pas paramétrée comme résidente..

• Si le traitement est appelé par ProgramCall

• • Attente de l'acquittement du traitement par la fonction "PongReceive" de "WebServiceStatus". En cas d'absence d'acquittement renvoi d'un code d'erreur.

  • Réception de la réponse et éventuellement d'un numéro de version du service Diva

  • Journalisation de l'exécution de l'action dans le fichier XwebServices.log avec la date, l'heure ainsi que la durée d'exécution de l'action.

• Si le traitement est appelé par ProgramGoto,

• • c'est à ce dernier de renvoyer la réponse en utilisant la fonction WebServiceReturn.

Remarques :

• L'action « ping » permet de tester les services Web sans avoir à écrire de programme Diva. Elle est directement traitée par le programme XwebServices.dhop. Pour cela elle doit être créée et activée dans le fichier paramètre des actions. XwebServices renvoie un status à 0 et dans le paramètre de retour sa version ainsi que le nom du serveur sur lequel il s'exécute.

• La durée de l'exécution de l'action doit être relativement courte. Le client attend la réponse en temps réel. Si le traitement est trop long, la liaison avec le client risque d'être interrompue.

• Le service Web Diva est un programme qui n'effectue pas d'affichage.

• Si le paramètre Résidente de l'action n'est pas cochée, l'appel du programme se fait par un ProgramCall ce qui est nettement plus coûteux en temps.

Voir également :
Rubrique "Harmony Markup Parameters HMP" de la documentation Xwin - Programmation.
Rubrique "Tunnels" de la documentation Xwin - Programmation.
Rubrique "ProgramCall" de la documentation Xwin - Programmation.

Service Web Diva

Le service Web Diva est le programme chargé d'exécuter l'action demandée par le client du service Web.
Il récupère dans le tunnel par la fonction PingReceive les paramètres suivants :

Si l'action est paramétrée résidente
Il traite l'action et renvoie le résultat par la fonction WebServiceReturn.
Il enchaîne au programme XwebServices.dhop par l'instruction ProgramGoto
Si l'action n'est pas paramétrée résidente :
Il traite l'action puis renvoie les résultats dans le tunnel par la fonction Pong

Puis il se termine par l'instruction ProgramExit.
Remarques :

• Pour stocker les paramètres de type <hmp>, on utilisera de préférence une donnée de type 'S' dont la taille s'adapte automatiquement au contenu.

• La fonction ServiceMode renvoie la valeur 3 si le programme est invoqué par un service Web.

Services Web résidents

Principe
A partir de la version 6.3a d'Harmony, le système gère un pool de tâches pour l'exécution des services web. Ce pool permet de garder des tâches Harmony en attente et ainsi de réduire considérablement le temps d'exécution d'une requête.
Lors du premier appel à un service web, le programme XwebServices.dhop est chargé. Une fois le traitement de l'action effectué, le contrôle est rendu au programme XwebServices.dhop (par l'instruction ProgramGoto). Ce dernier se met alors en attente d'un appel de service web.
Lors de l'appel suivant à un service web, s'il existe une tâche disponible dans le pool, celle-ci est immédiatement activée.
Mise en oeuvre

• Paramètre des actions

La case Résidente de l'action doit être cochée. Voir le fichier paramètres des actions.

• Fin du programme qui traite l'action.

Le programme qui traite l'action doit renvoyer le résultat, éventuellement écrire dans le fichier journal, puis enchaîner au programme XwebServices.dhop.
Pour assurer la compatibilité avec l'ancien mode de fonctionnement il est conseillé d'écrire le code de la manière suivante (les lignes en gras sont celles qui doivent être ajoutées pour les services web écrits dans les versions antérieures à la version 6.2) :
if IsProgramCalled = FALSE ; l'action est paramétrée Résidente
WebServiceReturn(resultat,0) ;
ProgramGoto("xwebservices.dhop")
endif
Pong("WebServiceStatus",0) ; l'action n'est pas résidente
Pong("WebServiceResult",resultat)
Pong("WebServiceVersion",MaVersion)
programexit
Paramétrage de la taille du pool des services web
Par défaut, le système garde 10 tâches dans le pool.
Pour changer cette valeur, ajoutez, dans le chapitre System du fichier Divalto.Ini, la clé :
WebServicesSizePool=nombre_de_tâches
Attention, la modification doit être faite dans la base de registre globale à l'ordinateur.
Journalisation
Dans le mode non résident, Xwebservices.dhop écrit dans le journal après chaque action, la date et l'heure d'exécution de l'action, ainsi que sa durée.
Dans le mode résident, Xwebservices.dhop ne récupère plus la main après l'exécution de l'action (en effet, dans ce mode, celle-ci est exécutée par un programGoto et non plus un programCall). Il convient donc au programme qui gère l'action de journaliser lui-même s'il le désire.
Pour cela :
Il devra déclarer le module XwebServices.Dhop et faire appel à la fonction de journalisation WriteLogFile
Exemple
Module "Xwebservice.dhop"
TempsTic = wingetTickCount - T0 ;T0 est initialisé au début du main t0 = winGetTickCount
Temps = TempsTic/1000
WriteLogFile(0,"Exécution de l'action Mon Action v1.1 en " & nospaces(temps) & " secondes")

Exemple de service Web Diva

;____________________________________________________________________
;Description :
; Service Web pour quantité en stock pour une référence article
;____________________________________________________________________
define MaVersion = "6.1 "
module "pmstock.dhop"
1 ParamEntree S
1 dos 3,0
1 ref 25
1 stock 12,D2
main
; récupération des paramètres d'entrée
PingReceive("WebServiceParameters",ParamEntree)
Dos = hmpseek(ParamEntree,"dos",998) ; Dossier par défaut 998
Ref = hmpseek(ParamEntree,"reference","")
; calcul du stock
stock = interro_stock(dos,ref)
; réponse
if IsProgramCalled = FALSE ; l'action est paramétrée Résidente
WebServiceReturn(stock,0)
ProgramGoto("xwebservices.dhop")
endif
Pong("WebServiceStatus",0) ; l'action n'est pas résidente
Pong("WebServiceResult",stock)
Pong("WebServiceVersion",MaVersion)
programexit

Installation du serveur Web

Les services Web Diva s'appuient sur la technologie .NET de Microsoft.
La mise en œuvre nécessite donc le serveur IIS (Internet Information Services) de Microsoft. Elle nécessite également l'installation du FrameWork .Net sur ce serveur.
Pour le détail de l'installation voir le chapitre « Installation Harmony Web » dans l'installation et paramétrage d'Harmony.

Client Diva d'un service Web Diva

La fonction WebServiceDivaExecute permet d'exécuter un service Web Diva.
Elle comporte 4 paramètres :

• L'URL de la page WebServiceDiva.asmx du serveur Web

• Le paramètre <action>

• Les paramètres d'entrée du service

• Le paramètre de retour renvoyé par l'action

Elle renvoie un compte-rendu :

• 0 si OK

• En cas d 'erreur, le paramètre retour contient habituellement un message d'erreur en clair.

Confidentialité
Les paramètres d'entrée et de retour peuvent être cryptés pour assurer la confidentialité des informations transmises.

Exemple de client Diva d'un service Web Diva

;____________________________________________________________________
;Description :
; Demande la quantité en stock pour une référence article à
; un service Web Diva
;____________________________________________________________________
1 Url S
1 St X
1 Retour S
1 Stock 12,D2
main
; Appel du service
Url = "http://www.divalto.fr/Ws/WebServiceDiva.asmx"
St = WebServiceDivaExecute(Url, \
"<action>Stock", \
"<dos>998<reference>ALB0001", \
Retour)
; en cas d'erreur Retour contient le message
if St
MessageBox(binhexa(stx(St)) & " " & Retour ," ")
else
Stock = Retour
endif
ProgramExit

Service dhsTelnet

Installation et paramétrage du service dhsTelnet

dhsTelnet est un service qui assure l'interface entre un (ou plusieurs) programme(s) Diva et un (ou plusieurs) client(s) Telnet (douchettes, écrans passifs, …). Il attend la connexion des clients et, pour chaque client qui se connecte, lance l'exécution d'un programme Diva. Ce dernier peut alors dialoguer avec le client Telnet via des commandes spécifiques d'entrée-sortie.
Installation
Pour installer le service dhsTelnet, lancez le programme diva InstallTelnet.dhop (qui se trouve dans Divalto/Sys).
Liste des fichiers livrés

Paramétrage
Au démarrage, le service dhsTelnet charge le fichier paramètres dhsTelnet.txt. Ce fichier doit préciser la liste des connexions Telnet à gérer, à raison d'un type de connexion par ligne.
Une ligne doit respecter la syntaxe suivante :
<port>numéro_de_port_à_écouter<prog>programme_à_lancer<user>code_utilisateur<env>environnement <show>visibilité<paramsytelnet>"<pc8>codage_pc8<timeout>valeur_du_timeout<crlf>crlf <fic>fichier_des_touches<debug>débogueur"<paramsharmony>"paramètre_à_transmettre"

Les valeurs par défaut sont paramétrées dans Divalto.ini, au chapitre [ytelnet].
Voir aussi la rubrique Gestion des licences nommées dans Telnet.

Exemples :
<port>2260<prog>PanneauAffichage.dhop<user>AFF
<port>2247<prog>demoxtelnet.dhop<user>DEMO<env>ERP210
<port>2248<prog>resultatbalance1.dhop<user>RB<paramsytelnet>"<pc8>1<timeout>0<crlf>1"
<port>2350<prog>resultatbalance2.dhop<user>RB<paramsytelnet>"<pc8>1<timeout>0<crlf>1"
<port>2247<prog>demo.dhop<user>DEMO<paramsytelnet>"<timeout>15"<paramsharmony>"<demo>1"
Remarque : le fichier dhsTelnet.txt livré contient une première ligne de commentaires rappelant la syntaxe d'une ligne de paramètres et une deuxième ligne d'exemple permettant de lancer le programme de démonstration DemoTelnet.dhop :
<port>2247<prog>demotelnet.dhop<user>DEMO

Gestion des licences nommées dans Telnet

Une application Telnet, s'exécutant sur un site pour lequel la gestion des licences nommées est active, doit être adaptée afin de prendre en compte cette nouvelle gestion. En effet, l'utilisateur de l'application Telnet doit s'authentifier avant de pouvoir exécuter l'application. Pour cela, les paramètres suivants doivent être spécifiés dans le fichier Dhstelnet.txt :

Programme Diva
Le programme Diva associé au port telnet peut récupérer les paramètres suivants :

• Le mode Login, renvoyé par la fonction GetEnv ("TELNET_LOGIN"). Vaudra 1 si la balise <Login> est active dans le fichier paramètre. Ceci permet de développer des programmes Telnet compatibles avec les deux modes de licences.

• Le compte de l'utilisateur est renvoyé par la fonction GetUserName. Il s'agit du compte de l'utilisateur Windows qui a effectué la connexion, soit en principe le compte de l'utilisateur Divalto, sauf si un alias est associé à ce compte.

• La variable System.User contient le code de l'utilisateur Divalto.

Programmation d'un serveur Telnet

Un exemple de programmation de serveur Telnet est livré avec Harmony (DemoTelnet.dhsp dans le sous-projet Xtelnet du projet Exemples).
Vous y trouverez la liste des commandes du module Ytelnet (commentaires en début de source).
Pour exécuter cette démonstration, lancez au préalable le fichier batch TestTelnet.bat, qui fait appel à l'émulateur Telnet de Windows sur le port 2247.
DemoTelnet propose un menu avec les choix suivants (utilisez les touches du clavier a, p, c, l, x, y pour changer les paramètres de fonctionnement de Ytelnet) :
a = codage ANSI ; p = codage PC8
x = vt220 (fichier des touches tvt220.txt) ; y = telnet (fichier des touches dhsTelnet.txt)
c = crlf ; l = cr seul
Remarque : le logiciel d'émulation de terminal utilisé pour la démonstration est livré et installé avec le système Windows mais il diffère suivant les versions (2000 ou XP). Celui de Windows 2000 ne renvoie que CR alors que celui de Windows XP renvoie CR+LF.
Attention : ce programme de démonstration est un exemple « général » qu'il faudra évidemment adapter au client(s) Telnet concerné(s).
Voir aussi la rubrique Gestion des licences nommées dans Telnet.