DataBlade Developers Kit User's Guide

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

Home Contents Index Master Index New Book

Using Generated Code

This section contains the following subsections:

In addition to references for each of the 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.

See the ExmAmortize() function in the Business example DataBlade module for an example of using the MI_FPARAM structure in an iterative function.

Server Connection Handle

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 Informix Dynamic 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.

Tracing and Error Handling

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").

How Tracing Works

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.

Adding Tracing and Error Handling

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.

(1 of 2)

Macro Action (if tracing is enabled)
DBDK_TRACE_MSG()
Prints a message in the trace file.

DBDK_TRACE_ERROR()
Prints a message in the trace file and raises an error by calling mi_db_error_raise().

DBDK_TRACE_ENTER()
Prints a message in the trace file upon entering a routine.

DBDK_TRACE_EXIT()
Prints a message in the trace file upon exiting a routine.

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.

The DBDK_TRACE_MSG() and DBDK_TRACE_ERROR() Macros

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, messgNo, level);
DBDK_TRACE_ERROR(caller, messgNo, level);
 


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

messgNo
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);

The DBDK_TRACE_ENTER() and DBDK_TRACE_EXIT() Macros

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");

Enabling Tracing in a DataBlade Module

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

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

Creating a Trace Class

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 Manualfor more information.

Creating the TraceSet_project Procedure

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.

Enabling Tracing in a Database Session

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.

To enable tracing in your DataBlade module

1. Set the appropriate locale environment variables.

2. Set the trace output file and the trace threshold for the current session.

These steps are described in the following sections.

Setting Your Locale

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.

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 without changing the trace threshold:

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.

Standard Error Messages

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

Utility Functions Generated by BladeSmith

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

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 parameters:

Gen_Con

The database connection handle

Gen_Caller

The name of the calling function

Gen_InData

A pointer to the text to be scanned

Gen_InDataLen

An integer containing the length of the text (mi_lvarchar strings are not null-terminated)

Gen_Width

An integer containing the maximum data length for text data

Gen_Format

A string containing a sscanf() format string for the structure member to be scanned

Gen_Result

A pointer to the member in the structure where Gen_sscanf() stores the scanned value

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

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.

DataBlade Developers Kit User's GuideChapter 5: Programming DataBlade Module Routines in C Home Contents Index Master Index New Book