Please enable JavaScript to view this site.

A-Shell Reference

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

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".