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 port field if you have an old application that is having trouble using a DatagramSocket. The fields in a DatagramSocket are:

alive	An int that is 1 if the datagramsocket has been activated and 0 otherwise. Storing 1 in alive activates the datagramsocket, which automatically tries to bind it to localaddress and localport and then connect it to remoteaddress and remoteport. Calling the send or receive built-ins also activate the datagramsocket. Storing 0 in alive closes the datagramsocket, which means it is no longer bound to a local address or connected to a remote system.
broadcast	An int that is 1 if the datagramsocket can send broadcast datagrams and 0 if it can not. Storing a negative number in broadcast is ignored and makes no changes to the current setting.
localaddress	A String that identifies network interfaces on the local machine that the datagramsocket 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 wildcard address that usually matches any local address. A datagramsocket that is bound to localaddress and localport will only receive packets directed to that address and port. Reading localaddress when the datagramsocket is alive always returns an IP address. Changing localaddress while a datagramsocket 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 datagramsocket is alive and NULL when it is not alive.
localport	An int that identifies the port that the datagramsocket 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. A datagramsocket that is bound to localaddress and localport will only receive packets directed to that address and port. Changing localport while a datagramsocket is alive is not allowed and will result in an invalidaccess error.
port	An obsolete field that was replaced by localport in the 1.4.0 release of the Yoix interpreter.
receive(String buf [, Pointer addr, Pointer port])	A Builtin that waits for a datagram packet to arrive at this datagramsocket's localaddress and localport, stores the packet data in buf, and returns the number of bytes received or -1 if receive timed out, was interrupted, or encountered any other kind of error. receive automatically activates the datagramsocket if it is not alive. The string buffer buf must be large enough to accommodate the data in any expected packet; bytes that don't fit will be lost. Information about where the data came from can stored in the locations that the optional addr and port arguments point to. addr should point to a string that will be filled in with the IP address of the host that sent the data. port should point to an integer that will be filled in with a port that can be used to contact the host that sent the data. A datagramsocket that is connected to remoteaddress and remoteport can only receive packets from that address and port, which means the optional addr and port arguments will not provide any additional information.
receivebuffersize	An int that is the size, in bytes, of the buffer used by the datagramsocket to receive packets. Reading returns the actual buffer size if the datagramsocket is alive, or the size that will be requested from the operating system when it is activated. Writing requests a buffer 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.
remoteaddress	A String that identifies a remote system that the datagramsocket should be connected to when it is alive. The value should be an IP address, a name that can be resolved by DNS, or NULL (the default) which means the datagramsocket is not connected. A datagramsocket that is alive and connected to remoteaddress and remoteport can only send packets to or receive packets from that address and port. A datagramsocket that is alive and has a NULL remoteaddress or a remoteport that is -1 is not connected to a remote system. Reading remoteaddress when the datagramsocket is alive always returns the IP address or NULL. Writing first disconnects the datagramsocket and then tries to establish a new connection when remoteaddress is not NULL and remoteport is integer between 0 and 65535, inclusive.
remotename	A read-only String that is the name of the host associated with the IP address read from remoteaddress or NULL when the datagramsocket is not alive or not connected to a remote system.
remoteport	An int that identifies the port on remoteaddress that the datagramsocket should be connected to when it is alive. A datagramsocket that is alive and connected to remoteaddress and remoteport can only send packets to or receive packets from that address and port. A datagramsocket that is alive and has a NULL remoteaddress or a remoteport that is -1 is not connected to a remote system. Writing first disconnects the datagramsocket and then tries to establish a new connection when remoteport is integer between 0 and 65535, inclusive and remoteaddress is not NULL.
reuseaddress	An int that is 1 if more than one datagramsocket can be bound to the same localaddress and localport pair and 0 otherwise. Storing a negative number in reuseaddress is ignored and makes no changes to the current setting.
send(String buf [, String addr, int port])	A Builtin that uses this datagramsocket to send the contents of buf to a remote system and returns the number of bytes sent or -1 if there was an error. Nothing is sent and 0 is returned if buf is NULL or the empty string (i.e., ""). send automatically activates the datagramsocket if it is not alive. A datagramsocket that is connected to remoteaddress and remoteport can only send packets to that address and port, which means the optional addr and port arguments should be omitted. A datagramsocket that is not connected to a remote system must be told where buf should go using the addr and port arguments. addr should be an IP address, a name that can be resolved by DNS, or NULL which is a convenient way to refer to the local host. port should be an integer between 0 to 65535, inclusive.
sendbuffersize	An int that is the size, in bytes, of the network buffers used by the datagramsocket to send packets. Reading returns the actual size if the datagramsocket 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.
timeout	A double that specifies how long the receive built-in will wait, in seconds, before giving up. A zero value disables timeouts and means receive will wait forever. Writing is allowed, but does not affect a receive call 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 datagrams that are sent from the datagramsocket. 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 DatagramSocket 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 datagramsocket is activated for fields that you choose not to initialize.

Example:	The following program is a clumsy little chat script that happens to be a decent DatagramSocket example. Put import yoix.*.*; DatagramSocket socket; String buf[1024]; String text; final String HELLO = "ready to chat\n"; final String GOODBYE = "goodbye\n"; if (argc == 2) { socket.localport = atoi(argv[1]); socket.receive(buf, &socket.remoteaddress, &socket.remoteport); printf("%s> %s", socket.remotename, buf); socket.send(HELLO); } else if (argc == 3) { socket.remoteaddress = getHostAddress(argv[1]); socket.remoteport = atoi(argv[2]); socket.send(HELLO); } else fprintf(stderr, "usage error\n"); Thread receiver_thread = { run() { while (socket.receive(buf)) { printf("%s> %s", socket.remotename, buf); if (buf === GOODBYE) break; } exit(0); } }; receiver_thread.run(); do { if ((text = stdin.nextline) == NULL) text = GOODBYE; else text += "\n"; socket.send(text); } while (text !== GOODBYE); exit(0); in a file named datachat.yx and type something like yoix datachat.yx 8888 in one window and yoix datachat.yx 127.0.0.1 8888 in another and you should be able to chat with yourself. See the documentation of Socket if you are looking for another chat example.
See Also:	getAddress, getAllByName, getHostAddress, getHostName, getInterfaceAddress, getInterfaceAddresses, isAnyLocalAddress, isLinkLocalAddress, isLoopbackAddress, isMulticastAddress, isSiteLocalAddress, MulticastSocket, ServerSocket, Socket