Data Types

Caché supports a number of data types for variables, where each data type is itself a class. Each data type class represents a specific literal type, such as a string or integer. These data type classes determine the behavior of both object properties and fields in relational tables. Caché also allows you to create your own data types.

Data type classes provide the following features:

They provide for SQL, ODBC, ActiveX, and Java interoperability by providing SQL logical operation, client data type, and translation information.
They provide validation for literal data values, which you can extend or customize by using data type class parameters.
They manage the translation of literal data for its stored (on disk), logical (in memory), and display formats.

Data type classes differ from other classes in a number of ways:

They cannot be instantiated or stored independently.
They cannot contain properties.
They support a specific set of methods (called the data type interface), which is described below.

Available Types

Caché provides a library of the most common data types including strings, integer, floats, timestamps and so on. These are:

Caché Data Type Classes

Class Name	Holds	Analogous SQL Type(s)
%Binary	binary data	BINARY, BINARY VARYING, RAW, VBINARY
%Boolean	a boolean value	N/A
%Currency	a currency value	MONEY, SMALLMONEY
%Date	a date	DATE
%Float	a floating point value	DOUBLE, DOUBLE PRECISION, FLOAT, REAL
%Integer	an integer	BIT, INT, INTEGER, SMALLINT, TINYINT
%List	data in $List format	N/A
%Name	a name in the form “ Lastname,Firstname”	N/A
%Numeric	a numeric values of varying precision	DEC, DECIMAL, NUMBER, NUMERIC
%Status	an error status code	N/A
%String	a string	CHAR, CHAR VARYING, CHARACTER, CHARACTER VARYING, NATIONAL CHAR, NATIONAL CHAR VARYING, NATIONAL CHARACTER, NATIONAL CHARACTER VARYING, NATIONAL VARCHAR, NCHAR, NVARCHAR, VARCHAR, VARCHAR2
%Time	a time value	TIME
%TimeStamp	a value for a time and date	TIMESTAMP

Operation

This section describes the basic features and functionality of Caché data types.

Using Data Types in Classes

The principal function of data type classes is for specifying the types of properties within a class. The basic definition format is:

Property City As %String;

Because data types are part of the %Library package, you can simply call them without explicitly mentioning the package name.

Validation Functionality

Any property using a system data type (or a data type derived from a system data type) supports data validation through a generated method associated with the property. The validation method has a name of the form PropertyNameIsValidDT; for instance, an Age property of type %Integer has an associated AgeIsValidDT method. The method checks the validity of a value specified for the property.

Parameters

Data type classes support various parameters. These perform various actions and vary from data type to data type. These parameters include:

COLLATION — Specifies the manner in which property values are transformed for indexing.

The allowable values for collation are discussed in the SQL Introduction.
DISPLAYLIST — Used in conjunction with the VALUELIST parameter for enumerated (multiple-choice) properties. DISPLAYLIST, if not null, represents the display values for the property corresponding with the logical values listed in VALUELIST. The display values are returned by the LogicalToDisplay method.
FORMAT — Specifies the format for the data type's display value. The value of FORMAT corresponds to the formatting option of the $FNUMBER function, which performs the formatting.
INDEXSUBSCRIPTS — If present, specifies the number of subscripts used by the property in indices, using a comma as a delimiter in the property value; the %CacheStorage class uses this number. A value of 2 specifies that the first comma piece of the property value is stored as the first subscript and the second comma piece of the property value is stored as the second subscript.
MAXLEN — Specifies the maximum number of characters the string can contain
MAXVAL — Specifies the maximum allowed logical value for the data type.
MINLEN — Specifies the minimum number of characters the string can contain.
MINVAL — Specifies the minimum allowed logical value for the data type.
ODBCDELIMITER — Specifies the delimiter character used to construct a %List value when it is projected via ODBC.
PATTERN — Specifies a pattern that the string must match. The value of PATTERN must be a valid Caché pattern-matching expression.
SCALE — Specifies the number of digits following the decimal point.
TRUNCATE — Specifies whether to truncate string to MAXLEN characters, where 1 is TRUE and 0 is FALSE.
VALUELIST — Used for enumerated (multiple-choice) properties. VALUELIST is either a null string (“”) or a delimiter-separated list (where the delimiter is the first character) of logical values. If a non-null value is present, then the property is restricted to values in the list, and the validation code simply checks to see if the value is in the list.
XSDTYPE — Declares the XSD type used when projecting XML Schemas.

The supported parameters for each of the system data types are:

Supported Parameters for System Data Type Classes

Data Type Class	Supported Parameters
%Binary	MAXLEN, MINLEN
%Boolean
%Currency	DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST
%Date	DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST
%Float	DISPLAYLIST, FORMAT, MAXVAL, MINVAL, SCALE, VALUELIST, XSDTYPE
%Integer	DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST, XSDTYPE
%List	ODBCDELIMITER
%Name	COLLATION, INDEXSUBSCRIPTS, MAXLEN, XSDTYPE
%Numeric	DISPLAYLIST, FORMAT, MAXVAL, MINVAL, SCALE, VALUELIST
%Status
%String	COLLATION, DISPLAYLIST, MAXLEN, MINLEN, PATTERN, TRUNCATE, VALUELIST, XSDTYPE
%Time	DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST
%TimeStamp	DISPLAYLIST, MAXVAL, MINVAL, VALUELIST

Keywords

To provide interoperability with client systems, data type classes include the following class keywords:

CLIENTDATATYPE — Specifies the Java or ActiveX type used when the data type is accessed via client applications. See CLIENTDATATYPE for the default for each data type.
ODBCTYPE — Specifies the ODBC type used when the data type is accessed via ODBC. See SQL and ODBC Methods for the default for each data type.
SQLCATEGORY — Specifies the SQL Category to use for the data type when the Caché SQL engine performs operations upon it. See SQL and ODBC Methods for the default for each data type.

CLIENTDATATYPE

To use Caché data with any client system (such as Java or ActiveX), the data needs to be in a form that the client system can understand. To do this, Caché provides the CLIENTDATATYPE class keyword, which specifies format information for how Caché projects a property to the client.

The table below contains a list of CLIENTDATATYPE values and which classes use them:

CLIENTDATATYPE Values

Value	Used for
BINARY	%Binary (or any property requiring that there is no Unicode conversion of data)
CURRENCY	%Currency
DATE	%Date
DOUBLE	%Float
INTEGER	%Boolean , %Integer
LIST	%List
NUMERIC	%Numeric
VARCHAR	%Name , %String
TIME	%Time
TIMESTAMP	%TimeStamp

SQL and ODBC Methods

Data type classes include a number of methods and class keywords designed to support interoperability with the Caché SQL relational database, as well as other relational databases.

The OdbcToLogical and LogicalToOdbc methods translate logical data values to and from values used by the Caché SQL ODBC Interface. The ODBC value must match the ODBC type specified by the data type class' ODBCTYPE class keyword.

The ODBCTYPE class keyword specifies the ODBC data type used when a property is projected to ODBC. The definition of the data type class specifies this value. Overriding it prevents a class from working properly with ODBC.

The following ODBCTYPE values are used for the Caché system data types:

ODBCTYPE Values

Value	Caché Data Type
BINARY	%Binary
CURRENCY	%Currency
DATE	%Date
DOUBLE	%Float
INTEGER	%Integer , %Boolean
NUMERIC	%Numeric
TIME	%Time
TIMESTAMP	%TimeStamp
VARCHAR	%String , %List , %Name

The SQLCATEGORY Class Keyword

The SQLCATEGORY class keyword specifies the SQL Category that Caché SQL uses to perform operations on the value of data of this data type. Operations controlled by the SQLCATEGORY include comparison operations (such as greater than, less than, or equal to); other operations may also use it. The definition of the data type class specifies this value. Overriding it prevents a class from working properly with SQL.

The following SQLCATEGORY values are used for the Caché system classes:

SQLCATEGORY Values

Value	Caché Data Type
CURRENCY	%Currency
DATE	%Date
DOUBLE	%Float
INTEGER	%Integer , %Boolean
NAME	%Name
NUMERIC	%Numeric
STRING	%String , %Binary , %List
TIME	%Time
TIMESTAMP	%TimeStamp

Data Formats and Translation Methods

When handling data, Caché uses a number of different formats, depending on the situation. These have various purposes — such as for displaying data in a human-readable format or for manipulating data programmatically. Caché data types automatically convert data among these formats. If you create your own data type that is a subclass of a Caché data type, any property using your data type automatically includes the methods for converting among the various formats.

You only need to know about these formats and conversions between them if you are either creating a data type not based on a system data type or performing non-standard data manipulation.

The formats are:

Display — The format in which data can be input and displayed. For instance, a date in the form of “April 3, 1998” or “23 November, 1977.”
Logical — The in-memory format of data, which is the format upon which operations are performed. While dates have the display format described above, their logical format is as an integer; for the sample dates above, their values in logical format are 57436 and 50000, respectively.
Storage — The on-disk format of data — the format in which data is stored to the database. Typically this is identical to the Logical format.
ODBC — The format in which data can be presented via ODBC or JDBC. This format is used when data is exposed to ODBC/SQL. The available formats correspond to those defined by ODBC.

If a property uses a system data type (or a data type derived from a system data type), the property automatically includes methods for translation among the various data formats. Though you do not use these methods directly, they serve as the basis for a data type's property-specific methods (called property methods). They include:

DisplayToLogical — converts a variety of display values into appropriate logical values.
IsValidDT — performs data validation for the value associated with a property. The method returns 1 as the first character if the value is valid and 0 as the first character if it is not valid. When validation is enabled, the IsValidDT method is invoked automatically.
LogicalToDisplay — converts a logical value to a display value.
LogicalToOdbc — converts a logical value into an ODBC value (optional).
LogicalToStorage — converts a logical value into a storage value (optional).
OdbcToLogical — converts a logical value into a storage value (optional).
StorageToLogical — converts a database storage value into a logical value (optional).

Enumerated Properties

Properties can support multiple choice values, also known as enumerated values. To create such a properties, there are two data type class parameters: VALUELIST and DISPLAYLIST.

To specify a list of valid values for a property, use its VALUELIST parameter. The form of VALUELIST is a delimiter-separated list of logical values, where the delimiter is the first character. For instance:

Property Color As %String(VALUELIST = ",red,green,blue");

In this example, VALUELIST specifies that valid possible values are “red”, “green”, and “blue”, with a comma as its delimiter. Similarly,

Property Color As %String(VALUELIST = " red green blue");

specifies the same list, but with a space as its delimiter.

The property is restricted to values in the list, and the data type validation code simply checks to see if the value is in the list. If no list is present, there are no special restrictions on values.

DISPLAYLIST is an additional list that, if present, represents the corresponding display values to be returned by the property's LogicalToDisplay method.

This functionality works by convention: the data type class' LogicalToDisplay and IsValidDT methods must first check for the presence of these class parameters and include code to process these lists if present.