Look up cast functions

A cast function is a user-defined function that converts one data type (the source data type) to a different data type (the target data type).

The way that a cast is called depends on the type of the cast, as the following table shows.


Type of cast	How it is called
Built-in cast	Called by the database server automatically when built-in types need conversion in an SQL statement or a UDR call
Implicit cast	Called by the database server automatically when castable data types are part of an SQL statement
Explicit cast	Called explicitly within an SQL statement with the :: operator or CAST AS keywords Called explicitly within a DataBlade® API module with the Fastpath interface

To look up a cast function by its source and target data types, use one of the following Fastpath look-up functions.


DataBlade® API function	How it looks up a cast function
mi_cast_get()	Looks up a cast function for source and target data types specified as type identifiers
mi_td_cast_get()	Looks up a cast function for source and type data types specified as type descriptors

To obtain a function descriptor for a cast function, the mi_cast_get() or mi_td_cast_get() function performs the following steps:

Asks the database server to look up the cast function in the syscasts system catalog.
After the function locates a syscasts entry for the cast function, it obtains routine information for the cast function from the sysprocedures system catalog table. These functions also determine the type of cast that the cast function performs: an explicit cast, an implicit cast, or a built-in cast.
Allocates a function descriptor for the cast function and save the routine sequence in this descriptor.
You can obtain information about the UDR from this function descriptor. For more information, see Obtain information from a function descriptor.
Allocates an MI_FPARAM structure for the function descriptor.
You can get a pointer to this structure with the mi_fparam_get() function. For more information, see Obtain the MI_FPARAM structure. You can also allocate your own MI_FPARAM structure to use instead of this automatically allocated one. For more information, see A user-allocated MI_FPARAM structure.
Returns a pointer to the function descriptor that identifies the specified cast function.
Subsequent calls to mi_routine_exec() can use this function descriptor to identify the cast function to execute. For more information, see Execute the routine.

Tip: The mi_cast_get() and mi_td_cast_get() functions search for cast functions only in the syscasts system catalog table. Therefore, these functions can locate only cast functions that the CREATE CAST statement has registered.

Suppose the following CREATE CAST statements register explicit casts between the DECIMAL and mytype data types in your database:

CREATE CAST (mytype AS DECIMAL(5,3) WITH mt_to_dec);
CREATE CAST (DECIMAL(5,3) AS mytype WITH dec_to_mt);

The following code fragment uses the mi_cast_get() function to obtain the function descriptor for a cast function that casts from a DECIMAL data type to the mytype data type.

Figure 1. Obtaining a cast function for a DECIMAL-to-mytype cast

MI_CONNECTION *conn;
MI_FUNC_DESC *fdesc2 = NULL;
MI_TYPEID *src_type, *trgt_type;
mi_char cast_status = 0;
mi_boolean need_cast = MI_TRUE;
mi_integer error;
MI_DATUM *ret_val;
mi_decimal dec_val;
...
/* Get type identifiers for source and target types */
src_type = mi_typestring_to_id(conn, "DECIMAL(5,3)");
trgt_type = mi_typestring_to_id(conn, "mytype");

/* Look up cast function based on type identifiers */
fdesc2 = mi_cast_get(conn, src_type, trgt_type, &cast_status);

switch ( cast_status )
   {
   case MI_ERROR_CAST: /* error in function look-up */
      mi_db_error_raise(NULL, MI_EXCEPTION, "mi_cast_get() failed");
      break;

   case MI_NO_CAST: /* no cast function exists */
      mi_db_error_raise(NULL, MI_EXCEPTION, "No cast function found");
      break;

   case MI_NOP_CAST: /* do not need a cast */
      need_cast = MI_FALSE;
      break;
   }

if ( need_cast )
   /* Execute the cast function with Fastpath */
   ...

The mi_cast_get() function allocates and initializes a function descriptor, fdesc2, for the dec_to_mt() cast function. The src_type is a pointer to the type identifier for the DECIMAL(5,3) data type. The trgt_type variable is a pointer to the type identifier for the mytype data type.

The mi_cast_get() function returns a NULL-valued pointer to indicate several different conditions. In Obtaining a cast function for a DECIMAL-to-mytype cast, the cast_status variable identifies which of these conditions has occurred, as follows.


The cast_status value	Condition
MI_ERROR_CAST	The mi_cast_get() function has not executed successfully.
MI_NO_CAST	No cast function exists between the specified source and target types.
MI_NOP_CAST	No cast function is needed between the specified source and target types.

The switch statement handles the possible status cast_status values from the mi_cast_get() call.

If you have type descriptors instead of type identifiers for the source and target types, use the mi_td_cast_get() function instead of mi_cast_get(). For example, the casting process might need information about scale and precision for built-in data types that have this information. A type descriptor stores scale and precision; a type identifier does not.

You can replace the call to mi_cast_get() in Obtaining a cast function for a DECIMAL-to-mytype cast with the following call to the mi_td_cast_get() function:

MI_TYPEID *src_type, *trgt_type;
MI_TYPE_DESC *src_tdesc, *trgt_tdesc;

...
/* Get type descriptors for source and target types */
src_tdesc = mi_type_typedesc(conn, src_type);
trgt_tdesc = mi_type_typedesc(conn, trgt_type);

/* Look up cast function based on type descriptors */
fdesc2 = mi_td_cast_get(conn, src_tdesc, trgt_tdesc,
   &cast_status);

The src_tdesc and trgt_tdesc variables are pointers to type descriptors for the DECIMAL(5,3) and mytype data types, respectively. The mi_type_typedesc() function creates type descriptors from the type identifiers that src_type and trgt_type reference.

When you call mi_cast_get() or mi_td_cast_get() from a client LIBMI application, the function allocates a local copy (on the client computer) of the function descriptor and MI_FPARAM structure. You can use the function-descriptor and MI_FPARAM accessor functions within a client LIBMI application to access these local copies.