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:
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:
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)
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);
See Defining Errors for instructions on creating error and trace messages with BladeSmith.
The standard error messages are listed in Standard Error Messages.
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.
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 IBM Informix: DataBlade API Programmer's Guide 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.
The syntax for using the TraceSet_project() procedure is as follows:
EXECUTE PROCEDURE TraceSet_project( "traceFile", traceThreshold );
See Setting a Trace Output File and a Trace Threshold for and example.
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.
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.
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/.
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 Developing Your DataBlade Module for information about reserving error codes for your DataBlade module.
Home | [ Top of Page | Previous Page | Next Page | Contents | Index ]