(v13) Plugin call return values
This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core
The plugin entry function, PLUGIN
, must return a value to the RIP when the call is complete. This is in addition to any results of operations the call requested—those results are not returned directly but instead by direct modification of the data structures pointed to in the arguments sent with the call.
Return values must be generated according to these rules:
- If the plugin supports the selector, and if the operation requested completes without a fatal soft‐ ware error, the
PLUGIN
routine must return the valueNOERR
. The constantNOERR
is defined in the plugin kit header files.
Caution: ReturningNOERR
is not taken to mean that the action has succeeded, just that the plugin has accepted the selector. - If the plugin does not support the selector, or if the attempt to perform the operation requested by the selector has resulted in a serious failure in the plugin code such that the plugin is no longer usable, the
PLUGIN
routine must return-1
. This may cause the RIP to shut down gracefully, or, in Single mode, it may cause the current job to be aborted.
Note that the D_SELECTOR_SUPPORT
call is the only one which is normally allowed to return -1
. Plugins which can potentially return -1
from other selectors to indicate an unrecoverable failure should remember this status, and immediately return -1
from any further calls to the PLUGIN
function.
- Recoverable errors are indicated by setting a suitable error code in
d_error
. For more information see section d_error (deviceDefinition) and (v13) Error Handling in Output Plugins.