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 TCPSRV, code, status, buffer, sockport {,flags}
TCPSRV provides a way to create server processes that support client requests via a socket interface. Similar to TCPCLI, and in fact designed specifically to integrate easily with it, TCPSRV is nevertheless flexible enough that it can be used to communicate with a wide variety of client processes over TCP/IP sockets. For example, you could use it to create a server that responded to web queries submitted from a CGI process.
Parameters
code (Num) [in]
Specifies operation, from choices below:
Value |
Description |
|---|---|
1 |
Create listening socket on port specified by SOCKPORT, and wait for a client to connect. If BUFFER parameter is non-null, then after the connection is accepted, the first 32 bytes of the BUFFERDATA parameter will be sent to the client as an acknowledgment message. On successful return, SOCKPORT is set to the connected socket, which must be specified to all the other calls for this socket. |
2 |
Write contents of BUFFER to socket. |
4 |
Read data from socket into BUFFER |
5 |
|
6 |
Close socket |
7 |
Check if socket has data to be read (returns FLAGS=1 if so) |
8 |
(Unix only) Like CODE 7 except returns the number of bytes available to read. |
status (F,6)
Return status. <0 for errors (-errno), >0 indicates number of characters written or read.
Read/write buffer (maximum 4096 bytes)
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).
flags (F,6) optional
On the connect operation, may contain 1 for a blocking connection, or 0 for a non-blocking connection. (Default is blocking.) On the check operation, contains the number of seconds to wait before returning if no characters are available. (Fractional seconds are ok; default is 0 if parameter not specified.) For the write operation, it specifies the number of characters to write. (Default is size of the BUFFER parameter if FLAGS not specified.) For the read operation, if non-zero, specifies the maximum number of bytes to read.
Comments
Note that only one server process can wait for connections on a particular port number for a single machine. So it is important that the server do its job and close the socket quickly if there is a possibility of multiple clients making frequent requests. Typically, this kind of single-threaded server works best for quick and simple lookup operations, such as price lookups or inventory status checks.
See the sample program TCPTST.BP in EXLIB:[908,25] for a working example.
