admin() and task() Function Return Codes

The admin() and task() functions perform equivalent tasks but produce different types of return codes. Use the admin() function if you want an integer return code, or the task() function if you want a textual return code.

When you run the admin() or task() function, it:

  • Performs the specified operation.
  • Returns a value that signifies whether the function succeeded or failed.
  • Inserts a row into the command_history table of the sysadmin database.

The return codes for the admin() and task() functions indicate whether the function succeeded or failed in different formats:

  • The task() function returns a textual message. The message is also inserted into the cmd_ret_msg column in the new row that the task() function inserts into the command_history table.
  • The admin() function returns an integer. This number is also inserted into the cmd_number column in the new row that the admin() function inserts into the command_history table.
    • If this value is greater than zero, the function succeeded, and a new row was inserted into the command_history table.
    • If this value is zero, the function succeeded, but Informix® could not insert a new row into the command_history table.
    • If this value is less than zero, the function failed, but a new row was inserted into the command_history table.

The operation that the admin() or task() function specifies occurs in a separate transaction from the insertion of the new row into the command_history table. If the command executes successfully, but the insertion into the command_history table fails, the command takes effect, but an online.log error entry indicates the problem.

If the command_history.cmd_number serial counter is 200 when this function is called, and the command succeeds, then Informix® executes the command and returns the integer 201. If the command fails, this example returns the value -201.

Suppose the task() function had executed the same command: 

EXECUTE FUNCTION task("check extents");
This command instructs the database server to check the extents, and returns a message indicating whether the command succeeded or failed.
If the command_history.cmd_number serial counter is 201 when this function is called, and the command fails, then the returned value is -202. Suppose that the next SQL administration API function that the DBSA invokes is this: 

EXECUTE FUNCTION admin('create dbspace',
   'dbspace2', '/work/CHUNKS/dbspace2', 20M);
If in this case the command succeeds, the returned value is 203. The DBSA can use the following query to examine the two rows of the command_history table that these calls to the admin() function inserted: 
SELECT * FROM command_history WHERE cmd_number IN (202,203);
This query returns two rows: 
cmd_number      202
cmd_exec_time   2009-04-17 16:26:14
cmd_user        informix
cmd_hostname    olympia
cmd_executed    create dbspace
cmd_ret_status  -1
cmd_ret_msg     Unable to create file /work/dbspace2
                
cmd_number      203
cmd_exec_time   2009-04-17 16:26:15
cmd_user        informix
cmd_hostname    olympia
cmd_executed    create dbspace
cmd_ret_status  0 
cmd_ret_msg     created dbspace number 2 named dbspace2
Note: When connected to a secondary node, the admin() function is disabled and will always return a value of -1. In addition, the task() function will return an error for commands that involve modifying disk structures, since these administrative actions are meant to be executed only on primary or standalone nodes.