[963] improve exit status

0 on success (or upgrade aborted by user)
1 on check and need update
2 on check and version of db too high
3 on command-line error
4 on db read error
5 on upgrade error

src/bin/dbutil/b10-dbutil.8

@@ -44,9 +44,9 @@ utility is a general administration utility for SQL databases\&. (Currently only
 \fBb10\-dbutil\fR
 operates in one of two modes, check mode or upgrade mode\&.
 .PP
-In check mode (\fBb10\-dbutil \-\-check\fR), the utility reads the version of the database schema from the database and prints it\&. It will tell you whether the schema is at the latest version supported by BIND 10\&.
+In check mode (\fBb10\-dbutil \-\-check\fR), the utility reads the version of the database schema from the database and prints it\&. It will tell you whether the schema is at the latest version supported by BIND 10\&. Exit status is 0 if the schema is at the correct version, 1 if the schema is at an older version, 2 if the schema is at a version not yet supported by this version of b10\-dbutil\&. Any higher value indicates a read or command\-line error\&.
 .PP
-When the upgrade function is selected (\fBb10\-dbutil \-\-upgrade\fR), the utility takes a copy of the database, then upgrades it to the latest version of the schema\&. The contents of the database remain intact\&. (The backup file is a file in the same directory as the database file\&. It has the same name, with "\&.backup" appended to it\&. If a file of that name already exists, the file will have the suffix "\&.backup\-1"\&. If that exists, the file will be suffixed "\&.backup\-2", and so on\&.)
+When the upgrade function is selected (\fBb10\-dbutil \-\-upgrade\fR), the utility takes a copy of the database, then upgrades it to the latest version of the schema\&. The contents of the database remain intact\&. (The backup file is a file in the same directory as the database file\&. It has the same name, with "\&.backup" appended to it\&. If a file of that name already exists, the file will have the suffix "\&.backup\-1"\&. If that exists, the file will be suffixed "\&.backup\-2", and so on)\&. Exit status is 0 if the upgrade is either succesful or aborted by the user, and non\-zero if there is an error\&.
 .PP
 When upgrading the database, it is
 \fIstrongly\fR

src/bin/dbutil/b10-dbutil.xml

@@ -73,7 +73,10 @@
       In check mode (<command>b10-dbutil --check</command>), the
       utility reads the version of the database schema from the database
       and prints it.  It will tell you whether the schema is at the latest
-      version supported by BIND 10.
+      version supported by BIND 10. Exit status is 0 if the schema is at
+      the correct version, 1 if the schema is at an older version, 2 if
+      the schema is at a version not yet supported by this version of
+      b10-dbutil. Any higher value indicates a read or command-line error.
     </para>
 
     <para>
@@ -85,7 +88,8 @@
       file.  It has the same name, with ".backup" appended to it.  If a
       file of that name already exists, the file will have the suffix
       ".backup-1".  If that exists, the file will be suffixed ".backup-2",
-      and so on.)
+      and so on). Exit status is 0 if the upgrade is either succesful or
+      aborted by the user, and non-zero if there is an error.
     </para>
 
     <para>

src/bin/dbutil/dbutil.py.in

@@ -47,6 +47,15 @@ isc.util.process.rename()
 # configure.ac)
 VERSION = "b10-dbutil 20120319 (BIND 10 @PACKAGE_VERSION@)"
 
+# Exit codes
+EXIT_SUCCESS = 0
+EXIT_NEED_UPDATE = 1
+EXIT_VERSION_TOO_HIGH = 2
+EXIT_COMMAND_ERROR = 3
+EXIT_READ_ERROR = 4
+EXIT_UPGRADE_ERROR = 5
+
+
 # @brief Statements to Update the Database
 # These are in the form of a list of dictionaries, each of which contains the
 # information to perform an incremental upgrade from one version of the
@@ -445,6 +454,12 @@ def check_version(db):
     an upgrade is needed.
 
     @param db Database object
+
+    returns 0 if the database is up to date
+    returns EXIT_NEED_UPDATE if the database needs updating
+    returns EXIT_VERSION_TOO_HIGH if the database is at a later version
+            than this program knows about
+    These return values are intended to be passed on to sys.exit.
     """
     current = get_version(db)
     latest = get_latest_version()
@@ -454,18 +469,18 @@ def check_version(db):
         info("database version " + version_string(current))
         info("this is the latest version of the database schema, " +
              "no upgrade is required")
-
+        return EXIT_SUCCESS
     elif match < 0:
         info("database version " + version_string(current) +
              ", latest version is " + version_string(latest))
         info("re-run this program with the --upgrade switch to upgrade")
-
+        return EXIT_NEED_UPDATE
     else:
         warn("database is at a later version (" + version_string(current) +
              ") than this program can cope with (" +
              version_string(get_latest_version()) + ")")
         info("please get the latest version of b10-dbutil and re-run")
-
+        return EXIT_VERSION_TOO_HIGH
 
 def perform_upgrade(db, upgrade):
     """
@@ -554,11 +569,11 @@ def parse_command():
     if (len(args) > 1):
         error("too many arguments to the command, maximum of one expected")
         parser.print_usage()
-        sys.exit(1)
+        sys.exit(EXIT_COMMAND_ERROR)
     elif len(args) == 0:
         error("must supply name of the database file to upgrade")
         parser.print_usage()
-        sys.exit(1)
+        sys.exit(EXIT_COMMAND_ERROR)
 
     # Check for conflicting options.  If some are found, output a suitable
     # error message and print the usage.
@@ -573,22 +588,23 @@ def parse_command():
 
     # Only get here on conflicting options
     parser.print_usage()
-    sys.exit(1)
+    sys.exit(EXIT_COMMAND_ERROR)
 
 
 if __name__ == "__main__":
     (options, args) = parse_command()
     db = Database(args[0], options.verbose)
+    exit_code = EXIT_SUCCESS
 
     if options.check:
         # Check database - open, report, and close
         try:
             db.open()
-            check_version(db)
+            exit_code = check_version(db)
             db.close()
         except Exception as ex:
             error("unable to check database version - " + str(ex))
-            sys.exit(1)
+            exit_code = EXIT_READ_ERROR
 
     elif options.upgrade:
         # Upgrade.  Check if this is what they really want to do
@@ -596,7 +612,7 @@ if __name__ == "__main__":
             proceed = prompt_user()
             if not proceed:
                 info("upgrade abandoned - database has not been changed\n")
-                sys.exit(0)
+                sys.exit(EXIT_SUCCESS)
 
         # It is.  Do a backup then do the upgrade.
         in_progress = False
@@ -613,9 +629,9 @@ if __name__ == "__main__":
             else:
                 error("upgrade preparation failed - " + str(ex))
                 info("database upgrade was not attempted")
-            sys.exit(1)
+            exit_code = EXIT_UPGRADE_ERROR
     else:
         error("internal error, neither --check nor --upgrade selected")
-        sys.exit(1)
+        exit_code = EXIT_COMMAND_ERROR
 
-    sys.exit(0)
+    sys.exit(exit_code)

src/bin/dbutil/tests/dbutil_test.sh.in

@@ -269,9 +269,9 @@ record_count_test() {
 check_version() {
     copy_file $1 $verfile
     ../run_dbutil.sh --check $verfile
-    if [ $? -ne 0 ]
+    if [ $? -gt 2 ]
     then
-        fail "version check failed on database $1"
+        fail "version check failed on database $1; return code $?"
     else
         ../run_dbutil.sh --check $verfile | grep "$2" > /dev/null
         if [ $? -ne 0 ]