====== V124=====

^Published By^Date^Version^Knowledge Level^Keywords^
|Revelation Technologies|14 NOV 1989|2.X|EXPERT|V124|

V124 provides facilities for low level access to an 
asynchronous communications port.

<code>
V124(operator, device.var, buffer, bytes, status)
</code>

==== Using V124 ====

By using V124, data may be read from or written to a port, 
and communication settings may be altered, although this is 
more easily accomplished using the system subroutine V123.  
For MS-DOS, the device driver COMMDVR.IBM must be an 
assigned device in the CONFIG.SYS file (see the TCL command 
TERMINAL).  For OS/2, the device driver can be either 
COM01.SYS or COM02.SYS.

=== operator ===

Use operator to pass a literal value indicating the operation 
to perform.  The following is a list of the operators 
available:

^Operator^Operation^
|OP|Opens a port to device.var.  This should always be preceded by an R/BASIC FLUSH operation.|
|CL|Closes the port associated with device.var.  An opened port must be closed to avoid subsequent corruption of files.|
|CI|Control In.  Reads the current settings for the port (see CO below for a description of these settings).|
|CO|Control Out.  Sets the communication parameters for the port (see the system subroutine V123 for further information regarding these parameters).  This must be a string of seven ASCII characters (7 bytes) passed in buffer and specifying the new settings.  The format is as follows:\\ \\ __Byte #__ - __Description__\\ 1 - An ASCII character (not an integer) specifying the baud rate code.  The codes are as follows:\\ Code - Baud rate\\ 1 - 50\\ 2 - 75\\ 3 - 110\\ 4 - 134.5\\ 5 - 150\\ 6 - 200\\ 7 - 300\\ 8 - 600\\ 9 - 1200\\ 10 - 1800\\ 11 - 2000\\ 12 - 2400\\ 13 - 3600\\ 14 - 4800\\ 15 - 9600\\ 16 - 19200\\  \\ 2 - An ASCII character (not an integer) indicating the number of stop bits\\ \\ 3 - An ASCII character (not an integer) indicating the number of data bits\\ \\ 4- A literal character indicating the parity mode\\ \\ 5 & 6 - Protocol.  This is two bytes in length, and requires setting bits 4 and 16.  Bit 4 indicates XOFF mode if set.  Bit 16 indicates STRIP mode if set.\\ \\ 7 - An ASCII character (not an integer) indicating the break count|
|RD|Read.  Data is read from buffer.  V124 does not wait for a [CRLF], but reads whatever data is in the buffer.|
|WR|Write.  The data specified in buffer is written to the port.|
|TB|Test Break.  If the break key is pressed, a break signal is sent to the port.|

=== device.var ===

Use device.var in an OP operation to return the DOS internal 
variable for the device driver.  This variable is used by 
subsequent V124 operators.

=== buffer ===

Use buffer to pass the DOS internal name for the 
communications port to access when opening device.var; or, in 
the case of a CI or WR specified operator, the data to write 
to the port.  The ASCII character 0 must be appended to the 
DOS internal name specified (as a terminator).

=== bytes ===

Use bytes to pass the number of bytes required for the 
operation.  This parameter is used only with a CI operator.

=== status ===

V124 returns false in status if the operation is successful, 
or true if not.  This parameter is used only with an OP or 
CI operator.

==== Values returned ====

If operator is CI or RD, the data is passed in buffer.  If 
operator is CI or OP, status returns true if the operation is 
successful and false if not.

==== Correct Use of V124 ====

<code>
* The following code demonstrates the use of V124

DECLARE SUBROUTINE V123, V124, MSG
DECLARE FUNCTION FUNCTION.KEY

device.var = ""
buffer     = "COMM$":CHAR(0)
bytes      = ""
status     = ""

* Flush buffers and open the port
FLUSH
V124("OP", device.var, buffer, "", status)
IF status THEN
    MSG("Unable to open the device","","","")
    STOP
END

* A simple terminal emulator
MSG("Initializing terminal emulation mode","","","")
stop.key = FUNCTION.KEY("F9")     ;* exit key
*Input loop, alternately checking input buffer and keyboard

buffer = ""
LOOP UNTIL buffer = stop.key
V124("RD", device.var, buffer) ;* check buffer
PRINT buffer:      ;* echo to screen
V124("TB" ,buffer)  ;* test for break key
    ;* get keyboard input and echo to screen
IF buffer NE stop.key THEN
* Write keyboard input to buffer
V124("WR", device.var, buffer) 
END
REPEAT
V124("CL", device.var)                 ;* close port
MSG("Ending terminal emulation","","","")
STOP
</code>