Informix DataBlade API Programmer's Manual DataBlade API Function Descriptions

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

MI_FUNC_DESC *mi_routine_get(conn, flags, rout_sig)

MI_CONNECTION *conn;

mi_integer flags;

char *rout_sig;

conn	is a pointer to the connection descriptor that a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect() has established.
flags	must be 0.
rout_sig	is 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] See the description in the Usage section for more information on the syntax of the rout_sig argument.

Valid in Client LIBMI Application?	Valid in User-Defined Routine?
Yes	Yes

The mi_routine_get() function creates 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

is the word function (the default) or procedure.


owner

is 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 as an 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 owner name to obtain UDRs of a particular owner. If you specify a NULL-valued pointer as an owner, mi_routine_get() assumes 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

is the name of the user-defined routine to look up.


parm1,...
parmN

is 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.

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.

The mi_routine_get() function allocates a new function descriptor in the PER_COMMAND memory duration.

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 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 is optional in the routine signature. As the preceding examples show, the udr_type defaults to function when it is omitted from the routine signature. If a user-defined procedure and a user-defined function have the same routine name, include the 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.

Other internal errors raise an exception.

See the descriptions of the following functions: mi_cast_get(), mi_fparam_get(), mi_routine_get_by_typeid(), mi_routine_exec(), and mi_routine_end().

For more information, see Calling UDRs with the Fastpath Interface.