Collecting Return Codes from CMOD utilities
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
|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:
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 == 0 ]] ; 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