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:
gcc -pthread -o myapp myapp.c libser_sr24.a -lmor if you have an older version of gcc,
gcc -D_REENTRANT -o myapp myapp.c libser_sr24.a -lm -lpthreadExample 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 -lmor 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
gcc -pthread -o myapp myapp.c -lser_sr24Example 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
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) |