OVCOMM.DLL is a communications DLL for ObjectVision that uses the interrupt
routines within Windows to automatically place data that is received on COM1, 2,
3 or 4 into an ObjectVision field.  This approachs allows you to set up a
simple change event on a field to handle serial data as it appears.  The DLL
allows you to receive characters in random "bursts", or (more reasonably), to
specify a character (like CR or LF) that will trigger the placement of data into
the ObjectVision field.

NOTE:  This DLL uses features available only within Windows version 3.1 or greater.


********************************** Maintenance Release 1.01 ******************************
This version, dated 3/4/93, fixes various problems with the trigger character, as well as
insures that no data is lost during high speed transfers requiring multiple updates to the
OVField.
******************************************************************************************


Using OVCOMM.DLL with ObjectVision

  A sample application, TESTCOMM.OVD, is provided to demonstrate the use of
  the OVCOMM.DLL @functions.  You should review this application if the instructions
  below are not clear.

  1) Register the four @functions within OVCOMM.DLL by placing
     the following commands in the event tree for the application:

       @REGISTER("@OVOPENCOMM","ICCICzw","CommPortString,OVField,OVFieldLen,EOLChar","OVCOMM.DLL","OVOpenComm",0)
       @REGISTER("@OVWRITECOMM","IIC","CommPortNum,OutputString","OVCOMM.DLL","OVWriteComm",0)
       @REGISTER("@OVCLOSECOMM","II","CommPortNum","OVCOMM.DLL","OVCloseComm",0)
       @REGISTER("@OVSETCOMMSTATE","ICCCCCCAA","CommPortStr,Baud,Parity,Data,Stop,Flow,ParityCheck,CarrierDet","OVCOMM.DLL","OVSetCommState",0)

     It is probably easiest just to copy these from the event tree of TESTCOMM.OVD
     and paste them into your application.

  2) Open the desired COM port using:

       @ASSIGN(CommPortNumm,@OVOPENCOMM(CommPortStr,OVField,OVFieldLen,EOLChar))

     where:

       CommPortNum  = The return value from @OVOPENCOMM.  If thePort >= 0, the open was successful
                      and CommPortNum contains the reference value to be used for subsequent
                      @OVWRITECOMM and @OVCLOSECOMM calls.

       CommPortStr  = A string referencing the Com port to be opened.  Valid values are
                      "COM1", "COM2", "COM3" or "COM4".

       OVField      = The field within your ObjectVision application that will receive characters
                      from the selected COM port.

       OVFieldLen   = The maximum number of characters to place in OVField.  This is used to prevent
                      overflowing the ObjectVision field as well as to force the placement of characters
                      into OVField if the trigger character is never received.
       
       EOLChar      = The trigger character.  When this character appears, all data that
                      have been received since the last occurance of the trigger character are
                      placed in the field.  Use @CHAR(255) to indicate that no trigger character
                      exists - ie: put characters into OVField immediately as they are received.
                      Carriage Return (@CHAR(13)) is a common trigger character.

     See the event tree for the "OpenComm" button within the sample application for an example.

  3) Configure the COM port using:

       @ASSIGN(CommState,@OVSETCOMMSTATE(CommPortStr,Baud,Parity,Data,Stop,Flow,ParityCheck,CarrierDet))

     where:

       CommState    = The return value from @OVSETCOMMSTATE.  "0" indicates OK, other values
                      indicate failure to change the port configuration.

       CommPortStr  = A string referencing the Com port to be opened.  Valid values are
                      "COM1", "COM2", "COM3" or "COM4".

       Baud         = A string referencing the desired baud rate for the COM port.  Valid values
                      are "110", "300", "600", "1200", "2400", "4800", "9600" and "19200".

       Parity       = A string referencing the desired parity for the COM port.  Valid values
                      are "None", "Even", "Odd", "Mark" and "Space".

       Data         = A string referencing the desired number of data bits for the COM port.
                      Valid values are "5", "6", "7" and "8".

       Stop         = A string referencing the desired number of stop bits for the COM port.
                      Valid values are "1", "1.5" and "2".

       Flow         = A string referencing the desired method of flow control for the COM port.
                      Valid values are "Xon/Xoff", "Hardware" and "None".

       ParityCheck  = A boolean indicating where parity checking is to be performed on the
                      data as it is received.  Valid values are No for no parity check and
                      Yes to enable parity checking.

       CarrierDet   = A boolean indicating whether to check for Carrier before enabling
                      communications.  Valid values are No for no Carrier Detect and Yes
                      to enable Carrier Detection.

      NOTE 1: You MUST call @OVSETCOMMSTATE before using the COM port.
      NOTE 2: All strings are CASE SENSITIVE!


     See the event tree of the "OK" button on the "Configure Com Port" form within the sample
     application for more information.

  4) Write data out the COM port using @WRITECOMM as follows:

       @ASSIGN(NumWritten,@OVWRITECOMM(CommPortNum,OutputStr))

     where:

       NumWritten   = The number of characters successfully written out the COM port.  This
                      should match the number of characters in the output string.

       CommPortNum  = The COM port to use when transmitting the string.  This should be the
                      value returned from the @OPENCOMM call.

       OutputStr    = The characters to be written out the COM port.  This may be a literal
                      string ("ABCDEFG") or the name of an ObjectVision field.
                      NOTE:  Nothing is appended to the end of this string.  If the receiving
                      system expects transmissions to be terminated with a special character
                      (such as a carriage return), you MUST append this character yourself.
                      For example:

                      @ASSIGN(NumWritten,@OVWRITECOMM(CommPortNum,OutputStr&@CHAR(13)))

     See the event tree for the "WriteComm" button within the sample application
     for more information.

  5) Incoming data should appear within OVField as it appears or when EOLChar is received,
     (depending on how you called @OPENCOMM).  REMEMBER!  If the receiving system echos input,
     the characters transmitted with @WRITECOMM will appear in OVField.

     You will probably want to do something with the data that you receive, so you must act on
     it BEFORE it gets overwritten with the next set of data.  Luckily, ObjectVision makes this
     easy through the use of the CHANGE event.  See the event tree for the "Input" field in
     the sample application for a trivial example.  (It is left for you to do something more 
     useful!)

  6) Close the COM port using @CLOSECOMM as follows:

       @ASSIGN(CloseStatus,@OVCLOSECOMM(CommPortNum))

     where:

       CloseStatus   = An integer indicating the success or failure of the close request.
                       0 indicates that the close was successful.  Any other value indicates
                       failure.

       CommPortNum   = The COM port to close.  This should be the value returned from the
                       @OPENCOMM call.

     See the event tree for the "CloseComm" button within the sample application for
     more information.


This DLL was written for fun and is provided to you in this same spirit.  It is
not intended for commericial use or profit and may not be used for these purposes
without the written consent of the author.  Those wishing to use these routines
for purposes other than personal enjoyment should contact me via Compuserve.  Likewise,
those desiring source code, enhancements or wishing to express an opinion regarding 
this work should contact me via email.

I hope you find this software enjoyable.


Steve Ura
72406,3660