Submission of the requests via the intermediary of files

Prerequisites

In order that the batch launch of the requests can be made via the intermediary of files, it is necessary :

    That the general parameter Use of batch files is set to Yes in the batch server parameters.

    That the EXTBATCH parameter is set to Yes. This parameter, which belongs to the group SUP, can be defined at the level of the folder and user. It is thus possible to globally prohibit the batch launch of requests in this way for a given folder, by according if necessary an exception to the designated users.

The files in the request (extension req)

The launch of a batch request can be carried out by placing a file with the extension .job in the directory dedicated to these files. This file must be of the type ASCII, structured with a line ending by <CR> or <CR><LF>, each line defining the value of a parameter in the form :

PARAMETER=VALUE

Certain parameters are mandatory and identify the execution context of the request. Other parameters depend on the request to be launched : their name corresponds to the name of the parameters defined in the screen associated with the launch of the request. In certain cases, a table of parameters is defined in the screen ; the syntax is then PARAMETER(index)=VALUE, index being a numeric value.

In order to facilitate the creation of such a file, it is possible to launch the request from the software by checking the template box in the request launch screen. If this is done, a file contains a complete list of launch parameters and their value will be created in the launch directory. This file is created with the name of the request and the .mod extension.

In the table below are the names of the mandatory parameters and their definition.

PARAMETER	DEFINITION
DOSSIER	The code for the folder in which the request must be launched.
UTIL	The code for the connection user in the folder
PASSE	The encrypted password for the user
GRP	The group of requests (if a group is launched)
TACHE	The request (if a request is launched)
DATE	The launch date (with the format YYYYMMDD)
HEURE	The launch time (with the format HHMM)

it should be noted that the parameter values are given without any sort of separator and that it is possible to insert comment lines prefixed with the character #. Thus the following can be entered in the requests file :

         # Mandatory parameters

         DOSSIER=DEMO (folder)

         DATE=20020614

        …

       # Additional parameters

       PARAM(1)=TEST

        PARAM(2)=ABC

Process cycle for the request files

The batch server checks at regular intervals the contents of the directory dedicated to the request files. During the checks, it reads the files present in the directory taking them in order of their ASCII classification. Thus, it is advisable to name these files with a fixed root and a sequential number on a fixed length. They can for example be named REQ000001.req, REQ0000002.req

During the processing of this file, the files are created successively in the different directories defined by the batch server parameters. These fields are defined below :

PROCESS STEP	FILES UPDATED
Batch process request made	Creation of the file xxxxx.job using an external process, in the dedicated directory.
The batch server takes into account the request and updates its table of requests to be launched.	The file xxxxx.job  is renamed xxxxx.req (and moved if the directories are not the same)
The server detects an error in the parameters file (password incorrect, task code unknown...)	The file xxxxx.job  is renamed xxxxx.old (and moved if the directories are not the same) A file xxxxx.sta is created in the dedicated directory. It contains an error code that is used to identify that the receipt file format was incorrect (see the file format below).
The request is in execution, the batch server having launched it.	The file xxxxx.req  is renamed xxxxx.old (and moved if the directories are not the same) A file named xxxxx.run is created in a dedicated directory.
The request is terminated (correctly or with an error)	The file xxxxx.run is deleted, and a file xxxxx.sta is created in the dedicated directory : this file contains a return status (see the file format below).
An interruption request made to the batch request (pending launch or already launched).	Creation of the file xxxxx.kil using an external process, in the dedicated directory.
Take into account the interruption request (if the request is not yet launched)	The file xxxxx.req (or the file xxxxx.job if it has not yet been taken into account) is renamed as xxxxx.old. The file xxxxx.sta is created in the dedicated directory. It contains an error code that is used to identify that the request has been interrupted without having been launched. The file xxxxx.kil is deleted.
Take into account the interruption request (if the request is already launched and not yet terminated)	The request is interrupted by killadx, then the file xxxxx.sta is created in the dedicated directory, with an error code that is used to identify that the request has been interrupted. The files xxxxx.kil and xxxxx.run are deleted.
Taking into account the execution priorities or the stopping of the batch server, the request could not be launched within the planned lead-time (request out of time)	The request is not launched, but the file xxxxx.req (the file xxxxx.jobin certain cases) is renamed xxxx.old and moved if necessary. A file xxxxx.sta is created in the dedicated directory. It contains an error code that is used to identify that the request could not be launched.

It should be noted that the fact that a file xxxxx.run exists does not necessarily signify that the request in question is running. In fact, if the batch server has been stopped without the requests that were running on it being stopped, the corresponding xxxxx.run files will still exist even when the request should have terminated its process. In this case, the xxxxx.sta will no longer be created. On the other hand, when the batch server is relaunched, the xxxxx.run file will be deleted, a xxxxx.sta file containing a specific status then being created.

The number of batch requests currently being processed can therefore not strictly be deduced from the number of xxxxx.run files present in the dedicated directory.

Description of the files XXX.sta, XXX.run, XXX.kil

These files are ASCII files, coded in ASCII 8 bits, present in the different directories according to the parameterization :

• The .kil file can be empty or contain a comment that will be picked up in the file with the extension .sta
• The .run file contains a line conforming with the structure defined below, the information registered being the request number, the start date and time and the task code (the other information will be filled with 0 or spaces)
• The file .sta contains a line whose format is defined below, all the fields being entered.

The structure of the only line contained in the files .run and .sta is the following :

• The line is composed of 8 fields with fixed length, with the separators (the colon character ‘ :’).
• The total length is 154 to 155 characters

The exact structure is the following :

Status no.	Request no.	Start date and time	End date and time	Folder code	User code	Task code	Message	End of line
NNNNN	NNNNNNNN	YYYYMMDDHHMMSS	YYYYMMDDHHMMSS	DDDDDDDDDD	UUUUU	TTTTTTTTTT	XXXXXXXXXXXXXXXXXX	<CR> or <CR><LF>
5 numbers	(8 numbers)	(14 numbers)	(14 numbers)	(10 characters)	(5 characters)	(10 characters)	(80 characters)	(1 or 2 bytes)

The message field is used to explain the error code if necessary. It is fixed length stored on 80 characters (the message being completed by spaces if necessary).

The request number stored on 8 characters, prefixed with zeros if necessary. This number is used to identify the log file name generated on the execution of the request. In fact, this file is called RQTNNNNNNNN.tra (NNNNNNNN being the request name in 8 characters). It is located in the TRA sub-directory of the folder SERVX3. It should be noted that this number can be null in certain error cases, when no request could be launched.

The task code corresponds to the task or linked tasks launched, and it is by this name that it is known in the task/linked tasks table.

The status code, over 5 numeric characters is used to identify the execution result. The first number determines the global result of the execution, the following numbers giving the additional information. When the request is terminated without error or without warning, then the error code equals to 0000. The detail of the codes is given below :

Value of the error code over 5 numbers				Message
First number	Meaning	Supplement	Meaning
0	Normal end to processing	0000	Without warning	REQUEST TERMINATED
		NNNN	With NNNN warnings in the log file (9999 if 9999 or more)	REQUEST TERMINATED WITH WARNINGS
1	Process end with error	0000	Non specified error (for example if GOK=-1 and no additional information)	REQUEST TERMINATED WITH UNKNOWN ERROR
		1NNN	Error no NNNN from Adonix engine (message M)	END ON ADONIX ERROR : M
		2000	Locking error (GOK=0)	LOCKING ERROR
		3NNN	Logic error in processing with : NNN = variable value GERRBATCH, M = variable value GMESSBATCH	REQUEST TERMINATED WITH ERROR M
			Important note : The variables GERRBATCH and GMESSBATCH make it possible for a developer to qualify precisely the error conditions and this is possible both for a specific/custom task and also a standard task by means of entry points. The value of the variable GERRBATCH influences the what follows the process, when this is integrated in a group of tasks. In fact, if the GERRBATCH variable is strictly less than 100, the task that will follow will be launched despite the error. If however GERRBATCH has a value greater than or equal to 100, the next tasks in the group will not be launched.
2	Process not launched	1000	The task has been programmed for a given time, but it could not be launched within the given time.	TIME EXCEEDED
		2000	Non existent task	TTT TASK NON EXISTENT
		3000	Authorization (not specified)	PROCESS NOT LAUNCHED BECAUSE OF A NON SPECIFIED AUTHORIZATION PROBLEM
		3100	Authorization (user U unknown)	USERU UNKNOWN
		3200	Authorization (password incorrect for user U)	PASSWORD INCORRECT FOR THE USER U
		3300	Authorization (refused by entry point)	PROCESS NOT LAUNCHED BECAUSE RIGHTS REFUSED BY ENTRY POINT
		3400	Authorization (level N for the task prohibited for user U insufficient)	ACCESS LEVEL N NOT AUTHORIZED FOR THE USER U
		3500	Authorization (function F not authorized for the user U)	F FUNCTION NOT AUTHORIZED FOR USER U
		4NNN	Passage mono user mode impossible (NNN users in process)	PASSAGE TO MONO MODE IMPOSSIBLE BECAUSE NNN USERS CONNECTED
		5000	Process T non existent	PROCESS T NON EXISTENT
3	Process stop	0000	Stopping of the process, reason unknown (for example if a process other than the batch server has killed the request)	REQUEST INTERRUPTED (REASON UNKNOWN)
		1000	By the file extension .kil, containing the message M	REQUEST INTERRUPTED BY U FOR THE REASON M
			NB: The user code can be empty in the case of a kill by file. In fact, the system tries to discover, from the identity of the user who created the file, if an Adonix user code corresponds or not. This search may not function according to the operating systems used.
		2000	By the task management and the user U : the message entered is M	REQUEST INTERRUPTED BY U FOR THE REASON M
		3000	By the batch server because of time-out	PROCESS INTERRUPTED BY THE SERVER REASON=TIME EXCEEDED

Remarks

It should be noted that, in the case of batch task templates (GTRAITE template), the user has the following variables available, accessible in the specific/custom tasks, or in the standard tasks by means of the entry points :

• The variable GOK is an update status from the launch of the task. It will be 1 if there are no problems, 0 in the case of a locking problem, -1 in the case of another serious error and 2 for a serious coherence error for the server. This variable is managed by the standard tasks : if it is not 1 at the end of the batch process, the task appears with the status Error in the task management ; in this case, if the task belongs to a group of tasks, the remaining tasks are blocked and will never be launched.
• The variable GERREUR only updates a blank value in the case of an error during the execution of an instruction (this is the error number corresponding to an exception processed by the instruction Onerrgo). If this variable is not blank at the end of the task, the task status is set to Aborted in the task management and if it belongs to a group tasks, the remaining tasks are blocked.
• The variable GERRTRACE is used to count the number of error lines in the log file created by the task. It is also managed by the standard tasks. The fact that it is positive places the task in Error in the task management, without however blocking the running of the remaining tasks in a group. This is in fact a count of the number of error lines that are supposed to be benign.
• The variable GERRBATCH is an additional numeric variable, which is used to give an error code depending on the task if it is considered that the task has not been correctly terminated (this is independent of whether the error log lines have been generated or not). If the value of the GERRBATCH is less than and not equal to 100, it is considered that the error status is benign. If on the other hand the value of GERRBATCH is greater than or equal to 100, the status of the task in the task management function passes to Error at the end of the execution, and if the task belongs to a group, the running of the remaining tasks is interrupted. This variable has been created to allow management of a specific/custom error by means of an entry point.
• The variable GMESSBATCH is an alphanumeric variable that is used to give an additional error message. This message is inserted in the contents of a file with the extension .sta if an error occurs.

Except for a coherence error on launch, the standard batch tasks in the software consider in all cases that the errors encountered are benign and simply update the log file by incrementing GERRTRACE. This signifies that any serious error interrupting the process must be processed in a specific/custom fashion, by means of entry points, by giving to GERRBATCH a value greater than 100.

Description of the file server.tra

This file, present in the TRA sub-directory of the SERVX3 directory, contains the server log. The structure of the lines conforms to that of a classic log file (standard header and numeric statuses over 5 characters). Each line is composed of a text potentially prefixed by a number (this number is itself preceded by the character < if it is considered an error, by = if it is a warning).

The following status numbers exist (they are prefixed by 4 and 5 for reasons of continuity with the previous statuses). It is to be noted that the statuses starting with 4 are the serious statuses that should not occur during normal operation (update, task management, batch server locking problems), and can either originate as system problems, from a bad installation or other reasons. The statuses starting with 5 are the normal statuses for the batch server activity :

SERIOUS SERVER COHERENCE ERRORS
Status	Explanation	Text
41000	De-synchronization task	DE-SYNCHRONIZATION TASK ERROR
42000	Problem with access to the tasks table	ACCESS ERROR WITH TASK TABLE
43000	Non existent request number	REQUEST NON EXISTENT ERROR
44000	Problem with access to the batch parameters table

 

NORMAL OPERATION MESSAGES FOR THE SERVER
50000	Server start-up	BATCH SERVER START-UP
51000	Request activation (process id P)	REQUEST ACTIVATION PID=P
52NNN	Adonix error NNN during server start-up (error message = M)	SERVER START-UP ERROR M
53000	Other error at server start-up	UNDETERMINED ERROR AT SERVER START-UP
54000	Launch of the server when it is already active	THE SERVER IS ALREADY ACTIVE
55000	Stopping the batch server

Description of the files RQTNNNNNNNN.tra

These files, present in the sub-directory TRA of directory SERVX3, containing the log associated with the request itself. The structure of the lines conforms to that of a classic log file (standard header and numeric statuses over 5 characters). Each line is composed of a text prefixed by a number (this number is itself preceded by the character < if it is considered an error or warning). These fields can be read directly from the request management by means of the right click / Read log.

After the header line, the first line in such a file is displayed in the form of a line with the following format (it includes the status Request activation is defined above) :

=51000 NNNNNNNN DD/MM/YY hh :mm :ss Request activation (51000)

(NNNNNNNN represents the task number in this case)

The classic log file lines for the task follow this first line (if the process in question is not launched in batch, these lines will be written in a classic log file FNNNNN.tra in the directory TRA of the launch folder). Then, except in the case where the task has been brutally stopped (for example by a killadx), a final line of an identical structure will be found, but where the number conforms to the status of a correct end (00000) or error (1NNNN) described above.

Tables used

The tables used by the function are as follows :

• Table ABATRQT
• Table ABATTAC
• Table ABATGRP