Executes a native operating system command on the host system running Adaptive Server.
xp_cmdshell command [, no_output]
is the operating system command string; maximum length is 255 bytes.
if specified, suppresses any output from the command.
Silently copies the file named log on the C drive to a file named log.0102 on the A drive:
xp_cmdshell 'copy C:\log A:\log.0102', no_output
Executes the operating system’s date command and returns the current date as a row of data:
xp_cmdshell 'date'
xp_cmdshell returns any output, including operating system errors, as rows of text in a single column.
xp_cmdshell is run from the current directory of the XP Server.
The width of the column of returned output is 80 characters. The output is not formatted.
xp_cmdshell cannot perform commands that require interaction with the user, such as “login”.
The user context in which an operating system command is executed via xp_cmdshell is controlled by the value of the xp_cmdshell context configuration parameter. If this parameter is set to 1 (the default), xp_cmdshell restricts permission to users with System Administration privileges at the operating system level. If this parameter is set to 0, xp_cmdshell uses the security context of the operating system account under which Adaptive Server is running. Therefore, using xp_cmdshell with the xp_cmdshell context configuration parameter set to 0, any user can execute operating system commands using the permissions of the account running Adaptive Server. This account may have fewer restrictions than the user’s own account.
See the System Administration Guide for more information about t xp_cmdshell context.
Regardless of the value of xp_cmdshell context, if the user who is executing xp_cmdshell is not a System Administrator (does not have the sa_role), a System Administrator must have granted that user explicit permission to execute xp_cmdshell. For example, the following statement grants “joe” permission to execute xp_cmdshell:
grant execute on xp_cmdshell to joe
To find out if xp_cmdshell was successful in spawning an external command XP Server, enter the following, where command is the name of the command you ran with xp_cmdshell:
@ret = exec xp_cmdshell command
If xp_cmdshell was successful, @ret = exec xp_cmdshell command returns a value of 0. If xp_cmdshell failed, @ret = exec xp_cmdshell command returns a value of 1.
To find out if the command you ran using xp_cmdshell was itself successful, enter the following, where command is the name of the command you ran with xp_cmdshell:
@ret = exec xp_cmdshell command, return_status
@ret = exec xp_cmdshell command, return_status causes xp_cmdshell to return the actual exit status code of the command. If a failure occurrs and XP Server cannot run the command, xp_cmdshell returns a value of 1. If the command runs successfully, xp_cmdshell returns a value of 0.
If the command was successful, @ret = exec xp_cmdshell command returns a value of 0. If the command failed, @ret = exec xp_cmdshell command returns a value of 1.
Both @ret = exec xp_cmdshell command and @ret = exec xp_cmdshell command,
return_status are backward-compatible.
Old stored procedures that do not use the return_status parameter
treat @ret = exec xp_cmdshell command,
return_status as if it were @ret = exec
xp_cmdshell command.
Also, the no_output parameter can still be used in combination with return_status, in any order.
By default, only a System Administrator can execute xp_cmdshell. A System Administrator can grant execute permission to other users.
