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:

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
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 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 HCL OneDB™ 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.