SXPG_CALL_SYSTEM: Run an External Command (Expres (SAP Library - Programming with the Background Processing System (BC-CCM-BTC))

SXPG_CALL_SYSTEM: Run an External Command (Express Method)

Use this function module to do the following:

check a user’s authorization to run a command
carry out the command.

To determine the system on which the command should be carried out, the function module takes by default the user’s current host system and the operating system type.

Since the function module is RFC-capable, you can use RFC (the remote function call interface) to carry run the function module at another R/3 application server. The external command is then carried out on the host system on which the destination server is running. See CALL FUNCTION... DESTINATION in the ABAP syntax documentation or User’s Guide for more information.

SXPG_CALL_SYSTEM checks the command that is specified in the call before carrying it out. The function module follows these rules in performing this check:

It checks for a command definition that has the same operating system type as in the system field SY-OPSYS. If found, then this command definition is used to run the command.
If the first check fails, then the function module looks to see if the command has been defined with an operating system type that belongs to the same syntax group as the SY-OPSYS operating system. A syntax group is an R/3 construct that groups together OS’s that share the same command and file name syntax. Example: the various flavors of UNIX belong to a syntax group.

If found, then this command definition is used to run the command. Example: If SY-OPSYS shows HP-UX as the OS, then a command definition for Sun UNIX would also be acceptable for carrying out the command.

If the second check also fails, then the function modules looks for the command with the operating system type ANYOS. ANYOS indicates that a command definition can be carried out on all supported host operating systems.

If found, then this command definition is used to run the command.

Syntax:

CALL FUNCTION ‘SXPG_CALL_SYSTEM’
IMPORTING
COMMANDNAME = <Name of command to run> " Default '*'
PARAMETERS = <Argument string> " Default <space>
EXPORTING
STATUS = <Exit status of command>
TABLES
EXEC_PROTOCOL = <Log> " In structure BTCXPM. Can
" contain STDOUT, STDERR
EXCEPTIONS
NO_PERMISSION " Command rejected by user exit auth.
" check
COMMAND_NOT_FOUND " Command not defined in R/3 database
PARAMETERS_TOO_LONG " Complete parameter string exceeds
" 128 characters
SECURITY_RISK " Security check failed
WRONG_CHECK_CALL_INTERFACE " Problem with function
" module for additional
" security check
PROGRAM_START_ERROR " Error while starting program
PROGRAM_TERMINATION_ERROR " Error while requesting final
" status of program
X_ERROR " Reserved
PARAMETER_EXPECTED " Required parameter not specified
TOO_MANY_PARAMETERS " User arguments not allowed by
" supplied in call
ILLEGAL_COMMAND " Command not legitimately defined
OTHERS

Parameters

IMPORTING Parameters

Parameter name	Use
COMMANDNAME	The name of the definition of the external command, as specified in the maintenance function (transaction SM69).
PARAMETERS	Arguments for the external command as specified by the definition in the R/3 System and by the calling program or user. These arguments are checked for impermissible characters, such as the ; under UNIX. Problems are registered with the SECURITY_RISK exception.

EXPORTING Parameters

Parameter name

Use

STATUS

Returns the final status of the execution of the external command:

· Value ‘O’: The external command was started and ran to end successfully.

· Value ‘E’: An error occurred; the external command was not run successfully.

Tables Parameters

Parameter name	Use
EXEC_PROTOCOL	Contains the STDOUT and STDERR output of the external command and any output from the target host system.

Exceptions

Exception name	Meaning
X_ERROR	Reserved for future use.
NO_PERMISSION	The AUTHORITY-CHECK of the user’s authorization for the authorization object S_LOG_COM failed. The user is not authorized to carry out the command named with the specified arguments on the target system.
COMMAND_NOT_FOUND	Command name, as identified by COMMANDNAME and OPERATINGSYSTEM, has not been defined in the maintenance function (transaction SM69).
PARAMETERS_TOO_LONG	The combined argument string (ADDITIONAL_PARAMETERS and the DEFINED_PARAMETERS, as returned in ALL_PARAMETERS) exceeds the limit of 128 characters in length.
SECURITY_RISK	Either: · The command contains impermissible characters. These are characters with potentially dangerous properties, such as ; under UNIX. · The command definition specifies that an extra-check function module be run. This function module has rejected execution of the command.
WRONG_CHECK_CALL_ INTERFACE	The command definition specifies that an extra-check function module is to be run. Either this function module is missing, or the interface defined for this function module does not match that of the standard R/3 function module SXPG_DUMMY_COMMAND_CHECK. For more information, please see SXPG_DUMMY_COMMAND_CHECK: Interface for Extra-Check Function Modules.
TOO_MANY_PARAMETERS	The command definition specifies that user-specified arguments for the external command are not allowed. However, an additional string of command arguments was specified.
PARAMETER_EXPECTED	The command definition includes the placeholder character ?, which signifies that additional user-defined arguments are required. However, no additional arguments string was supplied.
PROGRAM_START_ERROR	An error occurred while starting the external command. The R/3 system field SY-MSGV1 contains additional information on the problem.
PROGRAM_TERMINATION_ ERROR	An error occurred while trying to obtain the return code of the external program. The R/3 system field SY-MSGV1 contains additional information on the problem.
ILLEGAL_COMMAND	The external command definition was modified "illegally". That is, the command was not modified by means of the maintenance function (transaction SM69). The modified command is registered in the system log in its substituted form. The message is registered under the system log ID "LC".
OTHERS	Catch any new exceptions added to this function module.