documented okapi update problems

bin/dbupdate.php

@@ -26,7 +26,10 @@
   system('php maintain.php');
 
   // We do *two* tests for OKAPI presence to get some robustness agains internal OKAPI changes.
-  // This should be replaced by a facade function call.
+  //
+  // This should be replaced by a facade function call, but current OKAPI implementation
+  // does not work well when called from the command line, due to exception handling problems
+  // (see http://code.google.com/p/opencaching-api/issues/detail?id=243).
   $okapi_vars = sql_table_exists('okapi_vars');
   $okapi_syncbase = sql_field_exists('caches','okapi_syncbase');
   if ($okapi_vars != $okapi_syncbase)

bin/okapi-update.php

@@ -22,6 +22,12 @@
 		$GLOBALS['rootpath'] = dirname(__FILE__) . '/../htdocs/';
 		require_once($GLOBALS['rootpath']."okapi/facade.php");
 		okapi\Facade::database_update();
+			// This may not work properly if an OKAPI update mutation function relies
+			// on catching exceptions. The cryptic error message
+			//   "exception thrown without a stack frame in Unknown on line 0"
+			// may appear (see http://code.google.com/p/opencaching-api/issues/detail?id=243).
+			// Then, you must call OKAPI update manually via
+			//   http://site-address/okapi/update
 	}
 
 ?>