Hooks for various events

This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP.

A number of hooks can be set in the page device that are triggered by various events during the processing of a job. Some are procedures and some are sets of procedures represented as dictionaries.

For hooks that are dictionaries, the contents of such a dictionary in the operand of setpagedevice are merged with the corresponding dictionary already present in the page device. In this way, each call can add new procedures. For hooks that are procedures, you may need to combine the new and the old definition using the technique described in Augmenting Procedure Hooks.

`StartRender`		A hook to be run as rendering is about to start. This is not the end of page, as detected by the `EndPage` hook. For example, when a page with no content is processed, there is no call to `StartRender.` A `StartRender` hook can modify rendering if the change is done carefully. For example, it might substitute a new value for `NumCopies`. See also StartRender procedures for more examples.
`StartPartialRender`		A hook to be run immediately before a partial paint
`EndRender`		A hook to be run just after queuing all separations for rendering. If the RIP isn't pipelining (Harlequin Parallel Pages), all the rasters have also been output by this point. Outputting may abort for various reasons (memory or device problems, and so on), so this hook is not reliable as a way of telling if output has finished. Also, a call to `EndRender` (and `StartRender)` happens regardless of whether the user parameter `NeverRender` is `true`.
`StartJob`		A hook to be run immediately after the job starts. The precise timing is that this hook is run before the job is actually run, but after the file is opened and initialized as `currentfile`. It is called at the job’s save level. You can use `StartJob` with `setstdio` to substitute another stream for the current job, and process the current job in some manner. Use `StartJob` to copy a job to disk, or substitute the contents of a job for an alternate file stream. See also Using the job name from StartJob and EndJob hooks for hints on finding the job name from a `StartJob` or `EndJob` hook.
`EndJob`		A hook to be run as the job is about to end. It is called at the job’s save level. This hook is run even if the job fails for some reason, allowing its use for clean-up operations. When the `EndJob` hook is called, a boolean value is at the top of the operand stack, with `true` indicating that the job terminated with an error. The `EndJob` hook must leave the boolean on the stack but may examine its value to decide whether to perform any cleanup action. See also Using the job name from StartJob and EndJob hooks for hints on finding the job name from a `StartJob` or `EndJob` hook.
`BeginPage`		A hook to be run at the beginning of each page (standard PostScript language), see BeginPage and EndPage procedures
`EndPage`		A hook to be run at the end of each page (standard PostScript language), see BeginPage and EndPage procedures
`StartPainting`		A hook to be run as the first painting operator on a page is encountered
`StartImage`		A hook to be run at the start of images
`EndImage`		A hook to be run at the end of images

With the exception of StartPainting, these hooks should not make graphic marks or cause pagedevice deactivation.

You cannot use gsave and grestore within a /StartImage or /EndImage hook.