Functions for sending background RFC units into R/3. More...

Classes
struct	_RFC_UNIT_ATTRIBUTES
	If the external program is the sender of the bgRFC unit, this structure is used to set a bunch of special attributes that determine, how a bgRFC Unit will be processed in the backend. More...

struct	_RFC_UNIT_IDENTIFIER
	For convenience combines a unit's ID and its type. More...

struct	_RFC_UNIT_HANDLE
	Handle to a data container for a bgRFC LUW. More...

Enumerations
enum	_RFC_UNIT_STATE { RFC_UNIT_NOT_FOUND, RFC_UNIT_IN_PROCESS, RFC_UNIT_COMMITTED, RFC_UNIT_ROLLED_BACK, RFC_UNIT_CONFIRMED }
	Used in RfcGetUnitState() for inquiring the processing status of a background Unit that we (or someone else) sent into this backend. More...

Functions
DECL_EXP RFC_RC SAP_API	RfcGetUnitID (RFC_CONNECTION_HANDLE rfcHandle, RFC_UNITID uid, RFC_ERROR_INFO *errorInfo)
	Create a 32 digit bgRFC unit ID. More...

DECL_EXP RFC_UNIT_HANDLE SAP_API	RfcCreateUnit (RFC_CONNECTION_HANDLE rfcHandle, RFC_UNITID uid, SAP_UC const queueNames[], unsigned queueNameCount, const RFC_UNIT_ATTRIBUTES unitAttr, RFC_UNIT_IDENTIFIER identifier, RFC_ERROR_INFO errorInfo)
	Create a bgRFC unit. More...

DECL_EXP RFC_RC SAP_API	RfcInvokeInUnit (RFC_UNIT_HANDLE unitHandle, RFC_FUNCTION_HANDLE funcHandle, RFC_ERROR_INFO *errorInfo)
	Adds a function module to a bgRFC unit. More...

DECL_EXP RFC_RC SAP_API	RfcSubmitUnit (RFC_UNIT_HANDLE unitHandle, RFC_ERROR_INFO *errorInfo)
	Executes a bgRFC unit in the backend. More...

DECL_EXP RFC_RC SAP_API	RfcConfirmUnit (RFC_CONNECTION_HANDLE rfcHandle, RFC_UNIT_IDENTIFIER identifier, RFC_ERROR_INFO errorInfo)
	Removes the UID from the backend's status management. More...

DECL_EXP RFC_RC SAP_API	RfcDestroyUnit (RFC_UNIT_HANDLE unitHandle, RFC_ERROR_INFO *errorInfo)
	Releases the memory of the bgRFC unit container. More...

DECL_EXP RFC_RC SAP_API	RfcGetUnitState (RFC_CONNECTION_HANDLE rfcHandle, RFC_UNIT_IDENTIFIER identifier, RFC_UNIT_STATE state, RFC_ERROR_INFO *errorInfo)
	Retrieves the processing status of the given background unit from the backend system's status management. More...

Detailed Description

Functions for sending background RFC units into R/3.

Enumeration Type Documentation

enum _RFC_UNIT_STATE

Used in RfcGetUnitState() for inquiring the processing status of a background Unit that we (or someone else) sent into this backend.

Enumerator
RFC_UNIT_NOT_FOUND	No information for this unit ID and unit type can be found in the target system. If you are sure, that target system, unit ID and unit type are correct, it means that your previous attempt did not even reach the target system. Send the unit again. However, if you get this status after the Confirm step has already been executed, it means that everything is ok. Don't re-execute in this case!
RFC_UNIT_IN_PROCESS	Backend system is still in the process of persisting (or executing if type 'T') the payload data. Give it some more time and check the state again later. If this takes "too long", an admin should probably have a look at why there is no progress here.
RFC_UNIT_COMMITTED	Data has been persisted (or executed if type 'T') ok on receiver side. Confirm event may now be triggered.
RFC_UNIT_ROLLED_BACK	An error of any type has occurred. Unit needs to be resent.
RFC_UNIT_CONFIRMED	Temporary state between the Confirm event and the time, when the status data will be erased for good. Nothing to be done. Just delete the payload and status information on your side.

Definition at line 326 of file sapnwrfc.h.

Function Documentation

DECL_EXP RFC_RC SAP_API RfcConfirmUnit	(	RFC_CONNECTION_HANDLE	rfcHandle,
		RFC_UNIT_IDENTIFIER *	identifier,
		RFC_ERROR_INFO *	errorInfo
	)

Removes the UID from the backend's status management.

After RfcSubmitUnit() returned successfully, you should use this function to cleanup the status information for this unit on backend side. However, be careful: if you have a three-tier architecture, don't bundle Submit and Confirm into one single logical step. Otherwise you run the risk, that the middle tier (the NW RFC lib) successfully executes both, the Submit and the Confirm, but on the way back to the first tier an error occurs and the first tier can not be sure that the unit was really executed in the backend and therefore decides to re-execute it. This will now result in a duplicate execution in the backend, because the Confirm step in the first try has already deleted the UID in the backend, and consequently the backend is no longer protected against re-execution of this UID. In a three-tier architecture, the first tier should trigger both steps separately: first the Submit, and after it knows that the Submit was successful, the Confirm. Also in case the Confirm runs into an error, do NOT execute the Submit again, never! You may try the Confirm again at a later point, but otherwise just ignore the error. Better a left-over entry in the status information table than a duplicate unit...

Parameters

[in]	rfcHandle	A connection into the same system, into which the corresponding bgRFC unit has been sent via RfcSubmitUnit().
[in]	*identifier	The correct combination of UID and type of the unit. Best use the output you get from RfcCreateUnit().
[out]	*errorInfo	More details in case something goes wrong.

Returns: RFC_OK, RFC_INVALID_HANDLE, RFC_COMMUNICATION_FAILURE

DECL_EXP RFC_UNIT_HANDLE SAP_API RfcCreateUnit	(	RFC_CONNECTION_HANDLE	rfcHandle,
		RFC_UNITID	uid,
		SAP_UC const *	queueNames[],
		unsigned	queueNameCount,
		const RFC_UNIT_ATTRIBUTES *	unitAttr,
		RFC_UNIT_IDENTIFIER *	identifier,
		RFC_ERROR_INFO *	errorInfo
	)

Create a bgRFC unit.

Creates a data container that can later be filled with one or more function modules comprising the bgRFC unit. The backend will execute these function modules as an atomic unit. The connection handle specifies the target system, to which the unit will later be sent. The unit ID has been created in the previous step (or is an old one in case of retrying a failed unit). Via queueNames and queueNameCount you can specify the list of bgRFC queues, into which this unit shall later be inserted. If no queues are given (queueNameCount == 0), a synchronous unit is created (type 'T') that will later be executed immediately. Otherwise an asynchronous unit (type 'Q') is created, which will be inserted into the named queues and executed asynchronously by the bgRFC scheduler.

Parameters

[in]	rfcHandle	An open RFC connection into the system that will later receive the unit.
[in]	uid	A 32 digit unique identifier of the unit.
[in]	*queueNames[]	A list of bgRFC queues in the backend or NULL.
[in]	queueNameCount	The length of the queueNames list.
[in]	*unitAttr	A set of attributes that specify the behaviour of the unit in the backend. See RFC_UNIT_ATTRIBUTES for more information.
[out]	*identifier	This identifier can be used in later calls to RfcConfirmUnit() and RfcGetUnitState(). It is important that these functions are called with the correct unit type ('T' or 'Q'), otherwise the backend system won't find the status information corresponding to the uid... Therefore the NW RFC lib bundles the uid and the correct unit type here for your convenience.
[out]	*errorInfo	More details in case something goes wrong.

Returns: RFC_OK or RFC_MEMORY_INSUFFICIENT

DECL_EXP RFC_RC SAP_API RfcDestroyUnit	(	RFC_UNIT_HANDLE	unitHandle,
		RFC_ERROR_INFO *	errorInfo
	)

Releases the memory of the bgRFC unit container.

Parameters

[in]	unitHandle	A unit handle that is no longer needed.
[out]	*errorInfo	Not much that can go wrong here...

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcGetUnitID	(	RFC_CONNECTION_HANDLE	rfcHandle,
		RFC_UNITID	uid,
		RFC_ERROR_INFO *	errorInfo
	)

Create a 32 digit bgRFC unit ID.

This function fills the given RFC_UNITID with a 32 digit hexadecimal GUID and zero-terminates it. If you want the GUID to be generated by the backend, pass a valid rfcHandle, if you want the NW RFC library to generate one locally (using the appropriate OS functions), pass NULL as connection handle. In both cases the GUID is suitable for sending bgRFC units into an SAP system.

Parameters

[in]	rfcHandle	An open RFC connection into the system that is to create the unit ID, or NULL.
[out]	uid	Preallocated buffer that will receive the 32 digits of the unit ID and a terminating zero.
[out]	*errorInfo	Not much that can go wrong here...

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcGetUnitState	(	RFC_CONNECTION_HANDLE	rfcHandle,
		RFC_UNIT_IDENTIFIER *	identifier,
		RFC_UNIT_STATE *	state,
		RFC_ERROR_INFO *	errorInfo
	)

Retrieves the processing status of the given background unit from the backend system's status management.

Parameters

[in]	rfcHandle	A connection into the same system, into which the corresponding bgRFC unit has been sent via RfcSubmitUnit().
[in]	*identifier	The correct combination of UID and type of the unit. Best use the output you get from RfcCreateUnit().
[out]	*state	The state of the unit. See RFC_UNIT_STATE for more details.
[out]	*errorInfo	Not much that can go wrong here...

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcInvokeInUnit	(	RFC_UNIT_HANDLE	unitHandle,
		RFC_FUNCTION_HANDLE	funcHandle,
		RFC_ERROR_INFO *	errorInfo
	)

Adds a function module to a bgRFC unit.

Serializes the payload of the function module data container into bgRFC format and inserts it into the data container for the bgRFC unit. The funcHandle can afterwards be freed using RfcDestroyFunction(), because the data is copied, not referenced.

Note: Despite the name "invoke", nothing is executed in the backend system, yet!

Parameters

[in]	unitHandle	A valid (unsubmitted) bgRFC unit, to which the given function module shall be added.
[in]	funcHandle	A function module, whose payload (IMPORTING/CHANGING/TABLES) shall be added to the unit.
[out]	*errorInfo	More details in case something goes wrong.

Returns: RFC_OK, RFC_INVALID_HANDLE or RFC_MEMORY_INSUFFICIENT

DECL_EXP RFC_RC SAP_API RfcSubmitUnit	(	RFC_UNIT_HANDLE	unitHandle,
		RFC_ERROR_INFO *	errorInfo
	)

Executes a bgRFC unit in the backend.

Sends the bgRFC unit into the backend, where it will be executed synchronously or persisted in the given inbound queues and executed asynchronously by the bgRFC scheduler, depending on whether the unit type is 'T' or 'Q'. If the type is 'T', this function will wait until the unit is completely executed and then return the success or error information. If the type is 'Q', this function only inserts the unit into the specified queues and then returns. Processing of the unit in the backend system happens asynchronously. The return code of this function indicates, whether the unit could be persisted in the given queues successfully. In order to get information about the processing status of the unit, use RfcGetUnitState() at a later point.

Note: Despite the name "invoke", nothing is executed in the backend system, yet!

Parameters

[in]	unitHandle	A valid (unsubmitted) bgRFC unit, which shall be sent into the backend system.
[out]	*errorInfo	More details in case something goes wrong.

Returns: RFC_OK, RFC_INVALID_HANDLE, RFC_MEMORY_INSUFFICIENT, RFC_COMMUNICATION_FAILURE

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation