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.
1 Introduction
1.1 Documentation Set2 Library Overview
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.1 Dynamic Link Libraries3 Compiler Issues
2.2 Using the Library
2.3 Win32 STDCALL and DECLSPEC
2.4 Using Threads
3.1 Compiling WSC4 Example Programs
3.2 Compiling Example Programs
4.1 WSCVER5 Revision History
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
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.
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:
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
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,
MKDIR WSC PKUNZIP WSC4PB30.ZIP WSCRun 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.
http://www.hotfiles.com
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".
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.
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.
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.
Each of the example programs should be compiled and run.
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.
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.
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.
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.
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.
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!).
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).
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.
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
The DIALER programs dials up a specified host, such as a Bulletin Board System (BBS) .
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.
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.
XMS (XMODEM Send) and XMR (XMODEM Receive) are programs that send and receive files using the XMODEM protocol.
YMS (YMODEM Send) and YMR (YMODEM Receive) are programs that send and receive files using the YMODEM protocol.
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