Windows Standard
Serial Communications
for Visual Basic
Programmer's Manual
(WSC_4VB)
Version 3.0
July 26, 2000
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2000
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 256-881-4630
FAX : 256-880-0925
email : info@marshallsoft.com
web : www.marshallsoft.com
MarshallSoft is a member of the Association of Shareware Professionals
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1 Introduction
1.1 Documentation Set2 Library Overview
1.2 Example Program
1.3 Installation
1.4 Uninstalling
1.5 Limitations on COM Ports
1.6 Ordering
1.7 Updates
1.8 Awards
2.1 Dynamic Link Libraries3 Compiler Issues
2.2 Using the Library
2.3 Win32 STDCALL and DECLSPEC
2.4 Using Threads
2.5 WSC Class
2.6 Using the VB Timer
3.1 Compiling WSC4 Example Programs
3.2 Compiling Example Programs
3.3 VBA Applications
3.4 Power Builder
4.1 WSCVER5 Revision History
4.2 EASY
4.3 SELFTEST
4.4 MODEM
4.5 TERM
4.6 FINDER
4.7 ATOK
4.8 THREAD
4.9 DEVICE
4.10 MESSAGE
The Windows Standard Serial Communications Library for Visual Basic (WSC4VB) is an asynchronous communications dynamic link library (DLL) which uses the standard Windows serial communications API. Since it uses the Windows API, programs using the WSC library are fully compatible with other Window applications which also use the Windows serial communications API.
The WSC4VB dynamic link libraries (WSC16.DLL and WSC32.DLL) can be called from any Windows application capable of calling Windows API functions, including those written in Visual Basic, Delphi, MS Access, MS Excel, Fortran, COBOL, PowerBuilder, FoxPro, Power Basic Console Compiler, dBase, Xbase++, etc. The library works under NT/2000 and Windows 95/98, as well as Windows 3.1 (Win16 only).
Using WSC is very straight-forward. For example, to write "AT" followed by a carriage return to serial port COM1:
Dim Text As String Dim Code As Long Text = "AT" + Chr$(13) Code = SioReset(COM1,512,512) 'open COM1 with 512 KB buffers Code = SioPuts(COM1,Text,3) 'write "AT" plus CR to COM1 Code = SioDone(COM1) 'close COM1
Several Visual Basic example programs with full source code are included. Refer to Chapter 4 for more details on each of the example programs.
EASY : A simple terminal emulator program. SELFTEST : Performs COM port functionality testing. MODEM : Same as EASY but controls flow control, modem lines, etc. TERM : Terminal emulator with XMODEM, YMODEM, and ANSI support. FINDER : Finds a modem connected to one of the serial ports. ATOK : Sends "AT" to modem, uses WSC class (WscClass.cls). THREAD : Similar to EASY but uses Win32 thread. DEVICE : Sends text string to serial device.WSC4VB contains 28 functions. All functions return a negative number if an error condition is detected. For more details, consult the WSC4VB Reference Manual (WSC_REF) and the RS232/485 Serial Communications Users Manual (ASYNC.TXT). Our goal is to provide a robust serial communications library that you and your customers can depend upon. Contact us if you have any questions. The shareware and registered versions are identical except that the shareware version displays the "shareware" screen when first starting, after 20 minutes of run time, and every 10 minutes after that. The registered version also includes source code.
Each manual comes in three formats:
The following example program displays the WSC version number.
Dim Version As Integer Dim A, B, C As String Version = SioInfo(Asc("V")) C = Hex$(&HF And Version) Version = Version / 16 B = Hex$(&HF And Version) Version = Version / 16 A = Hex$(&HF And Version) If SioInfo(Asc("3")) Then Print "Win32 WSC Version " + A + "." + B + "." + C Else Print "Win16 WSC Version " + A + "." + B + "." + C End If Print
MKDIR WSC4VB PKUNZIP WSC4VB30.ZIP WSC
Note: PKZIP for Windows and WINZIP can also be used to unzip.
INSTALL 16 'for Windows 95/98/NT/2000 or Windows 3.1 If you are using 32-bit Visual Basic 4 (or above), then type: INSTALL 32 'for Windows 95/98/NT/2000The install program creates WSC4VB.BAS from either WSC16.BAS or WSC32.BAS, and copies the proper DLLs. This way, the source code for the example programs is identical for both Visual Basic 3 (Win16) and Visual Basic 4 and above (Win32). INSTALL will copy all DLLs to the C:\WINDOWS directory (or C:\WINNT if running Windows NT/2000), where Visual Basic can find them.
http://www.hotfiles.com
WSC4VB includes both Win16 and a Win32 dynamic link library (DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to the traditional static library which is bound to each and every application that uses it at link time.
An important advantage that DLLs have over other "popular" library formats such as VBX or OCX is that DLLs are callable by all Windows applications. Since DLLs are the building blocks of the Windows Operations System, they will not be replaced by a "newer technology".
The WSC4VB has been tested on multiple computers running Windows 3.1, Windows 95/98, Windows NT (version 4.0), and Windows 2000.
The WSC4VB library has also been tested with several Visual Basic compilers, including Microsoft Visual Basic v7.0 (from the Windows SDK), Microsoft Visual Visual Basic, Borland Visual Basic , Borland C++ Builder, Turbo Visual Basic for Windows, and Watcom Visual Basic.
WSC32 is written in ANSI C and is compiled using the _stdcall and _declspec keywords. This means that WSC4VB uses the same calling conventions and file naming conventions as the Win32 API. In particular, function names are NOT decorated. There is no leading underscore nor trailing "@size" added to function names.
The WSC32.DLL functions may be called by any Windows application program capable of calling the Windows API provided the proper declaration file is used.
WSC4VB is thread safe, and can be used from any Windows application capable of using threads.
The "AddressOf" operator, which was added to Visual Basic beginning in version 5.0, is required in order to create and run Win32 threads in Visual Basic. Refer to the THREAD example program.
The necessary Win32 thread functions are declared in the file SYSTEM32.BAS.
The WSC class "wscClass" (wscClass.cls) is a Visual Basic class wrapper for making calls to WSC32.DLL. The class name for each function is the same as the DLL function, except the leading "wsc" is replaced by "f".
Those functions that return strings do so by use of the "String Result" property. Instantiate wscClass as any other class in VB:
Dim X As New wscClass
Classes were added to Visual Basic beginning with version 5.0, and are required in order to compile wscClass.
Refer to the ATOK example project for an example of using wscClass.
All serial data is moved from the UART's buffer to the receive queue in memory (by the Windows serial port driver) under interrupt control. Similarly for all out going serial data.
Hovever, most of the example programs use the VB timer in order to check the receive queue. For example, in the EASY example program, the timer interval is set to 125. Thus, every 125 milliseonds the timer code will execute and all available serial data (if any) will be copied from the receive queue.
In practice, there is very little overhead to using a timer provided the timer interval is not set too low. The use of timers in VB can avoided by using thread as described in sectin 2.4.
Each of the example programs should be compiled and run. Before beginning, be sure to run INSTALL that will copy the proper Win16 (or Win32) files.
Refer to Section 4.0 "Example Programs" for more information on the example programs.
WSC32.DLL is written in standard ANSI C (WSC32.C), and has been compiled using Microsoft Visual C/C++ with the STDCALL and DECLSPEC compiler keywords. Source code for the WSC library is provided in the registered version only.
WSC32.C may also be compiled using Borland C/C++ or Watcom C/C++ compilers. If you recompile WSC32.C using Borland or Watcom compilers, the resulting WSC32.DLL can only be used by applications compiled with the same compiler, unless the "_stdcall" and "_declspec" keywords are specified.
For more information on the C/C++ version of WSC, download the latest version of WSC4C from our web site at www.marshallsoft.com.
Visual Basic MAK files are provided with most example programs. Most example source code is saved in Visual Basic 3.0 format so that it can be read by all versions of Visual Basic.
WSC can be used with Microsoft VBA (Visual Basic for Applications) applications such as EXCEL, ACCESS, and WORD. Note that WSC16.DLL must be used for 16-bit applications, even if running under Windows 95/98 or NT/2000. See EXCEL.TXT, ACCESS.TXT, and WORD.TXT for more information.
WSC can also be used with Power Builder applications. See PBUILDER.TXT for more information.
WSC.PBI : Power Builder declaration file.
The example programs are designed to demonstrate the various capabilities of WSC4VB. The best way to become familiar with WSC4VB is to study and run the example programs.
Most of the example programs can be compiled with any version of Visual Basic. However, some require VB 4.0 or above (MESSAGE) while others require VB 5.0 or above (ATOK and THREAD).
The WSCVER ("WSC Version") example program displays the WSC version number. This is the first program to compile and build since it versifies that WSC32.DLL (or WSC16.DLL) is installed properly.
EASY is a very simple communications program using WSC4VB. Everything that is typed on the keyboard is sent to the serial port, and everthing incoming from the serial port is displayed on the screen.
The easiest way to test EASY is to connect to a modem. Typing 'AT' should result in an 'OK' being displayed.
A null-modem cable can also be used to connect two computers together with their serial ports. Run EASY on both machines. Whatever is typed on one machine will be displayed on the other.
SELFTEST performs a serial port I/O functionality test. Either a pair of ports on the same computer (using a null modem cable) or a single port (using a loopback adapter) can be tested.
Refer to LOOPBACK.TXT for an explanation of how to make a loopback adapter (without tools!).
MODEM is similiar to EASY, but with enhanced capability. It can set flow control (hardware, software, or none), DTR line (set or clear), RTS line (set or clear), display the transmit and receive queue sizes, detect a break signal, detect changes in DSR and CTS, as well as check for various line errors (parity error, framing error, data overrun, receive queue overflow, and transmit buffer full).
TERM is a simple terminal emulator suitable for calling up a BBS and downloading or uploading files using XMODEM or YMODEM. The TERM program uses MIO.DLL for modem control commands, ASDRV.DLL for the ASCII protocol, and the XYDRV.DLL for XMODEM & YMODEM protocol.
Selecting 'Dial' from the menu bar will result in a pop-up dialog requesting the phone number to dial. Once entered, the number is dialed, and the program will wait for up to 60 seconds for the 'CONNECT' string from the modem. This wait can be terminated at any time by choosing 'BREAK' on the menu bar.
Once logged on, files can be uploaded or downloaded by selecting 'Send' or 'Receive' from the menu bar. To abort a file transfer, choose 'BREAK' from the menu bar then type a series of Ctrl-X (^X) characters from the keyboard.
The FINDER program searches for a connected modem. Your modem must be connected to one of COM1, COM2, COM3, or COM4, and must be turned on.
FINDER takes no arguments. After connecting your modem to one of your serial ports,
type
FINDER
The ATOK program demonstrates the use of the Visual Basic class "wscClass.cls". The program transmits an "AT" to the serial port, and receives the response. If the serial port is connected to a modem, sending an "AT" should result in "OK" being received and displayed.
The ATOK program uses classes, which were added to Visual Basic beginning with version 5.0
The THREAD example program is similar to EASY, except that it uses a Win32 thread. This requires the Visual Basic "AddressOf" operator, which was added to Visual Basic beginning in version 5.0.
Note that the Visual Basic thread function (see THREAD_F.BAS) blocks awaiting serial input.
The DEVICE example program is designed to send a text string to a serial device. A carriage return is appended to the end of the string.
The DEVICE program can be used to send commands to serial devices which use ASCII commands, such as bar code readers, XY-plotters, etc.
The MESSAGE program is similar to EASY, except that rather than using a timer as in EASY, it uses the SioMessage function to request that WSC send a "Left Button Down" Windows message whenever any new serial data is available.
The MESSAGE example program requires Visual Basic 4.0 or above.
NOTE: Version 2.0 was the first Visual Basic version.
Version 2.0: February 17, 1997.
Version 2.1: June 9, 1997.
Version 2.2: November 1, 1997.
Version 2.3: August 14, 1998
Version 2.4: June 1, 1999
Version 3.0: July 26, 2000