Batch Jobs
The following section describes the functionality provided for submitting background processes on-line. You use this functionality to submit your adhoc background processes or to submit a special run for one of your scheduled background processes.
For information on creating batch processes, see Defining Background Processes.
Contents
The on-line batch submission page enables you to request a specific background process to be run. When submitting a background process on-line, you may override standard system parameters and you may be required to supply additional parameters for your specific background process. After submitting your background process, you may use this page to review the status of the submission.
The following topics further describe logic available for on-line submission of background processes.
Contents
Batch Submission Creates a Batch Run
Jobs Submitted in the Background
Running Multi-threaded Processes
Lifecycle of a Batch Job Submission
Batch Submission Creates a Batch Run
When you request a batch job to be submitted from on-line, the execution of the desired background process will result in the creation of a batch run. Just as with background processes executed through your scheduler, you may use the Batch Run Tree page to view the status of the run, the status of each thread, the run-instances of each thread, and any messages that might have occurred during the run.
Note. Your on-line submission record is assigned a status value so that you may know whether your job has been submitted and whether or not it has ended, however, it will not contain any information about the results of the background process itself. You must navigate to the Batch Run Tree page to view this detail.
Jobs Submitted in the Background
When you save a record on the batch job submission page, the batch job does not get submitted automatically. Rather, it saves a record in the batch job table. A special background process will periodically check this table for pending records and will execute the batch job. This background process will update the status of the batch job submission record so that a user can determine when their job is complete.
Note. At installation time, your system administrator will set up this special background process to periodically check for pending records in the batch job submission table. Your administrator will define how often the system will look for pending records in this table.
It should be noted that this special background process only submits one pending batch job submission record at a time. It submits a job and waits for it to end before submitting the next pending job.
Note. If you request a batch job to be run multi-threaded, the special background process will submit the job as requested. It will wait for all threads to complete before marking the batch job submission record as ended. Refer to Running Multi-threaded Processesfor more information.
Email Notification
If you wish the system to inform you when the background process completes, you may supply your email address. The email you receive will contain details related to the batch job’s output; similar to the job results you would see from your batch scheduler.
Note. This assumes that during the installation process, your system administrator configured the system to enable email notification. Your administrator may also override the amount of detail included in the email notification.
Running Multi-threaded Processes
Many of the system background processes may be run multi-threaded. When submitting a background process on-line, you may also run a multi-threaded process or run a single thread of a multi-threaded process. The fields Thread Count and Thread Number on the batch submission page control the multi-threaded process requests:
· To run a multi-threaded process, indicate the number of threads in Thread Count and enter 0 in the Thread Number. For example, to run the account debt monitor (ADM) with 10 threads, enter Thread Count = 10 and Thread Number = 0. This will execute all 10 threads of ADM.
· To run a single thread in a multi-threaded process, indicate the number of threads in Thread Count and indicate the Thread Number you would like to run. For example, to run only thread 1 out of 10 threads for the account debt monitor (ADM), enter Thread Count = 10 and Thread Number = 1. This will execute thread 1 out of 10 for ADM.
· To run a process as a single thread, enter Thread Count = 1 and Thread Number = 1. This will execute the background process single-threaded.
Note. When running a multi-threaded process, the special background process will wait until all threads are complete before marking the batch job submission record as ended.
Batch Jobs May End in Error
It is possible for your background process to end with an error. Refer to Dealing With Abnormally Terminated Batch Processes for more information about this. When this occurs, your batch job submission record will still be marked as ended. You will need to navigate to the Batch Run Tree page to determine the status of the batch run.
Submitting Jobs in the Future
If you wish to request a batch job to be submitted in the future, you may do so when creating your batch job submission record by entering a future submission date. The special background process, which looks for pending records in the batch job submission table, will only submit batch jobs that do not have a future submission date.
Lifecycle of a Batch Job Submission
The following diagram illustrates the lifecycle of a batch job submission record.
Pending Records are created in Pending status. Records in this state are put in a queue to be submitted.
Canceled Users may Cancel a pending record to prevent the batch job from being submitted.
Started Once a pending record has been submitted for processing, its status will be changed to Started. Records in this status may not be canceled.
Ended When the batch job has finished processing, its status will be changed to Ended. Note that records in Ended status may have ended in error. Refer to Batch Jobs May End in Error for more information.
Batch Job Submission - Main
This page allows you to submit a batch job on-line. Navigate to this page using Main Menu, Batch, Batch Job Submission.
Description of Page
The Batch Job ID is a system generated random number that identifies a particular submission.
To submit a batch job, choose the Batch Code for the process you wish to submit.
List of system background processes. The list of background processes provided in the base product may be viewed in the application viewer's batch control viewer.
The following parameters are provided with each background process:
Thread Number Thread number is used to control whether a background processes is run single threaded or in multiple parallel threads. It contains the relative thread number of the process. For example, if the billing process has been set up to run in 20 parallel threads, each of the 20 instances receives its relative thread number (1 through 20). Refer to Running Multi-threaded Processes for more information about populating this field.
Note. Not all processes may be run multi-threaded. Refer to the description of a batch control to find out if it runs multi-threaded.
Thread Count Thread count is used to control whether a background processes is run single threaded or in multiple parallel threads. It contains the total number of threads that have been scheduled. For example, if the billing process has been set up to run in 20 parallel threads, each of the 20 instances receives a thread count of 20. Refer to Running Multi-threaded Processes for more information about populating this field.
Batch Rerun Number Rerun number is only used for background processes that download information that belongs to given run number. It should only be supplied if you need to download an historical run (rather than the latest run).
Batch Business Date Business date is only used for background processes that use a date in their processing. For example, billing using the business date to determine which bill cycles should be downloaded. If this parameter is left blank, the system date is used at the time the background process is executed.
Note that saving a record on this page does not submit the batch job immediately. A special background process will run periodically to find pending records and submit them. Depending on how often the special process checks for pending records and depending on how many other pending records are in the ‘queue’, there may be a slight lag in submission time. If the desired execution date/time is close to midnight, it is possible that your batch job will run on the day after you submit it. If you have left the business date blank in this case, keep in mind that your business date would be set to the day after you submit the job.
Override Nbr Records To Commit and Override Max Timeout Minutes. These parameters are optional and override each background process’s Standard Commit Records and Standard Cursor Re-Initiation Minutes (each background process’s Standard Commit Records / Standard Cursor Re-Initiation Minutes is documented in the list of system background processes). Note that Max Timeout Minutes corresponds to the Cursor Re-initiation Minutes.
Refer to Parameters Supplied to Background Processesfor more information.
User ID Enter the user ID for the background process. Refer to Parameters Supplied to Background Processesfor more information about the significance of the user id.
Default Note. This field defaults to the id of the current user.
Password Password is not currently used.
Language Code Language code is used to access language-specific control table values. For example, error messages are presented in this language code.
If you wish the system to notify you when the batch job is complete, enter your Email ID. Refer to Email Notification for more information.
Default Note. This field defaults to the email address for the current user, if populated on the user record.
The Desired Execution Date/Time defaults to the current date and time. Override this information if you wish the background process to be executed at some future date and time. Refer to Submitting Jobs in the Future for more information.
The Batch Job Status indicates the current status of the batch job. Refer to Lifecycle of a Batch Job Submission for more information.
The Program Name associated with the batch control code is displayed.
The following trace parameters may also be supplied to a background process and are only used during QA and benchmarking.
Trace Program Start Turn on this switch if you wish a message to be written whenever a program is started.
Trace Program Exit Turn on this switch if you wish a message to be written whenever a program is exited.
Trace SQL Turn on this switch if you wish a message to be written whenever an SQL statement is executed.
Trace Output Turn on this switch if you wish a message to be displayed for special information logged by the background process.
Note. The information displayed when the trace output switch is turned on depends on each background process. It is possible that a background process displays no special information for this switch.
Note. The location of the output of this trace information is defined by your system administrator at installation time.
If additional parameters have been defined for this background process on the Batch Control page, the Parameter Name, Description, Detailed Description and an indicator of whether or not the parameter is Required are displayed. Enter the desired Parameter Value for each parameter.
Each of the batch processes has, as part of its run parameters, a preset constant that determines how many errors that batch process may encounter before it is required to abort the run. You can override this constant with an optional additional parameter (MAX-ERRORS). The input value must be an integer that is greater than or equal to zero. The maximum valid value for this parameter is 999,999,999,999,999.
Once you have entered all the desired values, Save the record in order to include it in the queue for background processes.
If you wish to duplicate an existing batch job submission record, including all its parameter settings, display the submission record you wish to duplicate and use the Duplicate and Queue button. This will create a new Batch Job Submission entry in pending status. The new submission entry will be displayed.
If you wish to cancel a Pending batch job submission record use the Cancel button. The button is disabled for all other status values.
The batch process pages show the execution status of batch processes. For a specified batch control id and run id, the tree shows each thread, the run-instances of each thread, and any messages (informational, warnings, and errors) that might have occurred during the run. Refer to Defining Batch Controls for more information on how batch control codes are defined.
Contents
Dealing With Abnormally Terminated Batch Processes
Batch Run Tree - Main
This page allows you to view the status of a specific execution of a batch job. Navigate to this page using Main Menu, Batch, Batch Run Tree.
Description of Page
Select a Batch Control process and Batch Number to view information and statistics on the batch run’s “threads”. The concept of a “thread” is a bit difficult to explain. The following points should help understand this concept:
· Many batch jobs cannot take advantage of your hardware’s processing power when they are run singularly. Rather, you’ll find that a large percentage of the CPU and/or disk drives are idle.
· In order to minimize the amount of idle time (and increase the throughput of your batch processes), we allow you to set up your batch processes so that multiple instances of a given batch job are executed at the same time. For example, when you schedule the billing process, you can indicate that multiple parallel instances should be executed (rather than just one instance). You’d do this so that the processing burden of creating bills for your customers can be spread over multiple processes.
· We refer to each parallel execution of a batch process as a “thread”.
· Statistics and information messages are displayed in respect of each thread. Why? Because each thread is a separate execution and therefore can start and end at different times.
The tree includes a node that displays the total number of records processed for the batch run, the total number of records in error for the batch run and the batch run elapsed time. The elapsed time is the longest elapsed time among the batch thread(s). The message is red if there are any records in error.
If the background process has been enabled to create To Do entries for object specific errors, information about the To Do entries are displayed in the tree. This information is not displayed for each thread, but rather all the To Do entries created for the batch run are grouped together. The To Do entries are grouped by their status.
The messages that appear under a thread always show the start and end times of the execution instance. If errors are detected during the execution of the thread, these error messages may also appear in the tree. Refer to Processing Errors for information about the types of errors that appear in the batch run tree.
Batch Run Tree - Run Control
By default, if a batch process fails, it will restart. This notebook tab allows you to modify the restart status of a failed run.
Navigate to this page using Main Menu, Batch, Batch Run Tree, Run Control.
Description of Page
On the main page, you must select a Batch Control, Batch Number, and Batch Rerun Number to view a tree of the batch run. On this page, the following information is displayed:
· Date Time contains the date and time this batch run last start or last completed.
· Batch Business Date is the business date that was supplied to the background process (this date is used as the “system date” by the process).
Run Status indicates the status of the batch run. Valid values are: In Progress, Error, and Complete.
If the Run Status is Error, the system will attempt to restart this run when you attempt to execute the Batch Control. In most situations, this is exactly what you want to happen. However, there are rare situations where you do not want the system to execute a given batch run (e.g., if this run is somehow corrupt and you cannot correct the data for whatever reasons). If you want the system to skip the execution of a batch run (and proceed to the next run), turn on Do Not Attempt Restart.
Dealing With Abnormally Terminated Batch Processes
When a batch process abnormally terminates, its status remains In Progress. This is because there is no way for the terminated job to execute logic that would cause its status to be Error.
Circumstances that can cause abnormal termination include:
· A process encounters a severe database error.
· An operator manually terminates a process that is locked in an infinite loop.
Because the batch process’s status is In Progress, the system will not know that it should be restarted the next time the batch process is requested. Therefore, you must change the status of the batch run and its threads to be Error in order for the system to restart the process. To do this, you must run another batch process called UPDERR – Change A Batch Run’s Status to Error.