Spectrum M2p.59 Series, Hardware Manual, Page: 48 / 190

48 (c) Spectrum Instrumentation GmbH
Driver functions Software
type declarations to avoid any hard to find errors in your programs. If you’re using the driver in an environment that is not natively supported
by our examples and drivers please be sure to use a type declaration that represents a similar data width
Notation of variables and functions
In our header files and examples we use a common and reliable form of notation for variables and functions. Each name also contains the
type as a prefix. This notation form makes it easy to see implicit type conversions and minimizes programming errors that result from using
incorrect types. Feel free to use this notation form for your programs also-
Function spcm_hOpen
This function initializes and opens an installed card supporting the new SpcM driver interface, which at the time of printing, are all cards of
the M2i/M3i/M4i/M4x/M2p series and the related digitizerNETBOX/generatorNETBOX devices. The function returns a handle that has to
be used for driver access. If the card can’t be found or the loading of the driver generated an error the function returns a NULL. When calling
this function all card specific installation parameters are read out from the hardware and stored within the driver. It is only possible to open
one device by one software as concurrent hardware access may be very critical to system stability. As a result when trying to open the same
device twice an error will be raised and the function returns NULL.
Function spcm_hOpen (const char* szDeviceName):
Under Linux the device name in the function call needs to be a valid device name. Please change the string according to the location of the
device if you don’t use the standard Linux device names. The driver is installed as default under /dev/spcm0, /dev/spcm1 and so on. The
kernel driver numbers the devices starting with 0.
Under Windows the only part of the device name that is used is the tailing number. The rest of the device name is ignored. Therefore to keep
the examples simple we use the Linux notation in all our examples. The tailing number gives the index of the device to open. The Windows
kernel driver numbers all devices that it finds on boot time starting with 0.
Example for local installed cards
Example for digitizerNETBOX/generatorNETBOX and remote installed cards
If the function returns a NULL it is possible to read out the error description of the failed open function by simply passing this NULL to the error
function. The error function is described in one of the next topics.
Function spcm_vClose
This function closes the driver and releases all allocated resources. After closing the driver handle it is not possible to access this driver any
more. Be sure to close the driver if you don’t need it any more to allow other programs to get access to this device.
Function spcm_vClose:
Table 5: C/C++ type declarations for drivers and examples
Declaration Type Declaration Type
int8 8 bit signed integer (range from -128 to +127) uint8 8 bit unsigned integer (range from 0 to 255)
int16 16 bit signed integer (range from -32768 to 32767) uint16 16 bit unsigned integer (range from 0 to 65535)
int32 32 bit signed integer (range from -2147483648 to 2147483647) uint32 32 bit unsigned integer (range from 0 to 4294967295)
int64 64 bit signed integer (full range) uint64 64 bit unsigned integer (full range)
drv_handle handle to driver, implementation depends on operating system platform
Table 6: C/C++ type naming convention throughout drivers and examples
Declaration Notation Declaration Notation
int8 byName (byte) uint8 cName (character)
int16 nName uint16 wName (word)
int32 lName (long) uint32 dwName (double word)
int64 llName (long long) uint64 qwName (quad word)
int32* plName (pointer to long) char szName (string with zero termination)
drv_handle _stdcall spcm_hOpen ( // tries to open the device and returns handle or error code
const char* szDeviceName); // name of the device to be opened
drv_handle hDrv; // returns the handle to the opended driver or NULL in case of error
hDrv = spcm_hOpen ("/dev/spcm0"); // string to the driver to open
if (!hDrv)
printf (“open of driver failed\n”);
drv_handle hDrv; // returns the handle to the opended driver or NULL in case of error
hDrv = spcm_hOpen ("TCPIP::192.168.169.14::INST0::INSTR");
if (!hDrv)
printf (“open of driver failed\n”);
void _stdcall spcm_vClose ( // closes the device
drv_handle hDevice); // handle to an already opened device