The documentation may have changed since you downloaded the PDF. You can always find the latest information on SAP Help Portal.
Note
This PDF document contains the selected topic and its subtopics (max. 150) in the selected structure. Subtopics from other structures are not included.
2015 SAP SE or an SAP affiliate company. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose
without the express permission of SAP SE. The information contained herein may be changed without prior notice. Some software products marketed by SAP SE
and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are provided by
SAP SE and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be
liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express
warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. SAP and other
SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE in Germany and other
countries. Please see www.sap.com/corporate-en/legal/copyright/index.epx#trademark for additional trademark information and notices.
Table of content
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 1 of 24
Table of content
1 Writing RFC Programs in ABAP
1.1 Calling RFC Function Modules in ABAP
1.1.1 Introduction
1.1.2 RFC Calls
1.1.2.1 Parameter Handling in Remote Calls
1.1.2.2 Calling Remote Functions Locally
1.1.2.3 Calling Remote Functions Back
1.1.2.4 RFC Call Restrictions
1.1.3 Characteristics Using Unicode
1.1.4 RFC Exceptions
1.1.4.1 Class-Based RFC Exceptions
1.1.4.1.1 Class-Based RFC Exceptions
1.1.4.1.1.1 Semantic Considerations for Classic Exceptions
1.1.4.1.1.2 Class-Based Exceptions in Asynchronous RFC
1.1.4.2 Classic RFC Exceptions
1.1.4.2.1 Usnig Pre-Defined Exceptions for RFC
1.1.4.2.2 Exceptions That Cannot Be Handled
1.1.5 RFC Variants
1.1.5.1 Synchronous RFC (sRFC)
1.1.5.2 Asynchronous RFC (aRFC)
1.1.5.2.1 Call Properties of Asynchronous RFCs
1.1.5.2.2 Receiving Results from an Asynchronous RFC
1.1.5.2.3 Keeping the Remote Context
1.1.5.2.4 Parallel Processing with Asynchronous RFC
1.1.5.2.5 CALL FUNCTION - STARTING NEW TASK
1.1.5.2.6 RECEIVE
1.1.5.2.7 WAIT UNTIL
1.1.5.2.8 aRFC Programming Example
1.1.5.3 Transactional RFC (tRFC)
1.1.5.3.1 CALL FUNCTION - IN BACKGROUND TASK
1.1.5.4 Queued RFC (qRFC)
1.2 Writing Remote Function Modules in ABAP
1.2.1 Steps for Implementing Remote Function Modules
1.2.2 Programming Tips
1.2.3 Debugging Remote Function Modules
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 2 of 24
1.1.1 Introduction
Use
You can use the CALL FUNCTION statement to call remote functions, just as you would call local function modules. However, you must include an additional
DESTINATION clause to define where the function should run:
CALL FUNCTION Remotefunction
DESTINATION Dest
EXPORTING
F1 = a1
F2 = a2
IMPORTING
F3 = a3
CHANGING
F4 = a4
TABLES
t1 = ITAB
EXCEPTIONS
...
The Remotefunction field can either be a literal or a variable. The field Dest can be either a literal or a variable: its value is a logical destination (for example,
"hw1071_53") known to the local SAP System. You can define logical destinations in table RFCDES using transaction SM59, or using the following menu path:
Tools
Administration, Administration
Network
RFC Destinations .
Programming guidelines are available in the following topics:
Parameter Handling in Remote Calls
Characteristics Using Unicode
Calling Remote Functions Locally
Calling Remote Functions Back
RFC Variants
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 3 of 24
The destination parameter displays an entry in the RFCDES table. This entry contains all necessary parameters to connect to and log in the destination system.
Note
Table RFCDES is configured using transaction SM59 ( Remote Destinations ).
Interface Functions
RFC frees the ABAP programmer from having to program his own communications routines. When you make an RFC call, the RFC interface takes care of:
Converting all parameter data to the representation needed in the remote system. This includes character string conversions, and any hardware-dependent
conversions needed (for example, integer, floating point). All ABAP data types are supported.
Calling the communication routines needed to talk to the remote system.
Handling communications errors, and notifying the caller, if desired. (The caller requests notification using the EXCEPTIONS parameter of the CALL
FUNCTION statement.)
The RFC interface is effectively invisible to the ABAP programmer. Processing for calling remote programs is built into the CALL FUNCTION statement.
Processing for being called is generated automatically (in the form of an RFC stub) for every function module registered as remote. This stub serves as an
interface between the calling program and the function module.
A distinction is made between an RFC client and RFC server. RFC client is the instance that calls up the Remote Function Call to execute the function that is
provided by an RFC server. In the following, the functions that can be executed remotely will be called RFC functions and the functions provided via RFC API
will be called RFC calls.
Context Management
Every remote function module call made using the RFC interface defines its own context in the target system. The function group of the function module is loaded
into an internal session of the context, and is retained. What this means is that, if repeated calls of function modules belonging to the same destination and the
same function group are made, the global data of this function group can be accessed collectively.
A connection and its context is retained until it is explicitly closed, or until the calling program is finished. Function module RFC_CONNECTION_CLOSE can be
used to explicitly close a connection.
More Information
You can find detailed information about RFC calls here:
Parameter Handling in Remote Calls
Calling Remote Functions Locally
Calling Remote Functions Back
RFC Call Restrictions
RFC Variants
Page 4 of 24
Process
TABLES Parameters
The actual table is transferred, but not the table header. If a table parameter is not specified, an empty table is used in the called function.
The RFC uses a delta managing mechanism to minimize network load during parameter and result passing. Internal ABAP tables can be used as parameters for
function module calls. When a function module is called locally, a parameter tables is transferred by reference". This means that you do not have to create a new
local copy. RFC does not support transfer "by reference". Therefore, the entire table must be transferred back and forth between the RFC client and the RFC
server. When the RFC server receives the table entries, it creates a local copy of the internal table. Then only delta information is returned to the RFC client. This
information is not returned to the RFC client every time a table operation occurs, however; instead, all collected delta information is passed on at once when the
function returns to the client.
The first time a table is passed, it is given an object-ID and registered as a "virtual global table" in the calling system. This registration is kept alive as long as
call-backs are possible between calling and called systems. Thus, if multiple call-backs occur, the change-log can be passed back and forth to update the local
copy, but the table itself need only be copied once (the first time).
F1 = a1
F2 = a2
TABLES
t1 = ITAB
EXCEPTIONS
...
Local Call:
CALL FUNCTION... [no DESTINATION]
This is a local call, even though the function module is registered as remote. The module does not run in a separate roll area, and is essentially like a
normal function call. Parameter transfer is handled as for normal function modules. In particular, if the call leaves some EXPORTING parameters
unspecified, it terminates abnormally.
CALL FUNCTION Remotefunction
EXPORTING
F1 = a1
F2 = a2
TABLES
t1 = ITAB
EXCEPTIONS
...
You can also call a function for parallel processing within the same system. For more details, see Parallel Processing with Aynchronous RFCs.
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 5 of 24
Example
In the diagram, remote function B of System B invokes remote function A in the calling System A.
The Unicode system being called reacts to conversion errors depending on the profile parameters
rfc/cp_convert/ignore_error
rfc/cp_convert/ignore_error
by using a replacement character, or by terminating the call.
You can specify the replacement character using its UTF-16 character number. The default character therefore has the value 0023. The character "~ " would
therefore have the value 007E, for example. You can find a list of the Unicode character numbers at http://www.unicode.org/ .
Default: Ignore errors and replace non-convertible characters with character '#'.
The system making the call receives the exception COMMUNICATION_FAILURE with the message connection closed.
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 6 of 24
In the calling system, the reaction to conversion errors can be configured separately for each destination. See transaction SM59 Defining Remote
Destinations.
For the system being called, a conversion error is not visible. The calling Unicode system identifies errors in the input data before it triggers an action on the called
page; the calling Unicode system only identifies errors in the output data if the called context has already been disconnected.
Note
You can however still use classic exception handling.
Constraints
It is not possible to use both forms of exception handling (classic and class-based) at the same time in a function call.
More Information
You can find further information about RFC exception handling under:
Class-Based RFC Exceptions
Classic RFC Exceptions
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 7 of 24
Class CX_REMOTE_UNSPECIFIED_EXC is the super class for all exception classes that are used to replace the original exception. This is necessary
when all original exception are unknown in the RFC Client or if the transport of the exception to the RFC Client failed.
Class CX_REMOTE_APPL_ERROR handles error situation that were caused during the call or when executing the function module at the server side. It
essentially corresponds to the classic RFC exception SYSTEM_FAILURE.
Note
Some special cases of SYSTEM_FAILURE are assigned to the class CX_CONNECTIVITY_ERROR.
Class CX_CONNECTIVITY_ERROR contains all exceptions that were returned during the connection creation, resource allocation, or in the communication
layer during the function call. it corresponds to the classic exception COMMUNICATION_FAILURE, RESOURCE_FAILURE and some special cases of
SYSTEM_FAILURE.
Attribute REMOTE_CONTEXT in class CX_ROOT transports additional information in the case of application errors to the target system (for example, the name of
the affected application server or the ABAP destination).
Application-specific class-based exceptions are transported directly, that is, directly to the RFC Client without any additional wrapper by a class. This makes it
easier for the RFC Client to access the exception and facilitates the context of the RFC call to persist when the exception was propagated outside the function call.
More Information
For more detailed information on using class-based exception in the field of RFC:
Class-Based RFC Exceptions
Prerequisites
Both the client and server are based on SAP NetWeaver 7.1 or higher.
Function call does not contain an EXCEPTION block.
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 8 of 24
Note
The classic exception handling is used for function calls that contain an EXCEPTION block.
Note
If a class-based exception is triggered on the server during classic exception handling then this causes a runtime error and the classic exception
SYSTEM_FAILURE is returned at the client side.
The function module to be called is defined in the RFC Client. Restrictions
For releases < 7.11, all logon and authorization errors are mapped to exception class CX_REMOTE_APLL_ERROR. The error text is found in the
MESSAGE_TEXT field.
If not system message fields are set for communicating with releases < 7.11 (for example, sy-msgty, sy-msgid, sy-msgno, sy-mgsv1,,sy-msgv4),
method GET_TEXT does not return a valid value in some cases for exception class CX_REMOTE_APLL_ERROR. The error text is found in the
MESSAGE_TEXT field.
Procedure
For class-based exception handling in your function call use TRY/CATCH syntax instead of the EXCEPTIONS block.
More Information
It is also possible to handle classic exceptions with class-based exception handling. There are however a few semantic considerations in the RFC field with
regard to local function calls. For more information:
Semantic Considerations for Classic Exceptions
The following rules apply in certain cases when using asynchronous RFC calls. For further information, see:
Class-Based Exceptions in Asynchronous RFC
You can find a more detailed description of local class-based exception handling in the ABAP field under:
Class-Based Exceptions
Note
Any alternative use of the EXCEPTIONS block can cause a runtime error. Since the assignment of both of the statements is not unique, syntax checks
are not supported.
If the function call is implemented without the EXCEPTIONS block, the callback routine is to be implemented as the method (referenced using the CALLING
addition).
The class-based exception can be caught using TRY...CATCH...ENDTRY if the statement RECEIVE RESULTS FROM FUNCTION is contained in this block
(or in methods/forms that are called in this block).
Class-based exceptions must be caught and handled within the callback routine and cannot be propagated to the outside. Every uncaught exception
causes the runtime error UNCAUGHT_EXCEPTION.
If the class-based exception handling is active and the statement RECEIVE RESULTS FROM FUNCTION is missing in the callback routine, then a runtime
error is returned.
Note
These remarks do not need to be taken into consideration for RFC types with asynchronous properties (aRFC without response, tRFC, qRFC, bgRFC)
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 9 of 24
because:
Exceptions are not transported to the RFC client for aRFC without response.
the client program does not contain the response for tRFC, qRFC, and bgRFC, rather the RFC layer itself executes the handling of all error situations
(for both classic and class-based exceptions).
Note
We strongly recommend that you assign a return value to these two exceptions for each RFC, and that you process these, otherwise a runtime error may
occur in the exception situations described.
More Information
You can find further information about RFC exceptions under:
Usnig Pre-Defined Exceptions for RFC
Exceptions That Cannot Be Handled
Note
You can use MESSAGE only with the two system exceptions described here.
Cause
CALL_BACK_ENTRY_NOT_FOUND
CALL_FUNCTION_DEST_TYPE
CALL_FUNCTION_NO_SENDER
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 10 of 24
CALL_FUNCTION_DESTINATION_NO_T
Missing communication type (I for internal connection, 3 for ABAP) when performing an
asynchronous RFC.
CALL_FUNCTION_NO_DEST
CALL_FUNCTION_OPTION_OVERFLOW
CALL_FUNCTION_NO_LB_DEST
The specified destination (in load distribution mode) does not exist.
CALL_FUNCTION_NO_RECEIVER
CALL_FUNCTION_NOT_REMOTE
CALL_FUNCTION_REMOTE_ERROR
While performing an RFC, an error occurred that has been logged in the calling system.
CALL_FUNCTION_SIGNON_INCOMPL
CALL_FUNCTION_SIGNON_INTRUDER
CALL_FUNCTION_SIGNON_INVALID
CALL_FUNCTION_SIGNON_REJECTED
CALL_FUNCTION_SINGLE_LOGIN_REJ
CALL_FUNCTION_SYSCALL_ONLY
RFC without valid user ID only allowed when calling a system function module. The
meaning of the error codes is the same as for
CALL_FUNCTION_SINGLE_LOGIN_REJ.
CALL_FUNCTION_TABINFO
CALL_FUNCTION_TABLE_NO_MEMORY
CALL_FUNCTION_TASK_IN_USE
For asynchronous RFC only: The task name is already being used.
CALL_FUNCTION_TASK_YET_OPEN
CALL_FUNCTION_NO_AUTH
No RFC authorization.
CALL_RPERF_SLOGIN_AUTH_ERROR
CALL_RPERF_SLOGIN_READ_ERROR
RFC_NO_AUTHORITY
CALL_FUNCTION_BACK_REJECTE
CALL_XMLRFC_BACK_REJECTED
CALL_FUNCTION_DEST_SCAN
CALL_FUNCTION_DEST_SCAN
CALL_FUNCTION_CONFLICT_TAB_TYP
CALL_FUNCTION_CREATE_TABLE
CALL_FUNCTION_UC_STRUCT
CALL_FUNCTION_DEEP_MISMATCH
CALL_FUNCTION_WRONG_VALUE_LENG
CALL_FUNCTION_PARAMETER_TYPE
CALL_FUNCTION_ILLEGAL_DATA_TYP
CALL_FUNCTION_ILLEGAL_INT_LEN
CALL_FUNCTION_ILL_INT2_LENG
CALL_FUNCTION_ILL_FLOAT_FORMAT
CALL_FUNCTION_ILL_FLOAT_LENG
CALL_FUNCTION_ILLEGAL_LEAVE
CALL_FUNCTION_OBJECT_SIZE
CALL_FUNCTION_ROT_REGISTER
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 11 of 24
call. When using synchronous RFC, the called system must therefore be available. The call is only made once. If the called system is not available or problems
occur, the call fails (service property: At Most Once ).
Asynchronous RFC
2. CALL FUNCTION func STARTING NEW TASK task [DESTINATION {dest|{IN GROUP {group|DEFAULT}}}] parameter_list [{PERFORMING
subr}|{CALLING meth} ON END OF TASK]. Despite its name, asynchronous RFC (aRFC) does not actually entail asynchronous function calls in the strict
sense of the word. Although the function check returns to the calling program directly after the call, the data is not actually written to the database. The call can
therefore only take place on a directly available system.
If the called system is not available, the call fails. Like the sRFC, the aRFC also only has service property At Most Once .
Background RFC
3. CALL FUNCTION func IN BACKGROUND UNIT parameter_list.
Unlike the aRFC, the background RFC (bgRFC) can be termed a "genuine" asynchronous communication method, which performs the function module called in
the RFC server exactly one time (service property: Exactly Once) . Exactly Once). The remote system need not be available at the time when the RFC client
program is executing a bgRFC. The bgRFC component stores the called RFC function, together with the corresponding data, in the SAP database under a unique
transaction ID (TID).
If a call is sent, and the receiving system is down, the call remains in the local queue until a later time. The calling dialog program can proceed without waiting to
see whether or not the remote call was successful. If the receiving system does not become active within a certain amount of time, the call is scheduled to run in
batch.
bgRFC is always used if a function is executed as a Unit . Within a given unit, all calls:
1. executed in the order in which they are called
2. executed in the same program context in the target system
3. are executed in a single transaction: they are either committed or rolled back as a unit.
Using bgRFC is always recommended if you want to maintain the transactional sequence of the calls in a unit. bgRFC can be either transactional (type T) or
queued (type Q). When using type Q, units belonging to multiple calls are also sent and processed in exactly the sequence in which they were written to the
database.
Transactional RFC
4. CALL FUNCTION func IN BACKGROUND TASK [DESTINATION dest] parameter_list [AS SEPARATE UNIT].
Transactional RFC is the predecessor of bgRFC for transactional RFC calls. It has the same service properties as bgRFC. tRFC can still be used in exactly the
same way as bgRFC. However, it is not possible to use the two methods in parallel.
Queued RFC
queued RFC (qRFC) is the predecessor of bgRFC type Q. qRFC also allows you to fix the processing sequence. The technology behind qRFC is based on tRFC.
The only difference is that function module TRFC_SET_QUEUE_NAME is executed before the actual tRFC call. This function module makes it possible to
serialize using queues.
Note
We recommend using bgRFC, as it offers considerably better performance than tRFC and qRFC.
Note
Execution of a function module called by synchronous RFC does not lead to a database commit in an update function. For more information on updating data in
SAP systems, see Updating in SAP Systems.
The parameter list has the following syntax:
... [EXPORTING p1 = a1 ... pn = an]
[IMPORTING p1 = a1 p2 = a2 ...]
[CHANGING p1 = a1 p2 = a2 ...]
[TABLES t1 = itab1 t2 = itab2 ...]
[EXCEPTIONS exc1 = n1 exc2 = n2 .. [MESSAGE mess]
[OTHERS = n_others] ].
These additions are used to assign actual parameters to the formal parameters of the function module, and return values to exceptions that are not class-based.
The additions have the same meanings as for the general function module call, the only differences being that, with the addition TABLES, only tables with flat
character types can be transferred, and that if a header line exists, it is not transferred.
The additions EXPORTING, IMPORTING, and CHANGING allow you to transfer tables that have deep character types, deep structures, and strings.
For EXCEPTIONS, you can also specify an optional addition MESSAGE for the special exceptions SYSTEM_FAILURE and COMMUNICATION_FAILURE. If one
of these exceptions occurs, the first line of the corresponding short dump is entered in the field mess, which must be flat and of character-type.
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 12 of 24
Note
Transferring tables using the addition TABLES is considerably faster than using the other additions, since a binary format is used internally instead of an XML
format.
Note
The following calling parameters are available:
TABLES
passes references to internal tables. All table parameters of the function module must contain values.
EXPORTING
passes values of fields and field strings from the calling program to the function module. In the function module, the corresponding formal parameters are
defined as import parameters.
EXCEPTIONS
See Using Predefined Exceptions for RFCs
RECEIVE RESULTS FROM FUNCTION Remotefunction is used within a FORM routine to receive the results of an asynchronous remote function call. The
following receiving parameters are available:
IMPORTING
TABLES
EXCEPTIONS
The addition KEEPING TASK prevents an asynchronous connection from being closed after receiving the results of the processing. The relevant remote context
(roll area) is kept for re-use until the caller terminates the connection.
More Information
You can find more information about aRFC in:
Call Properties of Asynchronous RFCs
Receiving Results from an Asynchronous RFC
Keeping the Remote Context
Parallel Processing with Asynchronous RFC
You can find a description of the various statements for aRFC in:
CALL FUNCTION - STARTING NEW TASK
RECEIVE
WAIT UNTIL
RFC Example
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 13 of 24
DESTINATION Dest
Server System
FUNCTION Remotefunction.
CALL SCREEN 100.
ENDFUNCTION.
If you do not specify a destination, the asynchronous RFC mechanism starts a new session within the calling system.
Caution
You must not use IMPORTING parameters when calling aRFCs.
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 14 of 24
AT USER-COMMAND.
* Return from FORM routine RETURN_INFO via SET USER-COMMAND
IF SY-UCOMM = 'OKCD'.
IF MSG = SPACE.
WRITE: 'Destination =', INFO-RFCDEST.
ELSE.
WRITE MSG.
ENDIF.
ENDIF.
...
FORM RETURN_INFO USING TASKNAME.
RECEIVE RESULTS FROM FUNCTION 'RFC_SYSTEM_INFO'
IMPORTING RFCSI_EXPORT = INFO
EXCEPTIONS
COMMUNICATION_FAILURE = 1 MESSAGE MSG
SYSTEM_FAILURE = 2 MESSAGE MSG.
SET USER-COMMAND 'OKCD'. "Sets OK code
ENDFORM.
Note
You should use the addition KEEPING TASK only if you want to re-use the current remote context for a subsequent asynchronous call.
Keeping a remote context increases storage load and decreases performance due to additional roll area management in the system.
Caution
Parallel-processing is implemented with a special variant of asynchonous RFC. With your own parallel processing applications, It is therefore important that
you only use the correct variant:
CALL FUNCTION STARTING NEW TASK DESTINATION IN GROUP.
Using other variants of asynchronous RFC circumvents the built-in safeguards in the correct keyword, and can bring your system to its knees
Details are discussed in the following subsections:
Prerequisites for Parallel Processing
Function Modules and ABAP Keywords for Parallel Processing
Managing Resources in Parallel Processing
Process
Prerequisites for Parallel Processing
Before you implement parallel processing, make sure that your application and your SAP system meet these requirements:
Logically-independent units of work:
The data processing task that is to be carried out in parallel must be logically independent of other instances of the task. That is, the task can be carried out
without reference to other records from the same data set that are also being processed in parallel, and the task is not dependent upon the results of others
of the parallel operations. For example, parallel processing is not suitable for data that must be sequentially processed or in which the processing of one
data item is dependent upon the processing of another item of the data. By definition, there is no guarantee that data will be processed in a particular order
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 15 of 24
in parallel processing or that a particular result will be available at a given point in processing.
ABAP requirements:
The function module that you call must be marked as externally callable. This attribute is specified in the Remote function call supported field in the
function module definition (transaction SE37).
The called function module may not include a function call to the destination "BACK".
The calling program should not change to a new internal session after making an asynchronous RFC call. That is, you should not use SUBMIT or
CALL TRANSACTION in such a report after using CALL FUNCTION STARTING NEW TASK.
You cannot use the CALL FUNCTION STARTING NEW TASK DESTINATION IN GROUP keyword to start external programs.
System resources:
In order to process tasks from parallel jobs, a server in your SAP system must have at least 3 dialog work processes. It must also meet the workload
criteria of the parallel processing system: Dispatcher queue less than 10% full, at least one dialog work process free for processing tasks from the parallel
job.
Function Modules and ABAP Keywords for Parallel Processing
You can implement parallel processing in your applications by using the following function modules and ABAP keywords:
SPBT_INITIALIZE: Optional function module. Use to determine the availability of resources for parallel processing.
You can
check that the parallel processing group that you have specified is correct.
find out how many work processes are available so that you can more efficiently size the packets of data that are to be processed in your data.
CALL FUNCTION Remotefunction STARTING NEW TASK Taskname DESTINATION IN GROUP:
With this ABAP statement, you are telling the SAP system to process function module calls in parallel. Create a loop for this command by splitting up the
data to be processed into work packages. Transfer the data to be processed to an internal table (EXPORT arguments, TABLE arguments). The keyword
implements parallel processing by dispatching asynchronous RFC calls to the servers that are available in the RFC server group specified for the
processing.
Note that your RFC calls with CALL FUNCTION are processed in work processes of type DIALOG. The DIALOG limit on processing of one dialog step (by
default 300 seconds, system profile parameter rdisp/max_wprun_time) applies to these RFC calls. Remember to consider this restriction when dividing up
your data packets for parallel processing.
SPBT_GET_PP_DESTINATION: Optional function module.
Call immediately after the CALL FUNCTION keyword to get the name of the server on which the parallel processing task will be run.
SPBT_DO_NOT_USE_SERVER: Optional function module.
Excludes a particular server from further use for processing parallel processing tasks. Use in conjunction with SPBT_GET_PP_DESTINATION if you
determine that a particular server is not available for parallel processing (for example, COMMUNICATION FAILURE exception if a server becomes
unavailable).
WAIT: ABAP key word
WAIT UNTIL <logical expression>
Required if you wish to wait for all of the asynchronous parallel tasks created with CALL FUNCTION to return. This is normally a requirement for orderly
background processing. May be used only if the CALL FUNCTION includes the PERFORMING ON RETURN addition.
RECEIVE: ABAP key word
RECEIVE RESULTS FROM FUNCTION Remotefunction
Required if you wish to receive the results of the processing of an asynchronous RFC. RECEIVE retrieves IMPORT and TABLE parameters as well as
messages and return codes.
Managing Resources in Parallel Processing
You use the following destination additions to perform parallel execution of function modules (asynchronous calls) in the SAP system:
In a predefined group of application servers:
CALL FUNCTION Remotefunction STARTING NEW TASK Taskname
DESTINATION IN GROUP Groupname
In all currently available and active application servers:
CALL FUNCTION Remotefunction STARTING NEW TASK Taskname
DESTINATION IN GROUP DEFAULT
The addition first determines the amount of resources (work processes) currently available (i.e. in all servers or in a group of application servers, comparable with
login servers). The resources available for executing asynchronous calls on each application server depends on the current system load.
The applications developer is responsible for the availability of RFC groups in the production system (i.e. the customer's system). For details on how to maintain
the RFC groups, see Maintaining Group Destinations For Load Distribution.
After determining the available resources, the asynchronous call is executed in an available application server. 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.
The process for determining available resources in an RFC group is as follows:
First, the system determines the length of the dispatcher queue for the relevant application server. If it is greater than 10% of the overall length, the server makes
no resources available. If it is smaller, the system makes available the current number of free dialog processes minus 2 (as a reserve instance for other
purposes, e.g. for logon to the system or administration programs). Thus, one application server must have at least 3 dialog processes if RFC parallel processing
is taken into account.
Note
At present, only one RFC group per program environment is supported for parallel execution of asynchronous calls. Using both additions (
DESTINATION IN GROUP Groupname and DESTINATION IN GROUP DEFAULT) in one program is not allowed.
The exception routine RESOURCE_FAILURE is only triggered in connection with asynchronous RFCs with the additions DESTINATION IN GROUP
Groupname and DESTINATION IN GROUP DEFAULT.
You are recommended (for performance and other reasons) to use an RFC group with sufficient resources for parallel processing of asynchronous calls
Page 16 of 24
Use
Syntax
CALL FUNCTION func STARTING NEW TASK task
[DESTINATION {dest|{IN GROUP {group|DEFAULT}}}]
parameter list
[{PERFORMING subr}|{CALLING meth} ON END OF TASK].
Additions:
1. ... DESTINATION IN GROUP { group|DEFAULT}
2. ... {PERFORMING subr}|{CALLING meth} ON END OF TASK
Effect
Asynchronous call of a remote-capable function module specified in func using the RFC interface. You can use the addition DESTINATION to specify a single
destination in dest, or to specify a group of application servers by using IN GROUP. The latter supports parallel processing of multiple function modules. The
calling program is continued using the statement CALL FUNCTION, as soon as the remotely called function has been started in the target system, without having
to wait for its processing to be finished. You can use PERFORMING and CALLING to specify callback routines for copying results when the remotely called
function is finished. Character-type data objects are expected for func and dest.
If the destination has not been specified, the destination NONE is used implicitly. When the destination NONE is used, a new main session is opened for the
current user session. The asynchronous RFC does not support communication with external systems or programs written in other programming languages.
A character-type data object must be specified for task, one which contains for the remotely called function module a freely definable task ID that has a maximum
eight digits. This task ID must be unique for each call, and is handed to the callback routines for identifying the function. Each task ID defines a separate RFC
connection with its own context, meaning that, in the case of repeated function module calls of the same task ID, the global data of the relevant function group can
be accessed, if the connection still exists.
Note
In dialog processing, note that the maximum number of six main sessions cannot be exceeded, else an error message is displayed.
Addition 1
... DESTINATION IN GROUP {group|DEFAULT}
Effect
Specifying IN GROUP as a destination allows you to execute multiple function modules in parallel on a predefined group of application servers in the current
SAP system.
For group, you must specify a data object of the type RZLLI_APCL from the ABAP Dictionary, one that is either initial, or one that includes the name of an RFC
server group created in transaction RZ12. When specifying DEFAULT, or if group is initial, all application servers that are currently available in the current SAP
system are used as a group. Only one RFC server group may be used within a program. During the first asynchronous RFC using the addition IN GROUP, the
specified RFC server group is initialized. For each asynchronous RFC where the group is specified, the most suitable application server is determined
automatically, and the called function module is executed on this.
If the function module cannot be executed on any application server, due to not enough resources being currently available, this leads to the predefined exception
RESOURCE_FAILURE, to which a return value can be assigned, in addition to the remaining RFC exceptions. For this exception, the addition MESSAGE is not
permitted.
Note
The parallel processing of function modules using the addition IN GROUP makes optimum use of the resources available, and is preferred to selfprogrammed parallel processing with destinations that are specified explicitly.
An application server that is used as part of an RFC server group for parallel processing must have at least three dialog work processes, of which one
is currently free. Other resources such as requests in the queue, number of system logons and so on, are also taken into account, and are not allowed to
exceed certain limit values.
To ensure that only those application servers that have enough resources are accessed, we recommend that you work with explicitly defined RFC
server groups instead of working with the addition DEFAULT.
The function modules of the function group SPBT provide service functions for parallel processing, for example, initialization of RFC server groups,
determining the used destination, or temporarily removing an application server from an RFC server group.
Addition 2
... {PERFORMING subr}|{CALLING meth} ON END OF TASK
Effect
You can use this addition to specify either a subprogram subr or, as of Release 6.20, a method meth as a callback routine, which is executed after the
asynchronously called function module has finished. For subr, you have to directly specify a subprogram of the same program. For meth, you can enter the
same details as for the general method call.
The specified subprogram subr can have exactly one SING parameter of type clike only. The method meth must be public, and can have only one nonoptional input parameter p_task of type clike. When the RFC interface is called, this parameter is supplied with the task ID of the remotely called function that
was specified in the call in task. The results of the remote function can be received in the subprogram subr or method meth using the statement RECEIVE. In
the callback routine, no statements can be executed that cause the program run to terminate or end an SAP LUW. Statements for list output are not executed.
Prerequisite for executing a callback routine is that, after the remote function has ended, the calling program is still internally available. It is then executed the next
time the work process is changed. If the program has ended, or if it is part of a call sequence in the stack, then the callback routine is not executed. The
statement WAIT can be used to stop the program execution until certain or all callback routines have been executed.
CALL FUNCTION - STARTING NEW TASK parameter_list
Syntax
... [EXPORTING p1 = a1 p2 = a2 ...]
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 17 of 24
1.1.5.2.6 RECEIVE
Use
Syntax
RECEIVE RESULTS FROM FUNCTION func
parameter list
[KEEPING TASK].
Addition:
... KEEPING TASK
Effect
This statement can be used in a callback routine specified for the asynchronous RFC, in order to receive output parameters of an asynchronously called function
func in the parameter list parameter list, and to assign return values to exceptions.
Note
If a function module is started multiple times in a row using asynchronous RFC, the execuction sequence is not fixed, instead it depends in the system
availability.
Addition
... KEEPING TASK
Effect
With the addition KEEPING TASK, the asynchronous RFC connection is retained, as is the context of the called function module along with it. When a new call is
made with the same task ID, the same global data of the function group is addressed. Without the addition KEEPING TASK, an asynchronous RFC connection is
finished after the remote function is executed or the results are copied.
Note
You must only use the addition KEEPING TASK if the context of the called function module is required for other function calls.
RECEIVE - parameter_list
Syntax
... [IMPORTING p1 = a1 p2 = a2 ...]
[TABLES t1 = itab1 t2 = itab2 ...]
[EXCEPTIONS exc1 = n1 exc2 = n2 ... [MESSAGE mess]
[OTHERS = n_others]].
Effect
With these additions, the defined formal parameters of the function module specified in func are transferred to the actual parameters of the callback routine in the
calling program , and return values are assigned to non-class-based exceptions. The meaning of the additions is the same as for a synchronous RFC. In
particular, the special exceptions SYSTEM_FAILURE and COMMUNICATION_FAILURE can be assigned return values. If no exceptions occur, RECEIVE sets
the contents of sy-subrc to 0.
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 18 of 24
Specifying UP TO restricts the program interruption to a maximum number of seconds, specified in seconds. A data object of type f is expected for sec, which
must contain a positive integer. After the specified time period has passed at the very latest, the program execution continues with the statement following WAIT.
System Fields
The statement WAIT causes a switch in the work process, which is linked to the rollout and rollin of all loaded programs. For this reason, the time given in sec
must not be less than one second, to avoid burdening the system with too many work process switches.
Each time the statement WAIT is used, a database commit is performed. For this reason, WAIT must not be used between Open SQL statements that open or
close a database cursor.
There is also one variant of the statement WAIT that can be used independently of the asynchronous RFC.
Exceptions
Exceptions That Cannot Be Handled
Cause : Undefined status of WAIT statement
Runtime error : WAIT_ILLEGAL_CONTROL_BLOCK
Cause : Negative time entry for sec.
Runtime error : WAIT_ILLEGAL_TIME_LIMIT
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 19 of 24
UP TO 5 SECONDS.
ENDIF.
IF sy-subrc = 0.
exc_flag = 0.
ELSE.
MESSAGE 'Resource failure' TYPE 'I'.
ENDIF.
WHEN OTHERS.
MESSAGE 'Other error' TYPE 'I'.
ENDCASE.
ENDDO.
WAIT UNTIL rcv_jobs >= snd_jobs.
LOOP AT task_list INTO task_wa.
WRITE: / task_wa-name, task_wa-dest.
ENDLOOP.
FORM rfc_info USING name.
task_wa-name = name.
rcv_jobs = rcv_jobs + 1.
RECEIVE RESULTS FROM FUNCTION 'RFC_SYSTEM_INFO'
IMPORTING
rfcsi_export = info
EXCEPTIONS
system_failure
= 1 MESSAGE mess
communication_failure = 2 MESSAGE mess.
IF sy-subrc = 0.
task_wa-dest = info-rfcdest.
ELSE.
task_wa-dest = mess.
ENDIF.
APPEND task_wa TO task_list.
ENDFORM.
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 20 of 24
You can use transactional RFCs, for example, for complex processes that require updating of related database tables during different phases in a transaction.
Transactional RFC processing ensures that all the planned updates are carried out when the program reaches the COMMIT WORK statement.
Caution
Function modules that are to be called transactionally, cannot have any EXPORT parameters in the definition, since an IMPORTING parameter in the calling
program leads to a syntax error.
Note also that you cannot make asynchronous calls to functions that perform call-backs.
System Availability
If the remote system is unavailable, the SAP System schedules the report RSARFCSE for background processing with the relevant transaction ID as variant.
This report, which forwards asynchronous calls for execution, is called repeatedly until it succeeds in connecting with the desired system.
When scheduled in batch, RSARFCSE runs automatically at set intervals (the default is every fifteen minutes, for up to 30 attempts). You can customize this
interval and the length of time the program should go on trying. Use enhancement programs SABP0000 and SABP0003 to do this.
To configure a destination, call transaction SM59, select the screen for a destination and choose
of connection attempts up to the task and the time between repeat attempts.
Edit
TRFC Options
If the system is not reachable within the specified amount of time, the system stops calling RSARFCSE, and the status CPICERR is written to the ARFCSDATA
table. Within another specified time (the default is eight days), the corresponding entry in the ARFCSSTATE table is deleted (this limit can also be customized). (It
is still possible to start such entries in transaction SM59 manually.)
More Information
You can find a description of the statements for tRFC in:
CALL FUNCTION IN BACKGROUND TASK
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 21 of 24
modules registered for an SAP LUW in their destination, every 15 minutes up to a total of 30 times. You can make changes to these parameters using transaction
SM59. If the destination does not become available within the given time, this is noted in the database table ARFCSDATA as a CPICERR entry. By default, this
entry in database table ARFCSSTATE is deleted after 8 days.
Addition
... AS SEPARATE UNIT
Effect
When using the addition AS SEPARATE UNIT, the relevant function module is executed in a separate context, a context in which the global data of the function
group is not influenced by previous calls. Each function module that is registered with the addition AS SEPARATE UNIT is given a separate transaction ID.
Without the addition AS SEPARATE UNIT, the usual description is applicable for the context of the called function modules. What this means is that, when using
the same destination for multiple calls of function modules belonging to the same function group, the global data of this function group is accessed collectively.
Note
You can use the function module ID_OF_BACKGROUNDTASK to define the transaction ID (TID) of the current SAP LUW, according to a transactional RFC.
The transactional RFC (tRFC) is suitable for realizing LUWs in distributed environments (a typical application is ALE). Here it must be noted that although
executing the function modules within a transaction ID is predefined, the sequence of the LUWs on the RFC servers does not necessarily correspond to the
sequence of SAP LUWs in the RFC client. To achieve a serialization on the RFC servers as well, the tRFC can be enhanced to queued RFC (qRFC). For this,
you can call function module TRFC_SET_QUEUE_NAME before a transactional RFC.
CALL FUNCTION - IN BACKGROUND TASK parameter_list
Syntax
... [EXPORTING p1 = a1 p2 = a2... ] [TABLES t1 = itab1 t2 = itab2 ...] ... .
Effect
These additions are used to assign actual parameters to the formal parameters of the function module. The significance of the additions is the same as for
synchronous RFC with the exception that no values can be copied with IMPORTING and CHANGING, and no return values can be allocated to exceptions that
are not class-based.
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 22 of 24
Scenario 1: tRFC
This scenario is appropriate is the data being sent is independent of each other. A calling application (client) in system 1 uses a tRFC connection to a called
application (r server) in system 2. In this scenario, data is transferred by tRFC, meaning that each function module sent to the target system is guaranteed to be
executed once only. You cannot define the sequence in which the function modules are executed, nor the time of execution. If an error occurs during the transfer, a
batch job is scheduled, which sends the function module again after 15 minutes.
Scenario 2: qRFC with Outbound Queue
In this scenario, the sending system uses an outbound queue to serialize the data being sent. This means that mutually dependent function modules are placed in
the outbound queue of the sending system. When the data is sent, the exact order is kept to, and the calls are sent to the target system exactly once in order .
Exactly Once In Order) .
Note
The server system coding does not need to be changed in order to process qRFC calls. However, it must be tRFC enabled.
Scenario 3: qRFC with Inbound Queue (& Outbound Queue)
In this scenario, as well as an outbound queue in the sender system (client), there is also an inbound queue in the target system (server). If a qRFC with inbound
queue exists, this always means that an outbound queue exists in the sender system.
The inbound queue only processes as many function modules as the system resources in the target system (server) at that time allow. This prevents a server
being blocked by a client. A scenario with just one inbound queue in the server system is not possible, since the outbound queue is needed in the client system
in order to set the order and to prevent individual applications from blocking all work processes in the client system.
More Information
You can find detailed information about qRFC in:
Queued Remote Function Call (qRFC)
Note
To view the entire directory tree of the function module documentation, choose Synchronize from the upper left part of the screen.
Note
Define the destination of the RFC server in the RFC client system that calls the remote function.
Either you or your system administrator can maintain the RFCDES table using transaction SM59 (
Tools
Network
RFC Destinations ). For more detailed information, see Maintaining Remote Destinations.
You can then use this destination in your programs to call the function module.
Administration, Administration
Procedure
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 23 of 24
Procedure
Declaring Parameters
For normal (non-remote) function modules, if a parameter is not defined like an ABAP Dictionary field, it takes the data type of the actual parameter used at runtime. A remote function module, however, does not have this information available. As a result, all parameter fields for a remote function module must be defined
as reference fields, that is, like ABAP Dictionary fields. (This applies to IMPORT, EXPORT, CHANGING and TABLES parameters.)
For character structures or fields, the caller's parameters need not be as long as expected by the called program. When incoming parameters are shorter, RFC
simply pads them with blanks. This means that the ABAP Dictionary definition of character parameters need not be exactly the same on the calling and called
sides. (However, the caller's parameters may not be not longer than expected on the called side).
Writing for Transactional Execution
Caution
There are two restrictions on writing remote functions that are to be called transactionally:
Transactional calls cannot return parameter values. As a result, the interface for these functions should not specify any EXPORT parameters.
Functions that run transactionally may not perform call-backs: the caller's context does not necessarily still exist when the call-back is relayed back to
the original system.
Exceptions
You can trigger exceptions in a remote function just as you would in a locally called function.
Since the system raises COMMUNICATION_FAILURE and SYSTEM_FAILURE internally, there is no reason for you to trigger them in your function module.
Calling Other Remote Functions
A remote function can call other remote functions, just like an ordinary function module.
In particular, it can use the call-back feature to call function modules running in the system of the original caller.
For more detailed information about callbacks between SAP systems, see Calling Remote Functions Back.
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Page 24 of 24