CueScript commands frequently contain strings. A string is a series of zero or more characters enclosed in “double-quotes”.

Examples of strings include: “Hello World”, “Press Stop to Cancel Show Playback”, “button.onColor”, and “My First Show”.

Examples of commands that use strings are AUDIO, LOAD, LOG, SET, STACK, and WRITE.


Special Characters

Sometimes it is necessary to enter special characters that are non-printable or difficult to enter into a string from the keyboard. Examples include carriage returns, linefeeds, tabs, quotation marks, or special hexadecimal characters such as NULL (0×00).

CueServer allows special characters to be entered into strings using escape sequences that start with the backslash character (\) followed by a single letter that designates the specific escape character desired. For example, the escape sequence “\n” becomes a new-line character.

Because the backslash is used to mean “escape”, a single backslash can’t be used to put a backslash into a string. If a backslash is needed, use the escape sequence for backslash which is a double-backslash (\\).

The following table shows the supported escape sequences:

Escape Sequence Hex Value Character Represented
\a 0x07 Alarm/Bell
\b 0x08 Backspace
\f 0x0C Formfeed
\n 0x0A Newline
\r 0x0D Carriage Return
\t 0x09 Horizontal Tab
\v 0x0B Vertical Tab
\\ 0x5C Backslash
\' 0x27 Single quotation mark
\" 0x22 Double quotation mark
\xhh 0xhh Any hexadecimal byte
\nnn 0xoo Any octal byte

Note that there are two special escape sequences for hexadecimal and octal bytes. The hexadecimal escape sequence is a “backslash-x” followed by exactly two hexadecimal characters (each from 0 thru F) that represents the desired byte. The octal escape sequence is a backslash followed by three digits from 0 thru 7. These three digits represent the desired byte value in octal.


Value Substitutions

In addition to the escape sequences above that allow special characters to be inserted into a string, CueServer also supports a variety of escape sequences that are used to substitute special values into a string.

These values change depending on the context in which the string is being used. CueServer will substitute the escape sequence with the actual value at the time that the string is being used. Each substitution is only valid within the context(s) supported.

The following table shows the supported escape sequences for Value Substitutions:

Escape Sequence Value Substituted Valid Contexts
\c Channel Number (8-bit) DMX Triggers
\C Channel Number (16-bit) DMX Triggers
\l Channel Value (8-bit) DMX Triggers
\L Channel Value (16-bit) DMX Triggers
\i Inverted Channel Value (8-bit) DMX Triggers
\I Inverted Channel Value (16-bit) DMX Triggers
\s Checksum; sum of preceding bytes (8-bit) Any
\S Checksum; sum of preceding bytes (16-bit) Any
\* Reset checksum to zero Any

By default, each of the values above will be substituted as a binary value. Additional modifiers may be placed between the backslash and the character to change which character format is used to output the value. Supported modifiers are listed below:

Modifier Result
$ The value will be output in hexadecimal ASCII characters (0-F). 8-bit values will output exactly 2 characters and 16-values will output exactly 4 characters.
# The value will be output in decimal ASCII characters (0-9). 8-bit values can range from 0-255 and 16-bit values can range from 0-65535.
% The value will be scaled to a percentage (0-100) output in decimal ASCII characters (0-9)

Examples

Write COM1 "Hello World\n"
Writes the string Hello World followed by a newline to the COM1 serial port.

Write COM1 "One\tTwo\Three\tFour"
Writes the strings One, Two, Three, and Four with tabs in-between each string to the COM1 serial port.

Write COM1 "Press \"Start\" to Begin\x00"
Writes the string Press “Start” to Begin followed by a NULL byte to the COM1 serial port.

Log "Channel \#C is set to \#l"
Adds a system log message with a string such as “Channel 701 is set to 255”.

Write "10.0.1.5" "5AA5\$C80\$l\$S"
Sends a UDP packet to 10.0.1.5 with a string such as “5AA502BD80FF033D”, assuming that the channel is 701 and the level is 255.