The mi_routine_get_by_typeid() function

The mi_routine_get_by_typeid() function looks up a registered user-defined routine (UDR) on the local database server by a routine signature that the function builds from a list of arguments. This function also creates a function descriptor for the UDR.

Syntax

MI_FUNC_DESC *mi_routine_get_by_typeid(conn, udr_type, udr_name, 
   owner,arg_count, arg_types)
   MI_CONNECTION *conn;
   MI_UDR_TYPE udr_type;
   char *udr_name;
   char *owner;
   mi_integer arg_count;
   MI_TYPEID *arg_types;
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.

udr_type
A value of type MI_UDR_TYPE that indicates whether the user-defined routine A function or a procedure:
MI_FUNC
The user-defined routine is a function.
MI_PROC
The user-defined routine is a procedure.
udr_name
The name of the user-defined routine.
owner
The owner of the routine. For more information about how to specify an owner name, see the following Usage section.
arg_count
The integer number of arguments that the user-defined routine takes.
arg_types
An array of pointers to type identifier, one type identifier for each of the udr_name routine arguments.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_routine_get_by_typeid() function obtains a function descriptor for the UDR that the routine signature specifies. This function builds the routine signature from the udr_type, udr_name, owner, arg_count, and arg_types arguments. The mi_routine_get_by_typeid() function is one of the functions of the Fastpath interface. It is a constructor function for the function descriptor.

The mi_routine_get_by_typeid() function performs the following tasks:
  1. Looks for a user-defined routine that matches the routine signature in the sysprocedures system catalog table
  2. Allocates a function descriptor for the routine and saves the routine sequence in this descriptor
  3. Allocates an MI_FPARAM structure for the routine and saves the argument and return-value information in this structure
  4. Returns a pointer to the function descriptor that it allocated for the user-defined routine
Server only: When you pass a public connection descriptor (from mi_open()), the mi_routine_get_by_typeid() 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_routine_get_by_typeid() 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 cannot perform the task you need done.

When the UDR is defined in a database that is not ANSI compliant, mi_routine_get_by_typeid() looks for UDRs owned only by owner. If you specify a NULL-valued pointer as an owner, mi_routine_get_by_typeid() looks for UDRs owned by anyone. The following call to mi_routine_get_by_typeid() looks for the a_proc() user-defined procedure in a database that is not ANSI compliant: 
MI_TYPEID *arg_types[2];
MI_FUNC_DESC *func_desc;
MI_CONNECTION *conn;
...
arg_types[0] = mi_typestring_to_id(conn, "integer");
arg_types[1] = mi_typestring_to_id(conn, "datetime");
func_desc = mi_routine_get_by_typeid(conn, MI_PROC, 
   "a_proc", NULL, 2, arg_types);

When the UDR is defined in an ANSI-complaint database, owner is part of its routine signature. You can specify a particular owner value to obtain UDRs of a particular owner. If you specify a NULL-valued pointer as an owner, mi_routine_get_by_typeid() uses the current user account as the owner value. If no UDRs exist for the current user, mi_routine_get_by_typeid() looks for UDRs with user informix as the owner name.

If a_proc() was defined in an ANSI-compliant database, the following call to mi_routine_get_by_typeid() looks up the a_proc() user-defined procedure owned by user dexter: 
func_desc = mi_routine_get_by_typeid(conn, 0, MI_PROC,
   "a_udr", "dexter", 2, arg_types);

Return values

An MI_FUNC_DESC pointer
A pointer to the function descriptor of the specified user-defined routine.
NULL
No matching user-defined routine was found or that the specified user-defined routine has multiple return values. The following routines can have multiple return values:
  • SPL routines that include the WITH RESUME clause in the RETURN statement
  • Iterator functions

Other internal errors raise an exception.