• apwComUtil

ComUtil - Serial Communication Utility APL+Win Workspace

OVERVIEW

This workspace contains useful functions when dealing with Serial Communication.

DESCRIPTION

Here is a description of the functions:

     To Open a Communication Port and Obtain an Handle for Asynchronous Communication
     Usage: r←'Open' ASerCom v
v[1] = Valid Communication Port Number (ex.: 1, 2, 3, 4, etc.)
v[2] = Valid Baud Rate (300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 76800, 115200)
v[3] = Valid Number of Data Bits (4, 5, 6, 7, 8)
v[4] = Valid Number for Parity (0 = None, 1 = Odd, 2 = Even, 3 = Mark, 4 = Space)
v[5] = Valid Number of Stop Bits (1, 1.5, 2)
v[6] = (Optional) Valid Number for Flow Control (0 = None, 1 = XOn/XOff Software, 2 = RTS/CTS Hardware)

r[1] = 1 for Success, 0 for Failure
r[2] = Communication Handle if Success or Error Number if Failure
r[3] = Literal Error Code if Error


     To Write Characters Asynchronously to a Serial Port
     Usage: r←'Send' ASerCom v
v[1] = Port Handle Obtained from the Function: 'Open' ASerCom v
v[2] = Characters to be Written to the Communication Port

r[1] = 1 for Success, 0 for Failure
r[2] = Number of Bytes Written if Success or Numeric Error if Failure
r[3] = Literal Error Code if Error


     To Read Asynchronously the Characters Received from a Serial Port
     Usage: r←'Recv' ASerCom v
v[1] = Port Handle Obtained from the Function: 'Open' ASerCom v
v[2] = (Optional) Number of Characters to Receive of the Serial Port

r[1] = 1 for Success, 0 for Failure
r[2] = Number of Bytes Received if Success, Error Number if Failure
r[3] = Bytes Received if Success, Literal Error Code if Error

Specify the number of characters that you will receive (v[2]) if you know it.
It will be faster that way. Otherwise Windows will time-out and it will
take some milliseconds extra (LastCharacterTimeOut) for each Read operation.
Alternatively, you can specify a Last Character ('LastCharac') in the General
Variables Section. When this Characters Arrives in the Buffer Windows Will
Terminate Immediately the 'ReadFile' Operation Without Timing-Out.


     To Send and Receive Characters on a Serial Port
     Usage: r←ASerCom v
v[1] = Valid Communication Handle Obtained from 'Open' ASerCom v
v[2] = Characters to be Written to the Communication Port
v[3] = (Optional) Number of Characters to Receive of the Serial Port

r[1] = 1 for Success, 0 for Failure
r[2] = Number of Bytes Received if Success or Numeric Error if Failure
r[3] = Literal Error Code if Error

Specify the number of characters that you will receive (v[3]) if you know it.
It will be faster that way. Otherwise Windows will time-out and it will
take some milliseconds extra (LastCharacterTimeOut) for each Read operation.
Alternatively, you can specify a Last Character ('LastCharac') in the General
Variables Section. When this Characters Arrives in the Buffer Windows Will
Terminate Immediately the 'ReadFile' Operation Without Timing-Out.


     To Release the Communication Port Handle
     Usage: r←'Close' ASerCom v
  v  = Port Handle Obtained with the Function: 'Open' ASerCom v

r[1] = 1 for Success, 0 for Error
r[2] = Error Number if Error
r[3] = Literal Error Code if Error


     To Add the Serial Communication Calls to
     your APLW.INI File.  It should be done only once.
     Usage: 'SetIni' ASerCom 0

     The same description is Valid for the function 'SSerCom' that
     is for Synchronous (Nonoverlapped) Serial Communication.

EXAMPLES

Examples of the function ASerCom:

1.  To Add the Serial Communications Calls to your APLW.INI file.
    (Must be done only once)

   'SetIni' ASerCom 0


2.  To Obtain an Handle of the Communication Port
    To Open COM2 at 38400 bauds, 8 data bits, no parity and 1 stop bit

    r←'Open' ASerCom 2 38400 8 0 1

    r[1] = 1 if Successful
    r[2] = Handle if Successful


3.  To Communicate with a Device once you Have an Handle
    To Send the word 'HELLO' and get the Answer back from the Device

    r←ASerCom Handle 'HELLO'

    r[1] = 1 if Successful
    r[2] = number of bytes received
    r[3] = bytes received (Answer)


4.  To Release the Handle of the Communication Device

    r←'Close' ASerCom Handle

    r[1] = 1 if Successful



Note 1: This is a function with No Subroutine, just copy it
        into your WS and you are ready to use it after you have
        initialize your APLW.INI file by doing: 'SetIni' ASerCom 0

Note 2: See the Section 'SECTION TO SET GENERAL VARIABLES' at the Beginning
        of the program.  You may want to adjust them for your specific
        device (modem, bar code reader, serial port, etc)

Note 3: Look the Public Comments inside the function for more information
        and Options not describe here.

Note 4: If you prefer Synchronous (Nonoverlapped) Serial Communication Use
        the function 'SSerCom' instead of 'ASerCom' with the same Syntax.

VERSION

June 2005       - First Release of WS
July 2005       - Bug Fixes and Addition of 'SSerCom'

DOWNLOAD

The workspace in APL+Win version 5 can be downloaded here: ComUtil.w3

INFORMATION

CategoryApl2000