(v13) How common errors are handled

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

The sub-sections of this page describe ways a plugin might handle various typical errors.

If the plugin cannot begin to output a page because of some error condition that can easily be fixed, it could produce a warning (reporting DETYPE_CONTINUE with a suitable error code) and not proceed with the actual output until the error has cleared.

When the error has cleared, then it can change back to:

DERR (DETYPE_CONTINUE, DERR_NONE)

and continue with the normal output sequence. See the description of dealing with Paper out , for an example of how this works.

If the plugin has to abandon output of the page, but must carry out further processing before reporting DETYPE_ABORT (which does not give it multiple calls of D_CLEAR_ERROR and D_IDLE ), then it can report DETYPE_CONTINUE and a DERR code resulting in a status message. It can then continue with its tidy‐up code until it is ready to report a DETYPE_ABORT . Alternatively, it can report a DETYPE_RESEND in order to be given repeated D_IDLE and D_CLEAR_ERROR calls to do its tidying up, and then set a DETYPE_ABORT code which will abort.

Note that D_CLEAR_ERROR is called whenever the error status changes, including when the error is cleared, so for example after a D_IDLE / D_CLEAR_ERROR loop completes, the D_CLEAR_ERROR selector will be called once more as the change from some error to no error is detected.

If the plugin sets an error that will terminate the current raster output (that is, an error with any type except for DETYPE_CONTINUE ), it should not access any raster band data after raising this error. Failure to comply with this may cause the plugin and RIP to crash.

Paper or film jam

How to handle paper and film jams depends largely on how difficult it is to unjam the output media.

On a fixed media device such as a plain paper laser printer, clearing a paper jam could be quite simple, hence a reasonable way to handle the error is to set DETYPE_RESEND . When the RIP loops calling D_IDLE and D_CLEAR_ERROR , the plugin can poll the printer to determine whether the jam has cleared. When it has been cleared, setting DETYPE_CONTINUE allows the RIP to close the “jammed” page, and then re‐send it.

On a film recorder, it may be more appropriate to set DETYPE_ABORT , as it could well be a more lengthy and complex job to unjam roll‐fed media.

Paper out

This error occurs when there is no paper or film remaining in the device.

Once again, how best to deal with the error probably depends on the device the plugin is sending out‐ put to. The simplest response would be to report DETYPE_ABORT . However, it may be preferable for output to restart as soon as more paper has been loaded. There are a number of ways of doing this.

If the paper runs out before the RIP starts to output the page, and the lack of paper is detected in the D_OPEN call, then the plugin can report it as a DETYPE_CONTINUE error, with a DERR code indicating the ‘paper out' status. The plugin can wait until the condition has cleared before performing any actual output from D_OUTPUT or D_IDLE calls. The RIP will continue to generate bands and call D_OUTPUT until it runs out of band space, at which point it will start making D_IDLE calls. When the error condition clears, the plugin can change the d_error value to DERR (DETYPE_CONTINUE , DERR_NONE) , and begin to output the page. When the RIP notices that bands have become free as the plugin has output data, it start to fill bands with data and call D_OUTPUT again. (The RIP can see how many bands are free from the d_linescopied field of the deviceDefinition structure.)

An alternative would be to report the error as a DETYPE_RESEND error, and allow the RIP to loop, attempting to resend the page until the D_OPEN call discovers that the ‘paper out' condition is over.

The advantage of the first method is that if the page is stored on disk, the RIP will not have to re‐read the pagebuffer at each re‐send. The RIP will be able to use that time to deal with other tasks, such as interpreting incoming jobs.

Data underrun

Data underrun occurs when the plugin is unable to supply data to the device fast enough. The plugin may or may not need to treat this as an error, depending on whether the device can be stop–started  that is, can be stopped until more data is available, and then restarted.

It also depends on whether the user has agreed that it is acceptable to stop–start the device: in some cases, performing a stop–start may impair the quality of the final output because it introduces alignment problems. For example, a capstan device might have to rewind the film to get back to where it left off but it requires a positional accuracy of a few microns, and only a very precisely‐adjusted mechanism can get it to that degree of accuracy. Getting a dot screen an even a few microns out of alignment can cause moire patterns, so precise alignment is very important.

If the device cannot stop–start, or if the user has forbidden stop–starting, the plugin should report the error

DERR(DETYPE_RESEND,DERR_DATA_UNDERRUN)

If the RIP is able and has not already done so, it will RIP the entire image to a pagebuffer file on disk and try resending the page, having closed the first one with D_CLOSE and with the c_abort flag set.

If the data underrun was reported during a page that had been read from a pagebuffer file, the RIP stops further output and seeks intervention from the user.

If the device can stop–start, the plugin should increment the d_stopstarts field in the deviceDefinition structure, to indicate that a stop–start occurred. The action the RIP takes after this depends on whether the user has permitted stop–starting.

If permitted, the increment of d_stopstarts is treated as a DETYPE_CONTINUE : The RIP may print a warning at the end of page output that a stop–start occurred, but does not treat it as an error by going into an error handling call sequence.