Archive pour la catégorie : Non classé

La facturation électronique impose aux entreprises de produire des fichiers XML structurés, normalisés, échangés entre plateformes. Pour les équipes qui maintiennent un système de gestion sur IBM i, cela soulève une question concrète : comment générer proprement un fichier XML en RPG Free ILE, alors que le langage est historiquement tourné vers les bases de données DB2 ?

Cet article retrace l’approche mise en œuvre lors d’un projet réel de génération de factures au format Factur-X / CrossIndustryInvoice (norme EN 16931). Au-delà du cas de la facture, la technique décrite vaut pour n’importe quel fichier texte à écrire sur l’IFS : XML, CSV, JSON ou HTML.

Deux mondes à réconcilier

Un développeur RPG passe l’essentiel de son temps dans un environnement bien délimité : des tables DB2, un accès natif ou du SQL intégré, des données encodées en EBCDIC. C’est efficace, robuste et parfaitement adapté à la gestion transactionnelle.

Un fichier XML, lui, appartient à un autre monde. Il vit dans l’IFS (Integrated File System), l’arborescence de type Unix du système. C’est un fichier « stream », attendu par les plateformes de dématérialisation dans un encodage précis : UTF-8. Le défi consiste donc à construire, depuis du code RPG, un fichier texte UTF-8 bien formé et à le déposer au bon endroit de l’IFS.

La bonne nouvelle : le système fournit déjà tout ce qu’il faut. Inutile d’introduire un composant Java ou un utilitaire externe ; les API C standard du système suffisent, et le RPG sait les appeler.

La clé : les API C de l’IFS

Quatre fonctions C couvrent l’ensemble du besoin. On les déclare en prototypes RPG, puis on les utilise comme n’importe quelle procédure.

dcl-pr open int(10) extproc('open');
  path     pointer value options(*string);   // chemin IFS
  oflag    int(10) value;                     // drapeaux d'ouverture
  mode     uns(10) value options(*nopass);    // droits d'accès
  codepage uns(10) value options(*nopass);    // CCSID du fichier
end-pr;

dcl-pr write int(10) extproc('write');
  fd     int(10) value;     // descripteur retourné par open
  buffer pointer value;     // adresse du texte à écrire
  nbytes uns(10) value;     // nombre d'octets à écrire
end-pr;

dcl-pr close int(10) extproc('close');
  fd int(10) value;
end-pr;

dcl-pr unlink int(10) extproc('unlink');  // suppression du fichier
  path pointer value options(*string);
end-pr;

Leur rôle se résume simplement : open crée ou ouvre le fichier et renvoie un identifiant, write y écrit des octets, close libère le fichier, et unlink le supprime si la génération échoue. La seule contrainte de compilation est de lier la directory de service QC2LE (paramètre BNDDIR('QC2LE')).

Trois concepts à maîtriser

Avant d’écrire la moindre balise, trois notions méritent d’être bien comprises, car elles conditionnent la validité du résultat.

• Le file descriptor. L’appel à open renvoie un entier, le descripteur de fichier (fd). Cet entier identifie le fichier ouvert ; on le transmet ensuite à write et à close. Une valeur négative signale un échec d’ouverture : il faut systématiquement tester ce cas avant d’écrire quoi que ce soit.

• Le CCSID 1208. Le dernier paramètre de open indique au système le jeu de caractères du fichier. La valeur 1208 correspond à l’UTF-8, l’encodage attendu pour un XML valide. C’est un point décisif : sans lui, les accents et les caractères spéciaux se retrouvent corrompus, et le fichier est rejeté par la plateforme destinataire.

• Le CRLF. Contrairement à l’écriture dans un fichier base de données, l’IFS ne gère pas les enregistrements pour nous. C’est au programme d’ajouter explicitement le retour chariot suivi du saut de ligne (x'0D0A') à la fin de chaque ligne, afin d’obtenir un fichier lisible et correctement structuré.

Le cœur du dispositif : une procédure d’écriture

Plutôt que d’appeler write directement à chaque ligne du XML — ce qui serait verbeux et source d’erreurs — on encapsule toute la mécanique dans une procédure unique, appelée ici WriteLine. C’est elle qui sera invoquée des centaines de fois pour construire le document.

dcl-proc WriteLine;
  dcl-pi *n int(10);
    pLine char(2048) const ccsid(1208);
  end-pi;

  dcl-s ligne char(2048) ccsid(1208);
  dcl-s lg    int(10);

  ligne = %trim(pLine) + CRLF;          // ajout du séparateur de ligne
  lg    = %len(%trim(ligne));

  return write(fd : %addr(ligne) : lg); // %addr = adresse du buffer
end-proc;

Deux détails méritent l’attention. D’abord, le tag ccsid(1208) sur le paramètre et sur la variable de travail garantit que le texte manipulé est bien en UTF-8, en cohérence avec le fichier ouvert. Ensuite, write ne raisonne pas en chaînes mais en octets bruts : on lui passe donc un pointeur vers le tampon, obtenu via %addr, accompagné d’une longueur.

Une fois cette procédure en place, le reste du programme devient remarquablement lisible : il ne s’agit plus que d’enchaîner des appels du type WriteLine('<balise>…</balise>').

Ne pas casser le fichier : l’échappement XML

Certains caractères ont une signification syntaxique en XML. Une raison sociale aussi banale que « Durand & Fils » suffit à rendre le fichier invalide si le & n’est pas échappé. Il faut donc remplacer ces caractères réservés par leurs entités correspondantes.

dcl-proc escapeXml;
  dcl-pi *n varchar(2048);
    pTexte varchar(2048) const;
  end-pi;

  dcl-s r varchar(2048);

  r = pTexte;
  r = %scanrpl('&'  : '&'  : r);   // à traiter EN PREMIER
  r = %scanrpl('<'  : '&lt;'   : r);
  r = %scanrpl('>'  : '&gt;'   : r);
  r = %scanrpl('"'  : '&quot;' : r);
  r = %scanrpl('''' : '&apos;' : r);
  return r;
end-proc;

L’ordre des remplacements n’est pas anodin : le & doit impérativement être traité en premier. Dans le cas contraire, les & introduits par les substitutions suivantes (<, >…) seraient eux-mêmes ré-échappés, produisant des séquences erronées. Cette fonction s’applique à toute donnée de texte libre : libellés d’articles, raisons sociales, désignations, commentaires.

Un exemple complet et minimal

Le programme ci-dessous rassemble les éléments précédents en une démonstration autonome. Il ouvre un fichier, écrit une petite facture, puis ferme le descripteur. C’est le squelette exact que l’on retrouve, démultiplié, dans un programme de production.

**free
///
// @Program  DEMOXML
// @Purpose  Démonstration minimale : créer un fichier XML sur l'IFS en RPG Free
//
// Le principe  :
//   1) open()  -> on crée/ouvre un fichier "stream" sur l'IFS en UTF-8
//   2) write() -> on écrit le contenu ligne par ligne
//   3) close() -> on ferme le descripteur
//
///
ctl-opt dftactgrp(*no) actgrp(*new) bnddir('QC2LE');

// ---------------------------------------------------------------------------
// 1. PROTOTYPES DES API C DE L'IFS
// ---------------------------------------------------------------------------
dcl-pr open int(10) extproc('open');
  path     pointer value options(*string);   // chemin IFS (ex: /tmp/fic.xml)
  oflag    int(10) value;                     // drapeaux d'ouverture
  mode     uns(10) value options(*nopass);    // droits d'accès (rwx)
  codepage uns(10) value options(*nopass);    // CCSID du fichier (1208 = UTF-8)
end-pr;

dcl-pr write int(10) extproc('write');
  fd     int(10) value;                        // descripteur retourné par open
  buffer pointer value;                        // adresse du texte à écrire
  nbytes uns(10) value;                         // nombre d'octets à écrire
end-pr;

dcl-pr close int(10) extproc('close');
  fd int(10) value;
end-pr;

dcl-pr unlink int(10) extproc('unlink');       // suppression du fichier
  path pointer value options(*string);
end-pr;

// ---------------------------------------------------------------------------
// 2. CONSTANTES D'OUVERTURE (drapeaux open + droits + séparateur de ligne)
// ---------------------------------------------------------------------------
dcl-c O_WRONLY          2;          // écriture seule
dcl-c O_CREAT           8;          // créer le fichier s'il n'existe pas
dcl-c O_TRUNC          64;          // remettre à 0 octet (écrasement)
dcl-c O_TEXTDATA 16777216;          // mode texte (conversion CCSID)
dcl-c CCSID_UTF8     1208;          // UTF-8 -> indispensable pour le XML
dcl-c MODE_RWX        448;          // droits rwx pour le propriétaire
dcl-c CRLF       x'0D0A';           // retour chariot + saut de ligne

// ---------------------------------------------------------------------------
// 3. VARIABLES
// ---------------------------------------------------------------------------
dcl-s fd     int(10);
dcl-s rc     int(10);
dcl-s chemin varchar(256);

// ===========================================================================
//                          PROGRAMME PRINCIPAL
// ===========================================================================
chemin = '/tmp/demo_facture.xml';

// --- ÉTAPE 1 : ouverture / création du fichier en UTF-8 -------------------
fd = open( %trim(chemin)
         : O_WRONLY + O_CREAT + O_TRUNC + O_TEXTDATA   // drapeaux combinés
         : MODE_RWX                                     // droits
         : CCSID_UTF8 );                                // 1208 = UTF-8

if fd < 0;                                  // < 0 => échec de l'ouverture
  *inlr = *on;
  return;
endif;

// --- ÉTAPE 2 : écriture du XML ligne par ligne ----------------------------
WriteLine('<?xml version="1.0" encoding="UTF-8"?>');
WriteLine('<Facture>');
WriteLine('  <Numero>FA-2026-001</Numero>');
WriteLine('  <Client>' + escapeXml('Durand & Fils') + '</Client>');
WriteLine('  <Montant devise="EUR">1250.00</Montant>');
WriteLine('</Facture>');

// --- ÉTAPE 3 : fermeture du descripteur ------------------------------------
rc = close(fd);

*inlr = *on;
return;

// ===========================================================================
// PROCÉDURE RÉUTILISABLE : écrit UNE ligne de texte + saut de ligne
//   Le buffer est tagué ccsid(1208) : le texte est donc bien en UTF-8.
// ===========================================================================
dcl-proc WriteLine;
  dcl-pi *n int(10);
    pLine char(2048) const ccsid(1208);
  end-pi;

  dcl-s ligne char(2048) ccsid(1208);
  dcl-s lg    int(10);

  ligne = %trim(pLine) + CRLF;        // on ajoute le séparateur de ligne
  lg    = %len(%trim(ligne));

  return write(fd : %addr(ligne) : lg);  // %addr = adresse du buffer
end-proc;

// ===========================================================================
// PROCÉDURE : échappement des caractères spéciaux du XML
//   ATTENTION : remplacer '&' EN PREMIER, sinon double échappement.
// ===========================================================================
dcl-proc escapeXml;
  dcl-pi *n varchar(2048);
    pTexte varchar(2048) const;
  end-pi;

  dcl-s r varchar(2048);

  r = pTexte;
  r = %scanrpl('&'  : '&amp;'  : r);   // & EN PREMIER
  r = %scanrpl('<'  : '&lt;'   : r);
  r = %scanrpl('>'  : '&gt;'   : r);
  r = %scanrpl('"'  : '&quot;' : r);
  r = %scanrpl(''''  : '&apos;' : r);
  return r;
end-proc;

Le fichier produit est un XML standard, où la raison sociale a bien été échappée :

<?xml version="1.0" encoding="UTF-8"?>
<Facture>
  <Numero>FA-2026-001</Numero>
  <Client>Durand &amp; Fils</Client>
  <Montant devise="EUR">1250.00</Montant>
</Facture>

Du squelette au cas réel

La génération d’une vraie facture électronique repose exactement sur ce principe, mais à une autre échelle. Une boucle SQL parcourt les factures à traiter ; pour chacune, les données sont chargées dans des structures externes (entête, parties prenantes, lignes d’articles, ventilation de TVA, pied de facture) ; puis des dizaines d’appels à WriteLine reconstituent l’arborescence CrossIndustryInvoice. Chaque valeur y est associée à son code métier normalisé — BT-1 pour le numéro de facture, BT-112 pour le montant total TTC, et ainsi de suite. La complexité réside alors dans la conformité à la norme, non dans la mécanique d’écriture, qui reste celle décrite ici.

Bonnes pratiques

Quelques principes, issus de l’expérience, font la différence entre une preuve de concept et un programme fiable en production :

• Tester le code retour de open. Un descripteur négatif signale un échec ; il ne faut pas tenter d’écrire dans un fichier qui n’a pas pu être ouvert.
• Toujours fermer le descripteur. Un fd laissé ouvert peut verrouiller le fichier ou produire un contenu incomplet.
• Nettoyer en cas d’erreur. Lorsqu’une exception interrompt la génération, unlink supprime le fichier partiellement écrit, évitant de livrer un XML tronqué.
• Assurer la cohérence UTF-8. Le tag ccsid(1208) du tampon et le CCSID passé à open doivent concorder.
• Centraliser l’écriture. Une procédure WriteLine unique rend le code lisible, réduit les risques d’erreur et facilite la maintenance.
• Échapper tout texte libre. Les données saisies par les utilisateurs doivent systématiquement passer par la fonction d’échappement avant d’être insérées dans une balise.

Conclusion

Générer du XML sur IBM i en RPG Free ILE ne requiert ni bibliothèque tierce ni changement de paradigme. Trois idées suffisent à poser des fondations solides : les API C de l’IFS (open, write, close, unlink) assurent l’écriture de tout fichier texte ; le CCSID 1208 garantit un encodage UTF-8 conforme ; et une procédure d’écriture associée à une fonction d’échappement rendent le code clair et maintenable. Le reste relève du métier — remplir les bonnes balises avec les bonnes données.

Cette approche, éprouvée dans le cadre de la facturation électronique, constitue une brique réutilisable pour tout besoin d’interopérabilité par fichiers structurés sur la plateforme IBM i.

La semaine dernière, à Lyon, lors du congrès Common Europe 2026, nous avons parlé modernisation, APIs, IA… et futur de l’IBM i.

Mais au détour des conversations, difficile d’oublier une évidence :
une partie de notre ADN technologique est née ici même, à Lyon.

Et si les développeurs RPG d’aujourd’hui partageaient, sans toujours le savoir, un héritage direct avec les canuts et les métiers Jacquard ?

Lyon, berceau d’une révolution : le métier Jacquard

Au début du XIXe siècle, Lyon est la capitale mondiale de la soie. Les métiers à tisser sont complexes, coûteux et surtout… difficiles à piloter.

En 1801, Joseph Marie Jacquard introduit une innovation majeure : un métier à tisser contrôlé par des cartes perforées.

Chaque carte représente une ligne du motif à tisser. Les trous dictent mécaniquement quelles aiguilles doivent être activées.

C’est simple, robuste, et surtout :

• programmable
• reproductible
• automatisable

Autrement dit : le premier système programmable industriel de l’histoire.

Napoléon, sponsor inattendu du “code”

Le métier Jacquard n’a pas été immédiatement accepté. Les canuts voyaient cette innovation comme une menace pour leur savoir-faire… et certains métiers ont même été détruits. C’est finalement Napoléon Bonaparte qui a soutenu Jacquard et officialisé l’usage de sa machine.

On pourrait presque dire que l’histoire de la “programmation” a démarré avec :

• une innovation disruptive
• une résistance des utilisateurs
• et un sponsor politique pour imposer le changement

Un schéma… encore très actuel ?

La carte perforée : premier support de programmation

Le principe est fondamental :

L’information n’est plus dans la machine, elle est dans un support externe.

Chaque trou correspond à une instruction binaire :

• trou → action
• pas de trou → pas d’action

Ce modèle va traverser les décennies et inspirer directement les premiers systèmes informatiques.

Ada Lovelace avait déjà compris

Au XIXe siècle, Charles Babbage conçoit sa “machine analytique”, ancêtre de l’ordinateur.

Son idée ? Utiliser… des cartes perforées inspirées directement du métier Jacquard.

Et Ada Lovelace, souvent considérée comme la première développeuse de l’histoire, va encore plus loin. Elle comprend que la machine pourrait manipuler autre chose que des chiffres.

Elle écrit, en substance :

“La machine pourrait composer de la musique si on lui donnait les règles.”

Autrement dit : la programmation n’était déjà plus une question de calcul, mais de logique et de création.

Du textile au numérique : l’héritage IBM

IBM industrialise massivement l’usage des cartes perforées au XXe siècle.

Le RPG : un langage façonné par les cartes

Le langage RPG, introduit dans les années 1960, est directement conçu pour… les cartes perforées.

Chaque ligne de code correspond à une carte. Chaque colonne a une signification précise.

Exemple :

• colonnes 1–5 : libre
• colonne 6 : type de ligne
• reste : spécifications

Ce format n’est pas une contrainte arbitraire, c’est un héritage physique.

Une histoire de continuité

Nous n’avons pas changé de paradigme
Nous avons changé de support

Du métier Jacquard à l’IBM i :

• on programme
• on structure
• on exécute

Conclusion : coder, c’est tisser

À Lyon, pendant le Congrès de Common Europe, difficile de ne pas voir le parallèle :

Les développeurs IBM i sont les héritiers des canuts !

Et au fond, nous faisons le même métier : Transformer des instructions en valeur.