home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d5xx / d523 / serlib.lha / SerLib / Docs / serlib.doc < prev    next >
Text File  |  1991-08-05  |  18KB  |  587 lines
  1.                       SerLib - Library    Version 3.0
  2.  
  3.                             © 1991 G. Glendown
  4.  
  5.                     __________________________________
  6.  
  7.                                   PREFACE
  8.                     __________________________________
  9.  
  10.  
  11. Today there are many people out in the world programming this nice machine,
  12. and many succeed. But even of those who do succeed in writing programs that
  13. keep the rules, probably everybody has problems with a couple pieces of the
  14. system  software.   There  have  been  many  good approaches to solve those
  15. problems, and there are quite a few good pieces of code you can use.
  16.  
  17. But  until  today,  there  hasn't  been  any help for people that want easy
  18. access to the serial port.  So what do they do ?  They take a language that
  19. includes  that  easy  access,  and program their (mostly fine) ideas in it.
  20. But  as  many use the thing called `GFA Basic' and `GFA Basic Compiler', it
  21. tends  to  go  from bad to worse.  Instead of having maybe 5 little bugs in
  22. their  program, they get those 5 little bugs plus approximately 10 big ones
  23. and  a  lot  of unwanted `features' that the compiler generates.  Among the
  24. features are:
  25.  
  26. -- no access using baud rates larger than 19200 Baud
  27. -- carrier detect via accessing the hardware
  28. -- current versions of the interpreter and compiler are incompatible to OS
  29.    2.0 and Amiga 3000/3000T
  30.  
  31. Though the first two problems can be fixed by a simple workaround, only few
  32. people  know  about it.  But what should be done ?  The best thing would be
  33. to  allow  easy  access  to the serial.device, so that people can use their
  34. C-Compiler again...
  35.  
  36. As a result of my work and wisdom (;-)), here's `serlib.library', a library
  37. that includes all routines needed for easy serial.device-access.
  38.  
  39.                                         -garry, Bad Hersfeld, Feb. 16th, 91
  40.  
  41.  
  42.                     __________________________________
  43.  
  44.                                 INSTALLING
  45.                     __________________________________
  46.  
  47.  
  48. SerLib.Library includes the following files:
  49.  
  50.                   serlib_SAS.lib        LibSrcAztec.lzh
  51.                   serlib.fd             LibSrcAztecL.lzh
  52.                   serlib.h              serlib.library
  53.                   serlib.i              mini
  54.                   serlibbase.h          mini.c
  55.                   serlibbase.i          sert
  56.                   serlib_lvos.asm       sert.c
  57.                   makefile              antrag.lzh
  58.                   OberonSerLib.lzh
  59.  
  60. In  order  to  install  the  library  and  additional  files, copy the file
  61. `serlib.library' to your LIBS:-directory.  Users of MANX' Aztec C will have
  62. to   create  the  Library-Stubs  from  the  sources  included  in  the  two
  63. .lzh-Files.   (I  don't use Aztec anymore, and didn't want to re-install it
  64. on my HD, sorry).  Anyway, it shouldn't be a problem.
  65.  
  66. If  you use Lattice/SAS C, you have to decide if you want to use pragmas to
  67. call  the  library  functions,  or  want  to use the .lib-File.  If you use
  68. pragmas, you can forget about `serlib_SAS.lib' (created with V5.10a).  Now,
  69. copy the .h- and .i-Files to your include-directory.  That's it already.
  70.  
  71. If  you should have a modem attached to your computer, just start `sert' or
  72. `mini'.   The  first  is a small test-program that asks for some modem-help
  73. (AT$,   at   least  it  does  on  my  HST...),  the  second  is  a  minimal
  74. terminal-program  that  lets you input a line, sends the line to the modem,
  75. prints the modems answer, etc.  Nothing great, just a test program.
  76.  
  77. Take  a  look  at  the archive `antrag.lzh', it includes an example program
  78. using  the  the library.  This program also has some nice routines built in
  79. for  string handling.  Please note that handling has changed from the first
  80. release  version due to additional routines for asynchronous transfers.  In
  81. order  to  add  these functions, programs using the function WaitSer() will
  82. most  likely break using version 3.0.  Sorry...  (take a look at the source
  83. of Antrag to see how to fix it, just a minor workaround...)
  84.  
  85. As  I  released a couple different versions and revisions in a rather short
  86. time  (between  Feb.   6th  and  Feb.  16th), here's some comments on those
  87. versions:
  88.  
  89. Version 1.0 -- not released to the public, just a few testers.
  90. Version 1.1 -- first release version, no known bugs; only had synchronous
  91.                transfer.
  92. Version 2.0 -- new version with asynchronous support. Due to large changes
  93.                and too little testing time, this version had some terrible
  94.                bugs.
  95. Version 2.1 -- most of the bigger bugs removed. Has some troubles when
  96.                Wait()ing.
  97. Version 2.2 -- removed the WaitSer()-bug, ORed in wrong direction. This was
  98.                hoped to be the `final' version.
  99. Version 3.0 -- as I still have some strange behavior with the WaitSer()-
  100.                Function, some more testing revealed a MOVEM, that did too
  101.                much and restored an old value in D0 ... removed, hopefully
  102.                this is the final version... (until some new ideas come
  103.                around the corner...)
  104.  
  105. The  next  version will probably include easy access to XPR-libraries, plus
  106. some  functions  still  missing now (any wishes ?).  Also, I plan to add an
  107. extra chapter with some examples on how to use the library...
  108.  
  109.  
  110.                     __________________________________
  111.  
  112.                            Using other languages
  113.                     __________________________________
  114.  
  115.  
  116. Additionally  to  the  original  implementation,  which  includes  code for
  117. calling  SerLib.Library from either C or Assembler, I've included some code
  118. from  Frank  Schummertz,  that  demonstrates  the usage of the library from
  119. Oberon.   The  archive  `OberonSerLib.lzh' includes the files as I received
  120. them from Frank.
  121.  
  122. To  use  any of SerLib.Libraries routines, just link the file `serlib.objs'
  123. to  the  other objects.  Check the example program for some hints on how to
  124. use the library from Oberon.  There shouldn't be any problems, though.
  125.  
  126.  
  127.                     __________________________________
  128.  
  129.                            THE LIBRARY FUNCTIONS
  130.                     __________________________________
  131.  
  132.    NAME   
  133.     AbortIOSer -- abort a previous SendSer or RecvSer
  134.  
  135.    SYNOPSIS
  136.     AbortIOSer( serlibdata, which);
  137.                    A0       D0:16
  138.  
  139.     AbortIOSer(struct SerLibdata *, ULONG);
  140.  
  141.    FUNCTION
  142.     AbortIOSer will perform an AbortIO() on a previous SendSer()- or
  143.     RecvSer()-Command.
  144.     By setting the appropriate bit in `which', either the SendSer() or
  145.     RecvSer() is aborted.
  146.  
  147.    INPUTS
  148.     serlibdata  - pointer returned by OpenSerial
  149.     which       - Either `ABORT_SEND' or `ABORT_RECV'
  150.  
  151.    RESULT
  152.     None
  153.  
  154.    SEE ALSO
  155.     OpenSerial(), SendSer(), RecvSer()
  156.  
  157.  
  158.    NAME   
  159.     ChangeData -- change the serial setup 
  160.  
  161.    SYNOPSIS
  162.     ChangeData( serlibdata, baud, bpc, stop, serFlags )
  163.                     A0       D0  D1:16 D2:16   D3:16
  164.  
  165.     ChangeData( struct SerLibData *, ULONG, UWORD, UWORD, UWORD);
  166.  
  167.    FUNCTION
  168.     Changes the setup of the serial port.
  169.  
  170.    INPUTS
  171.     serlibdata - Pointer returned by OpenSerial()
  172.     baud       - the baud rate at which the port will be operated.
  173.     bpc        - Bits per character (normally `8').
  174.     stop       - number of stop-bits (normally `1', may be `0' through `2')
  175.     serFlags   - Flags for the device.  Entered directly in
  176.                  io_SerFlags of the IOExtSer-structure.  See
  177.                  `devices/serial.h' for values to enter.
  178.  
  179.    RESULT
  180.     None
  181.  
  182.    NOTES
  183.     No sanity-check of the values given to ChangeDate.  So you
  184.     can use a baud rate of 27182 Baud, 20 Bits per character and
  185.     42 stop bits.  There's no telling how serial.device will
  186.     react to such a change-request...
  187.  
  188.    SEE ALSO
  189.     OpenSerial(), devices/serial.h
  190.  
  191.  
  192.    NAME   
  193.     CheckCD -- check if the modem has a Carrier detected
  194.  
  195.    SYNOPSIS
  196.     carrier = CheckCD( serlibdata )
  197.       D0                   A0
  198.  
  199.     ULONG CheckCD( struct SerLibData * );
  200.  
  201.    FUNCTION
  202.     Checks if a carrier is detected.
  203.  
  204.    INPUTS
  205.     serlibdata      - pointer returned by OpenSerial()
  206.  
  207.    RESULT
  208.     carrier         - 0 if no carrier, 1 if carrier is detected
  209.  
  210.    NOTES
  211.     If you need both carrier detect and number of bytes, a call
  212.     to GetStatus() and checking in the SerStatus-structure will be
  213.     faster as both SerBuffer() and CheckCD() call GetStatus() internally.
  214.  
  215.    SEE ALSO
  216.     OpenSerial(), GetStatus(), serlib.h, devices/serial.h
  217.  
  218.  
  219.    NAME   
  220.     CheckIOSer -- check if a previous RecvSer is finished
  221.  
  222.    SYNOPSIS
  223.     return = CheckIOSer( serlibdata );
  224.       D0                     A0
  225.  
  226.     BOOL CheckIOSer(struct SerLibdata *);
  227.  
  228.    FUNCTION
  229.     CheckIOSer will perform a CheckIO() on a previous RecvSer()-Command.
  230.  
  231.    INPUTS
  232.     serlibdata  - pointer returned by OpenSerial
  233.  
  234.    RESULT
  235.     return      - Return-value of CheckIO()-call.
  236.  
  237.    SEE ALSO
  238.     OpenSerial(), SendSer(), RecvSer(), AbortIOSer()
  239.  
  240.  
  241.    NAME   
  242.     ClearSer -- Clear the serial buffer
  243.  
  244.    SYNOPSIS
  245.     ClearSer( serlibdata )
  246.                   A0
  247.  
  248.     ClearSer( struct SerLibData *);
  249.  
  250.    FUNCTION
  251.     ClearSer empties out the serial receive buffer by doing a CMD_CLEAR.
  252.  
  253.    INPUTS
  254.     serlibdata  - Pointer returned by OpenSerial()
  255.  
  256.    RESULT
  257.     None
  258.  
  259.    SEE ALSO
  260.     OpenSerial()
  261.  
  262.  
  263.    NAME   
  264.     CloseSerial -- Close the serial.device
  265.  
  266.    SYNOPSIS
  267.     CloseSerial( serlibdata )
  268.                     A0
  269.  
  270.     CloseSerial( struct SerLibData * );
  271.  
  272.    FUNCTION
  273.     After being finished, use this to close the device and free
  274.     all memory allocated.
  275.  
  276.    INPUTS
  277.     serlibdata   - Pointer returned by OpenSerial.
  278.  
  279.    RESULT
  280.     None
  281.  
  282.    NOTES
  283.     No sanity check, better not get the idea to give this one a Null-
  284.     pointer! If the SerLibData-structure should be trashed, it could
  285.     lead to minor problems, too!
  286.  
  287.    SEE ALSO
  288.     OpenSerial(), serlib.h
  289.  
  290.  
  291.    NAME   
  292.     GetStatus -- get the Status data from the serial port
  293.  
  294.    SYNOPSIS
  295.     GetStatus( serlibdata, serstatus )
  296.                    A0          A1
  297.  
  298.     GetStatus( struct SerLibData *, struct SerStatus *);
  299.  
  300.    FUNCTION
  301.     Gets the status data from the serial port. Additionally, the number
  302.     of bytes in the system's serial buffer are also returned in the
  303.     SerStatus-structure.
  304.  
  305.    INPUTS
  306.     serlibdata     - pointer returned by OpenSerial()
  307.     serstatus      - address of a SerStatus-structure
  308.  
  309.    RESULT
  310.     serstatus      - filled structure
  311.  
  312.    NOTES
  313.     As usual, no sanity check.
  314.  
  315.    SEE ALSO
  316.     OpenSerial(), serlib.h, devices/serial.h
  317.  
  318.  
  319.    NAME   
  320.     OpenSerial -- Open the serial device for access through serlib.library
  321.  
  322.    SYNOPSIS
  323.     serlibdata = OpenSerial( device, unit, baud, bpc, stop, serFlags )
  324.        D0                      A0    D0:16  D1  D2:16 D3:16  D4:16
  325.  
  326.     struct SerLibData *
  327.                 OpenSerial( STRPTR, UWORD, ULONG, UWORD, UWORD, ULONG);
  328.  
  329.    FUNCTION
  330.     This routine attempts to open the serial.device for usage with
  331.     serlib.library.
  332.  
  333.    INPUTS
  334.     device     - the device to be opened.  Normally "serial.device".
  335.                  Change when using internal modems or multiple line
  336.                  serial cards.
  337.     unit       - the unit to open.  Normally `0', other when using a
  338.                  multiple line serial card.
  339.     baud       - the baud rate at which the port will be opened.
  340.     bpc        - Bits per character (normally `8').
  341.     stop       - number of stop-bits (normally `1', may be `0' through `2')
  342.     serFlags   - Flags for opening the device.  Entered directly in
  343.                  io_SerFlags of the IOExtSer-structure.  See
  344.                  `devices/serial.h' for values to enter.
  345.  
  346.    RESULT
  347.     serlibdata - pointer to the SerLibData-structure containing the
  348.                  paramteres for working with the port.  This pointer
  349.                  will be needed for every function call to
  350.                  serlib.library.
  351.  
  352.    NOTES
  353.     No sanity-check of the values given to OpenSerial.  So you
  354.     can use a baud rate of 27182 Baud, 20 Bits per character and
  355.     42 stop bits.  There's no telling how serial.device will
  356.     react to such an open-request...
  357.  
  358.    SEE ALSO
  359.     CloseSerial(), serlib.h, serlibbase.h, devices/serial.h
  360.  
  361.  
  362.    NAME   
  363.     ReadSer -- read bytes from the serial port
  364.  
  365.    SYNOPSIS
  366.     number = ReadSer( serlibdata, buffer, max )
  367.       D0                 A0         A1     D0
  368.  
  369.     ULONG ReadSer(struct SerLibdata *, STRPTR, ULONG);
  370.  
  371.    FUNCTION
  372.     Upon calling, ReadSer first checks how many bytes there are still
  373.     left to be read. If 0, it will return right away.
  374.     Otherwise, ReadSer will send a CMD_READ to the serial device with
  375.     IO_SIZE set to the number of bytes unread (or `max' if max is smaller)
  376.     If you get a return value that is equal to `max', you should process
  377.     the data received and then go back and get the rest.
  378.  
  379.    INPUTS
  380.     serlibdata  - pointer returned by OpenSerial
  381.     buffer      - pointer to a block of memory to be filled with data
  382.                   from the serial port
  383.     max         - size of the buffer. A maximum of `max' bytes will be
  384.                   read.
  385.  
  386.    RESULT
  387.     len         - number of bytes read from the port.
  388.  
  389.    NOTES
  390.     You might get in trouble if you set `max' to zero..
  391.  
  392.    SEE ALSO
  393.     OpenSerial()
  394.  
  395.  
  396.    NAME   
  397.     RecvSer -- read bytes from the serial port
  398.  
  399.    SYNOPSIS
  400.     RecvSer( serlibdata, buffer, num )
  401.                A0         A1     D0
  402.  
  403.     RecvSer(struct SerLibdata *, STRPTR, ULONG);
  404.  
  405.    FUNCTION
  406.     RecvSer will initiate a SendIO-call to the serial port, trying to
  407.     receive num bytes.
  408.  
  409.    INPUTS
  410.     serlibdata  - pointer returned by OpenSerial
  411.     buffer      - pointer to a block of memory to be filled with data
  412.                   from the serial port
  413.     num         - size of the buffer. `num' bytes will be read if the
  414.                   IORequest isn't aborted.
  415.  
  416.    RESULT
  417.     None
  418.  
  419.    NOTES
  420.     You might get in trouble if you set `num' to zero..
  421.  
  422.    SEE ALSO
  423.     OpenSerial(), ReadSer()
  424.  
  425.  
  426.    NAME   
  427.     SendSer -- Send a string to the serial port without waiting
  428.  
  429.    SYNOPSIS
  430.     SendSer( serlibdata, buffer, len)
  431.                  A0        A1    D0
  432.  
  433.     SendSer( struct SerLibData *, STRPTR, ULONG);
  434.  
  435.    FUNCTION
  436.     SendSer takes a buffer pointer and sends the specified number of bytes
  437.     to the serial port using the SendIO() function, so it doesn't wait for
  438.     completion of the command.
  439.  
  440.    INPUTS
  441.     serlibdata  - Pointer returned by OpenSerial()
  442.     buffer      - Pointer to a memory block containing the data for the
  443.                   serial port
  444.     len         - number of bytes to be sent
  445.  
  446.    RESULT
  447.     None
  448.  
  449.    NOTES
  450.     No sanity check, as usual.
  451.  
  452.    SEE ALSO
  453.     OpenSerial(), WriteSer()
  454.  
  455.  
  456.    NAME   
  457.     SerBuffer -- get the number of bytes still in the buffer
  458.  
  459.    SYNOPSIS
  460.     result = SerBuffer( serlibdata )
  461.       D0                   A0
  462.  
  463.     ULONG SerBuffer(struct SerLibData *)
  464.  
  465.    FUNCTION
  466.     Returns the number of bytes still in the system's serial buffer.
  467.  
  468.    INPUTS
  469.     serlibdata     - pointer returned by OpenSerial()
  470.  
  471.    RESULT
  472.     result         - number of bytes in the buffer
  473.  
  474.    NOTES
  475.     If you need both number of bytes and the carrier detect, a call
  476.     to GetStatus() and checking in the SerStatus-structure will be
  477.     faster as both SerBuffer() and CheckCD() call GetStatus() internally.
  478.  
  479.    BUGS
  480.     Would be hard for this one to have any.
  481.  
  482.    SEE ALSO
  483.     OpenSerial(), GetStatus(), serlib.h
  484.  
  485.  
  486.    NAME   
  487.     WaitSer -- wait for data from the serial port
  488.  
  489.    SYNOPSIS
  490.     signal = WaitSer( serlibdata, mask )
  491.       D0                  A0       D0
  492.  
  493.     ULONG WaitSer(struct SerLibData *, ULONG);
  494.  
  495.    FUNCTION
  496.     Waits for a signal bit set. Waits for the one of the serial port,
  497.     plus the ones you specify (timer, break, etc.).
  498.  
  499.    INPUTS
  500.     serlibdata      - Pointer returned by OpenSerial()
  501.     mask            - mask of signals waited for
  502.  
  503.    RESULT
  504.     signal          - set of signals that were active
  505.  
  506.    NOTES
  507.     This function has changed slightly from release 1.1. It doesn't do
  508.     a dummy-Read to the serial port any more, so in order to use it, add an
  509.     extra `RecvSer()' before calling WaitSer().
  510.  
  511.  
  512.    NAME   
  513.     WriteSer -- Send a string to the serial port
  514.  
  515.    SYNOPSIS
  516.     WriteSer( serlibdata, buffer, len)
  517.                   A0        A1    D0
  518.  
  519.     WriteSer( struct SerLibData *, STRPTR, ULONG);
  520.  
  521.    FUNCTION
  522.     WriteSer takes a buffer pointer and sends the specified number of bytes
  523.     to the serial port.
  524.  
  525.    INPUTS
  526.     serlibdata  - Pointer returned by OpenSerial()
  527.     buffer      - Pointer to a memory block containing the data for the
  528.                   serial port
  529.     len         - number of bytes to be sent
  530.  
  531.    RESULT
  532.     None
  533.  
  534.    NOTES
  535.     No sanity check, as usual.
  536.  
  537.    SEE ALSO
  538.     OpenSerial()
  539.  
  540.  
  541.                     __________________________________
  542.  
  543.                      USING SERLIB.LIBRARY IN PROGRAMS
  544.                     __________________________________
  545.  
  546.  
  547. SerLib.Library  is  Shareware.   You may copy it on non-profit-basis as you
  548. wish.   Anyway,  I  do not consider the german PD-`Distributors' working on
  549. `non-profit'  basis  (how  can you make a living when working on non-profit
  550. basis  ?),  so before selling SerLib on _any_ disks, german dealers have to
  551. get written permission from me.
  552.  
  553. After  using SerLib.Library for a while, you have to register by sending me
  554. the  shareware  fee  of DM 20.- / US$ 15.  This will get you a free copy of
  555. the next version (including other programs finished at that time).
  556.  
  557. When  using  SerLib.Library  in a PD or Shareware-program, include both the
  558. library  and  the file `SerLibLibrary.Readme' with the program.  Anyway, if
  559. you  do,  I  would appreciate a copy of the program (either via email or on
  560. disk).   Additionially,  you  have  to  register  as  I  presume  you  find
  561. SerLib.Library very useful!
  562.  
  563. Commercial  programs  using it need a special registration.  Contact me for
  564. further details.
  565.  
  566. Remember,  supporting  shareware  authors helps to keep up the standards of
  567. free and affordable software!
  568.  
  569. If you have problems or bug reports, need help or just want to send me the
  570. shareware fee, use one of the addresses below:
  571.  
  572.       from any country:                   from the US:
  573.       Garry Glendown                      Garry Glendown
  574.       Güldene Kammer 35                   Box R
  575.       W-6430 Bad Hersfeld                 APO NY 09141
  576.       (Germany)
  577.  
  578. Telephone: 06621-77923 (HST/V32bis), give me a yell for voice call...
  579.  
  580. eMail may be sent to any of the following addresses:
  581.     ..cbmvax!cbmger!inside!garry
  582.     Garry@DGIHRZ01.BITNET
  583.     Garry@fulmin.zer.sub.org
  584.     Garry Glendown @ 2:243/43.999
  585.  
  586.  
  587.