855.1
TCP subroutines TCPSRV and TCPCLI have now been consolidated and enhanced in a single routine, TCPX.SBR. The old calling interfaces (XCALL TCPCLI..., and XCALL TCPSRV,...) are still supported but now deprecated. New syntax:
XCALL TCPX,OP,STATUS,DATA,SOCKPORT{,FLAGS{,TIMER{,HOSTNAME}}}
OP (numeric) Indications operation. Note changes: OP 1 now only applies to server; OP 8 works on all platforms; new OP 10 & 11.
Opcode |
Description |
|---|---|
1 |
(server) wait for client connection |
2 |
write DATA to socket |
4 |
read DATA from socket |
6 |
close socket |
7 |
check if data avail to read (return 1 in FLAGS if so) |
8 |
check how much data avail to read (return # bytes in FLAGS) |
9 |
(client) connect to generic server |
10 |
(client) (equivalent to old TCPCLI opcode 1; now deprecated) |
11 |
return system error message corresponding to STATUS |
STATUS (float): Returns status of operation. <0 = -errno. >0 indicates number of bytes read or written.
DATA (string, unformatted, or array): Packet of data to read or write. Note changes: there is no longer any hardcoded limit on the packet size; however the OS may impose its own limits.
SOCKPORT (numeric): On connect or accept (OPs 1,9,10) must supply the port # to listen on or connect to; returns the connected socket #, which must be supplied to all other calls (except OP 11).
FLAGS (numeric, optional): Usage varies with OP. Note changes on read and write operations: you may now specify number of bytes to read/write and a timeout value in TIMER to ensure whole logical packet read/writes in blocking connections, without risking being stuck for an inordinate amount of time if other end malfunctions.
OP 1,9,10 (connect/accept): set=1 for blocking mode.
OP 2 (write): specifies # of bytes to write. Must be <= size of DATA, unless DATA is subscripted, in which case we just trust the FLAGS value. 0 (or FLAGS not specified) means write entire DATA block. If FLAGS non-zero, we set the send buffer low water mark so that we don't attempt operation unless buffer has sufficient space. (This is one case where you might have a problem if you use a packet size larger than the OS supports.)
OP 4 (read): specifies # of bytes to read. 0 means read whatever is available (from 1 byte to size of DATA). For blocking connections, subroutine will wait until the required number of bytes is read (up to TIMER limit). For non-blocking connections, this size is only an upper limit; the routine will return as soon as the interface indicates there is data available (even if not the requested number of bytes.)
OP 6 (close): Initiate a "graceful" background shutdown. Call returns immediately; OS tries to gracefully close the connection. If other end is waiting on input (in OP 4), it will receive an error.
OP 7 (check for data): If TIMER specified, FLAGS is ignored and TIMER is used. If TIMER not specified, FLAGS specifies how long to wait before returning STATUS 0 if no data avail. If FLAGS is F,6 then it is interpreted as fractional seconds; otherwise it is interpreted as milliseconds.
OP 8 (check how much data): FLAGS not used.
OP 11 (get error message): FLAGS not used.
As a convenience for backwards compatibility with TCPCLI on the connect OP, FLAGS can be the 6th param if the 5th param is a string (i.e. TCPX is called with the TCPCLI syntax:
XCALL TCPX,OP,STATUS,DATA,SOCKPORT,HOSTNAME,FLAGS)
TIMER (numeric, optional)
For OP 7, number of milliseconds to wait before returning if no data avail. For reads and writes on blocking connections, number of milliseconds to wait before returning if full operation cannot be satisfied.
HOSTNAME (string):
Used only on the connect OP; supplies the name of the host where the server is running. As a convenience for backwards compatibility with TCPCLI/TCPSRV, it can be the 5th param (if 6 params specified and 6th is numeric), or the last param (with 5, 6, or 7 params specified).
