IBM Tivoli Storage Manager, Version 7.1

Client return codes

The backup-archive command-line interface and the scheduler exit with return codes that accurately reflect the success or failure of the client operation.

Scripts, batch files, and other automation facilities can use the return code from the command-line interface. For operations that use the Tivoli® Storage Manager scheduler, the return codes are shown in the output of the QUERY EVENT administrative command.

In general, the return code is related to the highest severity message during the client operation.

An exception to these rules is made when warning or error messages indicate that individual files could not be processed. For files that cannot be processed, the return code is 4. Examine the dsmerror.log file to determine the cause of errors that occur during client operations. Errors that occur during scheduled events are recorded in the dsmsched.log file.

Table 1 describes the return codes and their meanings.

Table 1. Client return codes and their meanings
Code Explanation
0 All operations completed successfully.
4 The operation completed successfully, but some files were not processed. There were no other errors or warnings. This return code is common. Files are not processed for various reasons; the following reasons are the most common.
  • The file satisfies an entry in an exclude list. Excluded files generate log entries only during selective backups.
  • The file was in use by another application and could not be accessed by the client.
  • The file changed during the operation to an extent prohibited by the copy serialization attribute. See Copy serialization attribute.
8 The operation completed with at least one warning message. For scheduled events, the status is Completed. Review the dsmerror.log file (and dsmsched.log for scheduled events) to determine what warning messages were issued and to assess their impact on the operation.
Windows operating systems 12 The operation completed with at least one error message (except for error messages for skipped files). For scheduled events, the status is Failed. Review the dsmerror.log file (and dsmsched.log for scheduled events) to determine what error messages were issued and to assess their impact on the operation. Generally, this return code means that the error was severe enough to prevent the successful completion of the operation. For example, an error that prevents an entire drive from being processed yields return code 12.
AIX operating systems HP-UX operating systems Linux operating systems Oracle Solaris operating systems Mac OS X operating systems 12 The operation completed with at least one error message (except for error messages for skipped files). For scheduled events, the status is Failed. Review the dsmerror.log file (and dsmsched.log for scheduled events) to determine what error messages were issued and to assess their impact on the operation. Generally, this return code means that the error was severe enough to prevent the successful completion of the operation. For example, an error that prevents an entire file system or file specification from being processed yields return code 12.
other For scheduled operations where the scheduled action is COMMAND, the return code is the return code from the command that was run. If the return code is 0, the status of the scheduled operation is Completed. If the return code is nonzero, then the status is Failed.

Some commands might issue a nonzero return code to indicate success. For these commands, you can avoid a Failed status by wrapping the command in a script that starts the command, interprets the results, and exits. The script should produce return code 0 if the command was successful, or a nonzero return code if the command failed. Then, ask your Tivoli Storage Manager server administrator to modify the schedule definition to run your script instead of the command.

The return code for a client macro is the highest return code that is issued among the individual commands that comprise the macro. For example, suppose a macro consists of these commands:

AIX operating systems HP-UX operating systems Linux operating systems Oracle Solaris operating systems Mac OS X operating systems
selective "/home/devel/*" -subdir=yes
incremental "/home/devel/TestDriver/*" -subdir=yes
archive "/home/plan/proj1/*" -subdir=yes
Windows operating systems
selective c:\MyTools\* -subdir=yes
incremental c:\MyPrograms\TestDriver\* -subdir=yes
archive e:\TSM\* -subdir=yes

If the first command completes with return code 0, and the second command completes with return code 8, and the third command completed with return code 4, the return code for the macro is 8.

For more information about the QUERY EVENT command, see the IBM® Tivoli Storage Manager Administrator's Reference that is appropriate for your operating system.



Feedback