Handle

“Handle” is the general term for something which is stored. There are handles for every item: for playbacks, palettes, workspaces, groups, fixtures and more. To get an impression what handles are in your show you might use Titan IDs.

With regards to the Web API there are three ways to identify a handle:

• by usernumber - this is the number you set using Set Legend in Titan. In order to use this method denote the handle as
  handle_userNumber=2
• by location - this is the 'place' where you find this item in the Titan UI, e.g. the 6th button on page 1 in the Fixtures and Playbackswindow. In order to use this method identify the handle as
  handle_location=Presets_1_6
  • 'Presets' is the handle group i.e. the workspace window “Fixtures and Playbacks”. See Location for the available groups
  • 1 is the page number (1-based)
  • 6 is the button number on that page (1-based)
  • all three parts are concatenated wih underscores _. Titan IDs already gives the correct location string.
• by Titan ID. Everything in the show has a unique ID which is set by the system and cannot be changed by the user. You can get the Titan IDs of your show with Titan IDs. There are some useful reserved IDs for masters, see titanId. In order to use this method to identify a handle the notation is
  handle_titanId=2335.

Let's assume we want to kill a particular cuelist using Playbacks/KillPlayback. The prototype for this is

http://[ip]:4430/titan/script/2/Playbacks/KillPlayback?handle={handle}

Given a show where a cuelist is recorded in the Fixtures and Playbacks window (group: Presets), page 1, button 6, and this cuelist (here: Cue List 2) has the user number 2:

Luckily Titan IDs already shows the Titan ID and the correct location (it's the “Computed Web API Location string”).

We can kill this cuelist by one of the following ways:

http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_userNumber=2 - by user number http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_location=Presets_1_6 - by location http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_titanId=2335 - by titan Id

It appears that Titan applies some guessing and interprets the handle as userNumber if no other type is defined. Hence,

http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle=2 does also work.

Various errors may result from wrong or incomplete parameters:

http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle=Presets_1_6 does not work and throws the error
“Error: Failed to parse value to AcwUserNumber”

Reason: the part _location is missing, thus Titan tries to parse this as usernumber (default), and fails.

http://localhost:4430/titan/script/2/Playbacks/KillPlayback?2 does not work and results in
“Error: Der Objektverweis wurde nicht auf eine Objektinstanz festgelegt.” (no object referenced)

Reason: the parameter name and parsing (handle_userNumber) and the equal sign is missing.

http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_titanId=23350 leads to
“Error: Unable not find handle in group 'playbackHandle' with index '23350'.\r\nParametername: handle”

Reason: the specified handle could not be found (there doesn't exist a handle in that location/with that titanId)

http://localhost:4430/titan/script/2/Playbacks/KillPlayback? throws
“Error: Die Sequenz enthält kein übereinstimmendes Element.” (no matching element in sequence)

Reason: the handle wasn't correctly specified or not specified at all

http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_titanId= gives
“Error: Die Eingabezeichenfolge hat das falsche Format.” (wrong format)

Reason: the parameter name and parsing was correctly set but no value given.