Soumission de requêtes par l'intermédiaire de fichiers

Pré-requis

Pour que le lancement de requêtes batch puisse être fait par l’intermédiaire de fichiers, il est nécessaire :

    Que le paramètre général Utilisation des fichiers batch soit égal à Oui dans les paramètres du serveur batch.

    Que le paramètre EXTBATCH soit égal à Oui. Ce paramètre, qui appartient au groupe SUP, peut être défini au niveau dossier et utilisateur. Il est ainsi possible d’interdire globalement le lancement de requêtes batch de cette façon pour un dossier donné, en accordant si nécessaire une exception à des utilisateurs désignés.

Les fichiers de requête (extension req)

Le lancement d’une requête batch peut être réalisé par le dépôt d’un fichier d’extension .job dans le répertoire dédié à ces fichiers. Ce fichier doit être de type ascii, structuré en ligne terminées par <CR> ou <CR><LF>, chaque ligne définissant la valeur d’un paramètre sous la forme :

PARAMETRE=VALEUR

Certains paramètres sont obligatoires et identifient le contexte d’exécution de la requête. D’autres paramètres dépendent de la requête à lancer ; leur nom correspond au nom des paramètres définis dans l’écran associé au lancement de la requête. Dans certains cas, un tableau de paramètres est défini dans l’écran ; la syntaxe est alors PARAMETRE(indice)=VALEUR, indice étant une valeur numérique.

Afin de faciliter la création d’un tel fichier, il est possible de lancer la requête depuis le progiciel, en cochant la case modèle dans l’écran de lancement des requêtes. Si ceci est fait, un fichier contenant la liste complète des paramètres de lancement et leur valeur sera créé dans le répertoire de lancement. Ce fichier est créé avec le nom de la requête et l’extension .mod.

On trouvera dans le tableau ci-dessous le nom des paramètres obligatoires et leur définition.

Il est à noter que les valeurs du paramètre sont données sans séparateur d’aucune sorte, et qu’il est possible de mettre des lignes de commentaires préfixées par le caractère #. Ainsi, on pourra mettre dans le fichier de requêtes :

         # Paramètres obligatoires

         DOSSIER=DEMO

         DATE=20020614

        …

       # Paramètres complémentaires

       PARAM(1)=TEST

        PARAM(2)=ABC

Cinématique de traitement des fichiers de requête

Le serveur batch inspecte à intervalles réguliers le contenu du répertoire dédié aux fichiers de requête. Lors de l’inspection, il lit les fichiers présents dans le répertoire en les prenant dans l’ordre de classement ascii. Ainsi, il est conseillé de nommer ces fichiers avec une racine fixe et un numéro séquentiel sur une longueur fixe. On pourrait par exemple les nommer REQ000001.req, REQ0000002.req…

Lors du traitement de chaque fichier, des fichiers sont créés successivement dans les différents répertoires définis par les paramètres du serveur batch.  Ces fichiers sont définis ci-dessous :

Il est à noter que le fait qu’un fichier xxxxx.run existe ne signifie pas nécessairement que la requête en question tourne. En effet, si le serveur batch a été arrêté sans que les requêtes qui tournaient encore n’aient été arrêtées, les fichiers xxxxx.run correspondants existeront toujours même lorsque la requête aura terminé son traitement. Dans ce cas, le fichier xxxxx.sta ne sera pas non plus créé. Par contre, lorsque le serveur batch sera à nouveau lancé, le fichier xxxxx.run sera effacé, un fichier xxxxx.stacontenant un statut particulier étant alors créé.

Le nombre de requêtes batch en cours de traitement ne peut donc pas forcément se déduire du nombre de fichiers xxxxx.run présents dans le répertoire dédié.

Description des fichiers XXX.sta, XXX.run, XXX.kil

Ces fichiers sont des fichiers ascii, codés en ascii 8 bits, présents dans différents répertoires, selon le paramétrage :

• Le fichier .kil peut être vide, ou contenir un commentaire qui sera repris dans le fichier d’extension .sta
• Le fichier .run contient une ligne conforme à la structure définie ci-dessous, les informations renseignées étant le numéro de la requête, la date et l’heure de début, et le code de la tâche (les autres informations sont remplies avec des 0 ou des espaces)
• Le fichier .sta contient une ligne dont le format est défini ci-dessous, tous les champs étant renseignés.

La structure de la ligne unique contenue dans les fichiers .run et .sta est la suivante :

• La ligne est composée de 8 champs de longueur fixe, avec des séparateurs (le caractère deux-points ‘ :’).
• La longueur totale est de  154 ou 155 caractères

Le schéma exact est le suivant :

La zone message permet d’expliciter le code erreur si nécessaire. Elle est stockée en longueur fixe sur 80 caractères (le message étant complété par des espaces si nécessaire).

Le numéro de requête est stocké sur 8 caractères, préfixé par des zéros si nécessaire. Ce numéro permet de connaître le nom du fichier de trace généré à l’exécution de la requête. En effet, ce fichier s’appelle RQTNNNNNNNN.tra (NNNNNNNN étant le numéro de requête sur 8 caractères). On le trouve dans le sous-répertoire TRA du dossier SERVX3. Il est à noter que ce numéro peut être nul dans certains cas d’erreur, lorsque aucune requête n’a pu être lancée.

Le code de la tâche correspond à la tâche ou à l’enchaînement de tâches lancé, tel qu’il est connu dans la table des tâches ou des enchaînements.

Le code statut, sur 5 caractères numériques, permet de connaître le résultat de l’exécution. Le premier chiffre détermine le résultat globale de l’exécution, les chiffres suivants donnant des informations complémentaires. Lorsque la requête s’est terminée sans erreur et sans avertissement, on a un code erreur égal à 00000. Le détail des codes est donné ci-dessous :

Remarques

Il est à noter que, dans le cadre de la modélisation des tâches batch (modèle GTRAITE), l’utilisateur dispose des variables suivantes, accessibles dans des tâches spécifiques, ou dans des tâches standard par le biais de points d’entrée :

• La variable GOK est un statut mis à jour dès le lancement de la tâche. Elle vaut 1 s'il n'y a pas de problème, 0 en cas d’erreur de verrouillage, -1 sur une erreur grave autre, et 2 sur une erreur grave de cohérence du serveur. Cette variable est gérée par les tâches standard : si elle ne vaut pas 1 en fin d'un traitement batch, la tâche apparaît en statut Erreur en surveillance des tâches; dans ce cas, si la tâche fait partie d'un groupe de tâches, les tâches suivantes sont bloquées et ne seront jamais lancées.
• La variable GERREUR n'est mise à une valeur non nulle qu'en cas d'erreur à l'exécution d'une instruction (c'est le numéro d'erreur correspondant à une exception traitée par l'instruction Onerrgo). Si cette variable est non nulle en fin de tâche, l'état de la tâche est mis à Avorté en surveillance des tâches, et les tâches qui suivent, si la tâche fait partie d'un groupe, sont bloquées.
• La variable GERRTRACE permet de compter le nombre de lignes de trace d’erreur créées par la tâche. Elle est également gérée par les tâches standard. Le fait qu'elle soit positive met la tâche en Erreur dans la tâche de surveillance, sans pour autant bloquer l'enchaînement des tâches suivantes dans un groupe. Il s'agit en fait du décompte d'un nombre de lignes d'erreur supposées bénignes.
• La variable GERRBATCH est une variable numérique supplémentaire, qui permet de donner un code d’erreur dépendant de la tâche si on considère que la tâche ne s’est pas bien terminée (ce indépendamment du fait que des lignes de trace d’erreur ont été ou pas générées). Si la valeur de GERRBATCH est strictement inférieure à 100, on considère qu'il s'agit d'un statut d'erreur bénin. Si par contre la valeur de GERRBATCH est supérieure ou égale à 100, le statut de la tâche dans la fonction de surveillance des tâches passe à Erreur en fin d'exécution, et si la tâche fait partie d'un groupe, l'enchaînement des tâches suivantes s’interrompt. Cette variable a été créée pour permettre une gestion d'erreur spécifique par le biais d'un point d'entrée.
• La variable GMESSBATCH est une variable alphanumérique permet de donner un message d’erreur complémentaire. Ce message est inséré dans le contenu du fichier d’extension .sta si une erreur se produit.

Sauf erreur de cohérence au lancement, les tâches batch standard du progiciel considèrent dans tous les cas que les erreurs rencontrées sont bénignes et mettent simplement à jour la trace en incrémentant GERRTRACE. Ceci signifie que toute erreur grave devant interrompre le traitement doit être traitée de façon spécifique, par le biais de points d'entrée, en donnant à GERRBATCH une valeur supérieure à 100.

Description du fichier serveur.tra

Ce fichier, présent dans le sous-répertoire TRA du répertoire SERVX3, contient la trace du serveur. La structure des lignes est conforme à celle d’un fichier de trace classique (en-tête normalisé, et statuts numériques sur 5 caractères). Chaque ligne est composée d’un texte éventuellement préfixé par un numéro (ce numéro est lui-même précédé par le caractère < si on considère qu’il s’agit d’une erreur, par = s’il s’agit d’un avertissement).

Les numéros de statuts suivants existent (ils sont préfixés par 4 et 5 pour des raisons de continuité de numérotation avec les statuts précédents). Il est à remarquer que les statuts commençant par 4 sont des statuts graves qui ne devraient pas survenir dans une exploitation normale (problèmes de mise à jour, de gestion des tâches, de verrouillage du serveur batch), et peuvent venir soit de problèmes système, soit d’une mauvaise installation, soit encore de spécifiques. Les statuts commençant par 5 sont, quant à eux, des statuts normaux de l’activité du serveur batch :

Description des fichiers RQTNNNNNNNN.tra

Ces fichiers, présent dans le sous-répertoire TRA du répertoire SERVX3, contiennent la trace associée à la requête elle-même. La structure des lignes est conforme à celle d’un fichier de trace classique (en-tête normalisé, et statuts numériques sur 5 caractères). Chaque ligne est composée d’un texte éventuellement préfixé par un numéro (ce numéro est lui-même précédé par le caractère < si on considère qu’il s’agit d’une erreur ou d’un avertissement). Ces fichiers peuvent être lus directement depuis le gestionnaire de requêtes par le biais d’un clic droit / Lecture trace.

Passée la ligne d’en-tête, la première ligne d’un tel fichier se présente sous la forme d’une ligne au format suivant (elle intègre le statut Activation requêtedéfini ci-dessus) :

=51000 NNNNNNNNJJ/MM/AA hh :mm :ss Activation requête (51000)

(NNNNNNNNreprésentant ici le numéro de tâche)

Les lignes de trace classique de la tâche suivent cette première ligne (si le traitement en question n’est pas lancé en batch, ces lignes seraient écrites dans un fichier de trace classique FNNNNN.tra dans le répertoire TRA du dossier de lancement). Puis, sauf dans le cas où la tâche a été arrêtée brutalement (par un killadx, par exemple), on trouvera une ligne finale de structure identique, mais dont le numéro est conforme au statut de fin correcte (00000) ou d’erreur (1NNNN)décrit ci-dessus.

Tables mises en oeuvre

Les tables mises en oeuvre par la fonction sont les suivantes :

• Table ABATRQT
• Table ABATTAC
• Table ABATGRP