Conseil n° 2 : Superviseur du journal IFS

de fichiers lui-même, entraînant un minimum de délai dans le transfert des données à la destination finale (cette approche facilite l’identification du fichier reçu sans devoir rechercher les nouveaux fichiers dans le répertoire). Le superviseur du journal IFS (integrated file system) que j’offre ici vise ces deux objectifs. Comme son nom l’indique, le superviseur du journal IFS s’appuie sur la fonction journal IFS. Vous pouvez configurer le journal IFS pour journaliser les changements apportés à des objets IFS spécifiques de l’un des types suivants : *STMF (stream file), *DIR (directory), *SYMLNK (symbolic link), *DTAARA (data area) ou *DTAQ (data queue). (A noter que le journal IFS n’accepte pas le type d’objet *FILE qui, dans ce contexte, signifierait un fichier de données physique iSeries natif. Cependant, vous pourriez utiliser soit le journal d’audit système (QAUDJRN), soit le point de sortie FTP Client Request Validation (QIBM_QTMF_CLIENT_REQ) pour avoir un utilitaire quelque peu semblable à celui de cet article. Pour plus d’informations sur QAUDJRN, visitez publib.boulder.ibm.com/ iseries/v5r2/ic2924/info/rzaki/rzakiibmjrn.htm. Les points de sortie FTP sont documentés à publib.boulder.ibm.com/iseries/ v5r2/ic2924/info/rzaiq/rzaiqreferenceexit.htm.) L’un des événements de répertoire que vous pouvez journaliser est la création d’un objet dans ce répertoire, génératrice de plusieurs entrées de journal. L’une de ces entrées est du type Create Summary et elle est le déclencheur du superviseur du journal IFS. La possibilité d’identifier un nouveau fichier stream dès qu’il est créé dans un répertoire donné résout la moitié du problème. En effet, il ne nous reste plus qu’à établir le point chronologique où toutes les données ont été écrites dans le fichier stream et à déterminer qu’il a été fermé.

Le système place un verrou sur le fichier stream afin qu’aucun autre processus ne puisse mettre à jour le fichier pendant que FTP y écrit des données. Une fois le transfert de données effectué, le verrou est supprimé. Donc, pour savoir quand le fichier stream est apte au traitement, il suffit de contrôler le nombre de verrous sur le fichier stream et d’attendre qu’il tombe à zéro. Après avoir décidé comment le superviseur du journal devra opérer, il est temps de passer la configuration du journal.

Pour aider à la création et à la configuration du superviseur du journal IFS, j’ai écrit le programme CL CBX601X, qui crée les objets et programmes du journal requis, d’après ses deux paramètres d’entrée :

1. la bibliothèque qui recevra l’utilitaire compilé
2. le chemin d’accès et le nom du répertoire IFS à superviser

Vous trouverez d’autres instructions dans l’en-tête source CBX601X (vous pouvez télécharger tout le code de cet utilitaire sur www.itpro.fr Club Abonnés, mois concerné).
Outre la création de la zone de données, du récepteur du journal et du journal nécessaire à cet utilitaire, le programme commence aussi à journaliser les changements pour le répertoire IFS spécifié et compile les programmes CBX601C, CBX601, CBX6011, CBX6012 et CBX6013.

Le programme RPG IV CBX601 est le programme de sortie de commande RCVJRNE (Receive Journal Entry) et le programme CL CBX601C tourne dans un sous-système batch comme un programme sans fin. CBX601C configure RCVJRNE pour appeler le programme de sortie CBX601 quand une entrée de journal est reçue. Si aucune entrée n’a été reçue dans un délai de 25 secondes, il transmet un zéro pour indiquer qu’il n’y a pas d’entrée disponible. Le délai de 25 secondes permet au job de détecter une requête de fin de job contrôlée qui, par défaut, attend pendant 30 secondes. Le code source CBX601 inclut d’autres informations sur le mode de fonctionnement du programme de sortie, ainsi que des liens vers la documentation IBM concernant les entrées du journal et leurs structures et la commande RCVJRNE.
Les trois programmes RPG IV restants, CBX6011, CBX6012 et CBX6013, effectuent le traitement de fichiers proprement dit. Quand le programme de sortie du journal CBX601 s’exécute, il appelle CBX6011, qui appelle d’abord CBX6012 pour lui faire tester si quelqu’un a placé un verrou sur le fichier IFS. Un tel verrou indiquerait que le transfert de fichier était encore en cours. Cette vérification est répétée autant de fois que spécifié par la constante de programme NBR_RTY. Le délai en secondes entre chaque vérification est indiqué par la constante RTY_ITV_SEC.
Actuellement, le paramétrage précédent définit un maximum de 120 essais successifs et un intervalle de 30 secondes entre chacun d’eux. Cette fonction attend donc jusqu’à une heure que la création de fichiers soit terminée. Vous devez bien sûr adapter ce paramètre à vos besoins précis.
Si la tentative de parvenir à une situation de non-verrouillage échoue, un message est envoyé dans la file d’attente des messages utilisateur du profil utilisateur exécutant le programme.
Notons que le programme CBX6012, qui teste les verrouillages d’objets sur le fichier IFS, utilise API QP0LROR (Retrieve Object References) pour extraire les verrouillages d’objets. Comme QP0LROR a été introduit en V5R2, cet utilitaire nécessite la version V5R2 ou ultérieure. Quand le fichier n’est plus verrouillé, CBX6011 appelle CBX6013 qui contient le code destiné à ouvrir, lire et fermer le fichier IFS. C’est dans CBX6013, que vous pouvez facilement ajouter votre propre code de traitement du fichier IFS. Voici des étapes de traitement dans CBX6013 :

1. Vérifier l’existence du fichier et utiliser l’API stat pour extraire l’information du fichier.
2. Convertir un tampon horodateur EPOCH en un type de données horodateur. Comme exemple de la manière de rendre ce type d’information objet IFS disponible, c’est ici le tampon horodateur de la dernière donnée modifiée.
3. Ouvrir le fichier IFS spécifié et le lire ligne à ligne. 4. Insérer le code de traitement des données dans la sousroutine PrcFilDta.
5. Fermer le fichier et l’archiver dans (c’est-à-dire, le déplacer dans) un sous-répertoire appelé Archive. Si le sous-répertoire Archive n’existe pas, il est créé. Si un fichier de même nom existe dans le répertoire d’archive, l’API unlink supprime implicitement ce fichier avant de déplacer le nouveau.

Pendant que le processus précédent s’exécute, le fichier IFS est écarté, pour empêcher sa mise à jour par d’autres processus. Au fil du traitement du fichier, des messages informatifs signalant l’événement du moniteur et le résultat du traitement du fichier, sont envoyés à la file d’attente de messages du profil utilisateur qui exécute le job superviseur du journal.

Après avoir installé l’application et les objets exemple, soumettez le programme CBX601C à une file d’attente de jobs disponible pour un type de job NEP (never-ending-process) :

SbmJob Cmd( CALL PGM( CBX601C ))
Job( CBXIFSLOG ))
Job( )
Pour mettre fin au job de logs exemple contrôlé, exécutez la commande suivante :

EndJob Cmd( CBXIFSLOG )
Option( *CNTRLD )
Delay( 30 )

On l’a vu, l’option *CNTRLD et un délai de 30 secondes permettent au programme de sortie du journal de détecter la requête de fin et d’arrêter le traitement du journal en bon ordre.

Pour tester le superviseur du journal, copiez simplement un fichier stream dans le répertoire journalisé. En voici un exemple : CPY OBJ(‘/qopensys/testfile.txt’)
TODIR( »/qopensys/journal_dir’)
Avant de mettre en production l’utilitaire superviseur du journal présenté ici, sachez bien qu’il ne constitue que le point de départ de votre propre mise en oeuvre. En effet, vous devez étudier soigneusement les exigences spécifiques de votre environnement, ainsi que les standards de développement et de conception de votre site.

Le superviseur du journal IFS est créé à partir des sources suivantes :

• CBX601C – exécute la commande RCVJRNE • CBX601 – programme de sortie RCVJRNE qui traite les entrées du journal
• CBX6011 – effectue le traitement du fichier stream
• CBX6012 – vérifie le nombre de verrous sur le fichier stream
• CBX6013 – extrait les données du fichier stream ligne à ligne
• CBX601X – crée les objets de l’utilitaire et configure le journal IFS

Notes à l’attention des programmeurs

Pour consulter la documentation IBM à propos des entrées du journal et de leur structure, visitez publib.boulder.ibm. com/iseries/v5r2/ic2924/info/rzaki/rzakijrnentry.htm. Le finder du code journal se trouve à publib.boulder.ibm.com/iseries/ v5r2/ic2924/info/rzaki/finder/rzakijournalfinder.htm. A noter que le membre include QP0LJRNL.H auquel le code journal « B-Integrated file system » se réfère, contient un zéro comme troisième caractère, et pas la lettre « O » que l’on voit par erreur sur ce site Web.

La documentation de la commande RCVJRNE se trouve à publib.boulder.ibm.com/iseries/v5r2/ic2924/info/cl/rcvjrne.h tm. Vous trouverez aussi de la documentation directement sur votre système grâce au texte d’aide de la commande RCVJRNE.