COMIO

Parameters

opcode  (Num)  [in]

specifies the operation according to these options:

Value	Meaning
1	Open port specified in the buffer parameter, return channel in channel
2	Close port specified by channel
4	Check if any characters available to read; return count in count
8	Input a maximum of count characters; see the count table below for special cases
16	Write exactly count characters (or up to null if count=0)

 

channel  (Num)  [out]

specifies the channel number associated with the port. This value is returned from the open operation, and must be passed to the subroutine for all other operations.

buffer  [in/out]

is usually a string variable to pass the data to be sent or received (for read/write operations). For the open operation, it is used to pass control information about the port settings, and must be mapped as follows:

MAP1 BUFFER

MAP2 BYTESIZE,B,1     ! 7=7 bits, 0 or 8 = 8 bits

MAP2 PARITY,B,1       ! 0=none, 1=odd, 2=even, 3=mark, 4=space

MAP2 STOPBITS,B,1     ! 0=1, 1=1.5, 2=2

MAP2 FLOWCTL,B,1      ! Add: 1=DTR/DSR, 2=RTS/CTS, 4=XON/XOFF

MAP2 MISC,B,2         ! Unused

MAP2 PORT,S,20        ! e.g. "COM1" (no colon)

 

status  (Num)  [out]

returns a status code or bit field indicating the level of success of failure of the operation:

Value	Meaning
0	Success
-1	Parameter error
-2	No more memory handles available
-3	Memory allocation failure
-4	Unable to create write event
-5	Unable to create read event
-6	Invalid channel passed in CH argument
-7	Unable to open connection to port
-8	Ctrl+C received while waiting for input
-9	Unable to set comm parameters; see History below.
>0	Bit field containing one or more port status error flags from the following table:

 

Value	Port Status Error Flags
&h0001	Input buffer overflow. (Either no room in input buffer, or char received after EOF)
&h0002	Buffer overrun (next character is lost)
&h0004	Parity error
&h0008	Framing Error
&h0010	Break detected
&h0100	Output buffer full
&h0200	Time out (parallel device)
&h0400	I/O error
&h0800	Device not selected (parallel device)
&h1000	Parallel device is out of paper
&h8000	Requested mode not supported

Hex-Decimal Values

 

count  (Num)  [in/out]

usage depends on the operation, as given in the table. Also see History, below.

Operation	Value	Usage of COUNT parameter
Open	1	Must be set to the desired baud rate.
Close	2	Ignored
Check	4	Returns number of characters available to be read.
Read	8	Must be set to either the number of characters you wish to read, or a special code (<=0) indicating the character you want to terminate the read on. The read routine will continue reading (and waiting if necessary) until the requested number of characters, or the requested terminating character, is received (up to the time limit specified by a timeout parameter > 0). To input up to a specific terminating character whose ASCII value is N, set count to -N. (For example, set count = -3 to input up to a byte chr(3).) 0 and -1 are historical exceptions to this formula. 0 inputs up to a terminating LF, while -1 inputs up to a terminating CR. (The terminating character, and in the case of LF, the immediately preceding CR, will be stripped from the buffer.) On return, count will be set to the number of bytes received, including any terminating character(s).
Write	16	Must be set to the number of characters to write (from the BUFFER parameter). You may set it to 0 to output up to the first null byte in the BUFFER string. On return, it will contain the number of characters actually output.

 

msg  (String)  [out]

returns the text of the Windows error message if an error occurs. The text will be truncated to fit, but for best results map msg to eighty-plus characters. If no error, then msg will be "". The error message begins with the actual Windows error code, making it easier to identify with precision.

timeout  (Num)  [in]

timeout value (in seconds), applies only to check (4), read (8) and write (16) operations. This is particularly useful when reading with the option to read until CR or LF, since if the data ends without sending a CR or LF, you could otherwise be stuck waiting forever. If timeout occurs, msg will be set to "TIME" (or possibly "(#) TIME" where # is an internal error code). The status and count parameters may or may not indicate an error, so when using the timeout option, you should always check msg to see if it contains the substring "TIME".

 

History

 

2010 October, 5.1.1193:  The timeout feature now applies to the check (4) operation as well as the read (8) and write (16) operations. Also, it now applies to all variations of the read operation. (Previously it only worked in the variation where it was reading up to a CR or LF.)

An internal timer interval which affected buffering and response time was reduced from 1 second to 1/10 second, potentially pauses of up to 9/10 of a second during sending and receiving operations.

2009 December, 5.1.1170:  A new status code -9 (unable to set comm parameters) has been added to distinguish when the open operation fails because of fundamental reasons (status -7) or because of an error while initializing the port (status -9). Also, the system error message (returned in the msg parameter) now begins with the actual Windows error code, making it easier to identify with precision.

2009 December, 5.1.1168:  In addition to the existing OPCODE 8 (read) special COUNT values of 0 (read to LF) and -1 (read to CR), you may now specify any character value for the terminating character to read to, by putting its negative ASCII value (-2 thru -257) in COUNT. For example,

COUNT = -3  ! read to ETX or chr(3)

xcall COMIO, 4, CH, BUF, STATUS, COUNT

Since -1 is interpreted as chr(10) (LF), to specify chr(1) (SOH) as the terminating character, set COUNT = -257.

To read up until an explicit null byte, set COUNT = -256. Note that this requires that we receive a explicit null byte in the input buffer, not to be confused with the implicit null byte used to terminate the buffer.

Consistent with previous operation, the terminating byte is discarded, although it is included in the returned COUNT (indicating the number of characters received). And in the case of COUNT = 0 (wait for LF), if the character preceding the LF is CR, the CR is also discarded. (The previous documentation described this option as waiting for CRLF, but in reality, it has always terminated on LF, with the preceding CR being optional.)

2006 April, A-Shell 4.9.955:  Add support for the msg and timeout parameters, as well as the logging function and support for ports greater than COM9.