COMPORT Object +
Updated: March 18, 2006

A communications port (com1, com2, com3, com4, etc) may be opened, read and/or
written and closed.

Once opened for IO (.Open method), a communications port configuration can
optionally be read (.GetCom method) or changed (.SetCom method).

For external device automation and robotics fans, note that parallel port IO
is very easy in HotBasic -- just .Open "lpt1", "lpt2", etc, as a FILE and go
straight to the FILE object read/write methods!


PROPERTIES (Read/Write):
~~~~~~~~~~ ~~~~~~~~~~~~~
BaudRate   Default = 1200

ByteSize   Default = 8

EofChar    End of input character; Default = 0 

ErrorChar  Error replacement character; Default = 0

EvtChar    Received event character; Default = 0

Flags      Default = &H1011 (fBinary; fDtrControl=1; fRtsControl=1)

  Flag bits (Microsoft DCB structure):
  fBinary            &H1  'binary mode; no EOF check
  fParity            &H2  'enables parity checking
  fOutxCtsFlow       &H4  'CTS output flow control
  fOutxDsrFlow       &H8  'DSR output flow control
  fDtrControl       &H30  'DTR flow control type (2 bits)
  fDsrSensitivity   &H40  'DSR sensitivity
  fTxContinueOnXoff &H80  'XOFF continues Tx
  fOutX            &H100  'XON/XOFF out flow control
  fInX             &H200  'XON/XOFF in flow control
  fErrorChar       &H400  'enables error replacement
  fNull            &H800  'enables null stripping
  fRtsControl     &H3000  'RTS flow control (2 bits)
  fAbortOnError   &H4000  'abort read/write on error

  To set Flag bits:    MyPort.Flags = MyPort.Flags OR MyBits
  To clear Flag Bits:  MyPort.Flags = MyPort.Flags XOR MyBits

Parity     Default = 0 (0=none; 1=odd; 2=even; 3=mark; 4=space)

StopBits   Default = 0 (0=1; 1=1.5; 2=2)

XoffChar   Tx and Rx XON character; Default = 19

XoffLim    Transmit XOFF threshold; Default = 512

XonChar    Tx and Rx XON character; Default = 17

XonLim     Transmit XON threshold; Default = 2048


PROPERTIES (Read Only Numeric):
~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
Handle     ComPort handle

Mode       Mode used to open ComPort.  Please see .Open

ReadNum    (bytes) Reads bytes number of bytes
           MyInteger = MyPort.ReadNum(4)

  Note: Bytes read are assigned to number which can be any numerical data type.
  Bytes read should generally be confirmed (please see Notes below) and may be
  less than the number requested (4 in example above).


METHODS    Arguments & Comments
~~~~~~~    ~~~~~~~~~~~~~~~~~~~~
Close      Closes open ComPort.  MyPort.Close

GetCom     Reads open ComPort configuration (DCB) of properties above.

           MyPort.GetCom 

Open       (com_port, mode) Opens Comport
 
           DIM MyPort as COMPORT
           MyPort.Open "com2", 2  'open for read/write
           IF NOT MyPort.Handle THEN Goto FailPortOpen

           com_port is a string designating a valid communications port
           mode = 0 (read only), 1 (write only), 2 (read/write)

Read       (var) Reads var from ComPort.  MyPort.Read(MyByte)

SetCom     Sets open ComPort configuration (DCB) with properties above.

           MyPort.SetCom 

Write      (var) Writes var.  MyPort.Write(MyVar)

WriteNum   (var, bytes) Writes var as bytes of data

           MyPort.WriteNum(MyInt64, 8)

WriteStr   (string$, bytes) Writes bytes from string$

           MyPort.WriteStr(x$, 10)


###########
Notes:  

.GetCom will replace the defaults with the current settings of the port.
.SetCom uses current property settings to configure the port.
Both .GetCom and .SetCom require a previous successful .Open of a ComPort.

  MyVar = RETFUNC

gets method results:

1. ComPort handle or error after .Open
2. Number of bytes read or written after .Read, .Write, .WriteNum & .WriteStr

Editorial:
Yes, I know; "methods" don't have results or if they do, then they are
"read-only properties".  On the other hand, every time you assign a value to a
property, it does something, right?  Otherwise, you would not do it.  So
properties may be viewed as methods, too.

But let us humor those who think that the concepts of "property" and "method"
have some utility in writing computer programs. {smile}


+ PentHouse (registered) version

Copyright 2006 James J Keene PhD
Original Publication: March 5, 2006