Windows Standard

Serial Communications

Library for Xbase++


Programmer's Manual


(WSC4XB)


Version 3.0

August 7, 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.



TABLE OF CONTENTS


1 Introduction
1.1 Documentation Set
1.2 Example Program
1.3 Installation
1.4 Uninstalling
1.5 Ordering
1.6 Updates
2 Compiler Issues
2.1 INCLUDE Files
2.2 Compiling and Linking Programs
2.3 Dynamic Strings
2.4 Key Codes
2.5 Xbase++ Compiler
3 Example Programs
3.1 WSCVER
3.2 SIMPLE
3.3 XMS and XMS
3.4 YMS and YMR
3.5 FINDER
3.6 ATOK
3.7 DEVICE
4 Revision History

1 Introduction

The Windows Standard Serial Communications Library for Xbase (WSC4XB) 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.

Using WSC is very straight-forward. For example, to write "AT" followed by a carriage return to serial port COM1:

   Text = "AT" + Chr(13)
   Code = xSioReset(COM1,512,512)
   Code = xSioPuts(COM1,@Text,3)
   Code = xSioDone(COM1)

Seven example programs are included, demonstrating serial port functions. All programs will compile using any version of Xbase++.

A Dynamic Link Library (WSC32.DLL) is provided. WSC4XB can be used with Windows 95/98, 2000 and NT. The WSC4XB DLL, (WSC32.DLL) can also be used from any language (C/C++, Visual Basic, PowerBASIC Console Compiler, Delphi, Visual FoxPro, Visual dBase, Xbase++, COBOL, Fortran, etc.) capable of calling the Windows API.

When comparing WSC against our competition, note that:

1.1 Documentation Set

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

Each manual comes in three formats:

1.2 Example Program

The following example demonstrates the use of some of the library functions:


#INCLUDE "DLL.CH"
#INCLUDE "WSC32.CH"

Procedure Main()
LOCAL Version
LOCAL A, B, C

? "WSCVER 7/24/2000"
?
Version = xSioInfo(ASC("V"))
* Compute WSC version
A = int(Version / 256)
Version = Version - (256 * A)
B = int(Version / 16)
C = Version - (16 * B)
? "WSC Version: " + LTRIM(Str(A)) + "." + LTRIM(Str(B)) + "." + LTRIM(Str(C))
return

In the example program above, xSioInfo function is called to get the version number of the WSC32.DLL.

Refer to the WSC Reference Manual (WSC_REF) for individual function details.

1.3 Installation

  1. Before installation of WSC4XB, your Xbase++ compiler should already be installed on your system and tested.

  2. Create your WSC4XB project directory, copy the WSC4XB archive, and then unzip the archive.

  3. Run INSTALL.BAT which will copy WSC32.DLL to either C:\WINDOWS or C:\WINNT.

  4. You're ready to run!

Note that the Windows registry is not modified.

1.4 Uninstalling

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

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

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

1.5 Ordering

WSC4XB may be registered for $95. See the section "Ordering" in the WSC User’s Manual (WSC_USR) for details on ordering.

1.6 Updates

Updates from an older version of WSC4XB are $30 USD for email delivery. See Section 1.5 "Ordering" in the WSC User’s Manual (WSC_USR) for details on ordering.


2 Compiler Issues

2.1 INCLUDE Files

All example programs include the file WSC32.CH. The file WSC32.CH contains all the necessary constants and function declarations for WSC4XB. The Xbase++ include file DLL.CH is also required. For example,

   #INCLUDE "DLL.CH"     
   #INCLUDE "WSC32.CH"   

2.2 Compiling and Linking Programs

See Section 3.0 "Example Programs" for more details on each of the example programs. To compile and link console mode programs, say SIMPLE.PRG, use
   xpp simple.prg                                 
   alink /subsystem:console simple.obj wsc32.lib  

To compile and link windows GUI programs such as ATOK.PRG, use

   xpp atok.prg                                   
   alink /subsystem:windows atok.obj wsc32.lib    
Some programs (such as XMR.PRG, XMS.PRG, YMR.PRG, and YMS.PRG) require the XYDRV32 module and must be linked with XYDRV32.LIB. For example, alink /subsystem:console xms.obj wsc32.lib xydrv32.lib Also, some programs (such as FINDER.PRG) require the MIO32 module and must be linked with MIO32.LIB. For example, alink /subsystem:console finder.obj wsc32.lib mio32.dll


2.3 Dynamic Strings

A string in the C language (in which WSC and Windows are written) consists of a pointer to the first byte of a character buffer in which a zero byte ends the string characters.

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

Procedure SayError(ErrCode)
   LOCAL Code
   LOCAL Buffer
   if ErrCode < 0
     ? "ERROR " + STR(ErrCode)
     Buffer = SPACE(128)
     Code = xSioWinError(@Buffer, 128)
     if Code > 0
       ? Left(Buffer,Code)
     endif
   endif
return

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 WSC Declaration File

All WSC functions are declared in the WSC declaration file WSC32.CH. This file can be copied to the Xbase++ INCLUDE directory (where Xbase++ can find it) if so desired.

Note that each function is declared with the prefix character of 'X'

2.5 Xbase++ Compiler

If you don't have the Alaska Software Xbase++ compiler, you can find it on the web at

http://www.alaska-software.com


3 Example Programs

Before writing your own programs, compile and run the example programs.

3.1 WSCVER

The first example program is the program WSCVER (WSC Version) which displays the WSC library version number.

   xpp wscver.prg                                 
   alink /subsystem:console wscver.obj wsc32.lib  

3.2 SIMPLE

SIMPLE is a very simple communications program using WSC4XB. 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.
   xpp simple.prg                                 
   alink /subsystem:console simple.obj wsc32.lib  

3.3 XMS and XMR

XMS (XMODEM Send) and XMR (XMODEM Receive) are programs that send and receive files using the XMODEM protocol.
   xpp xms.prg                                             
   alink /subsystem:console xms.obj wsc32.lib xydrv32.lib  

   xpp xmr.prg                                             
   alink /subsystem:console xmr.obj wsc32.lib xydrv32.lib  

3.4 YMS and YMR

YMS (YMODEM Send) and YMR (YMODEM Receive) are console mode programs that send and receive files using the YMODEM protocol.
   xpp yms.prg                                             
   alink /subsystem:console yms.obj wsc32.lib xydrv32.lib  

   xpp ymr.prg                                             
   alink /subsystem:console ymr.obj wsc32.lib xydrv32.lib  

3.5 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. FINDER takes no arguments. Note that FINDER uses the MIO module.
   xpp finder.prg                                           
   alink /subsystem:console finder.obj wsc32.lib mio32.dll  

3.6 ATOK

The ATOK program was developed using the Forms Designer (XPPFD) and is the only graphical example. The ATOK program sends "AT" to a connected modem and expects an "OK" back.
   xpp atok.prg                                 
   alink /subsystem:windows atok.obj wsc32.lib  

3.7 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.
   xpp device.prg                                 
   alink /subsystem:windows device.obj wsc32.lib  

4 Revision History

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

Version 3.0: August 7, 2000