ADMIN_CMD procedure - Run administrative commands

The ADMIN_CMD procedure is used by applications to run administrative commands using the SQL CALL statement.

Syntax

Read syntax diagramSkip visual syntax diagramADMIN_CMD(command-string )

The schema is SYSPROC.

Procedure parameter

command-string
An input argument of type CLOB (2M) that specifies a single command that is to be executed.

Authorization

One of the following authorities is required to execute the routine:
  • EXECUTE privilege on the routine
  • DATAACCESS authority
  • DBADM authority
  • SQLADM authority

Default PUBLIC privilege

In a non-restrictive database, EXECUTE privilege is granted to PUBLIC when the procedure is automatically created.

The procedure supports the following command line processor (CLP) commands:
Note: Some commands might have slightly different supported syntax when run through the ADMIN_CMD procedure.

See DB2_LOAD_RESTRICTED_IO_PATH for security considerations when running these commands.

The procedure also supports the following commands which are not supported by the CLP:

Usage notes

Retrieving command execution information:
  • As the ADMIN_CMD procedure runs on the server, the utility messages are also created on the server. The MESSAGES ON SERVER option (refer to the specific command for further details) indicates that the message file is to be created on the server.
  • Command execution status is returned in the SQLCA resulting from the CALL statement.
  • If the execution of the administrative command is successful, and the command returns more than the execution status, the additional information is returned in the form of a result set (up to two result sets). For example, if the EXPORT command executes successfully, the returned result set contains information about the number of exported rows; however, if the RUNSTATS command executes successfully, no result set is returned. The result set information is documented with the corresponding command.
  • If the execution of the administrative command is not successful, an SQL20397W warning message is returned by the ADMIN_CMD procedure along with a result set containing more details about the reason for the failure of the administrative command. Any application that uses the ADMIN_CMD procedure should check the SQLCODE returned by the procedure. If the SQLCODE is >= 0, the result set for the administrative command should be retrieved. The following table indicates what information might be returned depending on whether the MESSAGES ON SERVER option is used or not.
    Table 1. SQLCODE and information returned by the ADMIN_CMD procedure
    Administrative command execution status MESSAGES ON SERVER option specified MESSAGES ON SERVER option not specified
    Successful The SQLCODE returned is >= 0: Additional information (result sets) returned, if any. The SQLCODE returned is >= 0: Additional information (result sets) returned, if any, but the MSG_RETRIEVAL and MSG_REMOVAL columns are NULL.
    Failed The SQLCODE returned 20397: Additional information (result sets) returned, but only the MSG_RETRIEVAL and MSG_REMOVAL columns are populated. The SQLCODE returned is < 0: No additional information (result sets) is returned.
  • The result sets can be retrieved from the CLP or from applications such as JDBC and CLI applications, but not from embedded C applications.
  • Case-sensitive names and double-byte character set (DBCS) names must be enclosed inside a backward slash and double quotation delimiter, for example, \" MyTabLe \".

For all commands executed through the ADMIN_CMD, the user ID that established the connection to the database is used for authentication.

Any additional authority required, for example, for commands that need file system access on the database server, is documented in the reference information describing the command.

This procedure cannot be called from a user-defined function (SQLSTATE 38001) or a trigger.