%MSG

Envoyer un message par son identifiant

Désigne un message du fichier de messages (identifiant, fichier, données) dans une instruction snd-msg.

Syntaxe

snd-msg *ESCAPE %MSG(identifiant : fichier-de-messages)
snd-msg *ESCAPE %MSG(identifiant : fichier-de-messages : données)

identifiant: L'identifiant du message, sur 7 caractères ('CPF9898').
fichier-de-messages: Le nom du fichier de messages ('QCPFMSG').
données: Facultatif : les données qui remplacent les variables &1, &2… du texte du message.
Résultat: Aucune : %MSG n'est utilisable que dans snd-msg.

À quoi ça sert

Un texte libre dans snd-msg n'a pas d'identifiant : le programme appelant ne peut pas savoir de quelle erreur il s'agit sans lire le texte. Avec %MSG, le message porte un identifiant que l'appelant lit et compare. Les textes vivent dans un fichier de messages, ce qui permet de les traduire.

Le message générique CPF9898 de QCPFMSG affiche tel quel le texte qu'on lui passe : pratique pour un message d'application.

Exemple 1 : CPF9898 et un message avec ses données

**free
// %MSG : envoyer un vrai message (avec identifiant) plutot qu'un texte libre.
ctl-opt dftactgrp(*no) actgrp(*new);

dcl-ds sds psds qualified;
  msgid char(7) pos(40);
  msgtxt char(80) pos(91);
end-ds;

// Message generique CPF9898 : le texte est celui qu'on fournit.
monitor;
  verifieMontant(-320);
on-error;
  snd-msg 'Identifiant : ' + sds.msgid;
  snd-msg 'Texte       : ' + %trim(sds.msgtxt);
endmon;

// Message prevu dans QCPFMSG, avec ses donnees (objet, bibliotheque, type).
monitor;
  snd-msg *escape %msg('CPF2105' : 'QCPFMSG' : 'CLIENT    JOBIRPG   FILE')
          %target(*self);
on-error;
  snd-msg 'Identifiant : ' + sds.msgid;
  snd-msg 'Texte       : ' + %trim(sds.msgtxt);
endmon;

*inlr = *on;

dcl-proc verifieMontant;
  dcl-pi *n;
    montant packed(9:2) const;
  end-pi;
  if montant < 0;
    snd-msg *escape %msg('CPF9898' : 'QCPFMSG' : 'Montant negatif : ' + %char(montant));
  endif;
end-proc;

Résultat réel, compilé et exécuté sur IBM i 7.5 :

Identifiant : CPF9898
Texte       : Montant negatif : -320.00.
Identifiant : CPF2105
Texte       : Objet CLIENT de JOBIRPG type *FILE non trouvé.

Le premier message, CPF9898, reprend le texte fourni (« Montant negatif : -320.00 »). Le second, CPF2105, est un message du système dont le texte « Objet &1 de &2 type *&3 non trouvé » est rempli par les données : nom de l'objet sur 10 caractères, bibliothèque sur 10, type. L'appelant récupère l'identifiant et le texte dans la zone d'état du programme (psds, positions 40 et 91).

Exemple 2 : Un identifiant inexistant

**free
// %MSG : l'identifiant n'est pas verifie a la compilation.
ctl-opt dftactgrp(*no) actgrp(*new);

dcl-ds sds psds qualified;
  msgid char(7) pos(40);
  msgtxt char(80) pos(91);
end-ds;

monitor;
  snd-msg *escape %msg('ZZZ0001' : 'QCPFMSG' : 'Stock insuffisant') %target(*self);
on-error;
  snd-msg 'Identifiant : [' + sds.msgid + ']';
  snd-msg 'Texte       : ' + %trim(sds.msgtxt);
endmon;

*inlr = *on;

Résultat réel, compilé et exécuté sur IBM i 7.5 :

Identifiant : [ZZZ0001]
Texte       : Texte non disponible pour le message ZZZ0001 du fichier QCPFMSG.

Le message ZZZ0001 n'existe pas : le compilateur ne le vérifie pas, et l'envoi réussit. L'appelant reçoit l'identifiant, mais le texte devient « Texte non disponible… » et les données passées sont perdues.

Le piège

L'identifiant n'est vérifié ni à la compilation ni à l'envoi. Une faute de frappe (ZZZ0001) passe sans erreur, et l'utilisateur voit « Texte non disponible pour le message… » (exemple 2). Testez chaque message au moins une fois.

Dans la partie principale du programme, un *ESCAPE sans %TARGET(*SELF) part vers l'appelant du programme, hors de vos monitor : c'est pourquoi les exemples utilisent %TARGET(*SELF) à ce niveau.