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.

Nested Batch Files

When a batch file uses call to run another batch file, Windows may report an exit code of 0 for the outer batch file even though the inner batch file ended with a non-zero exit code (for example, using exit /b %ERRLVL%), and even though %ERRORLEVEL% shows the correct value in the outer batch file. adTempus reports the exit code that Windows returns, so the step appears to succeed.

To work around this, explicitly set the exit code at the end of the outer batch file:

@echo off
call inner_batch.bat
exit %ERRORLEVEL%

Programs That Work Outside adTempus

If a program or batch file works when you run it from a command prompt but fails when adTempus runs it, capture the console output and review it for error messages. The following are common causes of this kind of failure.

Permission and Environment Problems

When you test the program outside of adTempus, make sure you are logged in using the same user account that the job runs under. If the program requires Administrator permissions, make sure you have checked the Run with highest privileges option for the job.

Mapped Drive Letters

Jobs do not have access to drive letters that were mapped outside of adTempus. If your batch file uses a mapped drive letter, it will fail with the error "The system cannot find the drive specified." Replace the drive letter with the corresponding UNC path (for example, replace m:\inputfiles with \\prodserver3\data\inputfiles), or map the drive on the Resources page of the job. See Network Access for Jobs for more information.

Relative Paths

Fully qualify all paths and file names. A command such as myprogram /source \\prodserver3\data\*.* may work at a command prompt because the current directory is the folder containing the program, but fails in adTempus with the error "'myprogram' is not recognized as an internal or external command, operable program or batch file." Use the full path to the program (e.g., c:\processing\myprogram), or set the Startup Directory for the step.

Programs That Wait for Input

If the program displays a dialog box or prompts for input, it will appear to hang, because nobody can see or respond to the prompt. See Understanding Logon Sessions for information on running a job interactively so that you can see what the program is displaying.

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.