CALL FUNCTION ... STARTING NEW TASK

CALL FUNCTION

Variant 2

CALL FUNCTION func ...STARTING NEW TASK task name.

1. ... DESTINATION dest
2. ... DESTINATION IN GROUP group name
3. ... DESTINATION IN GROUP DEFAULT
4. ... PERFORMING form ON END OF TASK
5. ... EXPORTING p1 = f1 ... pn = fn
6. ... TABLES p1 = itab1 ... pn = itabn
7. ... EXCEPTIONS syst_except = rc MESSAGE mess

Effect

Starts the function module func asynchronously in a new session. In contrast to normal function module calls, the calling program resumes processing as soon as the function module is started in the target system. It does not wait until the function module has finished. Through CALL SCREEN, the called function module can, for example, display a screen and thus interact with the user.

Notes

This variant applies only from R/3 Release 3.0, so both the client system and the server system must have Release 3.0.

With this variant, the called function module must also be flagged in the Function Builder as externally callable, even if it is executed locally (without the addition DESTINATION).

There can be no function call to the destination 'BACK' in the called function module (for more information about the destination 'BACK', see CALL FUNCTION func DESTINATION dest ).

This variant does not support the execution of external programs accessible via the destination of the TCP/IP type as asynchronous calls (see the Transaction Tools -> Administration, Administration -> Network -> RFC destinations for maintaining destinations).

From Release 4.0, you can check the load of each RFC destination more closely (in the RFC destination maintenance for an R/3 connection, choose Destination -> ARFC options). This checks whether the target host has sufficient resources before the function module is executed. If the target host is overloaded, the system delays executing the function module. The algorithm for calculating the load on the target host is the same one used in an asynchronous RFC call using the DESTINATION IN GROUP addition. Note that this option can only be used with target hosts running Release 3.1H or higher.

In principle, parallelization makes sense whenever application servers have the necessary resources. In this case, the application servers must be configured with at least 3 dialog work processes.

A program that is run in the background and uses RFC parallelization requires at least 1 dialog work process per application server because dialog processes use parallel execution.

If the instance profile parameter 'auth/rfc_authority_check' is set (to 1), the system automatically performs an RFC authorization check. The authorization check refers to the relevant function group for the function module to be called. If no authorization is found, a runtime error occurs. You can check the authorization in advance with the function module AUTHORITY_CHECK_RFC.

When you are using asynchronous RFC to implement parallel windows, all these windows are closed if the caller session is the only session and terminates.

Effect

Executes the function module externally as a Remote Function Call (RFC); dest can be a literal or a variable. The R/3 System where the function module is executed depends on the specified destination. Externally callable function modules must be flagged as such in the Function Builder (of the target system).

Note

If the destination is not explicitly specified, the system uses the default destination 'NONE'.

Note

If an error occurs in the target system during a Remote Function Call, details from the error message are returned to the calling system (SY-MSGNO, SY-MSGID, SY-MSGTY, SY-MSGV1, SY-MSGV2, SY-MSGV3, and SY-MSGV4). These fields are initialized at the start of every RFC call.

Note

Note that there is a database commit after every Remote Function Call (RFC). Consequently, you may not use RFCs between SQL statements that open and close a database cursor (example: SELECT...ENDSELECT).

Effect

You use this addition to perform parallel execution of function modules (asynchronous calls) on a predefined group of R/3 System application servers.

You use addition 2 (DESTINATION IN GROUP group name) to perform parallel execution of function modules on a predefined group of application servers. To maintain the RFC groups, choose Tools -> Administration -> Administration -> Network -> RFC destinations -> RFC -> RFC groups . The application programmer is responsible for the availability of RFC groups in the production system.

You use addition 3 (DESTINATION IN GROUP DEFAULT) to perform parallel execution of function modules (asynchronous calls) on all currently available R/3 System application servers. However, instead of this variant, you are recommended to use an RFC group with appropriate resources for parallel processing of asynchronous calls (at least for performance reasons). Please note that the addition DESTINATION IN GROUP ' ' has the same effect as the addition DESTINATION IN GROUP DEFAULT.

When you first call a function module with these additions, the system initializes the specified RFC group (provided no explicit initialization has already been performed).

To obtain current information about resources (that is, the number of resources available to process function modules), you can also initialize the RFC group explicitly in the program via the function module SPBT_INITIALIZE. You must perform this action before the first function module call.

In both cases, the system first determines the number of currently available resources (work processes) on the available application servers (either a group of servers or all servers). By checking the current system load of each application server, the system determines how many work processes are available to execute asynchronous calls.

After determining the available resources, the asynchronous call is executed to one of the destinations. If no resources are available at that particular time, the system executes the exception routine RESOURCE_FAILURE (see the addition EXCEPTIONS). In the case of an asynchronous function module call, this exception must be handled by the application program (see example).

Resource Limits

No resources are made available by the system if any of the following limits is exceeded:

Notes

In order to be taken into consideration for RFC parallel processing, an application server must therefore have at least 3 free dialog processes.

The system triggers the exception RESOURCE_FAILURE only for asynchronous RFCs with the additions DESTINATION IN GROUP group name and DESTINATION IN GROUP DEFAULT.

At present, only one RFC group per program environment is supported for parallel execution of asynchronous calls. Using both the additions DESTINATION IN GROUP group name and DESTINATION IN GROUP DEFAULT in a program is thus not allowed.

To find out which destination was automatically selected, call the function module SPBT_GET_PP_DESTINATION immediately after the function module call with the two additions. This returns the selected RFC destination.

If you want to delete an application server from the list of the configured RFC group at runtime (for example, when the application server is not accessible for technical reasons), use the function module SPBT_DO_NOT_USE_SERVER.

While the parameters for receiving results (i.e. IMPORTING and TABLES parameters) are specified directly as additions in the case of "conventional" function modules (see variant 2), these are logged in the FORM routine form when making an asynchronous call (see RECEIVE).

Notes

If a function module returns no result, and you are not interested in error messages that arise when executing the function module, this addition (... PERFORMING form ON END OF TASK) can be omitted.

If you want to handle the error messages that arise when executing the asynchronous function module call, you must use this addition. Also, when receiving the results in the FORM routine (see RECEIVE), you must react accordingly to the system exceptions SYSTEM_FAILURE and COMMUNICATION_FAILURE.

With asynchronous RFC, the task name uniquely identifies the asynchronous connection and thus the context called.

If several asynchronous function modules are executed consecutively to the same destination, you must assign a different task name to each.

A calling program that starts an asynchronous RFC with PERFORMING form ON END OF TASK cannot switch roll areas or change to an internal mode. This is because the asynchronous function module call reply cannot be passed on to the relevant program. You can perform a roll area switch with SUBMIT or CALL TRANSACTION.

If a calling program makes asynchronous calls, finishes, and then expects responses, these responses cannot be admitted.

To wait for the reply to a started asynchronous function module, use the WAIT command with the addition PERFORMING form ON END OF TASK. Here, WAIT must be in the same program context (mode).

Effect

EXPORTING passes values of fields and field strings from the calling program to the function module. In the function module, the formal parameters are defined as import parameters.

Effect

While any exceptions arising in the called function module are handled by the second addition (in the FORM routine), this addition can handle two special system exceptions, as with function module calls with the addition DESTINATION:

SYSTEM_FAILURE

is triggered, if a system crash occurs on the receiving side.

COMMUNICATION_FAILURE

is triggered if there is a connection or communication problem.

In both cases, you can get a description of the error with the optional addition

... MESSAGE mess

Note

In principle, you should always react to these two system exceptions, whether you are making an asynchronous function module call or receiving results.

Asynchronous call to a transaction and display as modeless dialog box.

DATA: MSG_TEXT(80) TYPE C. "Message text 
... 
* Asynchronous call to Transaction SM59 --> 
* Create a new session 
CALL FUNCTION 'ABAP4_CALL_TRANSACTION' STARTING NEW TASK 'TEST' 
  DESTINATION 'NONE' 
  EXPORTING 
	TCODE = 'SM59' 
  EXCEPTIONS 
	COMMUNICATION_FAILURE = 1 MESSAGE MSG_TEXT 
	SYSTEM_FAILURE		= 2 MESSAGE MSG_TEXT. 
 
  IF SY-SUBRC NE 0. 
	WRITE: MSG_TEXT. 
  ELSE. 
	WRITE: 'O.K.'. 
  ENDIF.

Using RFC groups to parallelize function module calls (RFC parallel processing)

DATA: INFO LIKE RFCSI, C,  "Message text 
	JOBS TYPE I VALUE 10,  "Number of parallel jobs 
	SND_JOBS TYPE I VALUE 1,  "Sent jobs 
	RCV_JOBS TYPE I VALUE 1,  "Received replies 
	EXCP_FLAG(1) TYPE C,  "Number of RESOURCE_FAILUREs 
	TASKNAME(4) TYPE N VALUE '0001',  "Task name administration 
	BEGIN OF TASKLIST OCCURS 10, 
		 TASKNAME(4) TYPE C,  "Administration of tasks 
		 RFCDEST	 LIKE RFCSI-RFCDEST, 
	END OF TASKLIST. 
... 
DO. 
 ... 
  CALL FUNCTION 'RFC_SYSTEM_INFO' 
	 STARTING NEW TASK TASKNAME DESTINATION IN GROUP DEFAULT 
	 PERFORMING RETURN_INFO ON END OF TASK 
	 EXCEPTIONS 
		 COMMUNICATION_FAILURE = 1 
		 SYSTEM_FAILURE		= 2 
		 RESOURCE_FAILURE	= 3. 
 
  CASE SY-SUBRC. 
	WHEN 0. 
* Administration of asynchronous tasks 
	TASKLIST-TASKNAME = TASKNAME. 
	CLEAR TASKLIST-RFCDEST. 
	APPEND TASKLIST. 
	WRITE: /  'Started task: ', TASKLIST-TASKNAME COLOR 2. 
 
	TASKNAME = TASKNAME + 1. 
	SND_JOBS = SND_JOBS + 1. 
	JOBS	 = JOBS - 1.  "Number of existing jobs 
	IF JOBS = 0. 
		EXIT.  "Job processing finished 
	ENDIF. 
	WHEN 1 OR 2. 
* Handling of communication and system failure 
		... 
	WHEN 3.  "No resources available at present 
* Receive reply to asynchronous RFC calls 
	IF EXCP_FLAG = SPACE. 
		 EXCP_FLAG = 'X'. 
* First attempt for RESOURCE_FAILURE handling 
		 WAIT UNTIL RCV_JOBS >= SND_JOBS UP TO '0.01' SECONDS. 
	ELSE. 
* Second attempt for RESOURCE_FAILURE handling 
		 WAIT UNTIL RCV_JOBS >= SND_JOBS UP TO '0.1' SECONDS. 
	ENDIF. 
	IF SY-SUBRC = 0. 
		CLEAR EXCP_FLAG.  "Reset flag 
	ELSE.  "No replies 
		"Endless loop handling 
		... 
	ENDIF. 
	ENDCASE. 
ENDDO. 
... 
 
* Receive remaining asynchronous replies 
WAIT UNTIL RCV_JOBS >= SND_JOBS. 
LOOP AT TASKLIST. 
  WRITE:/   'Received task:', TASKLIST-TASKNAME COLOR 1, 
		30  'Destination: ', TASKLIST-RFCDEST COLOR 1. 
ENDLOOP 
... 
 
FORM RETURN_INFO USING TASKNAME. 
 
  RECEIVE RESULTS FROM FUNCTION 'RFC_SYSTEM_INFO' 
	IMPORTING RFCSI_EXPORT = INFO 
	EXCEPTIONS 
	COMMUNICATION_FAILURE = 1 
	SYSTEM_FAILURE		= 2. 
 
  RCV_JOBS = RCV_JOBS + 1.  "Receiving data 
	IF SY-SUBRC NE 0. 
* Handling of communication and system failure 
	... 
	ELSE. 
	READ TABLE TASKLIST WITH KEY TASKNAME = TASKNAME. 
	IF SY-SUBRC = 0.  "Register data 
		TASKLIST-RFCDEST = INFO_RFCDEST. 
		MODIFY TASKLIST INDEX SY-TABIX. 
	ENDIF. 
	ENDIF. 
  ... 
ENDFORM

0) Valid security key but incorrect logon data.

1) Calling system is not a Trusted System or

security key is invalid.

2) User either has no RFC authorization (authorization

object S_RFCACL), or you tried to log on using

one of the protected users 'DDIC' or 'SAP*'.

3) The timestamp of the logon data is invalid.