This section guides you through the installation and basic setup of Harlequin Direct, so that you can process your first PDF and confirm it has been output correctly.

Installation

There is no separate installer for Harlequin Direct; to deploy everything required, extract the supplied zip/archive file into the directory of your choice.

If you are running Harlequin Direct on Windows, you must install the following Visual Studio redistributables:

• Microsoft Visual C++ 2015-2019 Redistributable
• Microsoft Visual C++ 2013 Redistributable

Due to the use of socket-based communication, Windows Firewall may block access to certain ports during running on Windows. Similarly, ensure that you set appropriate permissions in Linux.

Connecting to Harlequin Direct

To confirm that a connection can be established on Windows, launch Harlequin Direct as follows from a command prompt in the directory with HarlequinDirect.exe:

HarlequinDirect -port 9999

To confirm the same on Linux, launch Harlequin Direct from its directory at the console/terminal as follows:

./HarlequinDirect -port 9999

In both cases, you should see:

HarlequinDirect
Version 1.8.0.33
(C) 2021 Global Graphics Software Ltd

If port 9999 is not available, Harlequin Direct exits and you also see Socket connection failed. Please try other ports until you discover one that is free.

To try the connection on Windows, use a telnet client such as PuTTY to connect to localhost on port 9999.

To test the connection on Linux, use telnet from the command prompt as follows:

telnet localhost 9999

In both cases, you should see the following in your telnet prompt:

HARLEQUIN_DIRECT_READY

If you do not see this output, something is likely blocking your socket-based communication. On Windows, this is usually due to Windows Firewall settings; on Linux, ensure that you update your port permissions.

Once you can communicate with Harlequin Direct, you can shut it down remotely over telnet with the following command:

EXIT

If you drive Harlequin Direct from another machine, repeat these steps from that machine, replacing localhost with the IP address of the machine running Harlequin Direct, to confirm that the required connection across the network can be established.

Licensing

To do anything beyond confirming your connection, you require a Harlequin Direct license, which is a base-64 encoded string associated with your password.

If you do not have a license string and password, please contact your Global Graphics representative, as you can't proceed without them.

Plugins

For extensibility and scalability, Harlequin Direct uses a plugin-based pipeline architecture, where the specific plugins and the number of threads devoted to them can be configured as required. (The number of parallel RIPs are also configurable, as you will see in the next section.)

The available plugins you can select depends on your digital press workflow, but the following pipeline, which we use for the remainder of this guide, is always available:

Screening → Packing → Tiff Output

Each stage of the pipeline receives its work from the previous stage or from the RIP (in the case of the first stage) in a queue; completed work goes onto the queue for the next plugin (if there is one).

To achieve different pipeline configurations, see the next section for details.

Basic configuration

Harlequin Direct uses a JSON (JavaScript Object Notation) format configuration file, which allows you to exercise control over all aspects of the application. The file is organized as a single top-level object containing multiple "section" sub-objects. The sections contain the actual configuration options. The following table covers the basic settings you may wish to change. (For a full table of configuration options, see Advanced Usage.)

"Plugin1.dll"[1]|"Plugin2.dll"[1]

You can specify the configuration file either when launching Harlequin Direct or when it is idle (that is, not processing any active jobs) through the API or socket interface. The former is covered in the next section; see Advanced Usage for details on the latter.

Once you launch Harlequin Direct, you can't change the command port.

In the next section, use the example JSON config ExampleHDConfig.json.

Processing your first PDF with Harlequin Direct

Before you start, ensure a PDF is available to process. In this example, we use the Harlequin Direct brochure from the Global Graphics website (saved as brochure.pdf in the same directory as the Harlequin Direct binary).

Edit ExampleHDConfig.json to include your license string as the value for HDLicence (instead of INSERT_LICENSE_HERE).

Launch Harlequin Direct with example config file

On Windows, launch requires the following at the Command Prompt in the directory containing the HarlequinDirect.exe binary:

HarlequinDirect.exe -C ExampleHDConfig.json

On Linux, launch requires the following at the console/terminal in the directory containing the HarlequinDirect binary:

./HarlequinDirect -C ExampleHDConfig.json

Note: Since a command port is already specified in the configuration file, there is no need to supply one with -port.

Connect using telnet and supply password

Connect over telnet like in the Getting Started section with PuTTY or via the telnet command on Windows or Linux, respectively.

You should see:

HARLEQUIN_DIRECT_READY

Now enter the following at the telnet prompt, replacing yourpasswordhere with your actual password:

SET_PASSWORD,yourpasswordhere

You should see:

SOCKET_RECEIVED
COMMAND_QUEUED,1,SET_PASSWORD,yourpasswordhere
COMMAND_EXECUTING,1
COMMAND_SUCCEEDED,1

Your Harlequin Direct window should still only be showing the following:

HarlequinDirect
Version 1.8.0.33
(C) 2021 Global Graphics Software Ltd

Starting a print run

All jobs processed by Harlequin Direct must take place within a “Print Run”.

In your telnet session, submit the following command:

START_PRINT_RUN

In the telnet window, you should see:

SOCKET_RECEIVED
COMMAND_QUEUED,2,START_PRINT_RUN
COMMAND_EXECUTING,2
COMMAND_SUCCEEDED,2

And in the Harlequin Direct window, you should see:

Awaiting Command socket connection : Port 9998
Command Socket connected!
Awaiting Status socket connection : Port 9997
Status Socket connected!
Waiting for ScreenPro Direct Password
ScreenPro Direct Password Set
Idle (Output released)
Starting scalable rip...
Initial RIP virtual memory: 5 MiB (4776 KiB) used, 59 MiB (60416 KiB) commit limit, 128 MiB (131072 KiB) reserved

This means that the RIP and the screening pipeline are ready for processing your PDF.

Submitting your PDF

With the Print Run now started, you can send your PDF by supplying the path to it in a SUBMIT_JOB command.

This path is relative to the working directory of the Harlequin Direct application, so ensure that you copied it to that machine (or made it available via a network share) if you are driving Harlequin Direct from a different one.

To submit the job, send the following in the telnet session:

SUBMIT_JOB,datasheet.pdf,1

You should see something similar to the following in the Harlequin Direct window:

Scalable RIP Accepted Job 1 On Thu Dec 10 17:51:04 2020
File: datasheet.pdf
Config: Direct_Default_CMYK
Priority: 0
Ripping file %C%GGS/HarlequinDirect_Windows_v1.5.0/datasheet.pdf as PDF.
Starting Job On Thu Dec 10 17:51:04 2020
Title: Not Available
Subject: Not Available
Author: Not Available
Creator: Adobe InDesign 15.0 (Macintosh)
Producer: Adobe PDF Library 15.0
CreationDate: D:20200409105057+01'00'
ModDate: D:20200409105058+01'00'
Trapped: False
Scalable RIP Metadata for Job 1
File: datasheet.pdf
Pages: 2
Chunk Size: 1
Scalable RIP Starting Job 1 On Thu Dec 10 17:51:04 2020
Total time: 0.028 seconds (00:00:00.028)
Job Completed: datasheet.pdf

Scalable RIP Job 1 rendered 2 pages of 2...
Scalable RIP Job 1 Schedule time: 0.498 seconds (00:00:00.498)
Scalable RIP Job 1 Active time: 0.290 seconds (00:00:00.290)
Scalable RIP Job 1 Elapsed time: 0.319 seconds (00:00:00.319)
Scalable RIP Job 1 Completed: datasheet.pdf

If you check the Harlequin Direct directory, there should now be eight TIF files (that is, four separations for each of the two pages of the datasheet) named from JobId_1_ImageId_1_Plane_1.tif to JobId_1_ImageId_2_Plane_4.tif.

Stopping the Print Run

Ordinarily, you would likely send more PDFs through at this point, but we stop the Print Run here.

Type the following in the telnet session:

STOP_PRINT_RUN

You should see:

SOCKET_RECEIVED
COMMAND_QUEUED,4,STOP_PRINT_RUN
COMMAND_EXECUTING,4
COMMAND_SUCCEEDED,4

In the Harlequin Direct window, you will see something like:

Waiting for IDLE command
Run complete
Idle (Output released)
Average Throughput : 399.107624 MB/s

You can now send the EXIT command to shut down Harlequin Direct and disconnect.

If all is confirmed to be working as expected, there is no need to use socket-based communication to drive Harlequin Direct beyond this point. We recommend that you use the Harlequin Direct API instead, which is detailed later in this guide.