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.

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 :

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.stafile 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 :

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 :

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 :

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 activationis defined above) :

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

(NNNNNNNNrepresents 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