Troubleshooting Failed Jobs

When an adTempus job fails, the instance is listed in the job's history and in the Failed Jobs view 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. For example, if adTempus cannot find the program that it is supposed to be running.

Errors Reported by Tasks

When a step fails because of an error returned by the program or script being run by adTempus, the Job Log will generally have a warning message similar to this:

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. adTempusdoes 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" program that writes output to the console when you run it from a command prompt, capture the program's output (see below) 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 (see below) and review it for error messages.

Capturing Console Output

Console-mode programs are programs that are designed to be run from the command prompt or automation tool. Instead of showing a graphical 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, select the Capture screen output from console-mode program option in the Program Execution Task Properties.

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.