Windows Standard

Serial Communications

for Delphi

Programmer's Manual


(WSC_4D)


Version 3.0

September 1, 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 Awards
1.4 Installation
1.5 Uninstalling
1.6 Limitations on COM Ports
1.7 Ordering
1.8 Updates
2 Library Overview
2.1 Dynamic Link Libraries
2.2 Using the Library
2.3 Win32 STDCALL and DECLSPEC
2.4 Using Threads
2.5 Using Messages
2.6 Using the Delphi Timer
3 Compiler Issues
3.1 Delphi Versions
3.1.1 Delphi 1
3.1.2 Delphi 2
3.1.3 Delphi 3
3.1.4 Delphi 4 and above
3.2 Compiling WSC
3.3 Compiling Example Programs
4 Example Programs
4.1 VERSION
4.2 EASY
4.3 SELFTEST
4.4 MODEM
4.5 TERM
4.6 FINDER
4.7 EVENT
4.8 DEVICE
4.9 MESSAGE
4.10 XMS and XMR
4.11 YMS and YMR
5 Revision History

1 Introduction

The Windows Standard Communications Library for Delphi (WSC4D) 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 WSC4D DLLs (WSC16.DLL and WSC32.DLL) can be called from any application capable of calling Windows API functions, including those written in C/C++, Delphi, Visual Basic, MS Access, MS Excel, Fortran, COBOL, etc. The library runs under Windows NT and 2000, Windows 95/98, and Windows 3.1.

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

      VERSION :  [VER] Displays WSC version number.
      EASY    :  A simple RS232 terminal program.
      RS485   :  A simple RS485 terminal program.
      SELF    :  Performs COM port functionality testing.
      MODEM   :  [MODM] Same as EASY but controls flow control, modem lines, etc.
      TERM    :  Terminal emulator with XMODEM, YMODEM, and ANSI support.
      FIND    :  Finds a modem connected to one of the serial ports.
      EVENT   :  [EVNT] Same as EASY except uses SioEvent to await incoming data.
      MESSAGE :  [MESS] Same as EASY except uses SioMessage to await incoming data.
      XMS/XMR :  XMODEM send/receive example programs.
      YMS/YMR :  YMODEM send/receive example programs.
WSC4D contains 28 functions. All functions return a negative number if an error condition is detected. For more details, consult the WSC4D Reference Manual (WSC_REF) and the RS232/485 Serial Communications Users Manual (ASYNC). 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_4D) in the set.

Each manual comes in three formats:

1.2 Example Program

The following example transmits an "AT" to a modem connected to the serial port.

var
  Code : Integer;
begin
  Code := SioReset(COM1, 1024, 1024);
  If Code < 0 Then
    begin
      WriteLn('Cannot open port');
      exit
    end
  (* transmit "AT" *)
  Code := SioPutc(COM1, 'A');
  Code := SioPutc(COM1, 'T');
  Code := SioPutc(COM1, Chr(13))
end;

Refer to the sample programs for complete examples.

1.3 Awards

WSC4D has been rated 4 stars by ZDNET by Ziff Davis on the web at http://www.hotfiles.com. WSC4VB, the Visual Basic version (which uses the same DLLs and functions), has been rated 5 stars, which is their highest rating.

Our Windows Standard Serial Communications Library for C/C++ is one of the more popular downloads and a reviewer’s pick in the shareware libraries category.

1.4 Installation

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

  1. Before installation of WSC4D, your Delphi compiler should already be installed on your system and tested. Note that Delphi 2 (or up) is required in order to create Win32 programs.

  2. Start a console (command line) window.

  3. Delete all old versions (if any) of WSC16.DLL and WSC32.DLL.

  4. Create your WSC project directory, copy the WSC zip file, and then unzip the zip file. For example:
      MKDIR   WSC                
      PKUNZIP WSC4D30.ZIP WSC    [registered users unzip WSC4D.ZIP]
Run the install program INSTALL.BAT which will copy the correct files for your installation (Delphi 1 or Delphi 2 and above). If you are using 16-bit Delphi 1, then type:
      INSTALL 16               [for Windows 95/98 or Windows 3.1]
      INSTALL 16 NT            [for Windows NT/2000]
If you are using 32-bit Delphi 2 (or above), then type:
      INSTALL 32               [for Windows 95/98/NT/2000]
The install program creates WSC4D.PAS from either WSC16.PAS or WSC32.PAS, and copies the proper DLLs. This way, the source code for the example programs is identical for both Delphi 1 (Win16) and Delphi 2 and up (Win32).

1.5 Uninstalling

Uninstalling WSC4D is very easy. WSC4D does NOT modify the registry. First, delete the WSC4D project directory created when installing WSC4D. Next, delete WSC16.DLL and WSC32.DLL from your Windows directory, typically C:\WINDOWS for Windows 95/98 or C:\WINNT for Windows NT/2000.

1.6 Limitations on COM Ports

The 32-bit version of WSC4D (WSC32.DLL) can use any port from COM1 to COM32, provided that the port is known to Windows 95/98/NT/2000 and there is physical hardware present. More ports (256) can easily be added by recompiling the registered version of WSC32.C.

1.7 Ordering

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

1.8 Updates

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

2 Library Overview

2.1 Dynamic Link Libraries

WSC4D includes both Win16 and a Win32 dynamic link library (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 DelphiX 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 Using the Library

The WSC4D has been tested on multiple computers running Windows 3.1, Windows 95/98, and Windows NT/2000. Please examine the WSC16.PAS and WSC32.PAS files. Note that COM1 is defined as port zero, not port one. The user must assume the responsibility for passing the correct information when calling WSC4D 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 WSC4D 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

WSC4D is thread safe, and can be used from any Windows Win32 application capable of using threads. Note that 16-bit Windows does not support threads. Refer to the EVENT program (EVNT_PRJ) for an example of using threads with WSC4D.

2.5 Using Messages

WSC is capable (SioMessage function) of sending windows messages in response to specified serial events. Like using threads, 32-bit Delphi is required. Refer to the MESSAGE program (MESS_PRJ) for an example of using messages with WSC4D.

2.6 Using the Delphi Timer

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. This is true for all out going serial data as well. However, most of the example programs use the Delphi timer in order to check the receive queue. For example, in the EASY example program, the timer interval is set to 125. Thus, every 125 milliseconds the timer code will execute and all available serial data (if any) will be copied from the receive queue. In practice, there is very little overhead to using a timer provided the timer interval is not set too low. The use of timers in Delphi can avoided by using threads or messages as described above

3 Compiler Issues

3.1 Delphi Versions

Applications written with Delphi link with the same identical DLL's as for applications written in all other supported languages, such as C/C++ and Visual Basic.

3.1.1 Delphi 1

The first release of Borland Delphi (version 1) generated Win16 code. Therefore, applications written using Delphi 1 must link with WSC16.DLL. One very significant limitation of Delphi 1 is that strings are limited to 255 bytes.

3.1.2 Delphi 2

Delphi version 2 and above generates Win32 code. Therefore, applications written using Delphi 2 will link with WSC32.DLL. Strings can be up to 2GB rather than 255 bytes as in Delphi 1. Delphi 2 seems to have a problem with some of the PChar string functions. Although the default is "large strings", some of the string functions (such as StrPCopy) copy only 255 bytes. The MYSTRING.PAS unit contains a replacement unit to use instead of StrPCopy.

3.1.3 Delphi 3

Delphi 3 also has some problems with PChar string functions such as StrPCopy. See the above section.

3.1.4 Delphi 4 and above.

There are no known Delphi problems impacting our example programs in Delphi version 4 and above. Applications written using Delphi 4 and above will link with WSC32.DLL.

3.2 Compiling WSC

WSC is written in standard ANSI C (WSC16.C and WSC32.C), and has been compiled using Microsoft Visual C/C++. The Win32 version is compiled with the STDCALL and DECLSPEC compiler keywords. Source code for the WSC library is provided in the registered version only. WSC 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 DLL can only be used by applications compiled with the same compiler, unless the STDCALL and DECLSPEC keywords are specified.

3.3 Compiling Example Programs

Delphi project files are provided with all example programs. From the Delphi development environment, choose "File", then "Open Project". Delphi projects have extension ".DPR". All of the example programs can be compiled with any version of Delphi, except for the EVENT program (EVNT_PRJ) and the MESSAGE (MESS_PRJ) program, both of which require Delphi version 2.0 or above. Refer to Section 4 "Example Programs" for more details.

4 Example Programs

The example programs are designed to demonstrate the various capabilities of WSC4D. The best way to become familiar with WSC4D is to study and run the example programs. Most of the example programs can be compiled with any version of Delphi. However, some require 32-bit (Delphi 2) or above.

4.1 VERSION

The VER ("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. The project files are:
VER_PRJ.DPR : Project file. VER_PGM.PAS : Program file. VER_PGM.DFM : Delphi Form file.

4.2 EASY

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

The project files are:

EASY_PRJ.DPR : Project file. EASY_PGM.PAS : Program file. EASY_PGM.DFM : Delphi Form file.

4.3 SELFTEST

The SELF ("selftest") program 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!).

The project files are:

SELF_PRJ.DPR : Project file. SELF_PGM.PAS : Program file. SELF_PGM.DFM : Delphi Form file.

4.4 MODEM

MODEM is similar to EASY, 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 and 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).

The project files are:

MODM_PRJ.DPR : Project file. MODM_PGM.PAS : Program file. MODM_PGM.DFM : Delphi Form file.

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.

The project files are:

TERM_PRJ.DPR : Project file. TERM_PGM.PAS : Program file. TERM_PGM.DFM : Delphi Form file.

4.6 FIND

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.

The project files are:

FIND_PRJ.DPR : Project file. FIND_PGM.PAS : Program file. FIND_PGM.DFM : Delphi Form file.

4.7 EVENT

The EVNT example program is similar to EASY, except that it uses SioEvent to wait for incoming serial data. EVNT requires 32-bit Delphi.

The project files are:

EVNT_PRJ.DPR : Project file. EVNT_PGM.PAS : Program file. EVNT_PGM.DFM : Delphi Form file.

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

The project files are:

DVCE_PRJ.DPR : Project file. DVCE_PGM.PAS : Program file. DVCE_PGM.DFM : Delphi Form file.

4.9 MESSAGE

The MESSAGE program is similar to EASY, except that rather than using a timer as in EASY, it uses the SioMessage function to request that WSC send a "Left Button Down" Windows message whenever any new serial data is available.

The MESSAGE example program requires Delphi 2 or above.

The project files are:

MESS_PRJ.DPR : Project file. MESS_PGM.PAS : Program file. MESS_PGM.DFM : Delphi Form file.

4.10 XMS and XMR

XMS (XMODEM Send) and XMR (XMODEM Receive) are programs that send and receive files using the XMODEM protocol. See XMODEM.TXT for more information on 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. See YMODEM.TXT for more information on the YMODEM protocol.

5 Revision History

NOTE: Version 2.0 was the first Delphi version of WSC.

Version 2.0: February 17, 1997.

Version 2.1: June 9, 1997.

Version 2.2: October 20, 1997.

Version 2.3: August 19, 1998

Version 2.4: June 7, 1999

Version 3.0: September 1, 2000