SXPG_COMMAND_EXECUTE: Check Authorization for and Execute an External Command

Use

Using this function module, you can check the authorization of a user to execute a particular external command and run the command:

  • with the arguments specified in ADDITIONAL_PARAMETERS

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

If an SAP profile parameter is 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 "security function module" is specified in the command definition, this function module is also called in the course of processingebenfalls. This function module can prevent execution of the command.

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

CALL FUNCTION 'SXPG_COMMAND_EXECUTE'
     IMPORTING
        COMMANDNAME     = <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.

Parameter

IMPORTING Parameter

Parameter Name

Use

COMMANDNAME

The name of the definition of the external command, as specified in the maintenance function (Transaction SM69).

OPERATINGSYSTEM and TARGETSYSTEM

Host system, in which the command is to be run. 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 program as specified by the calling program or user. These arguments are appended to any arguments specified in the external command 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, 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, 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 on the trace specification in the defitinition of the external command (Transaction SM69).

EXPORTING Parameter

Parameter Name

Use

STATUS

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

Value O: The external command was started and successfully run.

Value E: Error; the external command was not executed.

Table Parameter

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

Name

Meaning

X_ERROR

Reserved.

NO_PERMISSION

The AUTHORITY-CHECK of the user's authorization for the authorization object S_LOG_COM failed. The user is not authorized to execute the command with the specified arguments in thte 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 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.

    Or:

  • The command definition specifies that an additional check function module should be run. This function module rejected execution of the command.

WRONG_CHECK_CALL _INTERFACE

The command definition specifies that an extra check function should 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, 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, additional command arguments were 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.

I LLEGAL_COMMAND

The external command definition was "illegally" modified; that is, not using the maintenance function (Transaction SM69).

The modified command is registered in the system log in its substituted form. You can find the message under the system log ID LC.

WRONG_ASYNCHRONOUS_ PARAMETERS

Reserved.

CAT_ENQ_TBTCO_ENTRY and JOBCOUNT_GENERATION _ERROR

Reserved.

OTHERS

Catch any new exceptions added to this function module.