5Data Types
Data Types
This chapter provides descriptions of all data types used by the Siebel Connector for IAA-XML. It includes the following topics:
Definition of Data Types
The data types used in IAA-XML are as follows:
String
A string of characters (optionally containing blanks) for which a maximum length can be specified. String indicates an element that allows character data up to a maximum number of characters. The number after the hyphen specifies the maximum number of characters. For example, S-12 specifies an element of characters with maximum length 12 characters. S-8 indicates an element with no maximum length. It is expected that character type elements may contain multibyte representations of characters in some implementations, depending on the allowable character sets.
Text
A string of characters (optionally containing blanks) for which a maximum length cannot realistically be fixed.
Binary
A finite sequence of binary octets. The definition consists of three logical elements: content type, binary data and binary data length.
The Binary data type is a compound type consisting of three logical elements as shown in the following table:
| Tag | Type | Usage | Description |
|---|---|---|---|
<contentType> |
Enumeration |
Optional |
Specified in IETF RFC 2046. |
<binLength> |
Integer |
Required |
Identifies the size of the binary data in number of bytes. |
<binData> |
Raw Binary Data |
Required |
Binary data. |
Boolean
A logical TRUE or FALSE condition.
Date
An indication of a particular day in the Gregorian calendar. Elements of data type Date (as shown in the following table), contain an indication of a particular day. This data type describes a unique period of time, normally 24 hours (not a repeating portion of every year).
This data type must contain a 4-digit year, and may contain a month number and a day number.
| Date Data Type | Type | Usage | Description |
|---|---|---|---|
<year> |
Short |
Required |
4-digit year value. |
<month> |
Short |
Optional |
Number of the represented month. Value must be within the range 1 through 12. Must be included if <Day> is included. If absent, the value is assumed to be 1 (January). |
<day> |
Short |
Optional |
Number of the represented day. Value must be within the range 1 through 31. If absent, the value is assumed to be 1. |
Time
An indication of a particular time in a day expressed with a maximum precision of one microsecond. Elements of data type Time (as shown in the following table), contain an indication of a particular time during a date. This data type describes a repeating portion of a day. That is, each time described (ignoring leap seconds) occurs once for each calendar date. Based on the IFX specification, it is required that a time data type be able to represent a specific period with indefinite precision. Milliseconds are the minimum required precision of the time data type.
A time represented using this data type must not be ambiguous with respect to morning and afternoon. That is, the time must occur once and only once each 24-hour period.
You should always specify the time zone to avoid ambiguous communication between clients and servers. The Time data type must not be ambiguous with respect to location at which the time occurs. If unspecified, the time zone defaults to Coordinated Universal Time (UTC).
| Time Data Type | Type | Usage | Description |
|---|---|---|---|
<hour> |
Short |
Required |
Number of the represented hour. Value must be within the range 0 through 23. |
<minute> |
Short |
Optional |
Number of the represented minute. Value must be within the range 0 through 59. Must be included if <Second> is included. If absent, the value defaults to 0. |
<second> |
Short |
Optional |
Number of the represented second. Value must be within the range 0 through 60. The value 60 is used only to represent leap seconds. Must be included if <Fraction> is included. If absent, the value defaults to 0. |
<fraction> |
Short |
Optional |
Number of represented microseconds. Value must be within the range 0 through 999,999. Particular implementations may choose to allow representations of smaller fractions. If absent, the value defaults to 0. |
<utcOffset> |
Short |
Optional |
Offset from UTC in minutes. Value must be within the range -720 through +720. Value is typically a multiple of 60 (an exact number of hours), but the offset may also include half and quarter hours. Generally should be included. If absent, the value defaults to 0, that is, UTC. |
Timestamp
An indication of a particular date and time expressed with a precision of one microsecond. Elements of data type Timestamp (as shown in the following table), contain the same information as DateTime values. Unlike that data type, Timestamp information is not intended to have meaning at the other end of the communication. In addition, microseconds are the minimum required precision of the time portion of this data type.
Timestamp is a type identical to DateTime but without semantic meaning between two machines. The general DateTime data type has meaning on both ends of the protocol (even though time synchronization is not required by this specification). Timestamp indicates an exact point in time with respect to the generating application. For example, a Timestamp value may be generated at a server when creating an audit response. The client application may return that value to the server in later requests, but the client software should not interpret the information.
| Timestamp Data Type | Type | Usage | Description |
|---|---|---|---|
<year> |
Short |
Required |
4-digit year value. |
<month> |
Short |
Required |
Number of the represented month. Value must be within the range 1 through 12. |
<day> |
Short |
Required |
Number of the represented day. Value must be within the range 1 through 31. |
<hour> |
Short |
Required |
Number of the represented hour. Value must be within the range 0 through 23. |
<minute> |
Short |
Required |
Number of the represented minute. Value must be within the range 0 through 59. |
<second> |
Short |
Required |
Number of the represented second. Value must be within the range 0 through 60. The value 60 is used only to represent leap seconds. |
<fraction> |
Short |
Required |
Number of represented microseconds. Value must be within the range 0 through 999,999. Particular implementations may choose to allow representations of smaller fractions. |
<utcOffset> |
Short |
Optional |
Offset from UTC in minutes. Value must be within the range -720 through +720. Value is typically a multiple of 60 (an exact number of hours), but the offset may also include half and quarter hours. Generally should be included. If absent, the value is assumed to be 0, i.e. time is assumed to be UTC. |
TimeDuration
A duration of time expressed in years, months, days, hours, minutes, and seconds as described in the following table:
| TimeDuration Data Type | Type | Usage | Description |
|---|---|---|---|
<years> |
Short |
Required |
4-digit year value. |
<months> |
Short |
Required |
Number of the represented month. Value must be within the range 1 through 12. |
<days> |
Short |
Required |
Number of the represented day. Value must be within the range 1 through 31. |
<hours> |
Short |
Required |
Number of the represented hour. Value must be within the range 0 through 23. |
<minutes> |
Short |
Required |
Number of the represented minute. Value must be within the range 0 through 59. |
<seconds> |
Short |
Required |
Number of the represented second. Value must be within the range 0 through 60. The value 60 is used only to represent leap seconds. |
Number
A numeric count not requiring any units.
Byte
A signed integer between -128 and +127, of type Number.
Integer
A signed integer between -2147483648 and +2147483647, of type Number.
Short
A signed integer between -32768 and +32767, of type Number.
Decimal
Decimal indicates a numeric value that is up to fifteen digits in length, excluding any punctuation such as sign, decimal, currency symbol and so on. The value is not restricted to integer values and has a decimal point that may be placed anywhere from the start of the value to the second last digit in the value, but not after the last digit (for example: +.12345678901234 is acceptable while 12345678901234567 is not).
Percentage
A percentage.
Amount
A numeric count including units, such as liters, inches, or kilometres per liter. For example, 150 km/l. An amount is a compound data type consisting of two logical elements as described in the following table:
| Tag | Type | Usage | Description |
|---|---|---|---|
<amount> |
Decimal |
Required |
Amount. |
<unit> |
String |
Required |
Unit. |
Currency Amount
A monetary amount including the currency. A Currency Amount is a compound data type consisting of two logical elements as described in the following table:
| Tag | Type | Usage | Description |
|---|---|---|---|
<amount> |
Decimal |
Required |
Amount. |
<currencyCode> |
String |
Required |
Currency code. |
All monetary amounts in IAA-XML are handled with the Currency Amount data type. When included, this data type contains a decimal value for the amount, and an optional three-letter currency code defined in ISO-4217.
Enumeration
A value out of a limited set, each with a specific mutually exclusive meaning.
Enumeration is a Value type that has a limited number of specified valid values, each of which is represented by a tag of up to 80 characters each.
At this point, the IAA-XML specification does not provide a syntax to define permitted values for an Enumeration type. Where defined, the permitted values will be found in the description of a property.
Short
A signed integer between -32768 and +32767.
Identifier
A value without business meaning that uniquely distinguishes an occurrence.
Object Reference
An identifier, unique across both space and time, with respect to the space of all Object references.
XML Schema, IAA-XML, and IFX Data Types
The W3C committee is defining a schema to be used for XML message definition and validation. One of the advantages of using the XML schema over DTDs is the ability to use and validate data types. The schema implementation is not yet available, however, forcing the first implementation of IAA-XML to use DTDs.
Oracle has examined the XML schema draft specification of data types, found at http://www.w3c.org/TR/2000/WD-xmlschema-2-20000225, and compared them with the IFX data types, as shown in the following table.
| IAA-XML Data Types | IFX Data Type | XML Schema Primitive Data Type |
|---|---|---|
String |
Character |
String |
Text |
||
Not supported |
Narrow Character |
String with a length attribute specified |
Binary |
Binary |
Binary |
Boolean |
Boolean |
Boolean |
Not supported |
YrMon |
TimeInstant with the with the day, hour, minute, and second omitted |
Date |
Date |
TimeInstant with the hour, minute, and second omitted |
Time |
Time |
TimeInstant with the year, month, and day omitted |
Not supported |
DateTime |
TimeInstant with seconds expressed as integers |
Timestamp |
Timestamp |
TimeInstant with decimal values included in seconds |
Amount |
||
Currency |
Amount Currency |
Amount Not supported |
Not supported |
Closed Enum |
Supported by enumeration attribute of each data type |
Enumeration |
Open Enum |
Supported by enumeration attribute of each data type |
Short |
Long |
Supported by length attribute on decimal, with scale attribute of 0 |
Identifier |
Identifier |
ID |
Not supported |
Phone Number |
Not supported |
Decimal |
Decimal |
Decimal |
Not supported |
Universally Unique Identifier (UUID) |
Not supported |
Not supported |
URL |
URI-reference |
XML schema has additional primitive data types for float (floating point number), double (double precision floating point number), TimeInstant, TimeDuration, RecurringInstant, IDREF (like IDREF in DTDs), ENTITY (like ENTITY in DTDs), and NOTATION (like NOTATION in DTDs). In addition, XML schema has derived data types that are specializations of primitive data types, such as language, integer, date, time, and name. In addition it supports user-defined data types.
Furthermore, the date and time formats for IFX, although functionally equivalent, are implemented differently. The IFX timestamp specification is the same as the XML schema format. If IAA-XML users choose to implement IFX conventions for other date and time formats in adapters, those adapters will have to change when XML schema has been adopted. Except for timestamp, IAA-XML DTDs will not use the IFX date and time data types at this time; they are defined only for consistency.
Date and Time Formats
Time is specified at the hub in a character format at the moment, with no validation expected. Siebel highly recommends users follow the ISO8601 standard, which is the proposed standard for dates and times in XML schemas. The ISO8601standard specifies time as follows:
CCYY-MM-DDThh:mm:ss.sssZ
Where CCYY is the year, MM is the month, DD is the day, T is the literal T used as a date-time separator, hh is the hours using a 24 hour clock, mm is minutes, and ss.sss is seconds. The Z indicates that the time is in Coordinated Universal Time (UTC). To indicate a timezone different from UTC follow the time with ±hh:mm to signify the difference from UTC and omit the 'Z'. The followings are examples of valid and equivalent times:
2000-04-06T19:30:40Z signifying GMT
2000-04-06T20:30:40+1:00 signifying CET
2000-04-06T13:30:40-6:00 signifying CT (US)
ISO8601 also specifies the format for time duration. It allows the omissions of parts of the date and time. This can be useful when you are only interested in the underwriting year or the renewal month and year. The following representation is used to achieve this:
PnYnMnDTnHnMnS
An optional preceding '-' (before the P) may be specified to signal a negative duration. For example, P1Y2M3DT10H30M signifies 1year, 2 months, 3 days, 10 hours and 30 minutes; -P10Y means 10 years ago. The specification may be truncated. Time periods can be specified using several combinations of times: the start instant and a duration, the start instant and end instant, or the end instant and a negative duration.