Windows Standard

Serial Communications

for PowerBASIC

Programmer's Manual


(WSC_4PB)


Version 3.0

September 8, 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 Limitations on COM Ports
1.6 Ordering
1.7 Updates
1.8 Awards
2 Library Overview
2.1 Dynamic Link Libraries
2.2 Using the Library
2.3 Win32 STDCALL and DECLSPEC
2.4 Using Threads
3 Compiler Issues
3.1 Compiling WSC
3.2 Compiling Example Programs
4 Example Programs
4.1 WSCVER
4.2 SIMPLE
4.3 SELFTEST
4.4 MODEM
4.5 TERM
4.6 FINDER
4.7 DIALER
4.8 THREAD
4.9 DEVICE
4.10 XMS and XMR
4.11 YMS and YMR
5 Revision History

1 Introduction

The Windows Standard Serial Communications Library for PowerBASIC (WSC4PB) 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 WSC4PB dynamic link library (WSC32.DLL) can be called from any WIN32 application capable of calling Windows API functions, including those written in PowerBASIC, C/C++, Delphi, Visual Basic, MS Access/Excel/Word, Fortran, COBOL, PowerBuilder, Visual FoxPro, Visual dBase, etc. The library runs under NT/2000 and Windows 95/98.

Using WSC is very straight-forward. For example, to write "HELLO" to the serial port COM1:

   Dim Text As Asciiz * 5
   Dim Code As Long
   Text = "HELLO"
   Code = SioReset(%COM1,512,512)  'open COM1 with 512 KB buffers
   Code = SioPuts(%COM1,Text,6)    'write "HELLO" to COM1
   Code = SioDone(%COM1)           'close COM1

Several PowerBASIC example programs with full source code are included. Refer to Section 4 for more details on each of the example programs.

  WSCVER   : Display WSC version number.
  SIMPLE   : A simple terminal emulator.
  SELFTEST : Performs COM port functionality testing.
  XMR      : Receives files via XMODEM protocol.
  YMR      : Receives files via YMODEM protocol.
  XMS      : Sends files via XMODEM protocol.
  YMS      : Sends files via YMODEM protocol.
  FINDER   : Finds a modem connected to one of your serial ports.
  ECHOPORT : Multi-threaded console mode program echoes all input.
  DIALER   : Modem dialer.
  RS485    : RS485 example program.
  DIALER   : Dials telephone number.
  DEVICE   : Sends text string to serial device.


WSC4PB contains 28 functions. All functions return a negative number if an error condition is detected. For more details, consult the WSC4PB Reference Manual (WSC_REF) and the RS232/422/485 Serial Communications User’s 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.

1.1 Documentation Set

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

Each manual comes in three formats:

1.2 Example Program

The following example program displays the WSC version number.

$INCLUDE "WSC32.BAS"

FUNCTION PbMain() AS LONG

Dim Version As Integer
Dim A As String
Dim B As String
Dim C As String

PRINT "WSCVER 9/08/2000 "

' display WSC version
Version = SioInfo(ASC("V"))
'''PRINT Hex$(Version)
C = Hex$(&HF And Version)
Version = Version / 16
B = Hex$(&HF And Version)
Version = Version / 16
A = Hex$(&HF And Version)
PRINT "WSC Version " + A + "." + B + "." + C

END FUNCTION

1.3 Installation

Installation of WSC4PB is very straight-forward. Unzip the archive (zip file) and go! The windows registry is not written to, nor are any hidden files created. That is,

  1. Before installation of WSC4PB, your (32-bit) PowerBASIC Console Compiler (or PowerBASIC DLL Compiler) should already be installed on your system and tested.

  2. Start a console (command line) window.

  3. Delete all old versions (if any) of WSC32.DLL from your system.

  4. Create your WSC project directory, copy the WSC archive (zip file), then unzip the WSC archive. For example:
   MKDIR   WSC
   PKUNZIP WSC4PB30.ZIP WSC
Run INSTALL.BAT to copy the DLL's to your Windows directory. You are now ready to compile and run a test program. Refer to Section 3.0 "Compiling Programs" for details.

1.4 Uninstalling

Uninstalling WSC4PB is very easy. WSC4PB does NOT modify the registry. First, delete the WSC4PB project directory created when installing WSC4PB. Second, delete WSC32.DLL from your Windows directory, typically C:\WINDOWS for Windows 95/98 or C:\WINNT for Windows NT/2000. Running the UINSTALL.BAT batch file will also delete WSC32.DLL as described above.

1.5 Limitations on COM Ports

WSC4PB can use any port from COM1 to COM32, provided that the port is known to Windows and there is physical hardware present. More ports can easily be added by recompiling WSC32.C.

1.6 Ordering

WSC4PB can be registered for $95. See Section 1.5 "Ordering" in the WSC User’s Manual (WSC_USR) for details on ordering.

1.7 Updates

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

1.8 Awards

The C/C++ version of WSC has been rated 4 stars by Ziff Davis on the web at http://www.hotfiles.com. The Visual Basic version (which uses the same DLLs) has been rated 5 stars, their highest rating.

http://www.hotfiles.com

2 Library Overview

2.1 Dynamic Link Libraries

WSC4PB is a Win32 dynamic link library (WSC32.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".

2.2 Using the Library

The WSC4PB has been tested on multiple computers running Windows 95/98 and Windows NT/2000.

Please examine the WSC32.BAS file. Note that %COM1 is defined as port zero, not port one. The user must assume the responsibility for passing the correct information when calling WSC4PB functions.

2.3 Win32 STDCALL and DECLSPEC

WSC32 is written in ANSI C and is compiled using the STDCALL and DECLSPEC keywords. This means that WSC4PB 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.

2.4 Using Threads

WSC4PB is thread safe. Refer to the THREAD and ECHOPORT example programs, which demonstrates the use of threads. ECHOPORT also demonstrates the use of the WIN32 Sleep() function.

3 Compiler Issues

Each of the example programs should be compiled and run.

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

3.2 Compiling Example Programs

Compiling programs using the PowerBASIC Console Compiler is very easy. For example, to compile SIMPLE.BAS, type

PBCC SIMPLE.BAS

at the command prompt. If your program requires access to any Windows API functions, you must include the path on the command line. For example, assuming that you have installed PBCC at C:\PBCC10, to compile the ECHOPORT.BAS program, type (the "-MT" is for Multi-Tasking support)

PBCC ECHOPORT.BAS -IC:\PBCC10\WINAPI -MT

Refer to Section 4.0 "Example Programs" for more information on the example programs.


4 Example Programs

The example programs are designed to demonstrate the various capabilities of WSC4PB. The best way to become familiar with WSC4PB is to study 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 versifies that WSC32.DLL is installed properly.

4.2 SIMPLE

SIMPLE is a very simple communications program using WSC4PB. 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 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.

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

4.4 MODEM

MODEM is similar to SIMPLE, 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>. It can also 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, 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.

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.

FINDER takes no arguments. After connecting your modem to one of your serial ports, type

FINDER

4.7 DIALER

The DIALER programs dials up a specified host, such as a Bulletin Board System (BBS) .

4.8 THREAD

The THREAD example program is similar to SIMPLE, except that it uses a Win32 thread. Note that the PowerBASIC thread function blocks awaiting serial input.

4.9 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.10 XMS and XMR

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

4.11 YMS and YMR

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

5 Revision History


NOTE: Version 2.3 was the first PowerBASIC version.


Version 2.3: August 3, 1998.

Initial release of PowerBASIC version.

Version 2.4: May 24, 1999

Version 3.0: September 8, 2000