ADR Socket Demo
===============
By: John Homppi - April 16, 1999 - Copyright Sisusypro Inc.

This demo shows the use of a TCP/IP link to access an ADR card on
a remote computer. It has been tested on Windows NT and Windows 95.

The demo consists of 2 programs:
ADRSockSrv is the server that runs on the computer hooked up to the
ADR card.
ADRSockClient is the client that runs on the remote computer.

The client program accepts a command parameter, transmits it
across the network to the server program which issues it to the
ADR card. An optional response from the ADR card is transmitted
back to the client program for display on the screen.

Installation
============
You must already have a working TCP/IP protocol stack on your
computer(s) before you install this demo. I will not endeavour to
teach you how to configure Internet protocols.
 
These instructions assume a familiarity with DOS commands.

1) Place the ADRSockSrv.exe on the server computer.
2) Place the ADRSockClient.exe on the client computer.
3) on both computers add the following at the bottom of the SERVICES file
ADRlink 20025/tcp
(see the ADRSockets\Samples sub-directory for a sample SERVICES file)
4) on the client computer add the following line to the bottom of HOSTS file
myserver 10.0.0.1
NOTE: replace myserver with the name of your server computer
      replace 10.0.0.1 with the IP address of your server computer
NOTE: to discover the IP address:
      in NT type IPCONFIG on the server computer at a command prompt
      in 95 type WINIPCFG on the server computer at a command prompt
(see the ADRSockets\Samples sub-directory for a sample HOSTS file)
5) on the server computer, 
(a) open a Command Prompt (DOS Prompt in Win95) window
(b) navigate to the directory containing ADRSockSrv.exe
(c) enter the command
ADRSockSrv 2
replacing 2 with the serial port number that the ADR card is connected to
(d) check that the screen says "accepting a socket"

6) on the client computer
(a) open a Command Prompt window
(b) navigate to the directory containing ADRSockClient.exe
(c) enter the command
ADRSockClient myserver y pa
replacing myserver with the name of your server computer. This causes
the ADR card to execute the "pa" command.

You will see a variety of messages on both the client and server Command
Prompt windows. Many of these were intended for myself as a learning aid. 
(see History below). Please focus on the output line labeled 
"value received is:".
Sorry if this causes confusion.

Usage
=====
The available commands depend on the model of ADR card that is connected.
See your hardware documentation. 
For program help enter the following in a Command Prompt window
ADRSockSrv /?
or
ADRSockClient /?

Notes
=====
(1) on Windows NT the SERVICES file is located at:
        C:\WINNT\SYSTEM32\DRIVERS\ETC\SERVICES
    on Windows 95 the SERVICES file is located at
        C:\WINDOWS\SERVICES

(2) on Windows NT the HOSTS file is located at:
        C:\WINNT\SYSTEM32\DRIVERS\ETC\HOSTS
    on Windows 95 the HOSTS file is located at
        C:\WINDOWS\HOSTS

(3) use any ASCII text editor to change the SERVICES and HOSTS files

(4) The client and server can be run on the same computer
for testing. The protocol stack will simply "loop-back"
the TCP/IP messages.


Sample Output
=============

Server output:

C:\ADRSockets>adrsocksrv 2
server is now listening
 accepting a socket
socket 92 accepted as fd = 56
 Message received: LL:4 Data: ypa
Reply: 007
terminating socket 56
 accepting a socket

Client output:

C:\ADRSockets>adrsockclient sisu001 y pa
Today is Friday, day 16 of April in the year 1999.
OS time:                                08:48:40
value received is: 007

Non-responsive Commands
=======================
On the server you may see the following messages

Read of serial port failed: RC=1, Bytes read=0, Error=0
error invoking ReadComPort
Reply: No Response

This usually occurs because the client asked for a response for
a command that generates no response. The ADR socket server 
program does not care what commands are supported by your model
of ADR card. It merely writes the command to the serial port
and, if requested, tries to read a reply from the serial port.
When the read operation times out, then the client is sent the
reply "No Response".

Note: If the client does not ask for a reply for a responsive
command then the reply from the ADR card is left sitting in the
serial port input buffer. When the server reads the reply for the
next command, it may incorporate both responses. To avoid this 
you should request the reply for responsive commands. Use a "y"
as the second parameter to the ADRSockClient program to request
a response.  
(P.S. You can request a reply for ALL commands, the only penalty 
is a slight delay for the time-out while reading the serial port 
for non-responsive commands) (I could fix this but then the 
server program would have to be aware of the command sets of the
various models of ADR card.)

Required DLL's
==============
MSVCRT.DLL
WSOCK32.DLL 
plus other standard Windows DLL's
Note: My first version of the ADR sockets demo linked to the WS2_32.DLL
but I quickly discovered that this DLL was not installed on a default
Windows 95 system. For wider portability the demo uses Windows Sockets 
Version 1.1 from the WSOCK32.DLL.

Trouble Shooting
================
1) Test your TCP/IP set up. 
(a) start up a Command Prompt window on your server
(b) ping the server with the command
PING 10.0.0.1
where 10.0.0.1 is the IP address of the server
or
PING myserver
where myserver is the name of the server
If the PING request times out then TCP/IP is not configured properly
on the server.

2) Repeat step 1) on the client
If the PING request times out then TCP/IP is either not configured
properly on the client or the network connection is not operational.

3) make sure that your ADR card is hooked up properly. See your
hardware documentation (re: HyperTerminal)

4) make sure that the serial port is not being used by some other 
program. (eg. close HyperTerminal after testing the serial port)

History
=======
This demo is based on code that I wrote for myself as a learning exercise.
This results in some rather arcane output messages on the screen.

The TCP/IP socket code is extracted from a client/server demo that I
wrote for a DEC Ultrix/Nextstep environment. The server simulated a useful 
task by sleeping for 500 milli-seconds. This code was later implemented 
with minor changes on IBM AIX, SUN OS and some flavour of HP machine. My
first step in a new environment was always to port my learning apps before 
anything complex. You might rightly have guessed that the demo is written
in plain generic C code to ensure portability. (C++ can be ported but not 
as easily; especially difficult is Nextstep's Objective C).

Unfortunately management then wanted to use Windows.... not such an easy
port. What! A port from Nextstep to Windows! Yes, it is true! (The company
shall remain nameless.) 
I learned the joys of Windows socket architecture and its restrictions
in a 16-bit, co-operative processing environment. (Blah, the bad old days). 

The ADR serial port code is extracted from a demo that I provided to Ontrak
Control Systems Inc. The serial port demo was built with Visual C++ and MFC.
That demo encapsulated the serial port in a C++ class, but it was physically
accessed using standard Win 32 API calls. This made it easy to incorporate 
with the plain C sockets demo. (You can see the MFC C++ serial port example 
at WWW.ONTRAK.NET in their programming section).

The final result is a demo that is a patchwork of coding styles and varying 
user interfaces.  

Multi-threading
===============
I wrote a multi-threaded version of the original UNIX demo that I ported 
to the Windows environment. (Round-robin scheduling of a fixed number of 
pre-allocated threads). However I have not expanded it to access the 
serial port. Concurrent commands from a single client program are not 
very valuable... it is after all a "SERIAL" port. 

My preliminary testing shows that the server responds to commands from a couple
of client computers before the IP times out. This uses the TCP/IP buffers as a 
kind of queuing mechanism.
However if multiple client machines or programs exist then it may be safer to 
have the server program queue up the commands rather than to risk refusal of 
concurrent connections. It all depends on your application. (If anyone needs 
this I can build it relatively easily).

Note that the CSockets class provided by Microsoft is not thread safe. (In
spite of Microsoft's documentation I tried this once in order to learn why 
it would not work..... if Microsoft says it does not work then it does not
work, unfortunately the converse is not always true)

Future
======
The ADR Sockets demo uses version 4 of the Internet protocol suite (IPV4).
The new version called IPV6 is currently being deployed but IPV4 will live 
for many more years. 

Who Am I
========
I am a freelance programmer who likes Windows NT development projects.
My current assignment includes serial data acquisition with video image
capture and analysis in a soft real-time application. I prefer living 
in a small town in Northern Ontario where I can drive my snow-mobile 
out the back of my yard into the woods.

Disclaimer
==========
These programs were written for demonstration purposes only. They do not
incorporate sufficient error detection and handling code for commercial
use. Only cursory testing has been performed. Use at own risk. 
No warrranty implied or explicit. No guarrantee either. 
Your mileage may vary. 
