The mi_td_cast_get() function

The mi_td_cast_get() function looks up a registered cast function by the type descriptors of its source and target data types and creates its function descriptor.

Syntax

MI_FUNC_DESC *mi_td_cast_get(conn, source_tdesc, target_tdesc, cast_status)
   MI_CONNECTION *conn;
   MI_TYPE_DESC *source_tdesc;
   MI_TYPE_DESC *target_tdesc;
   mi_char *cast_status;

conn: A pointer to a connection descriptor established by a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect().
The value can be a pointer to a session-duration connection descriptor established by a previous call to mi_get_session_connection(). Use of a session-duration connection descriptor A restricted feature of the DataBlade® API.
source_tdesc: A pointer to the type descriptor of the source data type of the cast, including its length and precision.
target_tdesc: A pointer to the type descriptor of the target data type of the cast.
cast_status: A pointer to the status flag to set to indicate the kind of cast function that it has located.


Valid in client LIBMI application?	Valid in user-defined routine?
Yes	Yes

Usage

The mi_td_cast_get() function obtains a function descriptor for a cast function whose source and target data types the source_tdesc and target_tdesc arguments reference. The mi_td_cast_get() function accepts source and target data types as pointers to type descriptors. This function is one of the functions of the Fastpath interface. It is a constructor function for the function descriptor.

To obtain a function descriptor for a cast function, the mi_td_cast_get() function performs the following tasks:

Looks in the syscasts system catalog table for the cast function that casts from the source_tdesc data type to the target_tdesc data type
Allocates a function descriptor for the cast function and saves the routine sequence in this descriptor
Allocates an MI_FPARAM structure for the cast function and saves the argument and return-value information in this structure
Sets the cast_status output parameter to provide status information about the cast function
Returns a pointer to the function descriptor that it allocated for the cast function

Server only: When you pass a public connection descriptor (from mi_open()), the mi_td_cast_get() function allocates the new function descriptor in the PER_COMMAND memory duration. If you pass a session-duration connection descriptor (from mi_get_session_connection()), mi_td_cast_get() allocates the new function descriptor in the PER_SESSION memory duration. This function descriptor is called a session-duration function descriptor. For more information, see the Informix® DataBlade® API Programmer's Guide.

The session-duration connection descriptor and session-duration function descriptor are advanced features of the DataBlade® API. They can adversely affect your UDR if you use them incorrectly. Use them only when a regular connection descriptor or function descriptor will not perform the task you need done.

The cast_status flag can have one of the following cast-type constant values.

MI_ERROR_CAST: The mi_td_cast_get() function failed.
MI_NO_CAST: A cast does not exist between the two specified types. The user must write a function to perform the cast.
MI_NOP_CAST: A cast is not needed between the two types. The types are equivalent and therefore no cast is required.
MI_SYSTEM_CAST: A built-in cast exists to cast between two data types, usually built-in data types.
MI_EXPLICIT_CAST: A user-defined cast function exists to cast between the two types. The cast is explicit.
MI_IMPLICIT_CAST: A user-defined cast function exists to cast between the two types. The cast is implicit.

The following call to mi_td_cast_get() looks for a cast function that converts INTEGER data to data of an opaque data type named percent:

MI_TYPE_DESC *src_tdesc, *trgt_tdesc;
MI_CONNECTION *conn;
MI_FUNC_DESC *fdesc;
mi_char cast_stat;
...
src_tdesc = mi_typestring_to_typedesc(conn, "INTEGER");
trgt_tdesc = mi_typestring_to_typedesc(conn, "percent");
fdesc = mi_td_cast_td(conn, src_tdesc, trgt_tdesc,
   &cast_stat);
if ( fdesc == NULL )
   {
   switch ( cast_stat )
      {
      case MI_NO_CAST:
         mi_db_error_raise(NULL, MI_EXCEPTION,
            "No cast function found");
         break;
      case MI_ERROR_CAST:
         mi_db_error_raise(NULL, MI_EXCEPTION,
            "Error in mi_td_cast_get() function");
         break;
      case MI_NOP_CAST:
         mi_db_error_raise(NULL, MI_EXCEPTION,
            "No cast function needed");
         break;
      ...

For more information about how to look up a UDR or about type descriptors, see the Informix® DataBlade® API Programmer's Guide.

Return values

An MI_FUNC_DESC pointer

A pointer to the function descriptor of the cast function that casts from source_tdesc to target_tdesc.

NULL

The cast_status value is one of the following constants:

MI_ERROR_CAST: The function was not successful.
MI_NO_CAST: A cast does not exist between the two specified types. The user must write a function to perform the cast.
MI_NOP_CAST: A cast is not needed between the two types. The types are equivalent and therefore no cast is required.