Control Center Scripting Interface

Introduction

The Control Center scripting interface allows you to script and automate manipulations to the database.

You can run a Control Center script immediately from a server or client machine, or launch Control Center as a script server from the server machine, and allow clients to send scripts to it through Telnet.

Batch Mode

You can run a script in Control Center by writing the script in a text file, then running Control Center with the following syntax:

Controlcenter -runScript <script_file> -user <user_name>

Controlcenter will execute the script in batch mode and exit.

The following is a sample script that imports an exported scene package three times, renaming it each time:

// The following function imports a scene from a given package, and then renames it
function TB_importAndRename()
{
var job = new Job( "testEnvCreate", "newJob");
{
// Importing the package 3 times, and renaming to DefaultScene1, DefaultScene2, etc
for ( var k = 0; k < 3; k++ )
{
// Note, the path to the package would be /home/testExport
// DO NOT specify IEContents.dat, it is assumed by the import module
var importData = new ImportData( job.envName,
job.name,
"/home/testExport/", // path to a package where scene is named "1"
"/USADATA"); // fileSystem
if ( ControlCentre.importScene( importData ) )
{
messageLog = "Imported scene " + job.envName + "/" + job.name + "/home/testExport successfully ";
}
else
{
messageLog = "Import fail";
}
// Now rename the scene "1" to "DefaultScene#" in order to be able to import it again
var scene = new Scene(job.name, "1");
scene.fileSystem = "/USADATA";
var name = "DefaultScene" + k; // Name must not exceed 25 chars
ControlCentre.printToConsole("renamed scene " + scene.jobName + ":" + scene.name );
}
}
}
TB_importAndRename();
Note
As in the example above, the function must be defined first, then called, so as to be executed when running the script. Contrary to Telnet Server mode, scripts executed in batch scripting mode should not begin with TB_BeginScript and end with TB_EndScript.

Telnet Server Mode

ControlCenter can be ran as a server from the database server machine and used remotely via the Telnet protocol. Doing this instead of running scripts from a client machine can significantly increase the performance of scripts, as ControlCenter will have direct access to the database files.
To act as a script server, ControlCenter must be run in a shell with the -script parameter. ControlCenter will launch as a server and will executed commands it receives through the port specified in the environment variable TOONBOOM_REMOTE_SCRIPT, which must be set beforehand.

  • On UNIX-based systems:
    export TOONBOOM_REMOTE_SCRIPT=1234
    Controlcenter -script
  • On Windows:
    SET TOONBOOM_REMOTE_SCRIPT=1234
    Controlcenter -script

The port number can also be specified with the -tcpPort argument:

Controlcenter -script -tcpPort 1234

In order to send scripts containing multiple lines to the script server, scripts must have a beginning and end token. These tokens are named TB_BeginScript and TB_EndScript, respectively. Control Center will execute each line of script betweens these tokens.

The following is a simple sample script to print out all versions of all scenes in a environment named "Test" and a job named "a".

TB_BeginScript
// List elements in a scene/job/environment
for (var i = 0; i < list.length; i++ )
{
env = list[i];
if ( env.name == "Test")
{
jobList = ControlCentre.jobs( env);
for ( var j = 0; j < jobList.length; j++ )
{
job = jobList[j];
if ( job.name == "a" )
{
sceneList = ControlCentre.scenes( job );
for ( var k = 0; k < sceneList.length; k++ )
{
scene = sceneList[k];
versions = ControlCentre.versions( scene );
for ( var l = 0; l < versions.length; l++ )
{
var ver = versions[l];
ControlCentre.printToConsole(ver.toString(true));
}
}
}
}
}
}
//Retrieve the entire message log and print it out.
TB_EndScript
Note
Database modifications are only obtained through the ControlCentre class methods. All other classes in this interface simply define data objects. Thus, declaring a new object of type Job does not add it to the database. Only a call to ControlCentre.addJob() achieves this.

Error Reporting

As these are database operations protected by locks, it is important to check the message logs. The ControlCentre object provides two very important methods to do this. Most scripts should have the following two lines at the end.

All messages that would normally appear in the applications message log can now be viewed in the telnet session.