SAP NetWeaver RFC Tcl-API

JMeh 11 Jul 2017 - RfcNwTcl

SAP NetWeaver RFC Tcl-API - Rev. 1.12 from 27. Nov 2014

Tcl-Library for executing RFC (Remote Function Calls) functions in and from a SAP R/3 NetWeaver Server. Data can be transfered in both directions on each call and can contain simple values, complex structures or tables (multiple rows of structures). Each field in a structure or table can itself be a structure or table. This allows nested tables to be transfered on a single RFC call.

The C source compiles on Windows and UNIX systems.
You can download the C sources and some examples here:

http://sesam-gmbh.org/images/Downloads/Public/rfcnwtcl.zip

You need to install the SAP NetWeaver Library (with includes) which you get from the SAP AG (if you are a customer). The libs are named libsapnwrfc.so and libsapucum.so (see Makefile). The corersponding SAP installation package also contains a Perl script for precompiling the source (see Makefile).

Nearly all RFC functions return with the text "RFC_OK" on success or "RFC_ERROR" on failure.

The library is well tested with several RFC applications (client and server) running on AIX, Linux and Windows. They transfer many megabytes of data each day.

Here is a simple client example to call a SAP function (Z_RFC_TEST01) on the SAP server and send a text as a function parameter (REQUTEXT = "A simple test."). The RFC function must be defined in the SAP system and you must have the rights to make this call.:

package require RfcNwTcl
Rfc::Init
Rfc::OpenConnection {DEST TST1}
Rfc::InvokeFunction Z_RFC_TEST01 {REQUTEXT "A simple test."}
Rfc::CloseConnection

Here is a server example to allow SAP to call the Tcl function named "MyCallback" from a SAP server. The name of the callback function from SAP view is Z_RFC_TEST02. It will be installed by invoking InstallServerFunction with both names. The return value of the Tcl function in this example is a table named "TABDAT" containing two rows with three columns. The structure of the function with their parameters must also be defined in the SAP system!

proc MyCallback {connAttr params} {
  return {TABDATA {{123 456 "Row 1"} {789 321 "Row 2"}}}
}

package require RfcNwTcl
Rfc::Init
Rfc::OpenConnection {DEST TST1}
Rfc::InstallServerFunction Z_RFC_TEST02 MyCallback
Rfc::CloseConnection
while 1 {
  if {[Rfc::RegisterServer {DEST TST1}] != "RFC_OK"} break
  set retry true
  while {$retry} {
    switch [Rfc::ListenAndDispatch 600] {
      RFC_OK - RFC_RETRY - RFC_ABAP_EXCEPTION {
        set retry true
      }
      default {
        set retry false
      }
    }
  }
  Rfc::CloseConnection
}

For all above examples the SAP connection requires to have a NetWeaver INI file named "sapnwrfc.ini" with the following contents:

DEST=TST1
TYPE=A
PROGRAM_ID=NWTEST1
GWHOST=192.168.0.100
GWSERV=sapservice
ASHOST=192.168.0.100
SYSNR=123
CLIENT=001
USER=sapuser
PASSWD=sappasswd
LANG=DE
TRACE=0

The contents must be modified to match your SAP server requirements.

Functions:

Rfc::DictToString dictValue

Convert dictionary to readable text.

Example:

set info [Rfc::DescribeFunction Z_RFC_TEST01]
puts [Rfc::DictToString $info]

Rfc::GetVersion

Return the version number of the C-library.

Example:

set info [Rfc::GetVersion]

Rfc::Init

Initialize the Library. Must be the first RFC-function to call.

Example:

set rc [Rfc::Init]

Rfc::OpenConnection destination

Opens a client connection to the SAP server. The parameter must specify a destination of the INI file (see above) or the whole destination definition (without the INI file).

Example 1:

set rc [Rfc::OpenConnection {DEST TST1}]

Example 2:

set connectionInfo {
  TYPE       A
  PROGRAM_ID NWTEST1
  GWHOST     192.168.0.100
  GWSERV     sapservice
  ASHOST     192.168.0.100
  SYSNR      123
  CLIENT     001
  USER       sapuser
  PASSWD     sappasswd
  LANG       DE
  TRACE      0
}
set rc [Rfc::OpenConnection $connectionInfo]

Rfc::GetConnectionAttributes

Read the connection attributes (as a Tcl dictionary) from an existing SAP connection.
The following dict items will be filled:

dest
host
partnerHost
sysNumber
sysId
client
user
language
trace
isoLanguage
codepag
partnerCodepage
rfcRole
type
partnerType
release
partnerRelease
kernelRelease
cpicConvId
progName
partnerBytesPerChar
partnerSystemCodepage

Example:

set info [Rfc::GetConnectionAttributes]

Rfc::DescribeFunction functionName

Get a function description (as a Tcl dictionary) from an existing SAP function.
The dict contains the following elements:

name (name of the RFC function)
params (number of params of the RFC function)
param_I (with I as 0..params-1 for each parameter)

A parameter itself contains the following items:

name (name of the parameter)
type (the SAP data type name)
direction (parameter direction):
- RFC_EXPORT
- RFC_IMPORT
- RFC_CHANGING
- RFC_TABLES
optional (specifies whether the value for this parameter has to be filled)
length (size of the parameter in bytes)
info (info text / comment)
struct (only if the parameter is a struct or a table):
- type (type as RFCTYPE_STRUCTURE or RFCTYPE_TABLE)
- name (name of the structure or table)
- fields (number of fields in the structure or table)
- field_J (with J as 0..fields-1 for each structure):
  - name (name of the field in the structure or table)
  - type (data type of the field)
  - length (byte length of the field)
  - offset (byte offset of the field)

The following RFC data types exist:

RFCTYPE_CHAR (1-byte or multibyte character, fixed size, blank padded)
RFCTYPE_DATE (Date YYYYYMMDD)
RFCTYPE_BCD (Packed number, any length between 1 and 16 bytes)
RFCTYPE_TIME (Time (HHMMSS)
RFCTYPE_BYTE (Raw data, binary, fixed length, zero padded.)
RFCTYPE_TABLE (Internal table)
RFCTYPE_NUM (Digits, fixed size, leading '0' padded.)
RFCTYPE_FLOAT (Floating point, double precision)
RFCTYPE_INT (4-byte integer)
RFCTYPE_ABAPOBJECT (ABAP object.)
RFCTYPE_STRUCTURE (ABAP structure)
RFCTYPE_DECF16 (IEEE 754r decimal floating point, 8 bytes)
RFCTYPE_DECF34 (IEEE 754r decimal floating point, 16 bytes)
RFCTYPE_XMLDATA (No longer used!)
RFCTYPE_STRING (Variable-length, null-terminated string)
RFCTYPE_XSTRING (Variable-length raw string, length in bytes)
RFCTYPE_INT8 (8-byte integer)
RFCTYPE_UTCLONG (timestamp/long, 8-byte integer)
RFCTYPE_UTCSECOND (timestamp/second, 8-byte integer)
RFCTYPE_UTCMINUTE (timestamp/minute, 8-byte integer)
RFCTYPE_DTDAY (date/day , 4-byte integer)
RFCTYPE_DTWEEK (date/week, 4-byte integer
RFCTYPE_DTMONTH (date/month, 4-byte integer)
RFCTYPE_TSECOND (time/second, 4-byte integer)
RFCTYPE_TMINUTE (time/minute, 2-byte integer)
RFCTYPE_CDAY (calendar day, 2-byte integer)

Example:

set info [Rfc::DescribeFunction Z_RFC_TEST01]
puts [Rfc::DictToString $info]

Rfc::GetErrorInfo

Get the error description of the last RFC error.

Example:

set info [Rfc::GetErrorInfo]
puts [Rfc::DictToString $info]

Rfc::InvokeFunction functionName parameterDict

Call a RFC function in the SAP system. The parameterDict must be filled with parameter values (see Rfc::DescribeFunction).

Example:

set params {
  PARAMTEXT "Only a Test."
  PARAMVAL1 4711
  PARAMVAL2 3.14159
  PARAMTAB {
    {123 456 "Hello there"}
    {789 321 "With german umlaut: äöüß ÄÖÜ"}
    {893 111 "Third row"}
  }
}
set result [Rfc::InvokeFunction Z_RFC_TEST01 $params]

Rfc::InstallServerFunction functionName callbackProc

Installs a Tcl callback function which can be called from SAP to transfer data to or from the client (or both).

Example:

proc MyCallback {connAttr params} {
  return {TABDATA {{123 456 "Row 1"} {789 321 "Row 2"}}}
}

Rfc::InstallServerFunction Z_RFC_TEST02 MyCallback

Rfc::RegisterServer loginParams

Connects to the SAP server and registers a server which can invoke Tcl functions. The connection to the SAP system must be closed to call this function. To install the callback function you have first connect to SAP as a client, call DescribeFunction, disconnect from SAP and then call RegisterServer to connect as a logical sever.

Example:

Rfc::OpenConnection {DEST TST1}
Rfc::InstallServerFunction Z_RFC_TEST02 MyCallback
Rfc::CloseConnection

set rc [Rfc::RegisterServer {DEST TST1}]

Rfc::ListenAndDispatch timeoutSeconds

After calling RegisterServer we can wait for incoming calls from the SAP system. This function is blocked until SAP makes a call or until a timeout event occurred.
The following result values are defined:

RFC_OK (success)
RFC_RETRY (timeout)
RFC_ABAP_EXCEPTION (ABAP-error)
RFC_ABAP_MESSAGE (function terminated, read error text with GetErrorInfo)
RFC_EXTERNAL_FAILURE (system error)
RFC_COMMUNICATION_FAILURE (communication error)
RFC_CLOSED (SAP has closed the connection)
RFC_NOT_FOUND (callback function not found)

Example:

set rc [Rfc::ListenAndDispatch 600]
if {$rc == "RFC_OK"} {
  # yeah :-)
}

Rfc::Ping

Make a RFC connection check to the SAP server.

Example:

set rc [Rfc::Ping]