Associative Lists

Each item in an associative list consists of a pair of associated values separated by an equal sign (=), such as a property and its value, or a value and its representation.

For example:

  • Property list: Color=255; Width=100; Depth=200; DisplayOnly; Charset=Ascii
  • ValRep list: EN=English; FR=French; DE=German

    Note: A ValRep list is an associative list that defines the possible values a field, and the way they are represented in a widget. The first value in the pair is the value stored in the database and the second value is the displayed representation. This makes it possible to store a short value for a field, while displaying a more meaningful representation. For more information, see ValRep Lists and Ranges .

The first and second values in an associative list item can be returned in Proc by the functions $idpart and $valuepart, respectively. For this reason, the format of an associative list item can be expressed as:

IdPart=ValuePart

Tip: This means that in ValRep lists, the Value is the IdPart and the Representation is the ValuePart.

For each item in an associative list:

  • The IdPart is limited to 289 bytes; the ValuePart can be any length.

    Note:  An IdPart of 511 bytes can be stored, but it cannot be validated.

  • The ValuePart can be referenced by its associated IdPart.
  • If no equal sign is present, all the data in the item is treated as both the IdPart and ValuePart. For example, the list item Monday is equivalent to Monday=Monday.
  • If either value in the pair is empty (for example color= or =None), the IdPart and ValuePart is considered to be empty.
  • A list item that has no values and no equal sign is empty. For example, the following list contains four items; the first and fourth of these are empty: ";B=Tuesday;C=Wednesday;"

Escaping Separator Characters

The colon (:), percentage (%), and equal (=) signs are not allowed as ordinary characters in the first or second value of a list item. To treat these as literal characters, they must be preceded by a percent sign (%). For example:

  • "1=A%=B;2=A%=C"
  • "12%:00%:00=noon"

Percentage signs are allowed 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

Any subfield separator must be preceded by the retrieve profile used for logical NOT (GOLD !). This allows you to use the subfield separator in the value or representation of a list item. For example: 

"Mon=Monday;Tue=Tuesday;Wed=Wednesday;Thu=Thursday;Fri=Friday;Weekend=Sat!;Sun"

Related Topics