Support

Diagnosing job failures

Article ID: K00000184
Last Updated: February 27, 2022

Applies To

adTempus 3
adTempus 4
adTempus 5

Introduction

When an adTempus job fails, the instance is listed in the job's history with a status of "Failed", and the Job Log shows the message "Job finished with status "Failed".

To determine the reason for the failure, you must examine the Job Log (one of the tab pages at the bottom of the window when you select the failed job in the adTempus Console) for other messages for the failed instance, or examine the step that failed.

There are two primary categories of job failure:

Some problem prevented adTempus from running the job, or one of its steps (an error reported by adTempus).
One of the steps returned a result indicating failure (an error reported by the scheduled task).

Error Reported by adTempus

When adTempus encounters a problem that prevents it from running a job or job step, it writes a message to the Job Log describing the problem. These problems are generally easy to identify and resolve based on the error message provided by adTempus.

Errors Reported by Scheduled Tasks

When a step fails because of an error returned by the program being run by adTempus, the Job Log will generally have a warning message with message code 333:

Step failed because the program run by adTempus returned an exit code of 1, which indicates failure. Consult the documentation or output from the program for information on the meaning of this exit code.

You can also find the exit code for a step by displaying the details for the failed job instance and looking at the Steps page. The step that failed will have a status of "Failed", and will generally have a Result value other than 0. This Result is the exit code (or return code) returned by the program that adTempus ran.

The exit code is a numeric code that a program returns to adTempus when it finishes running, which can be used by the program to indicate whether it ran successfully. Most applications use an exit code of 0 to indicate success, and values other than 0 to indicate warning or error conditions.

However, there is no formal standard for exit codes, and no generic list of what exit codes mean. The meaning of the exit code is determined by whoever wrote the program that is being run. Arcana Development does not know what, for example, an exit code of "42" from your application means. To find out, you must check the documentation of the program that is being run.

How adTempus Determines "Failure"

By default adTempus treats an exit code of 0 as success, and anything else as failure. That is, if the program that adTempus runs returns an exit code other than 0, adTempus will report the step as "Failed".

This behavior can be changed on the Advanced page of the Program Execution Task Properties window. The Success Criteria section lets you define the rules adTempus will use to interpret the exit code.

Diagnosing Failure Exit Codes

If your job fails due to a "failure" exit code you must first determine whether the program did actually fail. For example, some programs may use a non-zero exit code to indicate success. In this case, you need to change the Success Criteria as described above.

Once you have determined that the program is in fact failing you must look to that program for information on what caused the failure.

First, check the documentation for the program in question for information on the meaning of the exit code being reported.

Next, look for error messages being reported by the program:

Does the program produce a log file containing error messages, or write messages to the computer's Event Log? If so, check these.
If the program is a "console mode" (command-line) program or batch file that writes output to the window when you run it from a command prompt, capture the program's output and review it for error messages.

Batch Files

When adTempus runs a batch file, the exit code it receives is the exit code from the last program executed by the batch file. To determine where a failure is occurring in a batch file, capture the output from the batch file and review it for error messages.

Capturing Console Output

Console-mode programs are programs that are designed to be run from the command prompt. Instead of showing a Windows user interface, they write output directly to the console window. If an error occurs in such a program it will often write an error message to the console.

When you run a console-mode program in adTempus you can "capture" the output from the program so that you can review it for error messages. To do so:

In adTempus 3 and earlier, change the Window Mode (on the General page of the Program Execution Task Properties window) to "Capture Console".
In adTempus 4 and later, check the Capture screen output from console-mode programs box on the Execution Target page of the Program Execution Task Properties window.

After the job runs, display the instance's details in the job history. The Captured Files tab will contain a file named "console output.txt" for each step; this file contains the console output for the program and should be reviewed for error messages.

Testing Outside of adTempus

It is often useful to test your program or batch file outside of adTempus. This can make it easier to spot problems, and also helps to determine whether the issue is caused by being run from adTempus. Ideally you should test while logged in under the same user account that adTempus uses for the job, to rule out the possibility of security-related issues.

After you run a program or batch file from a command prompt, you can display the exit code by executing this command immediately after the program or batch file completes:

echo %errorlevel%

This is the exit code that would be returned to adTempus.