Functions to Obtain Information on Date and Time Data

Table 19 shows the DataBlade API functions that obtain qualifier information for a DATETIME (mi_datetime) or INTERVAL (mi_interval) value.

Suppose you have a table with a single column, dt_col, of type DATETIME YEAR TO SECOND. If row_desc is a row descriptor for a row in this table, the code fragment in Figure 14 obtains the name, qualifier, precision, and scale for this column value.

MI_TYPE_DESC *col_type_desc;
MI_ROW_DESC *row_desc;
mi_string *type_name;
mi_integer type_qual;
...
col_type_desc = mi_column_typedesc(row_desc, 0);
type_name = mi_type_typename(col_type_desc);
type_qual = mi_type_qualifier(col_type_desc);
type_prec = mi_type_precision(col_type_desc);
type_scale = mi_type_scale(col_type_desc);
sprintf(type_buf,
   "column=%d: type name=%s, qualifier=%d precision=%d \
   scale=%d\n", 
   i, type_name, type_qual, type_prec, type_scale);

In Figure 14, the value in the type_buf buffer would be as follows:

column=0, type name=datetime year to second, qualifier=3594 precision=14 scale=10

Qualifier of a Date-Time or Interval Data Type

The mi_type_qualifier( ) function returns the encoded qualifier of a DATETIME or INTERVAL data type from a type descriptor. This qualifier is the internal value that the database server uses to track the complete qualifier range, from the starting field to the end field. It is the value stored in the collength column of the syscolumns table for DATETIME and INTERVAL columns. You can use the qualifier macros and constants (see Table 18) to interpret this encoded value.

In Figure 14, the value in type_qual contains the encoded integer qualifier (3594) for the dt_col column. You can obtain the starting qualifier for the DATETIME value from the encoded qualifier with the TU_START macro, as follows:

TU_START(type_qual)

This TU_START call yields 0, which is the value of the TU_YEAR constant in the datetime.h header file. You can obtain also the ending qualifier for the DATETIME value from the encoded qualifier with the TU_END macro, as follows:

TU_END(type_qual)

This TU_END call yields 10, which is the value of the TU_SECOND constant in the datetime.h header file. Therefore, the encoded qualifier 3594 represents the qualifier year to second.

Precision of a Date-Time or Interval Data Type

For the DATETIME and INTERVAL data types, the precision is the number of digits required to store a value with the specified qualifier. In Figure 14, the call to the mi_type_precision( ) function saves in type_prec the precision for the dt_col column from its type descriptor. This precision has a value of 14 because a DATETIME YEAR TO SECOND value requires 14 digits:

YYYYMMDDHHMMSS

YYYY

is the 4-digit year.

MM

is the 2-digit month.

DD

is the 2-digit day of the month.

HH

is the 2-digit hour.

MM

is the 2-digit minute.

SS

is the 2-digit second.

The DataBlade API also provides functions that obtain DATETIME or INTERVAL precision of a column associated with an input parameter, a UDR argument, UDR return value, or a row column. For a list of these functions, see Table 19.

Scale of a Date-Time or Interval Data Type

For the DATETIME and INTERVAL data types, the scale is the encoded integer value for the end qualifier. In Figure 14, the call to the mi_type_scale( ) function stores in type_scale the scale for the dt_col column. This precision has a value of 10 because the end qualifier for the DATETIME YEAR TO SECOND data type is SECOND, whose encoded value (TU_SECOND) is 10.

The DataBlade API also provides functions that obtain DATETIME or INTERVAL scale of an input parameter, a UDR argument, UDR return value, or column. For a list of these functions, see Table 19.