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' or 'Result 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.

IBM CMOD arsdoc Return Codes

IBM Content Manager OnDemand's ARSDOC Return Codes

Return Code	Description
0	Success - There was no error.
1	No hits. There were no documents that met the search criteria.
2	Syntax error. For example, the parameter or value is invalid.
3	Generic Error. 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 due to it being down, or being unable to authenticate.
768	Warning - A limited number of results were returned. You probably used the -L # parameter to limit the number of returned hits from your query. See: ODUG Forums Post

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.

IBM CMOD arsload Return Codes

The Return Codes for Content Manager OnDemand's arsload utility are not well documented.

IBM Content Manager OnDemand's ARSLOAD Return Codes

Return Code	Description
0	Success There was no error.
2	Server is offline, unavailable, or unreachable. Check to see that your IBM OnDemand Server is operational, or that you can connect across the network if you are attempting to load remotely.
6	One of: Syntax Error The parameters you entered on the command line are incomplete or invalid. The arsload command parameter help was likely displayed. Processing error There was an error during processing, which lead to the failure of the arsload command, like ARS1127E.
13	Invalid User ID or Password. See ARS1105E for troubleshooting.

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 == 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