Release 2.0
A54630-01
 Library |
 Product |
 Contents |
 Index |
| Oracle8(TM) ConText(R) Cartridge Application Developer's Guide Release 2.0 A54630-01 |
|
This chapter describes the ConText Option PL/SQL packages you use to develop applications. The packages described in this chapter are:
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); curid
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); policy_name
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 4, "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. sharelevel defaults to 0 (single-use).
When you specify 0, the system automatically truncates the result table before the query. 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.
parallel 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; policy_name[@dblink]
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;
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); curid
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); type
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, "Viewing Highlighted Text". |
Returns the name of the allocated table.
Specify the number of textkeys in the allocated result table. This parameter applies only to HITTAB tables. tk_count defaults to 1.
exec ctx_query.gettab(CTX_QUERY.HIGHTAB, :hightab_var)
exec ctx_query.gettab(CTX_QUERY.HITTAB, :hittab_var, 3)
The second example returns a HITTAB result table that has a composite textkey made up of three columns. Its schema 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, id IN NUMBER, nofilttab IN VARCHAR2, plaintab IN VARCHAR2, hightab IN VARCHAR2, icftab IN VARCHAR2, mutab IN VARCHAR2, starttag IN VARCHAR2, endtag IN VARCHAR2); cspec
Specify the policy name for the column in which the document is stored.
Specify the unique identifier (usually the primary key) for the document.
textkey 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.
Specify the identifier to be used in the results tables to identify the rows that were returned by this procedure call.
Specify name of the RDOCTAB table where unfiltered document is stored.
Specify the name of the DOCTAB table where plain text version of document is stored.
Specify the name of the HIGHTAB table where highlight information for the document is stored.
Used internally by the Windows 32-bit viewer to specify where the ICF output required for WYSIWYG viewing of documents is stored.
Specify table where marked up, ASCII version of document i
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 id=null is specified in HIGHLIGHT, 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) RETURN NUMBER; policy_name[@dblink]
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.
Cursor ID.
See 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; encoded_tk
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; pk1-pk16
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); policy_name
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); policy_name
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(table_name IN VARCHAR2); tab
Specify the type of table to be released, which must be one of the following:
exec ctx_query.reltab(CTX_QUERY.HITTAB)
exec ctx_query.reltab(CTX_QUERY.HIGHTAB)
The TAB argument must be fully qualified with the PL/SQL package name (CTX_QUERY) as shown in the examples.
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); policy_name
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); policy_name
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.
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.
The CTX_LING.REQUEST_GIST procedure generates one point-of-view gist for each theme in a document, up to the number of themes specified in the linguistic settings; a generic gist is also generated for the entire document.
CTX_LING.REQUEST_GIST( policy IN VARCHAR2, pk IN VARCHAR2, table IN VARCHAR2); policy
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.
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;
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.
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); policy
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); callback_name
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); callback_name
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.
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); log_mode
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 specify the linguistic settings for a database session.
CTX_LING.SET_SETTINGS_LABEL(settings_label IN VARCHAR2); settings_label
Specify the label for the setting configuration used for the session. You can use one of the following predefined settings:
exec ctx_ling.set_settings_label('P')
At start-up of a ConText server, the GENERIC default setting configuration is active.
The settings specified by SET_SETTINGS_LABEL are active for the entire session or until SET_SETTINGS_LABEL is called with a new setting configuration.
You can specify any predefined ConText Option setting configuration or any custom setting configuration. Custom setting configurations are defined with the Administration Tool.
The style parser and the theme parser have been combined into a single parser that delivers the high quality of the style parser with enhanced performance that equals the performance of the theme parser. As a result, the 'S' setting configurations do not provide any advantage over the other setting configurations and should not be used. If the 'S' setting configurations are used, ConText Option successfully processes documents through the linguistics, but returns an error message for each document. These error messages can be ignored.
Theme indexing and theme querying only work with the GENERIC linguistic setting, which is the default.
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; wait
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); request_handle
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); request_handle
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; request_handle
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.
