The mi_routine_get() function

The mi_routine_get() function looks up a registered user-defined routine by a routine signature that is a character string and creates its function descriptor.

Syntax

MI_FUNC_DESC *mi_routine_get(conn, flags, rout_sig)
   MI_CONNECTION *conn;
   mi_integer flags;
   char *rout_sig;
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.

flags
The value must be 0.
rout_sig
A character string that specifies the routine signature of the user-defined routine to be looked up. This signature has the following format: 
[udr_type] [owner.]udr_name([parm1],...,[parmN])

For more information about the syntax of the rout_sig argument, see the description in the following Usage section.

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

Usage

The mi_routine_get() function obtains a function descriptor for the UDR that the rout_sig argument specifies. The rout_sig argument specifies the routine signature of the UDR in the following format: 
[udr_type] [owner.]udr_name([parm1], ..., [parmN])
udr_type
The word function (the default) or procedure.
owner
The name of the UDR owner.

When the UDR is defined in a database that is not ANSI-compliant, mi_routine_get() looks for UDRs owned only by owner. If you specify a NULL-valued pointer for owner, mi_routine_get() looks for UDRs owned by anyone.

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

udr_name
The name of the user-defined routine to look up.
parm1,...parmN
An optional list of data types for the parameters of the user-defined routine.

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 UDR, the mi_routine_get() function performs the following tasks:
  1. Looks for a user-defined routine that matches the rout_sig routine signature in the sysprocedures system catalog table
  2. Allocates a function descriptor for the UDR 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() 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() 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.

The following call to mi_routine_get() looks for the a_udr() user-defined function in a database that is not ANSI compliant: 
func_desc = mi_routine_get(conn, 0, 
   "a_udr(integer, integer)");
An ANSI-compliant database requires an owner name as part of a routine name. If a_udr() was defined in an ANSI-compliant database, you must include the owner name in the routine signature, as follows: 
func_desc = mi_routine_get(conn, 0, 
   "dexter.a_udr(integer, integer)");
The udr_type part of the routine signature is optional. As the preceding examples show, udr_type defaults to FUNCTION when this part is omitted from the routine signature. If a user-defined procedure and a user-defined function have the same routine name, include udr_type in the rout_sig signature. The following call to mi_routine_get() specifies that a_udr() is a user-defined function: 
func_desc = mi_routine_get(conn, 0, 
   "function a_udr(integer, integer)");

For user-defined procedures, specify the PROCEDURE keyword instead.

Return values

An MI_FUNC_DESC pointer
A pointer to the function descriptor for the routine that rout_sig specifies.
NULL
No matching user-defined routine was found or that the specified user-defined routine has multiple return values, which is possible with:
  • SPL routines that include the WITH RESUME clause in their RETURN statement
  • Iterator functions

Other internal errors raise an exception.