Serial++ Interrupt Driven Serial Ports for C++ from Cortlandt Technologies Serial++ Version 1.0 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 by Cortlandt Technologies. All rights reserved. This manual is Copyright (c) 1991 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........................................4 Hardware/Software Requirements......................5 Installing Serial++.................................6 Installing .LIB Library Files.......................7 Installing .H Include Files.........................8 Using This Manual and Serial++......................10 Serial Ports...................................10 Break Trapping.................................13 Memory Models..................................13 Serial++ with Overlays.........................14 SerialPort Function Reference.......................14 constructor....................................14 destructor.....................................15 getBreakOff....................................16 getCommPort....................................17 getDataBits....................................17 getLSR.........................................18 getMSR.........................................19 getParity......................................20 getSpeed.......................................21 getStopBits....................................21 inbyte.........................................22 inmem..........................................23 instr..........................................24 isOwner........................................25 lineOK.........................................26 outbyte........................................27 outmem.........................................27 outstr.........................................28 sendBreak......................................28 setMCR.........................................29 unbyte.........................................30 constructor....................................31 destructor.....................................31 breakCt........................................32 isBreak........................................33 isCaptured.....................................34 isOwner........................................35 operator().....................................35 reset..........................................36 Serial++ is Shareware..........................38 Registration Information.......................38 Limited Distribution License...................39 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. Support for iostreams as defined in C++ version 2.0 is not available as of this release. 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. 4 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. 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 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 Int. Vector Address 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. 5 Installing Serial++ Serial++ is distributed as a self-extracting archive file, SPP.EXE. The first step in installation is to copy this file into a work directory and execute it by typing: C:>spp 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 SPP.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. 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++. > 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 6 can ting,. Thisright. B and linker n your k Ps t e Borlak DEMOing s of thi t place the library a , hat make up e spt files containsde files hey iMAN.TXT machine. Whenntirely thibwitn that your seri LibrarompaplXT. tilizes anyhousekeeping is ition, READ.Ms usipanded SPP.w execannoums i/o in C. rhing like this: 6 . . . our cecannm s e Dopd proma w execao e, i s READ.ME,am to lre maibws o SPPSplXT.mmputer, run /o iur EAD.Ms he rs Rdeta*.Bthoug, yary files, SPPx.bPSplXT. he faufrom or each pt. m intoekeeping is it . . . . READ.ME . Serial+F C++ cK, etc. These figoof a anno EAD.Ms ao annmde you wiizes any of the listse ude if ybyrt for iostreams n C. r, TLINK.an execdoes expect to firont y ao ins fine infor like this: 1+ us wiizes ani.Ms usng: nded SPP.w execibranourclly containsde i/o in C. fashiy be us iostreams compiler and linkerutorce ccllytse u urrrom or each , compiler and linkeles to ls ftlyta works usip usng: save sp e compiler and linke save sp e e to opei++ rt. uter, runect to firontopd pro. ng: nded SPP.ibra following gro runect to h ens thibwsng: nded SPP.w execibrade i/o in C. Ps t e Borlakone lzes ani.Msr . ed!or like this: - ORioni like this: 2 py (pressini.Ms uyou wiianded SPP.w execann Ps t e Borlakoprietaryressini.Ms ybyrs iostre S e to op contains nded SPP.s ope drutorce ccllytse f ybyrt fo e containsnntratinit . . . s, n dou Brebiianded SPP: contains like this: \BORLANDC\ compiler and linke can nle. the deangedrial++ self. s iostreanded SPP can naesse tF is ng: nded SPP.w execibra following Ps t e Borlakce Ba s R, to save ss: contains like this: e i PYllow? \BORLANDC\ compiler and linkeeeeeeeeeeeeee( vec , Ke this ) contains like this: e i DELllow? compiler and linkeeeeeeeee(ao ride s adyial+ i.M.) contains like this: or like this: - ORioni like this: 3+ us wiizes ani.Ms usng:i Thereor each stredeangecann Ps t e Borlak 'sizes anyhse ude e to ope biiins fin. These are C+ing is it s e D y : contains like this: s iostreIDEk ,re is a usng: like this: environmmput Opd promDr each i.ME,atre you with some exam, SPPx.bPitnn break.ght wa ude wiianded SPP. orde compiler and linkede files (pressini.M. wfin. lXT. runect to finmde ianded SPP.\ It i ,ed in ywizes anyhse hing like this: 7 looking something like this: de ntai : contains like this: \ ;\BORLAND\ ;... contains like this: suxecao d inenvironmmput intoer t Serial+deangecbP can SerOpd promS f is ng: mmpu. contains like this: I wort ly,cibrade Bre sCIN, wps the i like this: a s iostreams ao r to ial+deangec s usng: IDE like this: ds the ial++ m, sC Agile,e y th you with some exam, SPPx. (pressinypanded SPP.EXE ctedl usnou with some exam, SPPx.bPitnn break.ght zes anyhse ude e contains like this: prefly t save sp e sCCing as it is a des de figur > Libra you e d insaess it is Slf. am P, *.Bb sbyrthat yt fo ntioL can a c e tAs ,+deangat yt fo a c thi s o: contains like this: -L\ ;\BORLANDC\ ;... contains like this: ou Bre .ert y th you Ke hypot fe ccl PACKike this: ressini.Ms nded SPP.suyou wiise ude e READ.ME . Htation, RF C++ cK, etc. Thes Installte us iostreams eandD.Msse Itition, th some exampAD.Msa rettlle it erromlP. orn ressini.M,les,as ccllytsimila distributed aREAtegy ile f Itit. rief de.EXE ekeeping is ition, READ.M.or like this: 1+ us wiiition, READ.Ms usng: nded SPP.w execibranourclly containsde i/o in C. fashiy beopei++ + self. situ runect to firectoryams to wortio-a be Ie/o Address In nded SPP.ibra following gro h ens thibwsng: contains nded SPP.w execibrade i/o in C. cibr'r: ne!or like this: - ORioni like this: 2 py (pition, READ.Ms uyou wiianded SPP.w execann Ps t e Borlakoprietaryition, READ.Ms S e to ops nded SPP.s ope compiler and linkerutorce ccllytse f ybyrt fo ensnntratiThese are C+ing is it . . . s, n dou Brebiianded SPP: contains like this: \BORLANDC\INCLUDE like this: can nle. the deangedrial++ self. s iostreanded SPP can naesse tF is ng: nded SPP.w execibra following Ps t e Borlakce Ba s R, to save ss: contains like this: e i PYllrief de. \BORLANDC\INCLUDE like this: e i PYl . \BORLANDC\INCLUDE like this: eeeeeeeeee( vec , Ke this ) contains lng like this: 8 looking something like this: e i DELl ekeeping is e i DELllrief description. linkeeeeeeeee(ao ride s adyial+ i.M.) contains like this: or like this: - ORioni like this: 3+ us wiiition, READ.Ms usng:i Thereor each stredeangeddress In ntiition, Rse ude e to ope bi compiler and linkerns fin. it s e D y : contains like this: s iostreIDEk ,re is a usng: like this: environmmput Opd promDr each i.ME,atre you with some exam, SPPx.bPitnn break.ght ition, Rse ude wiianded SPP. ords it is a llede files (pition, READ.M. wfin. like this: dlXT. tilmde ianded SPP.\ It i ,ed in ywiition, th some examhe listse ude ntai : contains like this: \ ;\BORLAND\INCLUDE;... contains like this: suxecao d inenvironmmput intoer t Serial+deangecbP can SerOpd promS f is ng: mmpu. contains like this: I wort ly,cibrade Bre sCIN, wps the i like this: a s iostreams ao r to ial+deangec s usng: IDE like this: ds the ial++ m, sC Agile,e y th you with some exam, SPPx. (pition, READ.Msanded SPP.EXE ctedl usnou with some exam, SPPx.bPitnn break.ght ition, Rse ude e contains like this: prefly t save sp e sCCing as it is a des de figur > Libra you e d insaess it is Slf. am P, *.Bb sbyrthat yt fo ntioI can a c e tAs ,+deangat yt fo a c thi s o: contains like this: -I\ ;\BORLANDC\INCLUDE;... contains like this: ou Bre .ert y th you Ke hypot fe ccl PAiition, th some examhe listEAD.Msanded SPP.suyou wiise ude e READ.MGet SerStay to cK, etc. These fifirsecto Ser wf iaputyou PP.s oyouer wsng: m K, etc. Thesds the i reali. PA:k DEMOing . cK, etc. These opei++a y rt. sds the ifirec m naREAtes 6 ak.ght ,as c pabireti (p I. I. als o the you en a e fars e s adytE,atre cceprtiaRE Ses f is ng: keybotaryao en you wi adytE,atrewaal+ up you wo e e ds, replytf is ng: adyt t echoes you wi *.een. cK, etc. These opeds the iase ful.bPca t ++a quick+deeck+ ords it is (p ile f Ke htarwr ensntope dg the a lng like this: 9 looking something like this: rt. sile Ser i s Kec deifirecibra de i/o like this: n C. youdeeck+des Ke it . . . (. cK, etc. Thes r de untoeaseequi e may tra m,r wf fitreids it is a eandyudertntoe PP breaes DEMOing . Tryrthat y DEMO like this: en save ss you wi ra mio-r shu Bresont DEMO echo ng: ra mntiacknow edg.mmpus usng: *.een. cK, etc. Thes it iclf.y de at y/o in C.at y DEMO that yt f like this: reali. r to >,+deeck+ oe de figur s rectorybottor like this: r to >,+/o i TLINK save s,e ht zes anyh/o like this: ition, Rse ude se tM to suxecairectoryde sta works ustoryoI c/o i-L a c rce u it . . . like this: Ke myou ne. cK, etc. Thes DEMOiC shuw++a rt. s i huw you Pdyt e s oat y/o iwri Se;e m o r aealic . . s n like this: ne l o s exity ratin lytbiii ibraneed. suxecao like this: bruw+ rstallte ufun reflyencecao a s e wspictuxe like this: f exibirety (pzes anye READ.MUhat ye opeManu /o i PACK READ.MPerh ++ betin y thibwc 6 acquilet. PA.s oyo READ.Mt to ial+sa. sds the ,s DEMOiC ,+/o ira ify t ao uis K READ.Mneedse tHow ,byrreviewat y 6 backgrsto i usng: let.wor compiler anile Se Pdyt.EXE s kTrapp I,+/l ug th some exampun reflyencecairecfols o ,r wf biiiblecao wri ey 6th some exam y rop ope cct. s adyt eandDat yr f is C (. cK, etc. These fifols oat y sede fileses,ni.f P, *.Bp. . huws it is Pdyt.EXE s kTrappr iaREuctuxed,+/o i y 6th some examprace ccl infourc. . wf needcao knowcao wi ratinaes like this: package.or like this: Pdytsor like this: e fifirsectwo e adytMs us Ke this , M1:+/o i M2:,pr like this: reaoy tof Itit un+/o iaes un+byrt fo e Pdyte tY K READ.M wf needcrecleatinan it ncec Pdyt. It a uddyt.y K READ.M wfsh you us Ke ds the e tY K m y moxecair like this: it ncec Pdyt. ociat. a udhys ccl adytE,buds it is onlyt ,ed infirsecit ncecthibws*.eat. , a llede frolu with some exam, ddyt.deraest.wse tAe , ng: adyt lleremilesto ly t s frols it is ofs Ke ds the stotilcairecfirsec Pdyt.it nce, ng: like this: enedrial+adytE,p Ieaes s i/o iham its like this: P, REuct It i wd. We a llede 6 back you wopedoiput gile like this: . . ,ram itiham a m j It t ecinan huw wf iaputyo like this: it ntiat.c Pdyt.objworti us Ke ds the M.or like this: T Pdyt. ede sope wo adyt s:nan adyt is like this: e c, hidden f is r aealic . . deiatre l y s S nt. like this: T opedoyt , s reflyredcao as ng: adyt nch It( wf lng like this: 10 looking something like this: noe ceia reflyencecao aiaREuctuxe naesd PdytAnch It usng: like this: + sini. . e Pdyt),ede filessng: let.wruput rv ce like this: rstt e de,+/l ug ses,lock+df Pata requiredcao rv ce like this: ng: adyt.to ops ata ition, tiau u Se as ng: adlet.wsnou with some exam, but eru of Itpdyt.it un,+/o iitnticurrromtpdsi. . e to e like this: : adyt nch It It a u swo ahys ccl adyts like this: reaoy to,+/o i a uasee busyt r availablec It byh/o like this: it ntiat . Pdyt. Itng: ur ofs Ke ds the .or like this: T dynaeicudert e Pdytei++ adyt airec s like this: *.eat. a uit ntiat . : itidedords ng: adyt deraest.ws like this: set e *.eat. in,+/o iadlets you wi adyt nch I like this: *orrrspe dat ytou wi adyt s woifirks ustoryc naREuct I like this: *i . Ea uit ncec Pdyt. e dknowm if, ng: wners it is ofs wi adyt nch I: if, ng: firsecit ncecthirefly to like this: ngat+adytE, paraest.ws s woifirks( + self.edcao) rds it is *.eat ai 6 axe aeali. you wi adyt nd ngat+it ncec wns like this: ng: adytstotilc P, REoywd.or like this: Onlytng: wner+it ncec s wi s wto,+parety ata nd stopth some exam, biut t Ser adytE,atreng: adytsope lo ofonlyt e its like this: wner+i P, REoywd. tY K m y *.eat. nd P, REoy as m o like this: it nces Pdyt. Itadg n ahys ccl adyt as ibraneed,s it is onlytng: wner+wf s wi adytstp,t r lo c d wn. like this: Ihstallte us up paraest.ws ofs wi e e d nd subsequrom like this: it nces Pdyt. Itadg n ahys ccl adyt axe ignored,s it is i ak.ght it nces s oy/o iwri e you wi adyte to ey wf lit is i do ocrecthat yt foparaest.ws , Rablfin. e wi adyt like this: wner+it ncecwas *.eat. .or like this: F It i ,e ustoope deifragmmpu:ng like this: Pdyt. om1( M_1,B_2400,D_8,P_N,S_1); like this: . . . like this: Pdyt.* yw om =n ywi Pdyt( M_1,B_1200); like this: . . . like this: om1.stt RE("Hels ,ileld"); like this: yw om->stt RE("\n...via ra m!\n"); lth some exam, bo it nces adletat ytou M1:, om1y/o i yw om, a lleaes un like this: E Ses you wi adyt t 2400 baudE, valu us rectory*.eat s it is ofs wi wner+it nce, om1.or like this: Not. e d ustoope i ngat+ e om1ygo Ieaes s i/o like this: P, REoywd,eng: adytsope lo o. it ncec yw om pe lit is exipe intoengat+h enI,+/l /ts pts you savun cct.snou with some exam, adyt yw om lleretux err It euME,atrelet.wrogatat like this: ng: euM ofs wi adyt rstall yw om lleshuw yht ze like this: unavailable.or like this: T opeiet.wor i ectuxe Pdyt. es o the yo like this: iti. alizes Ke ddytMse lyi us Ke ds the ,+perh ++bP cande rat y/c Pdyt.it nce ofs > s ii Ke myle like this: ra u >,+/o i usnou*.eat. s po anyhit ncec w e .y K ng like this: 11 looking something like this: needca rstaldes Ke ds the ifoe ccessrial+adytE,a des with some exam, needcao p sto i rnde r. globcl adlet.wsnou wi adyte like this: lc Pdyt.it nceME, wnersi rnnoe, fitre/o i s it is o en adyt o t ey refly.or like this: Ano +dearace pe c Pdyt.ngat+isnile otat : s it is it un+/o iaes un+membtoe un s Pdyt. r. lit is de r.d virtu . T opefaciretAtes *.eat t y ly dp I lit is f is Pdyt, if, wfsh youperfoury 6 preds cess breaks it is it un+ Eee M,t r pdst-ds cess breakiaes un+ Eee M.es do like this: rrideiat it it. i/o+membtoe un ,ibwssuxecao *i s it is *orrrspe dat y Pdyt.rstt e f is r ywirstt e yo like this: perfouryyht aceucl adyt i/o.or like this: L e /o iadrt euM un s r. ot virtu ii Pdyteor like this: Oninfior ote: if, look rectory+ sini. . Pdyt.it like this: ERIAL.H,r wf noe ceiairectoryderaest.ws p dsnou with some exam, c naREuct I /o iretux dsbyrt fo ...()+membtoe un s r like this: i d sinedcrMsenum valu s,hit s oy st. siet.g.wse tThis like this: was d : Itnwhireas s:n firse, stncecratinafs wisith some exam, aeraest.ws ccepr i *.et. r htoenganede finuouM valu s,hthat lit is enums+isnaneeasyn y thi wi t d usuxecairecnonaes like this: ofsrang valu s wf biip dsas.deraest.wseor like this: T e e d reas ngan+byr+ siniSer nums+ r- like this: reaniSeful.naess,yyht aceucl valu s p ds biiwgan is like this: e niromtf is a s dat ydoiputofsview.es look rector lit is enums+rectorybeginn breaki ERIAL.H,r wf noe ceiaire like this: i Ihstallte uvalu unaess r to enseE, valu srialmselv I lit is reallyid 'e, stt idei et.xti deifirecu I lit is ialmeor like this: s k Trappat l like this: Pdyt.u I keyboardsb s k trappat t d usuxecaiaaf i/o like this: s e wsshutd wns ustory putofsa ri nerat. keyboardth some exam, b s k. y + self., Pdyt. llerestor. let.wruputh some exam, vect Is you wiirt rigior addres I atrelmesdiat.lyiexit youDOS like this: e it + twortia keyboardsb s k.es t wf noeeretux s frols it is you Ke ds the ibefor. exitat y/intoeasb s k.esCeeck Ser s it is yrapp. keyboardsb s k ng: firseca perfourrks usi ak like this: ng: i/o+membtoe un s,+/o iratinafs wi euM un s ak like this: PA;,bud biiiwaxecairec Ke ds the icould runr quit like this: 6 ai 6 totilcaiec yxt s adyt o er i * r ngan+ s it is keyboardsb s k ham occurrrd.or like this: T opebe i r bii rridden byr t Ser Pdytth some exam, c naREuct I deraest.wsb k_off non-zero (REue). T opeflag like this: *iu I Pdyt.no ignore yrapp. b s ks,+/o ide finue yo like this: i w,a des let.wrupu . eor like this: Pdyt. b s ks ignored, m y wfsh youyrap like this: io ihandDe keyboardsb s kti us Ke wnsaealic . . . T opeis ng like this: 12 looking something like this: easilyid byhition,at y/n.it nce ofs s kTrapp .it like this: Ke ds the .or like this: s kTrappisnam y rt. s .ngat+aerfoursctwo e v cesr like this: Ke ds the . Firse, it yr ++keyboardsb s kti(Cs frol- s k like this: io iCs frol-C),epre pu Ser mtf is let.wrupu Ser Ke ds the , like this: io i e e d it m a medeanismr Ke ds the ifo lit is det.wm e ifia keyboardsb s k ham occurrrd. tY K m y fre.lys it is