An agent is a special program that loops continuously under the control of the Job manager. It is similar in function to a Windows service.
The Job manager allows you to complete the following:
- Start or stop an agent (automatically or manually),
- Automatically restart an agent in the event of failure,
- Control agents remotely in batch mode or via the graphic interface.
The agents are implemented by loading an Adelia DLL in a specific process (GSAGENT.EXE). It is similar in function to the jobs run by host processes (GSHOST), except that it is possible to control how the agent is run. The command line is the same as the command line for a job.
The agents communicate with the Job manager (queries, status notifications) via a toolbox extension DLL (GSAGENTDLL).
As a rule, the standard algorithm for an agent will be an infinite loop.
* Main loop
RET_CODE = 1
DO_WHILE RET_CODE = 1
* do what the agent has to do
...
* timed wait
CALL_DLL 'GsAgentDll' 'GSATimedWait' NBR_SEC RET_CODE
REDO
* agent end
CALL_DLL 'GsAgentDll' 'GSASetState' *BLANK RET_CODE
When the Job manager requests an agent to stop, it sets the state of the agent to 'S' (Stop requested). The program implementing the agent is responsible for checking this state by means of the GSAGetState function (or a return code of '2' from the GSATimedWait function), and to take the necessary measures to stop it as quickly as possible when requested by the Job manager.
If a timeout is specified and the agent does not respond to the stop request within the requested time, it is stopped abruptly ("killed") once this time elapses, and the agent program is unable to do anything to stop this. This should be taken into account if the agent needs to carry out lengthy processes without interruption.
When it finishes, the agent must specify the stop state as ' ', 'E' or 'W' (stopped normally, with errors or with warnings) by means of the GSASetState function. If not, the Job manager sets the state to "Stopped with errors".
