Le lancement de requêtes adonix via le serveur batch peut être piloté depuis une fonction adonix dédiée : le lancement de requêtes. Mais il est aussi possible de piloter le lancement de requêtes batch par le serveur en déposant des fichiers ascii contenant la définition de la requête dans un répertoire défini dans les paramètres du serveur. Ceci permet ainsi de déclencher des requêtes batch à partir de progiciels de supervision externes. Ce document décrit en détail les fichiers à mettre en place, ainsi que la cinématique d’exécution de ces requêtes.

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.

PARAMETRE

DEFINITION

DOSSIER

Le code du dossier sur lequel la requête doit être lancée

UTIL

Le code de l’utilisateur de connexion au dossier

PASSE

Le mot de passe crypté de l’utilisateur

GRP

Le groupe de requêtes (si un groupe est lancé)

TACHE

La requête (si une requête est lancée)

DATE

La date de lancement (au format AAAAMMJJ)

HEURE

L’heure de lancement (au format HHMM)

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 :

ETAPE DE TRAITEMENT

FICHIERS MIS A JOUR

Dépose d’une demande de traitement batch

Création du fichier xxxxx.job par un processus externe, dans le répertoire dédié.

Le serveur batch prend en compte la demande et met à jour sa table de requêtes à lancer

Le fichier xxxxx.job  est renommé en xxxxx.req (et déplacé si les répertoires ne sont pas les mêmes)

Le serveur détecte une erreur dans le fichier de paramètres (mot de passe incorrect, code tâche inconnu…)

Le fichier xxxxx.job  est renommé en xxxxx.old (et déplacé si les répertoires ne sont pas les mêmes). Un fichier xxxxx.sta est créé dans le répertoire dédié. Il contient un code d’erreur permettant de savoir que le fichier d’entrée était incorrect (cf. format du fichier ci-dessous).

La requête est en cours d’exécution, le serveur batch l’ayant lancé

Le fichier xxxxx.req est renommé en xxxxx.old (et déplacé si les répertoires ne sont pas les mêmes). Un fichier nommé xxxxx.run  est créé dans le répertoire dédié.

La requête est terminée (correctement ou avec une erreur)

Le fichier xxxxx.run est effacé, et un fichier xxxxx.sta est créé dans le répertoire dédié : ce fichier contient un statut de retour (cf.  format du fichier ci dessous).

Dépose d’une demande d’interruption de requête batch (en attente de lancement ou déjà lancée)

Création du fichier xxxxx.kil par un processus externe dans le répertoire dédié

Prise en compte de la demande d’interruption (si la requête n’est pas encore lancée)

Le fichier xxxxx.req (ou le fichier xxxxx.job s’il n’avait pas encore été pris en compte) est renommé en xxxxx.old. Le fichier xxxxx.sta est créé dans le répertoire dédié. Il contient un code erreur permettant de savoir que la requête a été interrompue sans avoir été lancée. Le fichier xxxxx.kil est effacé.

Prise en compte de la demande d’interruption (si la requête est déjà lancée et pas encore terminée)

La requête est interrompue par killadx, puis le fichier xxxxx.sta est créé dans le répertoire dédié, avec un code erreur permettant de savoir que la requête a été interrompue. Les fichiers xxxxx.kil et xxxxx.run sont effacés.

Compte tenu des priorités d’exécution ou de l’arrêt du serveur batch, la requête n’a pas pu être lancée dans les délais prévus (requête hors délai)

La requête n’est pas lancée, mais le fichier xxxxx.req (le fichier xxxxx.job le cas échéant) est renommé en xxxx.old et déplacé si nécessaire. Un fichier xxxxx.sta est créé dans le répertoire dédié. Il contient un code erreur permettant de savoir que la requête n’a pas pu être lancée.

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.sta contenant 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 :

No statut

No requête

Date et heure début

Date et heure fin

Code dossier

Code utilisateur

Code de la tâche

Message en clair

Fin de ligne

NNNNN

NNNNNNNN

AAAAMMJJHHMMSS

AAAAMMJJHHMMSS

DDDDDDDDDD

UUUUU

TTTTTTTTTT

XXXXXXXXXXXXXXXXXX

<CR>
ou <CR><LF>

5 chiffres

(8 chiffres)

(14 chiffres)

(14 chiffres)

(10 caractères)

(5 caractères)

(10 caractères)

(80 caractères)

(1 ou 2 octets)

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 :

Valeur du code erreur sur 5 chiffres

Message en clair

Premier chiffre

Signification

Complément

Signification

 

0

Fin normale de traitement

0000

Sans avertissement

REQUETE TERMINEE

NNNN

Avec NNNN avertissements dans la trace (9999 si 9999 ou plus)

REQUETE TERMINEE  AVEC AVERTISSEMENTS

1

 

 

Fin de traitement sur erreur

 

 

0000

Erreur non spécifiée (par exemple si GOK=-1 et pas d’informations supplémentaires)

REQUETE TERMINEE AVEC ERREUR INCONNUE

 1NNN

Erreur no NNNN du moteur adonix (message M)

FIN SUR ERREUR ADONIX : M

 2000

Erreur de verrouillage (GOK=0)

ERREUR DE VERROUILLAGE

 3NNN

Erreur logique de traitement avec : NNN = valeur variable GERRBATCH,
M = valeur variable GMESSBATCH

REQUETE TERMINEE AVEC ERREUR M

Note importantes :

  • les variables GERRBATCH et GMESSBATCH permettent à un développeur de qualifier de façon, précise des conditions d’erreur, et ceci est possible à la fois sur une tâche spécifique, mais aussi sur une tâche standard par le biais de points d’entrée.

  • La valeur de la variable GERRBATCH influe sur la suite du traitement, lorsque celui-ci est intégré dans un groupe de tâches. En effet, si la variable GERRBATCH est strictement inférieure à 100, la tâche qui suit va être lancée malgré l’erreur. Si par contre GERRBATCH a une valeur supérieure ou égale, les tâches suivantes dans le groupe ne sont pas lancées.

2

 

 

 

 

 

Traitement non lancé

 

 

 

 

 

1000

La tâche a été programmée à une heure donnée, mais n’a pas pu être lancée dans les délais prévus.

DELAI DEPASSE

2000

Tâche inexistante

TTT TACHE INEXISTANTE

3000

Habilitation (non spécifié)

TRAITEMENT NON LANCE CAR PROBLEME D’HABILITATION NON SPECIFIE

 3100

Habilitation (utilisateur U inconnu)

UTILISATEUR U INCONNU

 3200

Habilitation (mot de passe incorrect pour utilisateur U)

MOT DE PASSE INCORRECT POUR L’UTILISATEUR U

 3300

Habilitation (refus par point d’entrée)

TRAITEMENT NON LANCE CAR DROITS REFUSES PAR POINT D’ENTREE

3400

Habilitation (niveau N de la tâche interdit à l’utilisateur U insuffisant)

NIVEAU D’ACCES N NON AUTORISE A L’UTILISATEUR U

3500

Habilitation (fonction F non autorisée à l’utilisateur U)

F FONCTION NON AUTORISEE A l’UTILISATEUR U

4NNN

Passage en mode mono impossible (NNN utilisateurs en cours)

PASSAGE EN MODE MONO IMPOSSIBLE CAR NNN UTILISATEURS CONNECTES

5000

Traitement T inexistant

TRAITEMENT T INEXISTANT

3

Arrêt du traitement

0000

Arrêt du traitement, raison inconnue (par exemple si un processus autre que le serveur batch a tué la requête)

REQUETE INTERROMPUE (RAISON INCONNUE)

1000

Par fichier d’extension .kil, contenant le message M

REQUETE INTERROMPUE PAR U POUR LE MOTIF M

Note : dans le cas d’un kill par  fichier, le code utilisateur peut être vide. En effet, le système essaie de retrouver, à partir de l’identifié de l’utilisateur ayant créé le fichier, si un code utilisateur adonix correspond ou pas. Cette recherche peut ne pas fonctionner selon les systèmes d’exploitation utilisés.

2000

Par la gestion des tâches et l’utilisateur U : le message saisi est M

REQUETE INTERROMPUE PAR U POUR LE MOTIF M

3000

Par le serveur batch car time-out

TRAITEMENT INTERROMPU PAR LE SERVEUR RAISON=DEPASSEMENT DU TEMPS ACCORDE

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 :

ERREURS GRAVES DE COHERENCE DU SERVEUR

Statut

Explication

Texte

41000

Désynchronisation tâche

ERREUR DESYNCHRONISATION TACHE

42000

Problème d’accès à la table des tâches

ERREUR D’ACCES A LA TABLE DES TACHES

43000

Numéro de requête inexistant

ERREUR REQUETE INEXISTANTE

44000

Problèmes d’accès à la table des paramètres batch

 

 

MESSAGES D’EXPLOITATION NORMAUX DU SERVEUR

50000

Démarrage du serveur

DEMARRAGE SERVEUR BATCH

51000

Activation requête (process id P)

ACTIVATION REQUETE PID=P

52NNN

Erreur adonix NNN au démarrage serveur (message d’erreur = M)

ERREUR AU DEMARRAGE DU SERVEUR M

53000

Erreur autre au démarrage du serveur

ERREUR INDETERMINEE AU DEMARRAGE DU SERVEUR

54000

Lancement serveur alors qu’il est déjà actif

LE SERVEUR EST DEJA ACTIF

55000

Désactivation serveur

 

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ête défini ci-dessus) :

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

(NNNNNNNN repré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 :