Understanding and troubleshooting the Sage X3 Batch Server 

What is the Batch Server

As defined in the Online Help

 – Batch server

• The platform framework embeds a deferred (batch) tasks scheduling and monitoring function with a comprehensive parameters management for these processes
• i.e., is a thread running in background within the Syracuse (node.exe) context which monitors and manages a batch task queue (stored in table: X3.ABATRQT)

– Batch task

• Unlike an interactive session, a batch task is a process launched in background mode and monitored by the task scheduler (batch server)
• i.e., is a task added to the batch task queue to be launched and processed in a background session, controlled by the batch server 

Thread of execution running within the Syracuse context

• Once the batch server is started, will randomly select a Syracuse node and child process; within which the batch server thread will run
• Can configure the Batch Server to start-up automatically or not
• The batch server also launches a classic session (adonix.exe) which constantly runs until the batch server is shutdown. This process monitors and manages the batch job queue
• Batch tasks themselves, once eligible to be executed, are processed in their own new classic session 

Where is the batch server running?

Can check Administration, Usage, Sessions Management,Session Information

• or check Syracuse log files for the “batch” entries (if logging is enabled)
• or check via Batch Server (Action, Diagnoses)
• or can find in MongoDB collection “dbLocks” 

Batch Server configuration

• Administration, Administration, Endpoints, Batch Server (Syracuse layer)

“Maximum active queries” this runtime pool is spread across all runtime servers available to the batch server – Optionally use tags to control which Runtime servers are available

• “X3 server traces” shows the serveur.tra file
• Parameters, General Parameters, Parameter Values (Classic layer)
• Two parameters directly related to Batch Server

Parameters, Usage, Batch Server (Classic layer)

Task configuration

Usage, Batch Server, Task Management

Hourly constraints only apply to directly submitted batch tasks (not Recurring Tasks)

• Use “Single user” sparingly, as it can only run if able to get exclusive use of the Batch Server, it then blocks other tasks from running whilst it’s being executed.

Reports

Development, Script dictionary, Reports

Hourly constraints can apply to user submitted reports, as well as batch server task submission

• “Batch only” sets the report to only be runnable via the batch server 

Query (task) submission

Usage, Batch Server, Query submission

Click validation to enter any appropriate parameters

• Check “Template” to generate a template file to disk, if using file-based submissions (Change to “.job” file extension)

Recurring tasks

Usage, Batch Server, Recurring Task Management

• Won’t appear in the task queue as a separate entity until the first time it’s run
• “One single query” treats task as single task running continuously all day, although still only executes at the defined frequency 

Processing the batch task queue

When the batch server polling process wakes up, it reviews the tasks which are eligible to run and takes the oldest in the queue first. It can take multiple tasks from the queue, up to the number specified as the Maximum Queries, minus the number currently executing. – It will also consider things like “Allowable delay” and “Single user mode”, for example

• Then picks a process server to run on (round robin basis), then creates new classic sessions, one per new task to be executed. – In multiple runtime environment all these new sessions will go to the same runtime server, but the next cycle will recalculate the runtime server to be used.
• Once the batch task has completed, the classic session is closed.
• The batch server monitors for any tasks that need to be killed, for example where a “time-out” is specified for that task. 

See what’s going on

Usage, Batch Server, Query Management

Log button shows “serveur.tra”

• Query button allows you to submit new query
• SELECTION, Selection allows you to filter the list using calculation 

• Usage, Batch Server, Query Management
• To remove a task (that has not yet started), click the line and use the “delete” button (on the right)

Usage, Batch Server, Query Management

• Running tasks can be interrupted if required. This marks them to be killed in the next Batch Server cycle
• Administration, Administration, Endpoints, Batch server
• Select “List of queries”

– More intuitive filtering available 

Batch server logs

The batch server logs are located in “.. \Folders\X3\SRV\TRA” directory

– “serveur.tra” is the overall log file

– “RQTxxxxxx.tra” individual batch task log file

• Also check “.. \Folders\X3\SRV\tmp” directory for any temporary files
• There may be additional task specific output files in the child folder TRA directory, for example in “..\Folders\SEED\TRA” for the Accounting Entry process 

Syracuse logging

Change Syracuse logging to give more information • Navigate to Administration, Administration, Settings, Global Settings In the logs section, set the following parameters to ensure the log files can grow big enough for the logging needed, and the log files do not get removed too quickly. These suggested settings assume you have the default values currently set: -- Maximum file size (MB) set to "200" (10 default) -- Maximum number of days "15" ( 5 default) In the "Server Logs" section, set the following sections to "Info" or "Debug" log level --- batch Add any other settings related to the issue you are experiencing, for example the classic sessions logging may often also be useful: --- session --- x3Comm.client --- x3Comm.dispatcher --- x3Comm.print --- x3Comm.runtime --- x3Comm.sadfsq NOTE: changes take effect immediately when you save. Ensure you reset back to the original values (Generally “Error”) once the troubleshooting process is complete. 

Engine tracing

Available from 2021 R3

• Navigate to Administration, Usage, Logs, X3 session logs – “Batch query” type allows you to enable tracing for specific batch jobs. Enter just the task code, and/or can enter a specific task number