''[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.<<br>>
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.:

======tcl
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!

======tcl
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:

======none
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'''<<br>>
Convert dictionary to readable text.<<br>>
Example:

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

'''Rfc::GetVersion'''<<br>>
Return the version number of the C-library.<<br>>
Example:

======tcl
set info [Rfc::GetVersion]
======

'''Rfc::Init'''<<br>>
Initialize the Library. Must be the first RFC-function to call.<<br>>
Example:

======tcl
set rc [Rfc::Init]
======

'''Rfc::OpenConnection destination'''<<br>>
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).<<br>>
Example 1:

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

Example 2:

======tcl
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'''<<br>>
Read the connection attributes (as a Tcl dictionary) from an existing SAP connection.<<br>>
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:

======tcl
set info [Rfc::GetConnectionAttributes]
======

'''Rfc::DescribeFunction functionName'''<<br>>
Get a function description (as a Tcl dictionary) from an existing SAP function.<<br>>
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:

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

'''Rfc::GetErrorInfo'''<<br>>
Get the error description of the last RFC error.<<br>>
Example:

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

'''Rfc::InvokeFunction functionName parameterDict'''<<br>>
Call a RFC function in the SAP system. The parameterDict must be filled with parameter
values (see Rfc::DescribeFunction).<<br>>
Example:

======tcl
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'''<<br>>
Installs a Tcl callback function which can be called from SAP to transfer data 
to or from the client (or both).<<br>>
Example:

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

Rfc::InstallServerFunction Z_RFC_TEST02 MyCallback
======

'''Rfc::RegisterServer loginParams'''<<br>>
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.<<br>>
Example:

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

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

'''Rfc::ListenAndDispatch timeoutSeconds'''<<br>>
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.<<br>>
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:

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

'''Rfc::Ping'''<<br>>
Make a RFC connection check to the SAP server.<<br>>
Example:

======tcl
set rc [Rfc::Ping]
======