constraint

Defines the constraint of a parameter. The structure of this object depends upon the constrainttype of the parameter. Range constraints are specified as an attribute of a param tag; Choice, Alarm Table, and Struct constraints are specified using constraint tags as children to the param object.

Constraints may be defined within a param declaration, or defined globally and referenced by specific parameters.

Syntax

Constraints with inline constraint values:

<constraint constrainttype="ctype" constraint="cvalue" id="constraint-id" />

Constraints defined within a param tag with inline constraint values:

<param constrainttype="ctype" constraint="cvalue" param-attributes />


 

Choice and Alarm Constraints:

<param constrainttype="ctype" param-attributes>

<constraint key-attributes>cvalue</constraint>

<constraint key-attributes>cvalue</constraint>

. . .

</param>

Choice and Alarm Constraints defined within a param tag:

<param constrainttype="ctype" param-attributes />

<constraint key-attributes>cvalue</constraint>

<constraint key-attributes>cvalue</constraint>

. . .

</param>

 

See sections below for examples and syntax for each constraint type.

Constraint Types

Constraint

Constraint Type

Param Type

Unconstained

INT_NULL

INT16_PARAM

INT16_ARRAY

INT32_PARAM

INT32_ARRAY

FLOAT_NULL

FLOAT_PARAM

FLOAT_ARRAY

Range Constraint

INT_RANGE

INT_STEP_RANGE

INT16_PARAM

INT16_ARRAY

INT32_PARAM

INT32_ARRAY

FLOAT_RANGE

FLOAT_STEP_RANGE

FLOAT_PARAM

FLOAT_ARRAY

Integer Choice Constraint

INT_CHOICE

INT16_PARAM

INT16_ARRAY

INT32_PARAM

INT32_ARRAY

String Choice Constraint

STRING_CHOICE

STRING_PARAM

STRING_ARRAY

Alarm Table

ALARM_TABLE

INT16_PARAM

INT32_PARAM

Constraint Reference

ID_REFERENCE

All

Structure

STRUCT

STRUCT_PARAM

STRUCT_ARRAY

Note             If no constraint is specified for a parameter, it will be unconstrained by default.

Refer to the appropriate section below for definition of the constraint object for each constraint type.

constraint (Unconstrained)

Specifies that a parameter is unconstrained. All parameters are considered unconstrained by default if no constraint is applied.

Syntax

<param constrainttype="constraint-type" attributes />

Attributes

Attribute

Values

Restrictions

Description

constrainttype

INT_NULL

 

param type:

INT16_PARAM

INT16_ARRAY

INT32_PARAM

INT32_ARRAY

Parameter is unconstrained

FLOAT_NULL

 

param type:

FLOAT_PARAM

FLOAT_ARRAY

Examples

The following constraint specifies an integer to be unconstrained:

<param constrainttype="INT_NULL" name="Delay" oid="0x500" type="INT16_PARAM"/>

constraint (Constraint Reference)

References a globally-defined constraint. A constraint may be specified globally in the <meta> block. These globally-defined constraints may then by referenced by specific parameters.

Syntax

<constraint id="constraint-id" constrainttype="constraint-type">

 

<param constrainttype="ID_REFERENCE" constraint="constraint-id" attributes />

Attributes

Attribute

Values

Restrictions

Description

id

String

 

Unique identifier for this constraint

constrainttype

Any valid constraint type

Param type must be compatible with the referenced constraint.

See Constraint Types for valid constraint types.

 


 

Examples

The following example creates a global constraint VideoFormat. Params 0x501, 0x502 and 0x503 are all constrained using this constraint definition.

<constraint constrainttype="INT_CHOICE" id="VideoFormat">

  <constraint key="0">480i-59.94</constraint>

  <constraint key="1">576i-50</constraint>

  <constraint key="2">1080i-29.97</constraint>

  <constraint key="3">1080i-25</constraint>

  <constraint key="4">720p-59.94</constraint>

  <constraint key="5">720p-50</constraint>

  <constraint key="6">1080p-59.94</constraint>

  <constraint key="7">1080p-50</constraint>

</constraint>

 

<param constrainttype="ID_REFERENCE" constraint="VideoFormat" name="Vid1" oid="0x501" type="INT16_PARAM"/>

 

<param constrainttype="ID_REFERENCE" constraint="VideoFormat" name="Vid2" oid="0x502" type="INT16_PARAM"/>

 

<param constrainttype="ID_REFERENCE" constraint="VideoFormat" name="Vid3" oid="0x503" type="INT16_PARAM"/>

constraint (Range Constraints)

Constrains a numeric parameter type to a specific range.  Minimum and maximum values effect the parameter’s valid range. Display minimum and maximum values scale the parameter value to a different range for display purposes. Finally a step value can be set to constrain the minimum step size a value may be changed by.

Syntax

Min / Max Constraint:

<param constraint="min;max;" constrainttype="constraint-type" attributes />

Min / Max Constraint with Display-Min and Display-Max:

<param constraint="min;max;display-min;display-max;"
    constrainttype="
constraint-type" attributes />

Min / Max Step Constraint:

<param constraint="min;max;step" constrainttype="constraint-type" attributes />

Min / Max Step Constraint with Display-Min and Display-Max:

<param constraint="min;max;display-min;display-max;step"
    constrainttype="
constraint-type" attributes />


 

Attributes

Attribute

Values

Restrictions

Description

constrainttype

INT_RANGE

INT_STEP_RANGE

param type:

INT16_PARAM

INT16_ARRAY

INT32_PARAM

INT32_ARRAY

Type of constraint

FLOAT_RANGE

FLOAT_STEP_RANGE

param type:

FLOAT_PARAM

FLOAT_ARRAY

constraint

min

Required

Minimum value to which a parameter can be set

max

Required

Minimum value to which a parameter can be set

display-min

Optional; must be used with display_max.

The displayed value of the parameter when the parameter has a value of min. The default value is min.

display-max

Optional; must be used with display_min.

The displayed value of the parameter when the parameter has a value of max. The default value is max.

step

xxx_STEP_RANGE constraints only

Smallest increment a value may be changed by. Spinner widgets will increment a parameter by the step value. Note that the step increment is applied to the parameter value, not the display value.

Examples

The following example constrains a FLOAT_PARAM to [0,100]:

<param constraint="0.0;100.0;" constrainttype="FLOAT_RANGE" name="Delay" oid="audio.delay" type="FLOAT_PARAM"/>

The following example constrains an integer to [0, 255] mapping it to a display range of [0, 100], and the value increments by steps of 2:

<param constraint="0;255;0;100;2" constrainttype="INT_STEP_RANGE" name="Gain" oid="key1.gain" type="INT16_PARAM"/>

constraint (Integer Choice Constraints)

Choice constraints provide a list of possible values for a parameter, based upon a text selection. For integer parameters, the parameter may only be assigned a value specified in the constraint.

Syntax

<param constrainttype="INT_CHOICE" type="param-type" attributes >

<constraint key="choice1-key">choice1-value</constraint>

<constraint key="choice2-key">choice2-value</constraint>

. . .

</param>

Attributes

Attribute

Values

Restrictions

Description

type

INT16_PARAM

INT32_PARAM

INT16_ARRAY

INT32_ARRAY

 

Parameter must be integer type.

key

Integer

 

Numeric assignment of current enumerated choice.

value

String

 

Text name for the current enumerated choice

Examples

The following constraint provides an enumerated choice:

<param constrainttype="INT_CHOICE" name="Channel" oid="0x503" type="INT16_PARAM">

  <constraint key="0">Channel 01</constraint>

  <constraint key="1">Channel 02</constraint>

  <constraint key="2">Channel 03</constraint>

  <constraint key="3">Channel 04</constraint>

</param>

constraint (String Choice Constraints)

Choice constraints provide a list of possible values for a parameter, based upon a text selection. For String parameters, the constraint provides a set of defaults, but the user may arbitrarily enter any other value for the parameter.

Syntax

<param constrainttype="STRING_CHOICE" type="param-type" attributes >

<constraint>value</constraint>

<constraint>value</constraint>

. . .

</param>

Attributes

Attribute

Values

Restrictions

Description

type

STRING_PARAM

STRING_ARRAY

 

Parameter must be string type.

value

String

 

Available strings for drop-down widget

 


 

Examples

The following constraint provides five string options for a String parameter.

<param constrainttype="STRING_CHOICE" name="Name" oid="0x504" type="STRING_PARAM">

  <constraint>Zeus Test Card</constraint>

  <constraint>ZTC</constraint>

  <constraint>Johnny</constraint>

  <constraint>Matilda</constraint>

</param>

Figure 76 – String Choice

constraint (Alarm Table)

Alarm constraints map a set of alarms as bitfields into an INT16_PARAM or INT32_PARAM. Each bit represents an independent alarm which may have a message and severity assigned to it. Alarm parameters contribute to the device’s overall alarm status in DashBoard; the most severe alarm set will determine the device’s overall reported alarm status.

Syntax

<param constrainttype="ALARM_TABLE" type="param-type" attributes >

<constraint key="bit-number" severity="severity">value</constraint>

<constraint key="bit-number" severity="severity">value</constraint>

. . .

</param>

Attributes

Attribute

Values

Restrictions

Description

type

INT16_PARAM

INT32_PARAM

 

Parameter must be integer type.

key

Integer

INT16: 0..15

INT32:  0..31

The bit position for the alarm (0 is LSB).

 

severity

Integer

 

The severity of the alarm:

0 = OK

1 = WARN

2 = ERROR

value

String

 

Alarm message text

 


 

Examples

The following constraint creates an alarm table:

<param constrainttype="ALARM_TABLE" name="Alarm" oid="0x504" type="INT16_PARAM">

  <constraint key="0" severity="0">Hardware OK</constraint>

  <constraint key="1" severity="2">Hardware Error</constraint>

  <constraint key="2" severity="1">Flash Memory Full</constraint>

</param>

constraint (Struct Constraints)

Struct Constraints allow a parameter to define a complex structure of multiple parameters. The Struct Constraint is applied to each parameter that is an instance of a Struct.

Syntax

<param constrainttype="STRUCT" structtype="struct-type" templateoid="template-oid"

type="STRUCT" param-attributes>

Attributes

Attribute

Values

Restrictions

Description

type

String

Required

Set to "STRUCT"

templateoid

String

 

Specifies a template OID to pre-populate the structure. All parameters, constraints and widgets for the sub-OIDs are copied from the template.

structtype

String

Must be unique

Defines the structure type. Used by PanelBuilder to type-check custom widgets against defined struct parameters.

Examples

The following code is an example of a struct definition.

<param constrainttype="STRUCT" name="Clip Info" oid="clipInfo"

    structtype="playinfo" type="STRUCT" widget="36">

<value>

    <subparam name="Clip Name" suboid="ClipName" type="STRING" value="Test"/>

    <subparam name="Director" suboid="Director" type="STRING" value="Test"/>

    <subparam name="Date" suboid="AirDate" type="STRING" value="Test"/>

    <subparam name="Author" suboid="Author" type="STRING" value="Test"/>

</value>

</param>


 

The following declaration utilizes the previous example as a template, by specifying the templateoid attribute:

<param constrainttype="STRUCT" name="Clip List" oid="clipList"

structtype="playinfo" templateoid="clipInfo" type="STRUCT_ARRAY" widget="36">

<value>

    <subparam suboid="ClipName" value="Winter is Coming"/>

    <subparam suboid="Director" value="Tim Van Patten"/>

    <subparam suboid="OriginalAirDate" value="April 24, 2011"/>

    <subparam suboid="Author" value="David Benoiff &amp; D.B. Weiss"/>

</value>

<value>

    <subparam suboid="ClipName" value="The Kingsroad"/>

    <subparam suboid="Director" value="Brian Kirk"/>

    <subparam suboid="OriginalAirDate" value="April 24, 2011"/>

    <subparam suboid="Author" value="David Benoiff &amp; D.B. Weiss"/>

</value>

<value>

    <subparam suboid="ClipName" value="Lord Snow"/>

    <subparam suboid="Director" value="Brian Kirk"/>

    <subparam suboid="OriginalAirDate" value="May 1, 2011"/>

    <subparam suboid="Author" value="David Benoiff &amp; D.B. Weiss"/>

</value>

<value>

    <subparam suboid="ClipName" value="A Golden Crown"/>

    <subparam suboid="Director" value="Daniel Minahan"/>

    <subparam suboid="OriginalAirDate" value="May 22, 2011"/>

    <subparam suboid="Author" value="David Benioff &amp; D. B. Weiss"/>

</value>

</param>