Les documents XML

La magie réside dans XML. Le XMLSERVICE prend un document XML qui contient des commandes, des définitions de programmes, et des paramètres, et renvoie un document XML avec la sortie.

Le format des documents XML est très souple. Vous pouvez même ajouter des étiquettes et des labels à votre document XML pour faciliter l’analyse des résultats. Mais la syntaxe XMLSERVICE contient quelques mots réservés dont vous aurez besoin.

<cmd … </cmd>. L’étiquette cmd sert à émettre des commandes de ligne de commande via XMLSERVICE. Son utilisation est très simple. Placez simplement ce que vous taperiez sur une ligne de commande entre les étiquettes, et XMLSERVICE l’exécutera.

<sh> … </sh>. L’étiquette sh est l’équivalent PASE de l’étiquette cmd. Tout ce qui est inséré entre ces étiquettes sera exécuté comme si vous l’aviez entré sur la ligne de commande dans PASE (QP2TERM).

<pgm> … </pgm>. L’étiquette pgm vous permet de spécifier un programme ou une sous- procédure IBM i que vous souhaitez exécuter. Le nom du programme, la bibliothèque et le nom de la sous-procédure sont définis à l’aide des attributs name, lib, et func dans l’étiquette pgm. Entre les étiquettes, les paramètres et les valeurs de renvoi pour le programme sont définis. C’est l’équivalent du prototype dans vos programmes RPG.

Voici les étiquettes nécessaires pour le prototype :

<parm> … </parm>. L’étiquette parm identifie un paramètre de programmes. Elle ne demande pas d’attributs, mais vous pouvez spécifier le type de paramètre avec les attributs io et by. l’attribut io peut être réglé sur “in”, “out”, ou “both”, tandis que by peut être réglé sur “val” ou “ref ” pour indiquer le passage par valeur ou référence. À l’intérieur de l’étiquette parm, les paramètres sont définis à l’aide des étiquettes suivantes, selon les besoins.

<ds> … </ds>. L’étiquette ds indique que le paramètre est une structure de données. Elle ne demande pas d’attributs. Si le paramètre est une matrice de structure de données, les attributs dim et dou facultatifs sont utilisés. L’attribut dim définit le nombre maximum de  structures de données dans la matrice. L’attribut do ou “do until” sert à déterminer le nombre d’éléments de matrice réellement peuplés. L’étiquette ds contiendra des définitions de données ou d’autres étiquettes ds pour définir ses éléments.

<data> … </data>. L’étiquette data sert à définir le paramètre et à le peupler. L’attribut type est nécessaire et sert à définir le type de données et la taille du paramètre. Si le paramètre est un champ caractère, l’attribut facultatif varying peut être utilisé pour indiquer un champ caractère de longueur variable. L’attribut varying peut être réglé sur “on” ou “off.” Le tableau suivant indique les valeurs de type de données possibles.

Valeurs des types de données possibles.

<return> … </return>. l’étiquette return sert à identifier une valeur de renvoi, comme une valeur de renvoi sur une sous-procédure. Elle n’a pas d’attributs. La valeur de renvoi est définie à l’aide des étiquettes data et ds, exactement comme un paramètre.

Les différentes étiquettes peuvent être combinées dans une liste d’actions afin de construire un script de ce que XMLSERVICE doit faire.

Vous pouvez placer dans le script des commandes IBM i à exécuter avant votre appel de programme, ou chaîner de multiples appels de programme pour produire les résultats désirés. Supposons que j’aie une routine de tarification nommée GET_PRICE dans un programme de service appelé ITEMSRV. Cette procédure prend le numéro d’article, le nom de client et un indicateur « mark down », et renvoie le prix de vente.

Bien entendu, les procédures de tarification sont en réalité plus complexes que cela, mais nous les voulons simples pour notre exemple. Le prototype de la sous procédure se trouve dans la figure ci-dessous.

(((IMG6955)))
Prototype pour la sous-procédure.

Nous disposons maintenant de toute l’information nécessaire pour construire notre document XML à envoyer à XMLSERVICE, comme le montre cette figure :

(((IMG6956)))

Le document commence avec la version XML. Celle-ci sera incluse dans tout document XML que vous enverrez à XMLSERVICE. L’étiquette suivante, mult, m’indique simplement que je suis en train d’exécuter de multiples commandes ou programmes avec ce document.

A l’intérieur de l’étiquette mult, je commence avec une commande pour ajouter une bibliothèque à ma liste de bibliothèques. J’ai choisi cela comme exemple de quelque chose que vous feriez couramment avec XMLSERVICE. L’étiquette <cmd> contient ma commande exactement comme vous l’entreriez sur une ligne de commande. Ensuite, j’ajoute mon appel à ma procédure Get_Price.

Vous observerez que sur l’étiquette <pgm>, j’ai identifié le nom du programme de service, la bibliothèque, et le nom de la procédure. À l’intérieur de l’étiquette <pgm>, je commence par définir mes paramètres et la valeur de renvoi.

Vous pouvez voir que sur chaque étiquette <data>, j’ai inclus un attribut var et donné un nom au paramètre. XMLSERVICE n’utilise pas cette information, mais elle pourra s’avérer très utile lors de l’analyse de votre document XML renvoyé car elle sera incluse dans la sortie XML.

Notez aussi que j’ai inclus mes valeurs de paramètres sur chaque étiquette <data>. Quand vous utilisez cela en production, vous peuplerez les paramètres en construisant le document XML pour votre appel. C’est tout ce qu’il me faut pour mon document XML. Cela me semble simple et facile à comprendre.

Si je fais mon appel en utilisant le document XML ci-dessus, à quoi ressemble mon document XML renvoyé ? Et bien il ressemblera beaucoup au code suivant :

(((IMG6957)))

On voit que le document XML renvoyé est presque identique au document XML utilisé pour l’entrée. C’est parce que XMLSERVICE se déplace simplement dans votre document XML, un élément à la fois, et le traite. Toute donnée changée est reflétée dans les étiquettes <data>. Dans notre cas, nous avons commencé avec une commande pour ajouter une liste de bibliothèques. Vous remarquerez que la commande que nous avions dans l’étiquette <cmd> a été remplacée par un message de réussite. Notre appel de programme et ses paramètres sont tous restés inchangés car notre procédure ne les modifie pas. Si les paramètres avaient été modifiés, les changements se refléteraient sur l’étiquette <data> du paramètre.

Notre procédure a renvoyé le prix comme une valeur de renvoi, et donc notre étiquette <return> contient maintenant le prix dans son étiquette <data>. À présent nous utilisons la méthode que nous préférons pour analyser le document XML dans le langage de notre choix. La plupart des langages ont des possibilités d’analyse XML élémentaires qui devraient pouvoir traiter facilement ces documents Simple XML.