The Yoix^® Scripting Language

Several incompatible changes introduced in release 1.4.0 of the Yoix interpreter will affect older applications that used the DatagramSocket, ServerSocket, or Socket types. Take a look at the description of the obsolete address, fullname, name, and port fields if you have an old application that is having trouble using a Socket. The fields in a Socket are:

address	An obsolete field that was replaced by remoteaddress in the 1.4.0 release of the Yoix interpreter.
alive	An int that is 1 if the socket has been activated and 0 otherwise. Storing 1 in alive activates the socket, which automatically tries to bind it to localaddress and localport and connect it to remoteaddress and remoteport. Calling the sendUrgentData built-in also activates the socket. A socket that is alive has output and input streams that can be used to send and receive data. Storing 0 in alive closes the socket, which means it is no longer bound to a local address or connected to a remote system.
fullname	An obsolete field that was removed in the 1.4.0 release of the Yoix interpreter. The same information is available in the remoteaddress, remoteport, localaddress, and localport which can easily be combined into a string that describes the socket.
keepalive	An int that is 1 if keep-alive packets are supposed to be transmitted if no data or acknowledgement packets have been received by the socket for an interval (typically 2 hours or more) and 0 otherwise. Storing a negative number in keepalive is ignored and makes no changes to the current setting.
input	A read-only Stream that will be a File that can be used to read data sent from remoteaddress and remoteport if the socket is alive and ready to be used and NULL if it is not.
inputshutdown	An int that is 0 when the input stream can be used (i.e., it is not NULL and has not been explicitly disabled) 1 otherwise. Storing 1 in inputshutdown when the socket is alive means data that arrives will be acknowledged and silently discarded.
linger	A double that controls the behavior of a socket when it is closed, which happens automatically when alive is set to 0. Storing -1 (the default) in linger means no delay when the socket is closed, but all data waiting to be sent will be delivered. Storing 0 in linger means no delay when the socket is closed, but all data waiting to be sent will be discarded. Storing a value greater than zero in linger means delay that many seconds when the socket is closed, but unfortunately we are currently not certain what happens to unsent data (is it discarded or delivered) after the delay.
localaddress	A String that identifies network interfaces on the local machine that the socket will bind to when it is activated. The value should be the name of a network interface (e.g., eth0 or lo), an IP address, a host name that can be resolved by DNS, or NULL (the default), which means the loopback address. Reading localaddress when the socket is alive always returns an IP address. Changing localaddress while a socket is alive is not allowed and will result in an invalidaccess error.
localname	A read-only String that is the name of the host associated with the IP address read from localaddress when the socket is alive and NULL when it is not alive.
localport	An int that identifies the port that the socket will bind to when it is activated. The value should be an integer between 0 (the default) and 65535, inclusive. A localport that is 0 means the system should pick an ephemeral port. Changing localport while a socket is alive is not allowed and will result in an invalidaccess error.
name	An obsolete field that was removed in the 1.4.0 release of the Yoix interpreter. The same information is available in the remoteaddress and remoteport which can easily be combined into a string that describes the socket's remote peer.
oobinline	An int that is 1 if out-of-band data sent to the socket should be read in-line from input and 0 if the data should be discarded. Out-of-band data can be sent using sendUrgentData. Storing a negative number in oobinline is ignored and makes no changes to the current setting.
output	A read-only Stream that will be a File that can be used to send data to remoteaddress and remoteport if the socket is alive and ready to be used and NULL if it is not.
outputshutdown	An int that is 0 when the output stream can be used (i.e., it is not NULL and has not been explicitly disabled) 1 otherwise. Storing 1 in outputshutdown when the socket is alive means no more data can be written to output but data waiting to be sent will be delivered.
persistent	An int that is 0 (the default) if the socket should be explictly closed when the Yoix interpreter exits. Any other value means the socket will not be explicitly closed when the Yoix interpreter exits.
port	An obsolete field that was replaced by remoteport in the 1.4.0 release of the Yoix interpreter.
receivebuffersize	An int that is the size, in bytes, of the receive buffer used by the socket, which will also be the size of the TCP receive window that is advertised to the remote peer. Reading returns the actual buffer size if the socket is alive, or the size that will be requested from the operating system when it is activated. Writing requests buffers of a certain size, however the request may or may not be honored by the operating system. Storing a negative number in receivebuffersize is ignored and makes no changes to the current setting. Buffers larger than 64K bytes are allowed but must be requested before the socket is activated, otherwise the remote peer may not be able to take advantage of the extra space.
remoteaddress	A String that identifies the remote system that the socket should be connected to when it is activated. The value should be an IP address, a name that can be resolved by DNS, or NULL (the default) which means the socket is not connected to a remote system and can not be activated. A socket that is alive will have a remoteaddress that is not NULL, a remoteport that is an integer between 0 and 65535, inclusive, and can only send data to or receive data from that address and port. Reading remoteaddress when the socket is alive always returns the IP address. Changing remoteaddress while a socket is alive is not allowed and will result in an invalidaccess error.
remotename	A read-only String that is the name of the host associated with the IP address read from remoteaddress or NULL when the socket is not alive.
remoteport	An int that identifies the port on remoteaddress that the socket should be connected to when it is activated. A socket that is alive will have a remoteaddress that is not NULL, a remoteport that is an integer between 0 and 65535, inclusive and can only send data to or receive data from that address and port. Changing remoteport while a socket is alive is not allowed and will result in an invalidaccess error.
reuseaddress	An int that is 1 if another socket can be bound to the same localaddress and localport pair immediately after this socket is closed and 0 otherwise. Storing 0 in alive closes the socket, which puts it in a timeout state (officially called the TIME_WAIT state) that can last several minutes. During that time any attempt to reuse localaddress and localport by any process on your system will fail unless resueaddress was 1 when the socket was activated. Changing reuseaddress while the socket is alive is allowed, but the results are not well defined.
sendbuffersize	An int that is the size, in bytes, of the network buffers used by the socket to send packets. Reading returns the actual size if the socket is alive, or the size that will be requested from the operating system when it is activated. Writing requests buffers of a certain size, however the request may or may not be honored by the operating system. Storing a negative number in sendbuffersize is ignored and makes no changes to the current setting.
sendUrgentData(String data)	A Builtin that tries to send data out-of-band one byte at a time to the input stream that the remote peer is reading, and returns the number of bytes sent or -1 if there was an error before any bytes were sent. The individual bytes may or may not arrive together in the input stream and there is no guarantee the remote peer will accept out-of-band data, even if it looks like it was successfully sent. Keep urgent data short because there are not many guarantees about reliable delivery of out-of-band data.
tcpnodelay	An int which enables TCP_NODELAY, also known as Nagle's algorithm, when non-zero. A zero value disables it.
timeout	A double that specifies how long a read from the socket's input stream will wait, in seconds, before giving up. A read that times out returns a standard error indication (e.g., -1 or NULL) and increments the input stream's interrupted counter. A zero value disables timeouts and means a read from input will wait forever. Writing is allowed, but does not affect a read that has already started. Storing a negative number in timeout is ignored and makes no changes to the current setting.
trafficclass	An int that requests a type-of-service and precedence, using constants defined in yoix.net, for packets that are sent from the socket. The type-of-service should be one of IPTOS_LOWCOST, IPTOS_LOWDELAY, IPTOS_RELIABILITY, IPTOS_THROUGHPUT, or IPTOS_NORMAL (the default), while the precedence should be one of IPPREC_0 (the default), IPPREC_1, IPPREC_2, IPPREC_3, IPPREC_4, IPPREC_5, IPPREC_6, or IPPREC_7. The type-of-service and precedence can be combined using a bitwise-or operation and the result can be stored in trafficclass. Storing a negative number in trafficclass is ignored and makes no changes to the current setting. Two other constants defined in yoix.net, namely IPTOS_MASK and IPPREC_MASK, can be used to extract the type-of-service and precedence from the value obtained when the trafficclass field is read.

Several permanent fields have not been documented and should not be used in Yoix applications. If you look closely you may notice that many fields in a Socket are initialized with values, like -1, that the documentation says are explicitly ignored. It is an approach that lets Java (and your operating system) pick values when the socket is activated for fields that you choose not to initialize.

Example:	The program, import yoix.*.*; ServerSocket server; Socket socket; if (argc == 2) { // we are the server server.localport = atoi(argv[1]); stdout.nextline = "Waiting for connection on port " + argv[1]; socket = accept(server); } else if (argc == 3) { // set up the client socket.remoteaddress = argv[1]; socket.remoteport = atoi(argv[2]); socket.alive = TRUE; } else { // usage error fprintf(stderr, "ERROR: USAGE: %s [host] port\n", argv[0]); exit(1); } stdout.nextline = "Connected To: " + socket.remotename; Thread outputthread = { run() { while (line = socket.input.nextline) stdout.nextline = "<== " + line; stdout.nextline = "Connection closed."; exit(0); } }; outputthread.alive = TRUE; while (text = stdin.nextline) socket.output.nextline = text; outputthread.alive = FALSE; sets up a two-way chat from a terminal. The same script can act as a chat server or a chat client. It demonstrates a Socket being spawned by a ServerSocket accepting a connection and also being created to make a client connection. A separate Thread is used to read the incoming text. The other side of this chat can be this same script or it can be a standard socket communication program such as telnet.
See Also:	DatagramSocket, File, fprintf, fscanf, getAddress, getAllByName, getHostAddress, getHostName, getInterfaceAddress, getInterfaceAddresses, isAnyLocalAddress, isLinkLocalAddress, isLoopbackAddress, isMulticastAddress, isSiteLocalAddress, MulticastSocket, read, ServerSocket, Stream, write