| Oracle® Text Reference 10g Release 2 (10.2) Part Number B14218-01 |
|
|
View PDF |
| Oracle® Text Reference 10g Release 2 (10.2) Part Number B14218-01 |
|
|
View PDF |
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. |
Use this procedure to add an event to the index log for more detailed log output.
Syntax
CTX_OUTPUT.ADD_EVENT(event in NUMBER);
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.
CTX_OUTPUT.EVENT_INDEX_PRINT_TOKEN, which prints the each token as it is being indexed.
Example
begin CTX_OUTPUT.ADD_EVENT(CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID); end;
Related Topics
See Also:
REMOVE_EVENTUse 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);
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 |
|---|---|---|
TRACE_IDX_USER_DATASTORE |
1 | time spent executing user datastore |
TRACE_IDX_AUTO_FILTER |
2 | time spent invoking the AUTO_FILTER filter. (Replaces the deprecated TRACE_IDX_INSO_FILTER trace) |
TRACE_QRY_XX_TIME |
3 | time spent executing the $X cursor |
TRACE_QRY_XF_TIME |
4 | time spent fetching from $X |
TRACE_QRY_X_ROWS |
5 | total number of rows whose token metadata was fetched from $X |
TRACE_QRY_IF_TIME |
6 | time spent fetching the LOB locator from $I |
TRACE_QRY_IR_TIME |
7 | time spent reading $I LOB information |
TRACE_QRY_I_ROWS |
8 | number of rows whose $I token_info was actually read |
TRACE_QRY_I_SIZE |
9 | number of bytes read from $I LOBs |
TRACE_QRY_R_TIME |
10 | time spent fetching and reading $R information |
TRACE_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.
Traces are associated with a session—they can measure operations that take place within a single session, and conversely, cannot make measurements across sessions.
During parallel sync or optimize, the trace profile will be copied to the slave sessions if and only if tracing is currently enabled. Each slave will accumulate its own traces and implicitly write all trace values to the slave logfile before termination.
Related Topics
See Also:
"REMOVE_TRACE", "GET_TRACE_VALUE", "LOG_TRACES",and "RESET_TRACE", as well as the Oracle Text Application Developer's GuideHalt logging index and document service requests
Syntax
CTX_OUTPUT.END_LOG;
Example
begin CTX_OUTPUT.END_LOG; end;
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;
Use this procedure to programmatically retrieve the current value of a trace.
Syntax
CTX_OUTPUT.GET_TRACE_VALUE(trace_id BINARY_INTEGER);
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.
Traces are associated with a session—they can measure operations that take place within a single session, and conversely, cannot make measurements across sessions.
Related Topics
See Also:
"REMOVE_TRACE", "ADD_TRACE", "LOG_TRACES",and "RESET_TRACE", as well as the Oracle Text Application Developer's GuideUse 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:
"REMOVE_TRACE", "GET_TRACE_VALUE", "ADD_TRACE", and "RESET_TRACE", as well as the Oracle Text Application Developer's GuideReturns 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;
Use this procedure to remove an event from the index log.
Syntax
CTX_OUTPUT.REMOVE_EVENT(event in NUMBER);
Specify the type of index event to remove from the log. You can remove 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.
CTX_OUTPUT.EVENT_INDEX_PRINT_TOKEN, which prints the each token as it is being indexed.
Example
begin
CTX_OUTPUT.REMOVE_EVENT(CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID);
end;
Related Topics
See Also:
ADD_EVENTUse this procedure to disable a trace.
Syntax
CTX_OUTPUT.REMOVE_TRACE(trace_id BINARY_INTEGER);
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:
"GET_TRACE_VALUE", "ADD_TRACE", "LOG_TRACES",and "RESET_TRACE", as well as the Oracle Text Application Developer's GuideUse this procedure to clear a trace (that is, reset it to 0).
Syntax
CTX_OUTPUT.RESET_TRACE(trace_id BINARY_INTEGER);
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:
"REMOVE_TRACE", "GET_TRACE_VALUE", "ADD_TRACE", "LOG_TRACES", as well as the Oracle Text Application Developer's GuideBegin logging index and document service requests.
Syntax
CTX_OUTPUT.START_LOG(logfile in varchar2, overwrite in default true);
Specify the name of the log file. The log is stored in the directory specified by the system parameter LOG_DIRECTORY.
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.
Logging is associated with a session—it can log operations that take place within a single session, and, conversely, cannot make measurements across sessions.
Filenames used in CTX_OUTPUT.START_LOG are restricted to the following characters: alphanumeric, minus, period, space, hash, underscore, single and double quotes. Any other character in the filename will raise an error.
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);
Specify the name of the query log file. The query log is stored in the directory specified by the system parameter LOG_DIRECTORY.
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;
Notes
Filenames used in CTX_OUTPUT.START_QUERY_LOG are restricted to the following characters: alphanumeric, minus, period, space, hash, underscore, single and double quotes. Any other character in the filename will raise an error.
Logging is associated with a session—it can log operations that take place within a single session, and, conversely, cannot make measurements across sessions.
