The ADMIN_CMD procedure is used by applications to run
administrative commands using the SQL CALL statement.
Syntax
>>-ADMIN_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 currently supports the following DB2® command line processor (CLP)
commands:
Note: Some commands might have slightly different supported syntax
when executed through the ADMIN_CMD procedure.
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 procedureAdministrative 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.