DEVICE: How To: Socket Device Communication [25288]

This article applies to:

E-Prime 3.0

E-Prime 2.0

E-Prime 1.x

Detail

What Device am I Using?
A Socket is a physical interface on a computer that can send information from one object to another. A socket can send and receive packets of information. A Socket device can be thought of as a connection to an Ethernet card or WiFi.

Specific Information about This Device
Some information needs to be known to communicate through a Socket in E-Prime. The IP Address, Port Number, Connection Type, and Byte Ordering is needed. All this information reflects required fields for a Socket Device in E-Prime. To find this information, know where the Socket is connected to, the connection type, and byte ordering. Additionally, ensure that a valid connection exists and you can Ping both directions of the Socket in Command Prompt before testing in E-Prime.

When using Socket communication, it is important to know the difference between the two types of Internet Protocol (IP) traffic.

The first is UDP transmissions (User Datagram Protocol or Universal Datagram Protocol). UDP does not guarantee the delivery of packets, and if a packet is delivered, the delivery is not guaranteed to be in the correct order. UDP is faster than TCP but does not guarantee that intended data will actually be sent. TCP is slower but guarantees that data is received. UDP is "connectionless". If using UDP, be prepared to handle missing datagram, duplicate datagram, or datagram in the incorrect order. Error detection and correction must also be handled.

The second is TCP transmissions (Transmission Control Protocol). With TCP, if a packet is dropped, but the next packet makes it through, the kernel will withhold that packet until the earlier packet can be re-sent. This is because TCP is a guaranteed, in-order, streamed protocol. This means that "fresh" data sits in the kernel while waiting for the TCP timeout and re-transmission. This takes a minimum of 3 seconds for a lost packet. Due to this limitation, UDP is usually better for real-time low-latency applications.

Adding a Socket Device in E-Prime

To utilize a Socket Device in E-Prime, it needs to be added to an E-Prime experiment. To add a Socket Device follow these steps:

Open the Experiment Object at the top of E-Studio’s Structure window.
Click on the Devices tab.
Click the “Add…” button at the bottom of the window.
Click on the Socket Device and click the OK button to add the device.

Once a Socket Device is added to an experiment, the properties of the device will need edited with the information specified in the previous section (i.e., IP Address, Port Number, Connection Type, and Byte). To do this, select the Socket Device and click on the “Edit…” button at the bottom of the Devices tab. The Socket Device will be ready to send/receive signals once the properties are configured.

NOTE: This device does not exist in E-Prime 1.x. Please see DEVICE: Ability to use network sockets (SocketDevice) in E-Basic runtime/script [17851].

How to send a signal using a Socket Device
There are several ways to send signals to a Socket. Before beginning to write script or adding devices in an experiment to send signals, it is important to determine what type of signals are to be sent. First, take into consideration what device you are communicating with. There are several ways to send information to a Socket. The following chart shows all of the possibilities of signals along with a brief description.

Method	Description
WriteBytes	Writes an array of bytes to the Socket device.
WriteByte	Writes a byte to the Socket device.
WriteInteger	Writes integer data to the Socket device.
WriteLong	Writes Long data to the Socket device.
WriteString	Writes String data to the Socket device.

Not only can Socket information be sent through standard means of scripting, but it can also be sent through a Task Event of an object (E-STUDIO: Using Task Events [22862]). To do this, an Event must be added to an E-Object. Then, a Socket Task needs to be added with an Action (e.g., WritieLong). Lastly, Task Event's parameters need to be specified.

WriteBytes
The most important thing to keep in mind about using the WriteBytes command is that it sends an array of integers across the Socket device. Unlike the WriteInteger and WriteLong methods that only sends one Integer or Long of information at a time, this method sends multiple instances of Integer data at a time.

Syntax
SocketDevice.WriteBytes arrData, nCount

arrData – This parameter is the array of integers to be sent to the Socket Device.
nCount – This parameter is optional and represents the number of elements from the array that should be sent to the Socket. If this parameter is excluded, E-Prime sends the entire array’s worth of data to the Socket device.

Example

Dim arrData(2) As Integer

arrData(0) = 1
arrData(1) = 2
arrData(2) = 3

Socket.WriteBytes arrData, 1

In this example script, an array named arrData is declared. Since array definition begins at 0, this array has three seats to it. The script below the delcaration defines the integer values at each seat of the array. In this case, the array information that is sent to the Socket device is 1, 2 and 3. The final part of the sample demonstrates the proper syntax of using the WriteBytes command on a Socket Device (named Socket) to send only the first two seats of the array to the Socket. In this instance, only the 1 and 2 is sent the Socket.

WriteByte
This command writes only one Byte worth of information across the Socket.

Syntax
SocketDevice.WriteByte nData

nData – This parameter is the integer that is going to be written to the computer’s Socket. This information can be a variable (as demonstrated), attribute, or integer.

Example

Socket.WriteByte 255

This sample demonstrates how to send a signal of 255 to a Socket device named Socket. In this sample the nData parameter is an Integer data type. Only a single byte is sent. It is also possible to use a variable or use the “c.GetAttrib” statement to write an attribute to the Socket.

WriteInteger
This command writes only one Integer’s worth of information across the Socket. This integer is two bytes worth of data.

Syntax
SocketDevice.WriteInteger nData

nData – This parameter is the integer that is going to be written to the computer’s Socket. This information can be a variable (as demonstrated), attribute, or integer.

Example

Socket.WriteInteger 255

This example demonstrates how to send a signal of 255 to a Socket device named Socket. In this example, the nData parameter is an Integer, but it is also possible to use a variable or use the “c.GetAttrib” statement to write an attribute to the Socket.

WriteLong
Writes a Long’s worth of data to the Socket. Long data represents four bytes worth of data.

Syntax
SocketDevice.WriteLong nData

nData – This parameter is the integer that is going to be written to the computer’s Socket. This information can be a variable (as demonstrated), attribute, or integer.

Example

Socket.WriteLong 854775807

This example demonstrates how to send a signal of 854,775,807 to a Socket device named Socket. In this example, the nData parameter is a Long, but it is also possible to use a variable or use the “c.GetAttrib” statement to write an attribute to the Socket.

WriteString
Unique to the Socket, you are actually able to write strings worth of information to an external device using E-Prime.

Syntax
SocketDevice.WriteString StrData, nCount

StrData – This parameter is the string data that is sent across the Socket. This required parameter needs to be contained within quotation marks. This is how E-Prime determines that the signal is String data.
nCount - This parameter is optional and determines how many characters of the String will be sent to the Socket.

Example

Socket.WriteString "Send DoNotSend", 4

In this example, String data is sent to a Socket Device named Socket. This example contains the nCount parameter. In this case, only the first 4 characters of this String is sent across the Socket. This way, the signal appears as “Send” instead of the full “Send DoNotSend” string.

How to receive a signal using a Socket Device
A powerful feature of E-Prime is its ability to not only send signals to external devices but to receive signals as well. Just like sending signals to an external device, it is important to keep in mind what signals are to be received from this external device. This is especially important when receiving signals from an external device because E-Prime should know exactly what signal it is supposed to be listening for. The following chart shows all of the possibilities of signals along with a brief description of these.

Method	Description
ReadBytes	Reads Integer data from the Socket device and inputs it directly into an array
ReadByte	Reads one byte from the Socket device.
ReadInteger	Reads Integer data from the Socket device
ReadLong	Reads Long data from the Socket device
ReadString	Reads String data from the Socket device

ReadBytes
This method reads integer data from the Socket’s input cue and loads it into an array. Each element of this array represents one byte worth of data that is going to be read into the experiment. If the requested amount of bytes is more than what is available, only elements in the array available are filled with data.

Syntax

nRead = SocketDevice.ReadBytes (arrData, nCount)

nRead – is the value returned from the WriteBytes method that represents the actual number of bytes that have been read into the array.
arrData – an array of integers that represents the array to which the data that has been read from the Socket’s input cue will be written.
nCount - an optional parameter that specifies how many bytes to store into the array. If this optional parameter is omitted, the entire array size is required.

Example

Dim nRead As Integer
Dim arrData(3) As Integer

nRead = Socket.ReadBytes(arrData, 2)

This example first defines two important variables called “nRead” and “arrData”. The “nRead” variable holds the number of bytes that are written to the Socket and the “arrData” variable is an array that holds the values that are sent into the Socket. The remainder of this example demonstrates how to use each of these parameters to read Bytes of data that are sent to the Socket. This example only reads instances 0, 1 and 2 that come into the Socket because of the “nCount” parameter at the end of the statement.

ReadByte
This method reads only one integer from the Socket’s input queue into a variable in the experiment. If the integer that comes into the Socket device is less than the required two bytes then only one byte is received.

Syntax
nRead = SocketDevice.ReadInteger( nData)

nRead – returns an integer representing the actual number of bytes that have been read from the Socket’s input queue.
nData – returns the integer that has been written to the Socket’s input queue.

Example

Dim nData As Integer
Dim nRead As Long

nRead = Socket.ReadInteger(nData)

This example defines two variables. The first variable is “nData”. This variable represents the Integer data that the external device is sending to E-Prime. The “nRead” variable holds the number of bytes of the signal that has been sent through the Socket. The remainder of the example demonstrates how to use these variables to read the Integer information that is sent through the Socket.

ReadInteger
This method reads only one integer from the Socket’s input queue into a variable in the experiment. If the integer that comes into the Socket device is less than the required two bytes, only one byte is received.

Syntax
nRead = SocketDevice.ReadInteger( nData)

nRead – returns an integer representing the actual number of bytes that have been read from the Socket’s input queue.
nData – returns the integer that has been written to the Socket’s input queue.

Example

Dim nData As Integer
Dim nRead As Long

nRead = Socket.ReadInteger(nData)

First, two variables are declared. The first variable is “nData”. This variable represents the Integer data that the external device is sending to E-Prime. The “nRead” variable holds the number of bytes of the signal that has been sent through the Socket. The remainder of the example demonstrates how to use these variables to read the Integer information that is sent through the Socket.

ReadLong
This method reads a Long’s worth of data from the Socket’s input queue into a variable in the experiment. If the Long that comes into the Socket device is less than the required four bytes, all available data is retrieved.

Syntax
nRead = SocketDevice.ReadLong(nData)

nRead – returns an integer representing the actual number of bytes that have been read from the Socket’s input queue.
nData – returns the Long that has been written to the Socket’s input queue

Example

Dim nData As Long
Dim nRead As Integer

nRead = Socket.ReadLong(nData)

First, two variables are declared. The first variable is “nData”. This variable represents the Long data that the external device is sending to E-Prime. The “nRead” variable holds the number of bytes of the signal that has been sent through the Socket. The remainder of the sample demonstrates how to use these variables to read the Long information that is sent through the Socket.

ReadString
The ReadString method reads a string of bytes from the Socket device’s input queue. Each character in the string that is sent over represents a byte read from the Socket device’s input queue. Along with this method, there is also the opportunity to use the Mid and Asc functions to return an integer representation for the data read from the Socket device’s input queue.

Syntax
nRead = SocketDevice.ReadString( strData, nCount)

nRead – returns an integer representing the actual number of bytes that have been read from the Socket’s input queue.
strData – is an array of integers representing the array to whch the data read is stored.
nCount – an optional integer specifying how many bites to retrieve. If omitted, then 1K (1024 bytes) is requested

Example

Dim strData(5) As String
Dim nRead As Integer

nRead = Socket.ReadString(strData)

The first variable in the example is “strData”. This variable is an array that holds the String data sent from the Socket. In this case, it holds 5 bytes of data. The “nRead” variable holds the number of bytes of the signal that has been sent through the Socket. The remainder of the example demonstrates how to use these variables to read the String information that is sent through the Socket. Please notice that the nCount parameter has been omitted from this example. This means that E-Prime requests roughly 1024 bytes from the Socket’s input queue.

BUG FIX: UDP Sockets cannot receive data [25865]
E-STUDIO: Using Task Events [22862]

For further information on scripting using E-Basic, please refer to the E-Prime Command Reference (https://pstnet.com/ecr).

Articles in this section

Comments

Articles in this section

Related articles