SXPG_COMMAND_EXECUTE: Check Authorization for and Execute an External Command

Use this function module to check a user’s authorization to run a particular external command and then carry out the command.

Like SXPG_COMMAND_CHECK, this function module checks that the user is authorized to execute the command:

· with the arguments specified in ADDITIONAL_PARAMETERS

· on the target host system, as identified by OPERATINGSYSTEM and TARGETSYSTEM.

If any SAP profile parameter has been inserted in the portion of the command stored in the database, then the value of this parameter is substituted into the command. If an SAP application server is active on the target system (TARGETSYSTEM), then the profile parameter values are read from the profile in effect on that system. No parameter substitution is made in ADDITIONAL_PARAMETERS.

After substitution, the command is checked for the presence of “dangerous” characters, such as the semicolon ; on UNIX systems.

If an additional “safety” function module has been specified in the definition of the command, then this is called as well in the course of processing. This function module can prevent execution of the command.

If the authorization checks complete successfully, then the command is run on the target host system.

Syntax:

CALL FUNCTION ‘SXPG_COMMAND_EXECUTE’
     IMPORTING
        COMMANDNAME     = <command name in SAP system>
        OPERATINGSYSTEM = <external command name>
                              “ Default SY-OPSYS
        TARGETSYSTEM    = <Target host name> “ Default SY-HOST
        STDOUT          = 'X' “ Log STDOUT if marked. Default
                              “ ‘X’
        STDERR          = 'X' “ Log STDERR if marked. Default
                              “ ‘X’
        TERMINATIONWAIT = ‘X’ “ Synchronous program start,
                              “ Wait for termination and
                              “ event log, if returned.
                              “ DEFAULT 'X'
        TRACE           = ‘ ‘ “ Trace execution. Unmarked, no
                              “ trace. If value TRACE_LEVEL3,
                              “ trace active
        ADDITIONAL_PARAMETERS = <user-specified argument string>
                              “ DEFAULT SPACE
        ABAPPROG = <ABAP program> “ Default space
        ABAPFORM = <ABAP form in program> “ Default space
        JOBCOUNT = <Job count> “ Reserved for future use.
                               “ 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 SAP 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
         WRONG_ASYNCHRONOUS_PARAMETERS “ Reserved for future
                                       “ use
         CAT_ENQ_TBTCO_ENTRY “ Reserved for future use
         JOBCOUNT_GENERATION_ERROR “ Reserved for future use
         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).
OPERATING SYSTEM and TARGETSYSTEM	Identify the host system on which the command is to be executed. OPERATINGSYSTEM is specified in the command definition (transaction SM69). TARGETSYSTEM is the host name of the system upon which the command is to run
ADDITIONAL_PARAMETERS	Arguments for the external command as specified by the calling program or user. These arguments are appended to any arguments specified in the externalcommand definition (DEFINED_PARAMETERS). These arguments are checked for impermissible characters, such as the ; under UNIX. Problems are registered with the SECURITY_RISK exception.
STDOUT	Log STDOUT output from the external command in EXEC_PROTOCOL, if set to a non-space value. If set to space, then STDOUT is ignored. Can be logged only if TERMINATIONWAIT has a non-space value (wait for termination).
STDERR	Log STDERR output from the external command in EXEC_PROTOCOL, if set to a non-space value. If set to space, then STDERR is ignored. Can be logged only if TERMINATIONWAIT has a non-space value (wait for termination).
TERMINATIONWAIT	Wait for termination of external command. If set to space ‘ ‘, then the command is started asynchronously and no output is collected from the command or from the target host system. If set to a value other than space, then the function module waits for the external command to complete. It also logs STDOUT and STDERR, if requested, in EXEC_PROTOCOL, if the TARGETSYSTEM returns this output.
TRACE	Trace execution through CALL ‘writetrace’ and through the local trace function of the external commands interface itself. If set to space ‘ ‘, then no trace is carried out. Otherwise, tracing is active. Should be used ONLY for testing. The setting of this argument has no effect upon the trace specification in the definition of the external command (transaction SM69).

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, if TERMINATIONWAIT is activated.

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 SAP 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 ADDITIONAL_PARAMETERS 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_PARAMETERS is required. However, no additional arguments string was supplied.
PROGRAM_START_ERROR	An error occurred while starting the external command. The SAP 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 SAP 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”.
WRONG_ASYNCHRONOUS_ PARAMETERS	Reserved for future use.
CAT_ENQ_TBTCO_ENTRY and JOBCOUNT_GENERATION _ERROR	Reserved for future use.
OTHERS	Catch any new exceptions added to this function module.