9 CTX_OUTPUT Package

This chapter provides reference information for using the CTX_OUTPUT PL/SQL package.

CTX_OUTPUT contains the following stored procedures:

Name	Description
ADD_EVENT	Add an event to the index log.
ADD_TRACE	Enable tracing.
END_LOG	Halt logging of index and document services requests.
END_QUERY_LOG	Stop logging queries into a logfile.
GET_TRACE_VALUE	Return the value of a trace.
LOG_TRACES	Print traces to logfile.
LOGFILENAME	Return the name of the current log file.
REMOVE_EVENT	Remove an event from the index log.
REMOVE_TRACE	Disable tracing.
RESET_TRACE	Clear a trace.
START_LOG	Start logging index and document service requests.
START_QUERY_LOG	Create a log file of queries.

---

ADD_EVENT

Use this procedure to add an event to the index log for more detailed log output.

Syntax

CTX_OUTPUT.ADD_EVENT(event in varchar2);

event

Specify the type of index event to log. You can add the following events:

• CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID, which logs the rowid of each row after it is indexed. This is useful for debugging a failed index operation.

• CTX_OUTPUT.EVENT_OPT_PRINT_TOKEN, which prints each token as it is being optimized.

Example

begin
CTX_OUTPUT.ADD_EVENT(CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID);
end;

---

ADD_TRACE

Use this procedure to enable a trace. If the trace has not been enabled, this call adds the trace to the list of active traces and resets its value to 0. If the trace has already been enabled, an error is raised.

Syntax

CTX_OUTPUT.ADD_TRACE(trace_id BINARY_INTEGER);

trace_id

Specify the ID of the trace to enable. See Table 9-1 for possible trace values.

Notes

Table 9-1 shows the available traces:

Table 9-1 Available Traces

Symbol	ID	Metric
IDX_USER_DATASTORE	1	time spent executing user datastore
IDX_INSO_FILTER	2	time spent invoking the INSO filter
QRY_XX_TIME	3	time spent executing the $X cursor
QRY_XF_TIME	4	time spent fetching from $X
QRY_X_ROWS	5	total number of rows whose token metadata was fetched from $X
QRY_IF_TIME	6	time spent fetching the LOB locator from $I
QRY_IR_TIME	7	time spent reading $I LOB information
QRY_I_ROWS	8	number of rows whose $I token_info was actually read
QRY_I_SIZE	9	number of bytes read from $I LOBs
QRY_R_TIME	10	time spent fetching and reading $R information
QRY_CON_TIME	11	time spent in CONTAINS processing (drexrcontains/drexrstart/drexrfetch)

Tracing is independent of logging. Logging does not have to be on to start tracing, and vice-versa.

Related Topics

See Also: "REMOVE_TRACE", "LOG_TRACES", and "RESET_TRACE", as well as the Oracle Text Application Developer's Guide

---

END_LOG

Halt logging index and document service requests

Syntax

CTX_OUTPUT.END_LOG;

Example

begin
CTX_OUTPUT.END_LOG;
end;

---

END_QUERY_LOG

Use this procedure to stop logging queries into a logfile created with CTX_OUTPUT.START_QUERY_LOG.

Syntax

CTX_OUTPUT.END_QUERY_LOG;

Example

begin

CTX_OUTPUT.START_QUERY_LOG('mylog1');
     < get queries >
CTX_OUTPUT.END_QUERY_LOG;

end;

---

GET_TRACE_VALUE

Use this procedure to programmatically retrieve the current value of a trace.

Syntax

CTX_OUTPUT.GET_TRACE_VALUE(trace_id BINARY_INTEGER);

trace_id

Specify the trace ID whose value you want. See Table 9-1, "Available Traces" for possible values.

Example

This sets the value of the variable value:

value := ctx_output.get_trace_value(trace_id);

Notes

You can also retrieve trace values through SQL:

select * from ctx_trace_values;

See "CTX_TRACE_VALUES" for the entries in the CTX_TRACE_VALUES view.

If the trace has not been enabled, an error is raised.

Traces are not reset to 0 by this call.

Related Topics

See Also: ADD_TRACE and the Oracle Text Application Developer's Guide

---

LOG_TRACES

Use this procedure to print all active traces to the logfile.

Syntax

CTX_OUTPUT.LOG_TRACES;

Notes

If logging has not been started, an error is raised.

Traces are not reset to 0 by this call.

This procedure looks for the logfile in the directory specified by the LOG_DIRECTORY system parameter, which is $ORACLE_HOME/ctx/log on UNIX. You can query the CTX_PARAMETERS view to find the current setting.

Related Topics

See Also: ADD_TRACE and the Oracle Text Application Developer's Guide

---

LOGFILENAME

Returns the filename for the current log. This procedure looks for the logfile in the directory specified by the LOG_DIRECTORY system parameter, which is $ORACLE_HOME/ctx/log on UNIX. You can query the CTX_PARAMETERS view to find the current setting.

Syntax

CTX_OUTPUT.LOGFILENAME RETURN VARCHAR2;

Returns

Log file name.

Example

declare
   logname varchar2(100);
begin
   logname := CTX_OUTPUT.LOGFILENAME;
   dbms_output.put_line('The current log file is: '||logname); 
end;

---

REMOVE_EVENT

Use this procedure to remove an event from the index log.

Syntax

CTX_OUTPUT.REMOVE_EVENT(event in varchar2);

event

Specify the type of index event to remove from the log. Currently the only event you can add and remove is the CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID.

Example

begin

CTX_OUTPUT.REMOVE_EVENT(CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID);

end;

---

REMOVE_TRACE

Use this procedure to disable a trace.

Syntax

CTX_OUTPUT.REMOVE_TRACE(trace_id BINARY_INTEGER);

trace_id

Specify the ID of the trace to disable. See Table 9-1, "Available Traces" for possible values.

Notes

If the trace has not been enabled, an error is raised.

Related Topics

See Also: ADD_TRACE and the Oracle Text Application Developer's Guide

---

RESET_TRACE

Use this procedure to clear a trace (that is, reset it to 0).

Syntax

CTX_OUTPUT.RESET_TRACE(trace_id BINARY_INTEGER);

trace_id

Specify the ID of the trace to reset. See Table 9-1, "Available Traces" for possible values.

Notes

If the trace has not been enabled, an error is raised.

Related Topics

See Also: ADD_TRACE and the Oracle Text Application Developer's Guide

---

START_LOG

Begin logging index and document service requests.

Syntax

CTX_OUTPUT.START_LOG(logfile in varchar2, overwrite in default true);

logfile

Specify the name of the log file. The log is stored in the directory specified by the system parameter LOG_DIRECTORY.

overwrite

Specify whether you want to overwrite or append to the original query log file specified by logfile, if it already exists. The default is to overwrite the original query log file.

Example

begin
CTX_OUTPUT.START_LOG('mylog1');
end;

Notes

Logging is independent of tracing. Logging does not have to be on to start tracing, and vice-versa.

---

START_QUERY_LOG

Begin logging query requests into a query log file.

Use CTX_OUTPUT.END_QUERY_LOG to stop logging queries. Use CTX_REPORT.QUERY_LOG_SUMMARY to obtain reports on logged queries, such as which queries returned successfully the most times.

The query log includes the query string, the index name, and the timestamp of the query, as well as whether or not the query successfully returned a hit. A successful query for the phrase Blues Guitarists made at 6:46 (local time) on November 11th, 2003, would be entered into the query log in this form:

<QuerySet><TimeStamp>18:46:51 02/04/03</TimeStamp><IndexName>
IDX_SEARCH_TABLE</IndexName><Query>Blues Guitarists</Query><ReturnHit>Yes</ReturnHit></QuerySet>

Syntax

CTX_OUTPUT.START_QUERY_LOG(logfile in varchar2, overwrite in default true);

logfile

Specify the name of the query log file. The query log is stored in the directory specified by the system parameter LOG_DIRECTORY.

overwrite

Specify whether you want to overwrite or append to the original query log file specified by logfile, if it already exists. The default is to overwrite the original query log file.

Example

begin

CTX_OUTPUT.START_QUERY_LOG('mylog1');
     < get queries >
CTX_OUTPUT.END_QUERY_LOG;

end;