All "normal" API parameters (those not described as being represented as XSLM-specific data elements), both for the Application API and the Management API, use the data representation commonly used within the particular environment in which the application is executing - it is up to the licensing agents to transform the data as needed.
The API definitions use several type definitions, loosely defined later
in this chapter. The formal definitions are provided in
Multi-byte values are stored as a sequence of bytes, in such an order that the left-most byte is the most significant byte. Within such a multi-byte value, the bytes are numbered from the left, starting with 0. Individual bits within such a multi-byte value can be referred to either by its bit position within a particular byte, or as its bit position within the multi-byte value, again starting the numbering from the left-most bit as bit 01.
This data type is referred to as DTP_FIXED.
This data type is referred to as DTP_FLOAT.
All compliant licensing systems must be able to correctly process and display the Unicode Basic Latin character range. Other UCS characters must be correctly processed, but need not be displayable. However, any non-displayable character must still be included as part of the text string, whenever that string is being passed to an API caller.
Character strings are not 0-terminated. Instead, each character string is preceded by two length values: a 4-byte non-negative fixed-point binary number equal to the character count (indicating, in most cases, the display length) and a 4-byte non-negative fixed-point binary number equal to the byte count (indicating the number of bytes used to store the string) These counts do not include their own lengths, and may both be 0 to represent an empty string.
This data type is referred to as DTP_TEXT.
Byte strings are not 0-terminated. Instead, each byte sequence is preceded by a length value: a 4- byte non-negative fixed-point binary number equal to the byte count (indicating the number of bytes used to store the string). This count does not include its own length, and may be 0 to indicate an empty string.
This data type is referred to as DTP_BSTR.
where YYYY represents the century and year; MM represents the month ordinal (01...12); DD represents the day of month ordinal (00...31); hhmmss represents the hour, minute, and second; mmmmmm represents the fractional time in micro-seconds; ± indicates that the time value is offset from UTC time by a positive (+) or negative (-) value (UUU), given in minutes (000...720).
If less precision is desired, then the characters to the left of ± can be replaced (from right to left) with one or more asterisks ("*")). Any omitted part is assumed to take on its lowest value.
In addition, if ±UUU is given as +***, then no time offset is used, representing local time at the licensing system server, and if ±UUU is given as ****, then the time given represents local time at the licensing system agent.
This data type is referred to as DTP_TIME.
where DDDDDDDD represents the number of 24-hour days; hhmmss represents the number of hours, minutes, and seconds; mmmmmm represents fractional elapsed time in micro-seconds; :000 (which must be specified exactly as given) indicates that the time value represents a time interval.
This data type is referred to as DTP_INTVL.
A UUID is created by combining the current (local or UTC) date and time, a unique value such as a network card ID, and a serial number (unique within the organization creating the UUID).
The creation of a UUID is left at the discretion of the organization that needs to define one. There is no global directory of UUIDs in use and their corresponding "owners"instead, each occurrence of a UUID within a license certificate is accompanied by a character string representation of the creating organization. (There is no requirement that all such representations for a given UUID be identical, although in general this is the preferred method.)
This data type is referred to as DTP_UUID.
|Data Type||Data Element ID||Data Element||Data Element Value|
|4 bytes||4 bytes||4 bytes||Variable|
In addition to the primitive data types described above, many simple data elements may also be of type DTP_NULL, or empty6. This data type may be used in place of any data type normally associated with a particular data element ID to indicate that the element has a "null" (or unspecified) value. An empty data element contains only the data type, data element ID, and data element sequence number fields; the data element value is omitted.
A structure data element consists of a data element header, followed by zero or more data elements (simple or compound), that can be of the same or different types. A list data element, on the other hand, consists of a data element header, followed by zero or more occurrences of one data element (simple or compound). The data elements included within a structure data element can be either required or optional; required ones must be present, while optional ones may be omitted .
A compound data element consists of three control fields, a component count field, and the total length in bytes of the nested data elements that follow.
|Data Type||Data Element ID||Data Element||Component||Length of Nested|
|Sequence Number||Count||Data Elements|
|4 bytes||4 bytes||4 bytes||4 bytes||4 bytes|
|xslm_uint32||A 32-bit unsigned binary integer. The value-range is such that the high-order bit is always 0.|
|xslm_handle||A data structure containing a licensing-system-created handle corresponding to an instance of a license, or to an active session between an application and a licensing system. The internal data format of this structure may vary from implementation to implementation - an application should not have any reason to inspect the structure details. However, in all implementations, this data structure must be represented by exactly 64 bits.|
|xslm_bin_string||Binary string of unspecified length (length specified as a separate parameter, unless the length is fixed by the architecture).|
|xslm_string||Text string of unspecified length (length specified as a separate parameter, unless the length is fixed by the architecture).|
|xslm_uuid||A 128-bit string containing a UUID data structure.|
|xslm_tod||A 25-character string containing date and time values as specified in
|xslm_float||A double-precision 64-bit floating-point type, representing format IEEE 754 values, as specified in IEEE Standard 754-1985, that is, 64-bit multi-byte values containing (starting from the left) 1 bit for the sign, 11 bits for the exponent, and 52 bits for the base-2 fraction.|