Rulbus DLL Interface
[Reference Manual]

---

Detailed Description

The general interface of the Rulbus Device Library contains three groups of functions:

• report -- functions to report on the Rulbus hardware interface used and on the currently open Rulbus devices and to report on the last error that occurred in the library
• input/output -- functions to enable reading from and writing to the Rulbus directly, via a generic Rulbus device
• initialization -- the DLL initialization functions DllMain(), rdl_initialize() and rdl_finalize(). The operating system calls DllMain() when it loads or unloads the DLL and DllMain in turns initializes and cleans-up the library for you with rdl_initialize() and rdl_finalize().

For typical use of the Rulbus modules only function rdl_getLastError() is of interest. See dac.cpp. for an example of its use.

For access to the Rulbus for unsupported operations on a module, or for unsupported modules, see section Generic Rulbus Device.

Defines
#define	EXPORT   __declspec(dllimport)
	import (export) functions from DLL
#define	RDL_API   __cdecl
	calling convention
Typedefs
typedef char	int8
	8-bit signed int
typedef unsigned char	uInt8
	8-bit unsigned int
typedef int8	char8
	8-bit signed character
typedef uInt8	uChar8
	8-bit unsigned character
typedef uInt8	uChar
	8-bit unsigned character
typedef short int	int16
	16-bit signed int
typedef unsigned short int	uInt16
	16-bit unsigned int
typedef long	int32
	32-bit signed int
typedef unsigned long	uInt32
	32-bit unsigned int
typedef float	float32
	32-bit float
typedef double	float64
	64-bit float
typedef int32	bool32
	boolean (32-bit)
typedef char *	Cstr
	C-string.
typedef const char *	CCstr
	const C-string
Functions
EXPORT int32 RDL_API	rdl_initialize ()
	initialize Rulbus Device Library.
EXPORT int32 RDL_API	rdl_finalize ()
	finalize Rulbus Device Library.
EXPORT int32 RDL_API	rdl_printRulbusInterface ()
	report Rulbus Interface being used.
EXPORT int32 RDL_API	rdl_printRulbusDeviceList ()
	report all registered Rulbus devices.
EXPORT int32 RDL_API	rdl_getLastError (Cstr msg, int32 maxlen)
	format last error into message buffer.
EXPORT int32 RDL_API	RulbusDevice_open (int32 *pHandle, CCstr name)
	open a generic Rulbus device.
EXPORT int32 RDL_API	RulbusDevice_close (int32 handle)
	close a generic Rulbus device.
EXPORT int32 RDL_API	RulbusDevice_print (int32 handle)
	report on specified Rulbus device.
EXPORT int32 RDL_API	RulbusDevice_putByte (int32 handle, int32 offset, int32 byte)
	write a byte to a generic Rulbus device.
EXPORT int32 RDL_API	RulbusDevice_getByte (int32 handle, int32 offset)
	read a byte from a generic Rulbus device.
EXPORT int32 RDL_API	RulbusDevice_getRack (int32 handle, int32 *pRack)
	get Rulbus device's rack.
EXPORT int32 RDL_API	RulbusDevice_getAddress (int32 handle, int32 *pAddress)
	get Rulbus device's address.
BOOL EXPORT WINAPI	DllMain (HINSTANCE hinstDLL, DWORD fdwReason, LPVOID lpvReserved)
	entry point into dynamic-link library.

---

Function Documentation

BOOL EXPORT WINAPI DllMain (  HINSTANCE  hinstDLL, DWORD  fdwReason, LPVOID  lpvReserved )

DllMain() is called by the operating system (or a call to function LoadLibrary()), for example when a process (program) wants to use the DLL. In this case fdwReason is DLL_PROCESS_ATTACH and DllMain() calls rdl_initialize() to prepare the library for use. When the DLL is no longer needed, the operating system calls DllMain() with a fdwReason of DLL_PROCESS_DETACH and DllMain() in turn calls rdl_finalize() to clean-up the library. DllMain() returns TRUE on success, FALSE on error (DLL_PROCESS_ATTACH).

EXPORT int32 RDL_API rdl_finalize (   )

If the Rulbus Device Library is used as a dynamic-link library (DLL), the library is cleaned-up with this function by DllMain() when the operating system unloads the DLL; you should not call rdl_finalize() yourself. If however you link the Rulbus Device Library directly to your application, you must call rdl_initialize() before using any other function from the library and when done with the library, you should call rdl_finalize() to clean-up the library. See also rdl_initialize().

EXPORT int32 RDL_API rdl_getLastError (  Cstr  msg, int32  maxlen )

rdl_getLastError() copies at most maxlen characters (including the terminating \0) of the last error message into the buffer specified by msg. Only one message is retained for all threads using the Rulbus Device Library. If the error message for the thread calling rdl_getLastError() is not available (anymore), the following message is returned: [Rulbus: error message not available for this thread] Parameters: msg  the message buffer maxlen  the size of the message buffer msg Returns: 0, 1 (Ok, error) rdl_getLastError() returns 0 if the message could be copied, it returns 1 in the following situations: msg is NULL maxlen is zero or less the message was not available for this thread Examples: dac.cpp, error.cpp, run-daccs.cmd, and run-daccs2.cmd.

EXPORT int32 RDL_API rdl_initialize (   )

rdl_initialize() determines the Rulbus Interface to use and initializes the list to hold open Rulbus devices. (See Rulbus DLL Implementation, Create Rulbus interface .) If the Rulbus Device Library is used as a dynamic-link library (DLL), the library is initialized with this function by DllMain() when the operating system loads the DLL; you should not call rdl_initialize() yourself. If however you link the Rulbus Device Library directly to your application, you must call rdl_initialize() before using any other function from the library. When done with the library, you should call rdl_finalize() to clean-up the library. See also rdl_finalize().

EXPORT int32 RDL_API rdl_printRulbusDeviceList (   )

For each opened Rulbus device, rdl_printRulbusDeviceList() prints information for that device to standard output.

EXPORT int32 RDL_API rdl_printRulbusInterface (   )

rdl_printRulbusInterface() prints one of the following messages to standard output: EPP Rulbus Interface at [0x378], using CanIO port I/O, or ISA Rulbus Interface at [0x200], using CanIO port I/O Examples: run-daccs.cmd, and run-daccs2.cmd.

EXPORT int32 RDL_API RulbusDevice_close (  int32  handle  )

RulbusDevice_close() closes a generic Rulbus device that was opened with RulbusDevice_open(), or with one of the rbyydd_..._open() functions. RulbusDevice_close() returns 0 on success, 1 on error.

EXPORT int32 RDL_API RulbusDevice_getByte (  int32  handle, int32  offset )

RulbusDevice_getByte() returns the value read from the Rulbus at the address offset bytes from the generic devices' base address as specified with RulbusDevice_open(). On success RulbusDevice_getByte() returns the byte read, otherwise it returns -1. Returns: 0..255, -1 (byte read, error)

EXPORT int32 RDL_API RulbusDevice_open (  int32 *  pHandle, CCstr  name )

RulbusDevice_open() opens a generic Rulbus device with the specified name and passes back a handle to it on success. The handle can be used in functions RulbusDevice_putByte(), RulbusDevice_getByte() and RulbusDevice_close() to write to the Rulbus, read from it and close the generic Rulbus device again. RulbusDevice_open() returns 0 on success, 1 on error. Examples: pattern.cpp.

EXPORT int32 RDL_API RulbusDevice_print (  int32  handle  )

RulbusDevice_print() prints information for the device specified by handle to standard output. handle may be obtained with RulbusDevice_open() or one of the rbyydd_..._open() functions. Examples: run-daccs.cmd, and run-daccs2.cmd.

EXPORT int32 RDL_API RulbusDevice_putByte (  int32  handle, int32  offset, int32  byte )

RulbusDevice_putByte() writes byte to the Rulbus at the address offset bytes from the generic devices' base address as specified with RulbusDevice_open(). On success RulbusDevice_putByte() returns the byte written, otherwise it returns -1. Returns: 0..255, -1 (byte written, error)

---