






                                            
                                            
                                            
                                            
                                            
                                            
                                            
                                            
                                            
                                            
                                            
                                        Serial++
                                            
                          Interrupt Driven Serial Ports for C++
                                            
                               from Cortlandt Technologies








































                              









                                            

            
            
            
            
            
            
            
            
            
            
            
            
            
            Serial++ Version 1.10
            by Cortlandt Technologies
            P.O. Box 195
            Pleasantville NY 10570
            
            
            
            
            
            
                                              _______
                                         ____|__     |                (R)
                                      --|       |    |-------------------
                                        |   ____|__  |  Association of
                                        |  |       |_|  Shareware
                                        |__|   o   |    Professionals
                                      -----|   |   |---------------------
                                           |___|___|    MEMBER
            
            
            This program is produced by a member of the Association of
            Shareware Professionals (ASP).  ASP wants to make sure that the
            shareware principle works for you. If you are unable to resolve a
            shareware-related problem with an ASP member by contacting the
            memberdirectly, ASP may be able to help. The ASP Ombudsman can
            help you resolve a dispute or problem with an ASP member, but
            does not provide technical support for members' products.  Please
            write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442
            or send a CompuServe message via CompuServe Mail to ASP Ombudsman
            70007,3536.

            
            
            Copyright Notice:

            Serial++ is Copyright (c) 1991, 1992 by Cortlandt Technologies.
            All rights reserved.

            This manual is Copyright (c) 1991, 1992 by Cortlandt
            Technologies.  All rights reserved.

                                   









       

       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       
       Warranty Disclaimer

       CORTLANDT TECHNOLOGIES MAKES NO WARRANTY OF ANY KIND, EXPRESSED
       OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY WARRANTIES OF
       MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.

       CORTLANDT TECHNOLOGIES DOES NOT ASSUME ANY LIABILITY FOR THE USE
       OF THIS SOFTWARE BEYOND THE ORIGINAL PURCHASE PRICE OF THIS
       SOFTWARE.

       IN NO EVENT WILL CORTLANDT TECHNOLOGIES BE LIABLE TO YOU FOR ANY
       ADDITIONAL DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS, OR
       OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING FROM THE USE
       OF, OR INABILITY TO USE, THIS SOFTWARE AND ITS ACCOMPANYING
       DOCUMENTATION, EVEN IF CORTLANDT TECHNOLOGIES, HAS BEEN ADVISED
       OF THE POSSIBILITY OF SUCH DAMAGES.


                              









                               Table of Contents

            Introduction....................................... 1

            Hardware/Software Requirements..................... 2

            Installing Serial++................................ 3

            Installing .LIB Library Files...................... 4

            Installing .H Include Files........................ 5

            Getting Started.................................... 6

            Using This Manual and Serial++..................... 7

                 Serial Ports.................................. 7

                 Break Trapping................................ 9

                 Memory Models................................. 10

                 Serial++ with Overlays........................ 10

            SerialPort Function Reference...................... 13

                 Serial constructor............................ 13

                 Serial destructor............................. 14

                 checkLSR...................................... 15

                 checkMSR...................................... 16

                 getBreakOff................................... 17

                 getCommPort................................... 18

                 getDataBits................................... 19

                 getLSR........................................ 19

                 getMSR........................................ 20

                 getParity..................................... 21

                 getSpeed...................................... 22

                 getStopBits................................... 22

                 inbyte........................................ 23

                 inmem......................................... 24



                              









                      instr......................................... 25

                      isOwner....................................... 26

                      lineOK........................................ 27

                      outbyte....................................... 27

                      outmem........................................ 28

                      outstr........................................ 29

                      readLSR....................................... 29

                      readMSR....................................... 30

                      sendBreak..................................... 31

                      setMCR........................................ 31

                      unbyte........................................ 32

                      BreakTrap constructor......................... 35

                      BreakTrap destructor.......................... 35

                      breakCt....................................... 36

                      isBreak....................................... 37

                      isCaptured.................................... 38

                      isOwner....................................... 39

                      operator().................................... 39

                      reset......................................... 40

                      Serial++ is Shareware......................... 42

                      Registration Information...................... 42

                      Limited Distribution License.................. 43

            Index................................................... 47











                                   










            Introduction

            Serial++ is a library of small, safe, and efficient routines that
            bring interrupt driven serial port support to your C++ programs.
            It is compiled and linked with the Borland C++ compiler, and
            supplied in the form of a set of ready to link object libraries.

            The routines in Serial++ are as easy to use as file i/o in C, yet
            give you complete access to the registers of the 8250 UART,
            should you require it.  They allow you to read characters from
            and write characters to two serial ports simultaneously, in a
            fashion very similar to stream i/o in C.

            Implemented as C++ classes, the Serial++ library handles multiple
            ports and multiple instantiations with ease.  The SerialPort and
            BreakTrap classes contain all the internal housekeeping necessary
            to deal with  multiple instances of the each class using a single
            port.  It is because of this feature that Serial++ lends itself
            nicely to event driven applications.

            Serial++ protects your applications from keyboard breaks,
            (pressing the Control-Break or Control-C keys), to insure that
            the necessary interrupt housekeeping is completed before
            terminating,.  This guarantees that premature closing of a
            Serial++ application will not leave your system with invalid
            service routine addresses hooked to the serial interrupts..

            By default SerialPort will perform an orderly shutdown when a
            break key is pressed, and exit to DOS. You can, however, specify
            that keyboard breaks be handled in your own application code, in
            which case SerialPort will continue to operate and ignore the
            break. See the section on break trapping for details on how this
            works.

            You can also use the keyboard break handling in Serial++ by
            itself.  The BreakTrap class is entirely independent of the
            SerialPort class.

            Serial++ is linked into your C++ programs just like any other
            library.  There is absolutely no requirement for external TSR's -
            - applications using Serial++ are completely self contained.














     
                                  1








       


       Hardware/Software Requirements

       Serial++ may be used on any PC or PC-AT compatible computer,
       running on an Intel(Tm) 8088, 8086, or 80x86 family processor or
       compatible, that uses standard port addresses for COM1 and COM2.
       (You may also support COM1 or COM2 at non-standard IRQ's or port
       addresses: see the function reference entry on the constructor
       for details.)

       It is worth mentioning that Serial++ assumes that your serial
       port hardware makes use of the National Semiconductor 8250 UART
       chip, or a clone of it.  It is almost unheard of to find hardware
       that uses anything else, so if you don't know what your serial
       board uses, you're alright.  Be aware of this issue though, if
       you use some sort of exotic or proprietary serial boards in your
       machine.  When in doubt, try executing the demo program on your
       target machine.

       While Serial++ is largely unaffected by machine speed, and has
       been run on machines operating at 4.77 to 33 MHz, it does expect
       to find the serial ports and interrupt vector addresses at very
       specific locations:

       Device    Base i/o Address    Interrupt Number
       COM1:     0x03F8              0x000C
       COM2      0x02F8              0x000B
       
       Keyboard:
       Ctrl-Brk  n/a                 0x0023
       Ctrl-C    n/a                 0x001B

       If you have difficulty getting the demo program to work, you
       might want to consult the technical documentation that comes with
       your computer to verify the addresses shown above.

       Serial++ requires MS-DOS, version 2.11 or higher. [The library
       has been tested and works with version 5.00].  Serial++ uses DOS
       functions for saving, setting, and restoring interrupt service
       routine addresses.

       While it is running, Serial++ traps the interrupts mentioned in
       the table above.  Although it restores the addresses of the prior
       service routines upon exit, while it is running Serial++ could
       interfere with any TSR's that utilizes any of the listed
       interrupts.  Consult the documentation of any TSR's you use that
       provide serial communications or respond to the Control-Break or
       Control-C keys.







                             2








            


            Installing Serial++

            The Serial++ distribution diskette contains two self-extracting
            compressed files:  SPPBC2.EXE and SPPBC3.EXE, that each contain
            all of Serial++ -- libraries, includes, example files and
            documentation.

            Use file SPPBC2.EXE if you are presently using Version 2.0 of the
            Borland C++ compiler.

            Use file SPPBC3.EXE if you use any variant of Version 3.x of the
            Borland C++ compiler.

            The first step in installation is to copy the appropriate
            SPPBC?.EXE file into a work directory and execute it.  For
            example, if you use the version 3.0 compiler, you might type:
            
                 C:>copy a:sppbc3.exe
                 C:>sppbc3
            
            at the DOS command prompt.  SPP will announce each file as it is
            unpacked looking something like this:
            

              . . .
              
              READ.ME .
              PACKING.LST .
              SPPL.LIB .
              BREAK.H .
              SERIAL.H
              SPPS.LIB .
              . . .
              

            After you have expanded SPPBC?.EXE into its component files, you
            may delete it from your install work directory, to save space.

            The first file to check is READ.ME, which may contain updated
            information about Serial++.  You may also wish to examine the
            contents of PACKING.LST, which lists every file in the package,
            along with a brief description.  File HISTORY.TXT lists the
            changes in the current release.

            The files included in the Serial++ package fall into the
            following groups:

              >  Library files, SPPx.LIB.  There is one library file for each
                   memory model supported by Serial++.




     
                                  3








         >  Include files, *.H. These are C++ source includes that
              define the public interface of the classes that make up
              Serial++.

         >  Demo related files, *.CPP, *.BAT, *.MAK, etc. These files
              are included to provide you with some examples of how to
              use Serial++.  They include an executable demo program,
              SPPDEMO.EXE, which is ready to run.

         >  Documentation, READ.ME, PACKING.LST, and the file that
              contains this document, SPPMAN.TXT.

       In order to begin using Serial++, you must place the library and
       include files in a directory where the C++ compiler and linker
       can locate them.  You have several options as to where to keep
       these files, as explained below.  The placement of the
       documentation and demo files is of course not critical, they may
       be placed in any convenient directory, or removed after
       installation.


       Installing .LIB Library Files

       The goal with the .LIB files is to get them into the library
       search path used by the Borland C++ linker, TLINK. There are
       three  ways to accomplish this:

         1  Keep the libraries in the directory where you normally
              compile and link programs.  The Borland C++ compiler will
              automatically search the current directory for any .LIB
              file explicitly listed in a project or on the command line
              of the command line compiler.  This is the simplest of the
              three options.  If the directory you expanded SPP.EXE in
              happens to be the directory where you compile and link,
              your libraries are installed!

         - OR -

         2  Copy the Serial++ libraries into the directory where the
              standard libraries provided by Borland reside.  This
              directory is also automatically searched by the compiler.
              In most installations, this would be directory:
              
                 \BORLANDC\LIB
              
              unless you have changed the default Borland directory
              names.  From the directory where you expanded SPP.EXE,
              issue these DOS commands:
              
                 C:> COPY SPP?.LIB  \BORLANDC\LIB
                           (or whatever it is on your system)
              
                 C:> DEL SPP?.LIB
                      (to get rid of the temporary copies.)



                             4








                   
                   

              - OR -

              3  Keep the libraries in their own directory, and change the
                   compiler's library search path.  This can be accomplished
                   in several ways:
                   
                   If you use the Borland IDE compiler, from within the
                   environment select Options Directories, and add to the
                   beginning of the search path the directory that will
                   contain the Serial++ libraries.  If you wished to place
                   them in directory \SPP for example, the new library search
                   path might look like:
                   
                      \SPP;\BORLAND\LIB;...
                   
                   Be sure to save the environment after making the change by
                   selecting Options Save from the menu.
                   
                   Alternatively, you could use the BCINST program provided
                   with Borland C++ to make the change above in the IDE
                   program itself, BC.EXE. Again, add the path to the
                   Serial++ library directory and a semicolon to the
                   beginning of the library search path.
                   
                   If you prefer the command line compiler BCC.EXE, with or
                   without configuration files, you can achieve the same
                   result as described above by using the compiler's -L
                   switch.  As above, changing the switch to read:
                   
                      -L\SPP;\BORLANDC\LIB;...
                   
                   would insert the path to our hypothetical Serial++
                   libraries directory into the search path.


            Installing .H Include Files

            Although the Borland C++ compiler handles searching for include
            files a little differently than libraries, a basically similar
            strategy will work for installing the SERIAL.H and BREAK.H
            include files.

              1  Keep the include files in the directory where you normally
                   compile and link programs.  This is the default situation
                   that the C++ compiler expects --as mentioned before, if
                   the directory you expanded SPP.EXE in happens to be the
                   directory where you compile and link, you're done!

              - OR -




     
                                  5








         2  Copy the Serial++ include files into the directory where the
              standard include files reside.  This directory is also
              automatically searched by the compiler.  In most
              installations, this would be directory:
              
                 \BORLANDC\INCLUDE
              
              unless you have changed the default Borland directory
              names.  From the directory where you expanded SPP.EXE,
              issue these DOS commands:
              
                 C:> COPY SERIAL.H  \BORLANDC\INCLUDE
                 C:> COPY BREAK.H   \BORLANDC\INCLUDE
                           (or whatever it is on your system)
              
                 C:> DEL BREAK.H
                 C:> DEL SERIAL.H
                      (to get rid of the temporary copies.)
              
              

         - OR -

         3  Keep the include files in their own directory, and change
              the compiler's include search path.  This can be
              accomplished in several ways:
              
              If you use the Borland IDE compiler, from within the
              environment select Options Directories, and add to the
              beginning of the include search path the directory that
              will contain the Serial++ include files.  If you wished to
              place them in directory \SPP for example, the new include
              search path might look like:
              
                 \SPP;\BORLAND\INCLUDE;...
              
              Be sure to save the environment after making the change by
              selecting Options Save from the menu.
              
              Alternatively, you could use the BCINST program provided
              with Borland C++ to make the change above in the IDE
              program itself, BC.EXE. Again, add the path to the
              Serial++ include files directory and a semicolon to the
              beginning of the include search path.
              
              If you prefer the command line compiler BCC.EXE, with or
              without configuration files, you can achieve the same
              result as described above by using the compiler's -I
              switch.  As above, changing the switch to read:
              
                 -I\SPP;\BORLANDC\INCLUDE;...
              
              would insert the path to our hypothetical Serial++ include
              files directory into the search path.



                             6








            Getting Started

            The first thing you will want to try is to execute the demo
            program supplied with Serial++: SPPDEMO.EXE.

            This is a very simple program that demonstrates some of the basic
            capabilities of the Serial++ classes. It allows you to open a
            conversation on either serial port, and accepts strings from the
            keyboard to send to the port, and waits up to two seconds for a
            reply from the port which it echoes to the screen.

            This program is useful because it provides a quick check that
            Serial++ will work with your hardware.  It also gives you a
            simple working example of source code that you can compile and
            link to check out your installation of Serial++.

            If your computer is equipped with a smart modem, you will find it
            a handy partner for trying out SPPDEMO.EXE. Try using SPPDEMO to
            send commands to the modem -- you should see SPPDEMO echo the
            modem's acknowledgements on the screen.

            If you have difficulty compiling and linking SPPDEMO using the
            supplied make file, check the configuration section at the bottom
            of the make file, and the TLINK command, for the library and
            include search paths.  Make sure that the paths listed in the -I
            and -L compiler switches match the installation of the compiler
            on your machine.

            SPPDEMO.CPP shows a simple example of how to use the SerialPort
            class for reading and writing; for many of your applications this
            level of complexity will most likely be all you need.  Be sure to
            browse through the function reference to get a complete picture
            of the flexibility of the Serial++ library.


            Using This Manual and Serial++

            Perhaps the best way to become acquainted with Serial++ is to
            take the sample program, SPPDEMO.CPP, and modify it to suit you
            needs.  However,by reviewing some background on the internal
            workings of the SerialPort and BreakTrap classes, along with
            function reference that follows, you will be able to write some
            very sophisticated serial port handling right from C++.

            The following sections contain a brief description of how
            SerialPort and BreakTrap are structured, and provide some
            practical information you will need to know to get the most out
            of the package.

              Serial Ports

              The first two serial ports in your system, COM1: and COM2:, are
              supported for input and output by the class SerialPort.  You
              will need at least one instance of SerialPort for each port you


     
                                  7








         wish to use in your program.  You may have more than one
         instance of SerialPort associated with each physical port, but
         only one, the first instance to be created, will control the
         port parameters.  Also, the port will remain under the control
         of your program until that first SerialPort instance, the one
         which opened the port, passes out of scope and has its
         destructor executed.  We will come back to this point again
         later, as it has a major effect on how you will want to
         instantiate SerialPort objects in your programs.

         The SerialPort class consists of two portions: one portion is
         static, hidden from your application code and always resident.
         This portion, which is referred to as the port anchor (you will
         notice a reference to a structure named PortAnchor in the
         definition of class SerialPort), contains the interrupt service
         routine code, along with a block of data required to service
         the port. This data includes such things as the pointer to the
         buffer used for port input, and it's current position.  There
         is one port anchor for each of the two physical ports
         supported, and each is either busy or available for use by an
         instantiation of SerialPort for the duration of your program.

         The dynamic part of class SerialPort is the portion that gets
         created with each instantiation: it records the port parameters
         you set when you created it, and points to the port anchor
         corresponding to the port you specified in the constructor
         call. Each instance of SerialPort also knows if it is the owner
         of the port anchor: if it is the first instance to refer to
         that port, the parameters you specified (or defaulted to) at
         creation time are applied to the port and that instance owns
         the port until it is destroyed.

         Only the owner instance can set the speed, parity data and stop
         bit setting for a port, and the port is closed only when its
         owner is destroyed.  You may create and destroy as many other
         instances of SerialPort for a given physical port as you need,
         only the owner will set the port up, or close it down.
         Although the set up parameters of the second and subsequent
         instances of SerialPort for a given physical port are ignored,
         all of the instances can read and write to the port.  They will
         all do so at using the parameters established when the port
         owner instance was created.

         For example, in this code fragment:

            SerialPort com1(COM_1,B_2400,D_8,P_N,S_1);
            . . .
            SerialPort *newcom = new SerialPort(COM_1,B_1200);
            . . .








                             8








                 com1.outstr("Hello,world");
                 newcom->outstr("\n...via modem!\n");

              both instances pointing to COM1:, com1 and newcom, will output
              strings to the port at 2400 baud, the value set at the creation
              of the owner instance, com1.

              Note also in this example that when com1 goes out of scope and
              is destroyed, the port is closed.  If instance newcom still
              exists after that happens, all attempts to communicate to the
              port with newcom will return error status, and interrogating
              the status of the port through newcom will show the line
              unavailable.

              This internal architecture of SerialPort allows you to
              initialize your ports early in your program, perhaps by
              declaring a SerialPort instance of file scope in your main
              module, and then to create a temporary instance anywhere you
              need throughout your program to access the port, without the
              need to pass around or declare a global pointer to the port.
              All SerialPort instances, owners or not, can find and use the
              open port to which they refer.

              Another characteristic of SerialPort that is worth noting: the
              input and output member functions of SerialPort are all
              declared virtual.  This facilitates creating derived classes
              from SerialPort, if you wish to perform some preprocessing of
              input streams, or post-processing of output streams.  If you do
              override an inherited i/o member function, be sure to call the
              corresponding SerialPort routine from your new routine to
              perform the actual port i/o.

              Line and port status functions are not virtual in SerialPort.

              One final note: if you look at the definition of SerialPort in
              SERIAL.H, you will notice that the parameters passed to the
              constructor and returned by the get...() member functions are
              all defined as enum values, instead of simple integers.  This
              was done for two reasons:  first, since most of these
              parameters accept discrete rather than continuous values, using
              enums is an easy way to get the compiler to insure that no out
              of range values will be passed as parameters.

              The second reason is that by defining enums with user-
              meaningful names, the actual values passed can be whatever is
              convenient from a coding point of view.  If you look at the
              enums at the beginning of SERIAL.H, you will notice that
              although the value names make sense, the values themselves








     
                                  9








         really don't, outside of the context of the code that uses
         them.

         Break Trapping

         SerialPort uses keyboard break trapping to insure a safe and
         complete shutdown in the event of a user generated keyboard
         break.  By default, SerialPort will restore all interrupt
         vectors to their original addresses and immediately exit to DOS
         when it detects a keyboard break.  It will not return control
         to your program before exiting after a break.  Checking for a
         trapped keyboard break is the first action performed in all of
         the i/o member functions, and most of the status functions of
         Serial++; but be aware that your program could run for quite
         some time until the next serial port operation discovers that a
         keyboard break has occurred.

         This behavior can be overridden by setting the SerialPort
         constructor parameter brk_off non-zero (true).  This flag
         causes SerialPort to ignore trapped breaks, and continue to
         execute without interruption.

         If you use SerialPort with breaks ignored, you may wish to trap
         and handle keyboard breaks in your own application.  This is
         easily done by including an instance of the BreakTrap class in
         your program.

         BreakTrap is a very simple class that performs two services for
         your program.  First, it traps keyboard breaks (Control-Break
         and Control-C), preventing them from interrupting your program,
         and second it provides a mechanism for your program to
         determine if a keyboard break has occurred.  You may freely
         include and use BreakTrap in your programs that use SerialPort,
         because BreakTrap, like SerialPort, makes use of a static
         anchor structure that all instances share.  Therefore no
         contention occurs regardless of the number of concurrent
         instances of BreakTrap or SerialPort.

         BreakTrap provides you application with a number of member
         functions with which it can determine if one or many keyboard
         breaks have occurred, reset the break flag, an even check to
         make sure that some other instance of BreakTrap hasn't released
         the trap.  Please see the individual member function














                             10








              descriptions listed in the function reference for more
              information.

              Memory Models

              The Serial++ library is provided as four separate library
              files, that may be used with five different memory models
              supported by Borland C++.  The files and models are:

                      Memory Model   Library File
                 
                      Tiny,Small     SPPS.LIB
                      Medium         SPPM.LIB
                      Compact        SPPC.LIB
                      Large          SPPL.LIB

              Select the library file that matches the memory model you are
              using, and name that file as part of your project, or in the
              TLINK command in your make file.  Consult your compiler
              documentation for further information on memory model support.

              Serial++ with Overlays

              The routines contained in SerialPort and BreakTrap contain
              static portions that once enabled must remain at their absolute
              memory addresses.  This fact is common to all interrupt service
              routines.

              Serial++ may be used in overlaid programs, as long as the
              Serial++ routines are loaded as part of the "root" or non-
              swapped portion of the program.

              As long as you can control the use of overlays and guarantee
              that the Serial++ routines will never get swapped out or
              written over, everything should work just fine.





















     
                                  11

































































                             12








              


            SerialPort Function Reference

              ++++++++++++++++++++++++++++++++++++++++

              constructor

              Usage:

                 SerialPort(CommPorts    cp ,
                            Baud     sp        = B_1200,
                            DataBits db        = D_8,
                            Parity   ps        = P_N,
                            StopBits sb        = S_1,
                            size_t b_size      = SERIALPORT_STD_BUF_SIZE,
                            int  brk_off       = 0,
                            int      irq       = 0
                            unsigned int io_adr = 0)

              Returns:

                 n/a

              Description:

                 The SerialPort constructor allocates an instance of
                 SerialPort, and links it to the port anchor that services
                 the requested port.  If the port is not currently open,
                 SerialPort opens it and makes this instance the port owner.
                 The values passed into (or defaulted to) the constructor are
                 used to set up the port.  For the complete range of port
                 parameters supported, please see the enums located in file
                 SERIAL.H.

                 If the requested port is already open, this instance is
                 linked to it, and the port parameters passed in are ignored.


















     
                                  13








         Parameters:

            CommPorts cp:       Selects the desired port, COM1: or
                                COM2:. No default.

            Baud sp:            Selects the port speed. Defaults to 1200
                                baud.

            DataBits db:        Selects number of data bits per
                                character. Default is 8.

            Parity ps:          Selects desired character parity
                                checking. Default is no parity checking.

            StopBits sb:        Selects number of stop bits per
                                character. Default is 1.

            size_t b_size:      Sets size of buffer to use for input
                                characters from the selected port.
                                Default is 2048 bytes, defined in
                                SERIAL.H.

            int brk_off:        Flag to turn off automatic keyboard
                                break handling in SerialPort.  If flag
                                is true (non-zero), SerialPort ignores
                                keyboard breaks and continues to operate
                                if they occur.  If flag is false (zero,
                                this is the default), SerialPort does an
                                orderly shutdown of all ports and exits
                                to DOS immediately.

                                Although this flag is set in the
                                SerialPort constructor, the flag is sets
                                is global to all ports, therefore if you
                                wish to disable break handling in
                                SerialPort, every SerialPort constructor
                                must be called with brk_off non-zero.

            int irq             You may override the port's default IRQ
                                line by passing a value ranging from 1
                                to 7 in this position.  Please consult
                                your hardware's technical reference
                                before using this parameter, as you can
                                create conflicts with other periperals
                                such as the keyboard or hard drive by
                                re-assigning the IRQ.

            unsigned int io_adr This parameter allows you to re-assign
                                the sequence of i/o addresses used to
                                communicate with the UART's registers.
                                Again, caution is advised when changing






                             14








                                     the defaults: consult your hardware
                                     documentation carefully.

              Examples:

                 SerialPort com1(COM_1,2400,D_7,P_E,S_1);

                 SerialPort *cport = new SerialPort(COM_2); // using defaults


              ++++++++++++++++++++++++++++++++++++++++

              destructor

              Usage:

                 n/a

              Returns:

                 n/a

              Description:

                 The SerialPort destructor deallocates the storage associated
                 with this instance.  If this instance is the owner of the
                 port, the port is closed and all trapped interrupts are
                 returned to their prior state.  If the current instance is
                 not the port owner, the port is not closed.

                 If you wish to change the parameters in use for a particular
                 port, or close the port permanently, you must destroy the
                 SerialPort instance that owns the port.  After destroying
                 the port owner, you may reopen the port with different
                 parameters if you wish by instantiating a new SerialPort
                 object linked to the port.

                 A port may be closed or closed and re-opened even if other
                 non-owner instances are linked to the port.  Attempts to use
                 the port while it is closed results in error returns from
                 the SerialPort member functions, and causes no harm.
                 Changed port parameters are not a problem either, because
                 all instances linked to a particular port use the parameters
                 set by the owner instance.

              Parameters:

                 n/a








     
                                  15








         Examples:

            SerialPort cport= new SerialPort(COM_1);  // owns COM_1
            ...
            if (...
                 {
                 SerialPort com1(COM_1,2400); // uses cport's parameters
                 ...
                 }                   // com1 destroyed, port still open
                 ...
            delete cport;             // now the port is closed


         ++++++++++++++++++++++++++++++++++++++++

         checkLSR

         Usage:

            int checkLSR(unsigned char &cc);

         Returns:

            An integer value, true (non-zero) if a Line Status Register
            Interrupt has occurred since the last call to checkLSR,
            false (zero) if no LSR interrupt has occurred.

         Description:

            This routine returns a flag that is set by the port anchor
            when the UART raises the LSR interrupt.  The UART raises
            this type of interrupt when on of the following error
            conditions arises, causing the corresponding bit in the LSR
            to be set:
            
                      OE       =  0x0002,   // overrun error
                      PE       =  0x0004,   // parity error
                      FE       =  0x0008,   // framing error
                      BI       =  0x0010,   // break indication
            
            Calling this routine clears the port anchor's LSR interrupt
            flag.

         Parameters:

            unsigned char &cc   This reference returns an unsigned char
                                that contains the contents of the LSR at
                                the time the interrupt occurred.  You
                                may examine this value to determine
                                which error caused the interrupt.  Be
                                aware that this value may no longer be
                                the current value of the LSR; a call to





                             16








                                     readLSR() might return different
                                     results.

              Examples:

                 SerialPort com1(COM_1,B_2400);
                 
                 unsigned char intrpt_lsr;
                 ...
                 if (com1.readLSR(intrpt_lsr))  // if LSR interupt occurred
                     if (intrpt_lsr&OE)         //  if overrun err occurred
                         {
                          ...                   // do something...


              ++++++++++++++++++++++++++++++++++++++++

              checkMSR

              Usage:

                 int checkMSR(unsigned char &cc);

              Returns:

                 An integer value, true (non-zero) if a Modem Status Register
                 Interrupt has occurred since the last call to checkMSR,
                 false (zero) if no MSR interrupt has occurred.

              Description:

                 This routine returns a flag that is set by the port anchor
                 when the UART raises the MSR interrupt.  The UART raises
                 this type of interrupt when one of the following changes of
                 modem status occurs, causing the corresponding bit in the
                 MSR to be set:
                 
                           DCTS     =  0x0001,   // delta clear to send
                           DDSR     =  0x0002,   // delta data set ready
                           TERI     =  0x0004,   // trailing edge ring ind
                           DDCD     =  0x0008,   // delta data carrier detect
                 
                 Calling this routine clears the port anchor's MSR interrupt
                 flag.

              Parameters:

                 unsigned char &cc   This reference returns an unsigned char
                                     that contains the contents of the MSR at
                                     the time the interrupt occurred.  You
                                     may examine this value to determine
                                     which state change caused the interrupt.
                                     Be aware that this value may no longer
                                     be the current value of the MSR; a call


     
                                  17








                                to readMSR() might return different
                                results.

         Examples:

            SerialPort com1(COM_1,B_2400);
            
            unsigned char intrpt_msr;
            ...
            if (com1.readMSR(intrpt_msr))  // if MSR interupt occurred
                if (intrpt_msr&DDCD)       //  if carrier detect changed
                    {
                     ...                   // do something...


         ++++++++++++++++++++++++++++++++++++++++

         getBreakOff

         Usage:

            int getBreakOff(void);

         Returns:

            An integer value, true (non-zero) if SerialPort is ignoring
            keyboard breaks, false (zero) if keyboard breaks will
            interrupt SerialPort.

         Description:

            n/a

         Parameters:

         n/a

         Examples:

            SerialPort com1(COM_1);
            ...
            int breaks_off = com1.getBreakOff();


         ++++++++++++++++++++++++++++++++++++++++

         getCommPort

         Usage:

            CommPorts getCommPort(void);






                             18








              Returns:

                 The enum CommPorts value corresponding to the port to which
                 this instance is linked.

              Description:

                 n/a

              Parameters:

                 n/a

              Examples:

                 SerialPort com1(COM_1);
                 ...
                 CommPorts cp = com1.getBreakOff();


              ++++++++++++++++++++++++++++++++++++++++

              getDataBits

              Usage:

                 DataBits getDataBits(void);

              Returns:

                 The enum DataBits value in use by the port to which this
                 instance is linked.

              Description:

                 n/a

              Parameters:

                 n/a

              Examples:

                 SerialPort com1(COM_1);
                 ...
                 DataBits db = com1.getDataBits();










     
                                  19








         ++++++++++++++++++++++++++++++++++++++++

         getLSR

         Usage:

            int getLSR(LSR_Masks mm);

         Returns:

            An int value that is true (non-zero) if the 8250's Line
            Status Register bit corresponding to the mask passed in is
            1, otherwise false (zero).

         Description:

            The 8250's Line Status Register reflects the current state
            of port data line.  By selecting the mask corresponding to
            the line condition you wish to test from the enum LSR_Masks
            in SERIAL.H, you can use this routine to return the truth
            value of that line condition.  You may OR together several
            masks if you wish to test for multiple conditions in a
            single call.

         Parameters:

            LSR_Masks mm:       One or more mask values selected from
                                the enum defined in SERIAL.H:

            enum LSR_Masks
                          {
                           DR   =  0x0001,   // data ready
                           OE   =  0x0002,   // overrun error
                           PE   =  0x0004,   // parity error
                           FE   =  0x0008,   // framing error
                           BI   =  0x0010,   // break indication
                           THRE =  0x0020,   // THR empty
                           TSRE =  0x0040    // Transmit Shift empty
                           };

         Examples:

            SerialPort com1(COM_1,B_2400);
            ...
            if (com1.getLSR(BI)    // do this if line break detected
                 {
                 ...










                             20








              ++++++++++++++++++++++++++++++++++++++++

              getMSR

              Usage:

                 int getMSR(MSR_Masks mm);

              Returns:

                 An int value that is true (non-zero) if the 8250's Modem
                 Status Register bit corresponding to the mask passed in is
                 1, otherwise false (zero).

              Description:

                 The 8250's Modem Status Register reflects the current state
                 of several modem control lines.  By selecting the mask
                 corresponding to the status line you wish to test from the
                 enum MSR_Masks in SERIAL.H, you can use this routine to
                 return the truth value of the modem line.  You may OR
                 together several masks if you wish to test for multiple
                 conditions in a single call.

              Parameters:

                 MSR_Masks mm:       One or more mask values selected from
                                     the enum defined in SERIAL.H:

                 enum MSR_Masks
                                {
                                DCTS =  0x0001, // delta clear to send
                                DDSR =  0x0002, // delta data set ready
                                TERI =  0x0004, // trailing edge ring ind
                                DDCD =  0x0008, // delta data carrier detect
                                CTS  =  0x0010, // clear to send
                                DSR  =  0x0020, // data set ready
                                RI   =  0x0040, // ring indicator
                                DCD  =  0x0080  // data carrier detect
                                };

              Examples:

                 SerialPort com1(COM_1,B_2400);
                 ...
                 if (com1.getMSR(DCD)    // do this if carrier detected
                      {
                      ...








     
                                  21








         ++++++++++++++++++++++++++++++++++++++++

         getParity

         Usage:

            Parity getParity(void);

         Returns:

            The enum Parity value in use by the port to which this
            instance is linked.

         Description:

            n/a

         Parameters:

            n/a

         Examples:

            SerialPort com1(COM_1);
            ...
            Parity ps = com1.getParity();































                             22








              ++++++++++++++++++++++++++++++++++++++++

              getSpeed

              Usage:

                 Baud getSpeed(void);

              Returns:

                 The enum Baud value in use by the port to which this
                 instance is linked.

              Description:

                 n/a

              Parameters:

                 n/a

              Examples:

                 SerialPort com1(COM_1);
                 ...
                 Baud sp = com1.getSpeed();


              ++++++++++++++++++++++++++++++++++++++++

              getStopBits

              Usage:

                 StopBits getStopBits(void);

              Returns:

                 The enum StopBits value in use by the port to which this
                 instance is linked.

              Description:

                 n/a

              Parameters:

                 n/a

              Examples:

                 SerialPort com1(COM_1);
                 ...
                 StopBits sb = com1.getStopBits();


     
                                  23








         ++++++++++++++++++++++++++++++++++++++++

         inbyte

         Usage:

            int inbyte(unsigned char &cc,unsigned int t_out = 0);

         Returns:

            An int value, true (non-zero) if a character is read,
            otherwise false (zero).

         Description:

            This function reads one byte from the port's input buffer if
            it contains any.  If the buffer is empty, it will wait the
            number of milliseconds indicated by the timeout parameter;
            if a byte appears in the buffer within that time period, it
            reads it and returns.  If no byte appears in the buffer
            within the timeout period, the routine returns false, and
            the contents of the unsigned character reference is
            unchanged.

         Parameters:

            unsigned char cc:   A reference to the byte to receive the
                                character read from the port.

            unsigned int t_out: If positive, the number of milliseconds
                                to wait for a character to appear if
                                none are available immediately.  If
                                zero, no waiting occurs; if a character
                                is not immediately available, none is
                                returned.  The default for this
                                parameter is zero.

         Examples:

            SerialPort com1(COM_1);
            unsigned char cbuf[20];
            ...
            if (com1.inbyte(cbuf[0],2000))  // char read within 2 secs.
                 {
                 ...                   // do this


         ++++++++++++++++++++++++++++++++++++++++

         inmem

         Usage:

            int inmem(void *mp, size_t msize, unsigned int t_out=0);



                             24








              Returns:

                 An int value, true (non-zero) if all requested  characters
                 are read, otherwise false (zero).

              Description:

                 This function reads a specified number of bytes from the
                 port's input buffer.  If the buffer is empty, it will wait
                 the number of milliseconds indicated by the timeout
                 parameter; if another byte appears in the buffer within that
                 time period, it is read and the timer is reset.  If no byte
                 appears in the buffer within the timeout period, the routine
                 returns false, however many bytes have already been read.

                 Remember that the timeout period you specify is per
                 character read, and not a total cumulative value for the
                 entire count of characters requested.

              Parameters:

                 void *mp:           A void pointer to the starting byte to
                                     receive the characters read from the
                                     port.

                 size_t msize:       The count of characters to read,
                                     expressed as an unsigned short. (size_t
                                     is defined in STDLIB.H).

                 unsigned int t_out: If positive, the number of milliseconds
                                     to wait for a character to appear if
                                     none are available immediately.  If
                                     zero, no waiting occurs; if a character
                                     is not immediately available, none is
                                     returned.  The default for this
                                     parameter is zero.

              Examples:

                 SerialPort com1(COM_1);
                 unsigned char cbuf[20];
                 ...
                 if (com1.inmem(cbuf,sizeof(cbuf),2000))
                      {                   // all chars read within 2 secs.
                      ...              // do this











     
                                  25








         ++++++++++++++++++++++++++++++++++++++++

         instr

         Usage:

            char *instr(char *buf,
                        size_t maxlen,
                        unsigned int t_out=0);

         Returns:

            The character pointer passed in as the first parameter.  No
            error conditions are returned if a timeout or buffer
            overflow occurs, but the contents of the buffer are
            guaranteed to be null terminated.  The buffer contents are
            unchanged if no characters are read.

         Description:

            This function reads bytes from the port's input buffer until
            and end-of-line is detected.  If the buffer is empty, it
            will wait the number of milliseconds indicated by the
            timeout parameter; if another byte appears in the buffer
            within that time period, it is read and the timer is reset.
            If no byte appears in the buffer within the timeout period,
            the routine returns false, however many bytes have already
            been read.

            Remember that the timeout period you specify is per
            character read, and not a total cumulative value for the
            entire count of characters requested.

            Function instr looks for a carriage return (0x0a) or a
            carriage return and line feed (0x0a0d) as an end-of-line
            indication.  These characters are not placed the output
            string.  It does not check the data placed in the string for
            nulls (0x00); if one appears in the port it will be placed
            in the output string and have the effect of terminating it
            prematurely.

            If the buffer size is exceeded by the characters coming from
            the port, maxlen-1 data characters, plus a terminating null
            are returned.

         Parameters:

            char *buf:          A pointer to the character buffer to
                                receive the string read from the port.

            size_t msize:       The maximum number of characters the
                                buffer will accommodate, including the
                                terminating null, expressed as an




                             26








                                     unsigned short. (size_t is defined in
                                     STDLIB.H).

                 unsigned int t_out: If positive, the number of milliseconds
                                     to wait for a character to appear if
                                     none are available immediately.  If
                                     zero, no waiting occurs; if a character
                                     is not immediately available, none is
                                     returned.  The default for this
                                     parameter is zero.

              Examples:

                 SerialPort com1(COM_1);
                 unsigned char cbuf[20];
                 ...
                 *cbuf='\0';
                 com1.instr(cbuf,sizeof(cbuf),2000);
                 if (*cbuf!='\0')
                      {             // any chars read within 2 secs.
                      ...         // do this


              ++++++++++++++++++++++++++++++++++++++++

              isOwner

              Usage:

                 int isOwner(void);

              Returns:

                 An integer value that is true (non-zero) if this instance is
                 the owner of the associated port, false (zero) if this
                 instance is only linked to the port.

              Description:

                 n/a

              Parameters:

                 n/a

              Examples:

                 SerialPort com1(COM_1);
                 ...
                 if (com1.isOwner())       // if com1 is owner...
                      {                // do this
                      ...




     
                                  27








         ++++++++++++++++++++++++++++++++++++++++

         lineOK

         Usage:

            int lineOK(void);

         Returns:

            An integer value that is true (non-zero) if the port is open
            and available, and false (zero) otherwise.  If keyboard
            breaks have not been disabled, lineOK() will report false if
            a keyboard break has been trapped.

         Description:

            n/a

         Parameters:

            n/a

         Examples:

            SerialPort com1(COM_1);
            ...
            if (com1.lineOK())   // if com1 is open and available...
                 {
                 ...          // do this


         ++++++++++++++++++++++++++++++++++++++++

         outbyte

         Usage:

            void outbyte(unsigned char cc);

         Returns:

            n/a

         Description:

            The unsigned character passed in to outbyte is written to
            the associated serial port.









                             28








              Parameters:

                 unsigned character cc:  This character is written to the
                                     associated serial port.

              Examples:

                 SerialPort com1(COM_1);
                 ...
                 com1.outbyte('A')   // write character 'A' to COM_1
                 ...


              ++++++++++++++++++++++++++++++++++++++++

              outmem

              Usage:

                 void outmem(const void *mp, size_t msize);

              Returns:

                 n/a

              Description:

                 Writes a specified number of bytes from a specific memory
                 location to the associated port.

              Parameters:

                 const void *mp:     Pointer to the first byte to write to
                                     the port.

                 size_t msize:       Number of bytes to write, expressed as
                                     an unsigned short (size_t is defined in
                                     STDLIB.H).

              Examples:

                 SerialPort com1(COM_1);
                 char cbuf[20];
                 ...
                 com1.outmem(cbuf,sizeof(cbuf)) // write array to COM_1
                 ...










     
                                  29








         ++++++++++++++++++++++++++++++++++++++++

         outstr

         Usage:

            void outstr(const char *buf);

         Returns:

            n/a

         Description:

            Writes the null terminated string pointed to by the input
            parameter to the associated port.  outstr does not send the
            terminating null to the port, and does not send any extra
            characters (such as \n), after the string.  The count of
            characters sent is equal to strlen(buf).

         Parameters:

            const char *buf:    Pointer to the string to send to the
                                associated port.

         Examples:

            SerialPort com1(COM_1);
            char cbuf[20]="ATZ";
            ...
            com1.outstr(cbuf)   // write string "ATZ" to COM_1
            com1.outbyte('\n'); // send new line after
            ...


         ++++++++++++++++++++++++++++++++++++++++

         readLSR

         Usage:

            int readLSR(void);

         Returns:

            An int value that contains the current contents of the LSR
            byte in its least significant 8 bits.  The upper 8 bits are
            zero.

         Description:

            This routine reads the 8250's Line Status Register, and
            returns the current value as the low order byte of the
            returned int.



                             30








              Parameters:

                 n/a

              Examples:

                 SerialPort com1(COM_1,B_2400);
                 
                 int curr_lsr;
                 ...
                 curr_lsr = com1.readLSR();
                 ...


              ++++++++++++++++++++++++++++++++++++++++

              readMSR

              Usage:

                 int readMSR(void);

              Returns:

                 An int value that contains the current contents of the MSR
                 byte in its least significant 8 bits.  The upper 8 bits are
                 zero.

              Description:

                 This routine reads the 8250's Modem Status Register, and
                 returns the current value as the low order byte of the
                 returned int.

              Parameters:

                 n/a

              Examples:

                 SerialPort com1(COM_1,B_2400);
                 
                 int curr_msr;
                 ...
                 curr_msr = com1.readMSR();
                 ...










     
                                  31








         ++++++++++++++++++++++++++++++++++++++++

         sendBreak

         Usage:

            void sendBreak(int dur=750);

         Returns:

            n/a

         Description:

            This routine causes the associated serial port to send a
            line break for the number of milleseconds passed as the
            integer parameter.

         Parameters:

            int dur:            The duration of the line break, in
                                milleseconds.  Defaults to 750
                                milleseconds if omitted.

         Examples:

            SerialPort com1(COM_1);
            ...
            com1.sendBreak() // send 750 millisecond break on COM_1
            ...


         ++++++++++++++++++++++++++++++++++++++++

         setMCR

         Usage:

            int setMCR(MCR_Masks mm, int state);

         Returns:

            An integer value equal to that passed in as the int input
            parameter, state.

         Description:

            The 8250's Modem Control Register controls several features
            of the UART.  By selecting the mask corresponding to the
            UART feature you wish to enable or disable from the enum
            MCR_Masks in SERIAL.H, you can use this routine to change
            the operating condition of the UART.  You may OR together
            several masks if you wish to toggle multiple features in a
            single call.



                             32








              Parameters:

                 MCR_Masks mm:       One or more mask values selected from
                                     the enum defined in SERIAL.H:

                    enum MCR_Masks
                                   {
                                   DTR    =  0x0001,   // data terminal ready
                                   RTS    =  0x0002,   // request to send
                                   OUT1   =  0x0004,   // aux user o/p 1
                                   OUT2   =  0x0008,   // aux user o/p 2
                                   LOOP   =  0x0010    // enable loopback
                                   };

                                     Be very careful about changing the state
                                     of OUT1, OUT2, and LOOP.  Do not toggle
                                     these lines unless you know exactly what
                                     you are doing -- you could disable the
                                     serial port altogether.

                 int state:          This integer parameter turns on the
                                     features requested if it is true (non-
                                     zero), and turns off the feature is it
                                     is false (zero).

              Examples:

                 SerialPort com1(COM_1,B_2400);
                 int set_state = 1;
                 com1.setMCR(DTR,set_state);    // set DTR on
                 


              ++++++++++++++++++++++++++++++++++++++++

              unbyte

              Usage:

                 void unbyte(unsigned char cc);

              Returns:

                 n/a

              Description:

                 The unsigned character passed in to unbyte is pushed back
                 into the buffer of the associated serial port as the next
                 character to be read.

                 This routine is useful if you need to "look ahead" in the
                 input stream for the second character of a two character
                 escape sequence.


     
                                  33








         Parameters:

            unsigned character cc:   This character is returned to the
                                input buffer of the associated serial
                                port.

         Examples:

            SerialPort com1(COM_1);
            unsigned char cc
            ...
            com1.inbyte(cc)        // read character from COM_1
            if (cc=='\t')
                 ...              // do this if a tab
            else
                 com1.unbyte(cc); // otherwise put it back for next read









































                             34
































































     
                                  35








       BreakTrap Function Reference


         ++++++++++++++++++++++++++++++++++++++++

         constructor

         Usage:

            BreakTrap(void);

         Returns:

            n/a

         Description:

            The BreakTrap constructor allocates an instance of
            BreakTrap, and links it to the break trap anchor that
            services keyboard break interrupts.  If the trap is not
            currently set, BreakTrap sets it and makes this instance the
            trap owner.  If the break trap is already set, this instance
            is linked to it, and full access to all trap flags and
            controls.

            In either case, after creating an instance of BreakTrap, the
            break trap anchor routines capture each Control-Break and
            Control-C pressed, and record theses events by incrementing
            a counter.  No other response to the break is made, and any
            routine that contains an instance of BreakTrap within its
            scope can check the counter at any time to determine if a
            break has occurred.

         Parameters:

            n/a

         Examples:

            BreakTrap bt;
            ...
            BreakTrap *btp = new BreakTrap;
            ...


         ++++++++++++++++++++++++++++++++++++++++

         destructor

         Usage:

            n/a





                             36








              Returns:

                 n/a

              Description:

                 The BreakTrap destructor deallocates the storage associated
                 with this instance.  If this instance is the owner of the
                 trap, the trap is released and all trapped interrupts are
                 returned to their prior state.  If the current instance is
                 not the trap owner, the trap is not released.  If you wish
                 to release the trap, you must destroy the BreakTrap instance
                 that owns the trap.

                 A trap may be released or released and set again even if
                 other non-owner instances remain linked to the trap.
                 Attempts to use the trap while it is released returns
                 indications that no breaks have occurred, and causes no
                 harm.

              Parameters:

                 n/a

              Examples:

                 BreakTrap bt1= new BreakTrap;  // bt1 owns trap
                 if (...
                      {
                      BreakTrap bt2;   // bt2 is just linked
                      ...
                      }                // bt2 destroyed, trap still set
                      ...
                      delete bt1       // now the trap is released;


              ++++++++++++++++++++++++++++++++++++++++

              breakCt

              Usage:

                 unsigned int breakCt(void);

              Returns:

                 An unsigned int value that is the count of the number of
                 keyboard breaks that have occurred since the counter was
                 last reset.







     
                                  37








         Description:

            Each time a Control-Break or Control-C is pressed while
            break trapping is enabled, a counter is incremented by
            BreakTrap.  This routine returns the current count of break
            events.

            This counter can be reset by reset() member function
            described below.

         Parameters:

            n/a

         Examples:

            BreakTrap bt;
            ...
            if (bt.breakCt()>1)   // if more than one break occurred
                 {
                 ...             // do this


         ++++++++++++++++++++++++++++++++++++++++

         isBreak

         Usage:

            int isBreak(void);

         Returns:

            An integer value that is true (non-zero) if at least one
            keyboard break has been counted since the last reset,
            otherwise false (zero).

         Description:

            Each time a Control-Break or Control-C is pressed while
            break trapping is enabled, a counter is incremented by
            BreakTrap.  This routine returns true (non-zero) if the
            current count of break events is non-zero.

         Parameters:

            n/a










                             38








              Examples:

                 BreakTrap bt;
                 ...
                 if (bt.isBreak())     // if any breaks have occurred
                      {
                      ...             // do this


              ++++++++++++++++++++++++++++++++++++++++

              isCaptured

              Usage:

                 int isCaptured(void);

              Returns:

                 An integer value that is true (non-zero) if the break trap
                 anchor is currently active and trapping breaks, otherwise
                 false (zero).

              Description:

                 When more that one instance of BreakTrap exist in a program,
                 only one is the owner of the break trap.  If the owner
                 instance is destroyed, the trap is released -- however the
                 non-owner instances continue to exist.  This function allows
                 any instance, owner or otherwise, to verify that the trap is
                 currently set and keyboard breaks are being trapped.

                 If the owner instance has been destroyed, and the trap is
                 released, any other instance checking for breaks will see no
                 breaks counted, i.e. will be unaware that the trap has been
                 released.  It is therefore good practice to use isCaptured()
                 whenever multiple instances of BreakTrap are used.

              Parameters:

                 n/a

              Examples:

                 BreakTrap bt;
                 ...
                 if (bt.isCaptured()&&bt.isBreak()) // if trap is set and
                      {                            // any breaks have
                 occurred
                      ...                          // do this






     
                                  39








         ++++++++++++++++++++++++++++++++++++++++

         isOwner

         Usage:

            int isOwner(void);

         Returns:

            An integer value that is true (non-zero) if this instance is
            the owner of the break trap, otherwise false (zero).

         Description:

            This routine enables any instance to determine if it is the
            owner of the break trap.  Since the destruction of the trap
            owner shuts off break trapping, and leaves the application
            program susceptible to user interruption, it is dangerous to
            destroy the trap owner.

            By checking to determine if a particular instance is trap
            owner before deleting it, you can avoid losing break
            protection.

         Parameters:

            n/a

         Examples:

            ...
            BreakTrap *bt = new BreakTrap;
            ...
            if (!bt->isOwner()) // if instance is not owner
                 delete bt:    // okay to delete it
                 ...


         ++++++++++++++++++++++++++++++++++++++++

         operator()

         Usage:

            int operator()(void);

         Returns:

            An integer value that is true (non-zero) if breaks are
            currently being trapped and at least one break has been
            counted since the last reset, otherwise false (zero).





                             40








              Description:

                 This overloaded function operator provides a convenient
                 shorthand way to query the break trap about its state.  The
                 trap is tested to determine whether it is active and whether
                 any breaks have been occurred.  After testing the trap, this
                 function also resets it, i.e. sets the count of breaks
                 trapped since the last reset to zero.

                 Invoking this overloaded operator is the equivalent of
                 making three consecutive member functions: isCaptured(),
                 isBreak() and reset().  See the example below.

              Parameters:

                 n/a

              Examples:

                 BreakTrap bt;
                 ...
                 if (bt())  // test for trap open and breaks occurred
                      {    // break counter reset after test
                      ...  // breaks are detected, do this

              The above example is equivalent to the following code:

                 BreakTrap bt;
                 ...
                 if (bt.isCaptured())    // test if trap operating
                      if (bt.isBreak()) // any breaks caught?
                           {
                           bt.reset(); // reset break counter
                           ...         // do this

              Note also that this overloaded operator notation requires a
              reference to the instance, not a pointer to it.  If you have a
              pointer to the instance, you must dereference in explicitly:

                 BreakTrap *btp = new BreakTrap;
                 ...
                 if ((*btp)())     // test and reset
                      {
                      ...       // do this if breaks have occurred.


              ++++++++++++++++++++++++++++++++++++++++

              reset

              Usage:

                 void reset(void);



     
                                  41








         Returns:

            n/a

         Description:

            Each time a Control-Break or Control-C is pressed while
            break trapping is enabled, a counter is incremented by
            BreakTrap.  This routine resets that counter to zero.

         Parameters:

            n/a

         Examples:

            BreakTrap bt;
            ...
            if (bt.isBreak())  // any breaks caught?
                 {
                 bt.reset();  // reset break counter
                 ...          // do this



































                             42








            Serial++ License and Registration

              Serial++ is Shareware

              Serial++ is a copyrighted computer program which is being
              distributed as shareware.  It is not a public domain program,
              and it is not free.

              Shareware is a distribution technique allows you the user a
              legal but limited trial period to evaluate a program before
              purchase.  If you continue to use the program after the trial
              period has ended, you must pay for the program by registering
              it.  You are also allowed to distribute evaluation copies of
              this software to others subject to certain limitations detailed
              below.

              This system of "try before you buy" allows you the user to get
              the most out of your software dollar by evaluating a
              prospective software purchase under its actual conditions of
              use.  For small software vendors such as Cortlandt
              Technologies, it represents a viable way of reaching a
              potential market, without the large costs and risks of self-
              publishing.  Many fine programs in commercial release today
              would not be available if the shareware concept did not exist.

              Please support the shareware concept by registering those
              programs you actually use and by passing them on to others.

              Registration Information

              Serial++ is provided at no charge for evaluation purposes only.
              This shareware version of Serial++ is the complete working
              version of the library, not a crippled or demo copy.

              Cortlandt Technologies, hereby grants you a limited license to
              use this software for evaluation purposes only for a period not
              to exceed 30 days.  If you intend to continue using this
              software after the 30-day evaluation period, you must register
              it by paying the registration fee to Cortlandt Technologies.

              Serial++ is a library of routines which may be included in
              software you develop and distribute with no additional
              royalties ONLY IF YOU HAVE PAID THE ONE TIME REGISTRATION FEE
              TO CORTLANDT TECHNOLOGIES.  If you have registered your copy of
              Serial++, you have the right to unrestricted distribution of
              any software you develop using it.

              Using this software after the evaluation period has ended, or
              distributing your own software developed with it, without
              registering it is a violation of the terms of this limited
              license.

              The $24.95 registration fee licenses one copy of the software
              for use on one computer at any given time.  You may have copies


     
                                  43








         of Serial++ on more than one computer, as long as it is not
         possible for more than one copy to be in use at one time.  Site
         licenses, or multiple computers on a local area network, are
         quoted on a per case basis, please contact Cortlandt
         Technologies for current multiple user license information.

         Upon registering your copy of Serial++, you will receive:

         >  A printed manual

         >  Complete BORLAND C++ source code for the Serial++ class
              library.

         >  The most current version of the Serial++ library.  This
              includes all maintenance changes and revisions made at the
              time you place your order.

         >  Free technical support, via mail or Compuserve for one year
              after registration date.

         >  Notification of future releases of Serial++.

         Limited Distribution License

         Cortlandt Technologies encourages you to freely copy and
         distribute the unregistered version of Serial++ subject to the
         following restrictions:

         >  You may only distribute the complete Serial++ package, in
              its original self-extracting archive file. You may not
              distribute the unarchived form of any Serial++ files.

         >  None of the files comprising Serial++, program or
              documentation, may be modified in any way and must be
              distributed as a complete package, intact.

         >  You may charge a distribution fee for the package, but you
              must not represent in any way that you are selling the
              software itself.

         >  Documentation in printed form may not be reproduced in whole
              or in part, using any means, without the prior written
              permission of Cortlandt Technologies.  This restriction
              includes both bound documentation, and printouts you make
              of the documentation included in the distribution file on
              diskette.

         >  You may not use, copy, rent, lease, sell or transfer the
              licensed program except as provided in this agreement.
              Any such unauthorized use shall result in immediate and
              automatic termination of this license.






                             44








              >  Cortlandt Technologies reserves the right to withdraw
                   permission from any vendor to distribute our products at
                   any time and for any reason.

              All rights not expressly granted here are reserved by Cortlandt
              Technologies,


















































     
                                  45








                               Serial++ Order Form

       To register your copy of Serial++ please send $24.95 and this
       form to:

       Cortlandt Technologies
       P.O. Box 195
       Pleasantville, NY 10570

       You will receive the latest version of Serial++ complete with
       source code, a printed version of the manual, be eligible for
       technical support via mail and Compuserv, and be placed in our
       user database to automatically receive notices of upgrades and
       releases.  See the section in this manual on licensing and
       registration for more details.

       Please fill in the information requested below:

       . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

          Name _________________________________________________________

         Title _________________________________________________________

       Company _________________________________________________________

       Address _________________________________________________________

               _________________________________________________________

          City _________________________________________________________

         State _______ Postal _______  Country _________________________
        (Prov)         Code

        Daytime Phone ______________________ Evenings __________________

       __ I have enclosed $24.95 in __ Check __ Money Order.

       __ I am interested in multiple user or site license.

       Also, please tell us how you heard about Serial++, and where you
       got your evaluation copy?

       _________________________________________________________________

               Thank you for registering your copy of Serial++!










                             46
































































     
                                  47








                                       

                                       
                                       
                                       
                                       
                                       
                                       
                                       
                                       
                                       
                                       


                                     Index










































                             48








            























































     
                                  49
































































                              









            

            8250 UART, 2

            aux user o/p 1, 32

            aux user o/p 2, 32

            Baud, 22

            BI, 16,20

            break trapping, 9

            breakCt, 36-37

            BreakTrap, 10

            checkLSR, 15-16

            checkMSR, 16-17

            clear to send, 21

            CommPorts, 13,18

            constructor, BreakTrap, 35

            constructor, SerialPort, 13,14

            CTS, 21

            data bits, 13

            data carrier detect, 21

            data ready, 20

            data set ready, 21

            data terminal ready, 32

            DataBits, 19

            DCD, 21

            DCTS, 17,21

            DDCD, 17,21

            DDSR, 17,21

            delta clear to send, 21



                                   









       delta data carrier detect, 21

       delta data set ready, 21

       destructor, BreakTrap, 35-36

       destructor, SerialPort, 14,15

       distribution of Serial++, 43-44

       DR, 20

       DSR, 21

       DTR, 32

       enum parameters, 9

       FE, 16,20

       framing error, 20

       getBreakOff, 17-18

       getCommPort, 18-19

       getDataBits, 19

       getLSR, 30-31

       getMSR, 20-21

       getParity, 21-22

       getSpeed, 22

       getStopBits, 22-23

       inbyte, 23-24

       include files, 3,5-6

       inmem, 24-25

       input buffer, 14

       installation, 3

       instantiation, 8

       instr, 25-26

       interrupt service routine, 8



                              









            interrupt service routines, in overlays, 11

            interrupts, 2,15

            isBreak, 37-38

            isCaptured, 38-39

            isOwner, BreakTrap, 39

            isOwner, SerialPort, 26-27

            keyboard breaks, 14,16,17,18,27

            library files, 3,4-5,10

            line break, 31

            line break indication, 20

            Line Status Register, 19

            lineOK, 27

            LOOP, 32

            loopback enable, 32

            LSR, 15,19,29,30

            LSR_Masks, 19

            MCR, 31

            MCR_Masks, 32

            memory models, 10

            Modem Control Register, 31

            Modem Status Register, 20

            MS-DOS, 2

            MSR, 16,20

            MSR_Masks, 20

            non-owner instances, 15

            OE, 16,20

            order form, Serial++, 45



                                   









       OUT1, 32

       OUT2, 32

       outbyte, 27-28

       outmem, 28-29

       outstr, 29

       overlays, 10-13

       overloaded operator(), BreakTrap, 39-40

       overrun error, 20

       owner, 8,26,38

       PACKING.LST, 4

       Parity, 21

       parity, 13

       parity error, 20

       PE, 16,20

       port addresses, 2

       port anchor, 8

       port parameters, 8,15

       port speed, 13

       PortAnchor, 8

       READ.ME, 3,4

       readLSR, 30

       readMSR, 31

       registration of Serial++, 42-43

       request to send, 32

       reset, BreakTrap, 40-41

       RI, 21

       ring indicator, 21



                              









            RTS, 32

            sendBreak, 31

            SerialPort, 7-9

            setMCR, 31-32

            shareware, 42

            smart modem, 7

            SPPDEMO.EXE, 7

            SPPMAN.TXT, 4

            SPPx.LIB, 3

            static, 10

            stop bits, 13

            StopBits, 22

            TERI, 17,21

            THR empty, 20

            THRE, 20

            timeout, 23,24,25,26

            trailing edge ring indicator, 21

            Transmit Shift empty, 20

            TSR's, 1,2

            TSRE, 20

            unbyte, 32-34

            virtual functions, 9

            











                                   



