1 Introduction

1.1 Features
1.2 Documentation Set
1.3 Example Program
1.4 Installation
1.5 Uninstalling
1.6 Pricing
1.7 Updates
1.8 Keycode

2 Library Overview

2.1 Dynamic Link Libraries
2.2 Keycode
2.3 Limitations on COM Ports
2.4 INCLUDE Files
2.5 Virtual Serial Ports
2.6 Dynamic Strings
2.7 Null Terminated Strings
2.8 Win32 STDCALL and DECLSPEC
2.9 Waiting for New Serial Data
2.10 Error Display
2.11 SioEvent Logic

3 Compiler Issues

3.1 dBase 5.6 and 5.7
3.2 dBase 7.0 and above
3.3 Compiling dBase Programs
3.4 Compiling dBase Projects
3.5 Compiling to an Executable

4 Example Programs

4.1 WSCVER
4.2 SIMPLE
4.3 SIMPLE2
4.4 XMS and XMS
4.5 YMS and YMR
4.6 FINDER
4.7 DIALER
4.8 DEVICE
4.9 ATOK
4.10 SELFTEST

5 Revision History

1 Introduction

The Windows Standard Serial Communications Library for dBASE (WSC4DB) is a component library of functions providing the capability to quickly write serial communication applications in dBASE. The WSC component library uses the standard Windows API (Application Programmer's Interface) to communicate with any device connected to a serial port.

A straightforward 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.

The Windows Standard Serial Communications Library for dBASE (WSC4DB) supports both Win16 (dBASE 5.5 and 5.7) and Win32 (dBASE 7.0, 7.5 and dBASE Plus) versions of dBASE. WSC4DB includes numerous dBase example programs that demonstrate serial port communications to help software developers easily build software applications using the WSC SDK.

WSC has been tested on multiple computers running Windows 95/98, Windows Me, Windows NT4, Windows 2000, Windows XP and Windows Vista. Two dynamic link libraries (WSC16.DLL for dBASE 5.6/5.7 and WSC32.DLL for dBase 7.X and dBASE Plus) are provided. The WSC DLL's can be used from any language (C/C++, Visual C++ .NET, Visual C#, Visual FoxPro, Visual Basic, VB.NET, Visual FoxPro, Delphi, Visual dBase, and Xbase++) capable of calling the Windows API.

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

1. WSC4DB is a standard Windows DLL (NOT an OCX or ActiveX control) and is much smaller than a comparable OCX or ActiveX control.
2. Both WIN16 and WIN32 DLLs are included.
3. WSC does NOT depend on ActiveX or Microsoft Foundation Class (MFC) libraries or similar "support" libraries.
4. The WIN32 version of WSC is fully thread safe.
5. 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 Basic (WSC4VB), 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 in multi-language projects 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 http://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.

1.1 Features

Some of the many features of the Windows Serial Communications Library 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 an USB-to-serial converter.
• Includes over 34 functions plus modem control.
• Comes with ANSI emulation and ASCII, XMODEM and YMODEM.
• Supports RS232, 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 dBASE (V5.7 through V7.0) and dBASE Plus.
• 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++, Visual Basic, VB.NET, COBOL, Access and Excel.
• Can be purchased with or without source code.
• 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).

A good selection of dBase programs with full source code is included. Refer to Section 4 for more details on each of the example programs.

     [PROGRAM]    [DESCRIPTION]
     WSCVER     :  Program that displays the WSC version number.
     SIMPLE     :  A simple terminal emulator.
     SIMPLE2    :  A simple terminal emulator (alternate version)
     FINDER     :  Finds a modem connected to one of your serial ports.
     XMS , XMR  :  XMODEM programs.
     YMS , YMR  :  YMODEM programs.
     DEVICE     :  Program sends string to serial device.
     DIALER     :  Dials up host (or BBS).
     ATOK       :  Forms based program that sends "AT" to modem.
     SELFTEST   :  Performs port functionality testing.

WSC4DB contains 34 functions and modem control. All functions return a negative number if an error condition is detected. For more details, consult the WSC Reference Manual (WSC_REF.DOC or WSC_REF.HTM) and the RS232/422/485 Serial Communications User's Manual (SERIAL.DOC or SERIAL.HTM). Both manuals can be accessed online at

http://www.marshallsoft.com/wsc4db.htm

1.2 Documentation Set

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

• WSC_4DB Programmer's Manual (WSC_4DB.DOC, WSC_4DB.TXT, WSC_4DB.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 User's Manual (SERIAL.DOC, SERIAL.TXT, SERIAL.HTM)

The WSC_4DB Programmer's Manual is the language specific (Visual dBase) manual and provides information needed to compile your programs in a Visual dBase environment..

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

Documentation is also provided online at
http://www.marshallsoft.com/wsc4db.htm

1.3 Example Program

The following example program segment to set DTR (Data Terminal Ready) demonstrates the use of some of the library functions:

     *
     * SETDTR.PRG
     *
     #INCLUDE WSC32.CC
     #INCLUDE KEYCODE.CC
   
     ? "WSCVER 4.3"
     ?
     * pass the key code
     if SioKeyCode(WSC_KEY_CODE) < 0
       ?"ERROR: Bad Key Code!"
       return
     endif
     * open port COM1
     Code = SioReset(COM1, 512, 512)
     If Code < 0
       ?"ERROR: Cannot open port"
       return
     endif
     * set DTR
     Code = SioDTR(COM1, ASC("S"))
     * close port
     Code = SioDone(COM1)

1.4 Installation

1. Before installation of WSC4DB, your Visual dBase compiler should already be installed on your system and tested.
   
   
2. Unzip WSC4DB43.ZIP (or WSC4DB.ZIP for registered users) using any Windows unzip program.
   
   
3. Run the installation program SETUP.EXE which will install all WSC4DB files including copying WSC32.DLL and WSC16.DLL to your Windows directory. No Windows system files are modified.

Note that no DLL registration is required and the Windows registry is not modified.

1.5 Uninstalling

Uninstalling WSC4DB is very easy. WSC does not modify the registry.

First, run UINSTALL.BAT, which will delete WSC16.DLL and WSC32.DLL from your Windows directory, typically C:\WINDOWS for Windows 95/98/ME/XP/Vista or C:\WINNT for Windows NT/2000.

Next, delete the WSC project directory created when installing WSC4DB.

1.6 Pricing

A developer license for WSC4DB can 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 version or order directly on our web site at

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

1.7 Updates

When a developer license is purchased, the developer receives a set of registered DLLs plus a license file (WSCxxxx.LIC) that can be used to update the registered DLL's for a period of one year from purchase. Updates can be downloaded from

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

After one year, your license must be updated if you want to be able to download updates. The developer 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.

2.1 Dynamic Link Libraries

The WSC4DB 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 have 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.CC. The keycode for the evaluation (shareware) version is 0. You will receive a new key code and set of 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 Limitations on COM Ports

The 32-bit version of WSC4C (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.4 INCLUDE Files

INCLUDE files used by the example programs are:

WSC32.CC & WSC16.CC - Serial communications constants & declarations.

MIO32.CC & MIO16.CC - Modem I/O constants & declarations.

XYM32.CC & XYM16.CC - X/Ymodem constants & declarations.

There are three recommended ways to handle these INCLUDE files in dBase programs.

1. Copy the INCLUDE files to your compiler's INCLUDE directory.
2. Edit the INCLUDE statements (in each program) with their physical location.
3. Replace the INCLUDE statements (in each program) by their contents.
   
   
   

2.5 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, although WSC doesn't access USB directly.

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

2.6 Dynamic Strings

The Visual dBase language uses a technique known as "garbage collection" to manage string space at runtime, and may be called internally at any time by the dBase 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:

     Code = SioReset(Port, 1024, 1024)
     if Code < 0
       ? "ERROR " + Str(Code)
       * allocate 'Buffer' immediately before use
       Buffer = SPACE(128)
       Code = SioWinError(Buffer, 128)
       if Code > 0
         ? Left(Buffer,Code)
       endif
     endif

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.7 Null Terminated Strings

All strings returned from WSC functions are null terminated. That is, the end of the string is delimited by a Chr(0) character. These strings may be converted for dBase by using the dBase LEFT function: For example,

       Code = SioWinError(Buffer, 128)
       if Code > 0
         Buffer = Left(Buffer,Code)
       endif

2.8 Win32 STDCALL and DECLSPEC

WSC32 is written in ANSI C and is compiled using the _stdcall and _declspec keywords. This means that WSC4DB 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.9 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 receive incoming serial data. SioGetc and SioGets can be called directly. Note that if there is no input data available, SioGetc returns WSC_NO_DATA while SioGets returns zero. Also see Section 2.11 "SioEvent Logic".

2.10 Error Display

The error message text associated with WSC error codes can be displayed by calling GetErrorText (refer to Errors.cc). Each sample program contains examples of error processing.

2.11 SioEvent Logic

SioEvent, SioEventChar, and SioEventWait will block (the application will sleep) until the specified event or timeout (SioEventWait only) 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. Descriptions of these functions can be found in the WSC Reference Manual.

Also see the SIMPLE2.PRG example program that uses SioEventWait.

3.0 Compiler Issues

3.1 Visual dBase 5.6 and 5.7

Visual dBase 5.6 and 5.7 create 16-bit applications and use the 16-bit WSC DLL's ( WSC16.DLL, MIO16.DLL, and XYM16.DLL). Copy the 16-bit CC files (WSC16.CC, MIO16.CC, and XYM16.CC) to your compiler's INCLUDE directory.

3.2 Visual dBase 7.0 and above

Visual dBase 7.0 and above create 32-bit applications and use the 32-bit WSC DLL's (WSC32.DLL, MIO32.DLL, and XYM32.DLL). Copy the 32-bit CC files (WSC32.CC, MIO32.CC, and XYM32.CC) to your compiler's INCLUDE directory.

3.3 Compiling dBase Programs

Visual dBase programs end with the extension ".PRG". Before compiling any of the example programs, edit each file with the port number and baud rate. Programs can be edited within any text editor, and compiled from the VDB (Visual dBase) command window with the COMPILE command (e.g.: COMPILE SIMPLE.PRG) or executed from the VDB command window with the DO command (e.g.: DO SIIMPLE.PRG).

To open a program within the Visual dBase source editor, choose "File", then "Open". When the "Open File" dialog box appears, choose "Programs" for "Files of Type", then choose the program (*.PRG) to open. Lastly, choose "Open in Source Editor" for "Action" and push the "Open" button.

After editing the source program, you are ready to compile. From the dBase menu bar, choose "Build", then "Compile". To run choose, "Run". The VDB command window must be displayed in order to see the output.

3.4 Compiling dBase Projects

Visual dBase projects consist of several types of files such as forms, reports, data modules, etc. The project file itself ends with the extension of ".PRJ".

There is one example Visual dBase project: ATOK32. Open ATOK32 by choosing "File", then "Open Project" from the dBase menu bar. To compile ATOK32, choose "Build" from the menu bar, then "Rebuild All". This will create ATOK32.EXE, which can be executed by choosing "Execute atok32.exe" from the "Build" menu bar pulldown, or from the Windows command line prompt.

3.5 Compiling to an Executable

dBase programs end in ".PRG". They can be compiled to an executable using the dBase BUILD command.

For example, to create WSCVER.EXE from WSCVER.PRG in the C:\WSC4DB\APPS directory, type the following in the dBase command window:

     BUILD PROJECT C:\WSC4DB\APPS\WSCVER FROM C:\WSC4DB\APPS\WSCVER
     BUILD EXE C:\WSC4DB\APPS\WSCVER FROM C:\WSC4DB\APPS\WSCVER

4 Example Programs

All example programs end with ".PRG", except for the FORM example (ATOK), which ends with ".WFM".

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.

4.2 SIMPLE

SIMPLE is a very simple communications program using WSC4DB. 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 SIMPLE 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 SIMPLE on both machines. Whatever is typed on one machine will be displayed on the other.

4.3 SIMPLE2

SIMPLE2 is the same program as SIMPLE, except that it calls SioPuts rather than SioPutc, and SioGets rather than SioGetc. SioPuts and SioGets send and receive strings instead of characters. SIMPLE2 also calls SioEventWait when blocking (efficiently waiting) for new serial input.

4.4 XMS and XMR

XMS (XMODEM Send) and XMR (XMODEM Receive) are programs that send and receive files using the XMODEM protocol.

4.5 YMS and YMR

YMS (YMODEM Send) and YMR (YMODEM Receive) are programs that send and receive files using the YMODEM protocol.

4.6 FINDER

The FINDER program is a program that searches for a connected modem. Your modem must be connected to one of COM1 through COM4, and the modem must be turned on. Note that FINDER uses the MIO module.

4.7 DIALER

The DIALER program dials up a HOST (or BBS) program, connects, and then operates like SIMPLE; in which all serial input is copied to the screen and all keyboard input is sent out the serial port.

4.8 DEVICE

The DEVICE program is designed for talking to an arbitrary serial device. Use this program as a guide when communicating with all serial devices other than modems and other computers.

4.9 ATOK

The ATOK programs demonstrate how to call WSC functions from within a dBase FORM. They transmit the string "AT" and expect an "OK" back. There are separate versions for 16-bit dBase (ATOK16.WFM) and 32-bit dBase (ATOK32.WFM) because of the different FORM syntax.

4.10 SELFTEST

SELFTEST performs basic serial port I/O functionality testing using a loopback adapter. Refer to LOOPBACK.TXT for an explanation of how to make a loopback adapter (without tools!).

5 Revision History

The WSC DLL's (WSC16.DLL and WSC32.DLL) are written in ANSI C. All language versions of WSC (C/C++, Delphi, Visual Basic, PowerBASIC, Visual FoxPro, Visual dBase, Xbase++, and COBOL) use the same identical DLLs.

Version 3.0: August 21, 2000

• The initial release of the Visual dBase version of WSC.

Version 3.1: May 29, 2001.

• RESETDEV Win API call not called (allows USB/serial converters).
• SioPutc and SioPuts return immediately (optionally).
• XYM (XMODEM/YMODEM) allows local upload/download directory to be specified.

Version 3.2: August 23, 2002.

• Added SELFTEST example program.
• 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: January 13, 2004.

• 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: April 6, 2006.

• SioFlow returns 1 if OK.
• SioSetInteger(Port, ASC("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: October 10, 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).