PDL transform language

A transform is a process that defines how to convert an input into a different output. In PaperCut NG/MF, transforms are defined as simple scripts. There are a number of reasons for performing transforms on a print job. These include:

Extending compatibility

The output produced by one driver (such as PostScript) might not work on other printer brands without modification. For example, “TRAY = 1” on one printer might map to “TRAY = UPPER” on another. Use transforms to automatically make this adjustment to a print job. This is particularly important in a Find-Me printing environment where a job rendered by one driver cannot print correctly on another printer type without modifying the print job.

Modify behaviour/output

Much is possible with the power of transforms. Maybe it’s always enabling the “eco print” mode when an email is printed, or automatically removing the “stapling” option if accidently selected on a printer the does not support stapling. Another use-case is “virtual stationery”. Legacy reports could, for example, have a logo automatically added to each page.

Of note, PaperCut performs page analysis before transforms are applied. As such, a color logo added to a grayscale page, are recorded in PaperCut as grayscale.

Definitions

Before covering the details of the transform language, it’s important to understand the following terms:

Page Description Language (PDL)

A language used to describe the appearance of a printed page e.g. PostScript, Printer Control Language (PCL).

Printer Job Language (PJL) Header

Attributes in a PJL header define print job characteristics such as duplex, color, paper sizes, or media trays. Many printers rely on a PJL header, though many attributes are printer/manufacturer specific.

Transform script

A transform script defines a transform process to apply to a print job’s PDL. Transform scripts are written in a very simple scripting Domain Specific Language (DSL).

Source & target

The transform process refers to source and target print queues. A desired transform is applied when a job is transferred from a specific source queue (a global queue) to a specific target queue.

Writing a transform

Transforms are text files placed in a location (directory structure) that determines when the script applies. The file’s name and location must conform to the following path:

[install-path]/providers/print/[platform]/transforms/custom/[language]/[source]/[target].transform

• language - the PDL language of the print job (e.g. Postscript).
• source - the name of the queue that first received the print job (e.g. a global queue).
• target - the name of the queue the job is being transferred to print to.

For example, to apply a transform when a job is transferred from the queue named “Global Queue” to “Printer A”, the transform file should be located at:

[install-path]/providers/print/[platform]/transforms/custom/postscript/global queue/printer a.transform

Also see Writing a PDL transform (a practical example) for a walkthrough of how to write a transform.

Matching rules for running a transform script

The following steps select the transform script to run for a redirection from printer type source to printer type destination, which both use printer language language.

1. Look first in the custom directory then in the system directory.
2. Find the subdirectory whose name matches language e.g. if language is PostScript then look in custom/postscript.
3. Find the subdirectory whose name matches source. e.g. if source is PaperCut Global PostScript then look in custom/postscript/pc-win. (NOTE: On PaperCut NG/MF systems, pc-win is an alias that matches printer type PaperCut Global PostScript).
4. Find the file whose name matches destination. e.g. if destination is HP Color LaserJet then look for custom/postscript/pc-win/hp.color.laserjet.transform. This does not exist so backtrack.
5. Backtracking takes you to custom/postscript/pc-win/default.transform, which does not exist, then custom/postscript/default.transform, which does not exist, then s_ystem/postscript/pc-win/hp.color.laserjet.type.transform_, which does exist. (NOTE: printer type is matched against *.type.transform and printer name is matched agaist *.name.transform before printer type and name are matched against *.transform*)
6. Thus s_ystem/postscript/pc-win/hp.color.laserjet.transform_ is selected.

Examples

There are two example sources that script authors might find useful as starting points or reference:

[install-path]/providers/print/[platform]/transforms/examples
[install-path]/providers/print/[platform]/transforms/system

Also see Writing a PDL transform (a practical example) for a walkthrough of how to write a transform.

Transform language functions & specification

PDL transform command functions

Assignment

var = expression

e.g. x = 1

Evaluate the expression and assign the variable var with the result. If the expression contains any $[N] and/or %variable% tokens, they are replaced with their current values. To prevent variable substitution, include __no_replace__ in the variable name e.g. __no_replace__template.

IF THEN

IF condition THEN statement

e.g.
IF duplex THEN pjl_duplex = "ON"
Evaluate the condition expression, and if true execute the statement.

Rules for evaluating expressions

1. A number x is true if x != 0.
2. A string pattern is true if it can be found in the spool file using the rules in the FIND pattern [options] below. Strings can be regular expressions or plain strings, and have two optional attributes FIRST | LAST | ALL and a search distance. FIRST | LAST | ALL does not affect logical evaluation. Search distance does. e.g.
   /<<.*?\/ProcessColorModel\s*\/(DeviceCMYK|DeviceGray).*?>>\s*setpagedevice/ 10000
   is true if this regular expression is matched in the first 10,000 bytes of the spool file.
3. Compare numbers with ==, !=, <, >, <= and >=.
4. Compare strings with == and !=. These comparisons are case insensitive and do not perform the searches in rule 2 above.
5. You can combine logical expressions, such as the results of 1-4 above, with NOT, AND, OR, XOR, and (...) parentheses. e.g. x == 1 AND NOT (y > 2 OR z <= 3)

FIND

FIND pattern [options]

where the pattern is a regular expression (regex) or string.

FIND / regex/ [options]

FIND “string” [options]

FIND searches for the pattern (a string or a regex) in the spool file and assigns $0, $1, … from the resulting regular expression capture groups. If the pattern is a string, then only $0 is assigned.

e.g
FIND /<<.*?\/ProcessColorModel\s*\/(DeviceCMYK|DeviceGray).*?>>\s*setpagedevice/

could set $0 to “<< /ProcessColorModel /DeviceCMYK >> setpagedevice” and $1 to “DeviceCMYK” on a match.

Options

• FIRST: Return the first match in the spool file. This is the default
• LAST: Return the last match in the spool file.
• ALL: Return all matches in the spool file.
• n: Any positive integer. Search n bytes of the spool file. The default is to search one megabyte. A value of zero (0) searches through the entire spool file.

FIND REPLACE

FIND pattern [options] REPLACE text

where the pattern is a regular expression (regex) or string.

e.g
FIND "Letter" REPLACE "A4"
FIND /(\w+)\s=\sGrayscale/ REPLACE "$1 = BlackAndWhite"
FIND /MODE = \w+/ REPLACE "MODE = %my_var%"
FIND /MODE = \w+/ LAST 2000 REPLACE "MODE = %my_var%"

The FIND works as described above. Then REPLACE substitutes all the $[N] and %variable% values in the text, before replacing the string matched in the spool file with the substituted text.

ADD_HEADER

ADD_HEADER text

e.g.
ADD_HEADER my_header

Insert the string text as a header in the spool file.

STRIP_HEADER

STRIP_HEADER

Strip any PJL, XPIF, PostScript or other header (that our developers know about) from the spool file.

DELETE_UNTIL

DELETE_UNTIL text

e.g
DELETE_UNTIL "%!PS-Adobe-3.0"

Delete from the start of the spool file up to but not including the first occurrence of text.

REPEAT_ALL

REPEAT_ALL num_copies

e.g
REPEAT_ALL 3

Make num_copies of the input spool file in the output spool file after applying all other modifications.

Use this option for printers that don’t support spool files copies commands, typically printers without hard disks. You usually detect the copies command in the source spool file then use REPEAT_ALL to repeat the source spool files the same number of copies.

INSERT

INSERT ofs len text

e.g
INSERT regex_ofs regex_len my_replacement

Insert the string text at the spool file offset ofs, after deleting len bytes.

Setting ofs to -1 appends text to the end of the spool file. In general, setting ofs to -n inserts text n - 1 bytes before the end of the spool file.

DELETE

DELETE ofs len

e.g
DELETE regex_ofs regex_len

Delete len bytes from the spool file, starting at offset ofs.

It is equivalent to:

INSERT ofs len “”

Pre-populated variables

Pre-populated PDL transform script variables

Test mode

Test mode is designed to accelerate the development, testing and debugging of transform scripts. Test mode is enabled by adding the following line to a transform script:
ENABLE_TEST_MODE
​​​​​​or by setting
EnableTransformTestMode=on
​​​​​in the print-provider.conf file. The test mode option should only be enabled while developing scripts.

Test mode causes the system to output additional log files to assist in developing and validating transforms. These files are located at:
[install-path]/providers/print/[platform]/transforms/logs/

The test mode files created are:

PDL transform test mode output files

Tips & tricks

• Develop your scripts in TEST_MODE to help compare script behavior.
• Use existing examples as starting points.
• Print the same documents from source and destination printer drivers, and diff the resulting spool files. In most cases the things you need to modify are in the diff. e.g. One file has a header and the other does not, or one file sets color/grayscale with one string and the other file uses a different string.
• Look at a PostScript Printer Description (PPD) file of the destination printer, and copy PostScript snippets into a transform.

Troubleshooting

• See Troubleshooting PDL Transforms
• See Writing a PDL transform (a practical example) for a walkthrough of how to write a transform.