When an application gets the value of a property, the value
can be converted by XMS into another
data type. Many rules govern which conversions are supported and how XMS performs
the conversions.
A property of an object has a name and a value; the value has an
associated data type, where the value of a property is also referred
to as the property type.
An application uses the methods of the PropertyContext class to
get and set the properties of objects. In order to get the value of
a property, an application calls the method that is appropriate for
the property type. For example, to get the value of an integer property,
an application typically calls the Get Integer Property method.
However, when an application gets the value of a property, the
value can be converted by XMS into another
data type. For example, to get the value of an integer property, an
application can call the Get String Property method, which returns
the value of the property as a string. The conversions supported by XMS are shown
in Table 1.
Table 1. Supported
conversions from a property type to other data typesProperty type |
Supported target data types |
String |
xmsBOOL, xmsDOUBLE, xmsFLOAT, xmsINT, xmsLONG,
xmsSBYTE, xmsSHORT |
xmsBOOL |
String, xmsSBYTE, xmsINT, xmsLONG, xmsSHORT |
xmsCHAR |
String |
xmsDOUBLE |
String |
xmsFLOAT |
String, xmsDOUBLE |
xmsINT |
String, xmsLONG |
xmsLONG |
String |
xmsSBYTE |
String, xmsINT, xmsLONG, xmsSHORT |
xmsSBYTE array |
String |
xmsSHORT |
String, xmsINT, xmsLONG |
The following general rules govern the supported conversions:
- Numeric property values can be converted from one data type to
another provided no data is lost during the conversion. For example,
the value of a property with data type xmsINT can be converted into
a value with data type xmsLONG, but it cannot be converted into a
value with data type xmsSHORT.
- A property value of any data type can be converted into a string.
- A string property value can be converted to any other data type
provided the string is formatted correctly for the conversion. If
an application attempts to convert a string property value that is
not formatted correctly, XMS may return
errors.
- If an application attempts a conversion that is not supported, XMS may return
an error.
The following rules apply when a property value is converted from
one data type to another:
- When converting a boolean property value to a string, the value
xmsTRUE is converted to the string "true", and the value false
is converted to the string "false".
- When converting a boolean property value to a numeric data type,
including xmsSBYTE, the value xmsTRUE is converted to 1, and the value
xmsFALSE is converted to 0.
- When converting a string property value to a boolean value, the
string "true" (not case sensitive) or "1" is converted to
xmsTRUE, and the string "false" (not case sensitive) or "0" is
converted to xmsFALSE. All other strings cannot be converted.
- When converting a string property value to a value with data type
xmsINT, xmsLONG, xmsSBYTE, or xmsSHORT, the string must have the following
format:
The string components are defined as follows:
- blanks
- Optional leading blank characters.
- sign
- An optional plus sign (+) or minus sign (-) character.
- digits
- A contiguous sequence of digit characters (0-9). At least one
digit character must be present.
After the sequence of digit characters, the string
can contain other characters that are not digit characters, but the
conversion stops as soon as the first of these characters is reached.
The string is assumed to represent a decimal integer.
XMS may return
an error if the string is not formatted correctly.
- When converting a string property value to a value with data type
xmsDOUBLE or xmsFLOAT, the string must have the following format:
- [blanks][sign][digits][point[d_digits]][e_char[e_sign]e_digits]
The string components are defined as follows:- blanks
- (Optional) Leading blank characters.
- sign
- (Optional) Plus sign (+) or minus sign (-) character.
- digits
- A contiguous sequence of digit characters (0-9). At least one
digit character must be present in either digits or d_digits.
- point
- (Optional) Decimal point (.).
- d_digits
- A contiguous sequence of digit characters (0-9). At least one
digit character must be present in either digits or d_digits.
- e_char
- An exponent character, which is either E or e.
- e_sign
- (Optional) Plus sign (+) or minus sign (-) character for the exponent.
- e_digits
- A contiguous sequence of digit characters (0-9) for the exponent.
At least one digit character must be present if the string contains
an exponent character.
After the sequence of digit characters, or the optional
characters representing an exponent, the string can contain other
characters that are not digit characters, but the conversion stops
as soon as the first of these characters is reached. The string is
assumed to represent a decimal floating point number with an exponent
that is a power of 10.
XMS may return
an error if the string is not formatted correctly.
- When converting a numeric property value to a string, including
a property value with data type xmsSBYTE, the value is converted to
the string representation of the value as a decimal number, not the
string containing the ASCII character for that value. For example,
the integer 65 is converted to the string "65", not the string "A".
- When converting a byte array property value to a string, each
byte is converted to the 2 hexadecimal characters that represent the
byte. For example, the byte array {0xF1, 0x12, 0x00, 0xFF} is converted
to the string "F11200FF".
Conversions from a property type to other data types are supported
by the methods of both the Property and the PropertyContext classes. However, the C functions xmsPropertyGetStringByRef() and xmsGetStringPropertyByRef() make
no attempt to convert a property value that is not a string. If an
application calls either of these functions to get a pointer to a
property value that is not a string, XMS may return
an error.