This subroutine has been superseded by TCPX; it is supported and documented for historical reasons only. Unless you are running an ancient (and no longer supported) version of A-Shell, you should be using TCPX.
xcall TCPCLI, code, status, buffer, sockport, hostname {,flags}
TCPCLI.SBR provides a way for a client process to communicate with a server process over TCP/IP sockets. It is specifically designed to interface easily with another A-Shell server process which is running TCPSRV, but it is flexible enough to be used with a wide variety of server processes.
Parameters
code (Num) [in]
Specifies operation, from choices below:
|
Value |
Description |
|
1 |
Connect to TCPSRV server (same as 9 but waits for a response) |
|
2 |
Write contents of BUFFER to socket. |
|
4 |
Read data from socket into BUFFER |
|
6 |
Close socket |
|
7 |
Check if socket has data to be read (returns STATUS=1 if so) |
|
8 |
(UNIX only) Same as 7 but returns STATUS= number of bytes available to read |
|
9 |
Connect to server; same as 1 but does not wait for a response (works for any server, including TCPSRV) |
status
Return status. <0 for errors (-errno), >0 indicates number of characters written or read.
Read/write buffer (maximum 4096 bytes)
sockport (F,6)
For connect, caller must supply port number to connect to. On return, this will contain the connected socket number, which must then be passed to all the other calls for this session. If the connect operation returns <0, this indicates an error (with the number indicating which of the several internal steps failed).
hostname
On connect, must contain the host name or IP address of the server.
flags (F,6) optional
On the connect calls (1 & 9), set to 1 for a blocking connection, or 0 for a non-blocking connection. (Default is blocking.) On the check operation, set to number of seconds to wait before returning if no bytes are available. (Fractional seconds are ok; default is 0 if parameter not specified.) On the read call specifies (if non-zero) the maximum number of bytes to read (default is the size of BUFFER). On the write call, specifies (if non-zero) the number of bytes to write.
Comments
Sockets are not automatically closed when a BASIC program terminates, so it is important that you add a socket close command to your error trap. Otherwise you may not be able to reconnect to the socket.
You can translate the system error codes returned as negative numbers in the STATUS parameter by using XCALL MIAMEX, MX_ERRNOMSG, ABS (STATUS), MESSAGE$
The client connect calls will fail if the server is not already waiting for a connection. (In contrast, the server side the corresponding "accept connection" (Code 1) call using TCPSRV, will wait indefinitely for a client to make a connection.)
The number of bytes to read or write (as specified by FLAGS) will be trimmed to the smaller of the size of BUFFER and 4096 bytes. The one exception is that if the BUFFER variable is subscripted, then FLAGS may be as large as 4096. (This overcomes the obstacle when using an array caused by the fact that the subroutine calling mechanism reports the size of just one element, rather than the size of the entire array.)
Opcode 9 is recommended in place of Opcode 1, even when you know the server is running TCPSRV. The only difference is that Opcode 1 does an automatic read after connecting. It is more standard and flexible to issue a separate read to retrieve the server’s ACK message (if any).