Release 2.3
A58164-01
 Library |
 Product |
 Contents |
 Index |
| Oracle8 ConText Cartridge Application Developer's Guide Release 2.3 A58164-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 Server 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. It 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 Server 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.
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;
NUMBER that represents the number of hits.
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.
declarecount number;curid number;
begincurid := ctx_query.open_con('mypol', 'me', score_sorted=>true);count := ctx_query.count_last ;
end
declarecount number;
beginctx_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". |
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.
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 highlights are 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, ASCII 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.
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 ASCII 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.
Cursor ID.
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.
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;
Error callback procedure.
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 16); 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 16).
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 16 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 sixteen themes for a document.
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 REQUEST_THEMES. (By default, ConText writes only theme phrase 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 settingspecified 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 Corpration 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.
