# TCPX **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](num.md)) \[in\] indicates operation, per the [TCPX Opcodes](tcpxopcodes.md) 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](status(tcpx).md) table, which shows details by _opcode_. _buffer _([String](string.md), [Raw](blob.md), 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](tlsssl.md) 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 will want to make sure that _buffer_ = """ prior to accepting a connection. _sockport _([Num](num.md)) \[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](advancedserveroptions.md) 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](num.md)) \[in\] Usage varies with _opcode_ as noted in the tables [TCPX Flags1](tcpxflags1.md) and [TCPX Flags2](tcpxflags2.md). _timer _([Num](num.md)) \[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. _hostname _([String](string.md)) \[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](socketprogramming.md) for a more detailed discussion of sockets in general. • Sample programs TCPxxx in [EXLIB:\[908,25\]](https://bitbucket.org/microsabio/exlib/src/master/908025/). • Subtopics listed below. • On the A-Shell forum, search for "TCPX" and see the thread "[AIX / TCPX issue: async connects."](http://www.microsabio.net/bbs0719/ubbthreads.php?ubb=showflat&Number=10749) • [TLS/SSL](tlsssl.md) **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).+ • As a convenience for backwards compatibility with TCPCLI on the TCPOP\_CONNECT _opcode_, _flags_ can be the sixth parameter if the fifth parameter is a string— i.e. TCPX is called with the TCPCLI syntax: **xcall TCPX, opcode, status, buffer, sockport, hostname, flags** **History** 2017 April, A-Shell 6.5.1618: Add _sockary_ parameter, which see below. **Subtopics** - [Advanced Server Connection Options](advancedserveroptions.md) - [Asynchronous Client Connections](asynchronousclientcon.md) - [Closing](closing_tcpx.md) - [TCPX Opcodes](tcpxopcodes.md) - [TCPX Flags1](tcpxflags1.md) - [TCPX Flags2](tcpxflags2.md) - [Status (TCPX)](status(tcpx).md) - [TCPCLI](tcpcli_tcpx.md) - [TCPSRV](tcpsrv.md) - [Sockary](sockary.md)