2.3. Interface Between Visual Basic and Visual C++

2.3.1. Introduction

In the last section, we discussed the advantages of calling a DLL from within Visual Basic. This calling style is especially useful in real-time control and measurement applications, such as automated test equipment, automobile manufacturing, real-time control and process, as well as semiconductor inspection and process. In those applications, time and speed are critical factors to successful implementations. Visual Basic provides good environments (Graphic User Interfaces) between the human and machine, and it integrates separate tasks to an Object-Oriented-Programming environment and connects them with a sequence of events. Visual Basic is a machine-independent language, and it can be used for any operating system as long as a Visual Basic run-time engine is provided. But Visual Basic does not have a powerful ability to access low-level components, such as device drivers, I/O manager, Hardware Abstraction Layer (HAL), and even the hardware. So a medium or an interface is needed to connect between Visual Basic and low-level components. C/C++ is a good candidate for this interface.

As we know, C/C++, especially Visual C++, is a very good language applied in low-level applications. Most device drivers are developed in C. Even Windows API libraries that we employed in the previous section are developed in C. Visual Basic can access a C/C++ program by calling either static or Dynamic Link Libraries.

Dynamic Link Libraries can be loaded during the program running stage, not the program compiling stage. This provides more flexibility for the applications and saves memory space. Also, the DLL can be shared by multiple tasks, which is a popular technology today.

By combining Visual Basic and DLL developed in C/C++, we can conveniently access low-level components and still keep the advantage of using the good GUI provided by Visual Basic. Both user-friendly interface and real-time controllability can be obtained at the same time.

Generally, the DLL can be divided into two categories: Win32 general-purpose DLL and MFC-based DLL. The former can be developed in either the C environment or the Visual C++ environment, but the latter can only be developed in the Visual C++ environment. The Win32 general-purpose DLL has a relatively wider range of implementations, and it can be called by most third-party programs, such as Visual Basic, Java, Perl, and SmallTalk. The MFC-based DLL can only be accessed by a limited number of languages, such as Visual C++ and Visual Basic. But the MFC-based DLL has an advantage compared with the Win32 general-purpose DLL: The former can access objects and classes defined in the MFC library.

In order to meet the needs of general-purpose applications, we will concentrate on the development of the Win32 general-purpose DLL. To implement a Win32 general-purpose DLL, which is similar to calling a Window API DLL as we discussed in the previous section, you need to declare the DLL function prototype. This declaration is similar to earlier declarations, but it is not exactly the same. Besides the declaration, you also need to first develop a user-defined DLL and make a connection between Visual Basic and Visual C++. We will discuss this issue in detail next.

2.3.2. General Requirement for Calling a User-Defined DLL

To successfully call a user-defined DLL from within Visual Basic, you need to handle two kinds of jobs: develop a user-defined DLL in the Visual C++ domain, and declare and map the DLL functions in the Visual Basic domain.

Let's take a look at these two issues separately. First, in order to develop a Win32 general-purpose DLL, you need the following files.

SOURCE FILES

• Source files define and develop the source code for the DLL. This source code contains all DLL functions and local functions, as well as all functionalities of the DLL.

HEADER FILES

• Header files declare the prototypes for all DLL functions, local functions, and other components, such as structures and structure pointers. These header files are necessary if the DLL functions are to be accessed by some programs developed in C/C++. You have to place these header files into the calling programs to provide prototypes for all DLL functions.

DEF FILE

• The DEF file, or definition file, exports all DLL functions developed in the source files to the outside world. Third-party programs cannot access any DLL function without this definition file. Based on this DEF file, third-party programs can easily identify any DLL function developed in either C or Visual C++. Some calling programs developed in C/C++ don't even need this DEF file; they can still find the DLL functions they need.

LIB FILE

• The LIB file, or library file, provides a path for the calling program to locate the DLL file when the calling program is compiled. Without this library file, the compiler cannot recognize any DLL function as it compiles the calling program. This library file must be inserted into the calling program and linked with the calling program to obtain the target file if the calling program is developed in C/C++.

DLL FILE

• This is our final product for the DLL project. Basically, a DLL file is similar to an executable file (.exe), but it cannot run by itself. You need a calling program to call that DLL file to access and run DLL functions that are located in that DLL file. This DLL file should be placed in a searchable path in your machine, such as in C:WINDOWSSYSTEM. In this way, the computer can automatically find that DLL file and dynamically connect it with your calling program. You can define a user-defined DLL directory and save the DLL file under that directory, but you have to make that user-defined DLL directory a searchable directory on your system. Otherwise, your computer will not know where to find that DLL file, and a Cannot find the DLL error would be displayed on screen.

In order to declare and map DLL functions in the Visual Basic domain, you need to declare the prototype of DLL functions. This declaration is similar to earlier declarations when calling a Windows API DLL function. One difference is the library's name clause. You should place the full name of the library, which includes the complete path and library name, in this clause. For example, say you developed a DLL file named SimpleDLL.dll and saved this file in the directory C:stdll. You would need to place the full name of that library, C:stdllSimpleDLL.dll, in the library's name clause.

Let's start with a simple example project. In Chapter 4, we will develop a DLL file in the Visual C++ domain named STRandomDLL. The purpose of that DLL file is to interface to Smalltalk and compute the maximum, minimum, and mean values for a random sequence. Here, we want to use that DLL file, with some modifications, in our Visual Basic project.

The purpose of this simple example is to create a Visual Basic project to accept the user's inputs, for the amplitude and number for a random sequence. Then, we create the random sequence in the Visual Basic domain. Visual Basic will call the DLL developed in Visual C++ to perform the calculations for the maximum, minimum, and mean values for that random sequence. The calculated results will be returned to the Visual Basic domain by passing a structure. Finally, the calculated results will be displayed in three textboxes in the Visual Basic domain.

2.3.3. A Simple DLL Example

First, let's develop a DLL project in the Visual C++ domain. Launch Visual C++ 6.0 and create a new project with type Win32 Dynamic-Link Library, and enter VBSimple into the Project name: input field. Make sure that the content of the Location: field is our user-defined project folder, C:Vbdll. Click OK to open this new project.

In the newly opened project, click File|New to create a new C/C++ Header File, enter VBSimple in the File name: field, then click OK to open this header file. Enter the code shown in Figure 2-31 into this file.

Now, click the File|New menu item from Visual C++ 6.0 to create a new C++ Source File. Enter VBSimple in the File name: field, and click OK to open this new source file. Enter the code shown in Figure 2-32 into this new source file.

Figure 2-32.

						/******************************************************************************
						* NAME       : VBSimple.cpp
						* DESC.      : DLL file for calculation of random array result, called by Visual Basic.
						* DATE       : 6/30/2002
						* PGRMR.     : Y. Bai
						******************************************************************************/
						#include <windows.h>
						#include <cstdio>
						#include <cstdlib>
						#include <cstring>
						#include <cmath>
						#include <iostream>
						#include "VBSimple.h"
						using namespace std;
						Result cResult;
						DllExport int CALLBACK randCalc(int size, double rdataArray[])
						{
						int i;
						m_max = rdataArray[0];
						m_min = m_max;
						for (i = 0; i < size; i++)
						{
						if (m_max < rdataArray[i])
						m_max = rdataArray[i];
						if (m_min > rdataArray[i])
						m_min = rdataArray[i];
						m_mean = m_mean + rdataArray[i];
						}
						m_mean = m_mean/size;
						return 0;
						}
						DllExport Result CALLBACK randResult()
						{
						cResult.max = convert (m_max);
						cResult.min = convert (m_min);
						cResult.mean = convert (m_mean);
						return cResult;
						}
						double convert(double input)
						{
						char buf[128];
						sprintf(buf, "%.3f", input);
						return atof(buf);
						}
					

The code entered here is straightforward and doesn't need further explanation except for the CALLBACK keyword. Both DLL function declarations contain a CALLBACK keyword. When writing code in DLLs, it is important to remember that Stack Segment ! = Data Segment. This is an issue when an application function passes a pointer to one of its local variables to the DLL function. In Microsoft C++, all NEAR pointers are assumed to be relative to Data Segment. The way to avoid problems is to either

• use a function prototype declaring the parameter to be a FAR pointer, or

• explicitly cast the parameter to FAR.

DLL functions that will be called from applications should be declared with the FAR modifier because an intersegment jump is required from the application. Functions that are only called from within the DLL may be declared NEAR. The PASCAL or _cdecl calling conventions may be used as appropriate. Functions called from Windows must be declared using the PASCAL calling convention.

To summarize, a DLL function called by other applications should be cast by a keyword, FAR PASCAL. In Visual C++, the CALLBACK macro is equivalent to this FAR PASCAL cast. That is why you must place the macro CALLBACK just in front of the DLL function name.

We need to do one more thing before we can build our project—that is to create a DEF file, or definition file. Click the File|New menu item from Visual C++ 6.0, create a new Text file, enter VBSimple in the File name: field, and click OK to open this new text file.

We want to create a DEF file, not a text file. But in Visual C++ 6.0, you cannot find a file type of DEF, and the DEF file is similar to a text file. So we need to do the following conversion to translate that text file to a DEF file.

Click Project|Add To Project|Files. . . to open the Insert Files into Project dialog box. Select All Files (*.*) from the Files of type: list box and find the text file VBSimple.txt you just added. Right-click on this text file and select Rename from the pop-up menu. Replace the file extension .txt with .def and click OK. Click Yes in the message box to confirm that we want to rename this file. The text file VBSimple.txt has been renamed VBSimple.def, as shown in Figure 2-33.

Now, click the converted VBSimple.def file to select it, and click OK to add this DEF file into our project. From the Visual C++ 6.0 workspace, you will find that this DEF file has been added into the project. Click on the VBSimple.txt file from the Visual C++ 6.0 workspace to select it, then click Edit|Delete to remove this text file because we no longer need it.

Open the converted DEF file and enter the code shown in Figure 2-34 into this file.

Figure 2-34.

						LIBRARY VBSimple.dll
						EXPORTS
						randCalc
						randResult
					

Click Build|Build VBSimple.dll to build our DLL file. You can change the Active Configuration from Debug to Release and build the terminal DLL file in there. If everything is correct, your terminal DLL file should be located in either the Debug or Release folder, depending on your Active Configuration selection. Open the Active Configuration folder and copy the destination DLL file, VBSimple.dll, to our user-defined DLL directory—in our case, C:stdll. This is a searchable directory on our computer system. You can copy this DLL file directly to the system DLL directory, such as C:WINDOWSSYSTEM, if you don't like to create a user-defined DLL directory. The computer will automatically find and locate this DLL file as you run your program.

Now let's develop a Visual Basic project that calls the DLL file we just created. Launch Visual Basic 6.0 and create a new Standard EXE project. Click OK to open this newly created project. Click File|Save Form1.frm As to save Form1 as VBSimple.frm, and click File|Save Project As to change the project's name to VBSimple.vbp. Click the Form VBSimple and add the following components to this form. Figure 2-35 shows the resulting screen.

Click the View Code button to open the code window. Click General from the Object list to open the Form's General Declaration section, and enter the code from Figure 2-36 into this section. Please note that all variables and functions you declared here are the Form's level variables or the Form's level functions, which means that the scope of variables and functions defined in this section is the current Form. In other words, those variables and functions can be accessed by all event procedures defined in the current Form, VBSimple.frm. Any other event procedure defined in other Forms (even in the current project) cannot access those variables and functions.

The purpose of the Option Explicit statement is to tell the Visual Basic interpreter that all variables and functions declared in this Form are unique, and any variable used in this Form must be first declared, otherwise, an error message will be displayed for any variable that has been used without being declared.

In Visual Basic 6.0, it is legal to use a variable in the program without declaring it prior to use. Of course, this is convenient to users, but this also brings up a problem. The program would be absolutely wrong or even crash your computer if the user, thinking that a variable is a valid predeclared variable, used that variable and either the variable's name was misspelled or it was out of scope.

In order to solve this problem, the Option Explicit statement is used here to make sure that all variables used in this Form are unique and have been declared before they are used.

One point we need to emphasize is that the DLL file should be stored in a searchable path on your computer if you declare the DLL function in this way (only the DLL name, VBSimple.dll, is provided at the DLL name field). Otherwise, you should provide a full name for your DLL (including the path and DLL name). You can even delete the extension (.dll) in the DLL name and only provide the DLL name as "VBSimple" in the name field.

Another point is that you should declare all variables or user-defined data types that will be used by the DLL functions as arguments before you declare the DLL functions. Otherwise, the Visual Basic interpreter will give an error message.

Now, click cmdCreate from the Object list to open the Create command button's event procedure, and enter the code shown in Figure 2-37 into this procedure.

Now, click cmdCalc from the Object list to open the Calculate event procedure, and enter the code shown in Figure 2-38 into this procedure.

Enter the End command to the cmdExit_Click() event procedure to exit the project.

Now, run the project and the GUI form, as shown in Figure 2-39, should be displayed on screen. Enter some numbers in the Amplitude and Number fields, such as 10 and 100, to define the magnitude and the number of the random array to be created. Click the Create button to create a new random data array in the Visual Basic domain. Then, click the Calculate button to call two DLL functions to calculate and return the statistical results for the random data array.

The calculated results, which are maximum value, minimum value, and mean value of the random sequence, will be displayed in three textboxes, also shown in Figure 2-39.

You will notice that the calculated results have three significant digits, because we used a convert() function in the DLL function to translate the results to this mode.

Our first project is successful, and you have obtained hands-on experience in developing a DLL and interfacing that DLL from the Visual Basic domain. Click Exit to end the project.

2.3.4. A DLL Serial Port Test Project

A simple DLL project is discussed in the previous section. In this section, we show you a more complicated project in which a DLL is called and used as a drive to access and test the low-level hardware and serial ports from within the Visual Basic domain. To make things simple, we use an example DLL developed in Chapter 4, SerialDLL, which is used to interface with Smalltalk to test the serial ports. We need to make some modifications to that DLL file to match the requirements of our current application.

2.3.4.1. Develop a Visual C++ DLL Driver Project

We still want to use a single-loop test mode to test the serial port by sending a value to a port, then picking up that value from the same port to compare it with the sent-out value. The test is successful and the port is good if the sent-out value and the picked-up value are identical. To perform this test, you need to connect the sent-out pin (Pin-3 on a DB-9 port) and the receiving pin (Pin-2 on a DB-9 port) together. Refer to Figure 4-51 in Chapter 4 for more detailed information on this connection.

The functionality of this project is that all testing commands are sent from within the Visual Basic domain, and the associated command is passed to a DLL developed in Visual C++. The DLL also works as a device driver to test the serial port based on the command sent by Visual Basic. The commands sent from within Visual Basic are

• Setup: Sends out a setup command to initialize a serial port.

• Write: Sends out a value to a serial port.

• Read: Picks up a value from a serial port.

• Close: Terminates the DLL and Visual Basic application.

Make sure that you connect your serial port in the way shown in Figure 4-51 in Chapter 4. You should shut the power off when making the connection.

Now, let's take a look at the DLL developed in the Visual C++ domain. We want to modify an existing DLL project, SerialDLL, which is located in the Chapter 4VisualWorksvwdllSerialDLL folder. We don't need to develop a new project; instead, we can add this project to our new project and modify it inside our new project.

Launch Visual C++ 6.0 and create a new project with type Win32 Dynamic-Link Library, then enter VBSerialDLL in the Project name: field. Make sure that the Location: field contains our user-defined project folder, in our case, C:Vbdll. You can create and select any directory you like on your computer as a user-defined project folder. Click OK to open this new project.

Open Windows Explorer and copy the following files from the directory Chapter 4VisualWorksvwdllSerialDLL to our new project directory C:VbdllVBSerialDLL:

• SerialDLL.cpp

• SerialDLL.h

• SerialDLL.def

Return to the Visual C++ domain, and create three new files as follows:

• Source file: VBSerialDLL.cpp

• Header file: VBSerialDLL.h

• DEF file: VBSerialDLL.def

Open and copy the contents of each file to the associated newly created file. For example, open SerialDLL.cpp and copy its contents to the newly created source file VBSerialDLL.cpp. Do same thing for the SerialDLL.h and SerialDLL.def files. Now, open the copied header file, VBSerialDLL.h, and make the modifications highlighted with underscores as shown in Figure 2-40.

Figure 2-40.

							/****************************************************************************
							* NAME      : VBSerialDLL.h
							* DESC.     : Header file for VBSerialDLL.cpp
							* PGRMER.   : Y. Bai
							* DATE      : 7/2/2002
							*****************************************************************************/
							#ifndef _SERIALDLL_H_
							#define _SERIALDLL_H_
							#define MAX_STRING                256
							#define NOPARITY                    0
							#define ONESTOPBIT                  0
							#define RTS_CONTROL_DISABLE      0x00
							#define RTS_CONTROL_ENABLE       0x01
							#define DTR_CONTROL_DISABLE      0x00
							#define DTR_CONTROL_ENABLE       0x01
							#define msg(info) MessageBox(NULL, info, "", MB_OK)
							typedef struct
							{
							unsigned long ulCtrlerID;
							char       cEcho;
							char       cEORChar;
							long       lTimeout;
							long       lBaudRate;
							long       lDataBits;
							} SerialCreate, *pSerialCreate;
							typedef struct
							{
							char *pcBuffer;        /* added */
							int iMaxChars;         /* added */
							int piNumRcvd;        /* added */
							char cTermChar;       /* added */
							} CommPortClass;
							typedef enum
							{
							OK      = 0,           /* no error */
							EC_TIMEOUT,
							EC_FOPEN,
							EC_INVAL_CONFIG,
							EC_TIMEOUT_SET,
							EC_RECV_TIMEOUT,
							EC_EXIT_CODE,
							EC_WAIT_SINGLEOBJ,
							EC_INVALIDPORT,
							EC_WRITE_FAIL,
							EC_CREATE_THREAD,
							EC_UNKNOWNERROR
							}ERR_CODE;
							HANDLE    hPort;
							char*     sPortName;
							bool      PortCreateflg = false;
							/*local functions*/
							ERR_CODE PortInitialize(LPTSTR lpszPortName, pSerialCreate pCreate);
							ERR_CODE PortWrite(char* bByte, int NumByte);
							ERR_CODE PortRead(CommPortClass *hCommPort);
							void WINAPI ThreadFunc(void* hCommPorts);
							/*---------------------------------------------------------------------*/
							#define DllExport __declspec( dllexport )
							/*---------------------------------------------------------------------*/
							DllExport int CALLBACK Setup(int cPort, int bRate);
							DllExport int CALLBACK Read();
							DllExport int CALLBACK Write(int sdata);
							DllExport int CALLBACK Close();
							#endif
						

The only modification we made to this header file is adding the CALLBACK macro before each DLL function. This macro is very important in the connection between the DLL functions and the external applications. You would encounter a Bad calling convention error if you forgot to add this macro when you tried to call a DLL function from within the Visual Basic domain, and it is very difficult to debug this in your program.

Now, open the copied source file VBSerialDLL.cpp and make the following modifications, shown in Figure 2-41. The source code is relatively long, but don't worry about that. The purpose of showing this source file is to give you a complete picture of a derived project developed in the C/C++ domain. You will also find that the only modification we made to this source code is to add the CALLBACK macro, which has been underscored, before each DLL function implementation.

Figure 2-41.

							/***************************************************************************
							* NAME      : VBSerialDLL.cpp
							* DESC.     : DLL functions to interface to rs-232 serial port, called by VB.
							* PRGMER.   : Y. Bai
							* DATE      : 7/2/2002
							****************************************************************************/
							#include <stdio.h>
							#include <windows.h>
							#include <stdlib.h>
							#include <string.h>
							#include "VBSerialDLL.h"
							DllExport int CALLBACK Setup(int cPort, int bRate)
							{
							ERR_CODE rc = OK;
							pSerialCreate pParam;
							pParam = new SerialCreate;
							pParam->lBaudRate = bRate;
							pParam->lDataBits = 8;
							pParam->lTimeout = 3000;
							switch(cPort)
							{
							case 1:
							sPortName = "COM1";
							break;
							case 2:
							sPortName = "COM2";
							break;
							case 3:
							sPortName = "COM3";
							break;
							case 4:
							sPortName = "COM4";
							break;
							default:
							return EC_INVALIDPORT;
							}
							if (PortCreateflg)
							{
							msg("Port has been Setup ");
							return rc;
							}
							rc = PortInitialize(sPortName, pParam);
							if (rc != 0)
							msg("ERROR in PortInitialize()!");
							delete pParam;
							PortCreateflg = true;
							return rc;
							}
							DllExport int CALLBACK Write(int sdata)
							{
							int numByte = 1;
							char sByte[8];
							ERR_CODE rc = OK;
							sprintf(sByte, "%c", sdata);
							rc = PortWrite(sByte, numByte);
							if (rc != 0)
							msg("ERROR in PortWrite() !");
							return rc;
							}
							DllExport int CALLBACK Read()
							{
							int idata;
							char cdata[8];
							ERR_CODE rc = OK;
							CommPortClass* commClass;
							commClass = new CommPortClass;
							commClass->iMaxChars = 1;
							rc = PortRead(commClass);
							if (rc != 0)
							msg("ERROR in PortRead()! ");
							sprintf(cdata, "%d", commClass->pcBuffer[0]);
							idata = atoi(cdata);
							delete commClass;
							return idata;
							}
							DllExport int CALLBACK Close()
							{
							ERR_CODE rc = OK;
							if (PortCreateflg)
							CloseHandle(hPort);
							PortCreateflg = false;
							return rc;
							}
							ERR_CODE PortInitialize(LPTSTR lpszPortName, pSerialCreate pCreate)
							{
							DWORD          dwError;
							DCB            PortDCB;
							ERR_CODE       ecStatus = OK;
							COMMTIMEOUTS         CommTimeouts;
							unsigned char dBit;
							// check if the port has been created...
							if (PortCreateflg)
							{
							msg("Port has been initialized!");
							return ecStatus;
							}
							// Open the serial port.
							hPort = CreateFile(lpszPortName, // Pointer to the name of the port
							GENERIC_READ | GENERIC_WRITE, // Access (read/write) mode
							0,                       // Share mode
							NULL,                    // Pointer to the security attribute
							OPEN_EXISTING,           // How to open the serial port
							0,                       // Port attributes
							NULL);                   // Handle to port with attribute to copy
							// If it fails to open the port, return error.
							if ( hPort == INVALID_HANDLE_VALUE )
							{
							// Could not open the port.
							dwError = GetLastError();
							msg("Unable to open the port");
							CloseHandle(hPort);
							return EC_FOPEN;
							}
							PortCreateflg = TRUE;
							PortDCB.DCBlength = sizeof(DCB);
							// Get the default port setting information.
							GetCommState(hPort, &PortDCB);
							// Change the DCB structure settings.
							PortDCB.BaudRate = pCreate->lBaudRate;  // Current baud
							PortDCB.fBinary = TRUE;           // Binary mode; no EOF check
							PortDCB.fParity = TRUE;           // Enable parity checking.
							PortDCB.fOutxCtsFlow = FALSE;     // No CTS output flow control
							PortDCB.fOutxDsrFlow = FALSE;     // No DSR output flow control
							PortDCB.fDtrControl = DTR_CONTROL_ENABLE;// DTR flow control type
							PortDCB.fDsrSensitivity = FALSE;  // DSR sensitivity
							PortDCB.fTXContinueOnXoff = TRUE; // FALSE// XOFF continues Tx
							PortDCB.fOutX = FALSE;            // No XON/XOFF out flow control
							PortDCB.fInX = FALSE;             // No XON/XOFF in flow control
							PortDCB.fErrorChar = FALSE;       // Disable error replacement.
							PortDCB.fNull = FALSE;            // Disable null stripping.
							PortDCB.fRtsControl = RTS_CONTROL_ENABLE;// RTS flow control
							PortDCB.fAbortOnError = FALSE;    // Do not abort reads/writes on error.
							dBit = (unsigned char)pCreate->lDataBits;
							PortDCB.ByteSize = dBit;          // Number of bits/bytes, 4-8
							PortDCB.Parity = NOPARITY;        // 0-4=no,odd,even,mark,space
							PortDCB.StopBits = ONESTOPBIT;    // 0,1,2 = 1, 1.5, 2
							// Configure the port according to the specifications of the DCB structure.
							if (!SetCommState (hPort, &PortDCB))
							{
							// Could not create the read thread.
							dwError = GetLastError();
							msg("Unable to configure the serial port");
							return EC_INVAL_CONFIG;
							}
							// Retrieve the time-out parameters for all read and write operations on the port.
							GetCommTimeouts(hPort, &CommTimeouts);
							// Change the COMMTIMEOUTS structure settings.
							CommTimeouts.ReadIntervalTimeout = MAXDWORD;
							CommTimeouts.ReadTotalTimeoutMultiplier = 0;
							CommTimeouts.ReadTotalTimeoutConstant = 0;
							CommTimeouts.WriteTotalTimeoutMultiplier = 10;
							CommTimeouts.WriteTotalTimeoutConstant = 1000;
							// Set the time-out parameters for all read and write operations on the port.
							if (!SetCommTimeouts (hPort, &CommTimeouts))
							{
							// Could not create the read thread.
							dwError = GetLastError();
							msg("Unable to set the time-out parameters");
							return EC_TIMEOUT_SET;
							}
							EscapeCommFunction(hPort, SETDTR);
							EscapeCommFunction(hPort, SETRTS);
							return ecStatus;
							}
							/******************************************************************************
							* NAME        : PortWrite()
							* DESC.       : Write data to the port
							* DATE        : 11/9/00
							* PRGMER.     : Y. Bai
							******************************************************************************/
							ERR_CODE PortWrite(char* bByte, int NumByte)
							{
							DWORD dwError;
							DWORD dwNumBytesWritten;
							ERR_CODE ecStatus = OK;
							if (!WriteFile (hPort,      // Port handle
							bByte,      // Pointer to the data to write
							NumByte,    // Number of bytes to write
							&dwNumBytesWritten, // Pointer to the number of bytes written
							NULL))              // Must be NULL for Windows CE
							{
							// WriteFile failed. Report error.
							dwError = GetLastError ();
							msg("ERROR in PortWrite ..");
							return EC_WRITE_FAIL;
							}
							return ecStatus;
							}
							/*********************************************************************************
							* NAME      : PortRead()
							* PGRMER.   : Y. Bai
							*********************************************************************************/
							ERR_CODE PortRead(CommPortClass *hCommPort)
							{
							HANDLE hThread;                     // handler for port read thread
							DWORD IDThread;
							DWORD Ret, ExitCode;
							DWORD dTimeout = 5000;              // define time out value: 5 sec.
							ERR_CODE ecStatus = OK;
							if (!(hThread = CreateThread(NULL,  // no security attributes
							0,                         // use default stack size
							(LPTHREAD_START_ROUTINE) ThreadFunc,
							(LPVOID)hCommPort,         // parameter to thread funciton
							CREATE_SUSPENDED,         // creation flag - suspended
							&IDThread) ) )           // returns thread ID
							{
							msg("Create Read Thread failed");
							return EC_CREATE_THREAD;
							}
							ResumeThread(hThread);            // start thread now
							Ret = WaitForSingleObject(hThread, dTimeout);
							if (Ret == WAIT_OBJECT_0)
							{          // data received & process it...
							// Need do nothing because the data has been stored in the hCommPort in Thread Func.
							CloseHandle(hThread);
							}
							else if (Ret == WAIT_TIMEOUT)
							{
							// time out happened, warning & kill thread
							Ret = GetExitCodeThread(hThread, &ExitCode);
							msg("Time out happened in PortRead() ");
							if (ExitCode == STILL_ACTIVE)
							{
							TerminateThread(hThread, ExitCode);
							CloseHandle(hThread);
							return EC_RECV_TIMEOUT;
							}
							else
							{
							CloseHandle(hThread);
							msg("ERROR in GetExitCodeThread: != STILL_ACTIVE ");
							ecStatus = EC_EXIT_CODE;
							}
							}
							else
							{
							msg("ERROR in WaitFor SingleObject ");
							ecStatus = EC_WAIT_SINGLEOBJ;
							}
							return ecStatus;
							}
							/******************************************************************************
							* NAME      : ThreadFunc()
							* DESC.     : This function starts to read the port data.
							*           : The reason to use this thread is to overcome the hang up introduced by the
							*           : WaitCommEvent() function which waits for only the comm. event, not
							*           : synchronization event. The program will be dead-cycle without this thread.
							* PGRMER.   : Y. Bai
							* DATE      :  12/4/00
							*******************************************************************************/
							void WINAPI ThreadFunc(void* hCommPorts)
							{
							char Byte;
							BOOL bResult, fDone;
							int nTotRead = 0;
							DWORD dwCommModemStatus, dwBytesTransferred;
							CommPortClass* CommPorts;
							ERR_CODE ecStatus = OK;
							CommPorts = (CommPortClass* )hCommPorts;
							// Specify a set of events to be monitored for the port.
							SetCommMask(hPort, EV_RXCHAR|EV_CTS|EV_DSR|EV_RLSD|EV_RING);
							fDone = FALSE;
							while (!fDone)
							{
							// Wait for an event to occur for the port.
							WaitCommEvent(hPort, &dwCommModemStatus, 0);
							// Re-specify the set of events to be monitored for the port.
							SetCommMask(hPort, EV_RXCHAR|EV_CTS|EV_DSR|EV_RLSD| EV_RING);
							if (dwCommModemStatus & EV_RXCHAR||dwCommModemStatus & EV_RLSD)
							{
							// received the char_event, Loop for waiting for the data.
							do
							{
							// Read the data from the serial port.
							bResult = ReadFile(hPort, &Byte, 1, &dwBytesTransferred, 0);
							if (!bResult)
							{
							msg("ERROR in ReadFile !");
							fDone = TRUE;
							break;
							}
							else
							{   // Display the data read.
							if (dwBytesTransferred == 1)
							{
							if (Byte == 0x0D ||Byte == 0x0A) // null char or LF
							{
							CommPorts->piNumRcvd = nTotRead;
							fDone = TRUE;
							break;
							}
							CommPorts->pcBuffer[nTotRead] = Byte;
							nTotRead++;
							if (nTotRead == CommPorts->iMaxChars)
							{
							fDone = TRUE;
							break;
							}
							}
							else
							{
							if (Byte == 0x0D ||Byte == 0x0A) // null char
							{
							msg("Received null character ");
							fDone = TRUE;
							break;
							}
							}
							}
							}while (dwBytesTransferred == 1); //while (nTotRead < pRecv->iMaxChars);
							}
							}  // while
							return;
							}
						

Besides the DLL functions, there are 4 additional local functions implemented in this project. The purpose of these local functions is to access the low-level device driver to communicate with the serial port to be tested.

For this DLL, we assume that we have 4 COM ports available, ranging from COM1 to COM4. This is a very popular COM port arrangement for most computers. Generally, most users can access COM1 or COM2 on their computers, and some of the other ports are utilized by the system itself.

In our application, COM1 is available to us, and we will use this port as our testing port. Open the copied DEF file VBSerialDLL.def, and make the modifications shown in Figure 2-42.

Figure 2-42.

							LIBRARY VBSerialDLL.dll
							EXPORTS
							Setup
							Read
							Write
							Close
						

Now, click Build|Build VBSerialDLL.dll from the Visual C++ 6.0 menu bar to build the DLL project. If everything is fine, open Windows Explorer and copy this DLL file, VBSerialDLL.dll, to our user-defined DLL directory C:stdll.

2.3.4.2. Develop a Visual Basic Testing Project

Let's switch to the Visual Basic domain to develop our Visual Basic project to call that DLL to test the serial port. In this Visual Basic project, we plan to create two forms; one is used to get the user's inputs for the COM port setup parameters, COM port number and baud rate, and the other is used to send commands to test the serial port.

Launch Visual Basic 6.0 and create a new Standard EXE project. In the opened project, click Form1 on the screen and enter the following properties in the Properties window:

• Name: VBSerialDLL

• Caption: VB Serial Port Test DLL

Click the Project1 icon on the Project Explorer window, and enter VBSerial in the Name property of this project to change the project's name to VBSerial.vbp.

Save the form now named VBSerialDLL.frm to our user-defined project folder. Also, save this project (VBSerial.vbp) as VBProject to our user-defined project folder C:Vbdll.

Now, click Project|Add Form. In the opened dialog box, keep the default New Form selected, and click Open to open this new Form.

Click on the new form and enter Setup in the Name property of this form to name this form Setup. Add the following components to this form:

Set the Form's BackColor property to Yellow. Your finished Form, Setup, should match the one that is shown in Figure 2-43.

Now we have two forms in this project. We need to tell the Visual Basic interpreter which form should be displayed first as the project runs. To do that, click the Project|VBProject Properties. . . menu item from the menu bar, the last item on the Project submenu, to open the Project Properties dialog box. Select Setup from the Startup Object: field to make the Setup Form be our first form to be displayed as the program runs. Click OK to save this setting and close the dialog box.

Now, return to the Visual Basic workspace, click on another Form, VBSerialDLL, and add the following components to that form:

^[*] BackColor: Yellow

^[**] Interval: 500 ms

Please note that we add a Timer to this project. The purpose of this Timer is to periodically send out the test data to the serial port, and read back the test data from the same serial port after the data is sent out. Then we can compare the sending-out data and the reading-back data to check whether both data are identical. In the ideal case, these two data should be the same if the serial port is fine and communication between the program and driver has no problem.

The Timer has one property, Interval, which is used to determine how often the Timer should be activated and to execute the Timer event procedure to perform some desired job inside the procedure. You should place the task code inside the Timer event procedure and let the Timer handle that job periodically for you. The unit of the Interval is ms. Your finished Form, VBSerialDLL, should match that shown in Figure 2-44.

Now let's develop code for our project. Click the Setup icon from the Project Explorer window to open the Setup Form. Then click the View Code button to open the code window for this Form.

First, select the General item from the Object list to open the Form's General Declaration section, and enter the code Option Explicit at this section. Remember, the purpose of this statement is to avoid the misuse of variables in this program as the Form runs.

Next, select the Form item from the Object list to open the Form_Load event procedure. This procedure is the first procedure as this Form is executed. We want to display this Form at a certain location on the screen when the program executes. So we use the Object Me and its properties to set up the initial position for this Form. The Me object is the Form itself and the properties we want to use are Left and Top, which can be considered as the upper-left coordinates of the Form on screen.

Enter the code shown in Figure 2-45 into the Form_Load event procedure.

Before we can continue with the following coding, we first need to create a Code Module to hold our two global variables, comPort and baudRate. Because we created two Forms in this project, the Setup Form and VBSerialDLL Form, these two Forms need to share some variables to communicate to each other. So we need to create two global variables to hold the values of the port number and the baud rate, which are obtained from the Setup Form and entered by the user as the program runs. The VBSerialDLL Form also needs the values of these two variables to initialize the serial port.

Click Project|Add Module from the menu bar to open the Add Module dialog box. Keep the default Module selected, and click the Open button to open that Module. You will find that a new Module has been added to your project by checking the icons in the Project Explorer window. Right-click on that newly added Module, Module1, and select Save Module1 As. . . to open a dialog box. In the opened dialog box, browse to our user-defined project folder, C:vbdll, change Module1's name to VBSerial, and click Save to save this Module.

Double-click this newly created Module, VBSerial.bas, from the Project Explorer window to open it, and add the code shown in Figure 2-46 into this Module.

Two global variables, comPort and baudRate, are created here. Please note that if you want to create a global variable, use Public instead of Dim and place it in front of the variable. Because these two variables are both integer types in C/C++ and will be passed into the C/C++ domain, a Long data type is implemented for them.

Now, we need to write code for the OK command button. Select cmdOK from the Object list to open its event procedure. Enter the code shown in Figure 2-47 into this event procedure.

Now, click the VBSerialDLL icon from the Project Explorer window to open the second Form, VBSerialDLL. Click the View Code button to open its code window. First, we need to declare DLL functions that will be used in this Form and some of the Form's level variables, which are shown in Figure 2-48.

While still in the code window, click the Form item from the Object list to open the Form_Load event procedure, and enter the code shown in Figure 2-49 into this procedure.

Now, we need to write code for the Setup command button event procedure. The functionality of this event procedure is to call a DLL function to initialize the serial port with two parameters, comPort and baudRate. Also, the procedure needs to check the returned status of that DLL function to make sure that the function is executed successfully. An error message should be displayed on screen to warn the user if this function encountered any mistake and if the returned value was not equal to zero.

Click the cmdSetup item from the Object list to open the Setup event procedure, and enter the code shown in Figure 2-50.

The coding for the Test command button event procedure is very simple; that is, when the Test command button is clicked by the user, the flag sTest should be set, and this will tell the system that the current status of the program is testing. Click cmdTest from the Object list to open its event procedure and enter the code shown in Figure 2-51.

This flag is set to inform the Timer, VBSerialTimer, which was added when we built this Form. You will see that later from the Time event procedure. The Timer will check this flag periodically, and the check result will be used to determine what to do for the next step in the Timer event procedure.

Now, let's take a look at the Timer event procedure by clicking the VBSerialTimer item from the Object list to open its event procedure. Enter the code shown in Figure 2-52 into this event procedure.

Finally, we need to write code for the Exit command button event procedure. Click cmdExit from the Object list to open its event procedure. Enter the code shown in Figure 2-53 into this procedure.

At this point, we have finished developing a Visual Basic test project. Now let's test our project by pressing the F5 key from the keyboard. As your project runs, the first Form, Setup Form, is displayed on screen. Enter the setup parameters, comPort and baudRate, in the two textboxes, as shown in Figure 2-54.

In our application, the available port is COM1 and the baud rate we selected is 9600. You can select different parameters based on your system. Click the OK button to continue the project.

The second Form in our project, VBSerialDLL, is displayed on screen, as shown in Figure 2-55. You will find that the two parameters we entered in the last Form are displayed in the Port Setup information box. Click the Setup command button to call the DLL function Setup() to initialize the serial port with these two parameters. Then click the Test button to begin testing.

Random data will be created and sent to the serial port. That data is also displayed in the Sending Data textbox. The read-back data will be displayed in the bottom textbox labeled Reading Data. The interval between displaying these two data is about 500 ms or maybe a little longer. You should find that the sending-out data is identical to the reading-back data, which means that the serial port works fine and our testing is successful. The running result is shown in Figure 2-56.

Occasionally, an error message may be displayed to indicate that the testing for the serial port was not successful. This is understandable because a chance for error in the serial port application exists in the real world. Also, sometimes an error message doesn't mean that the error comes from the serial port itself; it may be introduced by some disturbance or magnetic field around the computer system. The chance of that kind of error, however, is very slight.

All files of this project, including DLL source files, header file, DEF file and DLL file, Visual Basic source files, Code Module, and executable file, are on the accompanying CD-ROM in the Chapter 2VBSerialDLL folder. You can copy these files onto your local machine and run them. You should copy the DLL file to a searchable folder on your system in order to run this project on your machine.

2.3.5. Call a DLL to Interface Multiple Tasks in Visual C++ 6.0

2.3.5.1. Functionality of the Multiple Tasks DLL Project

In this section, we want to show readers how to interface multiple tasks in the Visual C++ domain from within Visual Basic. To make things simple, we will develop a Visual C++ project that includes two threads. These two threads will run simultaneously in the Visual C++ domain, and a Visual Basic project will interface these two threads to perform a loop data collecting sequence. The communication or synchronization between two threads is handled by events, by either SetEvent() or ResetEvent() functions. The functional block diagram of this project is shown in Figure 2-57.

Two DLL functions work as interface functions to set up associated events based on the command sent from within Visual Basic. A vbSendEvent event will be set if the Send Data command is received by the DLL function SendData(); otherwise, the vbReadEvent event will be set if the Read Data command is received by the ReadData() DLL function.

The two threads work separately and communicate to each other by using events. A WaitForMultipleObjects() system function is placed in a While loop for each thread. This function waits for multiple objects to happen, including Exit, vbSendEvent, and vbReadEvent events. Thread I waits until either the Exit or vbSendEvent is signaled. If the Exit event is signaled, the program will exit the While loop and terminate Thread I. If the vbSendEvent is signaled, the program will call another wait function, WaitForSingleObject(), to wait until the ReadEvent is signaled (this event will be set by Thread II), which means that Thread II has finished picking up a data from the shared data buff (sdata) and is ready to pick up another data. When this situation occurs, Thread I will transfer the data sent out by Visual Basic to a shared data buff, sdata, and then set the event, SendEvent, to inform Thread II that a new data has been received from Visual Basic, and it has been stored into the shared data buff. Thread II can go ahead to pick it up. Then Thread I will continue to return to the While loop until another event happens. This loop runs infinitely until some event is signaled.

Similarly to Thread I, Thread II has an infinite While loop. A WaitForMultipleObjects() function waits for any event to happen, including Exit or vbReadEvent, which is signaled by the DLL function ReadData() when a Read Data command is sent out from Visual Basic and received by that DLL function. As this event is signaled, Thread II calls another wait function, WaitForSingleObject(), to wait until the SendEvent event is signaled, which should be signaled by Thread I when a data is ready. As this situation occurs, Thread II picks up the data from the shared data buff (sdata) and assigns this data to another data buff, rdata. Then Thread II will set ReadEvent to inform Thread I that Thread II has finished picking up that data, and it is ready to pick up the next one. If an Exit event is received, the program will exit the While loop and terminate Thread II. Otherwise, Thread II will continue to work in this infinite loop until some event happens.

In this way two threads work separately but communicate to each other by using the events, and interface with Visual Basic by using other events.

2.3.5.2. Develop a Multiple Tasks DLL in the Visual C++ Domain

Based on the working principle of this DLL, we will now open a Visual C++ 6.0 workspace and create a new project with type Win32 Dynamic-Link Library. Enter VBMultTask in the Project_name: field, and click OK to open this project.

Click File|New to create a new header file named VBMultTask.h, and enter the code shown in Figure 2-58 into this new header file.

Click File|New again to create a new C++ Source File named VBMultTask.cpp, and enter the code shown in Figure 2-59 into this new source file.

Before we can build our project, we need to create a DEF file to export our DLL functions. In the Visual C++ 6.0 workspace, create a new text file named VBMultTask.txt. Then click Project|Add To Project|Files. . . to open a dialog box. In the opened dialog box, find the newly created text file VBMultTask.txt and right-click it, select Rename from the pop-up menu, then rename the extension of this file to VBMultTask.def. Select this renamed file and click OK to add this file into our project. You can delete the original text file VBMultTask.txt by first selecting that file, and then clicking Edit|Delete from the menu bar.

Now, double-click the VBMultTask.def file to open it and enter the code shown in Figure 2-60 into this file.

Figure 2-60.

							LIBRARY VBMultTask.dll
							EXPORTS
							Init
							SendData
							ReadData
							Exit
						

Now click Build|Build VBMultTask.dll to build the project. Copy the resulting DLL file VBMultTask.dll to the user-defined dll directory C:stdll. At this point, we have finished developing a multiple-task DLL project.

2.3.5.3. Develop a Visual Basic Project to Call the Multiple Tasks DLL

The purpose of developing this Visual Basic project is to interface the DLL functions we developed earlier to test a multiple-task DLL project from within Visual Basic. This test project also confirms that Visual Basic is an Object-Oriented-Event-Driven-Programming language and it is useful for a multiple-task project. It is an especially good candidate to work in a multiple-task environment.

Open Visual Basic 6.0 and create a new Standard EXE project. Change the Form name from the default Form1 to VBMultTask.frm, and change the Project name from Project1 to VBMult.vbp. Save the Project and Form to our user-defined project directory, C:vbdll.

Add the following components to the new Form, VBMultTask.vbp; your resulting screen should look like that in Figure 2-61.

The purpose of the txtSend and txtRead textboxes is to display the sent-out and read-back data. The txtLoop textbox is used to receive the number of the loops when you want to perform a loop testing in this project. The purposes of the five command buttons are straightforward, and you have to first click the Initialize button to start this project.

Click the View Object button on the Project Explorer window to open the code window. Click the General item from the Object list to open the Form's General Declaration section, then enter the statement Option Explicit into this section.

Click Add-Ins from the menu bar to open the API Viewer, click File|Load Database File. . ., then browse and select the Win32 API database WIN32API.MDB from the opened dialog box to load this database to our project. Browse and select the Sleep API function from the Available Items list, and click Add to add this function to the Selected Items list box on the bottom of this Viewer. Make sure that the Private radio button is selected before you click the Add button to add this function. Click the Insert button to add this function to the project, inserting it into the Form's General Declaration section. Click Yes in the message box to confirm that we are sure we want to add this function to the project. Now, return to the code window and open the Form's General Declaration section by clicking the General item from the Object list, and enter the code shown in Figure 2-62 into this section.

Now, click the Form item from the Object list to open the Form_Load event procedure and add the initialization code shown in Figure 2-63 into this procedure.

Now, click the cmdInit item from the Object list to open its event procedure and enter the code shown in Figure 2-64 into this procedure.

After the initialization, we need to code the test section that will interface to the multiple-task DLL we developed in Visual C++. Click the cmdSend item from the Object list to open its event procedure. Enter the code shown in Figure 2-65 into this event procedure to finish the coding for this event.

Next, let's code for the cmdRead event procedure. The purpose of this event procedure is to call a DLL function ReadData() to pick up a data, which is sent out before by Visual Basic from the shared data buffer in the Visual C++ domain. This DLL function will set the vbReadEvent event to inform a WaitForMultipleObjects() system function in Thread II to begin to process to pick up the next data in Visual C++. Click the Object list and select the cmdRead item to open this event procedure. Enter the code shown in Figure 2-66 into this procedure.

The next procedure is the Loop test procedure. Recall that in the last example, a Timer is used to periodically send out and read back a random data to or from a serial port via a DLL developed in Visual C++. This Timer works just like a controller to coordinate between sending and reading data in the Visual Basic domain, which means the Timer will execute sending out a data and reading back a data alternately by using the CPU. In this example, we don't need the Timer; Visual Basic can talk directly to DLL functions to finish a similar functionality as in the previous example, because the DLL is developed in a multiple-task mode; Visual Basic can even call SendData() and ReadData() DLL functions simultaneously.

The Loop test is for this purpose. In the Code window, select the cmdLoop item from the Object list to open the cmdLoop event procedure, and enter the code shown in Figure 2-67 into this procedure.

Finally, we need to write code for the Exit command button. Select cmdExit from the Object list to open its event procedure. Enter the code shown in Figure 2-68 into this procedure.

Now everything is done and we can run our project. Press the F5 key on your keyboard to start the project, and the GUI will be displayed on screen, as shown in Figure 2-69.

You will notice that the Initialize button is the default button, because it is surrounded by a dashed line. If you click any button except Initialize, a message box will pop up to remind you to initialize the system, as shown in Figure 2-70(a).

Click the Initialize button to initialize the system. Then click the Send button to send a random data to the Visual C++ domain. The random data that is sent out will be displayed in the txtSend textbox. Click the Read button to pick up the data that is sent out; that data will be displayed in the txtRead textbox, as shown in Figure 2-69. By continuously clicking the Send and Read buttons, you can test and compare the sent-out data with the read-back data one by one.

Now we can do the loop test. Click the Loop button; a message box will be displayed on screen to ask you to enter a loop number. If you didn't enter a number in the Loop Number textbox you will get the error message, as shown in Figure 2-70(b). Now, enter a number, say, 30, and then click the Loop button again. This time you will find that the loop test runs and the sent-out data and read-back data are displayed in two textboxes alternately, as shown in Figure 2-71. The interval between displaying the two data is about 200 ms.

You can repeat the test by clicking the Send, Read, or Loop buttons. The result should be satisfactory. Now, click the Exit button if you want to terminate the project. That is all for this project. We have successfully developed a multiple-task DLL and have interfaced it with our Visual Basic project.

All files of this project, including the source files, header file, DEF file, and DLL file developed in Visual C++, and the source file, GUI file, and executable file developed in Visual Basic, are included on the accompanying CD-ROM in the Chapter 2VBMultTask folder. You can run this project directly by double-clicking the executable file VBMult.exe. But you need to copy the DLL file VBMultTask.dll to a searchable directory on your computer before you can run this project.