Release 2.4
A63821-01
Library |
Product |
Contents |
Index |
| Oracle8
ConText Cartridge Application Developer's Guide
Release 2.4 A63821-01 |
|
This chapter describes the ConText Option PL/SQL packages you use to develop applications. The following topics are described in this chapter are:
Before you can develop your own PL/SQL stored procedures
and triggers that call the procedures in the ConText packages described
in this chapter, your ConText administrator must explicitly grant EXECUTE
privileges to you for each ConText PL/SQL package you use.
| See
Also:
For more information about granting execute privileges, see Oracle8 ConText Cartridge Administrator's Guide. For more information about creating and invoking PL/SQL packages, see Oracle8 Application Developer's Guide. |
The CTX_QUERY package contains stored procedures and functions
that enable processing of two-step queries and highlighting for documents
returned by queries.
The package includes the following procedures and functions:
The CTX_QUERY.CLOSE_CON procedure closes a cursor
opened by CTX_QUERY.OPEN_CON. The CLOSE_CON
procedure is used in in-memory queries and called after CTX_QUERY.FETCH_HIT,
which retrieves the desired number of hits.
CTX_QUERY.CLOSE_CON(curid NUMBER);
Specify the cursor to be closed.
See CTX_QUERY.FETCH_HIT.
The CTX_QUERY.CONTAINS procedure selects documents
from a text column that match the specified search criteria, generates
scores for each document, and writes the results to a specified hitlist
result table.
CTX_QUERY.CONTAINS( policy_name[@dblink] IN VARCHAR2, text_query IN VARCHAR2, restab IN VARCHAR2, sharelevel IN NUMBER DEFAULT 0, query_id IN NUMBER, cursor_id IN NUMBER, parallel IN NUMBER, struct_query IN VARCHAR2);
Specify the policy that identifies the text column to be
searched.
If a database link to a remote database has been created, the database link can be specified as part of the policy name (using the syntax shown) to reference a policy in the remote database.
Specify the query expression to be used as criteria for selecting
rows.
| See
Also:
For more information about how to write query expressions, see Chapter 3, "Understanding Query Expressions". |
Specify the name of the hitlist table that stores intermediate results returned by CONTAINS.
Specify whether the results table is shared by multiple CONTAINS.
Specify 0 for exclusive use and 1 for shared use. This parameter defaults
to 0 (single-use).
When you specify 0, the system automatically truncates the
result table before the query. In this case, conid is set to NULL
and query_id is ignored.
When you specify 1 for multiple use, you must give a query_id to distinguish the results in the shared result table. Because the system does not truncate shared result tables, you must get rid of results from a previous CONTAINS by deleting from the result table where conid = query_id before you issue the query.
Specify the ID used to identify query results returned by a CONTAINS procedure when more than one CONTAINS uses the same result table (sharelevel = 1).
Not currently used.
Specify the number of ConText servers (with the Query personality) which execute a query and write the results to restab.
Specify the structured WHERE condition related to text_query.
This WHERE condition can include a subquery that selects rows from a structured
data column in another table.
exec ctx_query.contains('my_pol', 'cat|dog','CTX_TEMP', 1, 10) exec ctx_query.contains('my_pol@db1', 'oracle','CTX_DB1_TEMP')
In the first example, the results of the query for the term
cat or dog are stored in the ctx_temp result table.
The result table is shared because sharelevel is specified as 1.
The results in ctx_temp are identified by query_id of 10.
In the second example, my_pol exists in a remote database
that has a database link named DB1. The result table, ctx_db1_temp
exists in the same remote database.
The parallel parameter does not support the
max ( : ) and first/next ( #) query expression operators. When you specify
either operator in the query expression, the query is processed by a single
ConText server, regardless of the specified parallel level.
sharelevel determines whether the hitlist result table
is shared by multiple CONTAINS procedures.
If the result table (restab) is used to hold the results
of multiple CONTAINS, a sharelevel must be specified by each CONTAINS
so that the results of previous CONTAINS are not truncated.
If a query is performed on a policy in a remote database,
the result table specified by restab must exist in the remote database.
In struct_query, you can use any predicate, value
expression or subquery except USERENV function, CONTAINS function, SCORE
function, DISPLAY function and the ROWNUM pseudo column.
If the user who includes a structured query in a two-step
query is not the owner of the table containing the structured and text
columns, the user must have SELECT privilege with GRANT OPTION on the table.
In addition, if the object being queried is a view, the user must have
SELECT privilege with GRANT OPTION on the base table for the view.
| See
Also:
For more information about SELECT privilege with GRANT OPTION, see Oracle8 SQL Reference. |
The CTX_QUERY.COUNT_HITS function executes a query
for a policy and returns the number of hits for the query. It does not
populate a result table with query results.
COUNT_HITS can be called in two modes, estimate and exact.
The results in estimate mode may be inaccurate; however, the results are
generally returned faster than in exact mode.
CTX_QUERY.COUNT_HITS( policy_name[@dblink] IN VARCHAR2, text_query IN VARCHAR2, struct_query IN VARCHAR2, exact IN BOOLEAN DEFAULT FALSE) RETURN NUMBER;
Specify the name of the policy that defines the column to
be searched.
If a database link to a remote database has been created, the database link can be specified as part of the policy name (using the syntax shown) to reference a policy in the remote database.
Specify the query expression to be used as criteria for counting returned hits (rows)
Specify the structured where condition related to text_query.
Specify TRUE to obtain an exact count of the documents in
the hitlist. Specify FALSE to obtain an estimate count. The result returned
when you request an estimate count includes hits for documents that have
been deleted or updated. The default is FALSE.
NUMBER that represents the number of hits.
declare count number; begin count := ctx_query.count_hits(my_pol, 'dog|cat', TRUE); dbms_output.put_line('No. of Docs with dog or cat:'); dbms_output.put_line(count); end;
Counting query hits can be performed in two modes: estimate
and exact. The modes are based on the method ConText uses to record deleted
documents in a text index.
In exact mode, hits are returned only for those documents
that satisfy the conditions of the query expression and are currently in
the text column of the table.
In estimate mode, hits may be included for documents that
satisfy the query condition, but have been deleted from the text column
or have been updated so that they no longer satisfy the query expression.
This can occur when the text index for the column has not been optimized
and the internal document IDs are still present in the index.
In general, the inaccuracy of the results returned by COUNT_HITS
in estimate mode is proportional to the amount of DML that has been performed
on a text column.
|
Note: If the index being queried has been optimized and no further DML has been performed on the text column, estimate mode will return accurate results. |
| See
Also:
For more information about text indexing, DML, and optimization, see Oracle8 ConText Cartridge Administrator's Guide. |
Use the CTX_QUERY.COUNT_LAST function to obtain the number
of hits after executing CONTAINS in a two-step
query or OPEN_CON in an in-memory query. The
alternative method of obtaining the number of hits is to run the query
once to get the row count using CTX_QUERY.COUNT_HITS
and then run the query again to get the query results.
CTX_QUERY.COUNT_LAST RETURN NUMBER;
The number of hits obtained from the last call to CTX_QUERY.CONTAINS
or CTX_QUERY.OPEN_CON.
declare curid number; count number; begin curid := ctx_query.open_con('mypol', 'me', score_sorted=>true); count := ctx_query.count_last ; end
declare count number; begin ctx_query.contains('mypol', 'dog', 'ctx_temp'); count := ctx_query.count_last ; end
With two-step queries, COUNT_LAST always returns an exact
count.
With in-memory queries, COUNT_LAST returns an exact count
except when you include a structured condition, in which case it returns
an estimate. This is because COUNT_LAST ignores the structured condition,
specified in the struct_query parameter of OPEN_CON, when computing
number of hits in an in-memory query.
For two-step queries, the COUNT_LAST function is not meant
to replace calling COUNT_HITS, which is always faster than running the
query. However, in the case where you want to process all hits in a two-step
query, issuing the query with CONTAINS and then calling COUNT_LAST is more
efficient than calling COUNT_HITS and then calling CONTAINS.
With in-memory queries, issuing OPEN_CON and then calling
COUNT_LAST is always a more efficient way to obtain an estimate of the
query hits over calling COUNT_HITS and then calling OPEN_CON, since COUNT_LAST
returns a number faster than COUNT_HITS.
Use CTX_QUERY.FEEDBACK to generate feedback information for
query expressions. This procedure creates a graphical representation of
the ConText parse tree and stores the information in a feedback table.
CTX_QUERY.FEEEDBACK( policy_name IN VARCHAR2, text_query IN VARCHAR2, feedback_table IN VARCHAR2, sharelevel IN NUMBER DEFAULT 0, feedback_id IN VARCHAR2 DEFAULT NULL);
Specify the policy that identifies the text column to be queried.
Specify the query expression to be used as criteria for selecting rows.
Specify the name of the feedback table to store representation of the ConText parse tree for text_query.
Specify whether feedback_table is shared by multiple
FEEDBACK calls. Specify 0 for exclusive use and 1 for shared use. This
parameter defaults to 0 (single-use).
When you specify 0, the system automatically truncates the
feedback table before the next call to FEEDBACK.
When you specify 1 for shared use, Context does not truncate the feedback table. Only results with the same feedback_id are updated. When no results with the same feedback_id exist, then new results are added to the feedback table.
Specify a name that identifies the feedback results returned
by a FEEDBACK procedure when more than one FEEDBACK call uses the same
shared feedback table. This parameter defaults to NULL.
The user must have at least INSERT and DELETE privileges
on the feedback table. You must have at least CTXUSER role to call FEEDBACK.
When you include a wildcard, fuzzy, or soundex operator in
text_query, ConText looks at the index tables to determine the expansion.
When you include the SQE operator in text_query, the
expression feedback (expansion of the SQE expression) is based on the current
state of the index and will take into account any inserts, updates, or
deletes made to the base table; however, unlike a call to CONTAINS, the
SQE is not updated or refreshed as a result of the call to FEEDBACK.
Wildcard, fuzzy (?), and soundex (!) expression feedback
does not account for lazy deletes.
You cannot use FEEDBACK with remote queries.
To use the FEEDBACK procedure, you must have at least one
Q server running.
| See
Also:
For more information on using the FEEDBACK procedure, see Chapter 5, "Query Expression Feedback". |
The CTX_QUERY.FETCH_HIT function returns a hit stored
in the query buffer created by CTX_QUERY.OPEN_CON.
You must call FETCH_HIT once for each hit in the buffer until the desired
number of hits is returned or the buffer is empty.
CTX_QUERY.FETCH_HIT( curid IN NUMBER, pk OUT VARCHAR2, score OUT NUMBER, col1 OUT VARCHAR2, col2 OUT VARCHAR2, col3 OUT VARCHAR2, col4 OUT VARCHAR2, col5 OUT VARCAHR2);
Specify the cursor opened by CTX_QUERY.OPEN_CON.
Returns the primary key of the document. When the primary key is a composite textkey, PK is returned as encoded string. In this situation, use CTX_QUERY.PKDECODE to access an individual textkey column.
Returns the score of the document.
Returns additional columns for the document.
NUMBER that indicates whether hit was retrieved: 0 if no
hits fetched, 1 if hit was fetched.
declare score char(5); pk char(5); curid number; title char(256); begin dbms_output.enable(100000); curid := ctx_query.open_con( policy_name => 'MY_POL', text_query => 'dog', score_sorted => true, other_cols => 'title'); while (ctx_query.fetch_hit(curid, pk, score, title)>0) loop dbms_output.put_line(score||pk||substr(title,1,50)); end loop; ctx_query.close_con(curid); end;
If the primary key PK is a composite textkey, use CTX_QUERY.PKDECODE
to access the individual columns of the textkey.
CTX_QUERY.GETTAB procedure allocates result tables from the
result table pool to be used to store results from CTX_QUERY.HIGHLIGHT
or CTX_QUERY.CONTAINS.
If no result table of the specified type exists, GETTAB creates
a new table.
CTX_QUERY.GETTAB( type IN VARCHAR2, tab OUT VARCHAR2, tk_count IN NUMBER DEFAULT 1);
Specify the type of table to be allocated for text processing.
This parameter must be fully qualified with the PL/SQL package name (CTX_QUERY).
The type of table you specify can be one of the following:
| See
Also:
For more information about the structure of result tables, see Appendix A, "Result Tables". For more information about using HIGHLIGHT, see Chapter 6, "Document Presentation: Highlighting". |
Returns the name of the allocated table.
Specify the number of textkeys in the allocated result table.
This parameter applies only to HITTAB tables. The tk_count parameter
defaults to 1.
set serveroutput on declare mytab varchar2(32) ; begin ctx_query.gettab(CTX_QUERY.HITTAB, mytab, 3) ; dbms_output.put_line('table : '||mytab) ; end ;
This example returns a HITTAB result table that has a three-column
composite textkey. The name of the table is then output.
The schema for the returned table is: TEXTKEY, TEXTKEY2,
TEXTKEY3, SCORE, CONID.
The tk_count parameter applies only to HITTAB tables;
it has no effect on other table types.
THE CTX_QUERY.HIGHLIGHT procedure takes a query specification
and a document textkey and returns information that you can use to display
the document with or without the query terms highlighted. This procedure
is usually used after a query, from which you identify the document to
be processed.
CTX_QUERY.HIGHLIGHT( cspec IN VARCHAR2, textkey IN VARCHAR2, query IN VARCHAR2 DEFAULT NULL, id IN NUMBER DEFAULT NULL, nofilttab IN VARCHAR2 DEFAULT NULL, plaintab IN VARCHAR2 DEFAULT NULL, hightab IN VARCHAR2 DEFAULT NULL, icftab IN VARCHAR2 DEFAULT NULL, mutab IN VARCHAR2 DEFAULT NULL, starttag IN VARCHAR2 DEFAULT NULL, endtag IN VARCHAR2 DEFAULT NULL);
Specify the policy name for the column in which the document is stored.
Specify the unique identifier (usually the primary key) for
the document.
The textkey parameter can be a single column textkey or an encoded specification for a composite (multiple column) textkey.
Specify the original query expression used to retrieve the
document. If NULL, no highlights are generated.
If query includes wildcards, stemming, fuzzy matching
which result in stopwords being returned, HIGHLIGHT does not highlight
the stopwords.
If query contains a result set operator (threshold, max, or first/next), the operator is ignored. The HIGHLIGHT procedure always returns highlight information for the entire result set.
Specify the identifier to be used in the results tables to identify the rows that were returned by this procedure call. If NULL, the result tables are truncated.
Specify name of the RDOCTAB table where unfiltered document is stored. If NULL, the unfiltered version is not returned.
Specify the name of the DOCTAB table where plain text version of document is stored. If NULL, the plain text is not returned.
Specify the name of the HIGHTAB table where highlight information for the document is stored. If NULL, the highlight information is not returned.
Used internally by the Windows 32-bit viewer to specify where the ICF output required for WYSIWYG viewing of documents is stored. If NULL, the ICF is not returned.
Specify table where marked-up, plain text version of document is stored. If NULL, marked-up version is not returned.
Specify the markup to be inserted by HIGHLIGHT for indicating
the start of a highlighted term.
The default for ASCII and formatted documents is'<<<'.
The default for HTML documents filtered using an external
filter is'<<<'.
The default for HTML documents filtered using the internal HTML filter is the HTML tag used to indicate the beginning of a font change (i.e. <FONT =...>).
Specify the markup to be inserted by HIGHLIGHT for indicating
the end of a highlighted term.
The default for ASCII and formatted documents is'>>>'.
The default for HTML documents filtered using an external
filter is'>>>'.
The default for HTML documents filtered using the internal
HTML filter is the HTML tag used to indicate the end of a font change (i.e.
</FONT>).
begin ctx_query.highlight(cspec => '2354', textkey => '23', query => 'dog|cat', nofiltab => 'FORMATTED_TEXT', hightab => 'HIGHLIGHTED_TEXT', starttag => '<**<', endtag => '>**>'); end;
Before CTX_QUERY.HIGHLIGHT is called, the highlight/display
result tables (NOFILTAB, PLAINTAB, HIGHTAB, MUTAB, and ICFTAB) for the
desired output must be created, either manually or using the PL/SQL procedure
CTX_QUERY.GETTAB.
If the query argument is not specified or is set to
NULL, highlighting is not generated.
If query includes wildcards, stemming, fuzzy matching
which result in stopwords being returned, HIGHLIGHT does not highlight
the stopwords.
If the query expression query contains a result set
operator (threshold, max, or first/next), the operator is ignored. Highlight
always returns highlight information for the entire result set.
When textkey is a composite textkey, you must encode
the composite textkey string using the CTX_QUERY.PKENCODE
procedure.
If any of the table name parameters are omitted or set to
NULL, the respective table is not populated.
If the id argument is not specified or if id
is set to NULL, each specified table has all its rows deleted and the session-id
is used as the ID for all inserted rows. If an id is specified,
all rows with the same id are deleted from the respective tables
before new rows are generated with that id by the HIGHLIGHT procedure.
For HTML documents filtered through the internal HTML filter,
the plain text output generated for MUTAB retains the HTML tags from the
original document.
For HTML documents filtered through an external filter, HIGHLIGHT
removes all the HTML tags and stores only the plain (ASCII) marked-up text
for the document in MUTAB.
| See
Also:
For more information about internal and external filters, see Oracle8 ConText Cartridge Administrator's Guide. For more information about the structure of result tables, see Appendix A, "Result Tables". |
The CTX_QUERY.OPEN_CON function opens a cursor to
a query buffer and executes a query using the specified query expression.
The results of the query are stored in the buffer and retrieved using CTX_QUERY.FETCH_HIT.
CTX_QUERY.OPEN_CON( policy_name[@dblink] IN VARCHAR2, text_query IN VARCHAR2, score_sorted IN BOOLEAN DEFAULT FALSE, other_cols IN VARCHAR2, struct_query IN VARCHAR2) RETURN NUMBER;
Specify the name of the policy that defines the column to
be searched.
If a database link to a remote database has been created, the database link can be specified as part of the policy name (using the syntax shown) to reference a policy in the remote database.
Specify the query expression to be used as criteria for selecting rows.
Specify whether the results are sorted by score.
The default is FALSE.
Specify a comma separated list of the table columns (up to 5) to be displayed, in addition to document ID and score, in the hitlist.
Specify the structured WHERE condition related to text_query.
This WHERE condition can include a subquery that selects rows from a structured
data column in another table.
declarecid number;
begincid := ctx_query.open_con('MYPOL', 'dog', score_sorted =>true, struct_query => 'id < 900');
end;
In this example, the structured condition specifies that
ConText must return the documents that contain dog and where the
document id is greater than 900.
| See
Also:
CTX_QUERY.FETCH_HIT. |
The CTX_QUERY.PKDECODE function extracts and returns a composite
textkey element from a composite textkey string.
This function is useful for in-memory queries when querying
against a composite textkey table. Use PKDECODE to extract textkey columns
from the primary key returned by CTX_QUERY.FETCH_HIT.
CTX_QUERY.PKDECODE( encoded_tk IN VARCHAR2, which IN NUMBER) RETURN VARCHAR2;
Specify the encoded composite textkey string
Specify the ordinal position of which primary key to extract
from encoded_tk. When which is 0 or a number greater than
the number of textkeys in encoded_tk, encoded_tk is returned.
String that represents the decoded value of the composite
textkey.
declare pkey varchar2(64); begin pkey := ctx_query.pkdecode('p1,p2,p3', 2) pkey := ctx_query.pkdecode('p1,p2,p3', 0) pkey := ctx_query.pkdecode('p1,p2,p3', 5) end;
In this example, the value for the textkey is p1,p2,p3.
The first call to PKDECODE returns the value p2. The second and
third calls to PKDECODE specify ordinal positions that don't exist, thus
these calls return the same value, which is the concatenated value p1,p2,p3.
The CTX_QUERY.PKENCODE function converts a composite textkey
list into a single string and returns the string.
The string created by PKENCODE can be used as the primary
key parameter PK in other ConText procedures, such as CTX_LING.REQUEST_GIST.
CTX_QUERY.PKENCODE( pk1 IN VARCHAR2, pk2 IN VARCHAR2, pk4 IN VARCHAR2, pk5 IN VARCHAR2, pk6 IN VARCHAR2, pk7 IN VARCHAR2, pk8 IN VARCHAR2, pk9 IN VARCHAR2, pk10 IN VARCHAR2, pk11 IN VARCHAR2, pk12 IN VARCHAR2, pk13 IN VARCHAR2, pk14 IN VARCHAR2, pk15 IN VARCHAR2, pk16 IN VARCHAR2) RETURN VARCHAR2;
Each PK argument specifies a column element in the composite
textkey list. You can encode at most 16 column elements.
String that represents the encoded value of the composite
textkey.
exec ctx_ling.request_gist('my_policy',CTX_QUERY.PKENCODE('pk1-date', 'pk2-data'), 'theme table')
In this example, pk1-date and pk2-data constitute
the composite textkey value for the document.
The CTX_QUERY.PURGE_SQE procedure removes all session
stored query expressions for the current session. Session SQEs in other
sessions are not affected by PURGE_SQE.
CTX_QUERY.PURGE_SQE(policy_name IN VARCHAR2);
Specify the name of the policy for which the current session
SQEs are purged.
exec ctx_query.purge_sqe(my_pol)
The CTX_QUERY.REFRESH_SQE procedure re-executes a
stored query expression and stores the results in the SQR table, overwriting
existing results.
| See
Also:
For more information about the structure of the SQR table, see Oracle8 ConText Cartridge Administrator's Guide. |
CTX_QUERY.REFRESH_SQE( policy_name IN VARCHAR2, query_name IN VARCHAR2);
Specify the policy for the stored query expression.
Specify the name of the stored query expression to be refreshed.
exec ctx_query.refresh_sqe('my_pol', 'DOG')
The CTX_QUERY.RELTAB procedure releases a table previously
allocated by CTX_QUERY.GETTAB.
CTX_QUERY.RELTAB(tab IN VARCHAR2);
Specify the name of table to be released, previously assigned
by CTX_QUERY.GETTAB.
set serveroutput on declare mytab varchar2(32) ; begin ctx_query.gettab(CTX_QUERY.HITTAB, mytab, 3) ; dbms_output.put_line('table : '||mytab) ; .... ctx_query.reltab(mytab); end ;
This PL/SQL example allocates a HITTAB result table with
GETTAB, then releases it with RELTAB.
The CTX_QUERY.REMOVE_SQE procedure removes a specified
stored query expression from the system SQE table and the results of the
SQE from the SQR table for the policy.
| See
Also:
For more information about the structure of the SQE and SQR tables, see Oracle8 ConText Cartridge Administrator's Guide. |
CTX_QUERY.REMOVE_SQE( policy_name IN VARCHAR2, query_name IN VARCHAR2);
Specify the policy for the stored query expression.
Specify the name of the stored query expression to be removed.
exec ctx_query.remove_sqe('my_pol', 'DOG')
The CTX_QUERY.STORE_SQE procedure executes a query
for a policy and stores the named SQE in the SQE table and results from
the SQE in the SQR table for the policy.
| See
Also:
For more information about the structure of the SQE and SQR tables, see Oracle8 ConText Cartridge Administrator's Guide. |
CTX_QUERY.STORE_SQE( policy_name IN VARCHAR2, query_name IN VARCHAR2, text_query IN VARCHAR2, scope IN VARCHAR2);
Specify the policy for the stored query expression.
Specify the name of the stored query expression to be created.
Specify the query expression.
Specify whether the SQE is a session or system.
When you specify session, the stored query expression exists only
for the current session. When you specify system, the stored query
expression can be used in all sessions including concurrent sessions. SQEs
defined as system are not deleted when your session terminates.
exec ctx_query.store_sqe('my_pol', 'DOG', '$(dogs|puppy)','session')
SQEs support all of the ConText query expression operators, except for:
SQEs also support all of the special characters and other
components that can be used in a query expression, including PL/SQL functions
and other SQEs.
CTX_LING is the package of PL/SQL procedures used to request
linguistic output and to control how requests are submitted and processed
by ConText servers with the Linguistics personality.
CTX_LING contains the following stored procedures and functions:
The CTX_LING.CANCEL procedure cancels all pending linguistic
requests cached in memory.
CTX_LING.CANCEL ;
exec ctx_ling.cancel
Requests for themes and gists are cached in memory until
CTX_LING.SUBMIT is called. CTX_LING.CANCEL
only cancels these cached requests. After these requests have been submitted
and placed in the Service Queue, CTX_LING.CANCEL has no effect.
To cancel requests that have already been submitted to the
Services Queue, use CTX_SVC.CANCEL.
The CTX_LING.GET_COMPLETION_CALLBACK function returns the
name of the completion callback procedure for the current session (specified
in CTX_LING.SET_COMPLETION_CALLBACK).
CTX_LING.GET_COMPLETION_CALLBACK RETURN VARCHAR2;
Completion callback procedure.
declare callback varchar2(60); begin callback := get_completion_callback; dbms_output.put_line('Completion callback:'); dbms_output.put_line(callback); end;
To call procedures for both completed task processing as
well as error processing, you must also identify the error completion processing
routine with CTX_LING.SET_COMPLETION_CALLBACK.
If both completion and error callback procedures are defined,
the completion callback routine is performed first, then the error callback
routine.
The value assigned to VARCHAR2 in the declarative part of
the PL/SQL block depends on the length of the name for the specified completion
callback.
The CTX_LING.GET_ERROR_CALLBACK function returns the name
of the error callback procedure for the current session (specified in CTX_LING.SET_ERROR_CALLBACK).
CTX_LING.GET_ERROR_CALLBACK RETURN VARCHAR2;
declare e_callback varchar2(60); begin e_callback := ctx_ling.get_error_callback; dbms_output.put_line('Error callback:'); dbms_output.put_line(e_callback); end;
If both completion and error callback are set, the completion
callback is performed first, then the error callback.
The value assigned to VARCHAR2 in the declarative part of
the PL/SQL block depends on the length of the name for the specified completion
callback.
This function returns TRUE if the generation of theme hierarchy
information is enabled for the current session; otherwise it returns FALSE.
You enable the generation of theme hierarchy information
with SET_FULL_THEMES. ConText writes theme
hierarchy information to the THEME column of the theme table when you call
REQUEST_THEMES.
CTX_LING.GET_FULL_THEMES RETURN BOOLEAN;
Returns TRUE if the generation of theme hierarchy information
is enabled; otherwise returns FALSE.
The CTX_LING.GET_LOG_PARSE function returns a FALSE or TRUE
string to indicate whether parse logging is enabled for the current database
session (specified in CTX_LING.SET_LOG_PARSE).
CTX_LING.GET_LOG_PARSE RETURN BOOLEAN;
TRUE if parse logging is enabled, FALSE if parse logging
is not enabled.
declare parse_logging boolean; begin parse_logging := get_log_parse; end;
The CTX_LING.GET_SETTINGS_LABEL function returns the label
for the setting configuration that is active for the current session (specified
in CTX_LING.SET_SETTINGS_LABEL).
CTX_LING.GET_SETTINGS_LABEL RETURN VARCHAR2;
Current settings configuration label.
declare settings varchar2(60); begin settings := get_settings_label; dbms_output.put_line('Current setting configuration:'); dbms_output.put_line(settings); end;
The value assigned to VARCHAR2 in the declarative part of
the PL/SQL block depends on the character length of the label for the specified
setting configuration. The maximum length of a setting configuration label
is 80 characters.
Use the CTX_LING.REQUEST_GIST procedure to generate theme
summaries and a Gist for a document. You can generate paragraph-level or
sentence-level Gists and theme summaries.
By default, this procedure generates theme summaries for
all the themes in a document (up to 50); however, you can specify a single
theme for which a theme summary is to be generated.
CTX_LING.REQUEST_GIST( policy IN VARCHAR2, pk IN VARCHAR2, table IN VARCHAR2, glevel IN VARCHAR2 DEFAULT `PARAGRAPH', pov IN VARCHAR2 DEFAULT NULL);
Specify the name of the ConText policy on the column.
Specify the primary key (textkey) of the document (row) to be processed. The parameter pk can be a single column textkey or an encoded specification for a multiple column textkey.
Specify the table used to store the gist output.
Specify the type of Gist/theme summary to produce. The possible values are:
The default is paragraph.
Specify the theme for which a single Gist or theme summary
is generated. The type of Gist/theme summary generated (sentence-level
or paragraph-level) depends on the value specified for glevel.
To generate a Gist for the document, specify a theme of `GENERIC'
for pov. To generate a theme summary for the document, specify the
theme from the document for which the matching paragraphs/sentences are
selected.
If you specify a NULL value for pov, ConText generates
a Gist for the document and a theme summary for each of the document themes
(up to 50).
exec ctx_ling.request_gist('my_pol', '34', 'ctx_gist') begin ctx_ling.request_gist('doc_pol', CTX_QUERY.PKENCODE('Jones','Naval Inst Pr','10-1-1970'), 'CTX_GIST'); end;
In the following example, a single, paragraph-level theme summary is generated for a document with a pk of 1442 stored in the text column for policy my_pol. The theme (pov) for which the theme summary is generated is Oracle Corporation:
exec ctx_ling.request_gist(`my_pol','1442','ctx_gist',pov=>'Oracle Corporation')
In the following example, a sentence-level Gist is generated for document with a pk of 1442 stored in the text column for policy my_pol:
exec ctx_ling.request_gist(`my_pol','1442','ctx_gist','sentence','GENERIC')
You must call the CTX_LING.REQUEST_GIST procedure once for
each document for which you want to generate gists.
By default, ConText linguistics generates up to 50 themes
for a document. If the user settings specify that gists are to be created
for only the top 10 themes of the document, the REQUEST_GIST procedure
creates a total of 11 gists: one gist for the specified number of themes
and one generic gist for the entire document.
The REQUEST_GIST procedure only creates gists if the setting
configuration for the session in which REQUEST_GIST is called supports
gist generation.
The parameter pk can be either a single column textkey
or a multiple column (composite) textkey. When pk is a composite
textkey, you must encode the composite textkey string using the CTX_QUERY.PKENCODE
procedure as in the second example above.
Requests are not automatically entered into the Services
Queue; each request is cached in memory until the application calls the
CTX_LING.SUBMIT procedure.
CTX_LING.SUBMIT explicitly enters all of the cached requests
into the Services Queue as a single batch.
All of the linguistic settings that can be specified for
Gist-generation also apply to sentence-level Gists/theme summaries when
requested. The settings simply act on sentences rather than paragraphs.
For example, the size setting for Gists, which determines
the maximum number of paragraphs in a paragraph-level Gist, determines
the maximum number of sentences in a sentence-level Gist, when a sentence-level
Gist is requested.
The CTX_LING.REQUEST_THEMES procedure generates a list of
up to fifty themes for a document.
By default, this procedure generates single theme information.
To generate hierarchical theme information, you must first call CTX_LING.SET_FULL_THEMES.
CTX_LING.REQUEST_THEMES( policy IN VARCHAR2, pk IN VARCHAR2, table IN VARCHAR2);
Specify the name of the ConText policy for the column.
Specify the primary key (textkey) of the document (row) to be processed. The parameter pk can be a single column textkey or an encoded specification for a multiple column textkey.
Specify the table used to store the theme output.
exec ctx_ling.request_themes('my_pol', 34, 'CTX_THEMES') begin ctx_ling.request_themes('doc_pol', CTX_QUERY.PKENCODE('Jones','Naval Inst Pr','10-1-1970'), 'CTX_THEMES'); end;
You must call CTX_LING.REQUEST_THEMES procedure once for
each document for which you want to generate themes.
The parameter pk can be either a single column textkey
or a multiple column textkey. When pk is a composite key, you must
encode the composite textkey string using the CTX_QUERY.PKENCODE
procedure as in the second example above.
Requests for themes are not automatically entered into the
Services Queue; each request is cached in memory pending submission by
CTX_LING.SUBMIT.
CTX_LING.SUBMIT explicitly enters all of the cached requests
into the Services Queue as a single batch.
The CTX_LING.SET_COMPLETION_CALLBACK procedure specifies
the user-defined PL/SQL processing routine (usually a procedure) to be
called when a ConText server finishes processing a request in the Services
Queue.
CTX_LING.SET_COMPLETION_CALLBACK(callback_name IN VARCHAR2);
Specify the name of the callback procedure. See below for
a description of the arguments to the callback_name procedure.
exec ctx_ling.set_completion_callback('COMP_PROCEDURE')
A completion callback procedure must be defined before SET_COMPLETION_CALLBACK
can be called. The completion callback procedure must accept the following
arguments:
Control is passed to the SET_COMPLETION_CALLBACK procedure
at the completion of a linguistic request. It can log errors or otherwise
notify the application when a request has finished processing. This can
be particularly useful for a large job that is run asynchronously in batch
mode.
To call a procedure specifically for requests that terminate
with errors, use CTX_LING. SET_ERROR_CALLBACK.
The CTX_LING.SET_ERROR_CALLBACK procedure specifies the user-defined
PL/SQL processing routine (usually a procedure) to be called when a ConText
server encounters an error while processing a linguistic request.
CTX_LING.SET_ERROR_CALLBACK(callback_name IN VARCHAR2);
Specify the name of the callback procedure to be used when
an error occurs.
exec ctx_ling.set_error_callback('ERROR_PROCEDURE')
An error callback procedure must be defined before SET_ERROR_CALLBACK
can be called. The error callback procedure must accept the following arguments:
| Argument | Type | Purpose |
|---|---|---|
|
HANDLE |
NUMBER |
Specify the internal identifier for the request, as returned by SUBMIT |
|
ERRCODE |
VARCHAR2 |
Specify the code for the error. |
Control is passed to the SET_ERROR_CALLBACK procedure at
the completion of a linguistic request. The procedure can be used to log
errors or otherwise notify the application when a request has finished
processing. This can be particularly useful for a large job that is run
asynchronously in batch mode.
To call a procedures for both completed task processing and
error processing, use SET_COMPLETION_CALLBACK.
Use this procedure to enable the writing of theme hierarchy
information to the theme table. ConText writes the theme hierarchy information
when you call CTX_LING.REQUEST_THEMES. (By default, ConText writes only
single theme information to the theme table when you call REQUEST_THEMES.)
CTX_LING.SET_FULL_THEMES (theme_mode IN BOOLEAN DEFAULT TRUE);
Specify TRUE for ConText to write theme hierarchy information
to the THEME column of the theme table.
Specify FALSE to disable the writing of theme hierarchy information
to the THEME column of the theme table.
At the start of a session, the theme_mode flag is
FALSE.
Calling SET_FULL_THEMES without an argument is the same as
calling this procedure with theme_mode set to TRUE.
You can check whether the writing of theme hierarchy information
is turned on using GET_FULL_THEMES.
The CTX_LING.SET_LOG_PARSE procedure enables/disables logging
of linguistic parsing information for a session.
CTX_LING.SET_LOG_PARSE(log_mode BOOLEAN DEFAULT TRUE);
Specify whether to write parse information to a log file
during linguistic processing in a session. The default is TRUE.
exec ctx_ling.set_log_parse(TRUE)
At start-up of a ConText server, parse information logging
is disabled.
Once logging is enabled, it stays enabled for the session
until it is explicitly disabled.
When logging is enabled, the text of the document being parsed
and the paragraph offset information used by ConText to separate the document
into its constituent paragraphs is written to the log file specified when
the ConText server is started.
The log provides information about the input text used to
generate linguistic output and can be used for debugging the system. The
parse information is especially useful for debugging linguistic output
for formatted documents from which the text is extracted before it is processed.
However, due to the large amount of information generated
by ConText and written to the log file, parse logging may affect performance
considerably. For this reason, you should only enable parse logging if
you encounter problems with linguistics.
Use the CTX_LING.SET_SETTINGS_LABEL procedure to change the
linguistic settings for a database session.
CTX_LING.SET_SETTINGS_LABEL(settings_label IN VARCHAR2);
Specify the label for the setting configuration used for
the session. You can use one of the following predefined settings or one
that you create with the administration tool:
exec ctx_ling.set_settings_label('SA')
At start-up of a ConText server, the GENERIC default setting
configuration is active.
The setting specified by SET_SETTINGS_LABEL is active for
the entire session or until you call SET_SETTINGS_LABEL with a new setting
configuration. In addition, the specified setting is active only for your
current session; settings specified for your session have no effect on
the server setting.
You can specify any predefined ConText setting configuration
or any custom setting configuration. Define custom setting configurations
with the Administration Tool provided with ConText Workbench.
When your text is all upper-case or all lower-case and you
use the SA setting to convert the text to mixed-case, Oracle Corporation
does not recommend creating theme indexes or issuing theme queries. Creating
theme indexes with the SA linguistic setting does not produce consistent
results.
The CTX_LING.SUBMIT procedure creates a single request (row)
in the Services Queue for all linguistic requests cached in memory for
a single row (identified by PK) and returns a handle for the request.
CTX_LING.SUBMIT( wait IN NUMBER DEFAULT 0, do_commit IN BOOLEAN DEFAULT TRUE, priority IN NUMBER DEFAULT 0) RETURN NUMBER;
Specify maximum time in seconds to block subsequent requests while ConText server processes request. The default is 0.
Specify whether the job request should be committed to the database. The default is TRUE.
Specify the priority for the request. Requests are processed
in order of priority from lowest priority to highest priority. The default
is 0.
Handle that identifies the request.
declare handle number; begin handle := ctx_ling.submit(500); end;
In this example, procedures to create one or more gists and/or
themes have already been executed and the requests cached in memory. The
SUBMIT procedure enters the request(s) into the Services Queue and returns
a handle. It this case, it also prevents the queue from accepting other
submissions from the same requestor for 500 seconds.
SUBMIT does not cache requests for multiple documents nor
for documents in different columns. Only requests for a single document
at a time can be submitted.
If more than one request is queued in memory, SUBMIT processes
all of the requests as a single batch job. If the request is a batch job,
the ConText server processes each request in the batch in order.
All of the individual requests in the batch must be processed
successfully or the ConText server returns an ERROR status for the entire
batch. The error message stack returned by the ConText server identifies
the request that caused the batch to fail.
If SUBMIT is called from a database trigger, the DO_COMMIT
argument must be set to FALSE.
The CTX_SVC package contains PL/SQL procedures used to query
requests in the Services Queue and to perform administrative tasks on the
Queue.
CTX_SVC contains the following stored procedures and functions:
The CTX_SVC.CANCEL procedure removes a request from the Services
Queue, if the request has a status of PENDING.
CTX_SVC.CANCEL(request_handle NUMBER);
Specify the handle, returned by CTX_LING.SUBMIT, of the service
request to remove.
exec ctx_svc.cancel(3321)
To cancel requests that have not been entered in the Services
Queue, use the CTX_LING.CANCEL procedure.
The CTX_SVC.CANCEL_ALL procedure removes all requests with
a status of PENDING from the Services Queue.
CTX_SVC.CANCEL_ALL ;
execute ctx_svc.cancel_all
The CTX_SVC.CANCEL_USER procedure removes all requests with
a status of PENDING for the current user.
CTX_SVC.CANCEL_USER ;
execute ctx_svc.cancel_user
The CTX_SVC.CLEAR_ALL_ERRORS procedure removes all requests
(text indexing, theme indexing, and linguistics) that have a status of
ERROR in the Services Queue.
CTX_SVC.CLEAR_ALL_ERRORS ;
execute ctx_svc.clear_all_errors
The CTX_SVC.CLEAR_ERROR procedure removes a request with
a status of ERROR from the Services Queue.
CTX_SVC.CLEAR_ERROR(request_handle IN NUMBER);
Specify the handle, returned by CTX_LING.SUBMIT, of the errored
service request that is to be removed.
exec ctx_svc.clear_error(3321)
When you call CTX_SVC.CLEAR_ERROR with a 0 for the REQUEST_HANDLE,
ConText removes all requests in the Services Queue that have an ERROR status.
You can use CTX_SVC.REQUEST_STATUS to return the status of
a request in the Services Queue.
The CTX_SVC.CLEAR_INDEX_ERRORS procedure removes all indexing
requests (text and theme) that have a status of ERROR in the Services Queue.
CTX_SVC.CLEAR_INDEX_ERROR ;
execute ctx_svc.clear_index_errors
The CTX_SVC.CLEAR_LING_ERRORS procedure removes all linguistic
requests that have a status of ERROR in the Services Queue.
CTX_SVC.CLEAR_LING_ERROR ;
execute ctx_svc.clear_ling_errors
The CTX_SVC.REQUEST_STATUS function returns the status of
a request in the Services Queue.
CTX_SVC.REQUEST_STATUS( request_handle IN NUMBER, timestamp OUT DATE, errors OUT VARCHAR2) RETURN VARCHAR2;
Specify the handle of the service request, as returned by CTX_LING.SUBMIT.
Returns the time at which request was submitted.
Returns the error message stack for the request; message
stack is returned only if the status of the request is ERROR.
Status of the request, which is one of the following:
The request has not yet been picked up by a ConText server.
The request is being processed by a ConText server.
The request encountered an error (see ERRORS argument).
The request completed successfully.
declare status varchar2(10); declare time date; declare errors varchar2(60) begin status := ctx_svc.request_status(3461,timestamp,errors); dbms_output.put_line(status,timestamp,substr(errors,1,20)); end;
Specifying an invalid request handle in REQUEST_HANDLE causes
CTX_SVC.REQUEST_STATUS to return a status of SUCCESS.
