PostScript-language interpreter bootstrap

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

The PostScript language takes over from compiled code early on in the RIP’s life (though the PostScript language that is being run is not normally visible: it is built into the RIP). It is however a bootstrapping process. Only two operators def , and an operator which can create other operators and the systemdict dictionary exist initially, and as the bootstrap proceeds, more operators, procedures and dictionaries are created until the whole PostScript-language environment described in [RB3] exists.

This means that during execution of the various customizable PostScript language files which the RIP attempts to run during the bootstrap process, the complete PostScript-language environment is not necessarily present. A simplified sequence of events is given below:

• PostScript language interpreter starts.
• Some standard dictionaries and most operators are created.

… but some of the more complex are not fully functional until much later.

• Support for printing to %stdout% and %stderr% is provided.

… for example, the = and == procedures.

• Standard error handling capability is provided: the $error and errordict dictionaries and their default contents.

The handling of errors is special during start-up of the RIP, and designed to expose any errors in start-up code regardless of any custom error handler. This behavior is controlled by the /initializing Boolean in $error , so if it is a problem, any code that must not create a visible error can be preceded with: $error /initializing false put . This is the only use of this flag, so there are no other side effects to be considered.

Also be aware that changing the error handler does not work in the RIP. This is also deliberate it avoids imagesetters or platesetters wasting media when applications which substituted error handlers to print on the page so you must name the error handler defaulthandleerror instead of handleerror to make it take effect. (It is wise to define both to be the same thing.) See the Harlequin Technical Note Hqn017 for details of the error handler.

However, a default stopped context cannot exist until the server loop starts (as described in The Harlequin server loop). While all the customizable files are run in their own specific stopped contexts, the behavior if they fail can only be very limited because there may not even be a device to which error messages can be written. (For stopped contexts, see [RB2].)

• statusdict and higher-level page device procedures are initialized.

At this point procedures like setpageparams in statusdict and letter in userdict are created. Mostly, such procedures are simply short-cuts for calls to setpagedevice, which is how they are defined. See Configuring the page device for more details.

• The file Sys/ExtraDevices is run, with the run operator in a stopped context.

This file is fundamental to correct initialization of devices. The only devices that exist (are mounted) so far are %os% and %null% , so even though no device is specified in the name passed to the run operator, it must be located on %os% (since %null% is a non-relative device).

Its purpose is to mount and parametrize devices; see Device parameters and setdevparams. It can do a limited range of other tasks, but in particular no attempt should be made to do graphical operations yet. Most customized start-up code should be reserved until later in the boot sequence.

%config% (see %config% device parameters) and %pagebuffer% (%pagebuffer% device parameters) are both created here (and have appropriate parameters set for them, including /DeviceType and /Enable ), because they are both used by the core-RIP before another suitable opportunity exists when they could be created.

Other devices could be created in later PostScript-language code (indeed for removable floppy disks the devices which are mounted are typically revised at each turn round the server loop). However, fixed devices are mostly mounted in Sys/ExtraDevices , for example, the plugin device types for the GUI version.

Sys/ExtraDevices defines the %progress% and %monitor% devices. Harlequin MultiRIP Plugin kit describes how to modify these definitions, then write a plugin, and then initialize it to allow remote access to the rendering progress information and messages sent to these devices.

Sys/ExtraDevices also introduces any built-in custom filters to the system. (In the GUI version, custom filters are more likely to be implemented as plugins.)

When other device-relative devices are mounted, the search rules described in Searching for files apply to files with names which do not specify devices. The devices are searched for a file in the order in which they were mounted, so the order of mounting devices is important.

Consider also an environment where resources such as fonts are shared, but files written by the RIP appear in some user-specific place. In order that Sys/ExtraDevices can be specialized for each copy of the RIP in such an environment, the behavior of %os% may be different early on; it may re-map to a different part of any underlying filing system as other devices are mounted.

Sys/ExtraDevices is the only file that is required in order for the core-RIP to boot (though the skin often requires others). %os% could be implemented to read this file from ROM, and mount other ROM devices to provide fonts and other resources in an embedded controller implementation.

PostScript-language errors in Sys/ExtraDevices are trapped by use of the stopped operator. Therefore an error in Sys/ExtraDevices means that all the subsequent devices given in the file are not reached. It may not be apparent that this has happened because, in the absence of a redefinition of the null device type, the RIP has nowhere to report errors yet.

Therefore, one of the first actions of Sys/ExtraDevices is usually to re-map the pseudo devices %stdout% and %stderr% using the statusdict operators setstdin and setstderr (see Mapping standard input and output: setstdio and setstderr). Unless they are mapped to a log file on the %os% device, another appropriate device (such as a console, window, or serial line to which a debugging terminal could be attached) must be mounted first. If this is done, then any subsequent PostScript-language errors can be caught and reported.

• The page device starts to initialize.

The page device controls the behavior of rendering within the RIP and is highly configurable. The material in chapter 6 of [RB3] gives an explanation of its semantics, but does not give much detail about its intended function. This is explained further in Configuring the page device.

• The file Sys/ExtraPageDeviceKeys is run.

This allows customization of the keys within the page device dictionary. The method is explained in Adding custom page device keys. The file need not exist if no modifications are required.

If a PostScript-language error is detected while running this file, all the items added to the operand stack are ignored. A message is emitted to %stderr% if this happens; the message can be seen if %stderr% is remapped as described above.

Keys already present in the page device are overridden by definitions in this file. Therefore, the file can be used to change default values of standard page device keys: for example, this file is a good place to set up the procedures for the PageBufferSetup, SensePageDevice, and OperatorActions keys (see Configuring the page device), or set the default resolution. Alternatively this can be done in a normal call to setpagedevice in one of the later start-up files, or dynamically, using the ExtraPageDeviceKeys key.

This file should not be used for any other purpose, and should not have any side effects other than leaving the required key / value pairs on the operand stack.

• The file Sys/ExtraMediaSelectionKeys is run.

The same comments as made for Sys/ExtraPageDeviceKeys apply here. Also, however, keys supplied by this file must have already been introduced by Sys/ExtraPageDeviceKeys . See Extending media selection.

• Page device initialization is completed.
• The graphics state is initialized.

However, it is still not possible to render any graphics until setpagedevice has been called.

• The first call to setpagedevice occurs.

This results in a large number of side-effects including several calls to the skin. It arises as a result of initializing the default page size (which is a call to the userdict procedure a4 ; of course, a later startup file can override this default page size). See Configuring the page device for a description of how setpagedevice operates; side effects on the device interface may arise as follows:

— When the keys given in the operand dictionary are merged with the current page device dictionary, the SensePageDevice procedure is run (if it was defined in the Sys/ExtraPageDeviceKeys file). This procedure would commonly be implemented to operate on files and devices.

— When the media match algorithm is run, the OperatorActions procedure might be invoked (given suitable definition of the Policies entry), and this will often result in device calls. In principle any of the procedure operands of the page device could make device calls.

— The page device is reset to the new state. This causes those parameters of the %pagebuffer% device which do not change from page to page to be passed to it via setdevparams. The RIP makes queries about %pagebuffer% device capabilities that cause the core-RIP to modify its behavior according to the environment it is running in. The PageBufferSetup procedure of the page device is also called so that custom %pagebuffer% parameters can be passed at the same time; typically this transfers values from the current page device to the %pagebuffer% device using the currentpagedevice and setdevparams operators.

— The BeginPage procedure of the page device is run with page number operand 0 (zero).

— Any PolicyReport procedures are run.

This set of operations occurs on every call to setpagedevice . However, subsequent uses will also normally call the EndPage procedure near the beginning of the sequence. (The exact circumstances are listed in [RB3].)

A number of further calls to setpagedevice can be expected during the remainder of the boot sequence.

• The file Sys/HqnStart is run.

This file forms part of the bootstrap PostScript code, but is put in a separate file so that it is accessible. It is intended to load various resources, such as comment parsing procedures for loading “prep files”, and pre-load some fonts into memory. It is customizable (for example by varying the set of fonts loaded into memory), but we do not recommend further changes beyond those explicitly noted by comments in the file product specific initialization can be placed in Sys/HqnOEM , which is run later.

The file SW/Config/FontSubstitution will automatically be run as the RIP boots. The user can edit the following information in that file:

• Default font to use
• Default CID font to use
• Font substitution table
• CID Font substitution table

In all cases the file is heavily commented and is intended to be self-documenting. Some creators of print jobs do not always obey the rules applicable to the use of font UIDs and, in particular, some fonts embedded in print jobs make illegal re-use of UIDs between unrelated fonts. Since font caching persists across print jobs and since UIDs are used in the font caching process to help identify and reuse a font, breaking the UID rules may cause glyphs rendered and cached in one print job to be rendered in place of glyphs from another font (in another job).

This problem can be avoided by using the /SuppressUniqueID user parameter, which is set true by default. In the file HqnStart, this value is temporarily set to false so that the RIP can pre-load fonts installed in the RIP and keep using UniqueID as an optimization for character rendering. HqnStart then resets this parameter to true, thus any font downloaded from a print job (such as fonts embedded in PDF files) will not have a UniqueID associated with it.

You can disable this parameter by setting it to false in the unlikely event that performance is affected for specific jobs.

An alternative approach used in older versions of the RIP, blacklisting specific font UIDs, is now deprecated. Support for this approach will be removed in a future release.

In Sys/HqnStart and all following files, the code must explicitly mount any disk used, other than os% . Any disk not mounted explicitly here is not available until Sys/BootDevices has been run, just before the server loop starts up.

• All files in the directory Sys/ExtraStart are run in arbitrary order.

These files are intended to provide an easy way to install or remove patches to the RIP.

• The file Sys/HqnProduct is run.

This file contains PostScript-language code specific to a particular RIP product. For example, this file can contain code specific to the GUI version of the RIP, when that code is unnecessary or undesirable for other versions of the RIP, such as the core RIP or command line driven versions. OEMs should not alter this file.

• The file Sys/HqnPlatform is run, if present.

This contains any PostScript-language initialization which is platform-dependent. If there is none, this file may not be supplied. This file should not be altered.

• The file Sys/HqnOEM is run, if present.

This file is where most OEM PostScript-language initialization should be put: see the further comments in The RIP in action.

Because these files are not run in the server loop (see The Harlequin server loop), they consume memory and are not protected against PostScript errors in the same way as an ordinary job. Therefore, where the PostScript-language code is complex and the results do not need to persist in VM, save and restore should be used to conserve VM. The exitserver and startjob operators cannot be used during start-up.

While it is possible to do graphical operations here, it is not recommended, and may not be practical as the normal environment for running a job is not present. In particular, in the GUI version, no page setup has been run so no output device or resolution other than the default have been identified.

• If the file Sys/Bootlist exists, the files listed in it are run; if not the two files Sys/Start and Usr/Start are run.

This behavior is provided mainly for compatibility with Adobe. Some specialized PostScript-language applications actually make changes to the Sys/Bootlist file, and others add things to Sys/Start.

All these files are run from stopped contexts, so do not need to exist if they are not used. Some font installers, and other utilities, replace one or other of these files rather than adding new code to them, so we do not recommend that you add your own code to them.

• The file Sys/BootDevices is run.

This file is relevant to the GUI RIP (and plugin-driven headless RIP) only it is not used by the core RIP or command-line RIP.

This file is created by the RIP skin each time that the RIP boots. It mounts in the PostScript-language environment all local hard (fixed) disks and networked drives that are mounted in the operating system at the time of starting up the RIP. The disks are named in PostScript based on their names in the operating system. For example: this file names the disks %C% , %D% , and so on, in DOS and Windows systems; and it names the disks according to their name on the Desktop in Macintosh systems. (It names only the root directory ( %/% ) in UNIX systems relying on all other disks being mounted onto some subdirectory of the root directory.)

All disks mounted in Sys/BootDevices are made unsearchable by filenameforall. This avoids a variety of problems (for example, with font downloaders).

• Finally, the server loop is started, as described in The Harlequin server loop.