xcall COMIO, opcode, channel, buffer, status, count {,msg, timeout}
COMIO is included with A-Shell/Windows to allow simple I/O on Windows serial ports, since you cannot open up a Windows serial port as a file, like you can on other platforms. COMIO supports ports beyond COM9, and logs read/write errors to ashlog.log. Also:
| • | Refer to the sample program COMIO in EXLIB:[908,54]. |
| • | For more sophisticated applications involving serial communications, Autolog from Soft Machines is recommended. |
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 |
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".
