The mi_tracefile_set() function

The mi_tracefile_set() function sets the trace-output file. The database server writes trace messages to this file.

Syntax

mi_integer mi_tracefile_set(filename)
   const mi_string *filename;
filename
The path name of the trace-output file for writing trace messages.
Valid in client LIBMI application? Valid in user-defined routine?
No Yes

Usage

The mi_tracefile_set() function sets the trace-output file to the path that filename references. The database server writes trace messages to this file when it encounters a trace statement in a UDR and the following conditions are true:
  • Tracing for the trace class specified in the trace message is turned on.
  • A tracepoint for an active trace class has a threshold less than the current trace level of that class.

For information about how to turn on a trace class, see the description of the mi_tracelevel_set() function.

If you do not call mi_tracefile_set(), the database server writes trace output to a system-defined trace-output file with the session identifier and a .trc file extension. You can obtain the current session identifier with the onstat -g ses command.

On UNIX™ or Linux™, the system-defined trace file is in the /tmp directory with the following file name: 
session_id.trc
In the preceding format, session_id is a system-assigned session identifier.
On Windows™, the system-defined trace file has the following path name: 
$drive:\tmp\session_id.trc
In the path name, $drive is the disk drive on which the HCL® OneDB® product is installed and session_id is a system-assigned session identifier.

You can change the destination of trace messages with the mi_tracefile_set() function. When you use mi_tracefile_set() to specify the trace-output file, the database server first attempts to append trace messages to that file. If the file that filename references does not exist, the database server creates a new trace-output file with the name filename. You must ensure that the directory where filename resides provides the user others or public with read and write permission.

The filename can specify a full path name or a file name. If you specify only a file name, the DataBlade® API puts the file in the working directory of the database server environment. This directory is the one in which the oninit (or its equivalent) was executed to start up the database server. If mi_tracefile_set() receives an invalid file name, it creates a system-defined trace file.

Return values

MI_OK
The function was successful.
MI_ERROR
The function was not successful.