DataBlade API Programming Tips

While you program your DataBlade modules using the DataBlade API, observe these guidelines:

• Never assume that the content of an mi_lvarchar data type is null-terminated.

  The Informix database server never passes a null-terminated external representation of an mi_lvarchar data type; however, the DataBlade API provides functions to convert mi_lvarchar values to and from null-terminated strings. To allocate and free memory for mi_lvarchar data types, use the mi_var accessor functions. For more information, see the documentation on the mi_lvarchar_to_string() function in the IBM Informix: DataBlade API Programmer's Guide.

• Pass and return values greater than 4 bytes by reference.

  Opaque data types are wrapped in an mi_lvarchar data type and passed by reference.

  Write your user-defined routine code to pass arguments using a pointer. All built-in data types are passed by reference except fixed-length, noncharacter data types of fewer than 4 bytes. The mi_real data type (the SQL data type SMALLFLOAT) is always passed by reference. Pass opaque data types by value by creating them with the passedbyvalue modifier.

• Do not modify a user-defined routine argument unless it is an OUT parameter.

  Arguments to C routines cannot be modified unless you specify that the argument is an OUT parameter for a statement local variable. See IBM Informix: User-Defined Routines and Data Types Developer's Guide for more information.

• To test if an argument for a user-defined routine is null, use the mi_fp_argisnull() function.

  If you create a user-defined routine with the with (handlesnulls) modifier, your routine must check the input parameters to determine if they are null. To check whether arguments are null, pass the MI_FPARAM structure as the last argument in the C routine; then check the arguments by calling the mi_fp_argisnull() function.

• To set a return value to NULL, use the mi_fp_setreturnisnull() function.

  If you intend to return a null value from a function, you must call mi_fp_setreturnisnull() with MI_TRUE before the return statement. If you do not, you might receive an incorrect result or memory errors.

For code examples illustrating these and other DataBlade API coding tips, see the example DataBlade modules provided with the DataBlade Developer's Kit in the %INFORMIXDIR%\dbdk\examples directory or the IBM Informix Developer Zone at www.ibm.com/software/data/developer/informix.

For details on DataBlade API data types and routines, see the IBM Informix: DataBlade API Programmer's Guide.