************************
INFORMAES EM PORTUGUES
************************
HBComm Lib
Essa  a alterao mais recente da biblioteca HBComm.
As modificaes feitas por mim refletem as necessidades de uma biblioteca
de porta serial que pode conversar com mais de uma porta serial de cada vez.
Alm disso, as rotinas originais seriam lidar somente texto no criptografado
e no corretamente passariam Dados contendo caracteres nulos (Chr(0)).
Finalmente, acessar portas acima COM9 era um dever.

A principal diferena na sintaxe  a necessidade do usurio receber
o "Identificador" retornado pelo Init_Port() e pass-lo para todas as
outras rotinas sempre referenciar uma porta.
Isso equivale  varivel nComm usado nas antigas rotinas seriais Clipper/Fivewin.

Informaes das Funes:

Init_Port( cPort, nBaudrate, nDatabits, nParity, nStopbits, nBuffersize ) --> nHandle

*Inicialiazador da Porta Serial

     Where:

     cPort       Port que deve se conectar com a Porta Serial at a COM9

     nBaudrate   Exatamente como voc est acostumado (por exemplo, 2400, 9600, 4800 etc..)

     nDatabits   No Geral  8, mas pode ser 7 ou 4.
 
     nParity     codificados: 0,1,2,3-> nenhuma, mpar, marcar, at mesmo

     nStopbits   codificados: 0,1,2 -> 1, 1.5, 2

     nBuffersize ESTA usando 8000 na transmisso 38.400.

     nHandle     identificador retornado instncia.  Um numrico > = 256.  Se nHandle for negativo, a abertura falha.

OutBufClr( nHandle ) --> lSuccess

     Limpe o buffer de sada.  lSuccess ser sempre TRUE, a menos que seja usada uma nHandle incorreto.


IsWorking( nHandle ) --> lSuccess

     Verifica se a porta  valida para uso. Falhas podem ocorrer se um nHandle incorreto
      usado ou se a parte remota descarta a linha. Retorno ".T." ou ".F."

InChr( nHandle, @cBuff, nChar ) --> nBytesRead

     Busca dados do buffer de entrada. Observao o pelo argumento de referncia passando para o buffer.
     nChar pode ser determinada chamando InBufSize(). nBytesRead  o nmero real de bytes carregados
     no cBuff (geralmente igual a nChar a menos que h um problema ou nChar  exagerada.)

InBufSize( nHandle ) --> nNumberofBytesInInputBuffer

     Obter a contagem dos bytes Aguardando no buffer de entrada.
     Geralmente, seguido por uma chamada DO Inchr() para buscar os bytes para processamento.


OutChr( nHandle, cBytesToWrite, nCount ) --> lSuccess

     Escreva os primeiros bytes nCount de cBytesToWrite de seqncia de caracteres.
     Geralmente, nCount == len(cBytesToWrite).


OutBufSize( nHandle ) --> nBytesInOutputBuffer

     Obter a contagem de bytes de caracteres aguardando transmisso.

UnInt_Port( nHandle ) --> lSuccess

     (Fechar) na porta e liberar o identificador.


SIMPLES EXEMPLO DE USO:

******************************************
STATIC nHandle
IF OpenOk()  // FAZ A ABERTURA DA PORTA 
   DOProcessing()
ELSE        // CASO CONTRARIO ELE DAH ERRO  
   ALERT( 'Erro ao abrir a Porta !!!' )
   QUIT
ENDIF

*****************
Function OpenOk()  // abre a porta serial
*****************
IF ( nHandle := Init_Port( 'COM1', 9600, 8, 0, 0, 8000 ) ) > 0   // pode mudar conforme a nescessidade
   OutBufClr( nHandle )   // limpa a porta
   Return IsWorking()     // retorna a leitura da porta
ENDIF
Return FALSE

***********************
Function DOProcessing() // FAZ A VARREDURA NA PORTA
***********************
nChr := InBuffSize( nHandle )
cBuff := Space( nHandle )

IF nChr != InChr( nHandle, @cBuff, nChr )
   ALERT( 'ERRO NA LEITURA DA PORTA' )
   Return FALSE
ENDIF

IF ! OutChr( nHandle, cSomeStuff, Len( cSomeStuff ) )  // COMPARA A LEITURA COM OS BYTES RECEBIDOS
   ALERT("ERRO NA VERIFICAO")
   Return FALSE
ENDIF
UnInt_Port( nHandle )  // FECHA A PORTA
Return NIL


Traduo By Leonardo Machado.

Porto Alegre, 05 de Janeiro de 2007


********************************************************************************************************
********************************************************************************************************
********************************************************************************************************
********************************************************************************************************
********************************************************************************************************
********************************************************************************************************
********************************************************************************************************
********************************************************************************************************

**********************
INFORMATION IN ENGLISH
**********************
HBComm Library

This is the latest iteration of the HBComm library.  The modifications made
by me reflect my needs for a serial port library that could talk to more than
one serial port at a time.  Further, the original routines would handle only
clear text and would not correctly pass data containing null characters
(Chr(0)).  Finally, accessing ports above COM9 was a must.

The major difference in syntax is the need for the user to receive the
"Handle" returned by Init_Port() and pass it to all other routines whenever
referencing a port.  This is equivalent to the nComm variable used in the
old Clipper/Fivewin serial routines.

Function Information:

Init_Port( cPort, nBaudrate, nDatabits, nParity, nStopbits, nBuffersize ) -->
   nHandle

   Port opener and initializer.

   Where:

     cPort      Port designator.  Can either be old form 'COMn' or the more
                general form '\\.\COMn'.  The general form is required for
                ports higher than COM9.

     nBaudrate  Just like you're used to (e.g., 2400, 4800, 9600, etc. )

     nDatabits  Usually 8, but can be 7 or 4.

     nParity    coded: 0,1,2,3 -> none, odd, mark, even

     nStopbits  coded: 0,1,2 -> 1, 1.5, 2

     nBuffersize I'm using 8000 at 38,400 baud.

     nHandle    returned instance identifier.  A numeric >= 256.  If nHandle
                is negative, the open failed.

OutBufClr( nHandle ) --> lSuccess

     Clear the output buffer.  lSuccess will always be TRUE unless a bad
     nHandle is used.

IsWorking( nHandle ) --> lSuccess

     Check to see if port is operative.  Failures can occur if a bad nHandle
     is used or if remote party drops the line.

InChr( nHandle, @cBuff, nChar ) --> nBytesRead

     Fetch data from the input buffer.  Note the by reference argument passing
     for the buffer.  nChar can be determined by calling InBufSize().
     nBytesRead is the actual number of bytes loaded into cBuff (usually
     equal to nChar unless there is a problem or nChar is overstated.)

InBufSize( nHandle ) --> nNumberofBytesInInputBuffer

     Get the count of bytes waiting in the input buffer.  Usually followed by
     a call to Inchr to fetch the bytes for processing.

OutChr( nHandle, cBytesToWrite, nCount ) --> lSuccess

     Write the first nCount bytes from the string cBytesToWrite.  Usually,
     nCount == Len( cBytesToWrite ).

OutBufSize( nHandle ) --> nBytesInOutputBuffer

     Get the byte count of characters awaiting transmission.

UnInt_Port( nHandle ) --> lSuccess

     Uninitialize (Close) the port and free the handle.

USAGE:

Here's how I do this stuff...

STATIC nHandle

...Mainline...


IF OpenOk()

   DOProcessing()

ELSE

   MsgStop( 'Cannot open port!' )

   QUIT

ENDIF

Function OpenOk()

// Open the port

IF ( nHandle := Init_Port( 'COM1', 9600, 8, 0, 0, 8000 ) ) > 0

   OutBufClr( nHandle )   // limpa a porta

   Return IsWorking()

ENDIF

Return FALSE

Function DOProcessing()

...

// Get a chunk from the COM port

nChr := InBuffSize( nHandle )
cBuff := Space( nHandle )

IF nChr != InChr( nHandle, @cBuff, nChr )

   MsgStop( 'Some kind of read failure on COM Port.' )

   Return FALSE

ENDIF

// process data in cBuff

// write some stuff to port

IF ! OutChr( nHandle, cSomeStuff, Len( cSomeStuff ) )

   MsgStop( 'Write error on COM Port.' )

   Return FALSE

ENDIF

// ...etc

// and finally, when night is nigh...

// Close the port

UnInt_Port( nHandle )

Return NIL


Any further contributions to this library are most welcome.

Ned Robertson
XpertCTI, LLC
Richmond, VA  USA

July 21, 2003

