The mi_cast_get() function

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

Syntax

MI_FUNC_DESC *mi_cast_get(conn, source_type, target_type, cast_status)
   MI_CONNECTION *conn;
   MI_TYPEID *source_type;
   MI_TYPEID *target_type;
   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().

This 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 is an advanced feature of the DataBlade® API.

source_type
A pointer to the type identifier of the source data type for the cast.
target_type
A pointer to the type identifier of the target data type for the cast.
cast_status
A pointer to the status flag that mi_cast_get() sets to indicate the kind of cast function that it locates or the cause of an error.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_cast_get() function obtains a function descriptor for a cast function whose source and target data types the source_type and target_type arguments reference. The mi_cast_get() function accepts source and target data types as pointers to type identifiers. 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_cast_get() function performs the following tasks:
  1. Looks in the syscasts system catalog table for the cast function that casts from the source_type data type to the target_type data type
  2. Allocates a function descriptor for the cast function and saves the routine sequence in this descriptor
  3. Allocates an MI_FPARAM structure for the cast function and saves the argument and return-value information in this structure
  4. Sets the cast_status output parameter to provide status information about the cast function
  5. Returns a pointer to the function descriptor that it allocates for the cast function
Server only:
When you pass a public connection descriptor (from mi_open()), the mi_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_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.
Important: 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 cannot perform the task you need done.
The cast_status flag can have one of the following constant values.
Cast-type constant
Purpose
MI_ERROR_CAST
The mi_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, and the cast is explicit.
MI_IMPLICIT_CAST
A user-defined cast function exists to cast between the two types, and the cast is implicit.
The following call to mi_cast_get() looks for a cast function that converts from the INTEGER data type to an opaque data type named percent:
MI_TYPEID *src_type, *trgt_type;
mi_char cast_stat;
MI_FUNC_DESC *func_desc;
MI_CONNECTION *conn;
...
src_type = mi_typestring_to_id(conn, "INTEGER");
trgt_type = mi_typestring_to_id(conn, "percent");

func_desc = mi_cast_get(conn, &src_type, &trgt_type,
   &cast_stat);
if ( func_desc == 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_cast_get() function.");
         break;
      case MI_NOP_CAST:
         mi_db_error_raise(NULL, MI_EXCEPTION, 
            "No cast function needed.");
         break;
      ...

Return values

An MI_FUNC_DESC pointer
A pointer to the function descriptor of the cast function that casts from source_type to target_type.
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.