Windows Standard
Serial Communications
for C/C++
Programmer's Manual
(WSC_4C)
Version 3.0
July 12, 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 Console Mode
2.3 Using the Library
2.4 Static Linking
2.5 Large Memory Model in Win16
2.6 Win32 STDCALL and DECLSPEC
2.7 Using Threads
3.1 Command Line Tool Setup4 Supported Compilers
3.1.1 Microsoft3.2 Command Line Batch Files
3.1.2 Borland
3.1.3 Watcom
3.1.4 Lcc-Win32
3.3 Command Line Makefiles
3.4 Compiling Using an IDE
4.1 Microsoft C/C++5 Compiling Programs
4.2 Microsoft Visual C/C++
4.3 Borland C/C++
4.4 Turbo C/C++ for Windows
4.5 Borland C++ Builder
4.6 Watcom C/C++
4.7 Lcc-Win32 C/C++
5.1 Compiling WSC6 Example Programs
5.2 Compiling Example Programs
5.3 Static Libraries
7 Revision History
The Windows Standard Serial Communications Library for C/C++ (WSC4C) 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 WSC4C 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, PowerBuilder, FoxPro, Power Basic Console Compiler, dBase, Xbase++, etc. The library runs under NT and 2000, Windows 95/98, and Windows 3.1.
Registered users can statically link WSC with their application rather than using the DLLs.
Using WSC is very straight-forward. For example, to write "HELLO" to the serial port COM1:
SioReset(COM1,512,512); // open COM1 with 512 KB buffers SioPuts(COM1,"HELLO\r",6); // write "HELLO" to COM1 SioDone(COM1); // close COM1A good selection of C/C++ example programs with full source code are included. Refer to Section 6 for more details on each of the example programs.
[PROGRAM] [DESCRIPTION] SIMPLE : A simple terminal emulator. SELFTEST : Performs COM port functionality testing. MODEM : Same as SIMPLE but controls flow control, modem lines, etc. TERM : Terminal emulator with XMODEM, YMODEM, and ANSI support. BCB : Borland C++ Builder (32-bit C++) example. MFC_PGM : Microsoft Foundation Class (MFC) example program. CONSOLE : A WIN32 console mode program similar to SIMPLE. FINDER : Finds a modem connected to one of your serial ports. ECHOPORT : Multi-threaded console mode program echoes all input. EVENT : Blocking version of SIMPLE. Uses SioEvent. XMS , XMR : Console mode XMODEM programs. YMS , YMR : Console mode YMODEM programs. RS485 : RS485 version of CONSOLE. DEVICE : Program to communicate with serial device. HOST : Simple one-line BBS.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_4C) in the set.
Each manual comes in three formats:
The following example demonstrates the use of one of the library functions:
// // VERS.C // // This Win32 console mode program displays the WSC version number. #include <windows.h> #include <stdio.h> #include "wsc.h" void main(void) {int Version; Version = SioInfo('V'); printf("Win32 WSC Version %d.%d.%d", (Version>>8), 0x0f&(Version>>4), 0x0f&Version); }In the example program above, the SioInfo function is called to get the version number from WSC32.DLL. The same code will also work from inside a Win16 GUI program, except that the version number will be from WSC16.DLL. Refer to the WSCVER.C example program, which can be compiled for Win16 or Win32. Also see Section 6 "Example Programs". Refer to the WSC Reference Manual (WSC_REF) for individual function details.
The INSTALL batch file must be run to copy the DLL's to your Windows directory. All recent WIN32 C/C++ compilers support the "declspec" keyword. Microsoft VC (version 4.0 and up), Borland (version and up), Watcom (version 11.0 and up), and Lcc-Win32 compilers support the "declspec" keyword.
If you have an older Win32 compiler (Borland C/C++ 4.0/4.5 or Watcom 10.5/10.6), you can download the proper DLL's from our web site at www.marshallsoft.com/wsc4c.htm
Uninstalling WSC4C is very easy. WSC does NOT modify the registry. First, delete the WSC project directory created when installing WSC4C. Second, delete WSC16.DLL and WSC32.DLL from your Windows directory, typically C:\WINDOWS for Windows 3.1/95/98 and C:\WINNT for Windows NT and Windows 2000. That's it!
The 32-bit version of WSC4C (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.
WSC4C can be registered for $95. See Section 1.5 "Ordering" in the WSC User’s Manual (WSC_USR) for details on ordering.
Updates from an older version of WSC4C are $30 USD for email delivery. See Section 1.5 "Ordering" in the WSC User’s Manual (WSC_USR) for details on ordering.
WSC4C has been rated 4 stars by Ziff Davis on the web at
http://www.hotfiles.comThe Visual Basic version (which uses the same DLLs) has been rated 5 stars which is their highest rating. WSC4C is also one of the most popular downloads in the software tools section of many web download sites.
[FILE] [DESCRIPTION] SIMPLE16._ML : Large memory model makefile for Microsoft SIMPLE16._BL : Large memory model makefile for Borland.
dumpbin /exports wsc32.dllSome older compilers such as Borland C/C++ 4.0/4.5 and Watcom 10.5/10.6 do not support the "declspec" keyword. DLL's for these compilers can be downloaded from
http://www.marshallsoft.com/wsc4c.htm
SioEvent(Port, EV_RXCHAR)blocks the outgoing serial stream as well as the incoming serial stream.
SHELL=C:\COMMAND.COM /e:1024 /pto CONFIG.SYS in C:\ and then rebooting. Yes, this works for all versions of Windows, including Windows NT and Windows 2000. For all compilers, your path should point to the compiler BIN directory. For example, to add "C:\BC50\BIN" to your existing path, use
PATH C:\BC50\BIN;%PATH%
SET INCLUDE=C:\MSVC\INCLUDE SET LIB=C:\MSVC\LIB
-IC:\BC5\INCLUDE -LC:\BC5\LIBBRCC (the Borland Resource Compiler) doesn't use the *.CFG files. Set the INCLUDE environment variable or BRCC will not be able to find the INCLUDE files (such as WINDOWS.H). For example,
SET INCLUDE=C:\BC5\INCLUDE Clear the LIB environment variable (so it is not present when SET is typed at the command line) with SET LIB=
Set the WATCOM environment variables to point to your compilers include (H) and BIN directories. For example,
SET INCLUDE=C:\WC11\H;C:\WC11\H\NT SET WATCOM=C:\WC11 SET EDPATH=C:\WC11\EDDAT SET WWINHELP=E:\BINW
SET INCLUDE=C:\LCC\INCLUDE SET LIB=C:\LCC\LIBAfter making the above changes for your compiler, type PATH at the command line prompt to verify the search path, and type SET at the command line prompt to verify the INCLUDE and LIB environment variables.
If your compiler installation includes command line tools, then all of the example programs can be compiled directly from the command line. These same compiler commands can also be placed in a batch file.
See CONSOLE.BAT for an example of a console mode command line batch file and SIMPLE32.BAT for an example of a GUI mode command line batch file. Similarly, command line batch files can be created for all of the example programs.
Command line makefiles originated on UNIX systems. They are the standard way that C/C++ programs are constructed in command line environments. The advantage of makefiles (as compared to an integrated development environment) is that all compiler switches are coded within the makefile and the makefile can be run with a single keystroke.
Makefiles are provided for Microsoft, Borland, and WATCOM command line compilers.
All current windows compilers have an "Integrated Development Environment" (IDE) for building application programs in the Windows environment. Since there is no standard format for IDE project files, file names must be entered into the IDE from the keyboard.
Note that not only do IDE's vary between the different compiler manufacturers, but they also vary from version to version for the same compiler.
Creating a project makefile for the examples that have only command line makefiles is fairly straight forward. All of the IDE's use the concept of a file hierarchy. For example, the WSCVER example program file hierarchy in the IDE (for 32-bit) should look like:
WSCVER.EXE +++ WSCVER.C +++ WSC32.LIB
Replace WSC32.LIB above with WSC16.LIB for 16-bit applications, with WSC32BCB.LIB if using
Borland C++ Builder, and with WSC32LCC.LIB if using Lcc-Win32.
The order of the files is not significant. Also refer to the sections on individual IDE's that follow this section.
WSC4C has been tested with Microsoft C/C++, Microsoft Visual C/C++, Borland C/C++ , Borland C++ Builder, Borland Turbo C/C++, Watcom C/C++, and Lcc-Win32. Other Windows C/C++ compilers may work as well.
Note: See Section 4.2 for Microsoft Visual C/C++.
Microsoft C/C++ programs can be compiled from either the command line or from within the Microsoft development environment.
The last Win16 Microsoft compiler is version 1.52.
All Microsoft Win16 makefiles end with "16._m_". Note that many of the example programs are console mode programs, and cannot be compiled as Win16 programs since Win16 does not support console mode. To compile, use the Microsoft NMAKE utility:
NMAKE -f SIMPLE16._M_WSC can be used with Microsoft Foundation Class (MFC) programs. Use the MFCPGM16.MAK makefile to compile the MFC_PGM example program.
NMAKE -f MFCPGM16.MAK
NMAKE -f SIMPLE16._M_ NMAKE -f SIMPLE32._M_WSC can be used with Microsoft Foundation Class (MFC) programs. Use the MFCPGM32.MAK makefile to compile the MFC_PGM example program.
NMAKE -f MFCPGM32.MAK
To open an existing project, choose "File", then "Open Workspace", and then select "Makefiles" from the list of file types. Several of the example programs have Microsoft Visual Studio C/C++ makefiles, ending with ".MAK" , such as
WSCVER32.MAK SIMPLE32.MAKTo create a new project in MSVC 4.0, choose "File", then "New", then "Project Workspace". Select "Application" or "Console Application" for "Type:" and your project name for "Name:". Choose Win32 for platform. Then select "Create". Select "Insert", then "Files into Project". Add all filenames including any resource file (.RC) and WSC32.LIB. Lastly, select "Build", then "Rebuild All". To create a new project in MSVC 5.0, choose "File", then "New", then "Win32 Application" or "Win32 Console Application " and your project name. Check "Create new workspace Select "Project", then "Add to Project". Add all filenames including any resource file (.RC) and WSC32.LIB. Lastly, select "Rebuild All". Creating a new project in MSVC 6.0 follows the same logic as for MSVC 5.0.
Borland C/C++ programs can be compiled from either the command line or from within the Borland development environment.
Borland v4.0 and v4.5 do not recognize the "declspec" keyword, and they require "legacy DLL's", which can be downloaded from www.marshallsoft.com/wsc4c.htm.
Programs can be compiled using command line makefiles. All Borland Win16 command line makefiles end with "16._b_" while Borland Win32 command line makefiles end with ’32._b_". To compile using a makefile, use the Borland MAKE utility. For example,
MAKE -f SIMPLE16._B_ MAKE -f SIMPLE32._B_
Win32 Borland users must create the proper WSC32.LIB from WSC32.DLL by running the "implib" program in the Borland compiler \BIN directory.
implib wsc32.lib wsc32.dllTo create a new project, first turn off LINKER case sensitivities: Choose "Options", "Projects", "Linker", "General". Turn off the "case sensitive link" and "case sensitive exports and imports" boxes. Next, choose "Project", then "New Project". Use the INS (Insert) key to pop up a dialog box into which the project file names are entered. Select "GUI" or "Console" for the "Target Model:" Only "Runtime" and "Dynamic" should be checked for "Standard Libraries:"
Borland Turbo C/C++ for Windows does not have command line tools, so all programs must be compiled from the Turbo C/C++ integrated environment.
Follow the same directions as above (Borland IDE), except that the "Target Model:" can be any listed.
Borland C++ Builder does not have command line tools, so all programs must be compiled from the Borland C++ Builder integrated environment. Compile the BCB example program QM_PRJ with QM_PRJ.MAK if running BCB version 1 through 3, and compile with QM_PRJ.BPR if running BCB version 4 or above.
To load the QM_PRJ example project, Choose "File" / "Open Project" on the menu bar. Load QM_PRJ.MAK (or QM_PRJ.BPR). Then, choose "Build All" from "Project" to create the executable.
Note that WSC32BCB.LIB is the LIB file used with Borland C++ Builder. WSC32BCB .LIB can be created from WSC32.DLL by using the Borland IMPLIB program:
IMPLIB WSC32BCB.LIB WSC32.DLL
WMAKE -f SIMPLE32._W_Win32 programs can also be compiled using command line batch files. See SIMPLE32.BAT for an example of a console mode command line batch file and SIMPLE32.BAT for an example of a GUI mode command line batch file. To run these command line batch files from the command line, type
SIMPLE32
http://www.cs.virginia.edu/~lcc-win32/To use our DLLs with Lcc-Win32, you must link with WSC32LCC.LIB. This file can also be re-created using the Lcc-Win32 utility BUILDLIB.
buildlib wsc32.lcc wsc32lcc.lib Then, compile and link as normal. For example, to compile the CONSOLE example program, lcc -DWIN32 console.c lcclnk console.obj wsc32.lib -subsystem:console To compile the GUI mode example SIMPLE, lcc -DWIN32 simple.c lcc -DWIN32 about.c lcc -DWIN32 line.c lcc -DWIN32 paint.c lcc -DWIN32 sioerror.c lrc simple.rc lcclnk simple.obj about.obj line.obj paint.obj sioerror.lib wsc32lcc.lib simple.res -subsystem:windowsSee CONSOLE.BAT for an example of a console mode command line batch file and SIMPLE32.BAT for an example of a GUI mode command line batch file. Command files are used for Lcc-Win32 rather than makefiles since the makefile that comes with LCC- Win32 does not work well (unlike the actual compiler).
NMAKE -f WSC16._M_ NMAKE -f WSC32._M_ For Borland C, type: MAKE -f WSC16._B_ MAKE -f WSC32._B_ For Watcom C, type: WMAKE -f WSC16._W_ WMAKE -f WSC32._W_
NMAKE -f SIMPLE16._M_ NMAKE -f SIMPLE32._M_ For Borland C, type: MAKE -f SIMPLE16._B_ MAKE -f SIMPLE32._B_ For Watcom C, type: WMAKE -f SIMPLE16._W_ WMAKE -f SIMPLE32._W_There is also a Microsoft Developer Studio generated makefile for SIMPLE. See SIMPLE.MAK.
If using Microsoft Developer Studio, make these changes:
Alternatively, WSC16.C and WSC32.C can be edited so that they can be compiled and linked in like any other program file. In order to do this, remove all code from WSC16.C and WSC32.C from
#ifndef STATIC_LIBRARY to the following #endif
Many of the example programs are written in Win32 console mode. This was done in order to provide the clearest possible code, without the complication and complexity of GUI code. All console mode programs can be converted to GUI mode by adding the necessary Windows interface code.
Makefiles are classified as follows:
Files ending with .MAK (and .BPR) include:
The first example program is the GUI program WSCVER (WSC Version) which displays the WSC library version number.
There are command line makefiles for Microsoft (WSCVER32._M_), Borland (WSCVER32._B_), and Watcom (WSCVER32._W_), as well as a Microsoft Developer Studio makefile (WSCVER32.MAK), and a Lcc-Win32 command file (SIMPLE32.BAT).
After compiling, from the command line, type:
WSCVER
CONSOLE 1 38400
HOST 1 19200
Version 1.0: September 6, 1996.
Version 2.0: January 25, 1997.
Version 2.1: June 2, 1997.
Version 2.2: October 1, 1997.
Version 2.3: July 15, 1998.
Version 2.4: May 17, 1999.
Version 3.0: July 12, 2000.