DataBlade Developers Kit User's Guide Programming DataBlade Module Routines in C

This section contains the following subsections:

• Identifying the Source of Generated Code, next
• Comments in Generated Code
• MI_FPARAM Function Argument
• Server Connection Handle
• Tracing and Error Handling
• Utility Functions Generated by BladeSmith

When BladeSmith generates source code for your DataBlade module, it uses routines and data structures from various libraries.

The following table lists common prefixes for data types and routines appearing in generated DataBlade module code and lists their sources and where they are documented.

BladeSmith adds comments to the code it generates. Each routine begins with a prologue that describes the purpose of the routine, its arguments, and its return value. Comments throughout the code describe variable declarations and the results of generated C statements and routine calls.

In comments at the beginning and end of each generated routine, BladeSmith stores information it uses when regenerating source code. The prologue includes a routine ID. A comment at the end of the routine contains a calculated checksum.

Warning: Do not modify either of these comments; BladeSmith uses them to merge your edits into the regenerated code.

BladeSmith adds a Gen_ prefix to all variable names and routine names you did not create or explicitly define in BladeSmith: for example, utility functions and the Gen_Con connection argument.

BladeSmith adds an extra argument to all routines it generates: a pointer to an MI_FPARAM structure. However, with the exception of iterator functions and user-defined functions that allow null arguments, the generated code does not manipulate the values stored in MI_FPARAM structures. The MI_FPARAM argument is included for your convenience. If you want to use the MI_FPARAM structure, you must add code to all noniterator routines.

Typically, you only need to use the MI_FPARAM structure for the following tasks:

• Check for NULL arguments or return values
• Set arguments or return values to NULL
• Get data type information about arguments or return values
• Manage iterative calls to a function

To manipulate the values in an MI_FPARAM structure, you must use its DataBlade API accessor functions. Do not access MI_FPARAM structure members directly, because the structure might change between versions of the DataBlade API.

In addition to references for each of the MI_FPARAM accessor functions, the DataBlade API Programmer's Manual includes a chapter that describes the information stored in the MI_FPARAM structure and tells you how to get values from or store values in the structure and how to use the structure for creating iterative functions.

For an explanation of how generated code uses the MI_FPARAM structure in an iterator function, see Iterator Functions. The ExmAmortize() function in the example Business DataBlade module uses the MI_FPARAM structure in an iterative function.

BladeSmith calls mi_open() at the beginning of many of the routines it generates. The mi_open() call obtains a database server connection handle, which is a required argument in many DataBlade API calls. If your routine does not need a connection handle, remove the mi_open() and mi_close() functions that BladeSmith adds to your code.

Tip: If the only DataBlade API call your routine makes is to mi_db_error_raise(), you do not need a connection handle. You can pass a null value to mi_db_error_raise().

For routines running in the database server address space, except the large object DataBlade API routines, the connection handle enables client and database server routines to use the same DataBlade API routines.

When mi_open() is called at the beginning of a generated routine, mi_close() is called to release the handle immediately before the routine returns.

BladeSmith adds tracing and error handling code throughout the generated source code if the tracing option is set to True when you generate source code in BladeSmith.

A generated utility function, Gen_Trace(), processes all tracing and error handling. Your routines must not call Gen_Trace() directly. To perform tracing and error handling tasks, use the DBDK_TRACE macros defined in the generated header file.

This section describes:

• how to use the supplied DBDK_TRACE macros to add tracing and error handling to your generated code (see Adding Tracing and Error Handling).
• how to enable tracing and use the generated TraceSet_project procedure (see Enabling Tracing in a DataBlade Module and Enabling Tracing in a Database Session).
• the standard Informix-supplied error messages (see Standard Error Messages).

Tracing is the process of writing status messages for routines to a file. Use tracing for debugging; tracing can generate a high volume of output, which is not appropriate for production databases.

By default, tracing is disabled whenever you start a new database session.

Each tracing message has a tracing level associated with it. When you enable tracing, you set a threshold for tracing levels. Messages with a trace level less than or equal to the threshold are written to the trace file.

Tracing messages are written to a trace file, which is created with a default name and location, or with a name and location you specify. If you remove the trace file while tracing is enabled, it is automatically re-created. The default name and location of the trace file is tmp/session_id.trc, where session_id is the four-digit identifier of the current database server session. To obtain your current session ID, use the onstat -g ses command.

Messages are written to the trace file only if you:

• generate source code with tracing. See Generating Source Files for instructions.
• compile the DataBlade module. See Compiling DataBlade Module Code for instructions.
• enable tracing in your DataBlade module by adding a trace class to the systraceclasses system catalog and creating the TraceSet_project() procedure. See Enabling Tracing in a DataBlade Module for more information.
• enable tracing for a database session by setting a threshold and optionally specifying a trace file with the TraceSet_project() procedure. See Enabling Tracing in a Database Session for instructions.

Trace messages include the name of the executing routine, the source filename, and the line number of the call to Gen_Trace() with the embedded parameters %FUNCTION%, %FILENAME%, and %LINENO%. For example, the following example is a portion of a log file resulting from calling the "enter routine" and "exit routine" macros, DBDK_TRACE_ENTER() and DBDK_TRACE_EXIT(), for the Distance() function:

=========================================
Tracing session: 12 on 3/4/1998

10:55:32 Entering function Distance (Circle.c)

10:55:32 Successfully exiting Distance (Circle.c)



Important: If you want to include parameters other than %FUNCTION%, %FILENAME%, and %LINENO% in a message, you must call the gl_dprintf() function for trace messages or the mi_db_error_raise() function for error messages. For an example of calling these functions, see the Gen_Trace() function in the generated source code. See the "DataBlade API Programmer's Manual" for more information on using these functions.

To add tracing and error handling to the generated source code, edit the generated source code file and insert DBDK_TRACE macro calls.

The following table describes the tracing and error handling macros.

The macros are described in the following sections. See Setting a Trace Output File and a Trace Threshold for information on the name and location of the trace message file.

When tracing is enabled, use the DBDK_TRACE_MSG() and DBDK_TRACE_ERROR() macros to write messages to the trace message file. The DBDK_TRACE_ERROR() macro also raises an error.

If tracing is not enabled, no messages are written to the trace message file; DBDK_TRACE_ERROR() still raises an error.

The syntax for the DBDK_TRACE_MSG() and DBDK_TRACE_ERROR() macros is as follows:

DBDK_TRACE_MSG(caller, mesgNo, level);
DBDK_TRACE_ERROR(caller, mesgNo, level);

 



caller

The name of the C routine to which you are adding the macro. 


mesgNo

The number for an error or trace message in the syserrors or systraceclasses system catalog. Use numbers for messages defined in the BladeSmith project or messages BladeManager installs with all DataBlade modules. 

See Defining Errors for instructions on creating error and trace messages with BladeSmith.

The standard error messages are listed in Standard Error Messages.


level

An integer that determines the trace level for the message. If level is less than or equal to the tracing threshold, then the message is printed in the trace file. For example, the trace level for the DBDK_TRACE_ENTER() and DBDK_TRACE_EXIT() macros is 20.

See Setting a Trace Output File and a Trace Threshold for more information. 

For example, if you have a function called ExmAmortize() and a trace message number UE001 with a trace level of 20, use the following code fragment to add tracing to the ExmAmortize() function:

DBDK_TRACE_MSG("ExmAmortize", "UE001", 20);

If you have tracing enabled and the trace threshold set to 20 or above, the DBDK_TRACE_ENTER() and DBDK_TRACE_EXIT() macros write messages to the trace file when the called routine is entered and exited, respectively. BladeSmith automatically adds these macros to generated code for every routine.

The syntax for the DBDK_TRACE_ENTER() and DBDK_TRACE_EXIT() macros is as follows:

DBDK_TRACE_ENTER(caller);
DBDK_TRACE_EXIT(caller);

The caller parameter specifies the name of the C routine to which you are adding the macro.

For example, if you have a routine called ExmAmortize(), the following code fragment sends a message to the message file when the ExmAmortize() routine is entered:

DBDK_TRACE_ENTER("ExmAmortize");

After you generate code with tracing and compile your code, enable tracing in your DataBlade module.

1. Create a trace class.
2. Create the TraceSet_project() procedure.

These steps are described in the following sections.

Tracing classes are categories of tracing that can be activated independently, allowing you to tune your tracing output to suspected problem areas.

To enable tracing in a database, you must insert the DataBlade trace class as a record in the systraceclasses system catalog.

The tracing generated by BladeSmith provides a single trace class, with the same name as your DataBlade project.

This example creates a trace class for the Business DataBlade module:

insert into informix.systraceclasses(name)
	values('Business');

You can create your own tracing classes for customized tracing. See the DataBlade API Programmer's Manual for more information.

The TraceSet_project() procedure (where project is the name of your DataBlade module project) sets the tracing output file and the trace threshold for a database server session by calling the DataBlade API functions mi_tracefile_set() and mi_tracelevel_set().

The TraceSet_project() procedure is included in generated source code by BladeSmith when you choose to generate code with tracing in the Generate DataBlade dialog box. Although the TraceSet_project() procedure is included in the generated C code, the SQL statements to create it in the database are not included in the generated SQL scripts. This omission prevents end-users from accessing the TraceSet_project() procedure from SQL statements.

After you install and register your DataBlade module in the database, create the TraceSet_project() procedure using the following SQL statement:

CREATE PROCEDURE TraceSet_project(LVARCHAR, INT)
WITH( NOT VARIANT )
EXTERNAL NAME 
"/$INFORMIXDIR/extend/project/project.bld(TraceSet_project)"
LANGUAGE C
END PROCEDURE;

project is the name of your DataBlade module.

Tip: The comments for the TraceSet_project() procedure in your source code show the exact syntax to create the procedure for your DataBlade module.

The syntax for using the TraceSet_project() procedure is as follows:

EXECUTE PROCEDURE TraceSet_project(
                    "traceFile",
                    traceThreshold
);

 



traceFile

The path and filename of the trace output file for the current database server session, surrounded by quotation marks. If you do not specify a filename, the default file, /tmp/session_ID.trc, is created. If you specify a filename and then execute TraceSet_project() again during the same session without specifying a filename, the filename is not changed.

See Setting a Trace Output File and a Trace Threshold for an example.


traceThreshold

The trace threshold for the current database server session. There are three possible values:

0              Tracing is disabled.

> 0      Tracing is enabled and the threshold is set to that number.

< 0      The tracing threshold is not changed.

See Setting a Trace Output File and a Trace Threshold for an example.

After you enable tracing in your DataBlade module, enable tracing for the database session. By default, when you start a database server session, tracing is disabled.

1. Set the appropriate locale environment variables.
2. Register tracing routines in the database with the EnableTracing.sh shell script.
3. Set the trace output file and the trace threshold for the current session.

These steps are described in the following sections.

The system only displays and writes messages to your session that match the locale specified in the session environment variables. Therefore, to see your trace messages, you must set the SERVER_LOCALE environment variable to the same locale you used when you created your messages in BladeSmith.

Tip: To determine the locale for your trace message, look at its properties in BladeSmith; click the message in the project view, under the Errors folder, and choose Edit Properties. See Error Locale for more information. Registering Tracing Routines

To register the tracing routines for a particular DataBlade module in a database, specify the following syntax from the UNIX command line or MKS Korn Shell:

EnableTracing.sh database DataBlade [Project]

In this command, database is the name of the database in which you want to register the routines and DataBlade is the name of the DataBlade module that contains the tracing routines. The square brackets [ ] indicate that Project name is an optional argument. Specify a path for Project if you have moved your DataBlade module from its default directory. When you specify Project, specify only the part of the path that follows %INFORMIXDIR%/extend/.

After you have registered the tracing routines in the database, set the output trace file and tracing level as shown in Setting a Trace Output File and a Trace Threshold. The filename and trace level settings must be reset if you change DB-Access sessions or restart the server.

To unregister the tracing routines for a particular DataBlade module in a database, specify the following syntax from the UNIX command line or MKS Korn Shell:

DisableTracing.sh database DataBlade [Project]

In this command, database is the name of the database in which you want to register the routines and DataBlade is the name of the DataBlade module that contains the tracing routines. The square brackets [ ] indicate that Project name is an optional argument. Specify a path for Project if you have moved your DataBlade module from its default directory. When you specify Project, specify only the part of the path that follows %INFORMIXDIR%/extend/.

Important: Disable tracing in production DataBlade modules because tracing can substantially decrease performance, and output trace files can use considerable space. Setting a Trace Output File and a Trace Threshold

To set the trace output file and the trace threshold, use the TraceSet_project() procedure. The DBDK_TRACE_ENTER() and DBDK_TRACE_EXIT() macros provided by BladeSmith use the trace level 20.

The following example sets the filename to Business.trc in the /tmp directory and sets the threshold to 20:

EXECUTE PROCEDURE TraceSet_Business("/tmp/Business.trc", 
20);

To change the trace output file without altering the trace threshold, specify the trace threshold as -1. To change the trace threshold without altering the trace output file, do not put a filename between the quotation marks.

BladeSmith uses a standard set of messages in the code that it generates. These messages are shared by all DataBlade modules created with BladeSmith and cannot be changed. BladeManager adds the error messages to the syserrors system catalog and the systracemsgs system catalog when a DataBlade module is registered in a database.

The messages have the same text and error numbers in the two system tables, except that messages in the systracemsgs system table include the text "(%FILENAME%, %LINENO%)" after the %FUNCTION% parameter to ensure that the source filename and line number appear in the trace file.

The following table lists the standard U.S. English DataBlade module error messages.

The generated header file defines constants ERRORMSG1 through ERRORMSG17 for these error numbers.

You can define additional messages used in your DataBlade module. Define them in the BladeSmith project to ensure that they are loaded into the database when your DataBlade module is registered. See Contacting the Informix Registry for information about reserving error codes for your DataBlade module.

BladeSmith generates support functions that it calls from other generated code. These functions include:

• Gen_IsMMXMachine(). This function determines whether the database server is running on a computer with an Intel MMX processor. This function is only generated if you specify that you want MMX-enabled functions when you generate source code. See The Gen_IsMMXMachine() Utility Function for more information.
• Gen_LoadLOFromFile(). When an opaque type includes a large object handle, BladeSmith includes this function to retrieve the large object data from a disk file.
• Gen_nstrwords(). This function counts the number of values (each separated by a blank space) in a formatted string. This function is called from input and import functions to retrieve values from variable-length opaque types.
• Gen_sscanf(). This function is called from input and import functions to convert text data to the C structure for an opaque type. See The Gen_sscanf() Utility Function for more information.
• Gen_StoreLOToFile(). When an opaque type includes a large object handle, BladeSmith includes this function to write large object data to a disk file.
• Gen_Trace(). This function processes trace messages and errors. This function is generally invoked by the macros DBDK_TRACE_ENTER(), DBDK_TRACE_EXIT(), DBDK_TRACE_MSG(), and DBDK_TRACE_ERROR(). See Tracing and Error Handling for more information.

Most of the generated utility functions are called by code that BladeSmith generates, and you typically do not use them in your code. The Gen_sscanf() utility function, however, can be useful in your input/output functions. You can use the Gen_IsMMXMachine() function if you use Intel MMX instructions in your code.

The Gen_sscanf() utility function scans one value from an input string and stores it at a given address. Gen_sscanf() returns a pointer that points just past the value it scanned from the input string.

Gen_sscanf() takes the following arguments:

The generated input and import functions call Gen_sscanf() once for each structure member. Gen_sscanf() requires an input string in the current locale and uses the Informix GLS routines to scan the string.

The Gen_IsMMXMachine() utility function can be used when you include Intel MMX media enhancement technology in your DataBlade module. The function tests the processor in the database server computer to determine if it has MMX technology support. If MMX technology support is found, Gen_IsMMXMachine() returns 1.

If the database server machine does not have MMX technology support, or if the FORCE_NO_MMX environment variable is set in the database server environment, Gen_IsMMXMachine() returns 0. On UNIX machines, Gen_IsMMXMachine() always returns 0.

To execute MMX instructions when possible and to execute portable C code on computers that do not have MMX technology support, call Gen_IsMMXMachine() in an IF statement.

Gen_IsMMXMachine() declares a static INT flag, MMXType. It first looks for the FORCE_NO_MMX environment variable, which must be set in the environment before the database server is started.

If FORCE_NO_MMX is found, the function sets MMXType to 0 without testing the CPU. If FORCE_NO_MMX is not found, the function tests the processor and sets the MMXType variable to 1 if MMX technology support is found or 0 if not. After the value of MMXType is set, Gen_IsMMXMachine() returns its value immediately, so that tests are performed once after the DataBlade module object file is loaded.