Issuu on Google+

PuzzleFlow™ WebPairer Manual

2002-2008 Copyright © ACCHSH


Contents 1 Legal Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1 Copyrights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5 5 5

2 License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1 Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Rights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3 Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4 Limited Warranty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.5 Limitation of Liability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.6 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7 7 7 8 8 8 9

3

Introduction

................................................

11

4

About WebPairer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13

5 Installing PuzzleFlow™ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1 Before the installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2 New installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3 Upgrading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4 Uninstalling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

15 15 15 21 21

6 PuzzleFlow Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.1 MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.1.1 Installing MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.1.2 Configuring MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.1.3 Managing MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2 MySQL ODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.1 Installing MySQL ODBC Connector . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.2 MySQL System Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3 PostgreSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.1 Installing PostgreSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.2 Managing PostgreSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.4 PostgreSQL ODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.4.1 Installing PostgreSQL ODBC Connector . . . . . . . . . . . . . . . . . . . . . . . 6.4.2 PostgreSQL System Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.5 PuzzleFlow 3.x Database Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

25 25 25 28 34 37 37 38 41 41 47 49 49 52 55

1


2

7 HASP dongle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.1 Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2 Dongle installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.3 Dongle activation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.4 Quick Troubleshoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.5 Online support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

59 59 59 62 64 64

8 Reference Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.1 Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2 Work with WebPairer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2.1 Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2.2 Configuration template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Base information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filename pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Task configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deadline configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2.3 Job tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running new job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Job manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Single job monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Single job stage monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Job statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deadline monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

67 67 67 67 67 68 68 69 71 72 72 72 73 73 73 74 74

9 Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.1 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.1.1 Scalar variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.1.2 Global variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.1.3 Workflow variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.1.4 Puzzle variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.1.5 Job variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.1.6 Scoping rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.1.7 Array variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.1.8 Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2.1 Path functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2.2 Date Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2.3 String functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2.4 Number functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

77 77 77 80 83 84 91 94 96 97 102 103 106 108 112


9.2.5 9.2.6 9.3 9.3.1 9.3.2 9.3.3 9.3.4

Array functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Number operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . String operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comparison operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logical operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

113 116 117 118 119 119 120

10 Contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

123

3


4


Legal Information

Legal Information Copyrights

1 1.1

This document is protected under international copyrights, 2002-2008 ACCHSH. All information contained herein is the property of ACCHSH Group Ltd. No part of this publication (whether in hardcopy or electronic form) may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of the publisher. This publication and the information herein are furnished AS IS, are subject to change without notice, and should not be construed as a commitment by ACCHSH Group Ltd. ACCHSH Group Ltd assumes no responsibility or liability for any errors or inaccuracies, makes no warranty of any kind (express, implied, or statutory) with respect to this publication, and expressly disclaims any and all warranties of merchantability, warranties for particular purposes, and noninfringement of thirdparty rights.

Trademarks

1.2

Adobe, the Adobe logo, Acrobat, the Acrobat logo, Acrobat Capture, Acrobat Reader, Adobe Garamond, Aldus, Distiller, ePaper, Extreme, FrameMaker, Illustrator, InDesign, Minion, Myriad, PageMaker, Photoshop, Poetica, PostScript, and XMP are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Apple, Mac, Mac OS, Macintosh, QuickDraw, and TrueType are trademarks of Apple Computer, Inc., registered in the United States and other countries. KanjiTalk is a trademark of Apple Computer, Inc. UNIX is a registered trademark of The Open Group. Unicode is a registered trademark of Unicode, Inc. Java is a trademark of Sun Microsystems, Inc. JavaScript is a registered trademark of Netscape Communications Corporation.

5


Legal Information QuarkXPress is a trademark of Quark, Inc. and/or certain of the Quark Af.liated Companies Reg. U.S. Pat. & Tm. Off. and in many other countries. PANTONE is a registered trademark and Hexachrome is a trademark of Pantone, Inc. PANOSE is a trademark of Hewlett-Packard Company. OEB is a trademark of the Open eBook Forum. Helvetica and Times are registered trademarks of Linotype-Hell AG and/or its subsidiaries. International Cooperation for Integration of Processes in Prepress, Press and Postpress, CIP4, Job Description Format, JDF and the CIP4 logo are trademarks of CIP4. Rather than put a trademark symbol in every occurrence of other trademarked names, we state that we are using the names only in an editorial fashion, and to the benefit of the trademark owner, with no intention of infringement of the trademark.

6


License Agreement

License Agreement

2

READ THE FOLLOWING TERMS AND CONDITIONS CAREFULLY BEFORE OPENING THIS PACKAGE. INSTALLING OR USING THE SOFTWARE INDICATES YOUR ACCEPTANCE OF ALL TERMS AND CONDITIONS OF THE FOLLOWING LICENSE AGREEMENT. IF YOU DO NOT AGREE WITH ANY OF THESE TERMS AND CONDITIONS, PROMPTLY RETURN THIS PACKAGE TO YOUR SUPPLIER FOR A FULL REFUND, IF APPLICABLE.

Terms

2.1

In this License Agreement ('Agreement'), the purchaser of the license rights granted by the Agreement, is referred to as 'Licensee'. According to the terms and conditions of the Agreement, ACCHSH Group is ('Licensor') grants Licensee a single, non-exclusive license to use accompanied software ('Software'). The Software with hardlock protection (HASP) states for licensed product ('Product'). License refers only to the country where acquired from your supplier ('Supplier').

Rights

2.2

All rights to the Licensed Product, including, but not limited to, copyrights and trade secret rights, belong to Licensor or were licensed to Licensor and Licensor holds title to each copy of the Software or has legal right to sublicense the Product. The Software may include software covered by issued or pending patents. For detail on patents, please contact the Licensor. The Software shall only be used together with the supplied protection key (HASP) or in a demo mode. Licensee may transfer the Licensed Product and license to another party if the other party agrees to accept the terms and conditions of this Agreement or distribute the Licensed Product to others. Licensee shall not copy or modify the Licensed Product, except that Licensee may copy the Software for the sole purpose of backup as long as all copyright and other notices are reproduced and included on the backup copy. The Software is delivered in object code only. Decompilation, modification of resources, and any kind of reverse engineering are not allowed.

7


License Agreement

2.3

Termination This License Agreement is effective until terminated. Licensee may terminate this License Agreement by returning the Licensed Product to Licensor. Licensor may terminate this License Agreement if Licensee breaks any condition of the Agreement. Upon the termination of the Agreement for any reason, Licensee shall return the Licensed Product to Licensor. All provisions of this Agreement relating to disclaimers of warranties, limitation of liability, remedies, or damages, and Licensor's proprietary rights shall survive termination.

2.4

Limited Warranty Licensor does not warrant that the functions contained in the Licensed Product will meet Licensee's requirements or that the operation of the Software will be uninterrupted or error-free. Licensor does warrant that the media on which the Software is furnished and the protection key (HASP) will be free from defects in materials and workmanship under normal use for a period of thirty (30) days from the date of delivery ('Warranty Period'). Any other software and any hardware furnished with or accompanying the Software is not warranted by Licensor. Licensee's exclusive remedy under this limited warranty is the replacement of any defective physical media on which the Software is furnished, as provided below. To receive a replacement for defective media under this limited warranty, return the defective media during the Warranty Period, with written description of the problem to the following address: ACCHSH Group, Cracow, Jana Pawła II 41c, 31-864 Poland. EXCEPT AS PROVIDED ABOVE, THE LICENSED PRODUCT IS PROVIDED 'AS IS' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LICENSED PRODUCT IS WITH LICENSEE.

2.5

Limitation of Liability LICENSOR'S SOLE OBLIGATION OR LIABILITY UNDER THIS AGREEMENT IS THE REPLACEMENT OF DEFECTIVE MEDIA AND HASP ACCORDING TO THE LIMITED WARRANTY ABOVE. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY CONSEQUENTIAL, INCIDENTAL OR INDIRECT DAMAGES, INCLUDING, WITHOUT LIMITATION, ANY LOSS OF DATA, OR LOSS OF PROFITS OR LOST SAVINGS, ARISING OUT OF USE OF OR INABILITY TO USE THE SOFTWARE

8


License Agreement OR DOCUMENTATION (OR ANY HARDWARE FURNISHED WITH THE SOFTWARE), EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY THIRD PARTY. IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY DAMAGES.

General

2.6

Any hardware provided to Licensee by Licensor shall not be exported or reexported in violation of any export provisions of the United States or any other applicable jurisdiction. Any attempt to sublicense, assign or transfer any of the rights, duties or obligations hereunder is void. This Agreement shall be governed by and interpreted under the laws of Poland, without regard to conflicts of provisions. LICENSEE ACKNOWLEDGES THAT IT HAS READ AND UNDERSTANDS THIS AGREEMENT AND AGREES TO BE BOUND BY ITS TERMS. LICENSEE FURTHER AGREES THAT THIS AGREEMENT IS THE COMPLETE AND EXCLUSIVE STATEMENT OF THE AGREEMENT BETWEEN LICENSEE AND LICENSOR, AND SUPERSEDES ANY PROPOSAL OR PRIOR AGREEMENT, ORAL OR WRITTEN, AND ANY OTHER COMMUNICATIONS RELATING TO THE SUBJECT MATTER OF THIS AGREEMENT.

9


License Agreement

10


Introduction

Introduction

3

Thank you for choosing ACCHSH software. We hope you will enjoy the product. If you have any questions, do not hesitate to contact us through the website http://www.puzzleflow.com or e-mail addres support@puzzleflow.com.

11


Introduction

12


About WebPairer

About WebPairer

4

Page pairing speeds up the newspaper production by automatically pairing individual newspaper's pages and adding folio, page numbers, color bars and other page furniture. WebPairer is a web-based tool designed for press production. It utilizes advantages of IIS 5 Web Server and PuzzleFlow2 processing engines joining them together in a common press environment. WebPairer is an integral system for creating and managing newspaper production process. It provides the mechanism for creation templates describing whole pairing process. Key features: 1. Integrated web interface for job template definition and job tracking 2. Advanced filename template matching various production 3. Page accept/reject rules extensively utilize variables from job definition 4. 3 stage processing: . . .

preimposition operations (such as preflight, page geometry correction, color correction, personalization and many more) imposition – provides page pairing and plate naming postimposition operations (such as OPI resolving, resampling, separation, halftoning, postflight and output redistribution)

5. Advanced job tracking features: event tracking, progress information, plate production deadlines and e-mail notifications 6. Fast native PDF processing 7. Open architecture

13


About WebPairer

14


Installing PuzzleFlow™

Installing PuzzleFlow™

5

This chapter describes basic installation procedures and some advanced settings needed to start the PuzzleFlow™ system on your machine.

Before the installation

5.1

Due to somewhat overactive operating system safety control some programs are considered malicious and therefore forcefully closed on attempt to perform operations clasified as dangerous. It is called Data Execution Prevention (DEP). To fix the problem you can just specify an exception in Data Execution Previention rules (Control Panel -> System Properties -> Advanced -> Performance -> Data Execution Prevention). Another security system (Windows Vista) is Account Protection Control (UAC) in Control Panel -> User Account -> Settings. It is recommended to switch that off. Also make sure that no third party software (virus protection, script blocking, firewals etc.) does no block PuzzleFlow™ related programs. PuzzleFlow™ system, as well as a database server, often attempts to install and run various processed as services. Be aware that unlike a generic program process, a service process is not visible in the list of processes in the task manager. But services are quite likely to be blocked by various security control systems.

New installation

5.2

The installation package (downloaded from our website or distributed on CD) is an automatic installer application (*.exe file). To start the installation wizard, please, double click on this file or choose Add/Remove Software applet from Control Panel and select Install New. The wizard will guide you through the installation process. Loading Please, wait while the installer is being loaded.

15


Installing PuzzleFlow™ Choose your language

Then select the language you prefer for the PuzzleFlow™ installation. Welcome The setup Wizard will install PuzzleFlow™ on your computer. Press Next.

License agreement Reading and accepting the terms of the license agreement is required to proceed with the installation.

16


Installing PuzzleFlow™

Components For most users it is recommended to install the default components setup. The additional components, such as Web Applications or custom database support are not essential.

Installation folder Select the location where the PuzzleFlow™ system will be installed.

17


Installing PuzzleFlow™

Root folder Then select a root catalogue for the PuzzleFlow™ system. The root folder is a default path for your input and output folders and a default resources search path.

Install in progress Click Install to start the installation. Please wait.

18


Installing PuzzleFlow™

While installing solutions based on PuzzleFlow™ 4, the user is prompted for a database setup. Database installation and configuration has been described in a different section. Installation completed When the installation is completed, click Finish to close the Wizard.

19


Installing PuzzleFlow™

During the installation the wizard will create program directories and copy all the required files to default locations. It will also create a program group and corresponding program icons on your desktop. PuzzleFlow™ installer also takes care about protection dongle drivers. If there is a dongle driver already installed, PuzzleFlow™ skips the driver installation. Otherwise it runs an external installer for dongle driver PuzzleFlow™ creates a system account of name PuzzleFlow for its exclusive use. The account is initiated silently during the installation process, so in pretty most cases you don't need to take care about the account at all. However, if the account setup fails, you need to make some additional steps. To help that, PuzzleFlow™ (version 3.x) comes with Account Wizard application (which may be run the the installer program).

The most common reason of problems related to user account creation is an attempt to overwrite the previous PuzzleFlow™ installation without prior uninstalling. PuzzleFlow™ deinstallation program removes the account. If you skip the deinstallation process, the account remains in the system and PuzzleFlow™ installer may have problems with accessing it. In such a case, stop the installation, remove the account manually and run the installation again. Account Wizard program may be run manually anytime, not only during the installation process, as it is always installed with PuzzleFlow™ 3.x. In all systems based on PuzzleFlow™ 4, a service account setup is launched once runinng Config script

20


Installing PuzzleFlow™ (the same configuration window is used for database initialization, as described in previous sections).

A month after the installation of PuzzleFlow™ the server may no longer start correctly. Then, there is a message that the workflow list cannot be loaded. It happens only on XP Professional or Server operating systems. Due to the limitation of the system account for PuzzleFlow™ there is a problem with automatic login the server to its account. You may change the login limitations using Control Panel -> Administrative Tools -> Computer Manager. In Users entry please, select PuzzleFlow™ and then change its policy to Password never expires.

Upgrading

5.3

If you have PuzzleFlow™ already installed on your system, please, remove the previous installation before installing the new one. The Installer program always tries to replace files with new versions, but we strongly recommend to uninstall the previous version before the new one. Installing thenew version without previous deinstallation may lead to serious problems with the software. If you encounter such just after the new installation, you have probably missed some steps of uninstalling the previous setup.

Uninstalling

5.4

To uninstall PuzzleFlow™ system go to Start menu -> Programs -> ACCHSH -> PuzzleFlow and run Uninstall program.

21


Installing PuzzleFlow™

Confirm removing the PuzzleFlow™ installation.

Uninstalling the wizard will remove all program files, not needed registry settings and the PuzzleFlow system account. All user's configurations stored in the PuzzleFlow root directory are left untouched.

22


Installing PuzzleFlow™

The PuzzleFlow™ system is possibly running while trying to remove the installation. The Uninstaller program tries to kill all PuzzleFlow™ and related processes. It may happen, however, that some tasks cannot be stopped. In such a case, computer restart is needed.

23


Installing PuzzleFlow™

24


PuzzleFlow Database

PuzzleFlow Database

6

The PuzzleFlow™ system may be plugged in to a database. If the database is plugged in, every single job processed in PuzzleFlow™, every preflight report or overall processing log, every single system event is stored in the database. If the database is not connected, PuzzleFlow™ Manager keeps the events during a single session, but once the application is switched off, all job entries and event logs are lost. Usually, we do not need to keep the entire record of all the jobs processed, especially that every job report is stored as a XML file in the PuzzleFlow™ system archive. Every XML report is available as long as someone removes it manually. Although not obligatory for the typical PuzzleFlow™ 3.x installations, a database is required to run web-based applications, such as PuzzleFlow™ WebManager. All solutions based on the PuzzleFlow™ generation 4 framework cannot work without a database at all. PuzzleFlow™ 3.x can work with the following databases: . . . .

PostgreSQL MySQL Microsoft SQL Microsoft Access

Microsoft Access and Microsoft SQL are generally depreciated and should not be used in production. For production systems use MySQL or PostgreSQL. From the list above, PostgreSQL has actually the best performance and stability. But unfortunately, older versions of WebManager application (1.x series) could not be connected to that database. Thus, MySQL is generaly a recommended database for the PuzzleFlow™ 3.x systems. For solutions based on PuzzleFlow™ 4 (new generation of PuzzleFlow™ systems) PostgreSQL is definitely the best choice. Below we describe the installation procedure for MySQL (PuzzleFlow™ 3.x) and PostgreSQL (PuzzleFlow™ 4.x).

MySQL

6.1

Installing MySQL

6.1.1

Download and run MySQL server installation pack. If you install a database for PuzzleFlow™ 3.x, later you will also need the MySQL ODBC Connector installer. One may also install MySQL Query Browser – an application that provides the user

25


PuzzleFlow Database with a friendly access to a database content (you do not need it, unless you want to inspect the database content yourself). Click Next to proceed.

In the next wizard window select the Typical setup type.

Click Install to start the MySQL server installation.

26


PuzzleFlow Database

Please wait until the database has been installed.

After finishing, the wizard will ask you for an optional sign-up.

27


PuzzleFlow Database

OK, the database has been installed. Now the configuration part. Select Configure MySQL server now and click Finish

6.1.2

Configuring MySQL The database configuration wizard is launched automatically after closing the installation wizard window. Click Next to proceed.

28


PuzzleFlow Database

Select Detailed Configuration and click Next

As a server type, select Developer machine and click Next

29


PuzzleFlow Database

As a general usage of database, select Multifunctional Database and click Next

Now select the path in which the MySQL server is supposed to store data. By default, the database file will be created in the installation path.

30


PuzzleFlow Database

Select Decision support at the next wizard step and click Next to proceed.

Select the Enable TCP/IP Networking and Enable Strict Mode options and click Next to continue.

31


PuzzleFlow Database

Select Best Support For Multilingualism and click Next

Select Install As Windows Service and click Next.

32


PuzzleFlow Database

Now choose the root access password of the database. Click Next to continue.

Click Execute to let the wizard configure your MySQL database installation.

33


PuzzleFlow Database

Once all the operations have been successfully performed, click Finish to close the wizard.

6.1.3

Managing MySQL Neither PuzzleFlow™ 3.x installer nor WebManager installation package creates a database to be connected with. You have to do that yourself. The most userfriendly way to do so is to use a query browser with a graphical interface. Below, we describe the simplest method, using a command prompt. Go to the Start menu -> Programs -> MySQL and run MySQL Command Line Client. Enter the root password you have just chosen during the installation.

34


PuzzleFlow Database

Now create a new database by typing create database pf; and hit Enter.

Type exit; to close the MySQL database client.

35


PuzzleFlow Database

While deinstalling the PuzzleFlow™ system, a database remains intact. To remove it manually, type drop database pf; in the MySQL command prompt window.

One should distinguish removing the database from purging its obsolete content. If you want just to cleanup the database by removing some old entries, do not drop the database but use the dedicated PuzzleFlow™ functions, instead.

36


PuzzleFlow Database

MySQL ODBC

6.2

Using ODBC (Open Database Connectivity) is necessary for PuzzleFlow™ 3.x versions. PuzzleFlow™ 4 series communicates with databases natively, and does not utilize ODBC drivers at all. In this case you can simply skip this part.

Installing MySQL ODBC Connector

6.2.1

Run MySQL ODBC Connector installer package.

Click Next and select Typical as a setup type.

Click Install to start MySQL ODBC Connector setup.

37


PuzzleFlow Database

Click Finish to close the wizard.

6.2.2

MySQL System Data Sources Your operating system needs to be properly configured to cooperate with MySQL ODBC. Switch to Control Panel -> Administrative Tools -> Data sources (ODBC) -> System DSN.

38


PuzzleFlow Database

Click Add to make a new System Data Source entry and select MySQL ODBC driver.

Click Finish to close the window. Now you are supposed to provide database connection parameters.

39


PuzzleFlow Database

Fill up the fields according to the database installation presets. Type localhost as the server, root and as the user. As the database, select the name of the new database created before with the command prompt client.

Click Test to check the connection.

40


PuzzleFlow Database

Once a system data source is configured, close the window.

PostgreSQL

6.3

Installing PostgreSQL

6.3.1

Please download and run the PostgreSQL installation package. Choose your preferred language and click Next.

41


PuzzleFlow Database

It is highly recommended to switch off all the running applications while installing a database.

Read database release notes and proceed.

42


PuzzleFlow Database

Choose the location for program files and database files.

Installing PostgreSQL as a service guarantees running the database from its private system account created automatically during the installation process. This account is hidden by default, and also automatically removed while deinstalling the PostgreSQL database. You can specify the password for this account or let the installer generate a random password for you. Note that you will never need to use this password. It is kept and used internally by the database engine only. The PostgreSQL installer does not inform explicitly about creating a new account and removing it while deinstalling the database. If something goes wrong and the deinstaller is not able to remove the account, you will not be informed about that fact. It is recommended to remove such an account using Control Panel ->

43


PuzzleFlow Database Administrative Tools -> Computer Management -> Users and Groups. Otherwise, while installing PostgreSQL again, it may complain about the incorrect username or password, not giving any further explanation of the problem. If you get such a message, most probably you are trying to make an account of the same name as the already existing.

Now comes database initialization. Here you need to specify the communication port (leave default unless you know exactly what you are doing), the region of yours and UTF-8 encoding for both server and client. Then provide a password for the default PostgreSQL user named postgres. Contrary to the system account password specified earlier which you actually do not need to remember, the database user password is used whenever accessing the database directly. In particular, PuzzleFlow™ will prompt for that while trying to establish a connection with the database during the installation process.

44


PuzzleFlow Database

No change required in this window, just proceed.

No changes required here either.

45


PuzzleFlow Database

Click Next to start the installation.

46


PuzzleFlow Database

That is it.The database has been installed. After the installation process, the PostgreSQL database is ready to use. You do not need to run any post-install programs or wizards.

Managing PostgreSQL

6.3.2

Usually, there is no need to access the database manually. All solutions based on PuzzleFlow™ (generation 4) take care about a database management, so most probably you will never need to manage the database yourself. However, basic knowledge about using the database becomes useful, if there is a need to backup the database, recreate it from scratch or perform any other administrative operations that are beyond the scope of PuzzleFlow™ responsibility.

47


PuzzleFlow Database If you need to access the database directly, you may use query browser application such as one shown below (PGAdmin application installed with PostgreSQL package).

The database can be also managed using PostgreSQL command prompt (for advanced users only). To create the database type createdb -U postgres pf (assuming postgres is a default username and pf is a database name you are going to create).

To remove the database type dropdb -U postgres postgres.

48


PuzzleFlow Database

Please keep in mind that any direct intrusion into the database is dangerous and may cause system misfunctions. PuzzleFlow™ comes with higher level interfaces that should be used for everyday database maintanance.

PostgreSQL ODBC

6.4

Using ODBC (Open Database Connectivity) is necessary for PuzzleFlow™ 3.x versions. PuzzleFlow™ 4 series communicates with databases natively, and does not utilize ODBC drivers at all. In this case you can simply skip this part.

Installing PostgreSQL ODBC Connector

6.4.1

Run PostgreSQL ODBC Connector installer package.

49


PuzzleFlow Database Accept the license agreement.

Choose database drivers location.

Click Install to start.

50


PuzzleFlow Database

51


PuzzleFlow Database

Click Finish to close the wizard.

6.4.2

PostgreSQL System Data Source Installing the database and drivers may not be enough. Your operating system needs to be properly configured to cooperate with PostgreSQL ODBC. Switch to Control Panel -> Administrative Tools -> Data sources (ODBC) -> System DSN.

Click Add to initialize a new System Data Source entry and select PostgreSQL Unicode driver.

52


PuzzleFlow Database

Click Finish to close the window. Now you need to provide some parameters that will be used by the system while connecting to the database.

Fill up the window according to the database installation presets. Most probably you'll choose localhost as the server, postgres and as the user. As the database, select the name of the newly created database storage created for PuzzleFlow™

53


PuzzleFlow Database

Click Test to check the connection.

PostgreSQL has been configured properly.

54


PuzzleFlow Database

PuzzleFlow 3.x Database Wizard

6.5

This section applies to PuzzleFlow™ series 3 only. In PuzzleFlow™ generation 4 there is no need to bother about the database connection. It is enough just to install the database and PuzzleFlow™ 4 installer will take care about the entire database creation and configuration. Database Wizard is a small application present in all the PuzzleFlow™ 3.x installations. It helps to establish a connection between PuzzleFlow™ and the already installed and initialized database store. Please be sure that PuzzleFlow™ Server is turned off while running the database configuration wizard. Otherwise, all your settings may be lost. Also make sure that the database service is running. Go to the PuzzleFlow™ installation directory, usually C:\Program files\ACCHSH\PuzzleFlow and run DBWizard.exe program. The same utility is launched during the PuzzleFlow™ installation process, if one initially enables the database support. Select the Extended database option and click Next.

As a database server engine, select MySQL or PostgreSQL. Click the Select Data Source button. In the database link properties window, select Microsoft OLE DB Provider for ODBC Drivers and click Next.

55


PuzzleFlow Database

Select the database source to be used by PuzzleFlow™. The list should contain at least the newly created database source.

Click Test Connection. If the connection has been established, click OK and come back to the previous window. Then click the Update registry button. If connection

56


PuzzleFlow Database problems occurs, most probably you need to fix data sources configuration in administrative tools control panel.

Now run PuzzleFlow™ Manager application and load any workflow queue to to setup the initial database structure. This is the final test if the connection has been established. If the workflow loads correctly, the PuzzleFlow™ system is ready to work with the database.

57


PuzzleFlow Database

58


HASP dongle

HASP dongle Protection

7 7.1

This part describes a HASP dongle actualization procedure. If you do not have a hardware protection dongle, you can skip this part. You can still use the software but it will work in a demo mode only. If you have a dongle already, please follow the activation procedure below. Even if you have received the dongle, all the software will work in demo mode until the dongle is activated.

In the demo mode output files are watermarked and encrypted, so they will not be processed correctly by the output devices. The licensed version of the software requires a hardware protection dongle (HASP). The dongle is to be plugged into the parallel (printer) or USB port of the machine running the software. Some applications allow you to work without the hardware dongle; they require on-line or telephone activation instead. It is also possible to use one dongle for many machines in the network. Please, contact ACCHSH support for details.

Dongle installation

7.2

All the ACCHSH software installers come with the HASP Device driver and HASP Programmer application. Both elements are installed automatically during the software installation process. Standard HASP device drivers proposed by Windows doesn't work correctly. If they were previously installed one may need to remove them manually, since the installator may not be able to overwrite them. While installing the software for the first time one should remember that the dongle device should be plugged-off during drivers installation and plugged-in just after. Then the operating system should inform about the new device installed. .

Choose the language for HASP installation procedure

59


HASP dongle

60

.

Accept license agreement to continue

.

Welcome splash is displayed, click Next to continue


HASP dongle

.

Install new drivers option should be selected. Click Next to start the installation.

.

Please wait while installing the HASP dongle drivers.

.

Installation is complete, when the following splash is displayed

61


HASP dongle

Just after the installation, the HASP Programmer application is available in ACCHSH folder in Start menu. After the installation, please plug-in the dongle and ensure that it has been spotted by the operating system. If you are using USB key, the system should response the dongle has been recognized and is ready to use. The dongle itself should have a red light turned on.

It may happen that the dongle is not responding, although the driver has been properly installed and the USB port works fine. If so, please try to plug it in once more or try another USB port. If it still does not work, you may try to restart the computer having the dongle pugged-in. Some machines may need low- level device initialization.

7.3

Dongle activation To make an activation the dongle must be plugged-in. The activation also requires an internet connection. Before starting the activation process, please ensure that there is a stable internet connection. Be aware that firewalls and other software of that type may silently block an access to the internet. Please switch them off temporarily or configure them in the way that HASP Programmer have an access to the internet through HTTP protocol. After that, please, run the HASP Programmer application. The following window is displayed.

62


HASP dongle

Click Update dongle button to activate the dongle. The application sends a unique key identifier to puzzleflow.com. This identifier is verified on our site and the current dongle configuration is sent back to the dongle. If the operation is successfully completed, the following window is displayed:

If you see this message, you can turn off the application and start working with the software. The dongle is ready to use. If some problems occur, please read troubleshooting section below.

63


HASP dongle

7.4

Quick Troubleshoot It your dongle does not work properly, follow the instructions below: 1. Make sure that the dongle is plugged-in. 2. Make sure that only one ACCHSH dongle is plugged-in at once. 3. Make sure that the dongle is recognized by the system. If not, check if the HASP driver has been properly installed and the USB port is responding. You may need to change USB port or reboot the machine. 4. Make sure that the functionality you are going to use is licensed. 5. Make sure that the dongle is up-to-date. If not, update the dongle with HASP Programmer. 6. If there are problems during dongle actualization, please make sure that there is an internet connection and that HASP Programmer is not blocked by any firewalls. If the dongle still not work properly, please contact on-line support. The ServicePack 2 actualization for Windows XP may cause that HASP dongle doesn't work properly and the operating system can't find the proper driver. The simplest way to solve the problem is to download and install the newer versions of ACCHSH Software. You can also download and install the newest HASP driver from http://www.aladdin.com.

7.5

Online support To contact with ACCHSH on-line support, please send an e-mail to support@puzzleflow.com. To get the quick response, provide your company name, dongle number and description of the problem. If the problem is connected with the HASP dongle, please attach *.hshinf file. The file is generated by HASP Programmer after clicking Get info button. If you have a valid dongle, you do not have to write e-mails each time you want to download new software versions, documentation or other resources. Just run HASP Programmer (having the dongle plugged-in) and click On-line support button. Your default internet browser runs and connects you to the Customer

64


HASP dongle Zone. Here you can verify basic dongle information and download available resources. Displayed dongle label and pass key can be reused while visiting http://extranet.puzzleflow.com.

65


HASP dongle

66


Reference Guide

Reference Guide Workspace

8 8.1

The whole WebPairer window area is splited into four parts: . . . .

menu bar – contains hot links to command which can be executed from current workstate location bar – shows location in system menu structure, contains hot links to higher levels context menu – contains hot links to actions related with current workstate and main window which contains all editable system parameters.

Work with WebPairer

8.2

Login

8.2.1

WebPairer requires user authentication. In this version only one user is supported. Default username: wp Default user's password: (empty) There is no password for default user.

Configuration template

8.2.2

Main document of WebPairer is called Configuration template. It contains all data necessary for processing job.

67


Reference Guide Configuration templates can be managed via configuration loader, which gives ability for loading, creating and removing templates. All information in template is splitted into four section: base information, filename pattern decoding, task configuration and deadline settings.

Base information This section contains base information about job and it's configuration such as name, file location, number of pages etc. Here is description of used parameters: . . . . . .

configuration name – text which identifies this job configuration short name – name of the folder for job described by this configuration, must be compatible with Windows naming convention number of pages – number of pages included in final document description – additional text information about this configuration which is not processed in pairing system and is used only for user convenience preview generation – indicate if pages' preview will be generated and what will be it's resolution final page size – nett size (trim box) of input pages

Aside from configuration simple parameters base information panel allows for definition of global properties. Global property is a kind of variable that can have simple value or can be evaluated from given expression.

Global properties are helpful while defining rules (see task configuration). In example CHECK_LEVEL property is defined and will be used in selecting suitable Preflight configuration file. Other two properties (PAGECOUNT and JOBNAME) are default variables created from base informations. Global properties can be modified just before submitting the job, so you don't need to reconfigure template to change this values.

Filename pattern Some information such as page number, date etc. are passed to the WebPairer in the name of input file. In this section user define the transformation from file name to set of variables which will be used in pairing process.

68


Reference Guide For processing variables is used environment, which allows for defining variables and evaluating expressions. Example file name is '0107wap1' and stores page number ('01'), month of publication('07') and region ('wa'). File name is stored in FILENAME variable in all environments. At first you must specify definition of obligatory variable PAGENO (page number) which is used in whole pairing process. You can specify variable definition by selecting it's position in filename (start index and length – ex. Start: 1 and length: 2 gives '01'). You can select start position and length by clicking on index bar placed under filename or by typing values directly in variable definition window.

After simple variables definition you can define extended variables, which don't need to be based on filename. Variable RID is the example of extended variable definition: ${REGION}${FILENAME.SubStr(7,1)} Value of this expression is a concatenation of value of variable REGION and value of substring of variable FILENAME starting from 7 and length 1. For more details about expressions see Appendix.

Task configuration Whole pairing process is divided on four stages:

69


Reference Guide . . . .

page acceptation process – decides which incoming pages are to be accepted preimposition tasks – sequence of task that are performed before imposition imposition – uppermost task of pairing process postimposition tasks – sequence of task that are performed after imposition

In this section of configuration template user define how input pages will be processed by WebPairer by selecting which task will be performed. Task list configuration In process configuration panel you can specify which task are to be performed in with stage. Each stage has own subset of tasks (like Preflight, InkExaminer, PageResize etc.) which can be added.

Above is an example of configuration of post-imposition task list. All of this task will be performed in given order after imposition stage. Single task configuration All selected tasks have to be configured by selecting configuration file. For preand post imposition tasks configuration files can be prepared with PuzzleFlow™ Workflow Editor by selection processing puzzle, setting parameters and than saving configuration (for more details see PuzzleFlow™ Workflow Editor documentation). Imposition process is configured by selecting a imposition signature file. It can be prepared with Signature Designer. WebPairer allows to use many configuration files for one task. Which of them will be used depends on task's ruleset.

70


Reference Guide In example CHECK_LEVEL variable is used to decide which configuration file is to be selected. Each rule task's rule set is 'simple' rule, thats mean it has format: [variable] [operator] [value]. (ex. CHECK_LEVEL == 1) User interface helps in defining simple rules. Extended rules has to be typed manually, they are environment expressions. More about environment you can find in Appendix 1. Page acceptation rules Page acceptation process is configured directly for WebPairer's user interface. Configuration is based on acceptation rules which makes a rulset. If incoming page matches some rule an action defined in the rule is applied. For page accept process three types of action are defined: . . .

accept – incoming page will be processed by system hold – incoming page will be processed by system, but user approval is required reject – incoming page will be rejected

Page matches the rule when all of rule's conditions are met. If there is no suited rule in the ruleset, default action is applied. If page matches more than one rule, first (most top) of suited rules is used.

Deadline configuration WebPairer allows to define deadlines. Deadline is a moment before which processing must be completed. Deadline is used for job monitoring and user notification about job delay. There is a possibility to define different deadlines for different pages.

71


Reference Guide

Deadlines can be defined manually by giving rule set or with deadline timetable.

8.2.3

Job tracking WebPairer job management is responsible for running new jobs and monitoring active jobs.

Running new job To run new jobs a couple of actions must be performed. First of them is selecting job configuration (configuration template) or defining new one. Next redefining some global variables (for example deadline or CHECK_LEVEL) and preparing working directory for job by cleaning old files.

Directory structure Input pages can be submitted to processing through user interface or directly to working directory. Every job has own working directory, which name is defined by short name in base information section of configuration template. Main directory of the job is placed in: [PuzzleFlow ROOT]/WebPairer/data/[short_name]. Main directory contains: . . . . . .

./input – directory for incoming pages ./output – directory for final documents ./pre – output directory of preimposition and input for imposition ./imp – output directory of imposition, input for postimposition ./preview/input – input directory for preview generation ./preview – contains generated page thumbnails

Additionally input, pre, imp and output have an arch subdirectory which is an archive for respective process.

72


Reference Guide

Job manager Job manager allows for starting, stopping and killing active jobs. It also can redirect to given job monitor.

Single job monitor Pairing is divided on three separate processes: pre imposition, imposition and post imposition. Also job monitoring uses this division. Each job monitor is divided in 5 panels: 1. 2. 3. 4. 5.

Pre-imposition monitor Imposition monitor Post-imposition monitor Statistics monitor Deadline monitor

Each stage (pre-, post-, imposition) monitor has the same structure.

Single job stage monitor Stage monitor is showing the state of pages that are precessed in given stage. State of page processing is indicated by color of icon or can be observed in previews view (if preview generation is enabled – see Base template information).

Each page from pre-imposition task monitor has default action 'Upload file' (actions and page info is available after clicking on page icon) which can be used to insert (or replace) given page file. Page uploading is described in Page source upload section. Each page has a set of available actions, which depend on the state of selected page. Action

Description

Available in states

73


Reference Guide Show report Shows report of page processing Show output preview Shows processed page preview Resume job Upload file

Resumes job after holding Uploads page source

All expect unknown completed (when previews are available) holded In pre-imposition stage

Source and destination file are available by clicking on file name link. Page source upload For file uploading you must select the file and set it's name (which will be used in pairing process). By default characters used by page number are overwrote in file name, but you can type file name manually or live it as in original. In example uploaded file has name '3507wap1' and is changes automatically to '2107wap1.pdf' because it's going to be uploaded for page 21.

Job statistics WebPairer supports job statistics for particular tasks.

Two statistics for input pages and for output pages allows to check work efficiency.

Deadline monitor Also WebPairer supports deadline monitor for showing time limitations defined by user.

74


Reference Guide

Deadline monitor shows the current time (green column), default deadline (orange column) and page deadlines. If page exceeds it's deadline color of page number label is changed to red.

75


Reference Guide

76


Environment

Environment

9

PuzzleFlow™ offers a number of variables you can use to define pathnames, template names, job identifiers, and many other features of jobs and resources used by the PuzzleFlow™ system. The implemented operators and functions (also called methods) provide an easy way to handle various data types and reuse them in many different ways.

Variables

9.1

A Variable is a special string, which is substituted with its value in the runtime. The typical usage of the PuzzleFlow™ environment refers to common paths and template names. However, many other data, such as the time and the date, the user id, the workflow id or the job id, may be stored in the environment as well, and retrieved anytime it is needed. PuzzleFlow™ also allows the users to extend the standard environment with their own variables.

Scalar variables

9.1.1

Formally speaking, variables can be of a scalar type (any singular value) or of a array type (a list of values). For sake of simplicity, we use the term variable as a synonym for the named scalar value, while the array is a variable of the array type. This section describes formal aspects of scalar variables – the most commonly used type. The PuzzleFlow™ environment variables require a special syntax. The calling variable starts with a $ character followed by the variable name wrapped in braces. In the example, invoking the variable named FOO should be expressed as ${FOO}. Any other string which does not match this syntax returns itself (just a string) and will not be considered as a reference to the variable value. In the following example the variable ROOT contains the string C:\PuzzleFlow and the variable WORKFLOW contains the string Imposition. A path expression containing two variables: ${ROOT}\Special\Input-${WORKFLOW} The same string after resolving the used variables: C:\PuzzleFlow\Special\Input-Imposition As you will see in following sections, the syntax shown above is used for any kind of the environment expressions, not only for variables. Single variables are the

77


Environment simplest and the most commonly used type of the environment expression, so ${...} syntax can be associated with single variables.

78


Environment

Although PuzzleFlow™ ignores the case of all characters, it may be convenient to keep a reasonable case convention. In general, The PuzzleFlow™ variables are uppercase. The Names the of functions are mixed case. This convention allows to distinguish variables and methods in the more complex environment expressions. There are four major categories of variables in PuzzleFlow™ . . . .

global variables – set of variables which are always visible workflow variables – variables assigned to workflows puzzle variables – variables assigned to modules (puzzles) job variables – variables assigned to processed jobs

Actually there is one more variable category. Some puzzles use additional variables for the processed tasks only. These variables are not inherited at all and are invisible at any other stage of job processing. Therefore, we call them private variables. This category do not respect any of the inheritance and covering rules and therefore, it is not treated as a major category. Each variable value represents one of the following data type: . . . . .

integer type – integer number (positive or negative) string type – any kind of string of characters date type – data type used for date expressions path type – string which is a valid path or filename boolean type – logical true or false

In many cases one data type can be converted into each other. You do not have to worry about conversion since the methods do that automatically whenever it is possible. However, in some complex cases you have to make this conversion yourself using the available functions. Such conversions are described in the following sections. At this stage just remember that each variable represents one specified data type.

79


Environment

9.1.2

Global variables The global variables allow you to use your workflows on different workstations. For example, imagine that you have two workstations running PuzzleFlow™. The first one is called OPI and uses two hard drives – C: and D:. The second one is named IMPOSITION, and it has just a single drive C:. Both of them are set up to use the PuzzleFlow™ root folder called PuzzleFlow, but these folders are located on different partitions on each machine. The PuzzleFlow™ root folder is placed on the drive D: on OPI workstation, while IMPOSITION workstation has the root folder located on the drive C:. If there were no variables used in PuzzleFlow™, the workflow designed for the first machine would not work properly on the other one, due to the lack of the unified disk structure. To reuse the workflow from one machine on the other, you would have to change each path to start with C:. Fortunately, when you design your workflow you can use variables which point to the major folders of the PuzzleFlow™. Both machines use variable INP pointing directory where HotFolders are located: . .

At OPI the variable INP is set to D:\PuzzleFlow\Inputs At IMPOSITION the variable INP is set to C:\PuzzleFlow\Inputs

Knowing this, you can set your HotFolder plugin i.e. to use the directory ${INP}\My_Workflow which is valid on both machines. Thanks to the variables, PuzzleFlow™ system is flexible as much as possible. Another nice feature is that you do not have to worry about using numerous variables each time you select or type a folder or a file path. PuzzleFlow™ tracks your moves and uses the matching variable, if only there is one that matches the path just selected.

The PuzzleFlow™ environment could be used as a part of a global system environment. In the example, if INP variable already exists in the system environment, there is no need to define the same in the PuzzleFlow™ environment. If a variable is not defined in PuzzleFlow™, it will be taken from the system environment anyway. If a variable is defined in both PuzzleFlow™ the global system environment, PuzzleFlow™ has a priority. The general scoping rules (covering and inheritance) are described in the following sections.

80


Environment PuzzleFlow™ uses six main global variables: ROOT, CONF, RES, ARCH, INP, and OUT. Additional three are REPORTS, TEMP (synonym to TMP), and DATE. You can see and modify the locations they point to, the meaning values they refer to with the both Manager and Editor preferences dialog box. PuzzleFlow™ system preferences are also available in control panel. ROOT The path to the root folder of PuzzleFlow™. Preferably, all the folders described below should be subfolders of the ROOT, although you can configure them in any way you want. CONF The path to the folder that contains the configuration represented by *.pzl files (workflows). This variable is used mostly by Editor and Manager to store and load workflows. Of course, you can store your workflows anywhere you want, but keeping them in ${CONF} and its subfolders speeds up searching, because both Editor and Manager start browsing there. The default value is ${ROOT}\Workflows. RES The path to the folder containing the PuzzleFlow™ resources. ${RES} is the folder where you can place images for OPI, imposition signatures, personalization layers, and any other resources used with your workflow. The default value is ${ROOT}\Resources. ARCH The ${ARCH} folder is a default location for the files dropped by the Archive puzzle. Since Archive can create folders, it is not obligatory to use the ARCH variable. You can use the absolute path as well. However, it may help keeping consistency of the PuzzleFlow™ system.The default value is ${ROOT}\Archives. REPORTS The ${REPORTS} folder is a default location for the processing reports dumped in the runtime. You may want to use the ${ARCH} folder for that purpose as well. By default, the value of the REPORTS variable is set to ${ARCH}\Reports. Allthe processing reports are always stored in the PuzzleFlow™ database. If the REPORTS variable is defined, reports are also saved on the disk

81


Environment

as XML files in the ${REPORTS} folder. You can simply remove the REPORTS variable to disable the saving reports on the disk. INP The path to the folder containing HotFolders. ${INP} should be considered as a root folder for all the input folders of the existing workflows or as a HotFolder itself.The INP variable is initiated to ${ROOT}\Inputs. OUT The path to the folder containing OutFolders. ${OUT} The folder should be considered as a root folder for all the OutFolders of the existing workflows or as an OutFolder itself. OUT variable is initiated to ${ROOT}\Outputs. PSI Path used by native ACCHSH Postscript to PDF converter as a working directory. ${PSI} is the default directory used by Normalizer module looking for external resources (ie. prologue.ps, epilogue.ps files). See also PROLOGUE and EPILOGUE module-related variables. TEMP The path to the folder for temporary files. The TEMP variable is also called TMP. TEMP is initiated to ${ROOT}\Temp. Note that the variables with the same names are defined in the global Windows environment. According to the scoping rules described in the following sections, the variable from PuzzleFlow™ has a priority. DATE As you may expect, the DATE variable does not have a predefined value. Its value is assigned dynamically whenever the variable is used.

In the previous versions of PuzzleFlow™ TIME and DATE variables were synonyms and contained a string formatted as yyyy-mm-dd_hh-mmss. The TIME variable is no longer valid – it returns an empty string, just as any other undefined variable. However, there are methods named Time and Date which are described in details in the following sections.

82


Environment

The DATE variable is system dependent. The returned value may differ depending on the version and regional settings of your operating system. The ${DATE} expression may be evaluated to a string which contains colons and other characters which are not allowed in the path names. Therefore, DATE, and all the other date-related variables as SPOTTIME or MODIFYTIME, should not be used alone in the file name templates. The current version of PuzzleFlow™ provides date functions to be used to convert the date string into a valid path or file name strings. TRUE Contains logical true that can be used in conditions. Boolean true can be expressed as a string TRUE (case-insensitive) or an integer number other than zero. FALSE Contains logical false that can be used in conditions. Boolean false can be represented by a string FALSE (case-insentisive) or number zero. The way of representing boolean values by strings differs depending on the PuzzleFlow™ version. PuzzleFlow™ series 3 considers true as string TRUE (regardless of the letter case) or non-zero integer number.The earlier versions considered true as everythig except the number 0 and an empty string. The old behaviour has been changed because of its ambiguosity, since values like FALSE were considered as logical true, as any other non-empty string.

Workflow variables

9.1.3

This group of variables is assigned to workflows. WORKFLOW This variable refers to the name of the current workflow. AUTHOR This variable refers to the author of the current workflow. Whenever you design a new workflow, you can open the Workflow properties dialog box to specify both WORKFLOW and AUTHOR variables.

83


Environment USER This variable refers to the current user name (name of the user running workflow). WID This unique workflow identifier represented by an integer number or a string. Each workflow loaded on the server has its own WID identifier.

While designing a workflow in the PuzzleFlow™ Editor you can add your own workflow variables using Variables property tab in the Workflow properties dialog box.

9.1.4

Puzzle variables This group of variables is assigned to the puzzles in the processed workflow.

In analogy to workflow variables, you can specify your own variables for each puzzle in the workflow. The configuration dialog box of each puzzle contains Variables property tab for your own extensions to the standard environment. The property tab is available after clicking More options button in the bottom of the module configuration window. PUZZLE This variable simply refers to the name of the puzzle you use. You can specify the name of each puzzle using the Common property tab in the module configuration dialog box. PID The unique puzzle identified represented by an integer number or a string. Each puzzle used in the workflow has its own PID identifier.

Actually only PUZZLE and PID variables are always present. However, some puzzles use some additional variables depending on the function of a module. There are also two special variables which can be used to control the processing in runtime.

84


Environment SKIP A special variable that is checked just before each step of processing (each module of the workflow). If, at the moment of checking, the variable returns true (boolean true or non-zero number), PuzzleFlow™ will skip this module and pass the job to the following steps. In such a case, the report of the processing contains the information that the specified module has been skipped. HOLD A special variable that is checked just after each step of processing (each module of the workflow). If, at the moment of checking, the variable returns the value true (boolean true or non-zero number), PuzzleFlow™ will hold the job and wait for the user decision. In such a case, there is the information in the report that the job has been held at the specified step of the workflow.

Variables SKIP and HOLD can be defined anywhere, not only in the puzzles configuration. In example, specifying HOLD variable as true in general, properties of the workflow will cause to hold the job at each stage of the workflow. However, much bettter way to control every step of processing is to switch PuzzleFlow™ Manager to stand-by mode. SKIP_PAGE In case of the modules that operate on pages, rather than entire document (ie. BarCode) one can use a SKIP_PAGE variable. The value is evaluated for each page of the processed document and if true, the page modification is skipped. LAST_RESULT Each module sets this variable at the end of processing. The value is one of the strings: . . .

SUCCESS – when the job was successfully processed in the puzzle FAILURE – when the processing failed on the puzzle SKIPPED – when the processing has been skipped

The variable can be used for outputting custom messages and sending e-mails via PuzzleFlow™.

85


Environment LAST_PUZZLE The variable contains the name of the last puzzle that sets LAST_RESULT variable. The LAST_RESULT and LAST_PUZZLE variables are especially useful while using Mailer Module. You can use Mailer as the last Puzzle in the workflow and send a message of the content Status: ${FILE} ${LAST_RESULT} at ${LAST_PUZZLE}. In the example, if there was an error on the PreflightCheck, the expression will be expanded to the Status: file.pdf FAILURE at PreflightCheck. AUTO_REPLAY The variable can be used in the HotFolder environment configuration (or globally for the entire workflow config). If the value is set to true and the production is based on job ticket, the entire imposition process defined in the workflow chain is automatically repeated on every change of the referred page list. Whenever a source subdocument is overwritten or modified, a relevant imposition sheet containing this page is repeated.

The setting AUTO_REPLAY variable makes no sense, if the job ticket is removed from the input folder after finishing the production. PuzzleFlow™ will replay this job and stop waiting for the already deleted job ticket file. Once the file has been posted again, PuzzleFlow™ will resume and finish the job.

This function applies not only to the jobs already made and changed. Also the jobs holded on PreflightCheck, HotFolder filter or HOLD variables will be automatically resumed. Please, note that every workflow queue may have its own AUTO_REPLAY variable defined in the HotFolder Module environment configuration. AUTO_REPLAY_DELAY If set, the number it stores is the time (in seconds) of a delay between recognizing the change of some subdocument and applying auto-replay. This prevents from repeating the production after every single modification, if there are plenty of them and the replay should take place after all replacements.

86


Environment MESSAGE The content of this variable is written to the progress info in the runtime. Using MESSAGE you can customize the processing log or check the values of the used environment variables.The MESSAGE variable is evaluated at the beginning of the running module (the synonym is BEGIN_MESSAGE). END_MESSAGE Works like MESSAGE variable, but evaluation and adding its content to progress information is performed at the end of running the module.

There is a special trick which applies to the MESSAGE and END_MESSAGE variables. If you need a lot of messages, you can create variables named MESSAGE1, MESSAGE2, ..., or MESSAGE_i, MESSAGE_ii etc. All of them will be resolved and placed in the progress info. In other words, these particular variables work like association tables rather than normal variables. PAGENO This variable is used by JobSplitter Module to count the subsequent pages of a document being split. The custom environment expression that states for the splitting rule is supposed to use the PAGENO variable. The variable is also available for other modules dealing with subsequent pages, such as BarCode. EIGENVALUE The variable is a result of the custom environment expression used by JobSplitter. The value can be used in the output filename template. PART This variable is used by JobSplitter Module to count the subsequent groups of the split pages PART not necessarily refers to the page number since JobSplitter can split either subsequent pages (composite or separated) or groups of pages, in the consecutive or non-consecutive way. Hence,the PART variable can be used inside the expression describing the naming convention of splitted files, but not inside the expression determining the way of splitting. PAGENOHIGH The variable is used by JobSplitter to save the highest page number within the split page group.

87


Environment SEPARATION The variable is setup by JobSplitter Module while handling separated documents. It contains the separation name of the physical page being processed. LABEL This variable is used by JobSplitter to mark the subsequent pages or the split separations. Using the LABEL variable makes sense only if the processed job contains the defined page labels. In the example, after using the separation module, each page is labelled with its colorant name. However, in many other cases the labels may be undefined, and then the ${LABEL} expression returns just an empty string.

The separated documents usually come with the labels containing the subsequent separation names. Note ,however, that the label name may contain the characters not usable in the filenames (such as colon). Hence, while processing the separated documents, it is recommended to use the ${SEPARATION} variable instead.

PART and LABEL are used by PageSplitter only, but they belong to the puzzle variables category, not to the private category. This is because the PART and LABEL variables are exported (copied) to the job environment, so they respect the general scoping rules.

Some puzzles offers variables to be used with an alternative syntax. In the example, #P, #L, #D, #J are abbreviations for ${PART}, ${LABEL}, ${DATE} and ${JID} expressions respectively. This simplified syntax can be used together with the standard environment expressions. The expression #P is just an abbreviation for ${PART}. The expression #3P is an abbreviation for ${PART.Fixed(3)}, or ${PART.Fixed(3).Replace("0","_")}, depending on the data type of the variable.

88


Environment

A string $$ can be used to achieve the single $ character. In analogy, ## produce the single #. VERNO This variable belongs to OutputFolder Module. By default, before writing the processed job to the file, an output folder is inspected in order to avoid replacing the files that already exist. If there is such a conflict and OutputFolder is configured to use the unique names, the module generates a unique suffix for each job (i.e. file.pdf, file_1.pdf, file_2.pdf etc.). The number of the generated unique name is stored in the VERNO variable.

Note that the variable will not be set if the overwriting output files is enabled. VERSTR Like the VERNO, the VERSTR variable refers to OutputFolder and the unique name templates. If there is a filename conflict, a value of the VERSTR variable is added at the end of a template to avoid replacing the existing files. Adding the VERSTR suffix is performed only if the unique names option is enabled. Otherwise, VERSTR returns an empty value. By default,the VERSTR variable works as if you set its value to the expression: ${VERNO=0 ? "" : "_"+VERNO}. So, if there is no filename conflict (VERNO is equal to 0), the VERSTR becomes an empty value. Otherwise, the VERSTR contains concatenation of the underscore character and the unique name number. The number is stored in the VERNO variable. Both the VERNO and VERSTR variables can be modified in the Environment property tab. It is worthy to note that the VERSTR variable should always contain VERNO. Otherwise, it will not produce the unique name. By default, VERSTR is used as a suffix – it is added at the end of the file name. You can change this behavior using your own output file name template, which contains the VERSTR (or VERNO) variable.

89


Environment QUERY This variable is used by Resource and HttpResource Modules. If any processing module is configured dynamically in the runtime via Resource Module, QUERY stores the content provided in the Common property tab. In the simplest case it is just a file path and name. INDEX This variable is used by Archive Module to numerate the dumped files. Each dumped file increases INDEX value by 1. QUERY and INDEX are typical private variables. They are local for one specified puzzle (Archive or Resource), and are not available from any other environment level. These variables do not respect the general scoping rules. MIME The Variable containing the MIME type of the file being dumped by Archive Module. EXT2 The variable containing the file extension of the MIME type being dumped by Archive Module. This variable should be used instead of the EXT variable in case of bitmap previews generation, JDF runlist creation and every other action that uses Archive Module to save the non-PDF output. FONT_CAP The FONT_CAP variable can be used in Imposition Module environment to provide the full name of Type1 or TrueType font to be used in caption marks defined in the imposition signature. If not specified, Courier will be used. If specified, the module needs a resource search. FONT_CB FONT_CB works like FONT_CAP except that the font specified is used for color bar notes. PROLOGUE Once defined, the variable is used by ACCHSH native Normalizer Module to look for a prologue file (assuming using the prologue and epilogue option is enabled). The default location of the prologue file is ${PSI}\prologue.ps.

90


Environment EPILOGUE Once defined, the variable is used by ACCHSH native Normalizer Module to look for epilogue file (assuming using the prologue and epilogue option is enabled). The default location of the epilogue file is ${PSI}\epilogue.ps.

Job variables

9.1.5

The job variables are attached to every processed job. They are particulary useful while creating filename templates for the stored files. The job variables also allow storing some data in the job file and reuse them when the jobs are processed in another workflow. NAME Refers to the name of the job, without a file extension. The name of the job does not necessarily mean the name of the job file. Some engines replace an original name with the one given by the name template (i.e. PageSplitter works this way). So NAME variable refers to the output job name. EXT The extension of the job file. It does not have to be an extension of the file you put into HotFolder. ${EXT} is an extension of the file that was created by PuzzleFlow™. These extensions might be different, because some puzzles (i.e. Normalizer or Downsampler) change the extension as they convert document types. In other words, EXT refers to the final job file extension. FILE Refers to the whole filename of the output job. FILE should be considered as an abbreviation for the expression that combine the NAME and EXT variables into one string. So ${FILE} simply means ${NAME}.${EXT}. PATH Refers to an indirect path to the job excluding the root of the input folders and the filename. As said before, all the paths in PuzzleFlow™ system finally refers to the ROOT location. Not surprisingly, a path returned by the PATH variable is also relative and should be considered as the whole substring between ${INP} and ${FILE} substrings of the complete path string. It is worthy to note that the PATH variable is also defined in the global Windows environment. According to the scoping rules, the variable from PuzzleFlow™ environment has a priority.

91


Environment

PATH variable is also defined in the global system environment. MODIFYTIME Contains the time of the last modification of the current source file. MODIFYTIME, as other date-related variables, should not be used in the file name templates alone. It should be used with date functions.

MODIFYTIME variable is available only because of compatibility reasons. It is recommended to use the Mtime method instead. SPOTTIME Refers to the moment when the job was spotted by the PuzzleFlow™ system. SPOTTIME, as other date-related variables, returns a value which may contain characters not allowed in the path or file names. Therefore, it should not be used alone in the file name templates. It was designed to work with the date functions. SOURCE Refers to the absolute path to the main file of the job. When processed the job consists of more than one file, the main file is the one that contains a job ticket. It can be ajob ticket file, ora standalone PDF document. As you probably expect, in typical situations ${SOURCE} is an abbreviation for ${INP}${PATH}${NAME}.${EXT} expressions. However, the NAME and EXT variables refer to the final values, while SOURCE refers to initial one, so it works only if the filename is not changed during processing. Moreover, the SOURCE variable should not be used standalone. It was designed to be handled by the path functions such as File, Ext, or Mtime. DESTINATION In analogy to the SOURCE variable, DESTINATION refers to complete path to the job after processing. The best way to understand the relations between the variables that refer to some parts of the complete path of the input and output jobs, is to consider the following example. Assume that the complete job file location stored in the SOURCE variable is C:\PuzzleFlow\Inputs\Imposition\4up\MyFile.pdf,

92


Environment and that complete output location (DESTINATION) is C:\PuzzleFlow\Outputs\MyFile.pdf. If the ROOT location is C:\PuzzleFlow, and the INP (HotFolder location) is set to ${ROOT}\Inputs then the ${PATH} expression returns Imposition\4up, ${FILE} expression returns MyFile.pdf, while ${NAME}, ${EXT}, and ${FILE} contains MyFile, pdf, and MyFile.pdf respectively. Note that in this example we assume that running workflow does not change the filename of the final job. If the current workflow changes filenames of the input jobs, then the NAME, EXT, and FILE variables returns different values. JID Refers to the global job identifier. JID is a number assigned to each job when it is spotted by the PuzzleFlow™ server. It is guaranteed to be unique in a single server. You can use it for job numbering. Identifiers of the following jobs typically differ by more than one. JVID This variable stores the information how may times the current job has been replayed. It can be especially useful if job files are processed several times. The JVID variable can used in the output file name template to inform how many times the user has used a Replay function. HOTFOLDER Refers to the name of HotFolder that has spotted the job.The HOTFOLDER variable value can be set using the Common property tab in the HotFolder Module configuration dialog box.

PuzzleFlow™ allows the user to define their own variables. Those are stored in the environment or embedded in the documents for future reuse. The embedded variables property tab in the OutFolder dialog box allows setting the user environment which will by copied into the output jobs and may be retrieved while processing these jobs in another workflow or another queue of the same workflow.

93


Environment

The PuzzleFlow™ RunList application allows to specify the job environment even before sending the job to the final workflow. The user-defined variables are stored in the created job ticket file. As all other job variables, they are visible at each step of processing.

9.1.6

Scoping rules As said at the beginning of this section, there are the four main categories of the PuzzleFlow™ environment variables; global variables, variables assigned to workflows, variables assigned to puzzles, and job variables. You may wonder what will happen, if two variables which belongs to different categories have the same name, but the different value. In the example, imagine that before the installation of the PuzzleFlow™ system you have defined the variable ARCH in the global system environment. PuzzleFlow™ uses its own global ARCH variable. The processed workflow may also have the variable ARCH with a different value. The question is which value will be taken while evaluating expression ${ARCH}? Each variable category can be considered as a local (nested) environment. The general rule is that each variable defined in the local environment covers the variable of the same name defined in the global environment. In the example above,the The ARCH variable defined for the current workflow covers all others ARCH variables. The ARCH variable specified globally in the PuzzleFlow™ environment covers the ARCH variable specified in the global Windows environment. On the other hand, an inheritance (propagation) of variables starts from the most global environment. All the variables defined in the upper-level environment and not defined in the local ones, are exported to the nested environments. In the example, if there were no ARCH variable defined for the current workflow, the ARCH value would be taken from the global PuzzleFlow™ environment. If there were no ARCH variable specified in PuzzleFlow™, the value would be taken from the global Windows environment.

The most general rule is that locality of an environment, which can be also called variables category, determines the order of covering and the inheritance. According to the rules described above, the resolving variables start from the most local category. The locality of categories is fixed:

94


Environment . . . . .

job variables puzzle variables workflow variables global PuzzleFlow™ environment global system environment

In most cases you do not have to worry about locality, inheritance, and covering, since the resolving variables mechanism is fully automated. However, in some more complex environment expressions, you may want to force your own resolving manners. In the example, you may want to use the global ARCH variable, regardless of its values defined in other categories. You can make it using name spaces. A name space is kind of special variable, which points to a category which should be used to resolve the variable meaning. . . . .

SYSTEM – name space of global system variables GLOBAL – name space of global PuzzleFlow™ variables WKF – name space of workflow variables PZL – name space of puzzle variable

Note that there is no JOB name space. There is no need to specify the JOB name space, since the job environment always covers all others. Each used variable will be taken from the job category, if such a variable is defined in the local job environment. If the variable FOO is defined in several categories, then ${GLOBAL.FOO} points to the global value, ${WKF.FOO} points to the value defined for the workflow, and ${PZL.FOO} points to the value defined for the single puzzle. If there is just ${FOO}, PuzzleFlow™ search for such a variable in the subsequent environments starting from the most local (job variables) and takes the first encountered definition of the NAME variable. You can define your own local environments. Using the Variables property tab in the single module or the workflow configuration dialog box, or in the PuzzleFlow™ system preferences. Each such an environment becomes a namespace for its variables. Strictly speaking, each namespace is a named handle for the local environment. Each environment may contain variables and other environments. Thus, the entire environment can be imagined as a tree structure. In this tree, variables are leaves while local environments are branches, that may contain either leaves or other branches.

95


Environment

9.1.7

Array variables The PuzzleFlow™ environment supports an array data structure. The array is just a numbered list of the values (variables) of a given type. One array may contain many elements ofa different data type. We have already mentioned thatthe variable can be considered as a named container for some value. The arrays are also containers, but for many values at once. If we need to use a variable value in the environment expression, we just use its name. To get the value of a given array element, we use the array name followed by the unique integer number called index or key. Each index is a unique identifier of a given array element.

There is a slight difference between list and array. A list is just data structure, while an array is a named (defined) list of values. In practise however, those terms can be used reversibly. As you may expect, a list has a special syntax. It is expressed as a commaseparated list of values wrapped in [ and ] characters. To get the value of the specified element of the array, we use the array name followed by the index of this element wrapped in ( and ). ${[0,1,2]} is a list that contains three integer numbers. ${[0,'a',2,True]} is a list that contains four elements of various types. ${ARR(0)} returns the first element of the array named ARR, ${ARR(1)}, ${ARR(2)} return the second and the third element respectively. PAGES The current version of PuzzleFlow™ supports an array called PAGES. The array is available while imposing the document and you can use it in the signature template. The array contains page numbers included in the plate being imposed. The expression that included the PAGES array can be used in the imposition templates configuration for generating dynamic text captions or plate labels. For 16-pages document imposed as 2×1 booklet, an expression ${PAGES.Format('-',2)} is evaluated to 16-01 for the first plate, 02-15 for the second, 14-03 for the third, up to 08-09 for the last one. See Array functions section for more examples.

96


Environment

PAGES array is available only in runtime of imposing the document. You can save the information of the pages imposed on each plate using custom plate labels in the signature configuration. Labels can be retrieved from each page on further steps of processing. SUBDOC While working with the documents represented by a job ticket runlist,the SUBDOC array collects all the environments of singular subdocuments referred by the job ticket. Having this, one can retrieve some vital information about the source documents, even after the imposition step, when single input PDF pages no longer exist. To use the information available in the SUBDOC environment, one may need to store this environment into a document using variables embedding option in OutputFolder module configuration. This is because the subenvironment is accessible at the very last step of processing, that is, while writing the data to a file (one may check that with END_MESSAGE variable). Depending on the usage context, The SUBDOC object can be accessible as a property of the DOC environment.

Objects

9.1.8

As mentioned in the previous sections, namespaces represent various levels of the environment structure. Each environment name prefixed with the namespace is called a subenvironment, or simply an object. In general, an objects could be considered as any other variables in the environment. However, objects are usually followed by something (dot operator and a method) that operate on it. Objects should not be used alone. While the variables are simple data containers accessible directly,the objects are such containers but ofa higher level. DOC.INFO Some processing modules o fthe PuzzleFlow™ system, such as PreflightCheck, ToolBox and Personalizer, create the DOC environment, with thesubenvironment called DOC.INFO. The environment consists of vital information about the job being processed. One can retrieve the information using the following expressions: . .

${DOC.INFO.Title} – document title ${DOC.INFO.Author} – document author

97


Environment . . . . . . . . . . .

${DOC.INFO.Creator} – editorial application name ${DOC.INFO.Producer} – editorial application producer ${DOC.INFO.CreationDate} – the date of creation (retrieved from the file) ${DOC.INFO.CreationDateInDocument} – the date of creation (retrieved from contents) ${DOC.INFO.ModificationDate} – the date of modification (retrieved from the file) ${DOC.INFO.ModificationDateInDocument} – the date of modification (retrieved from contents) ${DOC.INFO.EncryptedDocument} – information if the document is encrypted ${DOC.INFO.FileName} – the name of the file ${DOC.INFO.FileSize} – the size of the file ${DOC.INFO.PageCount} – number of pages in the document ${DOC.INFO.NumberOfPages} – number of pages in the document (JDF convention)

Some of those keys, such as PageCount or CreationDate, are always present in every PDF document, while others, such as author or title, are not mandatory. Hence, one should not be surprised once the value returned by the expression is just an empty string.The PuzzleFlow™ system returns exactly what is inside the PDF. Be aware, however, that PDF/X standard may require some of those entries specified. ToolBox and PdfXMaker Modules allow completing missing info entries. In the previous versions of PuzzleFlow™, DOC.INFO object was aliased by the DOCINFO environment. In ToolBox Module, also PDF shortcut was available. Both DOCINFO and PDF subenvironments are no longer supported.

What if a module we want to use does not support DOC.INFO? Well, it is enough to attach PreflightCheck Module to the workflow chain and specify a custom variable on the preflight step. In the example, one can open the Variables property tab of the PreflightCheck module configuration and define MY_PAGECOUNT variable as DOC.INFO.PageCount. After that one can reuse MY_PAGECOUNT variable anywhere in the workflow, even in those modules that do not support the DOC.INFO object directly. That is because the user defined variables are exported to the higher environment level, so becomes global for the workflow queue. See Scoping rules for details.

98


Environment LAYER.INFO This subenvironment is available while running Personalization Module. The object contains some basic information about the PDF layer being merged with the main document. . . . . . . . .

${LAYER.INFO.Title} – the title of the layer ${LAYER.INFO.Subject} – the subject of the layer ${LAYER.INFO.Keywords} – document keywords ${LAYER.INFO.Author} – the author of the layer ${LAYER.INFO.Producer} – editorial application producer ${LAYER.INFO.Creator} – editorial application name ${LAYER.INFO.FSpec} – filepath specification ${LAYER.INFO.PageCount} – page number of the layer file

For each personalization layer a different subenvironment is generated. There is no way to export the information about the layers to higher level environments. In the previous versions, instead of LAYER.INFO, there was a LAYERINFO subenvironment – no longer supported in the current version PuzzleFlow™. PAGE.INFO Some PuzzleFlow™ modules, such as JobSplitter, operate on subsequent pages rather than the entire document. The detailed information about each page of the document is stored as a PAGE.INFO subenvironment. The object contains the following properties: . . . . . .

${PAGE.INFO.MediaBox...} – MediaBox area of the page ${PAGE.INFO.CropBox...} – CropBox area of the page ${PAGE.INFO.BleedBox...} – BleedBox area of the page ${PAGE.INFO.TrimBox...} – TrimBox area of the page ${PAGE.INFO.ArtBox...} – ArtBox area of the page ${PAGE.INFO.Label} – the label of the page

Label contains just a page label (if any). Other items are objects rather that variables and refer directly to the page geometry. Dimensions of page boxes can be retrieved and returned in a string form with Width and Height methods (see Object functions for details).

99


Environment

In the previous versions of PuzzleFlow™, instead of PAGE.INFO, there was a PAGEINFO subenvironment – no longer supported in the current version of the system. DOC.PFC The object named DOC.PFC is created by PreflightCheck Module while verifying the document. This special feature is enabled only when Create inventory option is in use. When selected, each preflight test becomes indexed with an integer number (shown in tooltip when the mouse cursor is above the given test). After the preflight process, DOC.PFC object contains results of all the tests that were performed. . . .

boolean values showing if the test was successfully finished or failed test results (numbers, dimensions etc., depending on the test type) list of pages where given object or property has been found Some modules uses shortened, synonymic form PFC instead of DOC.PFC. In examples below we consequently use a full name.

Lets imagine PreflightCheck was module configured to check constraints 76 and 77, so that the presence of the property (in this case, existence of RGB images and vector objects respectively) should cause a warning or error. Assuming there were RGB images in the document but no RGB vector graphic, DOC.PFC object elements have the following values: ${DOC.PFC.T76} returns true (a warning or error has been issued) ${DOC.PFC.T77} returns false (test passed, no warnings or errors) If the preflight test refers to some measurable property (page dimensions, text size, image resolution etc.), DOC.PFC object not only contains a boolean value of the test result, but also the value factually used in the document being preflighted. The value can be retrieved by expression ${DOC.PFC.T??V}, where ?? states for the test number. As an example, let us take the tests from 49 to 52 that check if the effective images resolution fits assumed acceptable range (ie. 150-300dpi). Lets now assume there were some images at 100×120dpi and some at 250×300dpi (horizontal and vertical respectively). After preflighting, DOC.PFC objects contains the following elements: ${DOC.PFC.T49} is true, ${DOC.PFC.T49V} returns 100, ${DOC.PFC.T50} is true, ${DOC.PFC.T50V} returns 120,

100


Environment ${DOC.PFC.T51} is false, ${DOC.PFC.T51V} returns 250, ${DOC.PFC.T52} is false, ${DOC.PFC.T52V} returns 300. Yet another expression allows retrieving formatted page numbers at which the property has been spotted. The expression is ${DOC.PFC.T??P}, where ?? states for the constraint identifier. ${DOC.PFC.T49P} may return 1-3,5,7,28-32, depending on which pages low resolution images has been detected.

Quite advanced preflight and correction systems can be build on this scheme. Having all the preflight tests results in such a symbolic form, we can create dynamic, "job-controlled" workflows, where different operations are performed depending on preflight results. FONT The FONT object is available while working with FontToCurves module. It contains basic information about the font being processed. The object is created subsequently for each font found in the document.The font object contains the following elements: FONT.Type – type of the font (can be Type0, Type1, Type3, TrueType or MMType1) FONT.Name – name of the font FONT.Base14 – returns true if font belongs to Base 14 PDF fonts FONT.Embedded – returns true if font is embedded FONT.Subset – returns true if font is embedded but subset

MAIL MAIL subenvironment is used by Mailer Module. The objects variables contain basic mail client configuration. MAIL.FROM – sender e-mail address (ie. name@server.com) MAIL.SMTPSERVER – sender SMTP server (ie. server.com) MAIL.SMTPPORT – SMTP server port (optional) MAIL.SMTPUSER – user name (if your SMTP server requires authorization) MAIL.SMTPPASSWORD – user password (if your SMTP server requires authorization)

101


Environment In PuzzleFlow™ series 3, the MAIL environment in Mailer Module has been replaced with relevant GUI options. However, the environment still exists and is available via the environment expressions. Mailer Module creates a local MAIL environment that simply covers the global one.

9.2

Functions Functions are procedures you can perform on variables to operate on their values. Most of the functions process a variable value and return another value, depending on the processed variable and function type. The new value is not assigned to the original variable. The Functions are also called methods. Invoking the functions has a special syntax. To perform the function called Fun on the variable VAR, you have to type the variable name first, and then the function name separated by a dot. The whole expression must start with $ and be wrapped in braces. ${VAR.Fun} You may want to use many methods which operate on one variable. If so, every next method is just added to the end of the list and separated by a dot. ${VAR.Fun1.Fun2.Fun3...} In the example above, the function Fun1 operates on the value returned by VAR variable. This function passes a new (or modified) value to Fun2. Again, the function Fun2 process the value returned by the function Fun1 and passes the new one to be processed by the function Fun3. This mechanism is repeated until the last function is reached. Then, the whole expression is substituted with the value returned by the last method.

Each expression which starts with $ and is wrapped in braces, returns the value of the most right method on the dot-separated list. Each function needs, at least, one parameter, which is a value returned by the left side of the expression. However, some more complex functions may need additional parameters, which instruct a method how to process some input data. Additional parameters are expressed as comma-separated list wrapped in parenthesis. ${VAR.Fun1(1).Fun2(−1,−2)}

102


Environment In the example above, the method Fun1 operates on the value stored in VAR variable using an additional parameter 1.The method Fun2 operates on the value returned by Fun1 using additional parameters −1 and −2. In general, most of the functions operate on some kind of character strings (paths or dates). These functions usually return some kind of substring of a string provided as the argument. There is also a couple of functions that operate on numbers and return a number or boolean type (true or false). However, these are not strict rules since each function may return any data type, regardless of an input type.

After saying that, each variable is a container for the specified type of data.The methods operate on variables, so each method requires one specified type of data as an argument. Each method also returns one specified type of data.The methods try to convert their arguments into proper data types. If such a conversion is impossible, an error may occur. According to the rules described above, the functions in the PuzzleFlow™ environment can be divided into five groups: . .

. . . .

string functions – functions that operate on strings in general. path functions – functions that operate on path strings and return some feature of the file pointed by this path (file functions) or an expression retrieved from path string date functions – functions that operate on dates and return formatted part of a date and time number functions – functions that operate on numbers array functions – functions that operate on lists of values object functions – functions that operate on specified objects

There is one significant difference between the object functions and all the others. The generic string or number functions are always available, regardless of the context they were used. The object functions are dedicated to the specified objects and available only in that context.

Path functions

9.2.1

Mtime This function operates on a full path which points to the existing job file. Actually, only SOURCE variable can be used as an argument of this method. The function

103


Environment returns the time of the last modification of the file pointed to by the source path. The returned value is a date-like formatted string ${SOURCE.Mtime} would be evaluated to 2008-03-10 17:41:09, depending on the real modification time of the file pointed by ${SOURCE}. Ctime The usage of Ctime function is the same as Mtime. The value returned by Ctime is a formatted string of the date and the time of the file creation. ${SOURCE.Ctime} would be evaluated to 2008-02-12 07:22:19, depending on the real creation time of the file pointed to by ${SOURCE}.

Mtime and Ctime methods operate on file features rather than on the string provided as input data. Both retrieve some information from the job file, while the path string is used only to point to the file. Therefore, these two methods are also called file functions. All other path functions operate on strings only.

As mentioned before, in the current version of the PuzzleFlow™ system each date-related variable returns the date formatted in the way it cannot be used as a valid file name. Mtime and Ctime methods also return the strings which may contain colons, slashes and others invalid characters, therefore these functions should be followed with the date function in the template expression. Name This function operates on the path string and returns the name of the file without its extension. Because of compatibility reasons, there is also a Title method which works in the same way. In the current version of PuzzleFlow™, the Name and Title functions are simply synonyms. Ext This function operates on the path string and retrieves a file extension. File This function operates on the path string and retrieves a full filename (including extension).

104


Environment Path This function operates on the path string and retrieves a directory path (excluding filename). Assume you perform normalization of the file named Puzzle.ps. The list below shows some examples of the name templates you could use in the OutFolder configuration, and the way they will be resolved: If ${FILE} gives Puzzle.pdf, then ${SOURCE.File} gives Puzzle.ps, ${NAME}.${SOURCE.Ext}.${EXT} gives Puzzle.ps.pdf, and ${NAME}-${WORKFLOW}.${EXT} gives Puzzle-Normalization.pdf.

Note that FILE, NAME, end EXT variables always refer to the output job filename, while File, Name, and Ext methods just return a substring from a string returned by the left side of the expression. Note also that PATH contains an indirect, relative path to the input job, while Path method returns the whole directory path (excluding file name). SubPath This function belongs to a group of a bit more complex methods, which need some additional parameters. The syntax of the function can be expressed as SubPath(Start,End), where Start and End are integer numbers referred to several segments of a path. The path string may be divided into segments separated by \ character (directory separator). In other words, the paths may be considered as a list of the directory names separated with backslashes.The SubPath method treats the path string in this way and returns a range of segments. The best way to understand how it works, is to consider the following example: Assume that SOURCE contains such a string: C:\PuzzleFlow\Inputs\Imposition\Booklet\48p-10_03_2008.pdf ${SOURCE.SubPath(1,2)} ${SOURCE.SubPath(1,3)} ${SOURCE.SubPath(4,5)} ${SOURCE.SubPath(5,4)}

returns C:\PuzzleFlow, returns C:\PuzzleFlow\Inputs, returns Imposition\Booklet, also returns Imposition\Booklet.

A simple conclusion of the example shown above is that if the arguments are positive, the segment indexes are assigned from left to right. However, SubPath

105


Environment method also accepts negative integers as parameters. The negative path indexes are assigned from right to left. Continuing the previous example, ${SOURCE.SubPath(−1,−1)} returns Booklet, ${SOURCE.SubPath(−2,−1)} returns Imposition\Booklet, ${SOURCE.SubPath(−1,−3)} returns Inputs\Imposition\Booklet The general rules of SubPath method are listed below: . . . .

9.2.2

Slashes and backslashes are removed from the left and right side of returned subpath. Parameters are 1-base indexes, which means that the counting indexes starts with 1 (not with 0). Parameters may be negative or positive integers. The order of the parameters does not influence the value returned. In other words, SubPath(a,b) and SubPath(b,a) mean the same.

Date Functions The date functions operate the special data type described at the beginning as date. Not surprisingly, the date functions accept the date format returned by Ctime and Mtime methods and all date-related variables such as DATE, MODIFYTIME and so on. In most cases we need only a part of information from the complete date. The date functions allow retrieving the needed information. Date Returns a date string formatted as year-month-day (yyyy-mm-dd). If ${DATE} gives 2008-03-11 14:05:31, then ${DATE.Date} returns 2008-03-11. If ${SOURCE.Mtime} gives 2008-07-23 11:34:01, then ${SOURCE.Mtime.Date} returns 2008-07-23. Time Returns a time string formatted as hour-minute-second (hh-mm-ss). In analogy to Date method, Time may be very useful while using time expression as a part of the file name template. If ${DATE} gives 2008-03-11 14:05:31, ${DATE.Time} returns 14-05-31. If ${SOURCE.Ctime} gives 2008-07-23 11:34:01, ${SOURCE.Ctime.Time} returns 11-34-01.

106


Environment Year Retrieves some information which refers to the year.The returned value consists of four digits. Month Retrieves some information which refers to month number. The returned value may range from 1 to 12. Day Retrieves some information which refers to the day of the month. The returned value may range from 1 to 31. Week_Day Retrieves some information which refers to day of week. Returned value may range from 1 to 7. Day_Of_Year Retrieves an information which refers to the current day of the year. The returned value may range from 1 to 366. Hour Retrieves some information which refers to the current hour. The returned value may range from 0 to 23. Minute Retrieves some information which refers to the current minute. The returned value may range from 0 to 59. Second Retrieves some information which refers to the seconds.The returned value may range from 0 to 59. Assume that the job file pointed by SOURCE variable was modified on Dec 30, 2008 at 7:02:34 AM ${SOURCE.Mtime.Day_Of_Year} will be evaluated to 364. ${SOURCE.Mtime.Day}.${SOURCE.Mtime.Month} would be evaluated to 30.12. ${SOURCE.Mtime.Hour}-${SOURCE.Mtime.Minute} would be evaluated to 72. ${SOURCE.Mtime.Time} would be evaluated to 07-02-34.

107


Environment

Note the difference between the two last expressions in the example above. Hour and Minute methods return integers, which are converted into digits as they are, meaning without leading zeros, while Time method return a whole string already formatted.

9.2.3

String functions PuzzleFlow™ provides a couple of methods which operate on strings in general, not only on path-like or date-like formatted strings. These methods can be used with paths, dates, or user's defined strings as well.

Note, that all types of data can be easily converted to string type. Dates are converted to string of letters and digits, while numbers are converted to list of digits SubString The function returns a substring of a string. This function needs two parameters, which represents indexes of the first and the last character of the processed string. Both parameters of the syntax can be expressed as SubString(Start,End), where Start and End are 1-based integer indexes of characters of the input string. If ${FILE} gives Impo4x4.pdf, then ${FILE.SubString(5,7)} returns 4x4, ${FILE.SubString(5,−1)} returns 4x4.pdf, and ${FILE.SubString(−1,1) returns simply Impo4x4.pdf. In analogy to the previously described SubPath method, the SubString method accept negative parameters. SubString treats the input string as a list of characters. Each character on the list has two indexes assigned, one positive, and one negative. The character indexed as 1 is the first character of the input string counting from the left, and the character indexed as −1 is the first character counting from right. General rules of SubString method are listed below: . . .

108

Parameters are 1-base indexes, which means that counting indexes starts with 1 (not with 0). Parameters may be a negative or positive integers. The order of parameters does not influence returned value. In other words, values returned by SubString(a,b) and SubString(b,a) are always equal.


Environment Substr This function gets a string returned by the left side of the expression and returns its substring determined by additional parameters. The syntax of Substr method can be expressed as Substr(Start,Length), where Start and Length are non negative integers. The first parameter is 0-based index of the first character of an initial string to be retrieved as a substring. The second one is a length of substring. If ${WORKFLOW} gives Normalization, then ${WORKFLOW.Substr(0,4)} returns Norm. If ${NAME} gives Impo4up, then ${NAME.Substr(4,3)} returns 4up.

Substr method is now obsolete, and exists only because of compatibility reasons. It is recommended to use SubString instead. SubStringDelim This function assigns the integer indexes to each segment of the input string separated by the string given as a third parameter. The syntax of this method can be expressed as SubStringDelim(Start,End,Delim), where start and End are 1based integer indexes while delim is non empty string which represents a segment separator. The first two parameters work as in the SubString method. The difference is that the indexes are assigned to some segments, instead of single characters. The last parameter allows specifying which kind of the segments should be indexed. If ${FILE} gives l2-en.manual-env.draft.pdf, then ${FILE.SubStringDelim(−3,−1,".")} returns manual-env.draft.pdf, and ${FILE.SubStringDelim(1,2,"-")} returns l2-en.manual. Delimiters from left and right side of returned string are removed. In analogy to previously described string functions, the order of first two parameters doesn't influence returned value. Left This method returns a substring which contains given number of first characters from an input string. The function require one positive integer as a parameter, which is the length of returned substring (a number of first characters retrieved from an input string). An expression Left(a) can be considered as an abbreviation for SubString(1,a).

109


Environment If ${FILE} gives 2x4L_13-11-03.pdf, then ${FILE.Left(4)} returns 2x4L. Right In analogy to previously described method, Right method returns a substring of an input string which consists of specified count of last characters. Function needs one positive integer as a parameter. An expression Right(a) can be considered as an abbreviation for SubString(−1,−a). If ${FILE} gives 2x4L_13-11-03.pdf, then ${FILE.Right(12)} returns 13-11-03.pdf. Length This method does not require any parameters. It just returns an integer number which is a number of characters in a string returned by the left side of the expression. If ${USER} gives PuzzleFlow, then ${USER.Length} returns 10. StartsWith This method checks if the string starts with a substring given as a parameter. A string provided as an argument is matched to a string of characters returned by the left side of the expression. The function returns a boolean result of matching. EndsWith In analogy to StartsWith method, EndsWith method tries to match a string given as a parameter to the end string returned by the left side of the expression. The function returns a boolean result of matching. If ${FILE} gives 2up_13_12_2008.pdf, then ${FILE.StartsWith("2up")} returns −1 (true), while ${FILE.EndsWith("2008")} returns 0 (false). One should remember that boolean values should never be converted into other data types. Although such a conversion does not cause an error, the results may lead to confusion. Booleans are conditions rather than real values you can use in the file name templates. All the methods and operators which return boolean values were designed to be used in conditions.

110


Environment Contains This function checks if a string returned by the left side of the expression contains a substring given as an argument. Returned value is boolean type. If ${FILE} gives sep_13_12_2008.pdf, then ${FILE.Contains("comp")} returns false, while ${FILE.Contains("sep")} returns true. Matches This method works similar to Contains method, but the global expression is matched instead of a substring. The global expression can be considered as a mask of a string. Among ordinary characters, it may contains two specials: . .

* – can be substituted by any string of characters (also empty). ? – can be substituted by any single character.

Any other character used in the global expression means itself. The matches method returns boolean true or false depending of the matching result. Expression ${FOO.Matches("*")} always return boolean true. Expression ${FOO.Matches("?")} returns true only if ${FOO.Length} = 1. If ${FILE} gives 24p_34_12_2008-draft.pdf, then ${FILE.Matches("*-draft.pdf")} returns true, ${FILE.Matches("*draft.???")} returns true, but ${FILE.Matches("*draft.?")} returns false. Replace Replace method can be used to substitute a given substring of the input string with another substring given as an argument. The syntax of this method could be expressed as Replace(substring,substitution), where substring is a text to be replaced with the replacement text given as substitution. The function returns the whole string after substitution. Assume that QUERY contains path C:\OPI\Images. Expression ${QUERY.Replace("C:","D:")} returns D:\OPI\Images, which can be used by Resource module. You can also use this method to format a date string (or any other string) in your own way. Note that if there are more than one substring to replace, you can just add another Replace method separated by a dot instead of repeating the whole expression.

111


Environment If ${DATE} contains 2008-03-11 16:55:04, then ${DATE.Replace(" ","_").Replace(":","-")} returns 2008-03-11_16-55-04. ToUnit The function converts text that represents dimension into other dimension, but expressed in different units, provided as an argument.The supported units are inches (in), centimeters (cm), millimeters (mm) and points (pt). The expression ${'1cm'.ToUnit('mm')} is evaluated 10 mm, and ${'1cm'.ToUnit('pt')} is evaluated to 28.3 pt.

9.2.4

Number functions This set of functions operates on numbers. Although not commonly used in the PuzzleFlow™ environment, they can be very useful while using some advanced environment expressions. IsOdd This function returns boolean true if the number returned by the left side of an expression is odd, and boolean false if the number is even. IsEven This function returns boolean true if the number returned by the left side of an expression is even, and boolean false if the number is odd. IsOdd and IsEven methods return boolean values, and therefore should be treated as conditions On the base of the values returned by these methods, you can choose the location of the files stored i.e. by Archive Module or split by PageSplitter. Fixed This function converts a number (a string of digits) to the formatted string which consists of a given number of digits. Assume that you want to generate previews of each page of processed document using PreviewGenerator with Archive module. The last one uses special INDEX variable to count dumped files. If you use ${INDEX.Fixed(3)} template, dumped files will be named 001, 002, 003 and so on.

112


Environment ToInt This functions tries to convert a number or a chain of digits into the integer number. If the conversion is impossible, an empty value is returned. If ${NAME} gives 0021p, then ${NAME.Left(4).ToInt} returns 21, ${NAME.Left(4).ToInt + 1} returns 22, while ${NAME.ToInt} returns an empty value.

As mentioned before, each data type can be easily converted into the string type. Therefore, some methods and operators may treat an input data a string by default. In the example, 01 and 1 are equal as numbers, but are not equal as strings. To avoid such a situation you should use ToInt method for data type conversion. FormatCounter FormatCounter function performs a conversion between number expressions. The desired number system is taken from the symbolic character provided as an argument. Characters d and D state for decimal and produces decimal number representation. Characters r and R state for roman and produces lower and uppercase roman numerals respectively. Finally, a and A converts number to its lowercase and uppercase alphanumeric representation. ${'1999'.FormatCounter('r')} is evaluated to mcmxcix, and ${'1999'.FormatCounter('R')} is evaluated to MCMXCIX. ${'0001'.FormatCounter('a')} is evaluated to a, ${'0002'.FormatCounter('a')} is evaluated to b, but ${'0003'.FormatCounter('A')} is evaluated to C, and ${'0026'.FormatCounter('A')} is evaluated to Z. Consequently, ${'0027'.FormatCounter('a')} is evaluated to aa, and ${'0028'.FormatCounter('A')} is evaluated to AB.

Array functions

9.2.5

All The function converts each element of the array on the left side of the expression into boolean type. It returns logical true, if all the elements are boolean true.

113


Environment ${[1,True,True].All} returns true, but ${[1,False,'ABC'].All} returns false, and ${[0,1,'ABC'].All} returns false. ${ARR.All} returns true if all the elements of ARR array are true.

True and False variables are predefined and contain logical true and false respectively. A mentioned above, the functions convert the input values into the required data type. Consequently, a simple boolean expression is converted into the list of the expressions if used in the array context. ${(ARR>7).All} returns true, if all the elements of ARR array are bigger than 7. ${(ARR==7).All} returns true, if all elements of ARR array are equal to 7. ${(ARR.IsOdd).All} returns true, if all elements of ARR array are odd.

We use ( and ) characters to control operations priority and order. See Operators chapters for details. Any The function converts each element of the array on the left side of the expression into boolean type. It returns logical true, if any of its elements are boolean true. ${[1,False].Any} returns true. ${[0,False].Any} returns false. ${ARR.Any} returns true if all elements of ARR array are true. ${(ARR==7).Any} returns true if any of ARR array is equal to 7. Size The method retrieves the number of elements stored in the table that is equal to the highes array index increased by one. ${[1,2,3].Size} gives 3 ${PAGES}.Size gives the number of pages on the imposition plate (see PAGES object description). Format The function converts each element of the array on the left side of expression into a string and returns the formatted string that is the concatenation of the array

114


Environment elements. The format function needs two arguments. The first one is a string inserted between each pair of the array elements. In analogy to Fixed function, the second one specifies how many characters should be used to type a given element. ${['A','B','C'].Format('-',1)} is evaluated to A-B-C, ${[1,2,3].Format('_',2)} is evaluated to 01_02_03. Min The function returns the smallest value of the array on the left side of the expression. If the elements are strings, they are compared lexicographically. If, at least, one of elements is a number, strings are converted to numbers. If such a conversion is impossible, any string is treated as bigger than any number. ${[1,2,45,8].Min} returns number 1, ${[1,-2,45,8].Min} returns number -2, ${[0,'-123','abc'].Min} returns string abc. Max The function returns the biggest value of the array on the left side of the expression. If the elements are strings, they are compared lexicographically. If at least one of elements is a number, strings are converted to numbers. If such a conversion is impossible, any string is treated as bigger than any number. ${[1,-2,45,8].Max} returns number 45, ${[0,'00','i',3].Max} returns string i, ${[0,'00','0',3].Max} returns number 3. FormatRange FormatRange function works on lists (arrays) rather that scalar values. It returns a string that consists of digits, commas and dashes. The function converts all the elements of the array into boolean values and returns a string representing a selection of true values. Let us assume that TEST is an array that contains the results of a given preflight test. The pages that have passed this test are marked with 1, other pages are marked with 0 in TEST array. The expression ${TEST.FormatRnage} returns formatted string representing selection of pages that have passed the test. Expressions ${[1,1,1,0,1,0,1].FormatRange}, as well as ${[True,1,7,�,7,0,1].FormatRange}, and ${[True,True,True,False,True,False,True].FormatRange}, are evaluated to string 1-3,5,7.

115


Environment

Object functions

9.2.6

Here we describe a set of functions that work only in the object context. Actually, all of them refers to page box objects provided by INFO environment. Width Width function operates on page box objects provided by INFO environment in the separate page context (see Objects section for details). The function returns the horizontal dimension of the box expressed in Postscript points, without unit. Height As described above, Height function operates on page box objects provided by INFO environment in singular page context. The function returns the vertical dimension of the box expressed in Postscript points, without unit. Let us assume that the processed document is A4. ${INFO.TrimBox.Width()}x${INFO.TrimBox.Height()}.pdf is evaluated to 595x842.pdf. ${INFO.TrimBox.Width() < INFO.BleedBox.Width()} is logical true, if the page has some horizontal bleeds. ${INFO.BleedBox.Width() â&#x2C6;&#x2019; INFO.TrimBox.Width() >= '6mm'.ToUnit('pt')} is logical true, if the page has at least 6mm horizontal bleeds in sum. The first example can be used in OutputModule to configure the output filename template. Two others can be used in JobSplitter module to split the document into groups of pages with the same geometry. Contains The function returns logical true, if the box object on the left side of the expression contains the box provided as an argument. ${INFO.BleedBox.Contains(INFO.TrimBox)} returns true if the document has horizontal and vertical bleeds. Intersects The function returns logical true, if the box object on the left side of an expression intersects the box provided as an argument. ${INFO.BleedBox.Intersetcs(INFO.TrimBox)} returns true if the bleeds area intersects the page area after trimming. It obviously means that the document geometry is incorrect.

116


Environment

Operators

9.3

Operators are characters or strings, which are read by the PuzzleFlow™ environment is a special way.The operators could be considered as a special kind of functions with a simplified syntax. The operators are usually used for basic, commonly used procedures such as arithmetic operations, comparing values, logical functions and others. Some special characters have already been described. In the example, $ the character instructs PuzzleFlow™ to read an environment expression, while { and } delimits an expression. Dot character, comma, parenthesis, and quotation marks (if used inside the expression) also have special meanings. The dot character is responsible for passing values from the left to the right side on the expression, the parenthesis are delimiters of method parameters, the comma is used as a parameter separator, while the quotation marks are used to delimit strings. None of the already described special characters returns a value. In the PuzzleFlow™ environment language each operator returns a value, like functions do. The operators are reserved sequences of characters which execute some basic procedures on their operands. In the example, the expression x + y contains an operand x which is added to the operand y by + operator. The only thing you should remember is that the operators operate on operands and that the operators work inside the expression only. All the operators have their priority. The operators with higher priority are evaluated before those with lower priority. Thanks to that rule, the order of all the operations performed while resolving the expression is clearly predictable. In the example, in a trivial arithmetic operation, such as x + y * z, a multiplication is always performed before addition. To change that behaviour, you have to use parenthesis, as in (x + y) * z. The PuzzleFlow™ environment uses the same method to control the operation order, but some ambiguous situations may appear in sophisticated expressions. ${VAR + 1.Fixed(3)} may produce different results depending on VAR the variable type. To avoid such complications, use ${(VAR + 1).Fixed(3)} instead. In analogy to the methods, we can divide the operators into groups, depending on the data type of their operands. There is, however, one very

117


Environment

important difference. Most of the operators may work on both scalar values and arrays. If an operator is applied, to scalar value(s), it returns scalar value of specified type. If applied to array(s), it returns a list of values of that type. Although not commonly used, this feature makes things easier.

9.3.1

Number operators In general, the number operators work with numbers. However, its possible to use any strings that can be converted to numbers. Addition and substraction Addition and substraction can be obtained using + and − operators, respectively. If ${NAME} gives page097, then ${NAME.Right(3).ToInt + 1} returns 98, ${NAME.SubString(5,6).ToInt − 1} returns 8, ${1 + NAME} returns 1page097, while 1 + ${NAME} returns 1 + page097. Addition and substraction operators will always convert their operands to numbers if only it is possible to make such a conversion. If one of the operands is 097 it will be converted to 97 anyway, so you do not really need to use ToInt method. If conversion to a valid number is impossible, + works like a concatenation operator (both operands are treated as a strings).

Addition and substraction are so called binary operators, which means that they need two operands. However, + and − can be also used as unary operators. Unary operator minus (−) simply inverts the value of the right operand. Multiplication and division As you probably expect, multiplication and division operators are represented by * and / characters respectively. Both require numbers as operands, and try to convert operands data types to numbers, if needed. Modulo The operator represented by % character returns the rest from division of its operands.

118


Environment If ${INDEX} gives 99, then ${INDEX % 2} returns 1, ${INDEX % 3} returns 0, while ${INDEX % 4} returns 3. In analogy to IsEven and IsOdd methods, you can use a modulo operator to segregate output files. The modulo is even more powerful in this case, since it allows to segregate pages into groups of four or eight, not only into two groups of odd and even pages.

String operators

9.3.2

String operators work with any kind of strings. Concatenation Operator represented by & character is used to joining strings. The concatenation operator tries to convert both its operands to strings and join these strings. Assume that you perform PS to PDF conversion on the file 16p_ps.ps. Expression ${NAME.Left(4) & "pdf.pdf"} returns 16p_pdf.pdf, ${NAME.Left(4)}pdf.pdf also returns 16p_pdf.pdf, but ${NAME.Left(4)}&"pdf.pdf" returns 16p_&"pdf.pdf". As you can see, concatenation can be also reached just by adding expressions. The concatenation operator is to be used only inside the expression.

Comparison operators

9.3.3

The comparison operators could be considered as a kind of tests which return boolean values. The operands for this group of the operators can be numbers, strings, or boolean values. Equality This operator is represented by = character or == string. It could be considered as a procedure which returns a boolean value depending on the equality of its operands. If both operands are numbers, the equality operator simply compares its values. But, if at least one of the operands is a string, the operands are compared lexicographically.

119


Environment Inequality This operator is represented by != or <> string. It could be considered as a procedure which returns a boolean value depending on the inequality of its operands. Greater than This operator is represented by > character. It could be considered as a procedure which returns true if the left operand is greater than the right one. Less than This operator is represented by < character. It could be considered as a procedure which returns true, if the left operand is smaller than the right one. Greater or equal This operator is represented by >= string. It could be considered as a procedure which returns true, if the left operand is greater than or equal to the right one. Less or equal This operator is represented by <= character. It could be considered as a procedure which returns true if the left operand is smaller than or equal to the right one.

9.3.4

Logical operators The logical operators performs basic operations on logical values. These groups of operators always treat their operands as logical values with a proper conversion if needed.

In case of variables data conversion one has to be aware of what data type is converted to boolean true and what to boolean false. In the previous versions of PuzzleFlowâ&#x201E;˘, everything except the number zero and empty string was considered as logical true in case of the implicit conversion to boolean. This approach was ambiguous. In the example, the word TRUE was obviously true, but according to those rules, the word FALSE was trueas well. Starting from PuzzleFlowâ&#x201E;˘ 3 series, boolean true can be represented by a string TRUE (case-insensitive) and any integer number other than zero. All other data are considered as boolean false. For sake of consistency, it is advised to use a string FALSE to represent boolean false.

120


Environment Conditional operator The conditional operator requires three operands: condition, an expression used if the condition is true, and an expression used in another case. The conditional operator syntax can be expressed as condition ? then : else, where condition returns boolean value, then is an expression used when the value returned by the condition is true, and else is an expression to be used if the condition returns false. An expression ${PAGE.IsOdd ? "Right" : "Left"}_${PAGE}.pdf used in PageSplitter configuration will produce the following: Right_1.pdf, Left_2.pdf, Right_3.pdf, Left_4.pdf...

It might be convenient to use conditions that return boolean value. However, it could be any other expression, since each data type can be easily converted into boolean. The number zero and empty string state for logical false. All other values are converted into true. Logical negation The character ! states for logical negation. This operator returns true if its operand returns false, and returns false, if its operand returns true. Logical And The string && states for logical And. It returns true if both of its operands returns true. If at least one of its operands returns false, the operator also returns false. Logical Or The string || states for logical Or. This operator returns true, if at least one of its operands returns true. If both of the operands return false, the operator also returns false.

121


Environment

122


Contact

Contact

10

Please visit http://www.puzzleflow.com to know more about us and our products. If you want to download a demo version of the software, documentation or other materials, please register using a contact form available on the webstie. The registration is is free and requires just some basic information about you. After the registration we send you a password code to the customer zone at http://extranet.puzzleflow.com.

Feel free to send technical questions to support@puzzleflow.com, sales and marketing issues to office@puzzleflow.com.

123



QPDF