Creating a Program
[User Manual]

Writing a Program

The Rulbus Device Library consists of several functions for each Rulbus module. These functions are published in the C/C++ header file rulbus.h. You normally need to only call functions for the Rulbus modules you want to use (but also see Handling Errors).

Rulbus modules are used according to the pattern: open -- use -- close, for example:

#include "rulbus.h"

int main()
{
   int32 handle;

   rb8510_dac12_open      ( &handle, "dac-ch0" );    // open device
   rb8510_dac12_setVoltage(  handle,  ...      );    // use it
   ...                                               //    even more
   rb8510_dac12_close     (  handle            );    // close device

   return 0;
}

The name used to open the DAC, "dac-ch0", corresponds to a name in the Rulbus device configuration file. See section Defining the Modules . Note that the types for parameters that may be modified (pointers) include a size specification in function calls to the library (e.g. int32 handle). Other parameters may be specified using the normal types.

Besides the functions related to specific Rulbus modules, there are library-related functions and general Rulbus device functions. Function names appear in the following forms:

• rdl_... -- library-related functions, like rdl_getLastError()
• rbyydd_... -- specific Rulbus module related functions, like rb8510_dac12_open()
• RulbusDevice_... -- general Rulbus device functions, like RulbusDevice_print()

Compiling the Program

In the following command, {include-path} specifies the directory with rulbus.h and rulbus-types.h and {library-path} specifies the directory with rulbus-omf.lib.

To create the program for use with the Rulbus Device Library DLL, compile as follows:

C:\>bcc32 -I(include-path) -L{library-path} example.cpp rulbus-omf.lib

With Borland C++ 5.6 you can also create a standalone program. See Compiling Programs, section Borland C++ for more information.

Handling Errors

All interface functions in the Rulbus Device Library use the same error handling pattern: they return the following status values:

• 0 the function call was successful
• 1 an error occurred

Notable exceptions to this rule are functions RulbusDevice_getByte(), RulbusDevice_putByte() and DllMain().

Properly written programs should always check the function return value to see if the function call was successful and should act accordingly. When an error occurred, a string explaining the error condition may be obtained with function rdl_getLastError().

#include <stdio.h>      // for stderr, fprintf()
#include "rulbus.h"     // for rb8510_dac12_open() etc.

static int error();

int main()
{
   int32 handle;

   if ( rb8510_dac12_open( &handle, ... ) )
      return error();

   // ...

   return 0;
}

static int error( )
{
   const int len = 100; char msg[len];

   rdl_getLastError( msg, len );
   fprintf( stderr, "%s\n", msg );

   return 1;
}

Complete Example

The following example program opens a DAC, generates a staircase voltage and closes the DAC again.

/*
 * dac.cpp - generate a staircase voltage.
 *
 * compile: bcc32 dac.cpp rulbus.lib
 */

#include <stdio.h>      // for printf() etc.
#include <stdlib.h>     // for strtol()
#include <windows.h>    // for Sleep()
#include "rulbus.h"     // rulbus interface

static int usage();     // print program usage, return EXIT_FAILURE
static int error();     // print error, return EXIT_FAILURE

/*
 * main - handle commandline arguments and generate staircase voltage on DAC.
 */

int main( int argc, char *argv[] )
{
   /*
    * handle commandline arguments:
    */

   if ( argc < 2 )
      return usage();

   /*
    * the name on the commandline must correspond to the name of a 12-bit 
    * DAC in the Rulbus device configuration file, typically rulbus.conf.
    */

   char *name = argv[1];

   /*
    * open the DAC:
    */

   int32 handle;
   if ( rb8510_dac12_open( &handle, name ) )
      return error();

   /*
    * generate 11 one volt steps, one per second:
    *
    * Note that the last step generates a RulbusRangeError, because the
    * voltage is outside [-10.235 .. +10.24 V].
    */

   for ( int i = 0; i <= 11; i++ )
   {
      fprintf( stdout, "[%d]", i );

      if ( rb8510_dac12_setVoltage( handle, i ) )
         return error();

      Sleep( 1000 );                    // delay one second
   }

   /*
    * close the DAC:
    */

   if ( rb8510_dac12_close( handle ) )
      return error();

   return EXIT_SUCCESS;
}

/*
 * usage - print program usage.
 */

static int usage()
{
   fprintf( stdout, "Usage: dac device-name\n" );
   return EXIT_FAILURE;
}

/*
 * error - retrieve and print Rulbus error.
 */

static int error()
{
   const int len = 100; char msg[len];

   rdl_getLastError( msg, len );
   fprintf( stdout, "%s\n", msg );

   return EXIT_FAILURE;
}

previous

top

next

---