Property Value Syntax and Ranges

This section describes how property values are formatted to be appropriate for their data types. Property values for applications occur in four places:

  • the value attribute of property elements in the OAS XML

  • in the file indicated by the valueFile attribute of property elements in OAS XML

  • on the ocpirun command line when options are used to set property values

  • in C++ when the ACI is used to apply property values to applications (the ACI is described in the API for Executing XML-based Applications in C++/Python: ACI topic)

The syntax accepted depends on the type of the property whose value is being set, and certain quoting requirements depend on the context where the value is specified.

In XML attributes: Attribute values in XML syntax are in single or double quotes. The property value syntax described below is used inside these quotes (in the OAS). To have quotes inside XML attribute values, the other type of quotes is used to delimit the attribute value. In either case, inside the quoted attribute value, the & and < characters must be escaped using the official XML notations: &amp; for & and &lt; for <. If both types of quotes must be in an attribute value, then the official XML escape sequences for the quotes can be used: &quot; for double quote, and &apos; for single quote. 1

On the shell command line: Similarly, when used on the command line for ocpirun, the shell quoting rules are different than in XML. If the property value has no single quotes at all, then using single quotes for the shell command line argument is the most convenient when any of the shell’s metacharacters are in the property value. The shell metacharacters are these:

|    &   ;    ( )   < >   *    ?    [ ]    { }    space    tab

If single quotes are in the value, or if shell variable or history expansion is required, the QUOTING section of the shell/bash manual page defines how to escape them.

In a C++ program: In C++, the values will be defined in double-quoted string literals, where only double-quote characters and backslash characters must be escaped by preceding them with a backslash.

These XML/shell/C++ rules are applied after the value is constructed according to the general property value syntax defined below.

Property values are also used when creating component specifications and workers. That usage is described in the OpenCPI Component Development Guide, but the format is as described here.

Values of Unsigned Integer Types: uchar, ushort, ulong, ulonglong

These numeric values can be entered in decimal, octal with leading zero, or hexadecimal with leading 0x. The limits are the typical ranges for unsigned 8, 16, 32, or 64 bits respectively.

The uchar type can also be entered as a value in single quotes, which indicates that the value is an ASCII character, with backslash escaping as defined in the C language. The syntax inside the single quotes is as described for the char type below.

Values of Signed Integer Types: short, long, longlong

These numeric values can be entered in decimal, octal with a leading zero, or hexadecimal with a leading 0x, with an optional leading minus sign to indicate negative values. The limits are the typical ranges for signed 16, 32, or 64 bits respectively.

Values of the Type: char

This type is meant to represent a character, i.e. a unit of a string. In software it is represented as a signed char type, with the typical numeric range for a signed 8-bit value. The format of a value of this type is simply the character itself, with the typical set of escapes for non-printing characters, as specified in the C programming language and IDL:

\n   \t   \v   \b   \r   \f   \a   \\   \?   \'   \"

A series of 1-3 octal digits can follow the backslash, and a series of 1-2 hex digits can follow \x.

OpenCPI adds two additional escape sequences as a convenience for entering signed and unsigned decimal values of type char. The sequence \d may be followed by an optional minus sign (–) and one to three decimal digits, limited to the range of -128 to 127. The sequence \u can be followed by one to three decimal digits, limited to the range of 0 to 255.

These escapes can also be used in a string value. Due to the requirements of the arrays and sequence values (see below), the backslash can also escape commas and braces, i.e.:

\,    \{    \}

Values of the Types: float and double

These values represent the IEEE floating point types with their defined ranges and precision. The values are those acceptable to the ISO C99 strtof and strtod functions respectively.

Values of the Type: bool

These values represent the Boolean type, which is logical true or false. The values can be case insensitive: true or 1 for a true value, and false or 0 for a false value.

Values of the Type: string

These values are simply character strings, but also can include all the escape sequences defined for the char type above. Due to the requirements of arrays and sequence values, the backslash can also escape commas and braces (\, and \{ and \} ). Double quotes may be used to surround strings, which protects commas, braces, and leading or trailing white space. To be interpreted this way, the first character must be a double quote. Two double quotes can represent an empty string.

Values in a Sequence Type

Values in a sequence type are comma-separated values. When the type of a sequence is char or string, backslash escapes are used when the data values include commas.

Values in an Array Type

When a value is a one-dimensional array, the format is the same as the sequence, with the number of values limited by the size of the array. If the number of comma-separated values is less than the size of the array, the remaining values are filled with the null value appropriate for the type. Null values are zero for all numeric types and the type char. Null values for string types are empty strings.

Values in Multidimensional Types

For multidimensional arrays or sequences of arrays, the curly brace characters ( { and } ) are used to define a sub-value. For example, a sequence of 3 elements, each consisting of arrays of length 3 of type char, would be:

{a,b,c},{x,y,z},{p,q,r}

This would also work for a 3 x 3 array of type char. Braces are used when an item is itself an array, sequence, or structure recursively.

Values in Struct Types

Struct values are a comma-separated sequence of members, where each member is a member name followed by white space, followed by the member value. A struct value can be “sparse”, i.e. only have values for some members. If the struct type was:

struct { long el[2][3]; string m2; char c; }; // C pseudo code

A valid value would be:

el {{1,3,2},{4,5,6}}, c x

This struct value would not have a value for the m2 member. Unmentioned members have null values.

Expressions in Property Values

Both numeric and string typed scalar values can be specified using an expression syntax and operator precedence from the C language, where any parameter property with a value can be accessed as a variable. All C expression operators can be used except the comma operator, assignments or self-increments/decrements. The conditional operator using ? and : is supported. Expressions can be used as elements of arrays or sequences, or as structure member values.

For example, if the nbranches property was a parameter, a valid expression elsewhere might be:

nbranches == 0x123 ? 2k-1 : 0177

Numeric Values

The numeric constant syntax is typical C language syntax (integer and floating point), with the following additions:

  • Integers with explicit radix after a leading 0 can use 0t for base 10 and 0b for base 2, in addition to the normally used 0x for base 16 and no letter for base 8. All these prefixes can be applied to the fraction and exponent for floating-point syntax.

  • Integers can use a letter suffix of K, M, or G, upper or lower case, indicating 2^10, 2^20 or 2^30 respectively. E.g. 2k-1 is 2047.

  • All arithmetic is done using a numeric data type exceeding the range and precision of uint64_t, int64_t and double, and then assigned to the actual data type of the property whose value is being specified.

  • The ** binary operator (pow) from the python and FORTRAN languages is also supported.

When the value of the expression is assigned to the property value or numeric property attribute (e.g. ArrayLength), it is range checked for validity. Boolean properties are set to true if the value is non-zero. Fractions are discarded when assigning values to integer types.

String Values

Within expressions, string constants (using double quotes as in C) and string-valued parameter properties can be used. All comparison operators are case sensitive and result in boolean numeric values (0 or 1). All operators requiring boolean values (!, ||, &&, ?:) use the length of the string (zero being false, otherwise true). The + operator concatenates strings. There is no implicit or explicit conversion between string values and numeric values. E.g. if sparam is a string-typed parameter with the value abc, then this expression has the numeric value of 1:

sparam == "abc"

This expression would have the string value xyz_abc:

"xyz_" + sparam

Expressions Used for String Values

To distinguish when a string value is an expression, as opposed to a string that might look like an expression, the string value must have a special prefix of \: (backslash followed by colon). So if a property (or sequence/array element or structure member) is a string type, any value assigned to it is considered not to be an expression by default. To make the string value interpreted as an expression, use the \: prefix.

So if sparam is a parameter with value abc, then specifying the property’s string value

sparam+"xyz"

would simply define that exact string (with plus sign and double quotes included) but if the string value was:

\:sparam+"xyz"

then it would be interpreted as an expression, and the actual string value would be:

abcxyz
1

The details of XML attribute encoding can be found at Wikipedia XML Character Entities