            PDCOMM   Version 2.00   Released 1997-03-09


INTRODUCTION
------------

PDCOMM is a set of public domain comms routines (currently) for DOS, 
OS/2, Amigados, Unix and Windows/NT written by Paul Edwards, Fidonet 
3:711/934, Matthew Parker, Fidonet 3:711/934.31, Michael Stapleton, 
Fidonet 3:711/934.33 and Chris Moran, Fidonet 3:713/708.

They were written for DOS because I was trying to make my
COM3 port work, which used IRQ9, and I couldn't get my existing comms
package to work, and whilst I asked questions in AUST_AVTECH to find out
why, I put what I learnt into code!  The latest version of this package
is available for FREQ from 3:711/934 by magic name "PDCOMM".

For some examples of programs that use these routines, obtain DDC or
RSEND from 3:711/934.  The example programs provided in this package
simply send "ATZ\r\n" to the modem and print out the response ("OK"?).

Note that the "port string" should be either "COM2:02F8,3,19200" (for
example) under MSDOS, or "COM3:19200" (under OS/2).  There are some
other variations acceptable for OS/2.  Under AmigaDOS, the "port string"
should be like "serial.device,0,19200", where 0 is the unit number.

*** REALLY IMPORTANT *** - if you compile under Watcom for DOS, you
must disable stack checking.  This is because it sets up it's own
stack (or something like that - Matthew Parker knows the details).

Note - I have found that because the comms routines don't do anything
special with 16550s, that strange anomalies can happen if you use
another comms program before one that uses PDCOMM, or try running the
DOS version under OS/2 with BUFFER=ON in the mode.  Solution is to 
reboot the computer, switch off the modem, make sure BUFFER is off,
that style of thing.  Or code 16550 support up of course.  :-)  Also,
high speed DOS comms don't work well under Windows 3.1 unless you
have a 16550 and a comms program that supports them.  The same appears
to be true for DOS programs running under OS/2, at least with the tests
I did (with a small buffer admittedly).

  
ACKNOWLEDGEMENTS
----------------

Thanks are due to:

Matthew Parker, for the assembler routines
Rod Speed, for a lot of technical advice given.
Paul Markham, for loaning me his comms book.
Dave Hatch, for releasing COMX8612 to the public domain.
Ken Chick, for pointing out a bug.
Michael Stapleton, for the Amiga routines

FILES INCLUDED
--------------

pdcomm.txt      Documentation for the PD comms routines (this file)

pdcomm.h        pdcomm master header file

pdcommo.h       pdcomm header file for os/2
pdcommo.c       pdcomm source code for os/2

pdcomma.h       pdcomm header file for Amiga
pdcomma.c       pdcomm source code for Amiga

pdcommu.h       pdcomm header file for Unix
pdcommu.c       pdcomm source code for Unix

pdcommw.h       pdcomm header file for Windows/NT
pdcommw.c       pdcomm source code for Windows/NT

pdcommd.h       pdcomm header file for dos
pdcommd.c       pdcomm source code for dos
pdcommda.h      pdcomm header file for assembler stuff
pdcommda.asm    pdcomm source file for assembler stuff
uart.h          header file for dos uart manipulation
uart.c          source file for dos uart manipulation
lldos.h         header file for low level dos routines
lldos.asm       source file for low level dos routines

error.h         header file for error handling
error.c         source file for error handling

comtest.c       demo program to write to com port
comtest.mak     makefile for dos
comtest.exe     demo executable for dos
comtestp.mak    makefile for os/2
comtestp.exe    demo executable for os/2
comtesta.mak    makefile for Amiga
comtesta.exe    demo executable for Amiga

pdpgoal.txt     goals of the public domain project


CAN YOU HELP
------------

Any enhancements you can make to PDCOMM would be appreciated by 
the whole community.  Please netmail me if you have a useful 
enhancement.


LIMITATIONS
-----------

Doesn't account for the missed transmit interrupt bug in some 8250s
  (probably not an issue).
Doesn't do anything particular for 16550s (it should still work
  though).
It does look at CTS to do handshaking, but never lowers RTS, and
  there is no ability to use XON/XOFF.

The good news is that it does work for high interrupts!


FUNCTIONS
---------

Here is the documentation (such as it is) for the comms routines.
Note that this is more of a "general" API, rather than what is
actually provided with this package.

/* Defaults - allow the object to set some default values */

void pdcommDefaults(PDCOMM *pdcomm);


/* Init - initialize the object */
/* "name" is implementation-dependant.  Examples are:
   "" - use the default, e.g. /dev/modem in unix, COMPORTD environment
        variable under DOS + OS/2, prefs/serial under AmigaDOS.
   "COM2" - used under OS/2.  All other parameters will be as set by
            the mode command.
   "2" - under MSDOS, will look at the variable COMPORTS to find out
         the IRQ etc, and the mode command for the rest.
   "COM2:02F8,3" - under MSDOS, will use COM2 with 0x2f8 as the I/O
                   port and 3 as the IRQ.

   "serial.device,0,19200" - under AmigaDOS, will use the normal serial
         device, unit 0.

   In the absence of the ability to determine the parameters, e.g. N81,
   from the system, N,8,1 will be used.
   Potentially, a syntax such as COM2:02F8,3,19200,N,8,1 could be used.
*/

void pdcommInit(PDCOMM *pdcomm, char *name);


/* Terminate use of the com port */

void pdcommTerm(PDCOMM *pdcomm);


/* By default, the com port stream is unbuffered, ie if you continually
   write blocks of 1 character in size, you will communicate with the
   OS all the time, a massive performance penalty.  It is suggested that
   if you are doing that sort of thing, you should instead set the
   buffering technique to "fully buffered" and do a "flush" as required.
   Same setup as C's setvbuf() function */

/* NOT ACTUALLY IMPLEMENTED in this implementation! */
   
void pdcommSetWBuf(PDCOMM *pdcomm, char *buf, int mode, size_t size);
void pdcommSetRBuf(PDCOMM *pdcomm, char *buf, int mode, size_t size);
void pdcommWFlush(PDCOMM *pdcomm);
void pdcommRFlush(PDCOMM *pdcomm);

/* Note that rather than spread calls to these functions throughout
   your code, it is probably wiser to encapsulate it in a similar
   way that repo.c is used in Tobruk */
size_t pdcommWriteBuf(PDCOMM *pdcomm, void *buf, size_t len);
size_t pdcommReadBuf(PDCOMM *pdcomm, void *buf, size_t max);

/* For the byte-at-a-time operations, there is, same as fputc and fgetc */

int pdcommWriteCh(PDCOMM *pdcomm, int ch);
int pdcommReadCh(PDCOMM *pdcomm);

/* Set speed, parity, databits and stopbits.  Hopefull there is no
   need to call these functions in normal operation, as they would
   be specified on the open (by the user).  However, the speed change
   facility is required on modems that don't support locked comm 
   ports. */

void pdcommSetSpeed(PDCOMM *pdcomm, unsigned long bps);

void pdcommSetParms(PDCOMM *pdcomm, 
                    int parityType,
                    int databits,
                    int stopbits);

/* Raise + drop DTR */

void pdcommRaiseDTR(PDCOMM *pdcomm);

void pdcommDropDTR(PDCOMM *pdcomm);
