ValRep

This property defines the possible values that the field accepts. The ValRep consists of a Uniface list of one or more items, in which each item consists of a value and optional representation.

Item1{;Item2{;ItemN}

Item can be:

  • List item: Value1{=Representation1}

    Example: EN=English; FR=French;DE=German.

  • Range: MinValue{:MaxValue}{=Representation1};{MinValue2{:MaxValue2}{=Representation2}...}

    Example: -5:10

    Example: "1:3=Low;4:6=Medium;7:10=High"

Arguments

  • Value—possible value of a field

    Note:  Although it is possible for a value of up to 511 bytes to be stored, validation fails for values larger than 289 bytes.

  • Representation—visible representation of the field’s value. If no representation is given, the actual field value is used instead. For widgets that support it, the Representation can include an icon preceding the text.
  • ;—list item separator (by default, Gold ;).
  • MinValue—lowest value allowed for the item.
  • MaxValue—highest value allowed for the item.

Description

ValReps can be defined for fields that have a limited number of allowed values. When a value is entered, selected, or stored Uniface uses the ValRep to validate the data in the field.

The widget associated with the field interprets the ValRep and determines whether and how the ValRep is displayed and which parts are used. For example:

  • The editbox, and many other widgets, do nothing with the ValRep.
  • A drop-down list uses all the items in the ValRep to build the options in its displayed list. If possible, it uses the representations, otherwise it displays the values.
  • A spinner widget uses only the first range item (MinValue : MaxValue) and ignores any representations.
  • The meter widget supports multiple ranges and Representation property can be used to specify a color associated with a range.
  • The tree widget uses ValReps to populate its structure.

It is the developer's responsibility to ensure that the ValRep matches the requirements of the widget.

Note: There can be differences in the way similar widgets in different types of components behave. For example, a DropDownList in a form can handle a ValRep such as "1:5=One to five;11:15=Eleven to fifteen", whereas a DropDownList in a DSP generates a format error.

The following field ValReps are all valid from a data point of view and can be used when validating the data, but they cannot be interpreted and displayed by all widgets:

  • "1"
  • "1=One"
  • "1:5"
  • "1:5=One to five"
  • "1;2;3;4;5"
  • "1=One;2=Two;3=Three;4=Four;5=Five"
  • "one=1;two=2"
  • "1:5;11-15"
  • "1:5=One to five;11:15=Eleven to fifteen"
  • "-15:-11;0;11-15"
  • "-15:-11=From minus fifteen to minus eleven;0=Zero; 11:15=From eleven to fifteen"

For more information, consult the documentation for the widget you intend to use.

Defining the ValRep

For simple ValRep lists, you can define a ValRep declaratively in the IDE (either in the ValRep property or the Widget Properties of widgets that support ValReps).

ValRep property dialog

For longer or more complex ValReps, use ProcScript. You can use $valrep to define the ValRep list for a field, or $fieldvalrep to define the ValRep of a field occurrence.

You can use list processing ProcScript instructions (for example, delitem, getlistitems, sort/list) to manipulate the list of values and representations.

ValRep Validation

ValRep lists are useful in restricting user input to valid values. Uniface uses the values defined in a ValRep list when performing syntax checks for fields at runtime. A user cannot enter a value that does not match the value or range of values specified in the ValRep list.

Note:  If you have a ValRep list of more than 32,768 items, you should set the $NO_VALREP_CHECK assignment setting to prevent this syntax check. A ValRep list of this size is not very practical for a user, and should be avoided.

Escaping Separators

The colon (:), percentage (%), and equal (=) signs are not allowed as ordinary characters in the Value part of a ValRep list.

Any equals sign (=) defined in the Value or Representation must be preceded by a percent sign and any subfield separator must be preceded by the retrieve profile used for logical NOT (GOLD !).

For example, in the following ValRep list:

C%:\me\you\them=Path 1;C%:\you\me\them=Path 2;C%:\them\us=Path 3;C%:\nowhere=Path 4

The ValueC:\nowhere is represented by Path 4.

Percentage signs are allowed in Value if they are followed by another character that is not an equal sign or colon. For example:

34% or worse=FAIL;mark %= 35% exactly=RE-SIT EXAM;36% or better=PASS

The interpretation of escape characters occurs during validation, either an implicit validation (for example, when displaying in a widget) or with an explicit validate statement.

Empty String Values

To define an item in a ValRep list as a NULL value, leave the Value part for that item empty. You can represent NULL values in lists as text strings or as empty items.

For example, if you want users to see a NULL value represented as the text "None" in a list box, specify None in the Representation and leave the corresponding Value part empty.

Test for NULL values by testing for an empty string (""). Uniface tests for values in Value, not for values in Representation.

Multiple Selections

If the widget supports multiple selection, the field should be defined with subfields. If the user selects multiple items in a widget, Uniface creates an indexed list of the corresponding values, with items separated by the subfield separator, by default, Gold ;.

Applies to

Related Topics