Cookbook

Getting familiar with Tightener.

Most of the action around Tightener is either 'behind the screens' or by way of the command line.

Once you have installed and configured Tightener, we can start interacting with it.

scriptrunner

We'll gradually explore our Tightener swarm.

On Mac and Linux we'll be running the commands from a Terminal window.

The first member of the swarm is called scriptrunner.

This is a local Tightener instance whose sole purpose is to run TQL (Tightener Query Language) scripts from the command line.

Run the command (yes, with an underscore between cd and samples)

cd_samples

This will take you to the SampleScripts directory.

Run the command

rt hello.tql

This will launch Tightener with coordinator net.tightener.coordinator.scriptrunner, read and execute hello.tql and quit. The console should show

Hello from hello.tql

Use

cd_samples
editFile hello.tql

and

cd_scripts
editFile rt

or

cd_scripts
editFile rt.bat

to view these files.

reflector

net.tightener.coordinator.reflector aka. reflector is a second type of coordinator.

I use it mostly for testing - bouncing off stuff and making sure I see the correct echoes return.

First, type

killApps
whatIsRunning

This kills any Tightener nodes you might have running previously, then shows you what Tightener nodes are still running. There should not be any as the killApps we entered has just killed them.

We'll now run the same hello.tql script but instead of using scriptrunner we'll send the script to the reflector and run it there.

We now use the rrt command ('run remote tql'). rrt is like rt but we also provide a target coordinator to use. This coordinator could be local or remote, all depending how things are configured.

Because rrt is also used with remote nodes, by default, rrt will wait for 10 seconds before terminating.

In this example we don't need it to wait that long and we'll override the default wait from 10 seconds down to 1000 milliseconds - that's what the 1000 you see below is about.

cd_samples
rrt reflector hello.tql 1000

The result seems the same as with rt. But behind the screens a lot more has happened.

We've now started up a swarm with three nodes: scriptrunner, main and reflector.

We also triggered a chain of data transfers:

scriptrunner -> main -> reflector -> main -> scriptrunner

Any Tightener computer can run a swarm of Tightener nodes, and that swarm is set up as a star network.

There can be many coordinators, including a special main coordinator, which is the hub at the center of the star.

When we run rrt, we launch scriptrunnner and instruct it to send the script hello.tql to a coordinator identified as reflector.

scriptrunner will consult our config.ini to resolve the shorthand notation reflector into a full URL.

The shorthand reflector expands to tgh://localhost/net.tightener.coordinator.reflector/default which is the fully qualified URL for our reflector coordinator.

scriptrunner is not able to communicate directly with reflector - it has to ask the main coordinator for help.

The main coordinator is the only coordinator able to launch other coordinators as needed.

main can receive messages from any coordinator on the computer and can send messages to any coordinators on the computer.

Other coordinators can only send messages to main. They can also launch main if it is not running yet. main is the hub for messaging.

1. So, scriptrunner starts, it needs to communicate with another coordinator and needs help. It notices main is not running. It will launch main.

2. Once main is up and running, scriptrunner sends hello.tql to main and tells it that this script needs to go to reflector.

3. main knows how to launch reflector. Once reflector is up and running, main sends the script to reflector

4. reflector runs the script. The script calls stdOut(). stdOut() will send output data back to the instigator of the script (scriptrunner). reflector send this data destined for scriptrunner to main, so main can forward it.

5. main then forwards the data from stdOut() to scriptrunner.

6. Finally, scriptrunner displays the stdOut() info and quits.

Type

whatIsRunning

this will now show you that there are two Tightener nodes still running in the background - main and reflector.

scriptrunner has quit after it completed its task, but the other coordinators remain alive.

Running killApps will quit those.

Need to use killApps after config.ini changes

The important thing to remember is that after you've made changes to config.ini, you should get into the habit of running killApps.

Otherwise, you might have coordinators running that have not 'seen' those changes.

But that is not all. killApps only quits 'pure' Tightener coordinators.

It does not kill apps like InDesign who embed Tightener as a plugin.

If you are using InDesign or Xojo or any other tool that embeds Tightener as a plug-in, you need to quit and restart after config.ini has been changed.

Interacting with InDesign

Tightener allows you to interact with many nodes - including multiple InDesign nodes if desired.

For example, a controlling Tightener TQL script could coordinate a bunch of local or remote InDesign Server nodes and coordinate all of them.

We'll start small and start with a local InDesign interaction.

When configuring Tightener, we defined some InDesign settings.

Tightener does not need to have a single, preferred InDesign target, but for the sake of this cookbook, having a default InDesign target that can be referred to as indesign makes things easier to explain.

The default config is set up to target one local copy of InDesign by way of a simple string indesign.

I'll assume you've set up the config to target the 2022 desktop version of InDesign for your platform (Mac or Windows).

Installing the plug-in

On Windows, you need to use a CMD window with elevated privileges - go to the Start button, type 'CMD', right-click the 'Command Prompt' option and select 'Run as administrator'.

Alternatively, you can make the permissions on the InDesign Plug-Ins folder less strict.

On my development machines, I loosen the permissions on Plug-Ins to allow regular users to have all normal permissions.

To install the Tightener plug-in you need to run the following command:

idPluginInstall

On Mac you might be asked for your password - this is because the idPluginInstall script uses sudo to get permissions to write to the InDesign Plug-Ins folder.

idPluginInstall will remove any older version of the Tightener plug-in before installing the current plug-in.

Later on, when desired, removing the plug-in is achieved with

idPluginRemove

Launching InDesign

The default config.ini is set up in such a way that the main coordinator is not able to launch InDesign.

All it is able to do is to launch the 'normal' Tightener coordinators - scriptrunner, reflector, console...

Once the InDesign plug-in is installed, we can launch the target version of InDesign with

idLaunch

It is recommended you use this command on the command line rather than double-clicking the InDesign icon, especially if your computer has multiple copies of InDesign installed.

By using idLaunch we can be relatively sure that the correct version of InDesign will launch.

Interacting with InDesign

Now that InDesign is running, we can run the same hello.tql script with it:

cd_samples
rrt indesign hello.tql

The result looks no different than before, but this time we've communicated from

scriptrunner -> main -> indesign -> main -> scriptrunner

We can also run InDesign-specific scripts. Run

cd_samples
rrt indesign getInDesignAppName.tql

and the return value should be

Adobe InDesign

which is the value of app.name in the InDesign DOM.

Running ExtendScript

There is also a command rre - Run Remote ExtendScript.

This works almost the same as rrt but instead it takes an ExtendScript rather than a TQL script.

idMakePDF.jsx is a simple-minded script that makes a PDF file.

cd_samples
rre indesign idMakePDF.jsx

In this case, indesign refers to our local copy of InDesign, but it would be just as easy to edit the config.ini and have indesign refer to a copy of InDesign Server on some remote server - the script can be run in exactly the same way.

Enabling networking

Tightener nodes are not network-enabled by default - a swarm of nodes can communicate as long as they are all running on the same computer.

On a computer, multiple Tightener nodes communicate with one another by way of the main node, which sits in the center of a star network of nodes.

The default main node is not network enabled.

To enable networking, we could add a gateway node to the swarm. Such gateway node does not need to be the main node. It is also possible to use a main node which can do double-duty as a gateway.

The current version of Tightener comes with three options for the main coordinator:

• a local, non-gateway version (default) ("${LOCAL_TIGHTENER_RELEASE}")
• a gateway version with a command-line UI ("${XOJO_CMDLINE_TIGHTENER_RELEASE}")
• a gateway version with a graphical UI ("${XOJO_UI_TIGHTENER_RELEASE}")

The gateway versions were written in Xojo, using he XojoTightener.xojo_plugin plug-in. In the future, many more gateway options can become available - building a gateway coordinator from scratch is a good test-case for any new Tightener plug-ins or DLLs I create.

Edit the config file:

editConfig

Find the line that says

MAIN_APP = "${LOCAL_TIGHTENER_RELEASE}"

and change it to

MAIN_APP = "${XOJO_CMDLINE_TIGHTENER_RELEASE}"

This tells the swarm to use a different main node.

To make sure all coordinators see the updated config.ini, we must kill any background nodes

killApps

If you have InDesign running, you also want to quit it.

Now we'll start the network-enabled main coordinator so it can start listening for remote connections.

The command to launch it is

gwConsole

This command will usurp your Terminal window, and you will need to open a new, additional Terminal window to continue working.

You must make this change on all computers that need to be part of the extended Tightener swarm.

Configure Linux to run InDesign scripts

If you have a Linux machine and a Mac or Windows machine with InDesign or InDesign Server, you can now run InDesign scripts from the Linux command line.

On Linux, we can now reconfigure the config.ini to use a remote Mac or Windows computer to run InDesign.

My Mac is registered under DNS name holly.rorohiko.com - I'll use that as an example to configure Linux.

On Linux:

editConfig

Change the line that says

[urlMap]
...
indesign = tgh:///indesign/main
...

into

[urlMap]
...
indesign = tgh://holly.rorohiko.com/indesign/main
...

This tells the Tightener swarm on Linux that the local URL shorthand indesign refers to the indesign coordinator on holly.rorohiko.com.

The second mention of indesign in this example is a shorthand reference to a coordinator on holly.rorohiko.com.

In other words, the string indesign in the URL tgh://holly.rorohiko.com/indesign/main will be resolved to a fully qualified RDN by holly.rorohiko.com using the config.ini file on holly.

It is important to grasp that in order to resolve a target like indesign on the Linux machine, we are relying on two independent config.ini files: one on the Linux machine and a second one on holly.rorohiko.com.

First, the config.ini on Linux maps the word indesign to a URL tgh://holly.rorohiko.com/indesign/main. This URL eventually ends up on holly.rorohiko.com which then uses its own config.ini further resolve indesign/main to net.tightener.coordinator.indesign.17.0/main, which gives us the fully resolved URL: tgh://holly.rorohiko.com/net.tightener.coordinator.indesign.17.0/main.

Restart your main node:

killApps
gwConsole

Assuming the gwConsole is running on the Mac as well as on Linux, and idLaunch was used on holly.rorohiko.com to launch InDesign, we can now execute:

cd_samples
rre indesign idMakePDF.jsx

on the Linux machine and this will execute the script on the Mac.