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.

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 :

• Table ABATRQT
• Table ABATTAC
• Table ABATGRP