Connection related API
[Public API]

Detailed Description

Opening and closing client & server connections.


Classes

struct  _RFC_ATTRIBUTES
 Structure returned by RfcGetConnectionAttributes() giving some information about the partner system on the other side of this RFC connection. More...
struct  _RFC_SECURITY_ATTRIBUTES
 Structure passed to the RFC_SERVER_AUTHORIZATION_HANDLER giving some security related information about the calling ABAP partner of an incoming RFC call. More...
struct  _RFC_SERVER_CONTEXT
 Used in RfcGetServerContext() for obtaining more information about the current incoming function call. More...
struct  _RFC_CONNECTION_HANDLE
 Handle to an RFC connection (client connection or server connection). More...
struct  _RFC_CONNECTION_PARAMETER
 Structure used for connecting to a backend system via RfcOpenConnection() or RfcRegisterServer(). More...

Enumerations

enum  _RFC_CALL_TYPE { RFC_SYNCHRONOUS, RFC_TRANSACTIONAL, RFC_QUEUED, RFC_BACKGROUND_UNIT }
 Used in RfcGetServerContext() for inquiring the type of an incoming function call from the backend. More...

Functions

DECL_EXP RFC_CONNECTION_HANDLE
SAP_API 		RfcOpenConnection (RFC_CONNECTION_PARAMETER const *connectionParams, unsigned paramCount, RFC_ERROR_INFO *errorInfo)
 Opens an RFC client connection for invoking ABAP function modules in an R/3 backend.
DECL_EXP RFC_CONNECTION_HANDLE
SAP_API 		RfcRegisterServer (RFC_CONNECTION_PARAMETER const *connectionParams, unsigned paramCount, RFC_ERROR_INFO *errorInfo)
 Registers a server connection at an SAP gateway.
DECL_EXP RFC_CONNECTION_HANDLE
SAP_API 		RfcStartServer (int argc, SAP_UC **argv, RFC_CONNECTION_PARAMETER const *connectionParams, unsigned paramCount, RFC_ERROR_INFO *errorInfo)
 Allows a program to be used as an RFC server which is started by the backend on demand.
DECL_EXP RFC_RC SAP_API RfcCloseConnection (RFC_CONNECTION_HANDLE rfcHandle, RFC_ERROR_INFO *errorInfo)
 Closes an RFC connection

Can be used to close client connections as well as server connections, when they are no longer needed.

DECL_EXP RFC_RC SAP_API RfcIsConnectionHandleValid (RFC_CONNECTION_HANDLE rfcHandle, int *isValid, RFC_ERROR_INFO *errorInfo)
 Checks an RFC connection

Can be used to check whether a client/server connection has already been closed, or whether the NW RFC library still "considers" the connection to be open.

DECL_EXP RFC_RC SAP_API RfcResetServerContext (RFC_CONNECTION_HANDLE rfcHandle, RFC_ERROR_INFO *errorInfo)
 RFC_RC SAP_API RfcResetServerContext

Resets the SAP server context ("user context / ABAP session context") associated with the given client connection, but does not close the connection.

DECL_EXP RFC_RC SAP_API RfcPing (RFC_CONNECTION_HANDLE rfcHandle, RFC_ERROR_INFO *errorInfo)
 Ping the remote communication partner through the passed connection handle.
DECL_EXP RFC_RC SAP_API RfcGetConnectionAttributes (RFC_CONNECTION_HANDLE rfcHandle, RFC_ATTRIBUTES *attr, RFC_ERROR_INFO *errorInfo)
 Returns details about the current client or server connection.
DECL_EXP RFC_RC SAP_API RfcGetServerContext (RFC_CONNECTION_HANDLE rfcHandle, RFC_SERVER_CONTEXT *context, RFC_ERROR_INFO *errorInfo)
 Inside a server function, returns details about the current execution context.
DECL_EXP RFC_RC SAP_API RfcGetPartnerSSOTicket (RFC_CONNECTION_HANDLE rfcHandle, SAP_UC *ssoTicket, unsigned *length, RFC_ERROR_INFO *errorInfo)
 Gets the partner's SSO2 ticket, if any.
DECL_EXP RFC_RC SAP_API RfcGetPartnerSNCName (RFC_CONNECTION_HANDLE rfcHandle, SAP_UC *sncName, unsigned length, RFC_ERROR_INFO *errorInfo)
 Gets the partner's SNC name, if any.
DECL_EXP RFC_RC SAP_API RfcGetPartnerSNCKey (RFC_CONNECTION_HANDLE rfcHandle, SAP_RAW *sncKey, unsigned *length, RFC_ERROR_INFO *errorInfo)
 Gets partner's SNC key, if any.
DECL_EXP RFC_RC SAP_API RfcSNCNameToKey (SAP_UC const *sncLib, SAP_UC const *sncName, SAP_RAW *sncKey, unsigned *keyLength, RFC_ERROR_INFO *errorInfo)
 Converts SNC name to SNC key.
DECL_EXP RFC_RC SAP_API RfcSNCKeyToName (SAP_UC const *sncLib, SAP_RAW const *sncKey, unsigned keyLength, SAP_UC *sncName, unsigned nameLength, RFC_ERROR_INFO *errorInfo)
 Converts SNC key to SNC name.
DECL_EXP RFC_RC SAP_API RfcListenAndDispatch (RFC_CONNECTION_HANDLE rfcHandle, int timeout, RFC_ERROR_INFO *errorInfo)
 Listens on a server connection handle and waits for incoming RFC calls from the R/3 system.
DECL_EXP RFC_RC SAP_API RfcInvoke (RFC_CONNECTION_HANDLE rfcHandle, RFC_FUNCTION_HANDLE funcHandle, RFC_ERROR_INFO *errorInfo)
 Executes a function module in the backend system.

Enumeration Type Documentation

enum _RFC_CALL_TYPE

Used in RfcGetServerContext() for inquiring the type of an incoming function call from the backend.

Enumerator:
RFC_SYNCHRONOUS  It's a standard synchronous RFC call.
RFC_TRANSACTIONAL  This function call is part of a transactional LUW (tRFC).
RFC_QUEUED  This function call is part of a queued LUW (qRFC).
RFC_BACKGROUND_UNIT  This function call is part of a background LUW (bgRFC).

Definition at line 324 of file sapnwrfc.h.

Function Documentation

DECL_EXP RFC_RC SAP_API RfcCloseConnection ( RFC_CONNECTION_HANDLE  rfcHandle,
RFC_ERROR_INFO *  errorInfo 
)

Closes an RFC connection

Can be used to close client connections as well as server connections, when they are no longer needed.

Parameters:
[in] rfcHandle Connection to be closed
[out] *errorInfo Error details in case closing the connection fails. (Can usually be ignored...)
Returns:
RFC_RC

DECL_EXP RFC_RC SAP_API RfcGetConnectionAttributes ( RFC_CONNECTION_HANDLE  rfcHandle,
RFC_ATTRIBUTES *  attr,
RFC_ERROR_INFO *  errorInfo 
)

Returns details about the current client or server connection.

See documentation of RFC_ATTRIBUTES.

Parameters:
[in] rfcHandle RFC connection
[out] *attr Information about the current connection and the communication partner on the other side.
[out] *errorInfo Additional error information (e.g. connection already closed).
Returns:
RFC_RC

DECL_EXP RFC_RC SAP_API RfcGetPartnerSNCKey ( RFC_CONNECTION_HANDLE  rfcHandle,
SAP_RAW *  sncKey,
unsigned *  length,
RFC_ERROR_INFO *  errorInfo 
)

Gets partner's SNC key, if any.

Parameters:
[in] rfcHandle RFC server connection. If this function is executed on a client connection, RFC_ILLEGAL_STATE will be returned.
[out] *sncKey Pre-allocated buffer, which will receive the backend user's SNC key.
[in,out] *length Needs to be filled with the buffer length of ssoTicket. The return value will be the byte length of the returned key (if buffer was large enough). Unfortunately in case of RFC_BUFFER_TOO_SMALL the required size is not returned by the GSS library. The maximum length of an SNC key is 1024.
[out] *errorInfo More error details in case SNC is not active.
Returns:
RFC_RC

DECL_EXP RFC_RC SAP_API RfcGetPartnerSNCName ( RFC_CONNECTION_HANDLE  rfcHandle,
SAP_UC *  sncName,
unsigned  length,
RFC_ERROR_INFO *  errorInfo 
)

Gets the partner's SNC name, if any.

Parameters:
[in] rfcHandle RFC server connection. If this function is executed on a client connection, RFC_ILLEGAL_STATE will be returned.
[out] *sncName Pre-allocated buffer, which will receive the backend user's SNC name (null-terminated string).
[in] length Size of the pre-allocated buffer. This information is coming from the GSS library, therefore unfortunately the feature of assigning the used/required length to an output parameter is not possible in this case. The maximum length of an SNC name is 256.
[out] *errorInfo More error details in case SNC is not active.
Returns:
RFC_RC

DECL_EXP RFC_RC SAP_API RfcGetPartnerSSOTicket ( RFC_CONNECTION_HANDLE  rfcHandle,
SAP_UC *  ssoTicket,
unsigned *  length,
RFC_ERROR_INFO *  errorInfo 
)

Gets the partner's SSO2 ticket, if any.

Can be used only with a server connection inside the implementation of a server function.

Parameters:
[in] rfcHandle RFC server connection
[out] *ssoTicket Pre-allocated buffer, which will receive the backend user's SSO2 ticket (signed user information in base64 format)
[in,out] *length Needs to be filled with the buffer length of ssoTicket. The return value will be the string length of the returned ticket (if buffer was large enough) or the required buffer size (if RFC_BUFFER_TOO_SMALL).
[out] *errorInfo More error details in case there is no ticket.
Returns:
RFC_RC
Warning:

DECL_EXP RFC_RC SAP_API RfcGetServerContext ( RFC_CONNECTION_HANDLE  rfcHandle,
RFC_SERVER_CONTEXT *  context,
RFC_ERROR_INFO *  errorInfo 
)

Inside a server function, returns details about the current execution context.

See documentation of RFC_SERVER_CONTEXT.

Parameters:
[in] rfcHandle RFC server connection
[out] *context Information about the current server execution context.
[out] *errorInfo Additional error information (e.g. connection is not a server connection).
Returns:
RFC_RC

DECL_EXP RFC_RC SAP_API RfcInvoke ( RFC_CONNECTION_HANDLE  rfcHandle,
RFC_FUNCTION_HANDLE  funcHandle,
RFC_ERROR_INFO *  errorInfo 
)

Executes a function module in the backend system.

The return codes have the following meaning:

  • RFC_OK
    The function call was executed successfully.
  • RFC_ABAP_EXCEPTION
    The function call was executed and ended with a defined ABAP Exception. The key of the exception can be obtained from errorInfo->key.

In the above two cases "rfcHandle" is still open and can be used to execute further function call.

  • RFC_ABAP_MESSAGE
    The function call was started to be processed, but was aborted with an ABAP Message. The message parameters can be obtained from errorInfo->abapMsgClass, errorInfo->abapMsgType, errorInfo->abapMsgNumber, errorInfo->abapMsgV1, ..., errorInfo->abapMsgV4.
  • RFC_ABAP_RUNTIME_FAILURE
    The function call was started to be processed, but was aborted with a SYSTEM_FAILURE (e.g division by zero, unhandled exception, etc in the backend system). Details can be obtained from errorInfo->message.
  • RFC_COMMUNICATION_FAILURE
    The connection broke down while processing the function call. Details can be obtained from errorInfo->message.

In these three cases the connection has been closed, so the "rfcHandle" needs to be refreshed via RfcOpenConnection.

  • RFC_INVALID_HANDLE
    "rfcHandle" is invalid or points to a connection that has already been closed.

Parameters:
[in] rfcHandle Client connection over which to execute the function module.
[in,out] funcHandle Data container containing the input data for the function module. RfcInvoke() will write the FM's output data into this container.
[out] *errorInfo Additional error information.
Returns:
RFC_RC

DECL_EXP RFC_RC SAP_API RfcIsConnectionHandleValid ( RFC_CONNECTION_HANDLE  rfcHandle,
int *  isValid,
RFC_ERROR_INFO *  errorInfo 
)

Checks an RFC connection

Can be used to check whether a client/server connection has already been closed, or whether the NW RFC library still "considers" the connection to be open.

Note that this does not guarantee that the connection is indeed still alive: A firewall may silently have closed the connection without notifying the endpoints. If you want to find out, whether the connection is still alive, you'll have to use the more expensive RfcPing().

Parameters:
[in] rfcHandle Connection to be checked
[out] *isValid 1, if the connection is still found in the internal connection management, 0 otherwise.
[out] *errorInfo Error details in case closing the connection fails. (Can usually be ignored...)
Returns:
RFC_RC

DECL_EXP RFC_RC SAP_API RfcListenAndDispatch ( RFC_CONNECTION_HANDLE  rfcHandle,
int  timeout,
RFC_ERROR_INFO *  errorInfo 
)

Listens on a server connection handle and waits for incoming RFC calls from the R/3 system.

The mechanism for dispatching incoming function calls works as follows: First RfcListenAndDispatch() checks, whether for the current combination of R/3 SystemID and function module name a callback function has been installed via RfcInstallServerFunction(). If not, it checks, whether a callback function for SystemID=NULL has been installed via RfcInstallServerFunction().If not, it checks, whether a global callback function has been installed via RfcInstallGenericServerFunction().

If a callback function has been found, the RFC call will be dispatched to that function for processing, and RfcListenAndDispatch() returns the return code of the callback function. Otherwise RfcListenAndDispatch() returns a SYSTEM_FAILURE to the R/3 backend and the return code RFC_NOT_FOUND to the caller.

In general the return codes of RfcListenAndDispatch() have the following meaning:

  • RFC_OK
    A function call was processed successfully.
  • RFC_RETRY
    No function call came in within the specified timeout period. ("timeout" is given in seconds.)
  • RFC_ABAP_EXCEPTION
    A function call was processed and ended with a defined ABAP Exception, which has been returned to the backend.

In the above three cases "rfcHandle" is still open and can be used to listen for the next request.

  • RFC_ABAP_MESSAGE
    A function call was started to be processed, but was aborted with an ABAP A-, E- or X-Message. The message parameters have been returned to the backend (and can be evaluated there via the sy-msgid, sy-msgtype, sy-msgno, sy-msgv1, ..., sy-msgv4 parameters).
  • RFC_EXTERNAL_FAILURE
    A function call was started to be processed, but was aborted with a "SYSTEM_FAILURE", which has been returned to the backend.
  • RFC_COMMUNICATION_FAILURE
    The connection broke down while processing the function call. No response has been sent to the backend.
  • RFC_CLOSED
    The connection has been closed by the backend side (SMGW, SM04). No response has been sent to the backend.
  • RFC_NOT_FOUND
    No handler has been found for the current function module name. A SYSTEM_FAILURE has been returned to the R/3 backend.

In these five cases the connection has been closed, so the "rfcHandle" needs to be refreshed via RfcRegisterServer.

  • RFC_INVALID_HANDLE
    "rfcHandle" is invalid or points to a connection that has already been closed.

Parameters:
[in] rfcHandle Server connection on which to listen for incoming requests.
[in] timeout Number of seconds to wait for an incoming request.
[out] *errorInfo Additional error information.
Returns:
RFC_RC

DECL_EXP RFC_CONNECTION_HANDLE SAP_API RfcOpenConnection ( RFC_CONNECTION_PARAMETER const *  connectionParams,
unsigned  paramCount,
RFC_ERROR_INFO *  errorInfo 
)

Opens an RFC client connection for invoking ABAP function modules in an R/3 backend.

Opens a client connection to an SAP System. The connectionParams may contain the following name-value pairs:

  • client, user, passwd, lang, trace

and additionally one of

  1. Direct application server logon: ashost, sysnr.
  2. Logon with load balancing: mshost, msserv, sysid, group.
    msserv is needed only, if the service of the message server is not defined as sapms<SYSID> in /etc/services.

When logging on with SNC, user&passwd are to be replaced by

  • snc_qop, snc_myname, snc_partnername and optionally snc_lib.

(If snc_lib is not specified, the RFC library uses the "global" GSS library defined via environment variable SNC_LIB.)

When logging on with SSO Ticket, you can use mysapsso2 instead of user&passwd. The old SSO format (mysapsso) is no longer supported.

Alternatively the connection parameters can be defined in the config file sapnwrfc.ini. In this case you just pass the parameter dest=... and all parameters that are missing in the sapnwrfc.ini entry into RfcOpenConnection().

For a complete list of logon parameters to be used in connectionParams as well as in the sapnwrfc.ini file, see the sample sapnwrfc.ini file in the SDK's demo folder.

If the logon was ok, RfcOpenConnection() returns a client connection handle, which can be used in RfcInvoke(). Otherwise the return value is NULL and errorInfo contains a detailed error description. errorInfo->code will be one of:

  • RFC_INVALID_PARAMETER One of the connectionParams was invalid
  • RFC_COMMUNICATION_FAILURE Something is wrong with the network or network settings
  • RFC_LOGON_FAILURE Invalid user/password/ticket/certificate
  • RFC_ABAP_RUNTIME_FAILURE Something is wrong with the R/3 backend
  • RFC_MEMORY_INSUFFICIENT A malloc failed when trying to allocate a temporary buffer

Parameters:
[in] *connectionParams An array of RFC_CONNECTION_PARAMETERs with the names as described above and the values as necessary in your landscape.
[in] paramCount Number of parameters in the above array.
[out] *errorInfo Returns more error details, if the connect attempt fails.
Returns:
A handle to an RFC client connection that can be used for invoking ABAP function modules in the backend.

DECL_EXP RFC_RC SAP_API RfcPing ( RFC_CONNECTION_HANDLE  rfcHandle,
RFC_ERROR_INFO *  errorInfo 
)

Ping the remote communication partner through the passed connection handle.

Sends a ping to the backend in order to check, whether the connection is still alive. Can be used on both, client connections as well as server connections.

Warning:
Do not use inside a server function implementation.
Parameters:
[in] rfcHandle The connection to check
[out] *errorInfo More error details in case the connection is broken.
Returns:
RFC_RC

DECL_EXP RFC_CONNECTION_HANDLE SAP_API RfcRegisterServer ( RFC_CONNECTION_PARAMETER const *  connectionParams,
unsigned  paramCount,
RFC_ERROR_INFO *  errorInfo 
)

Registers a server connection at an SAP gateway.

The connectionParams may contain the following name-value pairs:

  • gwhost, gwserv, program_id, trace, and the parameters for SNC communication as in RfcOpenConnection().

Program_id corresponds to an RFC destination in SM59 of type "T" in registration mode.

For a complete list of logon parameters to be used in connectionParams as well as in the sapnwrfc.ini file, see the sample sapnwrfc.ini file in the SDK's demo folder.

If the connection registration was ok, RfcRegisterServer() returns a server connection handle, which can be used in RfcListenAndDispatch(). Otherwise the return value is NULL and errorInfo contains information similar to the RfcOpenConnection() case.

Parameters:
[in] *connectionParams An array of RFC_CONNECTION_PARAMETERs with the names as described above and the values as necessary in your landscape.
[in] paramCount Number of parameters in the above array.
[out] *errorInfo Returns more error details, if the connect attempt fails.
Returns:
A handle to an RFC server connection that can be used for listening for function module requests from the backend.

DECL_EXP RFC_RC SAP_API RfcResetServerContext ( RFC_CONNECTION_HANDLE  rfcHandle,
RFC_ERROR_INFO *  errorInfo 
)

RFC_RC SAP_API RfcResetServerContext

Resets the SAP server context ("user context / ABAP session context") associated with the given client connection, but does not close the connection.

Parameters:
[in] rfcHandle The client connection, whose server context is to be reset.
[out] *errorInfo Error details in case resetting the server context fails. (Better close the connection in that case.)
Returns:
RFC_RC

DECL_EXP RFC_RC SAP_API RfcSNCKeyToName ( SAP_UC const *  sncLib,
SAP_RAW const *  sncKey,
unsigned  keyLength,
SAP_UC *  sncName,
unsigned  nameLength,
RFC_ERROR_INFO *  errorInfo 
)

Converts SNC key to SNC name.

Parameters:
[in] *sncLib Optional: file name of the GSS library to be used for the conversion. If not specified, the "global" GSS library (environment variable SNC_LIB) will be used.
[in] *sncKey SNC key to be converted.
[in] keyLength Byte length of the given SNC key
[out] *sncName Pre-allocated buffer, which will receive the corresponding (null-terminated) SNC name.
[in] nameLength Size of the given sncName buffer. (The maximum length of an SNC name is 256.)
[out] *errorInfo More error details in case something goes wrong.
Returns:
RFC_RC

DECL_EXP RFC_RC SAP_API RfcSNCNameToKey ( SAP_UC const *  sncLib,
SAP_UC const *  sncName,
SAP_RAW *  sncKey,
unsigned *  keyLength,
RFC_ERROR_INFO *  errorInfo 
)

Converts SNC name to SNC key.

Parameters:
[in] *sncLib Optional: file name of the GSS library to be used for the conversion. If not specified, the "global" GSS library (environment variable SNC_LIB) will be used.
[in] *sncName Null-terminated SNC name to be converted.
[out] *sncKey Pre-allocated buffer, which will receive the corresponding SNC key.
[in,out] *keyLength Needs to be filled with the buffer length of sncKey. The return value will be byte length of the SNC key (if buffer was large enough). Unfortunately in case of RFC_BUFFER_TOO_SMALL the required size is not returned by the GSS library. The maximum length of an SNC key is 1024.
[out] *errorInfo More error details in case something goes wrong.
Returns:
RFC_RC

DECL_EXP RFC_CONNECTION_HANDLE SAP_API RfcStartServer ( int  argc,
SAP_UC **  argv,
RFC_CONNECTION_PARAMETER const *  connectionParams,
unsigned  paramCount,
RFC_ERROR_INFO *  errorInfo 
)

Allows a program to be used as an RFC server which is started by the backend on demand.

This API needs to be called, if the server program is to be started by the R/3 application server. (RFC destination in SM59 of type "T" in startup mode.) argc and argv are the inputs of the mainU function. The R/3 application server passes the correct command line to the program, when starting it up, so you only need to forward these two parameters to RfcStartServer(). connectionParams is optional and is only needed, if you want to add additional logon parameters to the ones coming from the command line, e.g for activating trace.

Like RfcRegisterServer(), the function returns a server connection handle that can be used in RfcListenAndDispatch(). The mechanism of this kind of RFC destination thus works as follows:

  1. The R/3 application server opens a telnet connection to the host, where your server program is located, and starts the program with the necessary logon parameters. (Or creates a child process, if the startup method is "Start on application server".)
  2. Your server program calls RfcStartServer, which opens an RFC connection back to the R/3 system.
  3. The R/3 system then makes the function call over that RFC connection.

The main differences of "startup mode" compared to the "registration mode" are:

  • Advantage: no logon parameters need to be maintained in the server program. (Unless you want to open an additional client connection for looking up function module metadata (RFC_FUNCTION_DESC_HANDLEs) in the R/3 DDIC.)
  • Disadvantage: every single function call creates a new process and a telnet connection in addition to the actual RFC connection.

Parameters:
[in] argc From mainU() (command line supplied by backend)
[in] **argv From mainU() (command line supplied by backend)
[in] *connectionParams May optionally contain additional logon parameters
[in] paramCount Length of the connection parameter array above
[out] *errorInfo Returns more error details, if the connect attempt fails.
Returns:
A handle to an RFC server connection that can be used for listening for function module requests from the backend.

Generated on Fri Aug 29 16:54:52 2014 for SAP by  doxygen 1.5.5