Oracle Context Option Application Developer's Guide Go to Product Documentation Library
Library
Go to books for this product
Product
Go to Contents for this book
Contents
Go to Index
Index



Go to previous file in sequence Go to next file in sequence

CHAPTER 11. PL/SQL Packages


This chapter includes descriptions of the PL/SQL packages included with ConText Option for developing applications.

The packages described in this chapter are:

Query and Highlighting -- CTX_QUERY

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:

NAME TYPE DESCRIPTION
CLOSE_CON Procedure Closes the in-memory query cursor
CONTAINS Procedure Selects documents in the text column for a policy and writes the results to a specified result table
COUNT_HITS Function Performs a query and returns the number of hits without returning a hitlist.
FETCH_HIT Function Retrieves hits stored in query buffer by OPEN_CON
GETTAB Procedure Gets tables from the result table pool
HIGHLIGHT Procedure Provides filtering and/or highlighting for documents returned by a query
OPEN_CON Function Opens a cursor and executes an in-memory query
PKDECODE Function Decodes a composite textkey string (value)
PKENCODE Function Encodes a composite textkey string (value)
PURGE_SQE Procedure Deletes all SQEs from SQE tables
REFRESH_SQE Procedure Reexecutes an SQE and updates the results stored in the SQE tables
RELTAB Procedure Releases tables allocated by GETTAB
REMOVE_SQE Procedure Removes a specified SQE from the SQL tables
STORE_SQE Procedure Executes a query and stores the results in Stored Query Expression tables
Table 11 - 1. CTX_QUERY Procedures and Functions (Page 2 of 2)



CLOSE_CON

The CTX_QUERY.CLOSE_CON procedure closes a cursor opened by CTX_QUERY.OPEN_CON. It is always called after CTX_QUERY.FETCH_HIT, which retrieves the desired number of hits for the query, has been called.

Syntax

CLOSE_CON(CURID)

Argument Datatype Purpose
CURID NUMBER Specifies the cursor to be closed.

Examples

See CTX_QUERY.FETCH_HIT

CONTAINS

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.

Syntax

CONTAINS(POLICY_NAME[@DBLINK], TEXT_QUERY, RESTAB,
         SHARELEVEL, QUERY_ID, CURSOR_ID, PARALLEL,
         STRUCT_QUERY)

Argument Datatype Purpose
POLICY_NAME [@DBLINK] VARCHAR2 Specifies 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.
TEXT_QUERY VARCHAR2 Specifies the query expression to be used as criteria for selecting rows.
RESTAB VARCHAR2 Specifies the name of the hitlist table that stores intermediate results returned by CONTAINS.
SHARELEVEL NUMBER Specifies whether the results table is shared by multiple CONTAINS:
0 single-use
1 multiple-use
The default is 0.
QUERY_ID NUMBER Specifies the ID used to identify query results returned by a CONTAINS procedure when more than one CONTAINS uses the same result table.
CURSOR_ID NUMBER Not currently used.
PARALLEL NUMBER Specifies the number of ConText servers (with the Query personality) which execute a query and write the results to RESTAB.
STRUCT_QUERY VARCHAR2 Specifies the structured WHERE condition related to TEXT_QUERY.

Examples

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 identifed by QUERY_ID 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.

Notes

PARALLEL does not support the MAX ( : ) and FIRST/NEXT ( # ) query expression operators. If either operator is present 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, HANDLE function, DISPLAY function and the ROWNUM psuedo 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.

For more information about SELECT privilege with GRANT OPTION, see Oracle7 Server SQL Reference.

QUERY_ID is a user-specified value that is stored in the result table and is used to distinguish the results of a CONTAINS from other results stored in the same table. Table 11 - 2 illustrates how QUERY_ID and SHARE_LEVEL are used in a two-step query:

SHARE LEVEL Use QUERY_ID Argument Before the Query CONID Column After the Query
0 Exclusive Ignored System automatically truncates result table Automatically set to NULL CONID values are NULL
1 Shared Specified in the query User must delete from result table where CONID = QUERY_ID User sets to QUERY_ ID CONID = value of QUERY_ ID
Table 11 - 2. CTX_QUERY.CONTAINS Sharelevel Options (Page 1 of 1)



COUNT_HITS

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 more quickly than in exact mode.

Syntax

COUNT_HITS(POLICY_NAME[@DBLINK], TEXT_QUERY, STRUCT_QUERY,
           EXACT)

Argument Datatype Purpose
POLICY_NAME [@DBLINK] VARCHAR2 Specifies 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.
TEXT_QUERY VARCHAR2 Specifies the query expression to be used as criteria for counting returned hits (rows).
STRUCT_QUERY VARCHAR2 Specifies the structured where condition related to TEXT_QUERY.
EXACT BOOLEAN Specifies whether the results returned by COUNT_HITS contain hits for documents that have been deleted or updated:
TRUE Exact count
FALSE Estimated count
The default is FALSE.

Returns

NUMBER (Number of hits)

Examples

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;

FETCH_HIT

The CTX_QUERY.FETCH_HIT function returns a hit stored in the query buffer by CTX_QUERY.OPEN_CON. You must call this function once for each hit in the buffer until the desired number of hits is returned or the buffer is empty.

Syntax

FETCH_HIT(CURID, PK, SCORE, COL1, COL2, COL3, COL4, COL5)

Argument Datatype Purpose
CURID NUMBER Specifies the cursor opened by CTX_QUERY.OPEN_CON.
PK VARCHAR2 (OUT) Returns the primary key of the document.
SCORE NUMBER (OUT) Returns the score of the document.
COL1-5 VARCHAR2 (OUT) Returns additional columns for the document.

Returns

NUMBER (indicates whether hit was retrieved: 0 if no hits fetched, 1 if hit was fetched)

Example

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;

Notes

If the primary key PK is a composite textkey, use CTX_QUERY.PKDECODE to access the individual columns of the textkey.

GETTAB

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.

Syntax

GETTAB(TYPE, TAB, TK_COUNT)

Argument Datatype Purpose
TYPE VARCHAR2 Specifies the type of table to be allocated for text processing:
DOCTAB
RDOCTAB
HIGHTAB
HITTAB
See Table 11 - 3 for a description of the table types.
TAB VARCHAR2 (OUT) Returns the name of the allocated table.
TK_COUNT NUMBER Specifies the number of textkeys in the allocated result table. TK_COUNT applies only to HITTAB tables. TK_COUNT defaults to 1.

Examples

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.

Notes

The TABLE_TYPE argument must be fully qualified with the PL/SQL package name (CTX_QUERY) as shown in the examples.

The TK_COUNT parameter applies only to HITTAB tables; it has no effect on other table types.

Table Types

Table Type Description Stores Results for:
DOCTAB Result table which is used to store the marked-up text (MUTAB) or plain ASCII text (PLAINTAB) returned by CTX_QUERY.HIGHLIGHT MUTAB or PLAINTAB
RDOCTAB Result table which is used to store the non-filtered documents (NOFILTAB) or ICF output (ICFTAB) returned by CTX_QUERY.HIGHLIGHT NOFILTAB or ICFTAB
HIGHTAB Result table which is used to store the textkey, offsets, and lengths of query terms to be highlighted in documents (returned by CTX_QUERY.HIGHLIGHT) HIGHTAB
HITTAB Result table which is used to store the hitlist data returned by CTX_QUERY.CONTAINS RESTAB
Table 11 - 3. CTX_QUERY.HIGHLIGHT Table Types (Page 1 of 1)



HIGHLIGHT

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.

Syntax

HIGHLIGHT(CSPEC, TEXTKEY, QUERY, ID,
          NOFILTTAB, PLAINTAB, HIGHTAB, ICFTAB, MUTAB,
          STARTTAG, ENDTAG)

Argument Datatype Purpose
CSPEC VARCHAR2 Specifies the policy name for the column in which the document is stored.
TEXTKEY VARCHAR2 Specifies 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.
QUERY VARCHAR2 Specifies the original query expression used to retrieve the document.
ID NUMBER Specifies the identifier to be used in the results tables to identify the rows that were returned by this procedure call.
NOFILTAB VARCHAR2 Specifies name of the RDOCTAB table where unfiltered document is stored.
PLAINTAB VARCHAR2 Specifies the name of the DOCTAB table where plain text version of document is stored.
HIGHTAB VARCHAR2 Specifies the name of the HIGHTAB table where highlight information for the document is stored.
ICFTAB VARCHAR2 Used internally by the Windows 32-bit viewer to specify where the ICF output required for WYSIWYG viewing of documents is stored.
MUTAB VARCHAR2 Specifies table where marked up, ASCII version of document is stored.
STARTTAG VARCHAR2 Specifies the markup to be inserted by HIGHLIGHT for indicating the start of a higlighted 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 = ...>).
ENDTAG VARCHAR2 Specifies the markup to be inserted by HIGHLIGHT for indicating the end of a higlighted 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>).

Examples

begin
  ctx_query.highlight(cspec => '2354',
                      textkey => '23',
                      query => 'dog|cat',
                      nofiltab => 'FORMATTED_TEXT',
                      hightab => 'HIGHLIGHTED_TEXT',
                      starttag => '<**<',
                      endtag => '>**>');
end;

Notes

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.

For more information about internal and external filters, see "Oracle ConText Option Administrator's Guide".

OPEN_CON

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.

Syntax

OPEN_CON(POLICY_NAME[@DBLINK], TEXT_QUERY, SCORE_SORTED,
         OTHER_COLS)

Argument Datatype Purpose
POLICY_NAME [@DBLINK] VARCHAR2 Specifies 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.
TEXT_QUERY VARCHAR2 Specifies the query expression to be used as criteria for selecting rows.
SCORE_SORTED BOOLEAN Specifies whether the results are sorted by score.
The default is FALSE.
OTHER_COLS VARCHAR2 Specifies the table columns (up to 5) to be displayed, in addition to document ID and score, in the hitlist.

Returns

NUMBER (Cursor ID)

Examples

See CTX_QUERY.FETCH_HIT

PKDECODE

The CTX_QUERY.PKDECODE function extracts and returns a composite textkey element from a composite textkey string.

Syntax

PKDECODE(ENCODED_TK, WHICH)

Argument Datatype Purpose
ENCODED_TK VARCHAR2 Specifies the encoded composite textkey string.
WHICH NUMBER Specifies 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.

Returns

VARCHAR2 (string that represents the decoded value of the composite textkey)

Examples

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 return the same value, which is the concatenated value 'p1,p2,p3'.

Notes

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 in CTX_QUERY.FETCH_HIT.

PKENCODE

The CTX_QUERY.PKENCODE function converts a composite textkey list into a single string and returns the string.

Syntax

PKENCODE(PK1, PK2, PK3, PK4, PK5, PK6, PK7, PK8, PK9, PK10,
         PK11, PK12, PK13, PK14, PK15, PK16)

Argument Datatype Purpose
PK1 - PK16 VARCHAR2 Each argument specifies a column element in the composite textkey list. You can specify at most 16 columns.

Returns

VARCHAR2 (string that represents the encoded value of the composite textkey)

Examples

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.

Notes

The string created by PKENCODE can be used as the primary key parameter PK in other ConText procedures, such as CTX_LING.REQUEST GIST.

PURGE_SQE

The CTX_QUERY.PURGE_SQE procedure removes all session SQEs for the current session. Session SQEs in other sessions are not affected by PURGE_SQE.

Syntax

PURGE_SQE(POLICY_NAME)

Argument Datatype Purpose
POLICY_NAME VARCHAR2 Specifies the name of the policy for which the current session SQEs are purged.

Examples

exec ctx_query.purge_sqe(my_pol)

REFRESH_SQE

The CTX_QUERY.REFRESH_SQE procedure reexecutes an SQE and stores the results in the SQR table, overwriting the existing results in the SQR tables.

For more information about the structure of the SQR table, see Oracle ConText Option Administrator's Guide

Syntax

REFRESH_SQE(POLICY_NAME,QUERY_NAME)

Argument Datatype Purpose
POLICY_NAME VARCHAR2 Specifies the policy for the SQE.
QUERY_NAME VARCHAR2 Specifies the name of the SQE to be refreshed.

Examples

exec ctx_query.refresh_sqe('my_pol', 'DOG')

RELTAB

The CTX_QUERY.RELTAB procedure releases a table previously allocated by CTX_QUERY.GETTAB.

Syntax

RELTAB(TABLE_NAME)

Argument Datatype Purpose
TAB VARCHAR2 Specifies the type of table to be released:
DOCTAB
RDOCTAB
HIGHTAB
HITTAB

Examples

exec ctx_query.reltab(CTX_QUERY.HITTAB)
exec ctx_query.reltab(CTX_QUERY.HIGHTAB)

Notes

The TAB argument must be fully qualified with the PL/SQL package name (CTX_QUERY) as shown in the examples.

REMOVE_SQE

The CTX_QUERY.REMOVE_SQE procedure removes a specified SQE from the system SQE table and the results of the SQE from the SQR table for the policy.

For more information about the structure of the SQE and SQR tables, see Oracle ConText Option Administrator's Guide

Syntax

REMOVE_SQE(POLICY_NAME, QUERY_NAME)

Argument Datatype Purpose
POLICY_NAME VARCHAR2 Specifies the policy for which the SQE is removed.
QUERY_NAME VARCHAR2 Specifies the name of the SQE to be removed.

Examples

exec ctx_query.remove_sqe('my_pol', 'DOG')

STORE_SQE

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.

For more information about the structure of the SQE and SQR tables, see Oracle ConText Option Administrator's Guide

Syntax

STORE_SQE(POLICY_NAME, QUERY_NAME, TEXT_QUERY, SCOPE)

Argument Datatype Purpose
POLICY_NAME VARCHAR2 Specifies the policy for which the SQE is created.
QUERY_NAME VARCHAR2 Specifies the name of the SQE to be created.
TEXT_QUERY VARCHAR2 Specifies the query expression for the SQE
SCOPE VARCHAR2 Specifies whether the SQE is a session or system SQE.

Examples

exec ctx_query.store_sqe('my_pol', 'DOG', '$(dogs|puppy)',\
'session')

Notes

SQEs support all of the ConText Option 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.

Linguistic Services -- CTX_LING

CTX_LING is the package of PL/SQL procedures used to request Linguistic Services 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:

NAME TYPE DESCRIPTION
CANCEL Procedure Cancel all cached theme and Gist requests
GET_COMPLETION_CALLBACK Function Return the completion callback procedure specified for the current session
GET_ERROR_CALLBACK Function Return the error callback procedure specified for the current session
GET_LOG_PARSE Function Return a value indicating whether parse logging is enabled for current session
GET_SETTINGS_LABEL Function Return the currently active setting configuration
REQUEST_GIST Procedure Request Gists for a document
REQUEST_THEMES Procedure Request themes for a document
SET_COMPLETION_CALLBACK Procedure Specify a procedure to be called when a request completes
SET_ERROR_CALLBACK Procedure Specify a procedure to be called if an error is encountered by a request
SET_LOG_PARSE Procedure Enable/disable logging of parse information for the current session
SET_SETTINGS_LABEL Procedure Specify a setting configuration for the current session
SUBMIT Procedure Submit all cached theme and Gist requests to Services Queue
Table 11 - 4. CTX_LING Procedures and Functions (Page 2 of 2)



CANCEL

The CTX_LING.CANCEL procedure cancels all pending Linguistic Services requests cached in memory.

Syntax

CANCEL

Examples

exec ctx_ling.cancel

Notes

Requests for themes and Gists are cached in memory until 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, the CTX_SVC.CANCEL procedure must be used.

GET_COMPLETION_CALLBACK

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).

Syntax

GET_COMPLETION_CALLBACK

Returns

VARCHAR2 (Completion callback procedure)

Examples

declare callback varchar2(60);
begin
  callback := get_completion_callback;
  dbms_output.put_line('Completion callback:');
  dbms_output.put_line(callback);
end;

Notes

To call procedures for both completed task processing as well as error processing, you must also identify the error completion processing routine with SET_COMPLETION_ERROR.

If both completion and error callbacks are set, 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.

GET_ERROR_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).

Syntax

GET_ERROR_CALLBACK

Returns

VARCHAR2 (Error callback procedure)

Examples

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;

Notes

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.

GET_LOG_PARSE

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.).

Syntax

GET_LOG_PARSE

Returns

BOOLEAN (TRUE if parse logging is enabled, FALSE if parse logging is not enabled).

Examples

declare parse_logging boolean;
begin
   parse_logging := get_log_parse;
end;

GET_SETTINGS_LABEL

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.).

Syntax

GET_SETTINGS_LABEL

Returns

VARCHAR2 (current settings configuration label)

Examples

declare settings varchar2(60);
begin
   settings := get_settings_label;
   dbms_output.put_line('Current setting configuration:');
   dbms_output.put_line(settings);
end;

Notes

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.

REQUEST_GIST

The CTX_LING.REQUEST_GIST procedure generates one POV 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.

Syntax

REQUEST_GIST(POLICY, PK, TABLE)

Argument Datatype Purpose
POLICY VARCHAR2 Specifies the name of the ConText Option policy on the column.
PK VARCHAR2 Specifies the primary key (textkey) of the document (row) to be processed. PK can be a single column textkey or an encoded specification for a multiple column textkey.
GIST_TABLE VARCHAR2 Specifies the table used to store the Gist output.

Examples

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;

Notes

The CTX_LING.REQUEST_GIST procedure is called once for each document for which you want to generate Gists.

By default, Linguistic Services 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.

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.

REQUEST_THEMES

The CTX_LING.REQUEST_THEMES procedure generates a list of up to sixteen themes for a document.

Syntax

REQUEST_THEMES(POLICY, PK, TABLE)

Argument Datatype Purpose
POLICY VARCHAR2 Specifies the name of the ConText Option policy for the column.
PK VARCHAR2 Specifies the primary key (textkey) of the document (row) to be processed. PK can be a single column textkey or an encoded specification for a multiple column textkey.
THEME_TABLE VARCHAR2 Specifies the table used to store the theme output.

Examples

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;

Notes

The CTX_LING.REQUEST_THEMES procedure is called once for each document for which you want to generate themes.

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.

SET_COMPLETION_CALLBACK

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.

Syntax

SET_COMPLETION_CALLBACK(CALLBACK_NAME)

Argument Datatype Purpose
CALLBACK_ NAME VARCHAR2 Specifies the name of the callback procedure.

Examples

exec ctx_ling.set_completion_callback('COMP_PROCEDURE')

Notes

A completion callback procedure must be defined before SET_COMPLETION_CALLBACK can be called. The completion callback procedure must accept the following arguments:

Argument Type Purpose
HANDLE NUMBER Specifies the internal identifier for the request, as returned by SUBMIT.
STATUS VARCHAR2 Specifies the status of the request: SUCCESS OR ERROR.
ERRCODE VARCHAR2 Specifies the code for the error (NULL if request processed successfully)
Control is passed to the SET_COMPLETION_CALLBACK procedure at the completion of a Linguistic Services 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 aSET_ERROR_CALLBACK.

SET_ERROR_CALLBACK

The CTX_LING.SET_ERROR_CALLBACK procedure specifies the user-defined PL/SQL processing routine (usually a procedures) to be called when a ConText server encounters an error while processing a Linguistic Services request.

Syntax

SET_ERROR_CALLBACK(CALLBACK_NAME)

Argument Datatype Purpose
CALLBACK_ NAME VARCHAR2 Specifies the name of the callback procedure to be used when an error occurs.

Examples

exec ctx_ling.set_error_callback('ERROR_PROCEDURE')

Notes

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 Specifies the internal identifier for the request, as returned by SUBMIT
ERRCODE VARCHAR2 Specifies the code for the error
Control is passed to the SET_ERROR_CALLBACK procedure at the completion of a Linguistic Services 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, SET_COMPLETION_CALLBACK must also be called.

SET_LOG_PARSE

The CTX_LING.SET_LOG_PARSE procedure enables/disables logging of linguistic parsing information for a session.

Syntax

SET_LOG_PARSE(LOG_MODE)

Argument Datatype Purpose
LOG_MODE BOOLEAN Specifies whether to enable writing parse information to a log file during linguistic processing in a session:
TRUE
FALSE
The default is TRUE.

Examples

exec ctx_ling.set_log_parse(TRUE)

Notes

At startup 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 the Linguistic Services to separate the document into its constituent paragraphs is written to the log file specified when the ConText server when 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 the Linguistic Services 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 the Linguistic Services.

SET_SETTINGS_LABEL

The CTX_LING.SET_SETTINGS_LABEL procedure specifies the Linguistic Services user settings for a database session.

Syntax

SET_SETTINGS_LABEL(SETTINGS_LABEL)

Argument Datatype Purpose
SETTINGS_ LABEL VARCHAR2 Specifies the label for the setting configuration used for the session.

Examples

exec ctx_ling.set_settings_label('P')

Notes

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.

Any predefined ConText Option setting configuration or any user-defined custom setting configuration may be specified. Custom setting configurations are defined with the Administration Tool.

At startup of a ConText server, the GENERIC default setting configuration is active.

For a list of the predefined setting configurations, see "Predefined Setting Configurations" in "Linguistic Specifications (Chapter 13)."

SUBMIT

The CTX_LING.SUBMIT procedure creates a single request (row) in the Services Queue for all the Linguistic Services requests cached in memory for a single row (identified by PK) and returns a handle for the request.

Syntax

SUBMIT(WAIT, DO_COMMIT, PRIORITY)

Argument Datatype Purpose
WAIT NUMBER Specifies maximum time (in seconds) to block subsequent requests while ConText server processes request.
The default is 0.
DO_COMMIT BOOLEAN Specifies whether the job request should be committed to the database.
The default is TRUE.
PRIORITY NUMBER Specifies the priority for the request (requests are processed in order of priority from lowest priority to highest priority).
The default is 0.

Returns

NUMBER (handle that identifies the request)

Examples

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.

Notes

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 should be set to FALSE.

Services Queue Administration -- CTX_SVC

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:

NAME TYPE DESCRIPTION
CANCEL Procedure Removes a pending request from the Services Queue
CANCEL_ALL Procedure Removes all pending requests from the Services Queue
CANCEL_USER Procedure Removes a pending request from the Services Queue for the current user
CLEAR_ALL_ERRORS Procedure Removes all requests with an error status from the Services Queue
CLEAR_ERROR Procedure Removes a request that produced an error from the Services Queue
CLEAR_INDEX_ERRORS Procedure Removes errored indexing requests from the Services Queue
CLEAR_LING_ERRORS Procedure Removes errored requests for Linguistic Services from the Services Queue
REQUEST_STATUS Function Returns the status of a request in the Services Queue
Table 11 - 5. CTX_SVC Procedures and Functions (Page 1 of 1)



CANCEL

The CTX_SVC.CANCEL procedure removes a request from the Services Queue, if the request has a status of PENDING.

Syntax

CANCEL(REQUEST_HANDLE)

Argument Datatype Purpose
REQUEST_ HANDLE NUMBER Specifies the handle, returned by CTX_LING.SUBMIT, of the service request to remove.

Examples

exec ctx_svc.cancel(3321)

Notes

To cancel requests that have not been entered in the Services Queue, use the CTX_LING.CANCEL procedure.

CANCEL_ALL

The CTX_SVC.CANCEL_ALL procedure removes all requests with a status of PENDING from the Services Queue.

Syntax

CANCEL_ALL

Examples

execute ctx_svc.cancel_all

CANCEL_USER

The CTX_SVC.CANCEL_USER procedure removes all requests with a status of PENDING for the current user.

Syntax

CANCEL_USER

Examples

execute ctx_svc.cancel_user

CLEAR_ALL_ERRORS

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.

Syntax

CLEAR_ALL_ERRORS

Examples

execute ctx_svc.clear_all_errors

CLEAR_ERROR

The CTX_SVC.CLEAR_ERROR procedure removes a request with a status of ERROR from the Services Queue.

Syntax

CLEAR_ERROR(REQUEST_HANDLE)

Argument Datatype Purpose
REQUEST_ HANDLE NUMBER Specifies the handle, returned by CTX_LING.SUBMIT, of the errored service request that is to be removed.

Examples

exec ctx_svc.clear_error(3321)

Notes

If CTX_SVC.CLEAR_ERROR is called with a 0 for the REQUEST_HANDLE, all requests in the Services Queue that have ERROR status are removed.

CTX_SVC.REQUEST_STATUS can be used to return the status of a request in the Services Queue.

CLEAR_INDEX_ERRORS

The CTX_SVC.CLEAR_INDEX_ERRORS procedure removes all indexing requests (text and theme) that have a status of ERROR in the Services Queue.

Syntax

CLEAR_INDEX_ERROR

Examples

execute ctx_svc.clear_index_errors

CLEAR_LING_ERRORS

The CTX_SVC.CLEAR_LING_ERRORS procedure removes all Linguistic Services requests that have a status of ERROR in the Services Queue.

Syntax

CLEAR_LING_ERROR

Examples

execute ctx_svc.clear_ling_errors

REQUEST_STATUS

The CTX_SVC.REQUEST_STATUS function returns the status of a request in the Services Queue.

Syntax

REQUEST_STATUS(REQUEST_HANDLE, TIMESTAMP, ERRORS)

Argument Datatype Purpose
REQUEST_ HANDLE NUMBER Specifies the handle of the service request, as returned by CTX_LING.SUBMIT.
TIMESTAMP DATE (OUT) Provides the time at which request was submitted.
ERRORS VARCHAR2 (OUT) Identifies the error message stack for the request; message stack is returned only if the status of the request is ERROR.

Returns

VARCHAR2 (status of the request):

PENDING The request has not yet been picked up by a ConText server
RUNNING The request is being processed by a ConText server
ERROR The request encountered an error (see ERRORS argument)
SUCCESS The request completed successfully

Examples

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;

Notes

Specifying an invalid request handle in REQUEST_HANDLE causes CTX_SVC.REQUEST_STATUS to return a status of SUCCESS.




Go to previous file in sequence Go to next file in sequence
Prev Next
Oracle
Copyright © 1996 Oracle Corporation.
All Rights Reserved.
Go to Product Documentation Library
Library
Go to books for this product
Product
Go to Contents for this book
Contents
Go to Index
Index