This document describes how you can program a connection from SAP R/3 acting as a client to an webMethods EntireX RPC server. This connection is used when R/3 initiates the communication.
The following topics are covered here:
With the webMethods EntireX Rfc2Rpc gateway, it is possible to connect SAP R/3 as client to an webMethods EntireX RPC server. In this scenario, R/3 "pushes" information to an external application.
The following figure illustrates communication flow.
Communication between the processes is provided by TCP/IP. With webMethods EntireX, this is executed using a Remote Procedure Call (RPC), and for SAP R/3 using a Remote Function Call (RFC).
The Rfc2Rpc kernel transforms the RFC call to an webMethods EntireX RPC call. Thus, subroutines in webMethods EntireX (for example, Natural) can be called by subroutine reference from SAP R/3 APAB. For R/3, the Rfc2Rpc kernel process acts as a server, and for webMethods EntireX as client.
Both RPC and RFC logs require that in both the client and the server the structure of the parameters such as data type, input or output is submitted. This section also describes the structure of the parameters in the webMethods EntireX IDL.
To develop this scenario:
Define the interface between ABAP and webMethods EntireX in the IDL (Interface Definition Language)
Compile and link the IDL to generate the executable kernels
Browse to the generated ABAP client report for calling the remote service.
Check the webMethods EntireX Broker Attribute File
These steps are described in detail in the following sections, using a calculator program as an example.
For the Rfc2Rpc kernel, you must develop an IDL. In this IDL, you must define the interface between APAB and the webMethods EntireX subprograms. You can generate the contents of this IDL in any of the following ways:
using the IDL Extractor for Natural within webMethods EntireX
using the IDL Extractor for COBOL within webMethods EntireX from the COBOL source code.
The webMethods EntireX documentation contains more information about the Interface Definition Language.
All of the development steps are started from the corresponding page of the menu.
The example IDL file illustrated below contains the RFC function Z_EXX_CALC.
Library 'RFCRPC' Is
Program 'CALC' : 'Z_EXX_CALC' Is
Define Data Parameter
1 Op In
2 Arg1 (A1)
2 Op1 (I4)
2 Op2 (I4)
1 Rc Out
2 Furesult (I4)
END-DEFINE
The name of a subroutine in the ABAP can have up to 32 characters. To maintain the platform and language independence of the protocol layer, webMethods EntireX supports only 8 characters. The ABAP name must therefore be mapped to an webMethods EntireX name. In the above example, CALC is the subroutine name on the server and Z_EXX_CALC is the subroutine name in the ABAP. In this way, all of the programming conventions on the client and the server side can be supported.
This conversion is likewise made in the IDL in the printout program. The webMethods EntireX IDL supports a library concept. A library is introduced with the printout LIBRARY followed by a name. The use of the printout LIBRARY is described in the development environment. All subsequent printout programs within the IDL then belong to this library.
An import or export parameter is a group without multiple occurrences. Therefore, if you have a group defined in the IDL, this must be either IN or OUT. INOUT is possible too. In this case, this group is an import and an export parameter.
A group has 1 in the IDL on the name level and several fields on level 2. The sequence of the fields on level 2 must be the same in the client as in the server. In the ABAP, a parameter is defined by the name. The names of the parameters must therefore be the same in the client as in the server on level 1.
The following data types subsets are supported in the IDL for the Rfc2Rpc kernel:
| IDL Data Type | Description | ABAP Data Type |
|---|---|---|
| Anumber | String with fixed length | (number) TYPE C |
| Nnumber of before digits[.number of after digits] | Unpacked decimal. The after digits information is lost in ABAP. For example with data type N2.2, setting the numeric field to 100 yields a value of 1. | (sum of before and after digits) TYPE N |
| Pnumber of before digits[.number of after digits] | Packed decimal. The internal representation byte length is defined in ABAP language, while external representation is used in webMethods EntireX. To get the evaluated internal representation length, check the generated source ABAP report. | (internal representation length of before and after digits) TYPE P DECIMALS number of after digits |
| L | Logical. Set the value X in the
ABAP report to transport the value true. Otherwise
false is used.
|
(1) TYPE C |
| I4 | Integer. | (4) TYPE I |
Tables in the ABAP are multiple groups. The RFC log supports the transfer of as many developments within the table as desired. However, an upper limit must be input to the IDL. If the client sends more than defined in the IDL, the corresponding webMethods EntireX function is called multiple in a conversation. For example, the table array defines 10 records. The SAP functions send 11. The webMethods EntireX function is called with 10 and with 1 record. The first call opens the conversation and the last call closes the conversation. The conversation is required to hold the contect on server side of all receiving data.
The following section provides a summary of the last 2 abstracts and explains a straight-forward IDL development with some rules. The rules affect the functionality of the RFC protocol.
Define a group with name on level 1. The name defined here must be used in ABAP's CALL FUNCTION statements.
Define an explicit direction IN or OUT for
this group. IN OUT is possible and this parameter must be defined
twice in the IMPORTING and EXPORTING statement.
If this group has more than one occurrence, then define the maximum as multiple group. Now this group is an RFC table.
Define all fields with a type only on level 2 for a specific group.
Define a fixed array size for fields on level 2. See generated ABAP report to pass the fixed array via the RFC protocol.
The following abstract example shows all of the possibilities for group definition:
...
Define Data Parameter
1 MY_GROUP_IN In /* Defined 'in' group for server, exporting in ABAP caller
2 myField (A10)
2 myArray (A10/1:5) /* Fixed array
....
1 MY_GROUP_OUT Out /* Defined multiple 'out' group for server, importing in ABAP caller
2 myField (A10)
2 myArray (A10/1:5) /* Fixed array
...
1 MY_MULTIPLE_GROUP_IN (/1:10) In /* Defined multiple 'in' group for server, send table in ABAP caller
2 myField (A10)
2 myArray (A10/1:5) /* Fixed array
...
1 MY_MULTIPLE_GROUP_OUT (/1:10) Out /* Defined 'out' group for server, receive table in ABAP caller
2 myField (A10)
2 myArray (A10/1:5) /* Fixed array
...
End-Define
When developing the IDL, you defined a function in the IDL. During the compilation and linking process, an ABAP example report is created. This report shows the call to the defined external function. Use on the Develop page to display the generated code.
The data types for importing and exporting, and the tables are generated from the interface definition in IDL. The following example shows the report from the calculator example.
REPORT Z_EXX_CALC. DATA: I TYPE I. *************************** * Import, Export and Tables *************************** DATA: BEGIN OF Op, Arg1(1) TYPE C, Op1(4) TYPE I, Op2(4) TYPE I, END OF Op. DATA: BEGIN OF Rc, Furesult(4) TYPE I, END OF Rc. *************************** * Set export variables *************************** Op-Arg1 = ' '. Op-Op1 = 0. Op-Op2 = 0. Rc-Furesult = 0. *************************** * Call external Z_EXX_CALC * * Remove '*' in lines * for using transactional * and asynchronous RFC *************************** CALL FUNCTION 'Z_EXX_CALC' * IN BACKGROUND TASK DESTINATION 'EXX_GATEWAY' EXPORTING Op = Op IMPORTING Rc = Rc. * CALL FUNCTION 'START_OF_BACKGROUNDTASK' * EXPORTING * STARTDATE = sy-datum * STARTTIME = sy-uzeit. * * COMMIT WORK.
The report contains all of the structures required for data transfer and the statement CALL FUNCTION with DESTINATION. The Rfc2Rpc kernel has been registered with the SAP R/3 Application Server to receive this call.
It is also possible to call the external function with a transactional RFC. This is possible only if data are sent and not received. You must activate the statements IN BACKGROUND TASK, CALL FUNCTION 'START_OF_BACKGROUNDTASK' and COMMIT WORK for a transactional RFC. The advantage of a transactional RFC is that the SAP R/3 Application Server queues these calls if no external Rfc2Rpc kernel is accessible.
If SAP R/3 is the leading system for master data and wants to send the data without any acknowledgement, asychronous communication is preferred. You can develop an IDL (PMQ.idl) for an asynchronous interface. This IDL contains the business interface between applications.
Program 'MESSAGE' : 'Z_EXX_MESSAGE' Is
Define Data Parameter
1 SEND In
2 field1 (A250)
END-DEFINE
Only IN parameters can be defined in this IDL. The Rfc2Rpc kernel generates an asynchronous message (Unit of Work) for the Persistent Message Queue (PMQ) in the webMethods EntireX broker from this information at runtime. The Unit Of Work (UOW) is needed to send the date in transactional mode. Later the message consumer also uses this feature for delivery. The message format (XML or plain text) can be defined as a parameter.
During each of the IDL file's save steps, the file is copied into a separate sub-directory with a current time stamp. This page from the menu (http://YourGateway:8080/sapr3gateway/manager/devAdmin?cfg=2) contains the backup template with the specific sub-directory information.
Choose Compile and Link from the Develop page to start the makefile. The executable's kernels are generated from the synchronous and asynchronous IDL. On the results page, you will see the job output of this process. Please check that the job output report has the response code 0.
To activate the newly-generated version for the runtime environment, you must deploy the executables and restart the Running Task (see Running Task Rfc2Rpc (SAP calls External) Kernel Environment).
By default the internal data between the RFC and RPC protocol is exchanged via stack memory; this can cause problems when large amounts of data are involved. The following parameter allocates static memory:
-D COMBUFFER=static
Add this parameter in Makefile of
http://YourGateway:8080/sapr3gateway/manager/devAdmin?cfg=2
in the command line of ERXIDL.
The webMethods EntireX Broker Attribute File contains the resource definition for asynchronous communication. For example, there are some parameters for the Persistent Store (PSI) and the lifetime of Units of Work (UOWs).
The necessary parameters are described in a list.
In the R/3 programming language, the call to the
webMethods EntireX subroutine with the printout CALL
is given in FUNCTION. The import, export and table parameters are submitted
with the call. In order to route the subroutine reference to the agent (rather
than remaining within the R/3 application server), DESTINATION <target
name> must be added to the above printout. The target name is defined
and assigned by the R/3 administrator. This takes place in the transaction
SM59.
The agent will throw an RFC exception if it cannot establish a connection to the webMethods EntireX Broker. This condition should be intercepted by the calling ABAP program, since otherwise it aborts. The RFC exception is returned to the calling program as text. The exception text consists of prefix, error class and error number.
| Prefix | 'EXX' |
| Error class | webMethods EntireX Error class, 4 digits, with padded 0 |
| Error number | webMethods EntireX Error number, 4 digits, with padded 0 |
Table of most frequent exceptions.
| EXX02150148 | webMethods EntireX Broker not reachable |
| EXX00070007 | RPC Server not started |
| EXX00740074 | RPC Server does not answer in the prescribed time. |
It is possible to define additional parameters in the IDL file for generating UOWs. For example, the SAP client can define the queue name in webMethods EntireX Broker.
Program 'MESSAGE' : 'Z_EXX_MESSAGE' Is
Define Data Parameter
1 EXXIN In
2 server_name (A32)
1 SEND In
2 field1 (A250)
END-DEFINE
If the ABAP client calls this external function, it overwrites the server name of the runtime parameter EXX_PMQ_SERVER_ADDRESS. Note that the EXXIN parameter is not sent to the RPC Server. Using the following fields, you can control how messages are sent to the webMethods EntireX Broker.
| Fieldname | Description |
|---|---|
| server_name | Overwrites the server queue name of EXX_PMQ_SERVER_ADDRESS. |
| broker | Overwrites Broker ID address of EXX_PMQ_SERVER_ADDRESS. |
| lifetime | Defines unit of work lifetime. |
| do_xml | Sends message in XML format. |
| do_rpc | Sends message in RPC format. |
| do_not_uow_query_last | Do not get previous conversation ID. Always create a new conversation ID. |
| waittime | Wait this length of time to receive an answer. |
| do_new_conversation | Enables the client to control the conversation
ID. Set do_new_conversation = 'T' to create always a new
conversation for each UOW. Other value does a query for old existing
conversation.
|