Options valides (le défaut est souligné)
| doc |
doc=string
doc=file |
string : la source est une variable contenant du XML
file : la source est dans un fichier de l'IFS |
| case |
case=lower
case=upper
case=any
case=convert |
lower : le flux XML est en minuscules
upper : le flux est en majuscules
any : le flux XML doit être converti avant d'être traité
convert: les caractères invalides (- par ex.) sont remplacés par _ (tiret bas)
|
| trim |
trim=all
trim=none
|
all : les espaces d'extrémité des chaînes sont enlevés
none : les espaces d'extrémité des chaînes sont conservés |
| allowmissing |
allowmissing=no
allowmissing=yes |
peut-il y avoir des sous-zones de DS en plus ? (c.a.d n'ayant pas d'équivalent en tant qu'élément XML ) |
| allowextra |
allowextra=no
allowextra=yes |
peut-il y avoir des éléments XML en trop ?
(c.a.d n'ayant pas d'équivalent en tant que sous zone de la DS ) |
| path |
path=/ |
Chemin de l'élément à extraire (par défaut la racine)
A utiliser si la DS ne se nomme par comme l'élément principal |
| datasubf |
|
permet de traiter un élément XML contenant des attributs ET une valeur
Par exemple
<cours nom="XML" module="PGM">
manipuler du XML en RPG
</cours>
datasubf=text, permet de placer "manipuler du XML en RPG" dans la zone nommée TEXT
|
| countprefix |
|
permet de recevoir le nombre d'élément extrait dans un compteur
Par exemple countprefix=nbr, si on parse un élément nommé cours et présent trois fois,
place la valeur 3 dans nbrcours |
| ns |
|
gestion des espaces de nommage (par exemple VNS:Cours pour "qualifier" cours)
ns=remove -> retrait de l'espace de nommage : on cherche une DS nommée COURS
ns=merge -> ajout de l'espace de nommage (avec _) on cherche une DS VNS_COURS |
| nsprefix |
|
récupération de l'espace de nommage
nsprefix=ns,
on cherche une variable nommée NS_COURS,
dans laquelle placer la chaîne "VNS" |
Quelques exemples de code
Debug
Utilisation de PATH
Éléments ET attributs, sont traités de la même manière
Debug
Imbrication (avec LIKEDS)
Debug
Éléments présents n fois (occurrences)
Définitions
Résultat
Si cours avait été défini DIM(10) , soit plus que le nombre d'occurrences réel, il fallait l'option allowmissing
XML stocké dans un fichier (doc=file)
Le fichier contient plus de 500 cours
==> allowextra
Pour traiter une nombre infini d'occurrences, il faut passer par un %handler()
Le principe est de définir comme réceptacle de la fonction xml-into, non pas une DS, mais une procédure (s/pgm ILE)
La procédure
•retourne
- -1 pour indiquer une fin anticipée
- 0 pour continuer
•reçoit
- une variable (type indifférent) de communication entre le pgm principal et la procédure (code retour, par exemple)
- une DS à n dimensions pour recevoir les données du flux XML
- le parser, parse N éléments XML
- appelle la procédure
- récupère le retour (0 ou -1) et selon, continue le traitement
- un entier, indiquant le nbr d'éléments parsés (sur le dernier paquet cela peut être moins que N)
La DS reçue par la procédure
La procédure (qui en fait est en fin de source)
Le programme principal
Une autre solution, aujourd'hui consiste à faire faire le travail par SQL
XMLTABLE
Fonction Table qui traite sous forme colonnée (relationnelle), les éléments d'un flux XML. La source peut être :
- une colonne de type XML (nouveauté V7)
- le résultat de GET_XML_FILE
- le résultat de HTTPGETBLOB|CLOB
SELECT X.NOM, X.RUE, X.TEL FROM
XMLTABLE ('$c/customerinfo' passing <source> as "c"
COLUMNS
NOM CHAR(30) PATH 'name', -- élément
RUE VARCHAR(25) PATH 'addr/street', -- élément imbriqué dans addr
TEL VARCHAR(20) PATH '@tel' -- attribut
) AS X
Si le XML n'est pas une colonne base de données de type XML , il faut utiliser XMLPARSE( )
select * from XMLTABLE(
'$r/catalog/book' PASSING XMLPARSE(DOCUMENT GET_XML_FILE('/formation/books.xml') ) as "r"
COLUMNS
ID char(5) PATH '@id',
auteur char(10) PATH 'author',
titre char(50) PATH 'title'
) as txml;
Exemple d'utilisation en RPG
Cet exemple, illustre l'utilisation d'un curseur afin de retrouver la totalité des lignes.
Dans notre TP, nous aurions pu demander à SQL de réaliser l'ensemble du traitement
SQL sait aussi lire du JSON
Pour un traitement du format JSON par RPG, voyez le projet YAJL ou bien utilisez Data-Into
Nouveau code opération RPG Data-Into (TR4) , mariant XML-INTO et la notion de Handler de Rpg Open Access
- Voir l'annonce sur le Wiki RPG
- la documentation mise à jour
- En résumé, voici la syntaxe
data-into maDataStructure
%data('Exemple.csv' : 'doc=file case=any ccsid=job ')
%parser('*LIBL/MONPARSER'); |
- Vous devez écrire le parser ....
- Nos premiers tests
- but du jeu : lire ce fichier (résultat de CPYTOIMPF)
- Programme utilisant le PARSER pour recevoir la donnée
- Résultat
- Le parser (DTAINTOPR1)
// exemple de parser pour des données structurées comme ceci : // code appellation, nom appellation, pays // extrait : // 1 ; "madiran" ; "France" // 2 ; "rioja" ; "Espagne" // etc...
ctl-opt main(parserMain) option(*srcstmt) dftactgrp(*No);
/copy QOAR/QRPGLESRC,QRNDTAINTO
dcl-ds parseInfo_T qualified;
lineStartOffset int(10);
dataLen int(10); // Copy of data buffer length
pStartBuffer pointer; // Copy of intial buffer pointer
end-ds;
dcl-proc parserMain; // proc. principale
// on recoit
// parm.data = pointeur sur les données à traiter
// parm.env = pointeur sur des pointeurs de procédure pour le "callback"
// parm.handle = pointeur, handler à utiliser à chaque appel de fonction
// parm.userParm = pointeur vers paramètres utilisateur
// parm.datalen = lg des données à traiter
// parm.dataCcsid = ccsid des données à traiter
// parm.userParmsisNUllTerminated : *ON chaîne du langage C
// *OFF chaîne RPG
dcl-pi *n extpgm;
parm likeds(QrnDiParm_T) const;
end-pi;
// block de controle pour traitement d'une ligne
// (paramètre transmis à lireLIgne() ...)
dcl-ds parseInfo LikeDS(parseInfo_T) Inz;
// nom des zones
dcl-s name1 varchar(15) inz('appel_code');
dcl-s name2 varchar(15) inz('appellation');
dcl-s name3 varchar(15) inz('pays');
// variables pour stocker les valeurs extraites
dcl-s appel_code varchar(10);
dcl-s appellation varchar(30);
dcl-s pays varchar(20);
// ligne et positions des séparateurs
dcl-s ligne varchar(1024);
dcl-s separator1 int(5);
dcl-s separator2 int(5);
// on envoie parm.env qui est un pointeur sur une structure de pointeurs
// contenant les procédures à appeller en "callback"
// (l'info est fournie en tant que paramètre par data-into et réutilisée tel-que)
pQrnDiEnv = parm.env;
// block de contrôle renseigné avec pointeur vers data et lg reçus.
parseInfo.pStartBuffer = parm.data;
parseInfo.dataLen = parm.dataLen;
// début de traitement
QrnDiStart (parm.handle);
// début de tableau
QrnDiStartArray(parm.handle);
// lecture première ligne
ligne = lireLigne(parseInfo);
DoW ligne <> ''; // EOF ?
// recherche premier ";"
separator1 = %scan(';': ligne);
appel_code = %subst(ligne: 1: separator1 - 1);
separator2 = %scan(';': ligne:separator1 + 1);
// il peut ne pas y avoir de pays
if separator2 > 0 and separator2 < %len(ligne);
// on saute le " de début et de fin (d'où + 2)
appellation = %subst(ligne: separator1 + 2 :
separator2 - separator1 -2);
pays = %subst(ligne: separator2 + 2 );
else;
appellation = %subst(ligne: separator1 + 2 );
pays = *blanks;
endif;
// Début de structure (une occurence)
QrnDiStartStruct (parm.handle);
// nom de la donnée extraite 'appel_code'
QrnDiReportName (parm.handle
: %addr(name1: *data)
: %len(name1) );
// valeur de la donnée extraite 'appel_code'
QrnDiReportValue(parm.handle
: %addr(appel_code: *data)
: %len(appel_code) );
// nom de la donnée extraite 'appellation'
QrnDiReportName (parm.handle
: %addr(name2: *data)
: %len(name2) );
// valeur de la donnée extraite 'appellation'
QrnDiReportValue(parm.handle
: %addr(appellation: *data)
: %len(appellation) );
// nom de la donnée extraite 'pays'
QrnDiReportName (parm.handle
: %addr(name3: *data)
: %len(name3) );
// valeur de la donnée extraite 'pays'
QrnDiReportValue(parm.handle
: %addr(pays: *data)
: %len(pays) );
// Fin de structure
QrnDiEndStruct (parm.handle);
// lecture ligne suivante
ligne = lireLigne(parseInfo);
EndDo;
// Fin de tableau
QrnDiEndArray(parm.handle);
// fin du traitement
QrnDiFinish(parm.handle);
on-exit;
// voir si besoin (pas ici)
end-proc;
// lecture d'une ligne (jusqu'à "retour chariot" dans le buffer) // on recoit
// - un offset (décalage) pour naviguer
// - lg des données à traiter
// - un pointeur sur la donnée à traiter
dcl-proc lireLigne;
dcl-pi *n varchar(1024);
parseInfo LikeDS(parseInfo_T);
end-pi;
// variable de travail de 1024 "plaquée" sur les données
// aucune ligne ne doit dépasser 1024 c.
dcl-s buffer char(1024) based(precordStart);
dcl-s record varchar(1024);
dcl-s endOfLine int(5);
If parseInfo.lineStartOffset < parseInfo.dataLen; // encore de la data ?
// Début de ligne = pointeur en cours + offset
precordStart = parseInfo.pStartBuffer + parseInfo.lineStartOffset;
// recherche fin de ligne
endOfLine = %scan(x'25': buffer);
// FindeLigne trouvé ?
// "record" renseigné et position modifiée pour prochaine fois
if endOfLine > 0;
record = %Subst(buffer: 1: endOfLine - 1);
parseInfo.linestartOffset += endOfLine; // prochaine ligne
else; // pas de data
record = '';
endif;
else; // Fin du buffer
record = '';
endif;
return record;
end-proc;
|
- si la DS est incomplete : manque des zones (ici le nom de l'appellation)
- Vous recevez une erreur
- Sauf à le prévoir (comme avec XML-INTO) par Allowextra=yes
- Allowmissing permet d'avoir des zones dans la DS non retournées par le parser
- Si vous ne pouvez pas prédire le nombre d'occurences
- %Handler (comme XML-INTO) permet d'indiquer une procédure à appeler de manière récursive.
- Pour débuger
- Ajoutez la variable d'environnement QIBM_RPG_DATA_INTO_TRACE_PARSER
- ADDENVVAR ENVVAR(QIBM_RPG_DATA_INTO_TRACE_PARSER) VALUE(*STDOUT)
- Lancez le programme
- Pour voir la log utilisez cet utilitaire
// Program DSPSTDOUT
//
// Used to list debug information sent to Std Out by DATA-INTO in debug mode.
// i.e. when environment variable QIBM_RPG_DATA_INTO_TRACE_PARSER set to 'Y'
//
// Author: Based on code supplied by IBM's Barbara Morris
//
ctl-opt actgrp(*new);
dcl-pr printf extproc(*dclcase);
p pointer value options(*string : *nopass);
end-pr;
dcl-pr getchar int(10) extproc(*dclcase) end-pr;
dcl-c EOL x'15';
printf (EOL);
getchar ();
return;
|
- Affichage par DSPSTDOUT :
.../...
Sur cet écran F6 génère un spool de la totalité de la trace
Voyez comment le produit Open source YAJL s'est adapté à ce nouveau code opération.
