Write to Socket

This tool is set as legacy. It is still available to provide backward compatibility but it will no longer be maintained or updated in upcoming MERLIC versions.

Use this tool to write data to a (server) socket.

Set the socket for the writing in the parameter "URL" and establish the connection by setting the parameter "Connect" to 1. Since this tool establishes a client connection, a server needs to be available. With the button you can execute this tool in single steps. This offers you the possibility to write the data step by step.

If a "Socket Handle" is connected from a previous socket tool, all parameters will be adopted from the first socket tool only. Thus, if you want to adjust the parameter settings in the current tool, you have to make the adjustments in the first tool, else the parameter changes will be ignored.

Execution Behavior

The behavior of this tool regarding the execution differs from the default behavior. Usually a MERLIC tool is executed in the following cases:

The MERLIC Vision App is explicitly executed in continuous mode.
The MERLIC Vision App is explicitly executed in "Run Once" mode.
A MERLIC Vision App with the tool is opened in the MERLIC Creator.
A parameter value of the tool has been changed in the MERLIC Creator.

However, the tool Write to Socket is only executed in the following cases:

The MERLIC Vision App is explicitly executed in continuous mode.
The MERLIC Vision App is explicitly executed in "Run Once" mode.

This ensures that read and write operations are not applied when loading an MVApp or changing a parameter value of the tool. However, if the parameter Connect is set to 1, the tool still tries to establish a connection to the remote device.

Parameters

Basic Parameters

URL:

This parameter defines the URL of the socket to be written. A valid "URL" consists of the protocol to be used, the hostname of the computer to be connected, and the port number separated by a colon, e.g., "tcp://localhost:4000".

Connect:

This parameter defines if the connection to the socket is activated or deactivated. The parameter is set to 0 by default. This means that the connection to the socket is not active and therefore the connection is not established for writing. If you want to start writing the data to the socket, you have to set the parameter to 1 to open the connection for writing.

Since the tool is executed with every change of values, we recommend to set the parameter "Connect" to 0 until the tool has been completely configured.

Data:

This parameter contains the data that are written to the socket. It contains the string "MyString" by default. The data can be represented by an integer, real, or a string value. It is also possible to send the data as a tuple. If you want to write the result of a previous tool, you can connect the parameter to the respective result of the previous tool. Then, the connected data will be written to the socket.

To ensure that the data are sent correctly it is necessary to set the correct format in the parameter "Data Format".

Timeout:

This parameter defines the timeout for the writing. It is defined in seconds and set to 0.5 by default. You can change the "Timeout" at the corresponding connector.

Data Format:

This parameter defines how the data are converted for the writing. This is required because the data are sent as a binary packet. It is set to "z" by default. You can change its value at the corresponding connector. The "Data Format" can consist of one or more multiple qualifier characters each followed by an optional modifier and repeat count.

Integer values

Value	Description
c	1 byte = 8 bit, signed
C	1 byte = 8 bit, unsigned
s	2 bytes = 16 bit, signed
S	2 bytes = 16 bit, unsigned
i	4 bytes = 32 bit, signed
I	4 bytes = 32 bit, unsigned
q	8 bytes = 64 bit, signed (only available on 64 bit architectures)
Q	8 bytes = 64 bit, unsigned

Float values

Value	Description
f	Float, 4 bytes = 32 bit
d	Double, 8 bytes = 64 bit

String values

Value	Description
A	A string (default length 1024 bytes), padded with spaces.
z	A string with variable length, the length modifier specifies the maximum length (default length 1024 bytes).
Z	A string (default length 1024 bytes), padded with zeros and will be zero terminated when sending.

Special characters which do not require a value as Data Format

Value	Description
-	A zero byte is skipped.
_	A space byte is skipped.

Modifiers which can be used after one of the qualifiers above

Value	Description
n	Network byte order. This modifier converts the integer or float value when reading from network byte order (big endian) to host byte order. It can also be used as a first character in the format string.
N	This modifier converts the integer or float value when reading from intel byte order (little endian) to host byte order. It can also be used as a first character in the format string.

Value

Description

n

Network byte order. This modifier converts the integer or float value when reading from network byte order (big endian) to host byte order.

It can also be used as a first character in the format string.

N

This modifier converts the integer or float value when reading from intel byte order (little endian) to host byte order.

It can also be used as a first character in the format string.

Repeat count for preceding qualifier

Value	Description
n	In case of integers and real values, this counter defines how often the preceding qualifier is repeated, e.g., if n=5, then "c5" means "ccccc". You can use any integer value for n. In case of string values, n represents the size of the string, e.g., "A2" means a string with a size of 2 bytes. If you want to send a tuple containing two strings, you have to repeat the qualifier, e.g., "AA" or "zz". In the receiving socket it is sufficient to define the Data Format with a single qualifier, e.g., "z", to read the strings,

Value

Description

In case of integers and real values, this counter defines how often the preceding qualifier is repeated, e.g., if n=5, then "c5" means "ccccc".

You can use any integer value for n. In case of string values, n represents the size of the string, e.g., "A2" means a string with a size of 2 bytes.

If you want to send a tuple containing two strings, you have to repeat the qualifier, e.g., "AA" or "zz". In the receiving socket it is sufficient to define the Data Format with a single qualifier, e.g., "z", to read the strings,

Example combinations of parameter values for Data and Data Format

Data	Data Format	Description
string	z	The data 'string' is written as a string.
my_string	z9	The data 'my_string' with a size of 9 bytes is written.
['this'; 'is'; 'a'; 'string']	zzzz	The strings are concatenated and written as a single string 'thisisastring'.
[396.457; 402.589; 235.459]	d3	The tuple containing three double values is written. This corresponds to 'ddd'.
[2.54; 1.4; 3.28; 214748; -43897]	d3i2	The tuple containing three double values and two signed integer with 4 bytes will be written.
[1; 2; 'string']	i2z	The tuple containing two signed integers (4-byte) and a string is written. The receiving sockets reads the tuple [1, 2, 'string'].
[1; 2; 'string'; 'string2']	i2z	The tuple containing two signed integers (4-byte) and two strings is written. The receiving sockets reads the tuple [1, 2, 'stringstring2'].

Additional Parameters

Socket Handle:

This parameter can be used to specify the handle of the socket to which the data are written, i.e., from the previous tool, where a "Socket Handle" is already defined. If the "Socket Handle" is set, the "URL" and "Timeout" will be adopted from this previous tool.

Results

Basic Results

This tool has no basic results that are visible within MERLIC. The actual result is the file in which the text is written.

Tool State:

"Tool State" returns information about the state of the tool and thus can be used for error handling. Please see the topic Tool State Result for more information about the different tool state results.

Additional Results

Socket Handle Used:

This parameter represents the handle of the socket to which the data are written. It can be used by a subsequent tool to write or read. It should be avoided that several tools use the same handle to read from or write to the same socket simultaneously since this may lead to unexpected effects.

Processing Time:

This result returns the duration of the most recent execution of the tool in milliseconds. The result is provided as additional result. Therefore, it is hidden by default but it can be displayed via the button beside the tool results. For more information see the section Processing Time in the tool reference overview.