Previous section.

Systems Management: Software License Use Management (XSLM)
Copyright © 1999 The Open Group

Data Types and Data Elements

This chapter defines the primary data types and the different types of data elements used within an XSLM license certificate, as well as for the external representation of data elements maintained internally by a licensing system, such as certificate-instance data, status data, and logging data.

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 Data Elements.

Data Types

This section describes the detailed representation of all primary data types used within an XSLM licensing system.

Bit and Byte Numbering and Order

Within XSLM, the eight bits within a byte are numbered from left to right, starting with 0 and ending with 7. Bit 0 is the most-significant position.

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.

Fixed-Point Binary Numbers

All fixed-point binary numbers are (except where noted) stored as non-negative numbers, 4 bytes wide, with a maximum value of 2**31-12.

This data type is referred to as DTP_FIXED.

Floating-Point Numbers

All floating-point numbers are (except where noted) stored in IEE754 Double Float format, that is, as a 64-bit multi-byte value containing (starting from the left) 1 bit for the sign, 11 bits for the exponent, and 52 bits for the base-2 fraction.

This data type is referred to as DTP_FLOAT.

Character Strings

Character (text) strings are stored in Unicode, using a slightly modified version of the UCS Transformation Format 8 bit (UTF-8) format3.

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

Byte (binary) strings are stored as a sequence of bytes, numbered from the left, starting with the first byte being assigned the position 0.

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.

Date/Time and Time-Interval Values

Unless otherwise specified, all date and time values, as well as interval values, are stored in character format,4. as described below.
Representation of a Point in Time
A particular point in time is defined as follows: 
 

YYYYMMDDhhmmss.mmmmmm[±]UUU

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.

Representation of a Time Interval
A time interval is defined as follows: 
 

DDDDDDDDhhmmss.mmmmmm:000

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.

Universally Unique Identifiers (UUIDs)

Some license certificate elements, such as PUBLISHER-ID and LICENSING-SYSTEM- PUBLISHER-ID must contain values that are guaranteed to be unique in the global name space. Such values are defined as 16-byte long byte strings containing Universal Unique Identifiers (UUIDs)5.

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 Elements

Each data element is of one of two types: simple or compound. Simple data elements, such as integers and strings, are used to represent individual values; compound data elements, such as structures and lists, are used to represent a collection of related data elements (which can themselves be either simple or compound).

Simple Data Elements

A simple data element consists of three control fields, and the actual data value (whose format depends upon the data type).

Data Type Data Element ID Data Element Data Element Value
    Sequence Number  
4 bytes 4 bytes 4 bytes Variable

Data Type

provides syntactic information sufficient to parse the data element, even if the particular data element definition is not understood.

Data Element ID

provides semantic information needed to properly process the element data. Without prior knowledge of the meaning of this identifier, the data element cannot be understood by a licensing system; however, the Data Type syntactic information may enable a management tool to provide some limited form of management capability even for such data elements.

Data Element Sequence Number

is a certificate-unique, arbitrary, number that can be used by the management API functions to update a particular data element, once its sequence number is known (by first retrieving the complete certificate). Once a data element sequence number has been assigned to a data element (including certificate-related state information), it can never change.

Data Element Value

provides the actual value of the particular data element.

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.

Compound Data Elements

There are two kinds of compound data elements: structures and lists. These are syntactically identical, but are used to represent two very different types of data elements.

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

Data Type

provides syntactic information sufficient to parse the data element, even if the particular data element definition isn't understood.

Data Element ID

provides semantic information needed to properly process the element data. Without prior knowledge of the meaning of this identifier, the data element can't be understood by a licensing system; however, the Data Type syntactic information may enable a management tool to provide some limited form of management capability even for such data elements.

Data Element Sequence Number

is a certificate-unique, arbitrary, number that can be used by the management API functions to update a particular data element, once its sequence number is known (by first retrieving the complete certificate). Once a data element sequence number has been assigned to a data element (including certificate-related state information), it can never change.

Component Count

indicates the number of data elements that are included within this compound data element. Note that these data elements may themselves be compound data elements. If the value of component count is 0, then the compound data element is effectively a "null" element.

Length of Nested Data Elements

is the total length in bytes of all the data elements that are part of the current compound data element.

API Data Types

The following data types are used within the API definitions, with meanings as described. Actual definitions will be provided by licensing system vendors.

Name Description
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 Date/Time and Time-Interval Values.
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.


Footnotes

1.
This detailed description is needed to ensure that data can be created and manipulated within different computing platforms, even if they normally use different methods of representing such data (for example, little-endian versus big-endian)

2.
Thus, in most programming languages and computing environments, they may be represented as either unsigned or signed binary numbers.

3.
In this modified format, each character in the Basic Latin character range except the code U+0000 (that is, U+0001-U+007F) is represented as a single byte with a numeric code value equal to its UCS code value. All other UCS characters are represented by two or more bytes. This encoding ensures that all of the 0x01 through 0x7f ASCII codes can be represented in a single-byte format with no conversion required between the ASCII and Unicode formats.

4.
Using the modified UTF-8 format described above, but without any length fields (the date/time format uses a fixed-length format).

5.
Also known as Globally Unique Identifier (GUID).

6.
The detailed data element descriptions in Data Elements indicate whether a particular data element may take on the "null" value.

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index