Pros and Cons of Implementing Exit Codes in Admin Commands

Admin Overall Task List

Introduction

This topic discusses the details of exit codes from asadmin command line. This is an often requested feature that is rarely tracked.

A classic example of an application of this property is start-domain.

  • If the server is not running, you run start-domain and it starts up fine. Return is ZERO for success.
  • If the server is not running, you run start-domain and it doesn't start. Return is NON-ZERO for failure.
  • If the server is already running, you run start-domain and – now what? Is it an error because it could not be started because it is already running? Or is it a success because the server is in the state you wanted – running?

This last point is a gray area. In fact over the course of version 7,8 and 9 the error code returned has been both!

We propose here to break the ancient convention of zero==success and non-zero==failure and add grayness.

  • Zero: This means that we successfully did what you told us to do. Period. If you ran stop-domain and there was no domain running, zero will not be returned.
  • One: There was an error. This is not gray but, rather, black. Whatever you told us to do completely failed. E.g. stop-domain was run, the domain was running, and we could not stop it.
  • Everything Else: Gray area. Each command defines what these return values mean. E.g. with the start-domain command a returned 2 means that the domain is already running.