New RPM 7 is now available — see what’s new →

RPM Filter Transform

Screenshots in this article are from RPM 7.0.

Elite only Run an external program for custom data transformation.

Purpose

The filter transform reads input and produces output. RPM Elite can use this internally as it is processing a job prior to printing or other actions. For some workflows, this may save time and extra steps.

RPM has supported the filter action from the beginning. We started considering a filter transform when our customers reported to us that they were running their own software on a print job, then they wanted to send the results back into RPM for further processing.

We introduced the filter transform in RPM Elite 5.0. We currently use the mechanics of the filter transform, in RPM, for a number of features. Consequently, we are interested in how this is used and are willing to support your efforts.

Setup

Credentials

  • Credentials Optionally, select an account for the program to run as, or click Add User to enter one. Without credentials it runs as the RPM service account, NT SERVICE\rpm. The program, its working folder and its files must be on the RPM computer, and the program cannot interact with the desktop. See the RPM service account.

Application Setup

  • Program Click Browse and locate the program to run for each print job. Note: Only compiled Windows programs (.exe or .com) run directly. Scripting languages such as VBScript run by calling the script interpreter as the program and passing it the script and arguments.
  • Arguments If your program requires specific arguments, enter them here. The default, %s %o, passes the input and output file names. Click Customize to insert variables; see Command-line substitution below.
  • Start In The program’s working directory when it starts. The program can change its working directory as it runs.
  • Terminate if idle for this many seconds Select this option only if your filter program does not close after it has finished processing.
  • Allow batch file (not recommended) RPM runs a batch file (.bat or .cmd) only when this is selected. A program (.exe) is safer.

Program Input (%s)

  • Transfer file to filter using standard input (stdin) The data is streamed to the filter program. Many programs with UNIX origins support standard input.
  • Template (Mask) The name of the input file passed in %s. Click Customize to add variables. Note: Many variables are limited to jobs received using the LPR/LPD protocol. If jobs are received using other methods, most of them will be blank.

Program Output (%o)

  • Send program output to standard output (stdout) Select this if the filter program writes its result to standard output. Many programs with UNIX origins do.
  • Template (Mask) The name of the output file passed in %o, which RPM reads back when the program finishes.

Error Handling

  • Write standard output (stderr) to file in current working directory Saves the program’s standard error to a file in the Start In folder. Despite the label, it is standard error that is saved. See Standard error log.
  • Assume error if program returns non-zero result Puts the job in error when the program exits with a non-zero code. See Catch failures with the exit code.

Command-line substitution

RPM provides the following tags which are substituted with information from the print job.

  • %s = full path to the file to be processed
  • %f = name of the file to be processed without the path
  • %o = path and filename of the program’s output file
  • %O = filename of the program’s output file without the path
  • %n = name of the source file
  • %j = job name from control file
  • %t = title from control file
  • %b = banner from control file
  • %c = class from control file
  • %h = hostname specified by the LPR client
  • %u = user sent in the control file
  • %e = email field from the control file
  • %S = queue sequence number
  • %q = RPM queue name
  • %i = RPM job ID
  • %d = user data (USRDTA) of an IBM i spooled file
  • %1, %2 = Capture 1 and Capture 2 from a Data Extraction rule

Note: Use of the above tags is limited to jobs received using the LPR/LPD protocol. If jobs are received using other methods (i.e. telnet printing or drag and drop), most of these tags will be blank.

Note: If you need any of these literal strings in your argument list, you can prevent RPM from substituting them by “escaping” the percent sign with another. For instance, if you enter %%n in your argument list, RPM will not substitute it for the name of the source file, but instead will change it to a %n. Notice one of the percent signs are removed.