Some utility functions for initializing, tracing, version info, etc. More...

Functions
DECL_EXP RFC_RC SAP_API	RfcInit (void)
	Initialization of internal variablesSets up the internal state of the sapnwrfc library and initially reads and evaluates the sapnwrfc.ini file. More...

DECL_EXP const SAP_UC *SAP_API	RfcGetVersion (unsigned majorVersion, unsigned minorVersion, unsigned *patchLevel)
	Get information about currently loaded sapnwrfc library. More...

DECL_EXP RFC_RC SAP_API	RfcGetVersionInternal (void)
	This function is intended to be used by SAP Make-factory only. More...

DECL_EXP RFC_RC SAP_API	RfcSetIniPath (const SAP_UC pathName, RFC_ERROR_INFO errorInfo)
	Sets the directory in which to search for the sapnwrfc.ini file. More...

DECL_EXP RFC_RC SAP_API	RfcReloadIniFile (RFC_ERROR_INFO *errorInfo)
	Loads the contents of the sapnwrfc.ini file into memory. More...

DECL_EXP RFC_RC SAP_API	RfcSetTraceLevel (RFC_CONNECTION_HANDLE connection, SAP_UC destination, unsigned traceLevel, RFC_ERROR_INFO errorInfo)
	Sets the current trace level of the specified RFC connection or destination to the new value. More...

DECL_EXP RFC_RC SAP_API	RfcSetTraceEncoding (SAP_UC traceEncoding, RFC_ERROR_INFO errorInfo)
	Changes the character encoding to be used in trace files. More...

DECL_EXP RFC_RC SAP_API	RfcSetTraceDir (SAP_UC traceDir, RFC_ERROR_INFO errorInfo)
	Changes the directory where the NW RFC lib should write trace files. More...

DECL_EXP RFC_RC SAP_API	RfcSetTraceType (SAP_UC traceType, RFC_ERROR_INFO errorInfo)
	Changes the way the NW RFC lib writes trace files. More...

DECL_EXP RFC_RC SAP_API	RfcSetCpicTraceLevel (unsigned traceLevel, RFC_ERROR_INFO *errorInfo)
	Sets the global CPIC trace level used by the underlying CPIC libabry to write CPIC tracing information to the CPIC trace file cpic_<pid>.trc, where pid is the process ID of the current process. More...

DECL_EXP RFC_RC SAP_API	RfcUTF8ToSAPUC (const RFC_BYTE utf8, unsigned utf8Length, SAP_UC sapuc, unsigned sapucSize, unsigned resultLength, RFC_ERROR_INFO *errorInfo)
	Converts data in UTF-8 format to SAP_UC strings. More...

DECL_EXP RFC_RC SAP_API	RfcSAPUCToUTF8 (const SAP_UC sapuc, unsigned sapucLength, RFC_BYTE utf8, unsigned utf8Size, unsigned resultLength, RFC_ERROR_INFO *errorInfo)
	Converts data in SAP_UC format to UTF-8 format. More...

DECL_EXP const SAP_UC *SAP_API	RfcGetRcAsString (RFC_RC rc)
	Converts an RFC_RC return code to a human readable string for logging purposes. More...

DECL_EXP const SAP_UC *SAP_API	RfcGetTypeAsString (RFCTYPE type)
	Converts an RFCTYPE data type indicator to a human readable string for logging purposes. More...

DECL_EXP const SAP_UC *SAP_API	RfcGetDirectionAsString (RFC_DIRECTION direction)
	Converts an RFC_DIRECTION direction indicator to a human readable string for logging purposes. More...

DECL_EXP const SAP_UC *SAP_API	RfcGetServerStateAsString (RFC_SERVER_STATE serverState)
	Converts an RFC_SERVER_STATE state indicator to a human readable string for logging purposes. More...

DECL_EXP RFC_RC SAP_API	RfcLanguageIsoToSap (const SAP_UC laiso, SAP_UC lang, RFC_ERROR_INFO *errorInfo)
	Converts a 2-char SAP language code to the 1-char SAP language code. More...

DECL_EXP RFC_RC SAP_API	RfcLanguageSapToIso (const SAP_UC lang, SAP_UC laiso, RFC_ERROR_INFO *errorInfo)
	Converts a 1-char SAP language key to the 2-char SAP language code. More...

Detailed Description

Some utility functions for initializing, tracing, version info, etc.

Function Documentation

DECL_EXP const SAP_UC* SAP_API RfcGetDirectionAsString ( RFC_DIRECTION direction )

Converts an RFC_DIRECTION direction indicator to a human readable string for logging purposes.

Parameters

[in] direction Direction indicator to convert

Returns: String representation of the direction

Warning: Don't free the returned SAP_UC pointer – its's static memory...

DECL_EXP const SAP_UC* SAP_API RfcGetRcAsString ( RFC_RC rc )

Converts an RFC_RC return code to a human readable string for logging purposes.

Parameters

[in] rc Return code to covert to string

Returns: String representation of the return code

Warning: Don't free the returned SAP_UC pointer – its's static memory...

DECL_EXP const SAP_UC* SAP_API RfcGetServerStateAsString ( RFC_SERVER_STATE serverState )

Converts an RFC_SERVER_STATE state indicator to a human readable string for logging purposes.

Parameters

[in] serverState State indicator to convert

Returns: String representation of the state

Warning: Don't free the returned SAP_UC pointer – its's static memory...

DECL_EXP const SAP_UC* SAP_API RfcGetTypeAsString ( RFCTYPE type )

Converts an RFCTYPE data type indicator to a human readable string for logging purposes.

Parameters

[in] type Data type indicator to convert

Returns: String representation of the type

Warning: Don't free the returned SAP_UC pointer – its's static memory...

DECL_EXP const SAP_UC* SAP_API RfcGetVersion	(	unsigned *	majorVersion,
		unsigned *	minorVersion,
		unsigned *	patchLevel
	)

Get information about currently loaded sapnwrfc library.

Fills the provided unsigneds with the SAP release values, e.g. *majorVersion = 7, *minorVersion = 10, *patchLevel = 42.

Parameters

[out]	*majorVersion
[out]	*minorVersion
[out]	*patchLevel

Returns: Version information in string format.

Warning: Don't free the returned SAP_UC pointer, it's static memory...

DECL_EXP RFC_RC SAP_API RfcGetVersionInternal ( void )

This function is intended to be used by SAP Make-factory only.

Please DO NOT use it!

DECL_EXP RFC_RC SAP_API RfcInit ( void )

Initialization of internal variablesSets up the internal state of the sapnwrfc library and initially reads and evaluates the sapnwrfc.ini file.

In case the content or location of the sapnwrfc.ini file changes later on, reload it via RfcReloadIniFile(). RfcInit() no longer needs to be called explicitly. The RFC library does this automatically on DLL load.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcLanguageIsoToSap	(	const SAP_UC *	laiso,
		SAP_UC *	lang,
		RFC_ERROR_INFO *	errorInfo
	)

Converts a 2-char SAP language code to the 1-char SAP language code.

Parameters

[in]	*laiso	Pointer to the 2-char array with SAP LAISO code to convert
[out]	*lang	Pointer to the 1 char for SAP SPRAS key
[out]	*errorInfo	Will be filled with additional error information in case of an error.

Returns: RFC_RC RFC_OK or RFC_INVALID_PARAMETER in case of an error

Warning: The SAP LAISO code is not 100% ISO639_1 compliant - see also ABAP table T002X columns SPRAS/LAISO for details

DECL_EXP RFC_RC SAP_API RfcLanguageSapToIso	(	const SAP_UC *	lang,
		SAP_UC *	laiso,
		RFC_ERROR_INFO *	errorInfo
	)

Converts a 1-char SAP language key to the 2-char SAP language code.

Parameters

[in]	*lang	Pointer to the 1 char with SAP SPRAS key to convert
[out]	*laiso	Pointer to the 2-char array for SAP LAISO code
[out]	*errorInfo	Will be filled with additional error information in case of an error.

Returns: RFC_RC RFC_OK or RFC_INVALID_PARAMETER in case of an error

Warning: The SAP LAISO code is not 100% ISO639_1 compliant - see also ABAP table T002X columns SPRAS/LAISO for details

DECL_EXP RFC_RC SAP_API RfcReloadIniFile ( RFC_ERROR_INFO * errorInfo )

Loads the contents of the sapnwrfc.ini file into memory.

Searches the directory given by RfcSetIniPath() (or the current working directory) for the file sapnwrfc.ini and loads its contents into memory.

Parameters

[out] *errorInfo Detail information in case anything goes wrong. Note: if a file with the name sapnwrfc.ini does not exist in the given directory, this is not considered an error! Default settings are used in this case.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcSAPUCToUTF8	(	const SAP_UC *	sapuc,
		unsigned	sapucLength,
		RFC_BYTE *	utf8,
		unsigned *	utf8Size,
		unsigned *	resultLength,
		RFC_ERROR_INFO *	errorInfo
	)

Converts data in SAP_UC format to UTF-8 format.

Parameters

[in]	*sapuc	Pointer to SAP_UC data to be converted
[in]	sapucLength	Number of characters to convert
[out]	*utf8	Pre-allocated output buffer, which will receive the result. Output will be null-terminated.
[in,out]	*utf8Size	Needs to be filled with the size of the given output buffer in bytes. If the given buffer turns out to be too small (return code RFC_BUFFER_TOO_SMALL), it will be filled with the required buffer size that would be necessary to convert the given input data.
[out]	*resultLength	If the output buffer was large enough, resultLength will be filled with the length of the output string in bytes.
[out]	*errorInfo	Will be filled with additional error information in case of an error.

Returns: RFC_OK or RFC_BUFFER_TOO_SMALL

DECL_EXP RFC_RC SAP_API RfcSetCpicTraceLevel	(	unsigned	traceLevel,
		RFC_ERROR_INFO *	errorInfo
	)

Sets the global CPIC trace level used by the underlying CPIC libabry to write CPIC tracing information to the CPIC trace file cpic_<pid>.trc, where pid is the process ID of the current process.

The CPIC trace file is located in the same directory where the RFC trace files are located.

This function has the same effect as the sapnwrfc.ini parameter CPIC_TRACE_LEVEL. See the documentation of that parameter in the sample ini file contained in the /demo directory of the NW RFC SDK.

Parameters

[in]	traceLevel	Must be a value between 0 to 3, where 0 turns tracing off.
[out]	*errorInfo	Detail information in case of an error.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcSetIniPath	(	const SAP_UC *	pathName,
		RFC_ERROR_INFO *	errorInfo
	)

Sets the directory in which to search for the sapnwrfc.ini file.

By default the sapnwrfc library searches for the sapnwrfc.ini in the current working directory of the process. If you want to keep it in a different directory, use this function to tell the sapnwrfc library about the new path.

Note: After you have changed the directory, the NW RFC lib automatically loads the contents of the new sapnwrfc.ini file from that directory.

Parameters

[in]	*pathName	The full (absolute) path of the directory, in which the sapnwrfc library should look for the sapnwrfc.ini file. A path relative to the current working directory of the process also works.
[out]	*errorInfo	Detail information in case anything goes wrong.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcSetTraceDir	(	SAP_UC *	traceDir,
		RFC_ERROR_INFO *	errorInfo
	)

Changes the directory where the NW RFC lib should write trace files.

This function has the same effect as the sapnwrfc.ini parameter RFC_TRACE_DIR. See the documentation of that parameter in the sample ini file contained in the /demo directory of the NW RFC SDK.

Note: This API call affects only new trace files that will be opened after the call. The directory of already existing trace files is not changed in order to prevent confusion and garbage data...

Parameters

[in]	*traceDir	The new directory. Can be an absolute or relative path name. The directory needs to exist prior to calling this API. The NW RFC lib will not attempt to create non-existing directories.
[out]	*errorInfo	Detail information in case of an invalid traceEncoding input.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcSetTraceEncoding	(	SAP_UC *	traceEncoding,
		RFC_ERROR_INFO *	errorInfo
	)

Changes the character encoding to be used in trace files.

This function has the same effect as the sapnwrfc.ini parameter RFC_TRACE_ENCODING. See the documentation of that parameter in the sample ini file contained in the /demo directory of the NW RFC SDK.

Note: This API call affects only new trace files that will be opened after the call. The character encoding of already existing trace files is not changed in order to prevent confusion and garbage data...

Parameters

[in]	*traceEncoding	The new encoding. Possible values are "UTF-16", "UTF-8" and "DEFAULT". On Windows UTF-16 is recommended for faster performance. "DEFAULT" corresponds to the operating system's default character encoding, which is CP1252 or ISO-8859-1 on most Windows systems and UTF-8 on most Linux systems.
[out]	*errorInfo	Detail information in case of an invalid traceEncoding input.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcSetTraceLevel	(	RFC_CONNECTION_HANDLE	connection,
		SAP_UC *	destination,
		unsigned	traceLevel,
		RFC_ERROR_INFO *	errorInfo
	)

Sets the current trace level of the specified RFC connection or destination to the new value.

Note: If both of connection and destination are NULL, this function sets the "global" trace level. See below.

Parameters

[in]	connection	A handle to a currently open RFC connection (client or server connection). The new trace level will be effective immediately.
[in]	*destination	Null-terminated string specifying a client or server destination as defined via a DEST=... entry in sapnwrfc.ini. The new trace level will be used for new connections to that destination opened after the RfcSetTraceLevel() call. Already existing connections to that destination will not be effected.
[in]	traceLevel	The new trace level. Must be between 0 and 3. The meaning of those four values is as follows: 0: Off. Only severe errors are logged to the dev_rfc.trc file. 1: Brief. All API calls (except for the setter and getter functions) and important attributes like codepages, RFC headers, logon parameters are traced. Trace is written to a file named rfc<pid>.trc or rfc<pid>_<tid>.trc, depending on whether tracing is done on a "per-process" basis or a "per-thread" basis. <pid> is the current process ID, <tid> the current thread ID. 2: Verbose. In addition to 1, the values of the "scalar" RFC parameters as well as the contents of the network containers are traced. Scalar parameters are primitive types (CHAR, INT, FLOAT, etc) and flat structures. 3: Full. In addition to 2 the contents of nested structures and tables as well as all API calls of setter and getter functions are traced.
[out]	*errorInfo	Detail information in case the specified connection or destination does not exist.

Returns: RFC_OK, RFC_INVALID_HANDLE or RFC_INVALID_PARAMETER

Note

In general RFC trace can be activated/deactivated in 6 different ways:

By setting the parameter RFC_TRACE=[0|1|2|3] in the DEFAULT section of the sapnwrfc.ini file. This value applies to all destinations, for which no explicit trace level has been set. ("Global" trace level.)
By setting the parameter TRACE=[0|1|2|3] in a specific destination section of sapnwrfc.ini. it applies to that destination only and overrules the "global" trace level from the DEFAULT section.
By setting the environment variable RFC_TRACE=[0|1|2|3]. This overrules the setting from the DEFAULT section of sapnwrfc.ini.
Via RfcSetTraceLevel(). If connection and destination are NULL, this function sets the global trace level and overrules the value from the DEFAULT section of sapnwrfc.ini as well as the environment variable RFC_TRACE. If connection is non-NULL, it sets the trace level for the current connection only, and if destination is non-NULL, it sets the trace level for that destination, overruling the value from this destination's section in the sapnwrfc.ini file.
By passing a {name=TRACE, value=[0|1|2|3]} pair in the RFC_CONNECTION_PARAMETER array used in RfcOpenConnection(), RfcRegisterServer() or RfcStartServer(). If that RFC_CONNECTION_PARAMETER array also contains a {name=DEST, value=...} pair, the trace parameter from the array overrules the value from this destination's sapnwrfc.ini section.
In case the program is a server program: by activating the trace flag for the corresponding destination in SM59. The trace setting on backend side is then "inherited" by the external side.

For more information on trace settings see the sample sapnwrfc.ini file contained in the demo folder.

DECL_EXP RFC_RC SAP_API RfcSetTraceType	(	SAP_UC *	traceType,
		RFC_ERROR_INFO *	errorInfo
	)

Changes the way the NW RFC lib writes trace files.

This function has the same effect as the sapnwrfc.ini parameter RFC_TRACE_TYPE. See the documentation of that parameter in the sample ini file contained in the /demo directory of the NW RFC SDK.

Note: This API call closes currently open trace files and then changes to "one file per process" or one "file per thread". If the NW RFC lib is already using the given trace type, it does nothing.

Parameters

[in]	*traceType	Must be either "PROCESS" or "THREAD".
[out]	*errorInfo	Detail information in case of an invalid traceEncoding input.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcUTF8ToSAPUC	(	const RFC_BYTE *	utf8,
		unsigned	utf8Length,
		SAP_UC *	sapuc,
		unsigned *	sapucSize,
		unsigned *	resultLength,
		RFC_ERROR_INFO *	errorInfo
	)

Converts data in UTF-8 format to SAP_UC strings.

Parameters

[in]	*utf8	Pointer to UTF-8 data to be converted
[in]	utf8Length	Number of bytes to convert
[out]	*sapuc	Pre-allocated output buffer, which will receive the result. Output will be null-terminated.
[in,out]	*sapucSize	Needs to be filled with the size of the given output buffer in SAP_UC characters. If the given buffer turns out to be too small (return code RFC_BUFFER_TOO_SMALL), it will be filled with the required buffer size that would be necessary to convert the given input data.
[out]	*resultLength	If the output buffer was large enough, resultLength will be filled with the length of the output string in SAP_UC characters.
[out]	*errorInfo	Will be filled with additional error information in case of an error.

Returns: RFC_RC

Functions

Detailed Description

Function Documentation