xcall TCPX, opcode, status, buffer, sockport, flags {,timer, hostname}
xcall TCPX, opcode, status, buffer, sockidx, flags, timer, hostname, sockary(1)
TCPX provides an interface for applications to communicate with other processes via TCP sockets. It supports both client and server operations, and is theoretically compatible with just about any TCP socket-based client or service, whether implemented via A-Shell on the local machine, or some entirely different language and operating system on a remote machine across the Internet.
For managing an array of sockets with the sockary() parameter and the second syntax shown above, refer to the subtopic of that name below.
Parameters
opcode (Num) [in]
indicates operation, per the TCPX Opcodes table.
status (F,6) [in/out]
Returns status of operation. <0 = -errno. >0 indicates number of bytes read or written. For other operations, 0 generally indicates success. See the Status table, which shows details by opcode.
buffer (String, Raw, or array) [in/out]
Packet of data to read or write. Note that there is no hard coded limit on the packet size; however the OS may impose its own limits. 8K should work nicely in all environments. Warning: buffer takes on special meaning with TCPOP_ACCEPT (non-TLS) and TCPOP_CONNECT (with TCPXFLG_TLS). In the TCPOP_ACCEPT case, if buffer is not "", then the first 32 bytes will be transmitted to the client automatically upon accepting the connection. This may be a convenience in some cases, but can cause all kinds of problems if the client is not expecting it. For the TCPOP_CONNECT case (with TCPXFLG_TLS set in the flags parameter), if not "", it is interpreted as a list of algorithm/authentication/security priorities to override the default. See the topic TLS/SSL for more details.
Also note that the TCPOP_ACCEPT call will send the first 32 bytes of buffer (if not empty), unsolicited to the client. This can cause all kinds of confusion if the client is not expecting it, so in general you'll want to make sure that buffer = """ prior to accepting a connection.
sockport (Num) [in/out]
On connect or accept (opcodes TCPOP_ACCEPT, TCPOP_CONNECT, TCPOP_CONNECT_OLD) must supply the port number to listen on or connect to; returns the connected socket number, which must be supplied to all other calls (except opcode TCPOP_ERRMSG). See Advanced Server Connection Options for special case involving TCPXFLG_LISTEN. Also note that for some kinds of errors, TCPX may automatically close the socket, in which case it will return sockport set to -1, eliminating the need for your application to explicitly close it.
flags (Num) [in]
Usage varies with opcode as noted in the tables TCPX Flags1 and TCPX Flags2.
timer (Num) [in] optional
Number of milliseconds to wait before returning if operation cannot be completed. The value returned in status after a time out depends on the opcode. For opcode TCPOP_CHECK, status will return 0 on time out. For opcode TCPOP_WRITE and TCPOP_READ, status will return the number of bytes transferred before the timer expired. Under Windows only, timer also affects opcode TCPOP_ACCEPT (server wait for connection), causing it to return with status set to a negative value if no connection was accepted before the timer expired. Under Unix, timer has no affect on opcode TCPOP_ACCEPT, which will wait until either a connection is accepted or the process is aborted by an external event.
The timer parameter works to set a limit on the amount of time waiting in the TCPOP_CONNECT operation. Although in theory, the TCPOP_CONNECT operation should succeed or fail without delay, in practice, DNS delays and some firewalls can cause the operation to hang for several seconds, particularly on failed attempts. In earlier versions of A-Shell, the timer parameter had no effect on that. Starting in build 996.3 of 15 Oct 2007, if the connection cannot be established within the specified time limit, the attempt is aborted.
hostname (String) [in]
For TCPOP_CONNECT, must specify the host name or IPV4 address (###.###.###.###) of the host server to connect to. If specifying a name, do not include any protocol prefixes; just include the DNS name (e.g. myservice.mydomain.com, www.yourdomain.net, etc.). For TCPOP_ACCEPT, if specified, it will return the hostname or IP of the client. Ignored for all other opcodes.
Note that as a convenience for backwards compatibility with TCPCLI/TCPSRV, hostname can be the fifth parameter (if six parameters are specified and the sixth is numeric), or the last parameter (if five, six, or seven parameters are specified).
See Also
| • | Socket Programming for a more detailed discussion of sockets in general. |
| • | Sample programs TCPxxx in EXLIB:[908,25]. |
| • | Subtopics listed below. |
| • | On the A-Shell forum, search for "TCPX" and see the thread "AIX / TCPX issue: async connects." |
Warnings and Notes
| • | If you get tired of waiting for an asynchronous connection to complete, you can cancel the connection attempt by using TCPOP_CLOSE, just like you would for an established connection. |
| • | The interpretation of the STATUS value returned from TCPOP_CONNECT depends on whether it is a normal or asynchronous (TCPXFLG_ASYNC) connection request. In the normal case, STATUS>=0 indicates success. In the asynchronous case, STATUS=0 means the connection is still pending, while STATUS=1 means success. If still pending, you need to use TCPOP_CHECK to determine the outcome. It will return STATUS=0 for still pending, STATUS=1 for success, or STATUS<0 for connection failed. |
| • | If TCPOP_CONNECT (with the TCPXFLG_ASYNC flag) returns with STATUS=1 and SOCKPORT > 0, then the socket SOCKPORT is open (or "half open"), even though the connection is still pending. So you would be responsible for closing it if you don't follow through with the TCPOP_CHECK procedure to check for the result. On the other hand, if you get STATUS<0 on the TCPOP_CHECK (with TCPXFLG_ASYNC) operation, the socket will be automatically closed. |
| • | If an asynchronous connection attempt returns the pending status, the socket will be in non-blocking mode, regardless of whether you initially specified the TCPXFLG_BLOCK flag. To get it back into blocking mode once the connection is established, you need to specify TCPXFLG_BLOCK along with TCPXFLG_ASYNC on the TCPOP_CHECK call(s). |
History
2017 April, A-Shell 6.5.1618: Add sockary parameter, which see below.
Subtopics
•Advanced Server Connection Options
