Collecting Return Codes from CMOD utilities

Background

In almost all operating systems, in addition to processing data and providing output (either processed data, or a log of the work that was performed) processed provide what is called a 'Return Code' to quickly and easily indicate the status of the program at the time it stopped processing -- and Content Manager OnDemand is no different. All of the utilities provide 'return codes' or 'exit codes' when a utility stops processing. The return code is normally a single integer number, whose meaning is determined by the author of the utility, and normally available as part of the documentation. The only real standard is that 0 means a successful completion, and any other integer indicates a warning or error condition. Think of a '0' return code as "nothing to report" value.

Values and Meanings for return code numbers

Exit codes used by Content Manager OnDemand's ARSDOC Utility

Return Code	Description
0	Success
1	No hits
2	Syntax error. For example, the parameter or value is invalid.
3	An error occurred with the specified request. For example: the user ID has an incorrect permission level, the specified folder does not exist, or the specified database field does not exist.
4	Unrecoverable error. For example, the operation failed, or the user cannot connect to the server.

Unfortunately, utilities like arsdb, arsload, arssockd, and arsxml don't have documented return codes in IBM's Content Manager OnDemand official documentation. However, it's safe to assume that a non-zero exit code means there was a warning or error encountered, and the results should be investigated.

Capturing the Return Code from IBM CMOD ARSLOAD command on UNIX / Linux

To use the return code from a utility in a CMOD script, use the following process:

Execute the command you want to check on:

arsload -h localhost -u arsload -p /path/to/stash.file -g ApplicationGroup -a Application File.To.Load

Immediately afterwards, assign the 'return code' built-in variable to a variable you can re-use:

ARSLOAD_RC=$?

The $? special built-in variable is overwritten after each and every command that is executed in a shell, so don't insert any commands between it and the command you want the return code for!

Now that you have the return code, you can print the result...

echo "ARSLOAD returned: $ARSLOAD_RC"

... or use the 'if' command to decide to do something, like paging an administrator to alert them when a load failed.

if [[ $ARSLOAD_RC ]] ; then
  echo "The load was successful!"
else
  echo "There was a warning or error!"
  /path/to/Page_Administrator_Script "There was an error loading a file into CMOD!"
fi