D_IP_SETPARAMS

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

D_IP_SETPARAMS Selector

Parameter: SetparamsParam *param

Call type: Multi‐call

This selector assigns new parameters to the channel, or possibly the channel class. Parameters can be changed for a channel either by the user in the Input Manager’s Configure dialog, or from the PostScript language using the setdevparams operator.

Parameters cannot be changed for a channel class once it has been created. However, in principle, a channel class parameter dialog permitting this could be introduced in future.

The D_IP_SETPARAMS call says which fields have changed, but also gives both the old and new settings so that they can be changed as a consistent set. (If they are changed one by one, inconsistent naming may arise.)

TEXT

      typedef struct setparamsParam { int32 version ;
      int32 objectType ; void *objectContext ;
      int32 numItemsToChange ; int32 *itemIndexes ; void *previousStructIO ; MultiCallData multi ; IPStatus status ;
    } SetparamsParam ;

version

The version field should be ignored.

objectType

The RIP sets this to OBJTYPE_CHANNEL if the call refers to the parameters of a channel, and to OBJTYPE_CHANNELCLASS if it is a channel class.

objectContext

The RIP sets this to point to the channelContext structure for the channel if objectType is OBJTYPE_CHANNEL , or to the channelClassContext structure for the channel class if objectType is OBJTYPE_CHANNELCLASS .

numItemsToChange

The number of items in the itemIndexes array.

At version 4.5 of the RIP, plugin interface version 12.0, this is always set to 1, meaning that D_IP_SETPARAMS is called once for each parameter. This can cause problems with configuration, especially where some combinations of parameters are illegal, because only one parameter can change at each call. One possible solution is to tolerate transient invalid states during configuration, but not during use of the plugin.

itemIndexes

An array of integers indicating which of the plugin’s parameters have changed. See Input and output plugin parameters and plugin dialogs for details of plugin parameters. The numbers are indexes into the array of DICTSTRUCTION s, which are the template for the parameters of either the channel or channel class according to objectType .

Because these structures are provided by the plugin in the first place, it can easily determine, either via its copy of the DICTSTRUCTION or a simple switch statement, to which fields of the channelContext ’s channelSTIOData the indexes refer—and similarly for channel classes.

The plugin should change its state to reflect these parameters. For a serial line this might mean changing the baud rate and parity type. If the parameters do not form a consistent set, then none of them should be changed. This may require a change to be made and then backed off, so the RIP provides the old values. These values, found in previousStructIO , can be referred to using the same index.

previousStructIO

The previous settings for the parameters. For parameters which do not appear in the itemIndexes list, the values should, of course, be identical.

multi

Controls the sequence of calls to the selector. See The MultiCallData structure .

status

The plugin should set the IPmajor field of this IPStatus structure as follows:

IPS_OK

The call was successful.

IPS_LOCKED

It is temporarily impossible to change one or more of the parameters.

The plugin should leave them all alone.

The RIP keeps trying to change the parameters at short intervals. How‐ ever if a job arrives on the channel—that is, if dataAvailable is set by the tickle function—before it has become possible to change the parameters, the job proceeds with the old settings, and upon completion further attempts are made to change the parameters.

IPS_FAIL

It is impossible to change one or more of the parameters. This might be because the wrong parameter name was sent. If this is set, the RIP automatically restores the original parameter values in the structIO .