com.ibm.di.fc.sapr3rfc
Class SapR3RfcFC

java.lang.Object
  extended by com.ibm.di.fc.Function
      extended by com.ibm.di.fc.sapr3rfc.SapR3RfcFC
All Implemented Interfaces:
FunctionInterface, VersionInfoInterface

public final class SapR3RfcFC
extends Function

ITDI Function Component for SAP R/3 RFC Invocations.

This function component provides the ability to invoke an arbitrary ABAP RFC that is exposed by SAP R/3. It supports SAP R/3 4.6C.

This FC establishes connections and invokes RFCs using SAPs middleware JCo. To use this function component the correct version of JCo (currently 2.1.3) must be installed on your system. See http://service.sap.com/connectors for details on how to download and install SAP JCo.

Configuration is accomplished by setting logon parameters for client connections to R/3. The parameters are very similar to the logon parameters for the traditional SAP GUI. See initialize for more details on how to initialize.

initialize(java.lang.Object) must be the first operation called in this class. perform(java.lang.Object) can then be called one or more times. terminate() must be called to allow connection cleanup before the class is destroyed.

A typical connection to SAP requires setting the following SAP client configuration parameters. These should be set prior to calling initialize.

Additional parameters are also available. See the table of PARAM_CONFIG_* values for a brief explanation.

Using the FC
It can be placed in an assembly line or invoked directly from script. It is the callers' responsibility to check the returned Entry object for any errors that may have resulted from invoking the RFC. The FC can be invoked directly from script. As an example the following code can be used to invoke an RFC from JavaScript using the XML string style:

var fc = system.getFunction("ibmdi.SapR3RfcFC");
var docResponse = null;
var response;
fc.setParam(fc.PARAM_CONFIG_CLIENT, "200");
fc.setParam(fc.PARAM_CONFIG_USER, "SMITH");
fc.setParam(fc.PARAM_CONFIG_PASSWORD, "PASSWORD");
fc.setParam(fc.PARAM_CONFIG_SYSNUMBER, "11");
fc.setParam(fc.PARAM_CONFIG_APPLICATION_SERVER, "servername");
fc.initialize(null);
var rfc = new java.lang.String("<BAPI_COMPANYCODE_GETLIST/>");
var myentry = system.newEntry();
myentry.setAttribute(fc.PARAM_INPUT, rfc);
Attribute reqType = new Attribute();
reqType.addValue(SapR3RfcFC.PARAM_VAL_STRING);
entry.setAttribute(SapR3RfcFC.PARAM_INPUT_TYPE, reqType);
myentry = fc.perform(myentry);
var output = myentry.getAttribute(fc.PARAM_OUTPUT);
response = output.getValue(0);
fc.terminate();

Note that configuration parameters must be set before initialize() is called, and terminate() should be called to cleanup.

Here is another example invoking the RFC FC using the multi valued attributes style:
var rfc = system.newAttribute("BAPI_SALESORDER_GETLIST");
var attr1 = system.newAttribute("CUSTOMER_NUMBER");
attr1.addValue("0000000016");
var attr2 = system.newAttribute("SALES_ORGANIZATION");
attr2.addValue("AU01");
rfc.addValue(attr1);
rfc.addValue(attr2);
var entry = system.newEntry();
entry.setAttribute("requestType", "multiValuedAttributes");
var reqAttr = entry.newAttribute("request");
reqAttr.addValue(rfc);
var result = fc.perform(entry);


Field Summary
static java.lang.String PARAM_CONFIG_ABAP_DEBUG
          Enable ABAP debugging 0 or 1 (jco.client.abap_debug).
static java.lang.String PARAM_CONFIG_ALIAS_USER
          Alias user name (jco.client.alias_user).
static java.lang.String PARAM_CONFIG_APPLICATION_SERVER
          SAP application server (jco.client.ashost).
static java.lang.String PARAM_CONFIG_CLIENT
          SAP client (jco.client.client).
static java.lang.String PARAM_CONFIG_CODEPAGE
          Initial codepage in SAP notation (jco.client.codepage).
static java.lang.String PARAM_CONFIG_DSR
          Enable (1) or Disable (0) dsr support (jco.client.dsr).
static java.lang.String PARAM_CONFIG_EXTERNAL_AUTHENTICATION_DATA
          Data for external authentication (PAS) (jco.client.extiddata).
static java.lang.String PARAM_CONFIG_EXTERNAL_ID_TYPE
          Type of external authentication (PAS) (jco.client.extidtype).
static java.lang.String PARAM_CONFIG_GATEWAY_HOST
          Gateway host (jco.client.gwhost).
static java.lang.String PARAM_CONFIG_GATEWAY_SERVICE
          Gateway service (jco.client.gwserv).
static java.lang.String PARAM_CONFIG_GETSSO2
          Get/Don't get a SSO ticket after logon (1 or 0) (jco.client.getsso2).
static java.lang.String PARAM_CONFIG_GROUP
          Group of SAP application servers (jco.client.group).
static java.lang.String PARAM_CONFIG_IDLE_TIMEOUT
          Idle timeout (in seconds) for the connection after which it will be closed by R/3.
static java.lang.String PARAM_CONFIG_LANGUAGE
          Logon language (jco.client.lang).
static java.lang.String PARAM_CONFIG_LOGON_CHECK
          Enable/Disable logon check at open time, 1 (enable) or 0 (disable) (jco.client.lcheck).
static java.lang.String PARAM_CONFIG_MESSAGE_SERVER
          SAP message server (jco.client.mshost).
static java.lang.String PARAM_CONFIG_MYSAPSS02
          Use the specified SAP Cookie Version 2 as logon ticket (jco.client.mysapsso2).
static java.lang.String PARAM_CONFIG_PASSWORD
          Logon password (jco.client.passwd).
static java.lang.String PARAM_CONFIG_R3NAME
          SAP R/3 name (jco.client.r3name).
static java.lang.String PARAM_CONFIG_SAPLOGON_ID
          String defined for SAPLOGON on 32-bit Windows (jco.client.saplogon_id).
static java.lang.String PARAM_CONFIG_SNC_LIB
          Path to library which provides SNC service (jco.client.snc_lib).
static java.lang.String PARAM_CONFIG_SNC_MODE
          Secure network connection (SNC) mode, 0 (off) or 1 (on) (jco.client.snc_mode).
static java.lang.String PARAM_CONFIG_SNC_MYNAME
          SNC name.
static java.lang.String PARAM_CONFIG_SNC_PARTNERNAME
          SNC partner, e.g.
static java.lang.String PARAM_CONFIG_SNC_QOP
          SNC level of security, 1 to 9 (jco.client.snc_qop).
static java.lang.String PARAM_CONFIG_SYSNUMBER
          SAP system number (jco.client.sysnr).
static java.lang.String PARAM_CONFIG_TPHOST
          Host of external server program (jco.client.tphost).
static java.lang.String PARAM_CONFIG_TPNAME
          Program ID of external server program (jco.client.tpname).
static java.lang.String PARAM_CONFIG_TRACE
          1 (Enable) or 0 (disable) RFC trace (jco.client.trace).
static java.lang.String PARAM_CONFIG_TYPE
          Type of remote host 2 = R/2, 3 = R/3, E = External (jco.client.type).
static java.lang.String PARAM_CONFIG_USE_SAPGUI
          Use remote SAP graphical user interface (0/1/2) (jco.client.use_sapgui).
static java.lang.String PARAM_CONFIG_USER
          Logon user (jco.client.user).
static java.lang.String PARAM_CONFIG_X509_CERTFICATE
          Use the specified X509 certificate as logon ticket (jco.client.x509cert).
static java.lang.String PARAM_INPUT
          Attribute name of the RFC request.
static java.lang.String PARAM_INPUT_TYPE
          Attribute named requestType set on Entry input.
static java.lang.String PARAM_JCO_CLIENT_OPTIONS_PREFIX
           
static java.lang.String PARAM_OUTPUT
          Attribute name of the RFC response.
static java.lang.String PARAM_OUTPUT_TYPE
          Name of attribute on output with string value indicating response type.
static java.lang.String PARAM_VAL_DOM_DOCUMENT
          Used to indicate response/request of type DOM document.
static java.lang.String PARAM_VAL_MVA
          Used to identify response/request of type Attribute.
static java.lang.String PARAM_VAL_STRING
          Used to indicate response/request of type XML string.
 
Fields inherited from class com.ibm.di.fc.Function
logger
 
Constructor Summary
SapR3RfcFC()
          Constructor.
 
Method Summary
static java.lang.String[] getJCOClientOptions()
          Returns thelist of available JCO Client Options
 java.lang.String getVersion()
          Returns the version of this FC.
 void initialize(java.lang.Object o)
          This function is called once after the connector configuration file has been provided by the caller.
 void logError(java.lang.String msg)
           
 java.lang.Object perform(java.lang.Object obj)
           Execute the RFC.
 void setLog(Log arg0)
          Sets the logger object to use in this FC
 void setParam(java.lang.String param, java.lang.Object value)
          Sets a named parameter in the configuration.
 void terminate()
          This function is called when the connector is no longer needed by the user.
 
Methods inherited from class com.ibm.di.fc.Function
debug, getConfiguration, getContext, getDebug, getLog, getParam, getRSInterface, getUI, initialize, logmsg, querySchema, setConfiguration, setContext, setDebug, setRSInterface, updateSchema, verifyInitialized
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PARAM_JCO_CLIENT_OPTIONS_PREFIX

public static final java.lang.String PARAM_JCO_CLIENT_OPTIONS_PREFIX
See Also:
Constant Field Values

PARAM_CONFIG_CLIENT

public static final java.lang.String PARAM_CONFIG_CLIENT
SAP client (jco.client.client).

See Also:
Constant Field Values

PARAM_CONFIG_USER

public static final java.lang.String PARAM_CONFIG_USER
Logon user (jco.client.user).

See Also:
Constant Field Values

PARAM_CONFIG_ALIAS_USER

public static final java.lang.String PARAM_CONFIG_ALIAS_USER
Alias user name (jco.client.alias_user).

See Also:
Constant Field Values

PARAM_CONFIG_PASSWORD

public static final java.lang.String PARAM_CONFIG_PASSWORD
Logon password (jco.client.passwd).

See Also:
Constant Field Values

PARAM_CONFIG_SYSNUMBER

public static final java.lang.String PARAM_CONFIG_SYSNUMBER
SAP system number (jco.client.sysnr).

See Also:
Constant Field Values

PARAM_CONFIG_APPLICATION_SERVER

public static final java.lang.String PARAM_CONFIG_APPLICATION_SERVER
SAP application server (jco.client.ashost).

See Also:
Constant Field Values

PARAM_CONFIG_MESSAGE_SERVER

public static final java.lang.String PARAM_CONFIG_MESSAGE_SERVER
SAP message server (jco.client.mshost).

See Also:
Constant Field Values

PARAM_CONFIG_GATEWAY_HOST

public static final java.lang.String PARAM_CONFIG_GATEWAY_HOST
Gateway host (jco.client.gwhost).

See Also:
Constant Field Values

PARAM_CONFIG_GATEWAY_SERVICE

public static final java.lang.String PARAM_CONFIG_GATEWAY_SERVICE
Gateway service (jco.client.gwserv).

See Also:
Constant Field Values

PARAM_CONFIG_LANGUAGE

public static final java.lang.String PARAM_CONFIG_LANGUAGE
Logon language (jco.client.lang).

See Also:
Constant Field Values

PARAM_CONFIG_TRACE

public static final java.lang.String PARAM_CONFIG_TRACE
1 (Enable) or 0 (disable) RFC trace (jco.client.trace).

See Also:
Constant Field Values

PARAM_CONFIG_CODEPAGE

public static final java.lang.String PARAM_CONFIG_CODEPAGE
Initial codepage in SAP notation (jco.client.codepage).

See Also:
Constant Field Values

PARAM_CONFIG_SNC_MODE

public static final java.lang.String PARAM_CONFIG_SNC_MODE
Secure network connection (SNC) mode, 0 (off) or 1 (on) (jco.client.snc_mode).

See Also:
Constant Field Values

PARAM_CONFIG_SNC_PARTNERNAME

public static final java.lang.String PARAM_CONFIG_SNC_PARTNERNAME
SNC partner, e.g. p:CN=R3, O=XYZ-INC, C=EN (jco.client.snc_partnername).

See Also:
Constant Field Values

PARAM_CONFIG_SNC_QOP

public static final java.lang.String PARAM_CONFIG_SNC_QOP
SNC level of security, 1 to 9 (jco.client.snc_qop).

See Also:
Constant Field Values

PARAM_CONFIG_SNC_MYNAME

public static final java.lang.String PARAM_CONFIG_SNC_MYNAME
SNC name. Overrides default SNC partner (jco.client.snc_myname).

See Also:
Constant Field Values

PARAM_CONFIG_SNC_LIB

public static final java.lang.String PARAM_CONFIG_SNC_LIB
Path to library which provides SNC service (jco.client.snc_lib).

See Also:
Constant Field Values

PARAM_CONFIG_R3NAME

public static final java.lang.String PARAM_CONFIG_R3NAME
SAP R/3 name (jco.client.r3name).

See Also:
Constant Field Values

PARAM_CONFIG_GROUP

public static final java.lang.String PARAM_CONFIG_GROUP
Group of SAP application servers (jco.client.group).

See Also:
Constant Field Values

PARAM_CONFIG_TPNAME

public static final java.lang.String PARAM_CONFIG_TPNAME
Program ID of external server program (jco.client.tpname).

See Also:
Constant Field Values

PARAM_CONFIG_TPHOST

public static final java.lang.String PARAM_CONFIG_TPHOST
Host of external server program (jco.client.tphost).

See Also:
Constant Field Values

PARAM_CONFIG_TYPE

public static final java.lang.String PARAM_CONFIG_TYPE
Type of remote host 2 = R/2, 3 = R/3, E = External (jco.client.type).

See Also:
Constant Field Values

PARAM_CONFIG_ABAP_DEBUG

public static final java.lang.String PARAM_CONFIG_ABAP_DEBUG
Enable ABAP debugging 0 or 1 (jco.client.abap_debug).

See Also:
Constant Field Values

PARAM_CONFIG_USE_SAPGUI

public static final java.lang.String PARAM_CONFIG_USE_SAPGUI
Use remote SAP graphical user interface (0/1/2) (jco.client.use_sapgui).

See Also:
Constant Field Values

PARAM_CONFIG_GETSSO2

public static final java.lang.String PARAM_CONFIG_GETSSO2
Get/Don't get a SSO ticket after logon (1 or 0) (jco.client.getsso2).

See Also:
Constant Field Values

PARAM_CONFIG_MYSAPSS02

public static final java.lang.String PARAM_CONFIG_MYSAPSS02
Use the specified SAP Cookie Version 2 as logon ticket (jco.client.mysapsso2).

See Also:
Constant Field Values

PARAM_CONFIG_X509_CERTFICATE

public static final java.lang.String PARAM_CONFIG_X509_CERTFICATE
Use the specified X509 certificate as logon ticket (jco.client.x509cert).

See Also:
Constant Field Values

PARAM_CONFIG_LOGON_CHECK

public static final java.lang.String PARAM_CONFIG_LOGON_CHECK
Enable/Disable logon check at open time, 1 (enable) or 0 (disable) (jco.client.lcheck).

See Also:
Constant Field Values

PARAM_CONFIG_SAPLOGON_ID

public static final java.lang.String PARAM_CONFIG_SAPLOGON_ID
String defined for SAPLOGON on 32-bit Windows (jco.client.saplogon_id).

See Also:
Constant Field Values

PARAM_CONFIG_EXTERNAL_AUTHENTICATION_DATA

public static final java.lang.String PARAM_CONFIG_EXTERNAL_AUTHENTICATION_DATA
Data for external authentication (PAS) (jco.client.extiddata).

See Also:
Constant Field Values

PARAM_CONFIG_EXTERNAL_ID_TYPE

public static final java.lang.String PARAM_CONFIG_EXTERNAL_ID_TYPE
Type of external authentication (PAS) (jco.client.extidtype).

See Also:
Constant Field Values

PARAM_CONFIG_IDLE_TIMEOUT

public static final java.lang.String PARAM_CONFIG_IDLE_TIMEOUT
Idle timeout (in seconds) for the connection after which it will be closed by R/3. Only positive values are allowed. (jco.client.idle_timeout).

See Also:
Constant Field Values

PARAM_CONFIG_DSR

public static final java.lang.String PARAM_CONFIG_DSR
Enable (1) or Disable (0) dsr support (jco.client.dsr).

See Also:
Constant Field Values

PARAM_INPUT_TYPE

public static final java.lang.String PARAM_INPUT_TYPE
Attribute named requestType set on Entry input.

See Also:
Constant Field Values

PARAM_OUTPUT_TYPE

public static final java.lang.String PARAM_OUTPUT_TYPE
Name of attribute on output with string value indicating response type.

See Also:
Constant Field Values

PARAM_VAL_DOM_DOCUMENT

public static final java.lang.String PARAM_VAL_DOM_DOCUMENT
Used to indicate response/request of type DOM document.

See Also:
Constant Field Values

PARAM_VAL_STRING

public static final java.lang.String PARAM_VAL_STRING
Used to indicate response/request of type XML string.

See Also:
Constant Field Values

PARAM_VAL_MVA

public static final java.lang.String PARAM_VAL_MVA
Used to identify response/request of type Attribute.

See Also:
Constant Field Values

PARAM_INPUT

public static final java.lang.String PARAM_INPUT
Attribute name of the RFC request.

See Also:
Constant Field Values

PARAM_OUTPUT

public static final java.lang.String PARAM_OUTPUT
Attribute name of the RFC response.

See Also:
Constant Field Values
Constructor Detail

SapR3RfcFC

public SapR3RfcFC()
Constructor.

Method Detail

setParam

public void setParam(java.lang.String param,
                     java.lang.Object value)
Description copied from class: Function
Sets a named parameter in the configuration.

Specified by:
setParam in interface FunctionInterface
Overrides:
setParam in class Function
Parameters:
param - The new parameter's name
value - The new parameter value

terminate

public void terminate()
               throws SapR3RfcFCException,
                      java.lang.Exception
This function is called when the connector is no longer needed by the user. Always call terminate which will take care of releasing resources, closing parsers etc.

Specified by:
terminate in interface FunctionInterface
Overrides:
terminate in class Function
Throws:
java.lang.Exception - If super class terminate fails.
SapR3RfcFCException - If internal SAP connection closure fails.

initialize

public void initialize(java.lang.Object o)
                throws java.lang.Exception
This function is called once after the connector configuration file has been provided by the caller.

Specified by:
initialize in interface FunctionInterface
Overrides:
initialize in class Function
Parameters:
o - The configuration object from TDI.
Throws:
java.lang.Exception - If super class initialize fails.

getVersion

public java.lang.String getVersion()
Returns the version of this FC.

Returns:
String version + build date

getJCOClientOptions

public static java.lang.String[] getJCOClientOptions()
Returns thelist of available JCO Client Options

Returns:
String[] PARAM_JCO_CLIENT_OPTIONS

perform

public java.lang.Object perform(java.lang.Object obj)
                         throws SapR3RfcFCException,
                                SapR3FCParameterException

Execute the RFC. Must be called prior to calling this method.

The perform() method accepts an Entry object. If anything else is passed an Exception is thrown.

The Entry object contains two attributes: request and requestType. It supports three styles of invocation.

The value of requestType can be one of xmlDomDocument, xmlString, multiValuesAttributes. It indicates the type of the value associated with request.

The value of attribute request is a type of java.lang.String, org.w3c.dom.Document or com.ibm.di.entry.Attribute which contains the request as either a XML String, DOM Document, or multi-valued Attribute. Any other value will result in an Exception being thrown.

If request is of type org.w3c.dom.Document, then its associated value must be an org.w3c.dom.Document containing an XSchema which conforms to the specification for ABAP RFC XML serialization (see http://ifr.sap.com).

If request is of type java.lang.String, then its associated value must be an XML string. The string value will be parsed by a DOM parser. Its XSchema must also conform to the specification for Serialization of ABAP Data in XML (see http://ifr.sap.com).

If request is a multi-valued attribute the first value of attribute request must be of type java.lang.String containing the name of the RFC, while the second value of the attribute request must be com.ibm.di.entry.Attribute whose values contain additional attributes for the SAP RFC parameters as a series of nested and multi-valued attributes representing the names of the import and table parameters of the RFC. The names of the parameters must be encoded according to the rules for Serialization of ABAP Data in XML (i.e. names will not have characters that could result in badly formed XML).

For example Java code for BAPI_USER_GET_DETAIL where USERNAME = SAP* would be:

Attribute inputAttrib = new Attribute();
Attribute username = new Attribute();
Attribute user = new Attribute();
Entry entry = new Entry();
inputAttrib.addValue("BAPI_USER_GET_DETAIL");
inputAttrib.addValue(username);
username.addValue(user);
user.setName("USERNAME");
user.addValue("SAP*");
entry.setAttribute(SapR3RfcFC.PARAM_INPUT, inputAttrib);
Attribute reqType = new Attribute();
reqType.addValue(SapR3RfcFC.PARAM_VAL_MVA);
entry.setAttribute(SapR3RfcFC.PARAM_INPUT_TYPE, reqType);

On response the Entry will contain the attributes responseType and response. Attribute responseType will have a java.lang.String value corresponding to the input request type.

If the Entry contains an attribute responseType with value xmlDomResponse. The value of Attribute response is an org.w3c.dom.Document containing the RFC response.

If the Entry contains an attribute responseType with value xmlString. The value of Attribute response is a XML java.lang.String containing the RFC response.

If the Entry contains an attribute responseType with value multiValuedAttributes. The value of Attribute response is a nested and multi-valued Attribute where the first value is a java.lang.String which has the name of the RFC that was invoked, the second value contains the results of the RFC as a series of nested multi-valued attributes.

Parameters:
obj - Must be an Entry object.
Returns:
Entry
Throws:
SapR3RfcFCException - thrown when errors occur invoking RFC
SapR3FCParameterException - thrown when format of Entry on input is incorrect
See Also:
initialize(java.lang.Object)

logError

public void logError(java.lang.String msg)

setLog

public void setLog(Log arg0)
Description copied from class: Function
Sets the logger object to use in this FC

Specified by:
setLog in interface FunctionInterface
Overrides:
setLog in class Function
Parameters:
arg0 - The log object