MarshallSoft

Windows Standard

Serial Communications

Library for Visual FoxPro


Programmer's Manual


(WSC4FP)


Version 4.3

October 5, 2007



This software is provided as-is.
There are no warranties, expressed or implied.



Copyright (C) 2007 All rights reserved



MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815


Voice : 1.256.881.4630

email : info@marshallsoft.com

Web : www.marshallsoft.com


MARSHALLSOFT is a registered trademark of MarshallSoft Computing.



TABLE OF CONTENTS


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
2 Library Issues
2.1 Dynamic Link Libraries
2.2 Key Code
2.3 INCLUDE Files
2.4 Limitations on COM Ports
2.5 Win32 STDCALL and DECLSPEC
2.6 Dynamic Strings
2.7 Waiting for New Serial Data
2.8 SioEvent Logic
2.9 Error Display
2.10 Virtual Serial Ports
2.11 16-bit FoxPro
2.12 Adding WSC to a VFP Program
3 Compiling Issues
3.1 Compiling and Linking Programs
3.2 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 SELFTEST
4 Revision History

1 Introduction

The Windows Standard Serial Communications Library for Visual FoxPro (WSC4FP) is a component library of functions providing the capability to quickly write serial communication applications in Visual FoxPro. 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.

WSC4FP supports all versions of Visual FoxPro. WSC4FP includes numerous Visual FoxPro 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. 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, Visual C#, Visual FoxPro, Visual Basic, VB.NET, 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. WSC4FP 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 Basic (WSC4VB), 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 

     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. Contact us if you have any questions.

1.1 Features

Some of the many features of the Windows Serial Communications Library are:

A good selection of Visual FoxPro example programs with full source code is included. Refer to Section 4.0 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.
     DIAL      :  Dials up host (or BBS).
     SELFTEST  :  Performs port functionality testing.

WSC4FP 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) and the RS232/422/485 Serial Communications User's Manual (SERIAL). The manuals can also be accessed online at http://www.marshallsoft.com/wsc4fp.htm


1.2 Documentation Set

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

The WSC_4FP Programmer's Manual is the language specific (Visual FoxPro) manual and provides information needed to compile your programs in a Visual FoxPro 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:

The documentation is also provided on our web site at 

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

1.3 Example Program

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

     #INCLUDE C:\WSC4FP\APPS\KEYCODE.FOX
     #INCLUDE C:\WSC4FP\APPS\WSC32CON.FOX
   
     DECLARE INTEGER SioKeyCode in WSC32.DLL LONG KeyCode
     DECLARE INTEGER SioDTR in WSC32.DLL INTEGER Port, INTEGER Cmd
     DECLARE INTEGER SioDone in WSC32.DLL INTEGER Port
     DECLARE INTEGER SioReset in WSC32.DLL INTEGER Port,
                              INTEGER RxBufSize, INTEGER TxBufSize
   
     * 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)

Refer to section 4.0 for complete examples with source.

1.4 Installation

  1. Before installation of WSC4FP, your Visual FoxPro compiler should already be installed on your system and tested.

  2. Unzip WSC4FP43.ZIP (or WSC4FP.ZIP for registered users) using any Windows unzip program.
  3. Run the installation program SETUP.EXE which will install all WSC4FP 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.

1.5 Uninstalling

Uninstalling WSC4FP is very easy. WSC4FP does not modify the registry.

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

Second, delete the WSC project directory created when installing WSC4FP.

1.6 Pricing

A developer license for WSC4FP 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 person 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. Your license can be updated for :

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

2 Library Issues

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 WSC4FP library supports and has been tested with all versions of Microsoft Visual FoxPro.

2.1 Dynamic Link Libraries

The WSC4FP 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.FOX. 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 INCLUDE Files

All example programs include two files: KEYCODE.FOX and WSC32CON.FOX. The file, KEYCODE.FOX, FCE32CON.FOX contains the license keycode as discussed in the previous section. The file, WSC32CON.FOX , contains all the necessary constants for WSC4FP. Similarly, some example programs will contain MIO32CON.FOX and XY32CON.FOX.

Since function declarations cannot be in an INCLUDE file (at least through VFP version 5.0), they are listed in each program following the INCLUDE file or files. The complete list of WSC function declarations is also in file WSC32FUN.FOX.

Due to the behavior of Visual FoxPro regarding INCLUDE files, we recommend handling INCLUDE files in either of the following ways:

  1. Edit each INCLUDE file path in each program with the physical location of the INCLUDE file.
  2. Replace each INCLUDE file in each program with the contents (i.e., copy and paste contents) of the INCLUDE file.

2.4 Limitations on COM Ports

The 32-bit version of WSC4PB (WSC32.DLL) can use any port from COM1 to COM256, provided that the port is known to Windows 95/98/NT/2000/Me/Vista/XP 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 WSC4FP 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.

Any Windows application program capable of calling the Windows API provided the proper declaration file is used may call the WSC32.DLL functions.

2.6 Dynamic Strings

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

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.8 below.

2.8 SioEvent Logic

SioEvent, SioEventChar, and SioEventWait will block (the application will sleep) until the specified event or timeout (SioEventWait only) occurs. Descriptions of these functions can be found in the WSC Reference Manual (see section 1.2 above).

Also see the SIMPLE2.PRG example program that demonstrates the use of the SioEventWait function.

2.9 Error Display

All WSC functions return an integer code. Error conditions always have negative return codes as listed in WSC32CON.FOX (in the APPS sub-directory) and wscErrors.txt (in the DOCS sub-directory).

Each sample program contains examples of error processing.

2.10 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 converters 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). (http://www.marshallsoft.com/wsc_usr.htm#Section_2.12 )

2.11 Using 16-bit FoxPro for Windows

The example programs are all set up for use with Visual FoxPro, version 3.0 or above. However, WSC4FP can also be used with "FoxPro for Windows" by replacing the 32-bit function declarations with the 16-bit function declaration as found in WSC16FUN.FOX and using WSC16.DLL.

2.12 Adding WSC to a VFP Program

  1. - Add the WSC constants (found in WSC32CON.FOX) that you will use in your program.
  2. - Add the WSC function declarations (found in WSC32FUN.FOX) that you will call to your program.

Refer to the example programs.

3 Compiling Issues

3.1 Compiling and Linking Programs

The example programs are compiled from the Visual FoxPro development environment. Before running the example programs edit each example program with your serial port parameters as shown in the example program in Section 1.3 above.

3.2 Compiling to an Executable

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

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

     BUILD PROJECT C:\WSC4FP\WSCVER FROM C:\WSC4FP\WSCVER
     BUILD EXE C:\WSC4FP\WSCVER FROM C:\WSC4FP\WSCVER

FoxPro executables require VFP500.DLL and VFP5ENU.DLL (ENglish User), and may have to be copied from the VFP CDROM. If you are using an earlier or later version of FoxPro than version 5.0, substitute the appropriate DLL's for the above.

The FoxPro output display window will disappear as soon as your executable completes. In order to allow the user to control when the display window disappears, add the following code to your application, just before the final return. 

     ?  " Type any key to exit..."
     X = InKey(0)

4 Example Programs

Each of the following example programs is written for 32-bit FoxPro. For information on 16-bit FoxPro, refer to Section 2.12 above. Before writing your own programs, compile and run the example programs.

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

3.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 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 DLLs (WSC16.DLL and WSC32.DLL) are written in ANSI C. All language versions of WSC (C/C++, Delphi, Visual Basic, PowerBASIC, Visual dBase, Visual FoxPro, Xbase++, and COBOL) use the same identical DLLs.

Version 3.0: August 14, 2000

Version 3.1: May 24, 2001.

Version 3.2: August 20, 2002.

Version 4.0: January 8, 2004.

Version 4.1: August 12, 2004

Version 4.2: March 29, 2006.

Version 4.3: October 5, 2007.