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.