Service Orchestrator	Version 1.1.1.3	SEARCH   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT

This adapter enables direct communication from Service Orchestrator to SAP R/3 application server as client and server. The SAP RFC protocol is used to call RFC-enabled functions and the program running ABAP can call a sequence in Service Orchestrator.

• How to install

• How to call SAP Functions as Client

• How to call Sequences as Server

• Starter Kit

• Adapter Functions

• How to configure SAP for external Server

How to install

The first step is to install this adapter as custom component into the Service Orchestrator. Import the delivered ZIP file CSOAdapter4SAPR3.zip into your Service Orchestrator Eclipse project with the File -> Import ... -> Archive file wizard.

After installing the adapter the SAP JCO interface needs an additional system-dependent shared library. Download the JCO library from the SAP Support Portal (Downloads->Support Packages and Patches->Search for Support Packages and Patches) for your target operating system. To find the download page, search for JCO. Unpack and store the file in the file system. Add a library path to this directory in the startup script of Host Manager. Depending on the target operating system, use one of the following environment variables.

Tip:
Add the path to new shared libraries into the front of the existing path only for Host Manager of Service Orchestrator. This configuration step (in setMediatorEnvironment[.bat]|[.sh]) avoids problem with existing SAP GUI installation.

How to call SAP Functions as Client

To call an SAP function, this adapter requires an XML document. The running sequence contains this XML document in the current payload and has a specific structure. The root element is the RFC function name. The following child nodes are input parameters and input tables. The tag name must have the input parameter/table name. The adapter function getFunctionTemplate prints out an XML document with the correct structure. The getFunctionTemplate receives the meta definitions from the SAP repository. The meta definitions are stored in the memory cache of JVM. Therefore, only the first request to get meta information will ask for the SAP repository. At development time, store the retrieving XML document in the Service Orchestrator repository and load the document into the payload before calling this adapter with the call function at runtime.

In detail, an SAP function is called in the following way:

1. Open the connection with the adapter function open().
2. Set the function template into the current payload with getFunctionTemplate().
3. Fill in the sending parameter in the XML document.
4. Call the function with the adapter function call().
5. Close the connection with the adapter function close().

To optimize the loading of function templates into the memory cache, a Service Orchestrator start-up sequence should be called when the Component Factory is started. The adapter function loadRepositoryClientFunction supports a list of SAP function names. The meta information of all these functions is loaded into the memory cache.

How to call Sequences as Server

This case describes how to call Service Orchestrator sequences from an SAP ABAP client. The ABAP programming language calls external programs with the CALL FUNCTION statement. On the CALL FUNCTION statement, an RFC destination parameter must be passed. This RFC destination must be defined with the sm59 transaction.

The first step is to start the server dispatcher with the adapter function startDispatcher(). If the ABAP client calls the CALL FUNCTION the external function, the dispatcher receives the request. The incoming parameters are transformed into an XML document and this document is posted to a Service Orchestrator sequence. The Component Factory starts a sequence. The returned XML document of the calling sequence is received in the dispatcher. The dispatcher replies to the ABAP client with the export parameters.

To stop the server dispatcher, call the adapter stopDispatcher() function with the same parameters as the startDispatcher(). If the connection parameter must be changed, first stop the dispatcher with the old parameters. After this, you can start with new connection parameters.

If a new dispatcher is started before the old one is stopped, it will run a stop and a start (=restart).

Starter Kit

The Starter Kit is a Service Orchestrator project with sequences. The Eclipse import creats a directory demo. There are sequences for the client and server scenarios.

Adapter Functions

This section defines all adapter functions as client and server.

• Open Client Connection

• Open Client Connection with Load Balancing

• Get Function Template

• Call remote RFC Function

• Load Repository Client Function

• Reset Repository Client Functions

• Close Client Connection

• Start Server Dispatcher

• Stop Server Dispatcher

• Exception Handling

• Optional Input Properties

Open Client Connection

Function Declaration:

open( JCOAdapter.client, JCOAdapter.userid, JCOAdapter.password, JCOAdapter.language, JCOAdapter.host, JCOAdapter.systemNumber )

Opens a client connection. The first call of this function creates a client connection cache. A closed connection will be reused at the next request.

Input Properties:

Open Client Connection with Load Balancing

Function Declaration:

openWithLoadBalancing( JCOAdapter.client, JCOAdapter.userid, JCOAdapter.password, JCOAdapter.language, JCOAdapter.mshost, JCOAdapter.r3name, JCOAdapter.group )

Opens a client connection with load balancing options for SAP application server. The first time this function is called, it creates a client connection cache. Closed connection will be reused. The real connection will be created on the first getFunctionTemplate or call request. Therefore, this function does not return connection errors.

Input Properties:

Get Function Template

Function Declaration:

getFunctionTemplate( JCOAdapter.name )

Loads and returns the meta information of the fuction name defined in the target payload. You can use it for calling in the next step.

Input Properties:

Output Payload:

The template document is loaded into the document which is referenced by the property xbd.target.contentID. If this property is not set, the current payload document will be overwritten. The default content type is text/xml. To overwrite the default, set property xbd.target.contentType.

Call remote RFC Function

Function Declaration:

call()

Calls an RFC-enabled function with the opened connection.

Input Payload:

To call a function on server side, an XML document is required in the current payload. To get the structure of the XML ducument, call getFunctionTemplate() with the function name in a previous step.

Output Payload:

The function result is returned in the document which is referenced by the property xbd.target.contentID. If this property is not set, the current payload document will be overwritten. The default content type is text/xml. To overwrite the default, set property xbd.target.contentType.

Load Repository Client Function

Function Declaration:

loadRepositoryClientFunction( JCOAdapter.list )

Loads the meta information for calling remote RFC functions into the local repository. The meta information of each function must be available before it is called.

Input Properties:

Reset Repository Client Functions

Function Declaration:

resetRepositoryClientFunctions()

Reset the repository for all client functions. The meta information is removed from the repository. This function should be called if the interface of an RFC function is changed during the development time. After the reset, call to reload the meta information.

Close Client Connection

Function Declaration:

close()

Close and release all resources of this client connection. The connection handle is marked for reuse.

Start Server Dispatcher

Function Declaration:

startDispatcher( JCOAdapter.gwhost, JCOAdapter.gwserv, JCOAdapter.programID, JCOAdapter.workers, JCOAdapter.sequence, JCOAdapter.unicode )

The connection to SAP application server starts. The dispatcher is established. Incoming requests are dipatched to the sequence which is defined in the parameters.

Input Properties:

Input Payload:

The dispatcher must have meta information about functions and parameters. This adapter function requires an XML document for the meta information. The XML document has the following structure.

1. For one defined function, the root element must have the function name.
2. For more functions, the root element is repository. The next element name is the function name.
3. The next element is an import/export structure, a table or a single field with its name as XML tag name. The table name has a leading s character.
4. A structure or table contains fields.
5. A field as a type and a length. (For some types, the system defines the length.)
6. A structure has a direction, IN for receiving or OUT for sending.

Payload example:

<repository>
	<Z_MY_FUNCTION>
		<INPUT direction="IN">
			<field1 type="CHAR" length="10"/>
			<field2 type="INT"/>
		</INPUT>
		<OUTPUT direction="OUT">
			<field3 type="INT"/>
		</OUTPUT>
		<TABLEs>
			<TABLE>
				<field4 type="FLOAT"/>
			</TABLE>
		</TABLEs>
	</Z_MY_FUNCTION>
</repository>

Data types:

Stop Server Dispatcher

Function Declaration:

stopDispatcher( JCOAdapter.gwhost, JCOAdapter.gwserv, JCOAdapter.programID )

The connection to SAP application server is stopped. No more requests are dispatched. Use the same connection property values to stop that you used to start.

Input Properties:

Exception Handling

If an exception occurs during the adapter function call, the following properties will be set:

Tip:
After an adapter function call, check whether JCOAdapter.exception.LocalizedMessage exists.

Optional Input Properties

Following properties can be set optionally. Some properties can be set for either client or server. In this case, the name contains the target definition.

How to configure SAP for external Server

To call subprograms from an SAP R/3 application server using the ABAP CALL FUNCTION statement, you must define an RFC-Destination. Use the SM59 transaction in SAPGUI to access the following dialog. Create a new RFC destination of the type T with a Program ID. You will reach the Program ID input line by pressing the Registration button.

Use the name of the RFC destination CSO_JCO_ADAPTER in the ABAP CALL FUNCTION '...' DESTINATION='EXX_GATEWAY' statement. The program ID must be set as a property in starting dispatcher. (In the example here, the program ID and RFC-destination are the same strings. You can use different names.)

For Unicode application servers, the RFC communication must be set up with unicode flag.

Tip:
After creating an RFC destination and starting the dispatcher, you can ping the external process with the Test connection button from the R/3 application server.

Note:
The program ID is case sensitive. If you change the program ID or RFC destination name, then restart the server dispatcher to perform a new registration.

The following picture shows the same transaction in SAP 4.7 and in another SAPGUI client.

Select only the Gateway Options, if more than one SAP application server calls the same external server instance. For example, in the SAP production environment there may be several application servers and the RFC client program can run anywhere. Therefore, select one gateway and set the address here. Use the same address with property JCOAdapter.gwhost option in the dispatcher.

www.softwareag.com

© Copyright Software AG 20002007. All rights reserved.

SEARCH   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT