MarshallSoft

Windows Standard

Serial Communications

for C/C++

Programmer's Manual


(WSC_4C)


Version 4.3

September 24, 2007



This software is provided as-is.
There are no warranties, expressed or implied.



Copyright (C) 2007
All rights reserved



MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815


Voice : 1.256.881.4630

FAX : 1.256.880.0925

email : info@marshallsoft.com

Web : www.marshallsoft.com


MARSHALLSOFT is a registered trademark of MarshallSoft Computing.



TABLE OF CONTENTS


1 Introduction
1.1 Features
1.2 Documentation Set
1.3 Example Program
1.4 Installation
1.5 Uninstalling
1.6 Pricing
1.7 Updates
2 Library Overview
2.1 Dynamic Link Libraries
2.2 Keycode (License Key)
2.3 Console Mode
2.4 Limitations on COM Ports
2.5 Using the Library
2.6 Static Linking
2.7 Large Memory Model in Win16
2.8 Win32 STDCALL and DECLSPEC
2.9 Using Threads
2.10 Calling WSC Functions from C++
2.11 Adding WSC Functions to an Existing Program
2.12 Error Display
2.13 SioEvent Logic
2.14 Virtual Serial Ports
3 Compiler Issues
3.1 Compiling Using an IDE
3.2 Command Line Tool Setup
3.3 Command Line Batch Files
3.4 Command Line Makefiles
4 Supported Compilers
4.1 Microsoft Visual C++
4.2 Microsoft C++ .NET
4.3 Microsoft C# (C-Sharp)
4.4 Microsoft C/C++ (16-bit)
4.5 Borland C++ Builder
4.6 Turbo C/C++ for Windows
4.7 Borland C++ Builder
4.8 Watcom C/C++
4.9 Lcc-Win32 C/C++
5 Compiling Programs
5.1 Compiling WSC Source Code
5.2 Compiling Example Programs
6 Example Programs
7 Additional Examples
8 Revision History

1 Introduction

The Windows Standard Serial Communications Library (WSC4C) is a component library of functions providing the capability to quickly write serial communication applications in C/C++. The WSC component library uses the standard Windows API (Application Programmer's Interface) to communicate with any device connected to a serial port.

A straight forward interface is provided to access data from a serial port using RS232 or multi-drop RS422 or RS485 ports. WSC also supports virtual serial ports using Bluetooth serial and USB to serial converters.

WSC4C includes more 25 C/C++ example programs demonstrating serial communication functions. Microsoft Foundation Class (MFC), Borland C++ Builder (BCB). Microsoft Visual C++ .NET and Visual C# (C-sharp) examples are also included. WSC4C can also be used with C#.

WSC4C supports and has been tested with Microsoft Visual C++ (all versions including Visual C++.NET and C#), Borland C/C++, Turbo C/C++ for Windows, Borland C++ Builder, Watcom C/C++, and LCC-Win32 compilers. WSC4C can also be used with most other C/C++ Windows compilers.

Both Win16 and Win32 DLLs are provided. The WSC DLLs (WSC16.DLL and WSC32.DLL) can be used from any language (Visual Basic, (VB.NET), Delphi (Delphi .NET), Visual FoxPro, Xbase++, dBase, as well as Access and Excel, etc.) capable of calling the Windows API. WSC4C runs under Windows 95/98/ME/NT/2000/2003/XP. MarshallSoft provides separate products for WIN/CE for eVC (WSC4eVC) and for eVB (WSC4eVB). Evaluation versions for these may be downloaded from our web site at

     http://www.marshallsoft.com/serial-communication-library.htm


Our goal is to provide a robust serial communication component library that you and your customers can depend upon. A fully functional evaluation version is available. Contact us if you have any questions.

When comparing the Windows Standard Serial Communications Library against our competition, note that:

  1. WSC4C is a standard Windows DLL (NOT an OCX or ActiveX control) and is much smaller than a comparable OCX or ActiveX control.
  2. Both WIN16 and WIN32 DLLs are included.
  3. WSC4C does NOT depend on ActiveX or Microsoft Foundation Class (MFC) libraries or similar "support" libraries.
  4. The WIN32 version of WSC is fully threadable.
  5. The WSC functions can be called from applications not capable of using controls.

MarshallSoft also has versions of the Windows Standard Serial Communications Library for Visual Basic (WSC4VB), Delphi (WSC4D), PowerBASIC (WSC4PB), Visual FoxPro (WSC4FP), Visual dBASE (WSC4DB), and Xbase++ (WSC4XB). All versions of WSC use the same DLLs (WSC16.DLL or WSC32.DLL). However, the examples provided for each version are written for the specified computer language.

The latest versions of the Windows Standard Serial Communications Library (WSC) can be downloaded from our web site at http://www.marshallsoft.com/serial-communication-library.htm


1.1 Features

Some of the many features of the Windows Serial Communications Library are:

A good selection of C/C++ example programs with full source code is included. Refer to Section 6 for more details on each of the example programs.

     [PROGRAM]    [DESCRIPTION]
     WSCVER     :  Program that displays the WSC version number.
     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) C++ 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 that uses SioEvent.
     EventC     :  Blocking version of SIMPLE that uses SioEventChar.
     EventW     :  Blocking version of SIMPLE that uses SioEventWait.
     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 host program.
     DIAL       :  Dials up host (or BBS).
     HELLO      :  Example program which uses the C++ fSio class.
     VC_VERSION :  Visual C++ .Net version of the WSC version program (WSCVER).
     VC_SIMPLE  :  Visual C++ .Net version of the simple terminal program (SIMPLE).
     CS_VERS    :  C# program that displays the WSC version number.
     CS_AT_OK   :  C# program that transmits "AT" and expects "OK" back.

1.2 Documentation Set

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 WSC_4C Programmer's Manual is the language specific (C/C++) manual dealing with compiler and programming issues such as installation and example programs. Read this manual first.

The WSC User's Manual (WSC_USR) discusses language independent serial communications programming issues including modem control. Purchasing and license information is also provided.

The WSC Reference Manual (WSC_REF) contains details on each individual WSC function.

The Serial Communications Manual (SERIAL) contains background information on serial port hardware.

Use Microsoft Word or Microsoft WordPad to print the document files. All manuals can also be viewed online at http://www.marshallsoft.com/wsc4c.htm

1.3 Example Program

The following example demonstrates some of the Windows Serial Communications library functions.

     #include <windows.h>
     #include <stdio.h>
     #include "wsc.h"
     void main(void)
     {int  Code;
      SioKeyCode(0); // 0 is evaluation version key code
      // reset (open) COM1
      Code =  SioReset(COM1,1024,1024);
      if(Code<0)
        {char Temp[80];
         // display error message
         SioWinError((LPSTR)Temp,80);
         printf("ERROR %d : %s\n",Code,(LPSTR)Temp);
         SioDone(COM1);
         exit(1);
        }
      // set the DTR line
      printf("Setting DTR\n");
      SioDTR(COM1,'S');
      // wait for user to quit
      printf("Type any character to exit.\n");
      getch();
      // close port
      SioDone(COM1);
     } /* end main */

Refer to section 6.0 for complete examples with source.

1.4 Installation

  1. Before installation of WSC4C, your Windows C/C++ compiler should already be installed on your system and tested. In particular, include command line tools when installing your compiler if you want to compile using command line makefiles. If you need help with makefiles, see MAKEFILE.TXT.

  2. Unzip WSC4C43.ZIP (or WSCxxxx.ZIP where xxxx is your Customer ID) using any Windows unzip program.

  3. Run the installation program SETUP.EXE which will install all WSC4C files, including copying WSC16.DLL and WSC32.DLL to your Windows directory. No Windows system files are modified. Note that no DLL registration is required.

All recent WIN32 C/C++ compilers support the "declspec" keyword. Microsoft Visual C++ (version 4.0 and up), Borland (version 5.0 and up), Watcom (version 11.0 and up), and Lcc-Win32 compilers support the "declspec" keyword. If you have an older Win32 compiler, you can get the legacy DLL's from our web site at

   
      www.marshallsoft.com/serial-communication-library.htm
   

1.5 Uninstalling

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 95/98/Me/XP and C:\WINNT for Windows NT/2000. That's it!

1.6 Pricing

A developer license for WSC4C can be registered for $115 (or $195 with ANSI C source code to the library DLL's). Purchasing details can be found in Section 1.3 "How to Purchase" in the WSC User's Manual (WSC_USR). Also See INVOICE.TXT or http://www.marshallsoft.com/order.htm

1.7 Updates

When you register WSC4C you will receive a set of registered DLLs plus a license file (WSCxxxx.LIC) that can be used to update your registered DLL's for a period of one year from purchase. Updates can be downloaded from

   
     http://www.marshallsoft.com/oem.htm
   

After one year, your license must be updated if you want to be able to download updates. Your license can be updated for :

Updates to the source code can be purchased for $40 additional. Note that the registered DLL's never expire.

2 Library Overview

2.1 Dynamic Link Libraries

The WSC4C serial communication library component 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 that is bound to each and every application that uses it at link time.

An important advantage that DLL's have over other "popular" library formats such as VBX or OCX is that DLL's are callable by all Windows applications. Since DLL's are the building blocks of the Windows Operating System, they will not be replaced by a "newer technology".

2.2 Keycode (License Key)

WSC16.DLL and WSC32.DLL each has a keycode encoded within them. Your keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.H. The keycode for the evaluation (shareware) version is 0. You will receive a new keycode and a set of new DLL's when registering. The KEYCODE is passed to SioKeyCode.

If you get an error message (value -108) when calling SioKeyCode, it means that the keycode in your application does not match the keycode in the DLL. After registering, it is best to remove the evaluation version of the WSC32.DLL and WSC16.DLL from the Windows search path or delete them.

2.3 Console Mode

WSC4C functions can be called from Win32 console mode programs. A "console mode" program is a Windows 95/98/NT/2000/Me/XP WIN32 command line program running in a command window. Although console mode programs look like DOS programs, they are WIN32 programs that have access to the Win32 API and the entire Windows address space. Programming using console mode programs reduces the complexity of using GUI code. All console mode programs can be converted to GUI mode by adding the necessary Windows interface code

2.4 Limitations on COM Ports

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

2.5 Using the Library

The Windows Standard Serial Communications Library (WSC) has been tested on multiple computers running Windows 95/98/Me/XP/Vista, and Windows NT/2000.

The WSC4C library has also been tested with several C/C++ compilers, including Microsoft Visual C/C++ (all versions including C++ .NET and C#), Borland C/C++, Borland C++ Builder, Turbo C/C++ for Windows, and Watcom C/C++.

The SETUP installation program will copy the Lib's and DLL's to your Windows directory. Refer to Section 1.4 "Installation".

"Legacy DLL's" required by Borland C/C++ 4.0/4.5 and Watcom 10.5/10.6 can be downloaded from our web site at www.marshallsoft.com/wsc4c.htm

2.6 Static Linking

The registered user can statically link WSC so that the DLL is not needed. Static linking requires the object file version (WSC32.OBJ) of the DLL (included in the registered package) or source code. To create an application that links WSC32.OBJ (or WSC16.OBJ) statically:

Make sure that all application code that includes WSC.H must define STATIC_LIBRARY before including WSC.H

If using Microsoft Developer Studio, make these changes:

  1. To the project file: Do NOT add WSC32.LIB to your project file.
  2. To the settings: (See "Build Settings" or "Project/Settings")
  3. C/C++ Tab: Add STATIC_LIBRARY to "preprocessor definitions:".
  4. Link Tab: Add WSC32.OBJ to "object/library modules:".
  5. Add #include "wsc.h" to all source files that make calls to WSC functions.

Alternatively, WSC16.C and WSC32.C can be edited so that they can be compiled and linked like any other program file. In order to do this, remove all code from WSC16.C and WSC32.C (provided when the source code is purchased) from


     #ifndef STATIC_LIBRARY


through the following

     #endif


2.7 Large Memory Model in Win16

WSC16.DLL can be used withWin16 programs written in any memory model. Two examples are included in this archive for compiling SIMPLE.C for the large memory model.

     [FILE]            [DESCRIPTION]
     SIMPLE16._ML   :  Large memory model makefile for Microsoft
     SIMPLE16._BL   :  Large memory model makefile for Borland.


2.8 Win32 STDCALL and DECLSPEC

WSC32 is compiled using the _stdcall and _declspec keywords. This means that WSC4C uses the same calling conventions and file naming conventions as the Win32 API. In particular, function names are NOT decorated. There are not any leading underscores or trailing "@size" strings added to function names.

Microsoft Visual C++ users can look at the WSC32 function names using the dumpbin.exe executable:

     dumpbin /exports wsc32.dll

Some 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

2.9 Using Threads

WSC4C is thread safe. Refer to the ECHOPORT.C example program, which demonstrates the use of multiple threads. ECHOPORT also demonstrates the use of the WIN32 Sleep() function.

Also examine the EVENT.C example program, which uses both threads and the SioEvent function.

2.10 Calling WSC functions from C++

Like Windows itself, WSC functions are coded in ANSI C, but they can be called directly from both ANSI C programs and from C++ programs.

WSC functions can also be called using the C++ class wrapper fSio. Refer to HELLO.CPP for an example.

2.11 Adding WSC Functions To Your Existing Program

In order to call WSC functions from an existing program, (1) add

#include "wsc.h"

to your application source code, (2) link with WSC32.LIB (for MSVC), WSC32BCB.LIB (Borland C/C++ and C++ Builder), WSC32.LIB (Watcom), or WSC32LCC (Win32/LCC), and recompile from source.

Refer also to Section 4.0 below.

2.12 Error Display

The error message text associated with WSC error codes can be displayed by calling SioError (refer to sioerror.c and paint.c) in GUI mode applications or SayError (see SayError.c) in console mode applications. Each sample program contains examples of error processing.

2.13 SioEvent Logic

SioEvent, SioEventChar, and SioEventWait will block until the specified event occurs. If a call to SioEvent, SioEventChar, or SioEventWait is placed in a thread, then the thread will block but the application calling the thread will not.

See the Event.c, EventChar.c, and EventWait.c example programs.

2.14 Virtual Serial Ports

A "virtual" serial port is COM port that appears to be a real RS232 serial port to the Windows API (and thus to WSC), but is in reality a COM port emulator.

The two most common virtual ports are those created for USB/serial port converters and Blue Tooth. WSC will work with most USB to serial port converts and with Bluetooth serial.

More information about Virtual serial ports can be found in Section 2.12 of the WSC User's Manual (WSC_USR). (http://www.marshallsoft.com/wsc_usr.htm#Section_2.12 )


3 Compiler Issues

Windows Serial Communications Library (WSC) applications can be compiled using an IDE or command line compiler tools. The following sections provide general compiler information.

3.1 Compiling Using an IDE

All current windows compilers have an "Integrated Development Environment" (IDE) for building application programs in the Windows environment.

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.

3.1.1 Compiling Example Programs with an IDE

Most of the example programs can be compiled from your compiler's IDE. For Visual C/C++, "project makefiles" are used since they can be used by all versions of Visual C/C++ (v4.0, v5.0, and v6.0). When opening the workspace, select Makesfiles(.mak) for the file type.

Alternatively, for VC++ v6.0, select "projects (.dsp)" for the file type.

3.1.1 Compiling New Projects with an IDE

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. Refer to Section 4 below for a particular IDE.

3.2 Command Line Tool Setup

Many software developers overlook the power of using command line compilers. There are a number of very significant advantages to using the command line version of your C/C++ compiler. Among these are:

In order to compile from the command line the command line compiler tools must be set up properly. Note that you have an option of installing the command line tools (or not) when your compiler is first installed. Refer to the compiler manufacturer's manual for details.

If necessary, the size of the environment table space can be increased (to 1024 for example) by adding

     SHELL=C:\COMMAND.COM /e:1024 /p


to CONFIG.SYS in C:\ and then rebooting. Yes, this works for all versions of Windows, including Windows NT, 2000, and XP

For all compilers, your path should point to the compiler's BIN directory. For example, to add "C:\BC50\BIN" to your existing path, use


     PATH C:\BC50\BIN;%PATH%


3.2.1 Microsoft

Set LIB and INCLUDE environment variables. For example,

     SET INCLUDE=C:\MSVC\INCLUDE
     SET LIB=C:\MSVC\LIB

3.2.2 Borland

Check that TURBOC.CFG, BCC32.CFG, TLINK.CFG, and TLINK32.CFG all have the correct information in them, as they should have when your compiler was installed. For example, assuming your BC compiler is installed at C:\BC5, the INCLUDE (-I) and LIB (-L) paths are specified by:

     -IC:\BC5\INCLUDE
     -LC:\BC5\LIB

BRCC (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=


3.2.3 Watcom

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

3.2.4 LCC-Win32

The LCC environment variables are set like the others. For example,

     SET INCLUDE=C:\LCC\INCLUDE
     SET LIB=C:\LCC\LIB

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

3.3 Command Line Batch Files

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 SIMPLE$.BAT for an example of a command line batch file for Lcc-Win32. Similarly, command line batch files can be created for all of the example programs.

3.4 Command Line Makefiles

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 always coded within the makefile and the makefile can be run with a single keystroke. Refer to Section 4.0 for in

Command line makefiles are provided for Microsoft, Borland, Watcom, and LCC-Win32 command line compilers. They can be found in the APPS sub-directory:

     borland50.zip     Borland C/C++ 5.0 makefiles.
     borland55.zip     Borland C/C++ 5.5 makefiles.
     c-builder.zip     Borland C++ Builder project makefiles.
     lcc-win32.zip     LCC-WIN32 project command files.
     microsoft60.zip   Microsoft C/C++ (v1.52, v4.0, v5.0, v6.0) makefiles.
     watcom11.zip      Watcom C/C++ 11 makefiles.


4.0 Supported Compilers

WSC4C has been tested with Microsoft Visual C++ (all versions including Visual C++ .Net and C# .NET)), 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. Refer also to Section 5, "Compiling Example Programs".

4.1 Microsoft Visual C++ (all versions)

Microsoft Visual C++ programs can be compiled from either the command line or from within the Microsoft Visual Studio development environment. All MSVC programs are Win32 only.

4.1.1 Microsoft Command Line Makefiles

Programs can be compiled using command line makefiles. All Microsoft Win16 command line makefiles end with "16._m_" while Win32 command line makefiles end with '32._m_". To compile using a makefile, use the Microsoft NMAKE utility. For example,

     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

The file, microsoft60.zip, contains the Microsoft C/C++ (v1.52, v4.0, v5.0, v6.0) command line makefiles.

4.1.2 Microsoft Developer Studio (VC v4.0)

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++ project makefiles, ending with ".MAK" , such as

     WSCVER.MAK
     SIMPLE.MAK

To create a new project in MSVC v4.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".

NOTE: Be sure to specify /YX rather than /Yu in your project settings [Build, Settings..., C/C++].

4.1.3 Visual Studio (VC v5.0 and v6.0)

To create a new project in MSVC v5.0 or v6.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".

If the compiler complains that it cannot find "_main", "Console Application" was chosen but the program being compiled is a GUI application. If the compiler complains that it cannot find "WinMain", "Application" was chosen but the program being compiled is a Console Mode application.

NOTE: Be sure to specify /YX rather than /Yu in your project settings [Build, Settings..., C/C++].

4.2 Microsoft Visual C++ .NET

All Visual Studio VC.Net projects end with extension ".vcproj". For example,

     vc_version.vcproj
     vc_simple.vcproj
     vc_xms.vcproj
     vc_xmr.vcproj

In order to open an existing Visual C++ .Net project, choose "File", "Open", and then "Project" from the Visual Studio menu. Specify the directory containing the Visual C++ .Net project files (for example, C:\WSC4C\APPS).

In order to call WSC functions from Visual C++ .Net programs, do the following to your existing Visual C++ .Net project:

  1. Add
     #include "wsc.h"
     #include "keycode.h"
   
after your existing #include statements.

  1. Open the project properties window under "Project" on the main menu. If your project is named "MyProject", then select "MyProject properties".

  2. Select "Configuration Properties", "Linker", "Input", "Additional Dependencies", then type in "WSC32.LIB" into the edit box. Note that WSC32.LIB must be in your project directory along with all of your source files.

  3. Rebuild.

NOTE: If using pre-compiled headers, the include statement

     #include "stdafx.h"
   
must be the first include statement in your program.


4.3 Microsoft C# (C-Sharp)

WSC functions can be called from C# (C-sharp) in the same manner as Win32 API functions.

All C# projects end with extension ".csproj". For example,

cs_vers.csproj

In order to open an existing C# project, choose "File", "Open", and then "Project" from the Microsoft C# Development Environment.. Specify the directory containing the C# project files (for example, C:\WSC4C\APPS).

In order to call WSC functions from your C# programs, do the following to your existing C# source code:

Add the contents of file wsc_funs.cs to source code after


     public class wsc : System.Windows.Forms.Form


Add the constants from wsc_cons.cs to your program as they are needed.

Look at the cs_vers program in the APPS directory for an example.

Note that if pointers are to be passed to C# programs, the C# programs must be compiled in "unsafe" mode. This is necessary only when calling those functions (such as SioPuts, SioGets, SioWinError) that pass pointers.

4.4 Microsoft C/C++ (16-bit only)

Microsoft (16-bit) C/C++ programs can be compiled from either the command line or from within the Microsoft development environment.

The last Win16 Microsoft compiler was version 1.52. All Microsoft Visual C/C++ compilers (beginning with Visual C/C++ version 4.0) compile Win32 programs ONLY. MSVC 1.52 was distributed with MSVC 4.0.

Earlier versions of Microsoft C/C++ preceding Visual C/C++ can also be used to compile the example programs.


4.4.1 Microsoft Command Line Makefiles

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

Use Visual C/C++ to compile 32-bit MFC programs.

The file, microsoft60.zip, contains the Microsoft C/C++ (v1.52, v4.0, v5.0, v6.0) command line makefiles.


4.5 Borland C/C++

Borland C/C++ version 5.0 programs can be compiled from either the command line (using makefiles ending with "._b_") or from within the Borland development environment using Borland v5.0 or above.

In order to use WSC with Borland C/C++ Version 4.0 or Version 4.5, you will have to download the legacy DLLs for Borland from our web site at http://www.marshallsoft.com/wsc4c.htm

Borland C/C++ Version 5.5 (which can be downloaded from www.borland.com) is a free Win32 console mode compiler (no IDE). Makefiles for BC v5.5 end with "._i_", and (like Borland C++ Builder) use ILINK32 rather than TLINK32. Be careful with linker response files (*.RSP) -- they must NOT end with a carriage return / line feed!

Borland programs always link with WSC32BCB.LIB.

4.5.1 Borland Command Line Makefiles

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_" (or "32._i_" for Borland 5.5). To compile using a makefile, use the Borland MAKE utility. For example,

     MAKE -f SIMPLE16._B_
     MAKE -f SIMPLE32._B_

The file, borland50.zip, contains the Borland C/C++ 5.0 command line makefiles, and
the file, borland55.zip, contains the Borland C/C++ 5.5 command line makefiles.

4.5.2 Borland IDE

To 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 "Files", then "New Project". Use the INS (Insert) key to pop up a dialog box into which the project file names are entered. Lastly, add WSC32BCB.LIB to your project. WSC32BCB.LIB can also be created from WSC32.DLL using the Borland IMPLIB utility:

   
     IMPLIB WSC32BCB.LIB WSC32.DLL
   

Select "GUI" or "Console" for the "Target Model:". Only "Static" or "Dynamic" should be checked for "Standard Libraries:"

NOTE1: If, after linking in the IDE, you get unresolved external references to the library functions in which each function name is all upper case, then you have NOT turned off case sensitivity as described above.

NOTE2: If you get errors compiling the windows header file "WINDOWS.H", turn on "Borland Extensions" in "Options", "Project", "Compiler", "Source".

4.6 Borland Turbo C/C++ for Windows

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.

4.7 Borland C++ Builder

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 BCB_PRJ with BCB_PRJ.MAK if running BCB version 1 through 3, and compile with BCB_PRJ.BPR if running BCB version 4 or above.

To load the BCB_PRJ example project, Choose "File" / "Open Project" on the menu bar. Load BCB_PRJ.MAK (or BCB_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

The file c-builder.zip contains the Borland C++ Builder project makefiles.

4.8 Watcom C/C++

Watcom C/C++ programs can be compiled from either the command line or from within the Watcom development environment.

Watcom v10.5and v10.6 do not recognize the "declspec" keyword, and there require "legacy DLL's", which can be downloaded from www.marshallsoft.com/wsc4c.htm

4.8.1 Watcom Command Line Makefiles

Win32 programs can be compiled using command line makefiles. All Watcom command line makefiles end with "32._w_" for Win32 makefiles. To compile using a makefile, use the Watcom WMAKE utility. For example,


     WMAKE -f SIMPLE32._W_


Win32 programs can also be compiled using command line batch files. See SIMPLE$.BAT for an example of a console mode command line batch file and SIMPLE$.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

The file, watcom11.zip, contains the Watcom C/C++ 11 command line makefiles.

4.8.2 Watcom IDE

To create a new project, choose "File", then "New Project". Enter the project name and then choose Win32 as the target. Use the INS (Insert) key to pop up a dialog box into which the project file names are entered.

Select "Options" from the main window, then "C Compiler Switches", then "10". Memory Models and Processor Switches". Check "80386 Stack based calling [-3s]", then check "32-bit Flat model [-mf]".

4.9 LCC-Win32 C/C++

Lcc-Win32 C/C++ programs can be compiled from either the command line or from within the development environment.

Lcc-Win32 is a freeware C compiler developed and distributed by Jacob Navia at


     http://www.cs.virginia.edu/~lcc-win32/


To use our DLL's 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:windows


See CONSOLE.BAT for an example of a console mode command line batch file and SIMPLE$.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).

The file, lcc-win32.zip, contains the LCC-WIN32 project command files.

5 Compiling Programs

5.1 Compiling WSC Source Code

This section applies only to those who have purchased source code for WSC.

WSC16.DLL and WSC32.DLL have been compiled using Microsoft Visual C/C++, and are callable from applications written using Microsoft, Borland, or Watcom compilers. If you recompile WSC32.C using Borland or Watcom compilers, then the resulting WSC32.DLL can only be used by applications compiled with the same compiler, unless the "_stdcall" and "_declspec" keywords are specified.

For Microsoft C, type:

     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_

5.2 Compiling Example Programs

The example programs can be compiled by using either the command line compiler or the compiler integrated development environment (IDE). Most compiler vendors provide both IDE and command line tools, although some compilers are command line only (Borland C/C++ 5.5 and LCC-Win32) or IDE only (Borland C/C++ Builder).

Refer also to Section 4, "Supported Compilers".

5.2.1 Compiling Using Visual C/C++ (VC v4.0, v5.0, and v6.0)

Microsoft Visual C/C++ (v4.0, v5.0, v6.0) compiles only 32-bit programs.

Programs can be compiled with Microsoft Visual C/C++ using either Developer Studio / Visual Studio or the command line compiler. Project makefiles (files ending in ".MAK") are provided for Developer Studio / Visual Studio. Command line makefiles (files ending in "._M_") are provided for use with the command line compiler (eg: NMAKE -f SIMPLE32._M_).

5.2.2 Compiling Using 16-bit Visual C/C++ (VC v1.52)

Microsoft Visual C/C++ v1.52 compiles only 16-bit applications. Command line makefiles are provided with several 16-bit example programs (eg: NMAKE -f SIMPLE16._M_).

5.2.3 Compiling Using Visual C/C++ .Net

Microsoft Visual C/C++ >NET compiles only 32-bit programs.

Programs can be compiled with Microsoft Visual C/C++ .NET using either Visual Studio .NET or the command line compiler. Project files (files ending in ".VCPROJ") are provided for Visual Studio (eg: VC_SIMPLE.VCPROJ).

Command line makefiles (files ending in "._M_") are provided for use with the VC.NET command line compiler (eg: NMAKE -f SIMPLE32._M_).

5.2.4 Compiling Using Borland C/C++ 5.0

Borland C/C++ 5.0 can compile both 32-bit and 16-bit programs.

Programs can be compiled with Borland C/C++ using either the Borland IDE or the command line compiler. Several Project files (files ending in ".IDE") are provided for the Borland IDE (unzip BC50-IDE.ZIP)and command line makefiles (files ending in "._B_") for the Borland command line compiler. For example (MAKE -f SIMPLE32._B_)

5.2.5 Compiling Using Borland C/C++ 5.5

Borland C/C++ 5.5 is a command line compiler that can compile both 32-bit programs only. Command line makefiles (ending in "._I_") are provided For example (MAKE -f SIMPLE32._I_)

5.2.6 Compiling Using Borland C++ Builder

Borland C++ Builder (BCB) is an IDE that features "drag and drop" forms building (like Delphi and Visual Basic).

BCB compiles 32-bit programs only. Compile the BCB example program BCB_PRJ with BCB_PRJ.MAK if running BCB version 1 through 3, and compile with BCB_PRJ.BPR if running BCB version 4 or above.

The file c-builder.zip contains the Borland C++ Builder project makefiles.

5.2.7 Compiling Using Watcom 11

Programs can be compiled with Watcom 11 using either the Watcom IDE or the command line compiler. Several command line makefiles (files ending in "._W_") for the Watcom command line compiler. For example (eg: WMAKE -f SIMPLE32._W_)

5.2.8 Compiling Using LCC-WIN32

LCC-Win32 compiles only 32-bit C (not C++) programs.

Command line batch files (ending with "$.bat) are provided for several of the projects. For example, to compile SIMPLE using LCC-Win32, type SIMPLE$.BAT on the command line.


6 Example Programs

Some of the example programs are written in GUI mode (WSCVER, BCB_PGM, MFC_PGM, TERM, MODEM , SELFTEST, SIMPLE), although most 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. Example programs are located in the APPS directory. Refer to Section 4.0 for help with compiling and using makefiles.

Makefiles are classified as follows:

Microsoft Visual C/C++ Developer Studio files end in ".MAK" and can be loaded with "Open Workspace" and include: simple.mak, modem.mak, term.mak, console.mak, event.mak, rs485.mak, xms.mak, xmr.mak, yms.mak, ymr.mak, finder.mak, echoport.mak, host.mak, device.mak, wscver.mak, dial.mak, & hello.mak.

Other files ending with .MAK (and .BPR) include:

6.1 WSCVER

The first example program is the GUI program WSCVER (WSC Version) that displays the WSC library version number. It's purpose is to display the WSC version, build, and registration string as well as to verify that WSC32.DLL (or WSC16.DLL for 16-bit apps) is being found and loaded by Windows.

There are command line makefiles for Microsoft (WSCVER32._M_), Borland (WSCVER32._B_), and Watcom (WSCVER32._W_), as well as a Microsoft Developer Studio makefile (WSCVER.MAK), and a Lcc-Win32 command file (WSCVER$.BAT).

Open project VC_VERSION.VCPROJ if using Visual C/C++ NET.

6.2 SIMPLE

SIMPLE is a very simple GUI mode communications program using WSC4C. Everything 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.

Open project VC_SIMPLE.VCPROJ if using Visual CC++ NET.

6.3 SELFTEST

SELFTEST is a GUI mode program that performs serial port I/O functionality testing using a loopback adapter. Refer to LOOPBACK.TXT for an explanation of how to make a loopback adapter (without tools!).

6.4 MODEM

MODEM is a GUI mode program that is similar to SELFTEST, 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 & receive queue sizes, detect a break signal, detect changes in DSR and CTS. It can also check for various line errors such as parity error, framing error, data overrun, receive queue overflow, and transmit buffer full.

6.5 TERM

TERM is a simple GUI mode ANSI terminal emulator suitable for calling up a BBS and downloading or uploading files using XMODEM or YMODEM. The TERM program uses MIO16.DLL (or MIO32.DLL) for modem control commands, and XYDRV16.DLL (or XYDRV32.DLL) for XMODEM & YMODEM file transfer.

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.

TERM uses ANSI.C, which provides ANSI terminal emulator support.

6.6 BCB_PGM

BCB_PGM is a Borland C++ Builder example GUI mode program similar to SIMPLE. BCB_PRJ.MAK is the BCB makefile necessary for building BCB_PGM.EXE.

6.7 MFC_PGM

MFC_PGM is a Microsoft Foundation Class C++ (GUI mode) program similar to SIMPLE. MFCPGM16.MAK is the Win16 makefile and MFCPGM32.MAK is the Win32 makefile. File NAFXCW.LIB may have to be copied from MFC\LIB on your Microsoft Visual C/C++ CD disk.

6.8 CONSOLE

The CONSOLE program is a console mode program similar to SIMPLE. It also demonstrates how to acquire and manipulate the standard input handle so that a "KeyPress" function can be implemented.

CONSOLE takes the port and baud rate as arguments. For example, to start CONSOLE on COM1 at 38,400 baud:


     CONSOLE 1 38400


6.9 FINDER

The FINDER program is a console mode 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.


6.10 ECHOPORT

The ECHOPORT console mode program which demonstrates the use of threads. Connect COM1 and/or COM2 to another computer or serial device using a NULL modem cable. ECHOPORT will echo back to the remote anything that it receives on the serial port. ECHOPORT takes no arguments.

6.11 EVENT, EventC, EventW

The EVENT console mode program demonstrates the use of SioEvent in efficiently waiting for serial input. SioEvent blocks until the requested event occurs.

Also see the EventC example program that uses SioEventChar and the EventW example program that uses SioEventWait.

6.12 XMS, XMR, YMS, YMR

XMS (XMODEM Send) and XMR (XMODEM Receive) are console mode programs that send and receive files using the XMODEM protocol. YMS (YMODEM Send) and YMR (YMODEM Receive) are console mode programs that send and receive files using the YMODEM protocol.

Open project VC_XMS.VCPROJ or VC_XMR.VCPROJ if using Visual C/C++ NET

6.13 RS485

The RS485 example console mode program operates like SIMPLE, except that it assumes an RS485 port. RTS is set before transmitting data, and cleared after the last bit of the last byte has been sent.

6.14 DEVICE

The DEVICE console mode 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.

6.15 HOST

The HOST console mode program is a simple example of a one-line BBS, which is capable of answering an incoming call. HOST uses both WSC32.DLL and MIO32.DLL. Start HOST from the command line passing the port and baud rate. For example,


     HOST 1 19200


6.16 DIAL

The DIAL console mode example program uses the MIO module to dial up using the port, baud rate, and phone number specified by the user on the command line. For example


     DIAL 1 38400 "1,256,880,9748"


6.17 HOST

The HOST console mode program answers an incoming modem call. It functions as a very simple BBS (Bulletin Board System) program.


6.18 CS_VERS

The CS_VERS example program is the (console mode) C# equivalent of the WSCVER example program. It displays the WSC32.DLL Version, Build #, and registration string and also demonstrates how to call WSC functions from within C# programs.

Also see section 4.3 "Microsoft C#" above.

Load project CS_VERS.CSPROJ

6.19 CS_AT_OK

The CS_AT_OK example C# program transmits the 3 byte character string "AT\n" on COM1 at 19200 baud. After sleeping a short period of time, the port is read for any response.

This example program demonstrates how to send and receive using SioPutc and SioGetc from a C# application program.

Recall that if "AT\n" is sent to a modem where word response codes are enabled, the string "OK" (without the quotes) will be returned by the modem.

Note that the program must be compiled using the "/unsafe" C# keyword.

Also see section 4.3 "Microsoft C#" above.

Load project CS_AT_OK.CSPROJ

6.20 CS_AT_OK_2

The CS_AT_OK example C# program is similar to CS_AT_OK, except that it uses the SioByteToShort and SioShortToByte functions.

Load project CS_AT_OK_2.CSPROJ

6.21 LoadLib

The LoadLib console mode example program demonstrates how to load WSC functions dynamically from a specified location.

6.22 Callback

The Callback example program demonstrates how to implement a WSC callback function. The code necessary to perform the callback is encapsulated in the SioCallback.c file.


7 Additional Examples

We have other examples programs including programs for controlling voice modems (which use the Rockwell voice/data chip set), an example of handling continuously incoming data, and others. Please contact us if you need an example program not listed above.

8 Revision History

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.

Version 3.1: April 19, 2001.

Version 3.2: July 17, 2002.

Version 3.3: October 28, 2003.

Version 4.0: November 12, 2003.

Version 4.1: August 12, 2004

Version 4.2: February 1, 2006.

Version 4.3: September 24, 2007.