New (UdpSocket constructor)

Create a UdpSocket object (UdpSocket class)

[Introduced in Sirius Mods 8.0]

New creates an instance of a UdpSocket object. This object can be used to exchange messages with a remote host using a Janus client socket (CLSOCKU) port.

Syntax

%udpSocket = [%(UdpSocket):]New[( [ClientPort= string], [LocalHost= string], - [LocalPort= number], [Host= string], - [Port= number])]

Syntax terms

%outUdpSocket	A UdpSocket object.
[%(UdpSocket):]	The optional class name in parentheses denotes a Constructor. See "Usage notes", below, for more information about invoking a Constructor.
ClientPort	The name of the client UDP socket (CLSOCKU) port. The default is the MASTER CLSOCKU port, if any is defined. However, if you omit clientport and no MASTER CLSOCKU port is defined, the request is canceled.
LocalHost	The IP address to use for messages sent on the client socket port. If not specified, the default or only IP address of the host on which Model 204 is running is used. This parameter is an alternative to the BINDADDR JANUS DEFINE parameter. If BINDADDR is specified on the CLSOCKU port used for the UdpSocket: The LocalHost parameter is unnecessary. If LocalHost value is specified, it must match the IP address specified on the BINDADDR. If LocalHost or BINDADDR is specified for a UDP socket, only messages sent to that IP address will be received by the UdpSocket object.
LocalPort	The UDP port number to use for messages sent to and received from the new UdpSocket. If this parameter is not specified, the UDP stack will assign a port number (usually 1024 and higher) to the UdpSocket object. This parameter is most useful when writing a UDP server application that is handled by a single thread (since only one thread can issue a New for a particular UDP port number). Typically a server application will create a UdpSocket for a well-known UDP port number to which clients subsequently send requests. There are some protocols such as SNMP that sometimes send messages from a well-known port number to another server.
Host	The target host for messages sent from the UDP socket. This can be an IP address or a host name, the latter being resolved using the Janus Domain Name Services support. If Host is specified on the New method invocation, it cannot be changed later. If an application wants to use a UdpSocket to communicate with multiple hosts, it should not specify Host on the New method invocation.
Port	The target port number for messages sent from the UDP port. This must be a number between 1 and 65534. If Port is specified on the New method invocation, it cannot be changed later. If an application wants to use a UdpSocket to communicate with multiple port numbers, it should not specify Port on the New method invocation.

Usage notes

• While the New method doesn't attempt to communicate with a target host, it can fail with a request canceling error if no CLSOCKU port is available or if the maximum number of connections for a port is exceeded.
• While a UDP socket doesn't actually have a connection with anything, a New method uses a logical connection for the port until the UdpSocket object is discarded. This logical connection is counted against the port's maximum connection limit.
• As described in "Using New or other Constructors", New can be invoked with no object, with an explicit class name, or with an object variable in the class, even if that object is Null:

  %udpSock = new %udpSock= %(UdpSocket):new %udpSock= %udpSock:new

Examples

1. The following code is a sample server that simply echoes any message sent to it:

   b %message is longstring %udpSock is object udpSocket %udpSock=new(localPort=1234) %udpSock:timeout = 0 repeat forever %message = %udpSock:receive %udpSock:send(%message) end repeat end

2. The following request sends a message to the server above, and it waits up to one second for a matching response:

   b %time is string len 32 %message is longstring %udpSock is object udpSocket %udpSock=new(host='198.242.244.47', port=1234) %time = %(system):currentTimeString('YYYYMMDDHHMISSXXX') %udpSock:send(%time) %udpSock:timeout = 1 repeat forever %message = %udpSock:receive if %message eq %time then printText Ping successful! loop end end if if %message eq '' then printText No response received for ping loop end end if end repeat end

See also

UdpSocket class	List of UdpSocket methods	UdpSocket methods syntax
Notation conventions for methods