Windows Standard Serial Communications for Visual Basic Programmer's Manual

Windows Standard

Serial Communications

for Visual Basic

Programmer's Manual

TABLE OF CONTENTS

1 Introduction Page 3

1.1 Features Page 4

1.2 Documentation Set Page 6

1.3 Example Program Page 6

1.4 Installation Page 7

1.5 Uninstalling Page 7

1.6 Pricing Page 7

1.7 Updates Page 7

2 Library Overview Page 7

2.1 Dynamic Link Libraries Page 7

2.2 Keycode (License Key) Page 8

2.3 Dynamic Strings Page 8

2.4 Limitations on COM Ports Page 9

2.5 Win32 STDCALL and DECLSPEC Page 9

2.6 Waiting for New Serial Data Page 9

2.7 Using Threads Page 10

2.8 WSC Class Page 10

2.9 Using VB.Net Page 10

2.10 VBA Applications Page 10

2.11 PowerBuilder Page 10

2.12 Adding WSC4VB To A Project Page 11

2.13 Error Display Page 11

2.14 SioEvent Logic Page 11

2.15 Virtual Serial Ports Page 11

2.16 Using 16-bit Visual Basic Page 12

2.17 Visual Basic Problems Page 12

3 Compiler Issues Page 13

3.1 Visual Basic Makefiles Page 13

3.2 Compiling Example Programs Page 13

3.3 Compiling WSC Page 13

4 VB 3/4/5/6 Example Programs Page 14

4.1 WSCVER Page 14

4.2 EASY Page 14

4.3 SELFTEST Page 14

4.4 MODEM Page 14

4.5 TERM Page 15

4.6 FINDER Page 15

4.7 ATOK Page 15

4.8 DEVICE Page 15

4.9 MESSAGE Page 15

4.10 XMS, XMR, YMS, & YMR Page 15

4.11 PUTTYPE Page 15

5 VB.Net Example Programs  Page 16

5.1 WSCVER.VB Page 16

5.2 EASY.VB Page 16

5.3 SELFTEST.VB Page 16

5.4 XMS.VB & XMR.VB Page 16

6 Revision History Page 17

Introduction

The Windows Std Serial Communications Library (WSC4VB) is a component library of functions providing the capability to quickly write serial communication applications in Visual Basic or VB.NET. The WSC component library uses the standard Windows API (Application Programmer's Interface) to communicate with any device connected to a serial port.

A straight forward interface is provided to access data from a serial port using RS232 or multi-drop RS422 or RS485 ports. WSC also supports virtual serial ports using Bluetooth serial and USB to serial converters

Windows Std Serial Communications Library (WSC4VB) includes 20 VB and VB.NET example programs demonstrating serial communication functions that have been tested on multiple computers running Windows 95/98, Windows Me, Windows NT4, Windows 2000, Windows Vista and Windows XP. The WSC4VB library supports and has been tested with several Visual Basic compilers, from VB 3.0 through VB 6.0 and VB.Net. WSC can also be used with any VBA (Visual Basic for Applications) language such as Excel, Access, MS Office, etc.

Both Win16 and Win32 DLLs are provided. The WSC DLL's (WSC16.DLL and WSC32.DLL) can be used from any language (C/C++, Visual C++ .NET, ,NET, Visual C#, Visual FoxPro, Delphi (Delphi .NET), Visual FoxPro, Visual dBase, and Xbase++) capable of calling the Windows API.

MarshallSoft provides separate products for WIN/CE for eVB (WSC4eVB) and for eVC (WSC4eVC). Evaluation versions for each serial communication library may be downloaded from our web site at

https://www.marshallsoft.com/serial-communication-library.htm

Our goal is to provide a robust serial communication library component that you and your customers can depend upon. A fully functional evaluation version is available. Contact us if you have any questions.

When comparing the Windows Standard Serial Communications Library against our competition, note that:

WSC4VB is a standard Windows DLL (NOT an OCX or ActiveX control) and is much smaller than a comparable OCX or ActiveX control.

Both WIN16 and WIN32 DLLs are included.

WSC does NOT depend on ActiveX or Microsoft Foundation Class (MFC) libraries or similar 'support' libraries.

The WIN32 version of WSC is fully thread safe.

The WSC functions can be called from applications not capable of using controls.

MarshallSoft also has versions of the Windows Standard Serial Communications Library for Visual C/C++ (WSC4C), Delphi (WSC4D), PowerBASIC (WSC4PB), Visual FoxPro (WSC4FP), Visual dBASE (WSC4DB), and Xbase++ (WSC4XB). All versions of WSC use the same DLLs (WSC16.DLL or WSC32.DLL). However, the examples provided for each version are written in the specified computer environment. Development time is shortened because programmers need only learn one interface.

The latest versions of the Windows Standard Serial Communications Library (WSC) can be downloaded from our web site at

https://www.marshallsoft.com/serial-communication-library.htm

Features

Some of the many features of the Windows Serial Communications Library for Visual Basic (WSC4VB) are:

Can control any serial device connected to the serial port.

Can be used from GUI mode or console mode programs.

Can control up to 256 ports simultaneously.

Can be used with virtual serial ports using Bluetooth serial or a USB to serial converter.

Includes over 34 functions plus modem control.

Comes with ANSI emulation and ASCII, XMODEM and YMODEM.

Supports RS232, and multidrop RS422, and RS485 ports.

Supports hardware and software flow control.

Supports any baud rate (32-bit version).

Ability to specify the parity, word size, and number of stop bits.

Supports binary and text data transfer.

Is fully thread safe.

Supports Windows 95/98/Me/NT/2000/2003/XP/Vista.

Supports character peek (SioEventChar).

Implemented as a standard Windows DLL, which will work with all versions of Windows.

Can send Windows messages on completion of events (incoming character, etc.)

Includes 16-bit (WSC16.DLL) and 32-bit (WSC32.DLL) versions.

Supports all versions of Visual Basic, from V3.0 through VB.Net.

Can be used with Microsoft Visual .NET and Visual C# (Managed Code)

Can be used with Microsoft Foundation Class (MFC), and Borland C++ Builder programs.

Can be used with VBA (Visual Basic for Applications) such as Excel, Microsoft Office and Access.

Does not depend on support libraries. Makes calls to core Windows API functions only.

Can be used with any program (in any language) capable of calling Windows API functions such

as Visual C++, Visual C++ NET, Visual FoxPro, Delphi, Xbase++, dBASE, COBOL, Access and Excel.

Can be purchased with or without ANSI C source code to the WSC DLLs.

Purchase a developer license for WSC4C and use the DLLs with any other development environment (VB, Visual FoxPro, etc).

Updates are free for one year (updates to source code are separate).

Royalty free: there are no run-time fees.

The evaluation version is fully functional (60 day evaluation period).

Is compatible with "Managed Code".

A good selection of Visual Basic (and VB.Net) example programs with full source code is included. Refer to Section 5 for more details on each of the example programs.

WSCVER : Program that displays the WSC version number.

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).

DEVICE : Sends text string to serial device.

MESSAGE : Send Windows message when incoming bytes are detected.

XMS/XMR : XMODEM Send & XMODEM Receive programs.

YMS/YMR : YMODEM Send & YMODEM Receive programs.

PUTTYPE : Transmits user defined data type.

VERSION.VB VB.Net version of the WSC version program (WSCVER).

EASY.VB VB.Net version of the simple terminal program (EASY).

SELFTEST.VB VB.Net version of the COM port functionality program (SELFTEST).

XMS.VB VB.Net version of the XMODEM Send program (XMS).

XMR.VB VB.Net version of the XMODEM Receive program (XMR).

1.2 Documentation Set

The complete set of documentation consists of four manuals in three formats. This is the first manual (WSC_4VB) in the set.

WSC_4VB Programmer's Manual (WSC_4VB.DOC, WSC_4VB.TXT, WSC_4VB.HTM)

WSC User's Manual (WSC_USR.DOC, WSC_USR.TXT, WSC_USR.HTM)

WSC Reference Manual (WSC_REF.DOC, WSC_REF.TXT, WSC_REF.HTM)

Serial Comm User's Manual (SERIAL.DOC, SERIAL.TXT, SERIAL.HTM)

The WSC_4VB Programmer's Manual is the language specific (Visual Basic and VB.NET) manual. All language dependent programming issues are discussed in this manual. Information needed to compile your programs in a VB environment is provided in this manual.

The WSC User's Manual (WSC_USR) discusses language independent serial communications programming issues including modem control. Purchasing and license information is also provided.

The WSC Reference Manual (WSC_REF) contains details on each individual WSC function.

The Serial Communications User's Manual (SERIAL) contains background information on serial port hardware.

Each manual comes in three formats:

Microsoft Word (files ending in .DOC). The best format for printing manuals.

Hyper Text (files ending in .HTM). Use any web browser to read.

ASCII Text (files ending in .TXT).

The documentation is also provided on our web site at

https://www.marshallsoft.com/wsc4vb.htm

1.3 Example Program

The following example program segment sets DTR (Data Terminal Ready).

' pass the keycode (0 for evaluation version)

Code = SioKeyCode(WSC_KEY_CODE)

' open port COM1

Code = SioReset(COM1, 512, 512)

If Code < 0 Then

' process error

Call SayError(EXAMPLE, Code)

Call ShutDown

Exit Sub

End If

' set DTR

Code = SioDTR(COM1, ASC('S'))

Refer to section 5.0 for complete examples with source.

1.4 Installation

(1) Before installation of WSC4VB, your Visual Basic compiler should already be installed on your system and tested. Note that Visual Basic 4.0 or above is required in order to create Win32 programs.

(2) Unzip WSC4VB43.ZIP (or WSC4VB.ZIP for registered users) using any Windows unzip program.

(3) Run the installation program SETUP.EXE which will install all WSC4VB files, including copying WSC16.DLL and WSC32.DLL to your Windows directory. No Windows system files are modified. Note that no DLL registration is required.

WSC4VB comes configured for 32-bit Visual Basic (VB4 and above). Before compiling for 16-bit Visual Basic (VB3 & 16-bit VB4), you must first run READY16.BAT in the APPS directory as described in Section 3.5.

1.5 Uninstalling

Uninstalling WSC4VB is very easy. WSC4VB does NOT modify the registry. First, delete the WSC4VB project directory created when installing WSC4VB. Second, delete WSC16.DLL and WSC32.DLL from your Windows directory, typically C:WINDOWS for Windows 95/98/Me/XP or C:WINNT for Windows NT/2000.

1.6 Pricing

A developer license for WSC4VBcan be registered for $115 (or $195 with ANSI C source code to the library DLL's). Purchasing details can be found in Section 1.3 'How to Purchase' in the WSC User's Manual (WSC_USR.HTM). Also see INVOICE.TXT provided with the evaluation person or order directly on our web site at

https://www.marshallsoft.com/order.htm

1.7 Updates

When a developer license is purchased for WSC4VB, the developer will received a new a set of registered DLLs plus a license file (WSCxxxx.LIC). The license file is needed to download updates to the registered DLL's for a period of one year from purchase. Updates can be downloaded from

https://www.marshallsoft.com/oem.htm

After one year, your license must be updated if you want to be able to download updates. Your license can be updated for :

$30 if the update is ordered within one year of the original purchase (or previous update).

$55 if the update is ordered between one and three years of the original purchase.

$75 if the update is ordered after three years of the original purchase.

If source code was previously purchased, updates to the source code can be purchased for $50 along with the DLL update. Note that the registered DLL's never expire.

2 Library Overview

The Windows Standard Serial Communications Library (WSC) has been tested on multiple computers running Windows 95/98/Me/XP/Vista, and Windows NT/2000.

The WSC4VB library has also been tested with several Visual Basic compilers, from VB 3.0 through VB 6.0 and VB.Net. WSC can also be used with any VBA language such as Excel, Access, MS Office as well as PowerBuilder.

2.1 Dynamic Link Libraries

The WSC4VB serial communication library component includes both Win16 and Win32 dynamic link libraries (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 that 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 Operating System, they will not be replaced by a 'newer technology'.

2.2 Keycode

WSC16.DLL and WSC32.DLL each has a keycode encoded within them. Your keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.BAS and KEYCODE.VB. The keycode for the evaluation (shareware) version is 0. You will receive a new keycode and a set of new DLL's when registering. The KEYCODE is passed to SioKeyCode.

If you get an error message (value -108) when calling SioKeyCode, it means that the keycode in your application does not match the keycode in the DLL. After registering, it is best to remove the evaluation version of the WSC32.DLL and WSC16.DLL from the Windows search path or delete them.

2.3 Dynamic Strings

The Visual Basic language uses a technique known as 'garbage collection' to manage string space at runtime and may be called internally at any time by the Visual Basic runtime, asynchronous to what you may be doing in your code.

When passing a string buffer to a DLL function into which text will be copied, it is strongly recommended that the local string be allocated immediately before use. For example, a string buffer is passed to the user defined dllGetMessage function , which copies a text message into it. Note that SPACE$(80) is called immediately before dllGetMessage.

Dim Code As Integer

Dim Buffer As String * 80

' allocate buffer just before call to dllGetMessage

Buffer = SPACE$(80)

' copy message into 'Buffer'

Code = dllGetMessage(Buffer, 80)

' message text is now in 'Buffer'

This technique is not necessary for passing a string to a DLL function, only when passing a buffer to a DLL into which data is to be placed by the DLL function.

2.4 Limitations on COM Ports

The 32-bit version of WSC4VB (WSC32.DLL) can use any port from COM1 to COM256, provided that the port is known to Windows 95/98/NT/2000/Me/XP/Vista and there is physical hardware present.

2.5 Win32 STDCALL and DECLSPEC

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 are neither leading underscores nor trailing '@size' strings 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.

2.6 Waiting for New Serial Data

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, all out going serial data is moved to the transmit queue in memory.

There are several methods that can be used to wait for new incoming serial data, as follows:

2.6.1 Polling Method: For Win16 (VB 3) and Win32 programs (including VB.NET).

The most straightforward method is to use a VB timer to check every so often. The timer interval should be set between 50 milliseconds and 250 milliseconds. Setting it much less than 50 milliseconds would consume considerable system resources polling, and setting it greater than 250 milliseconds will result in sluggish menu response times. A good compromise is to set the timer interval to 125 milliseconds.

2.6.2 Message Method: For Win32 programs (VB 4 and above).

The "Message Method" is probably the most natural method to use with Visual Basic (recall that WSC works with many different computer languages). In this method, the SioMessage function is called which sends a Windows message to a VB button when new data is ready to be read.

2.6.3 Event Method: For Win32 programs (VB 5).

This method uses SioEvent in a thread (background process) which blocks (efficiently waits) until new data is available. This method requires creating a thread in VB. However, although it is possible to create a thread in VB5, it is not recommended since VB5 is not thread safe.

2.6.4 EventWait Method: For Win32 programs (VB 4 and above, including VB.NET).

This method uses the SioEventWait function in a timer procedure to block (efficiently wait) until new data is available or until the timer period expires. A good choice for the timer interval is 250 milliseconds because it allows quick response to user input and also at the same time minimizes polling. Note that a 250 millisecond interval represents quite a large interval of CPU time.

2.7 Using Threads

The Windows Standard Serial Communications Library for Visual Basic (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 5.

The necessary Win32 thread functions are declared in the file SYSTEM32.BAS.

2.8 WSC Class

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

2.9 VB.Net

There are a few differences between VB 4/5/6 and VB.NET that affect writing programs that use WSC.

(1) Variables that are declared "As Long" in VB 4/5/6 are declared "As Integer" in VB.Net.

(2) Fixed length strings are not supported in VB.Net. When calling any WSC function that can return a string (SioGets, SioPuts, and SioWinError), memory for the string variable must be allocated first. For example:

Buffer = Space(80) ' allocate memory for 'Buffer'

Code = SioWinError(Buffer, 80)

(3) Some VB functions must be fully qualified. For example, instead of LEFT, use Microsoft.VisualBasic.Left

(4) The module WSC32.VB (not WSC32.BAS) must be included in all VB.Net programs.

2.10 VBA Applications

WSC can be used with Microsoft VBA (Visual Basic for Applications) applications such as EXCEL, ACCESS, and Microsoft Office. Note that WSC16.DLL must be used for 16-bit applications, even if running under Windows 95/98/Me or NT/2000. See the file VBA32.TXTas well as EXCEL.TXT, ACCESS.TXT and WORD.TXT in the DOCS directory for more information.

2.11 PowerBuilder

WSC can also be used with Power Builder applications. See PBUILDER.TXT for more information.

WSC.PBI : Power Builder declaration file.

2.12 Adding WSC4VB to Your Project

Copy WSC16.BAS (if running VB 3.0 or 16-bit VB 4.0), WSC32.BAS (if running VB 4/5/6), or

WSC32.VB (if running VB.Net) to the same directory (folder) as the application program to which you want to add WSC code. You will find these files in the APPS directory (folder) created when you ran SETUP, usually C:WSC4VBAPPS.

2.12.1 Adding WSC4VB to your VB 3.0 Project

Open your existing project with 'File', 'Open Project'. Then choose 'File', 'Add File', then add WSC16.BAS and KEYCODE.BAS to your project. WSC functions can now be called from your Visual Basic program.

2.12.2 Adding WSC4VB to your VB 4.0, 5.0, or 6.0 Project

Open your existing project with 'File', 'Open Project'. Then choose 'Insert', 'Module', then add WSC32.BAS and KEYCODE.BAS to your project. If prompted to add 'DAO 2.50 Object Library', choose 'no'.

WSC functions can now be called from your VB program.

2.12.3 Adding WSC4VB to your VB.Net Project

Open your existing project with 'File', 'Open Project'. Then choose 'Project', 'Add Module', then add WSC32.VB and KEYCODE.VB to your project. WSC functions can now be called from your VB.NET program.

2.13 Error Display

The error message text associated with WSC error codes can be displayed by calling SioError (refer to sioerror.c and paint.c) in GUI mode applications or SayError (see SayError.c) in console mode applications. Each sample program contains examples of error processing.

2.14 SioEvent Logic

SioEvent, SioEventChar, and SioEventWait will block until the specified event occurs. If a call to SioEvent, SioEventChar, or SioEventWait is placed in a thread, then the thread will block but the application calling the thread will not.

See the Event.c, EventChar.c, and EventWait.c example programs.

2.15 Virtual Serial Ports

A "virtual" serial port is COM port that appears to be a real RS232 serial port to the Windows API (and thus to WSC), but is in reality a COM port emulator.

The two most common virtual ports are those created for USB/serial port converters and Blue Tooth.

WSC will work with most USB to serial port converts and with Bluetooth serial.

More information about Virtual serial ports can be found in Section 2.12 of the WSC User's Manual (WSC_USR).  (https://www.marshallsoft.com/wsc_usr.htm#Section_2.12

2.16 Using 16-bit Visual Basic

WSC4VB comes configured for 32-bit Visual Basic (32-bit VB4 and up). Before compiling for 16-bit Visual Basic (VB3 & 16-bit VB4), you must run READY16.BAT in the APPS directory, which performs the following copies:

COPY WSC16.BAS WSC4VB.BAS

COPY XYM16.BAS XYM.BAS

COPY ASD16.BAS ASD.BAS

COPY MIO16.BAS MIO.BAS

COPY ERRORS16.BAS ERRORS.BAS

There is also a READY32.BAT to copy 32-bit versions of the above, although WSC4VB is already configured for 32-bit Visual Basic.

2.17 Visual Basic Problems

If you terminate your program when running inside the Visual Basic environment, and you do not call SioDone first, you will leave VB itself with an open handle to your COM port. When you run again, you will get an 'ACCESS DENIED' error and you must re-start VB itself.

Also refer to Section 7 'Resolving Problems' in the User's Manual (WSC_USR.DOC, WSC_USR.HTM or online at https://www.marshallsoft.com/wsc_usr.htm#Section_7).

3 Compiler Issues

The Windows Serial Communications Library for Visual Basic component library supports and has been tested with all versions of Microsoft Visual Basic (VB3, VB 4, VB 5, VB 6 and VB.NET).

3.1 Visual Basic Makefiles

The first Visual Basic for Windows (version 3.0) uses a text file known as a 'Visual Basic makefile' (.MAK) to list all the file components necessary to compile a program. Beginning in version 4.0, the 'Visual Basic Project file' (.VBP) was added. Both formats are 'project files'.

3.2 Compiling Example Programs

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.

Visual Basic project files (*.VBP) are provided for example programs that require VB 5.0 or 6.0.

The example programs can be compiled from the Visual Basic development environment using the provided Visual Basic makefiles. Choose 'File', then 'Open Project' from the main VB menu.

The example program code is stored in VB 3.0 (WIN16) and VB 4.0 (WIN32) formats. All 16-bit project files end in '16.MAK' (e.g.: WSCVER16.MAK) while 32-bit project files end with '32.VBP' (e.g.: WSCVER32.VBP). All 32-bit versions of VB (VB4 and above) can open files stored in VB4 format.

When saving the example programs in VB version 5.0 or VB 6.0 format, answer 'no' if asked to add the 'Microsoft DAO v2.5 library'.

Compile and run WSCVER16 (or WSCVER32) as the first example.

3.3 Compiling WSC

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 (ANSI C) for the WSC library is provided in the registered version (if ordered) only.

For more information on the C/C++ version of WSC, download the latest version of WSC4C from our web site at https://www.marshallsoft.com/wsc4c.htm

4 VB 4/5/6 Example Programs

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 Microsoft Visual Basic. However, some require VB 4.0 or above (MESSAGE) while others require VB 5.0 or above (ATOK and THREAD). Before compiling with 16-bit Visual Basic (VB3 and 16-bit VB4), run READY16.BAT. All example programs are located in the APPS directory.

4.1 WSCVER

The WSCVER ('WSC Version') example program displays the WSC version number. This is the first program to compile and build since it verifies that WSC32.DLL (or WSC16.DLL) is installed properly. Use this with Visual Basic 3/4/5/6. The VB.NET version, WSCVER.VB is Section 5.1

4.2 EASY

EASY is a very simple communications program demonstrating basic serial communications functions. Everything that is typed on the keyboard is sent to the serial port, and everything 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.

Use this example with Visual Basic 3/4/5/6. The VB.NET version, EASY.VB is Section 5.2

4.3 SELFTEST

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.

Use this with Visual Basic 3/4/5/6. The VB.NET version, SELFTEST.VB is in Section 5.3

Refer to LOOPBACK.TXT in the DOCS directory for an explanation of how to make a loopback adapter (without tools!).

4.4 MODEM

MODEM is similar 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).

4.5 TERM

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, ASD.DLL for the ASCII protocol, and the XYM.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. Refer to TERM.TXT for more information.

4.6 FINDER

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.

4.7 ATOK

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

4.8 DEVICE

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.

4.9 MESSAGE

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.

4.10 XMS, XMR, YMS, & YMR

The XMS (XMODEM Send) and XMR (XMODEM Receive) programs are standalone programs which implement the XMODEM protocol. The YMS (YMODEM Send) and YMR (YMODEM Receive) programs are standalone programs that implement the YMODEM protocol.

4.11 PUTTYPE

The PUTTYPE example program demonstrates how to send user defined data across a serial port. Edit it as necessary before compiling. Use this with Visual Basic 3/4/5/6. The VB.NET version, XMS.VB & XMR.VB is in Section 5.4
5 VB.Net Examples

Before building the Microsoft Visual Basic .NET (VB.NET) examples, be sure to read Section 2.9 "Using VB.Net" above.

5.1 WSCVER.VB

This is the VB.Net equivalent of the VB 3/4/5/6 WSCVER example program in Section 4.1 above. The WSCVER example program displays the WSC version number.

Open the VB.Net project file wscver.vbproj

5.2 EASY.VB

This is the VB.Net equivalent of the VB 3/4/5/6 EASY example program in Section 4.2 above. The EASY example program is a simple terminal program. Everything typed at the keyboard is sent out the serial port, and everything incoming from the serial port is displayed on the screen.

Open the VB.Net project file easy.vbproj

5.3 SELFTEST.VB

This is the VB.Net equivalent of the VB 3/4/5/6 SELFTEST example program in Section 4.3 above. The SELFTEST example program tests a serial port by connecting the serial port to be tested to a loopback adapter (easily made - see LOOPBACK.TXT) or to a modem.

Open the VB.Net project file selftest.vbproj

5.4 XMS.VB & XMR.VB

This is the VB.Net equivalent of the VB 3/4/5/6 XMS and XMR example programs in Section 4.11 above. XMS sends a file to the receiver such as XMR using the XMODEM protocol.

Open the VB.Net project file xms.vbproj for XMODEM/send.

Open the VB.Net project file xmr.vbproj for XMODEM/receive.

6 Revision History

NOTE: Version 2.0 was the first Visual Basic version.

Version 2.0: February 17, 1997.

Includes Win16 and Win32 libraries.

Added XMODEM & YMODEM DLL (XYDRV.DLL).

Added TERM example program.

Version 2.1: June 9, 1997.

Screen display uses MEMO class.

WIN32 version can display error text from Win32 Windows.

Added FIND example program.

Added SioRead function.

SioInfo can return seconds to expiration [SHAREWARE].

Version 2.2: November 1, 1997.

XYDRV code fixes bugs.

Added xyGetFileName function to XYDRV.

Supports up to 16 ports.

WSC4VB runs under Windows NT.

Added ASCII protocol (ASDRV).

Version 2.3: August 14, 1998

Improvements to XYDRIVER (XMODEM and YMODEM).

SioTimer function added.

SioBaud and SioParms can be called before SioReset.

Declaration files for Power Builder added.

Version 2.4: June 1, 1999

Improvements made to XYDRIVER (XMODEM and YMODEM).

Added SioEvent function (Win32 only).

WSC Class added (VB 5.0 & up)

Added ATOK example program (VB 5.0 & up).

Version 3.0: July 26, 2000

Increased default to 32 ports.

Added several new example programs (WSCVER, THREAD, DEVICE).

Added WORD and HTML documentation.

Added SioMessage function.

Version 3.1: May 1, 2001.

RESETDEV Win API call not called (allows USB/serial converters).

SioPutc and SioPuts return immediately.

New example programs (XMS, XMR, YMS, YMR, PUTTYPE).

XYM (XMODEM/YMODEM) allows local upload/download directory to be specified.

Version 3.2: July 30, 2002.

Added support for VB.Net

Default for RESETDEV is 'not called'. SioDebug(ASC("R")') to enable.

SioGetc & SioGets zero unused bits (DataBits 5,6,7).

Corrected problem with SioBaud(-1, BaudRateCode).

SioDebug returns -1 if no match.

Added SioDebug(ASC("W")) toggle SioPuts wait for I/O completion.

Added code to detect active threads & to close thread handles.

Added USE_THREADS, so can compile version of WSC32.C without threads.

Comm handle not saved in SioReset unless it is good.

SioEvent returns mask that caused the event.

Added SioInfo(ASC("B")) to get build number.

Version 4.0: November 21, 2003.

Can now order either with or without source code to the DLLs.

Added SioSetInteger function to set port specific integer parameters.

Added SioKeyCode function to pass the key code to the DLL.

Added SioGetReg function to return the registration string.

Added 'Burst Size' parameter for setting the TX burst size.

Added ability to signal blocked thread which was blocked by SioEvent.

Version 4.1: August 12, 2004

Fixed problem with SioTxClear.

Added overlapped I/O (for non-Win95) so can signal threads to exit w/o killing them.

Increased default burst size to 256.

SioFlow returns WSC_RANGE if cannot recognize parameter.

Adjusted XModem/YModem timing for faster transfers.

Version 4.2: February 21, 2006.

SioFlow returns 1 if OK.

SioSetInteger(Port, 'S', 1) always forces SioEvent to unblock.

Event mutex code added to EventThread() to prevent race conditions.

Message box displays error if SioWinError(Buffer, 0) called.

Major change in overlapped I/O

Fixed problem: SioEvent returning wrong code.

SioRxClear clears byte saved by SioUnGet.

Number of supported ports increased to a maximum of 256.

Added SioEventChar() and SioEventWait() functions.

Version 4.3: September 27, 2007.

Fixed problem with SioTxQue returning wrong values.

Changed SioParms so it checks the range of passed arguments.

Port is verified in SioEventChar.

SioStatus returns -1 if port is not functioning (USB/serial port disconnected).

Added SioByteToShort and SioShortToByte (WSC32 only) to handle Unicode ASCII..

[END]