API Programming Language Instructions


C/C++

     To use the serial board API from C or C++ regardless of your operating system, you must #include the ser_sr24.h file into your source code. This header file gives you a function declaration for each function in the API. It also defines constants for error codes, other constant values, and the necessary data structures.
Example: At the top of your C or C++ source file which uses any API functions or constants, you should have this line:

#include "ser_sr24.h"

Make sure that you have the ser_sr24.h file in the same directory as your source file or in the include directory for your compiler.
Also, if you have not yet installed the API library, see the installation page for instructions.

Compiling/Linking on Windows:
     Compiling procedures vary depending on what compiler you are using. You must instruct your compiler to link with the ser_sr24.lib file that is provided with the Windows version of the API. For example, in Microsoft Visual C++, this is done by adding ser_sr24.lib to the list of libraries in the "Link" section of the "Project Settings." You will need to either copy the ser_sr24.lib file into your compiler's "lib" directory or you could also simply copy the file into your project directory (with your source code). Some compilers such as Borland's may need the ser_sr24.lib file converted to their own format. The API already includes two formats of the ser_sr24.lib file: one file for use with Lcc and one for use with Microsoft Visual C++.

Compiling/Linking on Linux: Both static and shared libraries are included for the Linux platform. If you use the shared library, you should install this library on your Linux system, as described on the installation page. Regardless of which type of library you use, you must tell gcc that your program is going to be multithreaded, since the API is a multithreaded library. This can be done in one of two ways. On recent versions of gcc, you can simply specify the -pthread option. On versions of gcc that do not support this option, the -D_REENTRANT -lpthread options should be used instead. The first method does everything necessary to create a multithreaded application. In the second method, the precompiler definition _REENTRANT is created, which will affect what is defined in include files. Then the application is linked (-l) with the pthread library.
Note that your application will compile and link correctly without including all of these options, but you will likely run into some problems, especially with fork() and the exec functions if you leave these options out.

Static Library:

  1. For simplicity, It is recommended that you copy the file libser_sr24.a into the same folder that contains your source code.
  2. Link your application with libser_sr24.a, libm, and libpthread. On the gcc command line, this would add: libser_sr24.a -lm -lpthread
    But, as noted above, -lpthread can usually be replaced with -pthread
    Example of compiling and linking a single-file application:
          gcc -pthread -o myapp myapp.c libser_sr24.a -lm
       
    or if you have an older version of gcc,
          gcc -D_REENTRANT -o myapp myapp.c libser_sr24.a -lm -lpthread
       
    Example of compiling and linking a multiple file application:
          gcc -pthread -c myapp1.c               (produces myapp1.o)
          gcc -pthread -c myapp2.c               (produces myapp2.o)
          gcc -pthread -o myapp myapp1.o myapp2.o libser_sr24.a -lm
       
    or if you have an older version of gcc,
          gcc -D_REENTRANT -c myapp1.c               (produces myapp1.o)
          gcc -D_REENTRANT -c myapp2.c               (produces myapp2.o)
          gcc -o myapp myapp1.o myapp2.o libser_sr24.a -lm -lpthread
       
Shared Library:
  1. Make sure you have properly installed the library, as described on the installation page. Note that the installation procedure only needs to be performed once per system.
  2. Link your application with the shared library. On the gcc command line, this adds: -lser_sr24
    These examples will be for recent versions of gcc. As specified above, if your gcc doesn't support -pthread, replace it with -D_REENTRANT -lpthread
    Example of compiling and linking a single-file application:
           gcc -pthread -o myapp myapp.c -lser_sr24
        
    Example of compiling and linking a multiple file application:
           gcc -pthread -c myapp1.c
           gcc -pthread -c myapp2.c
           gcc -pthread -o myapp myapp1.o myapp2.o -lser_sr24
        

Visual Basic

     To obtain access to the API functions and constants from Visual Basic, you should add the ser_sr24.bas module and the ser_sr24.cls class module to your Visual Basic project.  These files are included with the Windows versions of the API. The ser_sr24.cls module implments a Visual Basic class, providing an object-oriented interface to the API. The ser_sr24.bas file contains function declarations, constants, and some code that is necessary for the implementation of hardware event handlers. The resulting interface is very convenient and easy to understand.

     To add these modules to your project, copy them into your project directory. The 'Project' menu contains the 'Add Module' and 'Add Class Module' commands. Use these to add the files. When you choose one of these commands, a dialog will pop up. Choose the 'Existing' tab, since you want to add existing modules to the project. You will then see a file dialog box where you can select the file to add.

     Note that the Visual Basic class simply provides an object-oriented interface to the API. It works in conjunction with the API dll file (ser_sr24.dll). This file needs to be placed in your system directory or in the directory with your executable. See the installation page for details.

     Don't worry if you are new to object oriented programming; it is very simple to use the serial board from Visual Basic. The first thing you have to do is to declare and initialize an object variable. This variable represents the serial board, and it allows you to access properties and methods which control the board. See the bottom of the ser_sr24_open documentation page for a code example of how to declare and initialize an object variable. This object variable may then be used for accessing all of the serial board functions. The object variable represents the board, and the board is accessed by calling object methods. In the API reference section, there is a page dedicated to each function, explaining the function and the expected parameters. At the bottom of each page, there is a section devoted to Visual Basic, explaining any differences for Visual Basic users and presenting a code snippet to clarify usage. The included sample programs also provide guidance. One thing to notice about the object-oriented interface is that the serial board handle is stored internally in the object; you don't have to pass it to the object methods.


Back to Contents Winford Engineering (2000)