RECEIVE

Basic form

RECEIVE RESULTS FROM FUNCTION func.

Extras:

1. ... KEEPING TASK

2. ... IMPORTING  p1 = f1       ... pn = fn

3. ... TABLES     p1 = itab1    ... pn = itabn

4. ... EXCEPTIONS except1 = rc1 ... exceptn = rcn

Effect

Receives the results returned by a function module called asynchronously ( CALL FUNCTION func STARTING NEW TASK taskname). This ABAP statement is used within a FORM routine. The form routine must have a place holder for passing the task name (for example, USING taskname - see example), and it can only be used to receive and execute simple ABAP statements. It cannot contain any statements that interrupt the program execution (such as CALL SCREEN, CALL DIALOG, CALL TRANSACTION, SUBMIT, COMMIT WORK, WAIT, Remote Function CAlls, CPIC calls), or any warning or information messages that use the MESSAGE statement.

Notes

This statement is only used in conjunction with a function module call of the form CALL FUNCTION func STARTING NEW TASK taskname. If the function module does not return any values, you do not need to define this part.

The FORM routine must contain the statement RECEIVE RESULTS FROM FUNCTION func, otherwise it cannot recieve the results, and the remote context (remote tasks) is not concluded. This eventually leads to the application server being overloaded.

This statement has only existed since R/3 Release 3.0. Therefore, both partner systems (client and server) must have Release 3.0 of the system or higher.

You can wait for the response from an asynchronous function call (PERFORMING form ON END OF TASK) using the WAIT statement. WAIT must appear in the same program context.

You can collect the results of an asynchronous call in dialog mode when the roll area changes or by using WAIT (both dialog and background processing).

If the calling program ends without receiving the reply from the asynchronous function module, the values cannot be delivered.

The FORM routine in which you evaluate the relevant tasks should only be used to receive the results of the asynchronous tasks. If you use WRITE statements in the form routine, the list output is suppressed.

Note that the asynchronous task is not necessarily terminated if the calling program terminates.

Since the FORM routine runs in the same program context as the main program, they should not both use the same global data structures.

Addition 1

... KEEPING TASK

Effect

This addition stops the asynchronous connection from being terminated once the results have been received. Instead, the remote context (roll area) is retained until the calling program ends. This allows you to re-address and use the same context (and roll area) under the same name.

Notes

Only use this addition if you want to reuse the remote context in a later asynchronous call. Otherwise, the context is retained until the calling program ends, leading to increased memory requirements and impaired performance in the remote system.

If the remote function module contains user dialogs (lists or screens), the screen output remains active until the calling program ends. If the asynchronous call is made in debugging mode, the remote debugging dialog remains visible until the end of the caller's dialog.

Addition 2

... IMPORTING p1 = f1 ... pn = fn

Effect

IMPORTING returns values from fields and structures in the function module to the calling progam. In the function module, the corresonding parameters are defined as export parameters. You can pass any number of these parameters.

Addition 3

... TABLES p1 = itab1 ... pn = itabn

Effect

TABLES passes the contents of internal tables.

Addition 4

... EXCEPTIONS except1 = rc1 ... exceptn = rcn

Effect

Besides the exceptions generated by the function module called, you should also handle two special system exceptions here (as when you call function modules using the DESTINATION addition):

In either case, you can use the optional addition

... MESSAGE mess

to receive a description of the error.

Note

You should always handle these two system exceptions both in the asynchronous function call and when you receive the results.

Example

DATA: INFO LIKE RFCSI,
* Result of the RFC_SYSTEM_INFO function
      MSG(80) VALUE SPACE,
* Exception handling
      RET_SUBRC like SY-SUBRC.
* SY-SUBRC handling

CALL FUNCTION 'RFC_SYSTEM_INFO'
     STARTING NEW TASK 'INFO'
     PERFORMING RETURN_INFO ON END OF TASK
     EXCEPTIONS
       COMMUNICATION_FAILURE = 1 MESSAGE MSG
       SYSTEM_FAILURE        = 2 MESSAGE MSG.

IF SY-SUBRC = 0.
  WRITE: 'Wait for response'.
ELSE.
  WRITE MSG.
ENDIF.
...
AT USER-COMMAND.
* Return from the form routine RETURN_INFO using SET USER-COMMAND
IF SY-UCOMM = 'OKCD'.
   IF RET_SUBRC = 0.
     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.
  RET_SUBRC = SY-SUBRC. "Setn RET_SUBRC
  SET USER-COMMAND 'OKCD'. "Set OK_CODE
ENDFORM.

Note

Wie das obige Beispiel zeigt, kann man in der FORM-Routine, in der die Auswertung des betreffenden Tasks vorgenommen wird, mit Hilfe der Anweisung SET USER-COMMAND ein Listen-Ereignis ausgelöst werden. Dieses kann dann im Rahmenprogramm im AT USER-COMMAND-Zeitpunkt (z. B. zweck Administration der asynchronen Aufrufe) verarbeitet werden. Hierbei wird nicht immer gewährleistet, daß nach jedem SET USER-COMMAND der AT USER-COMMAND ausgeführt wird.

The SET USER-COMMAND statement in screen processing in this case causes the last PAI module of the preceding screen to be processed with the specified user command as its OK_CODE. This does not ensure that the user command processing is executed after each SET USER-COMMAND statement. In debugging mode, for example, the statement is ineffective (the SET USER-COMMAND event is not processed).

For the purpose of adminstration of asynchronous function module calls (especially in background mode), you can use the WAIT statement. The above example, using the WAIT statement instead of SET USER-COMMAND, would then look like this:

Example

DATA: INFO LIKE RFCSI,
* Results of RFC_SYSTEM_INFO function
      MSG(80) VALUE SPACE,
* Exception handling
      RET_SUBRC like SY-SUBRC,
* SY-SUBRC handling
      SEMAPHORE(1) TYPE C VALUE SPACE.
* Flag for receiving asynchronous results

CALL FUNCTION 'RFC_SYSTEM_INFO'
     STARTING NEW TASK 'INFO'
     PERFORMING RETURN_INFO ON END OF TASK
     EXCEPTIONS
       COMMUNICATION_FAILURE = 1 MESSAGE MSG
       SYSTEM_FAILURE        = 2 MESSAGE MSG.

IF SY-SUBRC = 0.
  WRITE: 'Wait for the answer'.
ELSE.
  WRITE MSG.
ENDIF.
...
CLEAR SEMAPHORE.
WAIT UNTIL SEMAPHORE = 'X'.
* Return from the form routine RETURN_INFO
IF RET_SUBRC = 0.
   WRITE: 'Destination =', INFO-RFCDEST.
ELSE.
   WRITE MSG.
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.
  RET_SUBRC = SY-SUBRC. "Set RET_SUBRC
  SEMAPHORE = 'X'. "Set semaphore
ENDFORM.

Note

If you encounter problems, refer to Typical RFC problems and their solutions.

Exceptions

Non-Catchable Exceptions

• CALL_FUNCTION_NO_RECEIVER: Data received for unknown CPIC connection. Error triggered because an answer to an asynchronous function call has been received by CPIC protocol that could not be forwarded to the correct program context. This situation occurs when you use a SUBMIT or CALL TRANSACTION statement after the PERFORMING form ON END OF TASK statement. The SUBMIT statement generates a new internal session that can prevent the results from the function call being forwarded to the internal session from which the function module was called.
  
  
  

Exceptions for RFC

Non-Catchable Exceptions

• Cause: The called function module has not been released for RFC.
  Runtime Error: CALL_BACK_ENTRY_NOT_FOUND
  
• Cause: Destination type is not allowed.
  Runtime Error: CALL_FUNCTION_DEST_TYPE
  
• Cause: Missing communication type (I for internal connection, 3 for R/3) when calling an asynchronous RFC
  Runtime Error: CALL_FUNCTION_DESTINATION_NO_T
  
• Cause: The destination entered does not exist.
  Runtime Error: CALL_FUNCTION_NO_DEST
  
• Cause: The destination entered (in load distribution mode) does not exist.
  Runtime Error: CALL_FUNCTION_NO_LB_DEST
  
• Cause: Data received for unknown CPI-C connection.
  Runtime Error: CALL_FUNCTION_NO_RECEIVER
  
• Cause: The function module you tried to call is flagged as one that cannot be called remotely.
  Runtime Error: CALL_FUNCTION_NOT_REMOTE
  
• Cause: An error occurred when calling the function remotely. This error is logged in the calling system.
  Runtime Error: CALL_FUNCTION_REMOTE_ERROR
  
• Cause: The logon data for the user is not complete.
  Runtime Error: CALL_FUNCTION_SIGNON_INCOMPL
  
• Cause: The attempt to log on in the form of an internal call to a target system is not valid.
  Runtime Error: CALL_FUNCTION_SIGNON_INTRUDER
  
• Cause: RFC from an external program without a valid user ID.
  Runtime Error: CALL_FUNCTION_SIGNON_INVALID
  
• Cause: The user tried to log onto the target system without a valid user ID.
  Runtime Error: CALL_FUNCTION_SIGNON_REJECTED
  The error code signifies the following:
  1) Incorrect password or invalid user ID
  2) User locked
  3) Too many logon attempts
  5) Error in authorization buffer (internal error)
  6) No external user check
  7) Invalid user type
  8) User's validity interval has been exceeded
  
• Cause: No authorization for logon as a trusted system.
  Runtime Error: CALL_FUNCTION_SINGLE_LOGIN_REJ
  The error code signifies the following:
  0) Incorrect logon data with a valid security key.
  1) Either the calling system is not a trusted trusted system, or the security key is invalid.
  2) Either the user has no RFC authorization (authorization object S_RFCACL) or else someone tried to log on using a protected user, 'DDIC' or 'SAP*'.
  3) The timestamp for the logon data is invalid.
  
• Cause: An RFC without a valid user ID is only allowed for a system function module. The meaning of the error code is the same as for CALL_FUNCTION_SINGLE_LOGIN_REJ.
  Runtime Error: CALL_FUNCTION_SYSCALL_ONLY
  
• Cause: Data error (internal table info) when calling a function remotely
  

Runtime Error: CALL_FUNCTION_TABINFO

• Cause: No memory available for the table to be imported
  Runtime Error: CALL_FUNCTION_TABLE_NO_MEMORY
  

Cause: Only applies to asynchronous RFC: Task name is already being used
Runtime Error: CALL_FUNCTION_TASK_IN_USE

Cause: Only applies to asynchronous RFC: The specified task is already open
Runtime Error: CALL_FUNCTION_TASK_YET_OPEN

• Cause: No trusted authorization for the RFC call and trusted system
  Runtime Error: CALL_RPERF_SLOGIN_AUTH_ERROR
  
• Cause: No valid trusted entry for the calling system
  Runtime Error: CALL_RPERF_SLOGIN_READ_ERROR
  
• Cause: No RFC authorization for the user
  Runtime Error: RFC_NO_AUTHORITY