La technique du sous-fichier de messages utilisateur

les sous-fichiers de messages utilisateur.

Pour remplir de données des sous-fichiers ordinaires, il faut écrire dans des enregistrements de sous-fichiers. Les choses se compliquent quelque peu avec les sous-fichiers de messages. En effet, avant d’aboutir dans un sous-fichier de messages, le message doit d’abord passer par une file d’attente de messages de programme. Avant de m’étendre sur ce point, il faut en dire un peu plus sur les files d’attente de messages du programme.

Quand un programme est activé, le système crée une file d’attente de messages temporaire appelée file d’attente de messages de programme, et l’associe à  ce programme. Cette file d’attente est temporaire car supprimée dès que le programme est désactivé. Ceci contraste avec les files d’attente de messages permanentes, que l’on peut créer en utilisant la commande CrtMsgQ (Create Message Queue), et qui subsistent jusqu’à  ce que la commande DltMsgQ (Delete Message Queue) les supprime.

L’introduction d’un message dans un sous-fichier de messages d’erreur utilisateur s’effectue en deux étapes (figure 3). Il faut d’abord placer le message dans une file d’attente de messages de programme, puis copier le message de cette file d’attente dans le sous-fichier de messages. Voyons de plus près ces deux étapes.

Etape 1. Un programme envoie un message à  la file d’attente de messages de programme en utilisant soit la commande SndPgmMsg (Send Program Message), soit l’API QMHSNDPM (Send Program Message) de traitement de messages SndPgmMsg. Je n’entre pas ici dans le détail de SndPgmMsg ; pour plus d’informations sur cette commande, voir le manuel OS/400 CL Reference (SC41-5722).

La figure 4 présente la procédure RPG IV, PutErrMsg, que j’ai incluse dans la version du programme d’en-cours des comptes fournisseurs écrit pour tester cette technique. Le prototype de la procédure montre que celle-ci requiert trois paramètres : un identificateur de message, une donnée à  substituer dans le message et la longueur de cette donnée. Quant à  la procédure, c’est un simple appel adressé à  l’API QMHSNDPM pour envoyer le message dans la file d’attente de messages de programme.

La procédure PutErrMsg définit le paramètre QlMsgf (en A) pour contenir le nom et la bibliothèque (AGEMSGF et *LIBL) du fichier de messages contenant le message d’erreur. Dans cette petite application, tous les messages d’erreur utilisés proviennent de ce fichier de messages, c’est pourquoi je n’ai pas inclus ce dernier comme paramètre de la procédure.

Les quatre premiers paramètres de l’API QMHSNDPM décrivent de manière unique le message à  envoyer et la donnée de message à  substituer dans le message. Le cinquième paramètre, MsgType, indique à  l’API le type de message à  envoyer. Dans ce cas, MsgType est initialisé avec une valeur *DIAG pour indiquer que nous voulons envoyer un message de diagnostic (les messages de diagnostic servent généralement à  envoyer des messages d’erreur non fatale, l’adjectif fatale signifiant qu’il faut mettre fin immédiatement au programme.)

Les sixième et septième paramètres de l’API indiquent à  celle-ci où envoyer le message dans la pile d’appel. La valeur du septième paramètre, ClStkCounter, indique à  quelle distance en arrière dans la pile d’appel, par rapport à  la position indiquée dans le sixième paramètre, ClStkEntry, nous voulons envoyer le message. Ici, ClStkEntry est réglé sur la valeur « * » pour indiquer que ClStkCounter est relatif à  l’entrée en cours de la pile d’appel, procédure PutErrMsg. La valeur 1 pour ClStkCounter signifie que nous voulons envoyer le message une position en arrière dans la pile d’appel depuis cette procédure. Comme PutErrMsg est toujours invoqué depuis la procédure principale du programme, il s’en suit que nous envoyons le message à  la procédure principale (pour un descriptif complet de l’API QMHSNDPM et de ses paramètres, voir OS/400 Message Handling APIs, SC41-5862.)

La figure 5 présente une utilisation classique de la procédure PutErrMsg dans le programme d’encours. Le test If vérifie si la zone 30 jours de retard (30-days-overdue) est inférieure à  zéro. Dans l’affirmative, le programme invoque PutErrMsg pour placer le message AGE0002 dans la file d’attente de messages du programme, en utilisant la donnée de message « 30 » et en précisant une longueur de donnée de message de 2.

Etape 2. Après avoir placé tous les messages que l’on souhaite voir s’afficher dans le sous-fichier de messages d’erreur dans la file d’attente de messages, il faut s’assurer qu’ils sont copiés dans le sous-fichier. La figure 6 présente la partie pertinente des DDS incluse dans le fichier écran pour le programme d’en-cours. Elle commence, comme un sous-fichier ordinaire, par le mot clé SFL. Autre point commun : l’utilisation d’un enregistrement de sous-fichier (MSGSFL) et d’un enregistrement de contrôle de sous-fichier (MSGCTL).

Le mot clé SFL est suivi de trois mots clés (en A) spécifiques des sous-fichiers de messages d’erreur utilisateur. Le mot clé SFLMSGRCD est nécessaire pour l’enregistrement de sous-fichier ; il précise le numéro de ligne d’écran sur lequel doit commencer le sous-fichier de messages (ligne 23 dans l’exemple).

Le mot clé SFLMSGKEY indique une zone (MSGKEY dans l’exemple) qui contiendra une clé de message de quatre octets. Bien qu’obligatoire, cette zone ne joue aucun rôle important pour la technique de sous-fichier décrite ici. Elle n’importe qu’avec la technique de sous-fichier de messages d’erreur à  sorties multiples, une méthode plus complexe, sans avantage réel par rapport à  la méthode à  sortie unique décrite ici ; c’est pourquoi je ne la mentionne que brièvement dans cet article.

Le mot clé SFLPGMQ permet de nommer une zone (PGMQ dans ce cas) qui contiendra soit le nom du programme dont la file d’attente de messages est utilisée pour le sous-fichier de messages, soit la valeur spéciale « * » pour indiquer que le programme doit envoyer les messages à  sa propre file d’attente de messages. Le programme d’en-cours utilise la valeur spéciale « * » dans la zone PGMQ.

Les DDS du format de contrôle (B) démarrent comme une enregistrement de contrôle de sous-fichier ordinaire, avec le mot clé SFLCTL pour spécifier MSGCTL comme enregistrement de contrôle de l’enregistrement de sous-fichier MSGSFL. Les mots clés SFLDSP et SFLDSPCTL sont également utilisés avec des enregistrements de contrôle de sous-fichier ordinaires. Notons que ces mots clés ne sont pas conditionnés par un indicateur (comme c’est le cas en général avec des sous-fichiers ordinaires).

Le mot clé SFLINZ doit toujours être présent comme illustré.

Le mot clé SFLEND doit être présent et activé. Comme les DDS obligent à  conditionner ce mot clé par un indicateur, j’ai choisi N01. Le programme d’en-cours démarre par défaut avec l’indicateur 01 éteint et ne l’active jamais. Par conséquent, SFLEND est toujours activé.

La valeur SFLSIZ de 20 est un choix quelque peu arbitraire. Tant que SFLPAG n’est pas égal à  SFLSIZ, je peux placer jusqu’à  9999 messages à  la fois dans le sous-fichier de messages. En mettant 20 pour SFLSIZ, on indique que le système allouera suffisamment de mémoire contiguà« pour recevoir le contenu de 20 messages dans le sous-fichier de messages. Si je place un vingt et unième message dans le sous-fichier, le système allouera une autre tranche de mémoire contiguà« suffisamment grande pour contenir 20 autres messages de ce type.

J’ai choisi une valeur SFLPAG de 1 pour indiquer que je souhaite afficher un message à  la fois au bas de l’écran. On peut bien entendu utiliser SFLPAG pour afficher autant de messages que l’écran peut en contenir.

Comme je l’ai fait dans le format de sous-fichier, j’indique le mot clé SFLPGMQ dans le format de contrôle. En réalité, ce mot clé est obligatoire dans le format de sous-fichier et facultatif dans celui de contrôle. En le plaçant dans ce dernier, j’indique mon souhait au système : une instruction Write de l’enregistrement de contrôle doit entraîner la copie dans le sous-fichier de messages d’erreur de tous les messages présents dans la file d’attente de messages du programme. C’est l’essence même de la méthode de sortie unique. En omettant SFLPGMQ dans l’enregistrement de contrôle, on indique au système qu’il faut utiliser l’autre technique, celle des sorties multiples. Pour une brève explication de cette dernière, voir « La technique des sorties multiples »

La figure 7 illustre une partie de la boucle principale du programme d’en-cours. Notez qu’avant d’afficher l’écran, j’écris l’enregistrement MsgCtl (en A). Nous avons vu que cette étape effaçait le sous-fichier de messages d’erreur puis le peuplait avec les éventuels messages présents à  ce moment là  dans la file d’attente de messages du programme. Comme à  chaque passage dans cette boucle, je souhaite présenter un jeu d’erreurs différent (ou pas d’erreurs), je dois aussi effacer la file d’attente de messages du programme à  chaque passage dans la boucle. Comme on le voit dans la figure, j’invoque une procédure appelée RmvMsgsFrmQ (en B) pour supprimer les messages d’erreur de la file d’attente de messages du programme.

La figure 8 présente la procédure RmvMsgsFrmQ. Elle utilise l’API QMHRMVPM (Remove Program Messages) pour supprimer les messages d’erreur. Pour indiquer que la file d’attente de messages du programme est celle dont les messages doivent être supprimés, je donne au paramètre call-stack-entry et call-stack-counter les mêmes valeurs que celles utilisées avec l’API QMHSNDPM. L’API QMHRMVPM permet également de supprimer des messages individuels quand on connaît leur clé de quatre octets unique. Comme je veux supprimer tous les messages, j’ai indiqué les valeurs *Blank pour MsgKey et *ALL pour MsgToRmv.

• d’afficher des messages d’erreur multiples

• d’offrir une aide de second niveau

• de « débloquer ” le clavier.