Documentation Center

Viz Trio User Guide

Version 4.1 | Published September 25, 2023 ©

Working with Macro Commands over a Socket Connection

Viz Trio can be controlled using custom made control applications over a TCP/IP socket connection on port 6200 (the port number can be overridden - see Command line Parameters). This feature lets you use macro commands that can trigger actions in Viz Trio.

This section covers the following topics:

Sending Macro Commands

This section shows how to establish a connection with Viz Trio over a socket connection in order to send Macro Commands to control Viz Trio. Telnet is used as an example below.

To Configure Viz Trio for Socket Connections

  1. Open the Configuration Window and select Socket Object Settings.

  2. Set the following in the menu:

    • Set Socket type to Server socket.

    • Set Text encoding to UTF-8

    • Check Autoconnect and set Socket Host to localhost and Socket Port to 6200.

  3. Click OK.

To Connect to Viz Trio Using telnet

  1. Open Telnet by clicking Start, typing Telnet in the Search box, and then clicking OK.

  2. Type telnet localhost 6200 and press Enter.

    Note: Windows 7 users must enable Telnet as it is disabled by default.

To Send Commands to Viz Trio Using telnet

  1. Create a page in Viz Trio with the page number 1000.

  2. Open a telnet connection to Viz Trio, type page:read 1000 and press Enter.

To Enable telnet for Windows 7

  1. Click Start, click Control Panel, select Programs, and then click Turn Windows features on or off. Enter the administrator password or confirmation if prompted.

  2. In the Windows Features dialog box, select the Telnet Client check box.

  3. Click OK. Installation may take several minutes.

Unicode Support

Commands that can set and get text values (such as set_value and getproperty) support the full set of Unicode characters. The internal format is UTF-16 (WideString). However, when communicating with Viz Trio over a socket connection on port 6200, an 8-bit string must be used, and the default (and preferred) encoding is therefore UTF-8. It's also possible to use latin1 (ISO-8859-1, western european) encoding.

To Toggle the Socket Encoding

  • Send one of the following commands to the socket: socket_encoding latin1 or socket_encoding utf8.

    Note: The socket_encoding command is not a macro command, and can only be used with socket communication.

Escape Sequences

A socket command is terminated by a new line. To support setting and getting multi-line parameters and results, some characters must be escaped, i.e. represented by sequences of other characters. Backslash is used as the escape character for socket commands.

See the table below for supported escape sequences.

Escape Sequences

Escape Sequence

Meaning

\n

New line

\r

Carriage return

\xHH

Two-digit hexadecimal character code.

\

Backslash (\)

Error Messages

When controlling Viz Trio over a socket connection, you can enable error messages using the commandserver command:

commandserver:enable_error_messages true commandserver:enable_error_messages false

Note: Typing commandserver is optional.

Enabling error messages will send error messages to the connected client and display them on the interface (on a per socket connection). The client will receive all error messages that are normally only displayed on the Viz Trio user interface.

Note: All errors are sent. For example, if an operator attempts to read a non-existing page, this will result in error messages being sent to all clients connected over a socket connection.


Errors have the following format:

ERROR: <Error message>

If error handling is disabled, the client will still see errors caused by commands not being found and commands that return an error.

This command is only implemented for the command server on port 6200, and is not related to Socket Object Settings in the Configuration Window.