call-sap-rfc()
Note: See also section SAP RFC.
Requests an RFC b at an SAP system that is identified by alias b. Parameters needed for the call are defined in a map c. Fields and tables are returned line by line and are optionally added to a list or XML object f. If e is defined, only the specified fields and tables are used. If an ABAP exception occurs the job will be aborted, if not the name of the exception contains one of the tokens, as listed within param h. Parameter h contains an optional semicolon-separated list of ignored exceptions. If an exception occurred, which is ignored, the value of parameter i is returned instead. Parameter j for RFC queue and parameter k for JCoContext (see parameter table for details).
Parameters
|
Parameter |
Description |
|
a |
The SAP alias. |
|
b |
RFC name. |
|
c |
(optional) Name of the map containing the input parameters. Default: default. See subsection "Filling of parameter Map c before call". |
|
d |
(optional) Time in seconds the function waits for a response for the request. A time lower than three seconds will be ignored. The maximum timeout is 600 seconds. Default: 60 |
|
e |
(optional) Comma-separated list of field and table names and optional indexes the result should be restricted to. Default: No output filtering. See subsections Output Value Restriction with Parameter e (you can also output ABAP exceptions and the entire response in the SAPXML format). |
|
f |
(optional) This parameter allows you to additionally write the response values into a list or an XML object. If the parameter remains empty, neither is done. To additionally write into a list, simply enter its name here. The list is automatically created (or emptied, if it already exists). The response values are then inserted into the list. Filter e is also applied. The return values of the function and the contents of the list are therefore the same. To additionally write into an XML object, please use the prefix :xml: (written exactly like this and without spaces between prefix and name). The XML object is created automatically and will contain the entire response of the RFC. Filter e is not applied! You can evaluate the RFC response in the XML object using the functions select nodes from XML/DOM to List() and get value from XML(). Note: The XML structure in the XML object is identical to the XML structure of the debug file *_debug_RfcOut.xml, which can be written as a local debug file using parameter g. |
|
g |
(optional) true if a trace files of the request should be generated. Default: false . The names of the created trace files will be logged into the job log. File name format: <Job number>_<Timestamp>_debug_<RFC name>_<In|Out>.xml , where for a mapping test the value T is used instead of the job number . The files are written into folder ./debug/sap . Important note: Even if the parameter is set to true, the trace files are only written in a mapping test or if tracing has been activated for phase 3 of the profile (or system-wide). If you always want to write the debug files (e.g. in the test phase as proof for the SAP team), i.e. also in a normal job run and without the tracing in phase 3 activated (with its corresponding overhead), you can also specify the value always . Warning: These files are not automatically deleted, so it is the user's responsibility to monitor this folder and delete files manually to prevent a disk overflow. Please also note that a high number of files in this folder can affect performance. |
|
h |
(optional) Semicolon-separated list of ABAP exceptions to be ignored. |
|
i |
(optional) Return value if an ignored ABAP exception (see parameter h) occurred. |
|
j |
(optional) The RFC queue to be used. If the parameter is left empty, the default queue is used. Warning: If a JCoContext is used (see parameter k), a defined queue is ignored! |
|
k |
(optional) Create JCoContext (true/false). Default: <empty>. Limitation: The JCoContext can only be created for connections with JCo version 3. For aliases with JCo version 2.x, the function terminates with an error occurs if k=true. If a call is made with k=true, a JCoContext is created for alias a, which exists until the end of phase 3 of this profile job (or until a termination with error). Only with an explicit parameter value k=false, you can remove a subsequent call from an existing JCoContext (an empty parameter k does not close the context!). Such a context is required for (stateful) BAPI calls (Business Objects in SAP). All BAPI calls must take place in the same JCoContext because they are contiguous. All calls together are then committed at the end (BAPI_TRANSACTION_COMMIT). If no commit is executed by the end of the JCoContext, the BAPI data transferred to the SAP system within this JCoContext is discarded. Normal RFC calls do not have to be committed, so the JCoContext has no meaning there and should only be created for sequential BAPI calls, since it is very resource-intensive. But you can also call normal RFCs in an existing JCoContext. Note, however, that these are not rolled back if a commit is not made, because they will work without it! Warning: When the JCoContext is created, any queue defined in parameter j is ignored! Note: In the first function call, the value true can also be written in capital letters (TRUE). In that case, the JCoDestination for this job is cloned and an RFC_PING is executed at the beginning to test the connection. |
Filling of parameter map "c" before call
The function expects key-value-pairs following a specific notation in order to be able to assign the values to the corresponding parameters in the RFC.
|
Type of input parameter |
Resulting key per field |
|
A single field. |
fieldName |
|
A structure containing a list of fields (components). |
structureName-fieldName |
|
A table containing fields (components) as rows. |
tableName[rowNumber]-columnName |
If the value in the map contains a text like @variable_name@ and the mapping has a variable with that name defined, the placeholder will be replaced by the value of the variable. Is there no such variable, the text will be unchanged and be used as parameter including the placeholder.
To ease the process of creating the map holding the parameters, the function "fill-map-from-fields()" can be used.
In the case of structures and tables, it must be noted that the components (field names/column names) are not optional. If a component is specified for a structure type, all other components of this structure must also be defined (with an empty value or the default 0 for numeric types). For tables, each row represents a structural value. As a result, all the components of a row must also be defined there. In the case of tables, it is also important to note that the line numbers must be continuous to avoid a premature termination of the parameter list. If the parameter map c is filled with the function "fill-map-from-fields()", all components of structures and tables must be defined as the fields in the target structure of the profile. In order to force the insertion of empty fields as well, the processing statement val:addempty must also be used, as described in the documentation for this function. Fields and tables are returned by the function in the same way as it happens with the call of RFCs using the time-driven Input Agent "SAP" if the output format "FixRecord" has been selected. You will also find an example at the end of this page.
Output value restriction with parameter "e"
To restrict the response to single fields or lines of a specific table, it is enough to specify the names of the field or table names in parameter e, e.g. QUERY_TABLE,DATA. If only a part of the single value is needed, it is possible to define part text areas (substrings) to be used for the creation of the result line. This is done in the form of name[index_definition] or name[index_definition}, whereby the beginning of the line is represented by index 1. The curly bracket at the end results in a removal of trailing spaces in the resulting line. An index definition is defined in the form of [fromIndex+length] or [fromIndex-untilIndex]. The untilIndex is exclusive. If it is omitted, the end of the line is taken. Multiple index definitions can be joined by putting a slash / between them.
Below you can find some variants of output filter definitions. All of them are run against the following example line (spaces where substituted by underlines).
|
DATA__________________________Val1______Val2___Val3________Val4____ |
|
Output filter rule |
Meaning |
Result |
|
DATA |
The complete line. |
Like above. |
|
DATA[1] |
The complete line. |
Like above. |
|
DATA[1} |
The complete line without trailing spaces. |
DATA__[...]__Val4 |
|
DATA[31] |
The line from index 31. |
Val1__[...]__Val4____ |
|
DATA[1-2/31-41/48-60} |
The first character, Field1, Field3 without trailing spaces |
DVal1______Val3 |
|
DATA[1+2/31-41/48-60} |
The first two characters, Field1, Field3 without trailing spaces |
DAVal1______Val3 |
If a list is specified in f, the result of a successful function call is saved in this list and also returned as the result of the function. In the return value, the individual records are separated by a line break, whereas in the list each record is a single list entry.
ABAP exceptions
When the RFC ends with an ABAP exception, then the profile job will end with an error by default. You can modify this behaviour by explicitly inserting the segment EXCEPTION in the parameter e. If so, the ABAP exception is returned within a segment EXCEPTION. Other exceptions from JCo, which do not have the type AbapException, cannot be caught but will terminate the job with an error.
Format "SAPXML"
If one of the filter rules in parameter e is either :SAPXML: or :sapxml:, the entire response of the RFC is returned in the SAPXML format. All other filter rules except EXCEPTION are then ignored.
This XML can optionally be supplied in a single line if :sapxml: (in lower case) is used, or multi-line (formatted) if :SAPXML: (in upper case) is used.
Both options can be used together with parameter f. For single-line XML return, the list will contain the entire XML in one element. For multiline XML return, the list will contain one element per line.
Examples
The call of the function is shown using RFC_READ_TABLE as an example.
Following the profile, this example is based on: Package-SAP RFC Call Example RFC_READ_TABLE.pak
RFC_READ_TABLE
Input parameters
|
Index: |
1 |
2 |
3 |
4 |
5 |
|
Name: |
DELIMITER |
NO_DATA |
QUERY_TABLE |
ROWCOUNT |
ROWSKIPS |
|
Type: |
CHAR |
CHAR |
CHAR |
INT |
INT |
|
Size: |
1 |
1 |
30 |
4 |
4 |
|
Offset: |
0 |
1 |
2 |
32 |
36 |
|
Decimals: |
0 |
0 |
0 |
0 |
0 |
|
Default: |
SPACE |
SPACE |
|
0 |
0 |
|
Value: |
|
|
" " |
|
|
Output parameters
None.
Table parameters
Parameters: TABLES
|
Index: |
1 |
2 |
3 |
|
Name: |
DATA |
FIELDS |
OPTIONS |
|
Type: |
TABLE |
TABLE |
TABLE |
|
Size: |
4 |
6 |
7 |
|
Offset: |
0 |
4 |
10 |
|
Decimals: |
0 |
0 |
0 |
|
Value: |
TAB512 |
RFC_DB_FLD |
RFC_DB_OPT |
Table: DATA (TAB512) No. of Rows: 0 Row-length: 512 (chars) 512 (bytes)
|
Index: |
1 |
|
Name: |
WA |
|
Type: |
CHAR |
|
Size: |
512 |
|
Offset: |
0 |
|
Decimals: |
0 |
Table: FIELDS (RFC_DB_FLD) No. of Rows: 0 Row-length: 103 (chars) 103 (bytes)
|
Index: |
1 |
2 |
3 |
4 |
5 |
|
Name: |
FIELDNAME |
OFFSET |
LENGTH |
TYPE |
FIELDTEXT |
|
Type: |
CHAR |
NUM |
NUM |
CHAR |
CHAR |
|
Size: |
30 |
6 |
6 |
1 |
60 |
|
Offset: |
0 |
30 |
36 |
42 |
43 |
|
Decimals: |
0 |
0 |
0 |
0 |
0 |
Table: OPTIONS (RFC_DB_OPT) No. of Rows: 0 Row-length: 72 (chars) 72 (bytes)
|
Index: |
1 |
|
Name: |
TEXT |
|
Type: |
CHAR |
|
Size: |
72 |
|
Offset: |
0 |
|
Decimals: |
0 |
The description shows the following parameters that are needed to be set in order to call the RFC.
|
Parameter name |
Type |
Meaning |
Field names within that parameter |
|
DELIMITER |
Field Char(1) |
A delimiter to separate single values within a response line. |
n.a. |
|
NO_DATA |
Field Char(1) |
X if no data but only the field information is needed. |
n.a. |
|
QUERY_TABLE |
Field Char(30) |
Name of the database table to read from. |
n.a. |
|
ROWCOUNT |
Field Integer |
Number of rows to read. |
n.a. |
|
ROWSKIPS |
Field Integer |
Number of rows to be skipped before ROWCOUNT rows are read. |
n.a. |
|
DATA |
Table(OUT) |
Contains the read rows after a successful call. |
WA Char(512) |
|
FIELDS |
Table(INOUT) |
Information about the fields being read or - if set in the request - the columns to be read from the table. |
FIELDNAME Char(30) |
|
OPTIONS |
Table(IN) |
Text being added to the internally used SQL statement and regarded as the WHERE part of the statement. |
TEXT Char(72) |
To prepare and perform the RFC call, a target structure like the following can be prepared.
In general, the node CallSapRfc can be organised into two main parts.
Creation of the map that contains all values being needed. Because the RFC in this example does not have any parameters of type structures only two nodes filling the field parameters (node fill_INPUT_PARAMS) and table parameters (node fill_TABLE_PARAMS) are used.
Call of the RFC in the node CALL containing an additional field dumpParamsKeys thatis only used to dump keys and values of the parameter map. This can, for example, be used e.g. in a mapping test.
Filling values into the parameter map
The fields in the nodes are named exactly like the names of the fields in the corresponding parameter (in this case fields and tables, everything following after a # is ignored).
The goal of this example is reducing the number of fields to be read. This is realised by using a list that is filled in the field prepareFieldSelection.
1) save variable a(b) type-safe a constant: VAR_FIELD_SELECTION b constant: MANDT,CARRID,CONNID,FLDATE,PRICE,CURRENCY,PLANETYPE2) add to list(a,b,c) a result: 1 b constant: fieldList c constant: ,3) count values in list(name of list a) a constant: fieldList4) save variable a(b) type-safe a constant: VAR_SIZE b result: 3In every iteration of the node fill_FIELDS the first element of the list at that time is removed.
1) remove from list(position a, name of list b) a constant: 1 b constant: fieldListThese are the functions of the single fill fields.
In field fill_INPUT
1) fill-map-from-fields( map a, prefix b, index c, hidden d ) a constant: inMap b constant: c constant: d constant: falseIn field fill_option_table
1) fill-map-from-fields( map a, prefix b, index c, hidden d ) a constant: inMap b constant: OPTIONS[#] c constant: 1 d constant: trueIn field fill_fields_table
1) calculate and save variable(a,b,c,d,[e]) a constant: VAR_COUNTER b constant: + c constant: 1 d constant: true2) fill-map-from-fields( map a, prefix b, index c, hidden d ) a constant: inMap b constant: FIELDS[#] c variable: VAR_COUNTER d constant: truedumpParamsKeys is only used to dump the keys and values of the parameter map to the log. To prevent this from happening when the mapping runs productively, the variable VAR_IS_TEST is checked.
1) dump map (a,b) a constant: inMap b variable: VAR_IS_TESTThe field callRFC contains the 'main' function for the call of the RFC.
1) call-sap-rfc( alias a,rfc b,[inMap c],[timeout d],[filter e],[outList f],[debug g]) a constant: testsap b constant: RFC_READ_TABLE c constant: inMap d constant: 8 e constant: DATA[1} f constant: outList g constant: trueRFC Call
When starting the test, the dumParamKeys functions will log the following.
[...][M:] Dump of map inMap: 'FIELDS[6]-LENGTH'='0' 'FIELDS[5]-FIELDTEXT'=' ' 'FIELDS[3]-LENGTH'='0' 'FIELDS[7]-OFFSET'='0' 'FIELDS[1]-OFFSET'='0' 'FIELDS[1]-FIELDNAME'='MANDT' 'FIELDS[4]-LENGTH'='0' 'FIELDS[4]-FIELDNAME'='FLDATE' 'FIELDS[7]-TYPE'=' ' 'QUERY_TABLE'='SFLIGHT' 'FIELDS[6]-FIELDTEXT'=' ' 'FIELDS[1]-TYPE'=' ' 'FIELDS[6]-TYPE'=' ' 'FIELDS[7]-FIELDTEXT'=' ' 'FIELDS[2]-FIELDTEXT'=' ' 'FIELDS[2]-LENGTH'='0' 'OPTIONS[1]-TEXT'='CARRID = 'LH''[...] 'FIELDS[2]-OFFSET'='0' 'FIELDS[5]-OFFSET'='0' 'FIELDS[5]-LENGTH'='0' 'FIELDS[1]-LENGTH'='0' 'FIELDS[3]-FIELDNAME'='CONNID' 'FIELDS[2]-TYPE'=' ' 'ROWCOUNT'='@VAR_ROWCOUNT@' 'FIELDS[4]-OFFSET'='0'[...]For technical reasons, the key-value pairs are not sorted.
The call of the function "call-sap-rfc()" leads to the following messages.
15:07:52.768 [M:] Calling SAP by RFC 'RFC_READ_TABLE'15:07:52.893 [M:] rfc debug info: .\debug\sap\1319029672768_debug_RfcIn.xml15:07:52.940 [M:] rfc debug info: .\debug\sap\1319029672768_debug_RfcOut.xml15:07:52.940 [M:] Returning from SAP RFC 'RFC_READ_TABLE' after 172 ms15:07:52.940 [M:field=callRFC] Executed function [Pos=1]call-sap-rfc( alias a,rfc b,[inMap c],[timeout d],[filter e],[outList f],[debug g]), result='DATA 000LH 040020011222 666.00 EUR A310-300DATA 000LH 040020020119 666.00 EUR A310-300DATA 000LH 040020020216 666.00 EUR A310-300DATA 000LH 040020020316 666.00 EUR A310-300DATA 000LH 040020020413 666.00 EUR A310-300'Because parameter g is set to true, trace files were created and their filenames are logged. Because an output list has been specified, containing the rows of output table DATA the result of the function itself - a fix record format - can be ignored or used for bug tracking purposes.
Result processing
In this example, the values of output table DATA were added to the list outList. Every element in that list is a complete row of the table DATA. The single values must be 'extracted' by yourself later on.
The example profile does that in node OUTPUT.
In order to enter the node OUTPUT as often as there are entries in the list, the number of values is saved to a variable of type Integer in field readSize. This variable is used as path in node OUTPUT. The calculation field item always removes the first entry from that list outList using the function "remove from list()", all subsequent functions use the value of this field for further processing (using target field item). Are more than one field or table added to the result (by saying so using parameter e) the different lines must be 'distributed' over the corresponding nodes. For this reason - even if it is not needed in this particular examples - there is a function on node OUTPUT.
1) starts-with( a, b ) a Target field: item b Value: DATAIf the condition is met, the node will be entered and the calculation field data_item will cut away the first 30 characters of the row to let the line start with the first data field of the response.
All subsequent fields are cutting the needed part out of this line using the function "substring()" to eventually continue with the data conversion using other functions. Field FLDATE is shown here as an example:
1) substring( a, start [,length] ) a Target field: data_item b Value: 11 c Value: 82) create date(a, [adj. template b], template c, d [, force-empty e]) a Result: 1 b Value: yyyyMMdd c Value: dd.MM.yyyy d Value: empty e Value:An exemplary result of a node OUTPUT can be seen in the following screenshot.
