Oracle Context Option Administrator's Guide

Library

Product

Contents

Index

CHAPTER 10. PL/SQL Packages

ConText Option Administration - CTX_ADM
Services Queue Administration - CTX_SVC
Text Setup and Management - CTX_DDL
ConText Index Update and Management - CTX_DML
Thesaurus Management - CTX_THES
Product Information - CTX_INFO

This chapter provides reference information for using the PL/SQL packages provided with ConText Option to administer ConText servers and queues, and manage text.

Administration packages:

ConText Option Administration - CTX_ADM

Services Queue Administration - CTX_SVC

Text management packages:

Text Setup and Management - CTX_DDL

ConText Index Update and Management - CTX_DML

Thesaurus Management - CTX_THES

Miscellaneous packages:

Product Information - CTX_INFO

ConText Option Administration - CTX_ADM

The CTX_ADM PL/SQL package is used to manage ConText servers and queues. CTX_ADM contains the following stored procedures and functions:

NAME TYPE DESCRIPTION
CHANGE_MASK Procedure Modifies the personality mask for a ConText server
GET_QUEUE_STATUS Function Returns the status of the specified queue
RECOVER Procedure Cleans up database objects for deleted text tables
SET_QUERY_BUFFER_SIZE Procedure Increases the size of the pipe used for queries
SHUTDOWN Procedure Shuts down a single ConText server or all currently running ConText servers
UPDATE_QUEUE_STATUS Procedure Updates the status of the specified queue

Table 10 - 1. CTX_ADM Procedures and Functions (Page 1 of 1)

CHANGE_MASK

The CTX_ADM.CHANGE_MASK procedure changes the personality mask of the specified ConText server.

Syntax

CHANGE_MASK(NAME, PERSONALITY_MASK)

Argument Datatype Purpose
NAME VARCHAR2 Specifies the name (internal ID) of the server for which you are changing the personality mask.
PERSONALITY_ MASK VARCHAR2 Specifies the new personality mask that you want to assign to the server. Can be any combination of:
R, Q, D, M, or L
The default is QDM.

Examples

execute ctx_adm.change_mask('DRSRV_8025', 'D')

GET_QUEUE_STATUS

The CTX_ADM.GET_QUEUE_STATUS function returns the status (ENABLED, DISABLED) of the specified queue (DDL, DML, or Services).

A status of DISABLED indicates the queue or pipe is inactive and requests in the queue will not be processed by any of the available ConText servers. To enable the queue, you must call UPDATE_QUEUE_STATUS.

Syntax

GET_QUEUE_STATUS(QNAME)

Argument Datatype Purpose
QNAME VARCHAR2 Specifies the queue or pipe for which you want to return the status:
TEXT_QUEUE (DDL and Query pipes)
DML_QUEUE
SERVICES_QUEUE

Returns

Queue status (VARCHAR2):

ENABLED or DISABLED

Examples

declare status varchar2(8);
begin
  status := ctx_adm.get_queue_status('DML_QUEUE');
end;

Notes

When a queue or pipe has a status of DISABLED, the queue continues to accept requests. The ConText Option server administrator should regularly monitor the status of the queues and pipes to prevent accumulation of requests in disabled queues.

RECOVER

The CTX_ADM.RECOVER procedure deletes all database objects for text tables that have been deleted without first dropping the index or policies for the tables.

Note: ConText Servers automatically perform recovery approximately every fifteen minutes. CTX_ADM.RECOVER provides a method for users to manually perform recovery on command.

Syntax

RECOVER

Examples

execute ctx_adm.recover

SET_QUERY_BUFFER_SIZE

The CTX_ADM.SET_QUERY_BUFFER_SIZE procedure sets the size of the database pipe used for queries. The default size of the buffer is 8192 bytes.

Syntax

SET_QUERY_BUFFER_SIZE(BUFFER_SIZE)

Argument Datatype Purpose
BUFFER_SIZE NUMBER Specifies the size, in bytes, of the query buffer.

Examples

execute ctx_adm.set_query_buffer_size(100000);

Notes

CTX_ADM.SET_QUERY_BUFFER_SIZE can only be used to increase the size of the buffer from the default size (8192 bytes).

SHUTDOWN

The CTX_ADM.SHUTDOWN procedure shuts down the specified ConText server.

Syntax

SHUTDOWN(NAME, SDMODE)

Argument Datatype Purpose
NAME VARCHAR2 Specifies the ID of the server to shutdown.
SDMODE NUMBER Specifies the shutdown mode for the server:
0 Normal
1 Immediate
2 Abort
The default is 0.

Examples

execute ctx_adm.shutdown('DRSRV_3321', 1)

Notes

If you do not specify a ConText server to shut down, the SHUTDOWN procedure shuts down all currently running ConText servers.

UPDATE_QUEUE_STATUS

The CTX_ADM.UPDATE_QUEUE_STATUS procedure is used to change the status of the specified queue (Text, DML, or Services).

For example, the GET_QUEUE_STATUS returns a status of DISABLED for one of the queues. Once the error that caused the queue to become disabled is cleared, UPDATE_QUEUE_STATUS can be called with an action of ENABLE_QUEUE to reactivate the queue.

UPDATE_QUEUE_STATUS can also be used to control request processing in the system. When you disable a queue, you prevent any currently running ConText servers from picking up queued requests until you enable the queue.

Syntax

UPDATE_QUEUE_STATUS(QNAME, QSTATUS)

Argument Datatype Purpose
QNAME VARCHAR2 Specifies the queue or pipe for which you want to return the status:
TEXT_QUEUE (DDL and Query pipes)
DML_QUEUE
SERVICES_QUEUE
QSTATUS VARCHAR2 Specifies the action to perform on the queue:
DISABLE_QUEUE
ENABLE_QUEUE

Examples

execute ctx_adm.update_queue_status('ctx_adm.dml_queue', 'ctx_adm.enable_queue')

Notes

A queue with a status of DISABLED will remain inactive until it is enabled using UPDATE_QUEUE_STATUS; however, the queue will continue to accept requests. The ConText Option server administrator should regularly monitor the status of the queues and pipes to prevent accumulation of requests in disabled queues.

Both QUEUE_NAME and ACTION must be fully qualified with the PL/SQL package name (CTX_ADM) as shown in the examples.

Services Queue Administration - CTX_SVC

The CTX_SVC PL/SQL package is used to query requests in the Services Queue and to manage 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 with an error status 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 10 - 2. CTX_SVC Procedures and Functions (Page 1 of 1)

CANCEL

The CTX_SVC.CANCEL procedure removes a request with a status of PENDING from the Services Queue.

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

execute ctx_svc.cancel(214)

Notes

Requests with a status other than pending in the Services Queue cannot be removed using CTX_SVC.CANCEL. To cancel requests that ConText Option has not yet entered into the Services Queue, use CTX_LING.CANCEL.

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 cancel

CLEAR_ALL_ERRORS

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

Syntax

CLEAR_ALL_ERROR

Examples

execute ctx_svc.clear_all_errors

CLEAR_ERROR

If an ERROR status is returned by REQUEST_STATUS for a request in the Services Queue, the CTX_SVC.CLEAR_ERROR procedure can be used to remove the request 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 to remove.

Examples

execute clear_error(214)

Notes

If you call CLEAR_ERROR with a 0 (zero) value for REQUEST_HANDLE, all requests with status ERROR in the Services Queue are removed.

CLEAR_INDEX_ERRORS

The CTX_SVC.CLEAR_INDEX_ERRORS removes all indexing requests 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 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) Provides the error message stack for the request; message stack is returned only if the status of the request is ERROR (see below).

Returns

Status of the request (VARCHAR2):

PENDING   Request has not yet been picked up

RUNNING   Request is being processed by a ConText server

ERROR     Request encountered an error (see ERRORS argument)

SUCCESS   Request completed successfully

Examples

declare status varchar2(10);
begin
   status := ctx_svc.request_status(42);
end;

Notes

If you specify an invalid request handle in the arguments, the value returned by REQUEST_STATUS is SUCCESS.

Text Setup and Management - CTX_DDL

The CTX_DDL PL/SQL package is used to create preferences and policies for ConText Option and to perform DDL actions such as index creation and optimization. CTX_DDL contains the following stored procedures and functions:

NAME TYPE DESCRIPTION
CLEAR_ATTRIBUTE Procedure Clears the buffer for any attributes that have been set
CREATE_INDEX Procedure Creates an index for the text column using the specified policy
CREATE_POLICY Procedure Creates a policy in the ConText data dictionary
CREATE_PREFERENCE Procedure Creates a preference in the ConText data dictionary
CREATE_SOURCE Procedure Creates a text loading source in the ConText data dictionary
CREATE_TEMPLATE_POLICY Procedure Creates a policy that has no text column defined
DROP_INDEX Procedure Deletes an index
DROP_POLICY Procedure Deletes a policy from the ConText data dictionary
DROP_PREFERENCE Procedure Deletes a preference from the ConText data dictionary
DROP_SOURCE Procedure Deletes a text loading source from the ConText data dictionary
OPTIMIZE_INDEX Procedure Combines index fragments into complete strings and updates index strings for deleted documents
RESUME_FAILED_INDEX Procedure Resumes creation/optimization of a failed ConText index
SET_ATTRIBUTE Procedure Specifies the Tile attribute and corresponding value for a preference
UPDATE_POLICY Procedure Changes the description and/or the preferences in a policy
UPDATE_SOURCE Procedure Changes the description and/or the preferences in a source

Table 10 - 3. CTX_DDL Procedures and Functions (Page 2 of 2)

CLEAR_ATTRIBUTES

The CTX_DDL.CLEAR_ATTRIBUTES procedure clears the buffer of all attributes that have been set using CTX_DDL.SET_ATTRIBUTE.

Syntax

CLEAR_ATTRIBUTES

Examples

execute ctx_ddl.clear_attributes

CREATE_INDEX

The CTX_DDL.CREATE_INDEX procedure creates an index for the column defined in the specified policy.

Syntax

CREATE_INDEX(POLICY_NAME, PARALLEL)

Argument Datatype Purpose
POLICY_NAME VARCHAR2 Specifies the name of the policy for which the index is created.
PARALLEL NUMBER Specifies the number of ConText servers to be used in parallel to create the index for a column.
The default is 1.

Examples

execute ctx_ddl.create_index('MY_POLICY', 2)

CREATE_POLICY

The CTX_DDL.CREATE_POLICY procedure creates a policy for a column.

Syntax

CREATE_POLICY(POLICY_NAME, COLSPEC, SOURCE_POLICY,
              DESCRIPTION, TEXTKEY, LINENO,
              DSTORE_PREF, COMPRESSOR_PREF
              FILTER_PREF, LEXER_PREF, WORDLIST_PREF,
              STOPLIST_PREF, ENGINE_PREF)

Argument Datatype Purpose
POLICY_NAME VARCHAR2 Specifies the name of the policy to be created.
COLSPEC VARCHAR2 Specifies the column (and table) to which the policy is assigned.
SOURCE_ POLICY VARCHAR2 Specifies the name of a policy on which the policy to be created is based.
The default is DEFAULT_POLICY.
DESCRIPTION VARCHAR2 Specifies the description of the policy.
TEXTKEY VARCHAR2 Specifies the column or columns (up to sixteen) that represent the unique identifier (textkey) for each document.
LINENO VARCHAR2 Specifies the column that stores the unique ID for each document section) in a master-detail table.
DSTORE_PREF VARCHAR2 Specifies the name of the Data Store preference assigned to the policy.
COMPRESSOR_ PREF VARCHAR2 Specifies the name of the Compressor preference assigned to the policy (Compressors are not currently provided or supported by ConText Option).
FILTER_PREF VARCHAR2 Specifies the name of the Filter preference assigned to the policy.
LEXER_PREF VARCHAR2 Specifies the name of the Lexer preference assigned to the policy.
WORDLIST_ PREF VARCHAR2 Specifies the name of the Wordlist preference assigned to the policy.
STOPLIST_ PREF VARCHAR2 Specifies the name of the Stoplist preference assigned to the policy.
ENGINE_PREF VARCHAR2 Specifies the name of the Engine preference assigned to the policy.

Examples

begin
ctx_ddl.create_policy(policy_name  => 'MY_POLICY',
                      colspec      => 'DOCS.TEXT',
                      desrcription => 'This is my policy',
                      textkey      => 'AUTH,TITLE'
                      dstore_pref  => 'INTERNAL_STORE',
                      filter_pref  => 'ASCII_TXT',
                      lexer_pref   => 'ENGLISH_BASIC',
                      wordlist_pref => 'CTXSYS.NO_SOUNDEX',
                      stoplist_pref => 'MY_LIST'
                      engine_pref   => 'BASIC_INDEX',);
end;

In this example, the textkey for the DOCS.TEXT is a composite textkey consisting of columns in DOCS named AUTH and TITLE.

Notes

All of the arguments are optional, except for policy_name. If you do not specify a preference for one of the categories, the default preference for the category is automatically used.

For a composite textkey, each column name specified in TEXTKEY must be separated by a comma from the other column names. In addition, the string of column names is limited to 256 characters, including the comma,

If a preference belonging to another user is specified in a policy, the fully-qualified name of the preference must be used. For example, if you want to include the NO_SOUNDEX predefined preference in a policy, the syntax would be:

	(...,
	wordlist_pref => CTXSYS.NO_SOUNDEX,
	...)

CREATE_PREFERENCE

The CTX_DDL.CREATE_PREFERENCE procedure creates a preference in the ConText data dictionary for a Tile. All Tile attributes and their values that have been set using CTX_DDL.SET_ATTRIBUTE are applied to the preference created by CREATE_PREFERENCE.

The preference can then be used in a policy (indexing/linguistic generation) or a source (text loading).

Syntax

CREATE_PREFERENCE(PREFERENCE_NAME, DESCRIPTION, OBJECT_NAME)

Argument Datatype Purpose
PREFERENCE_ NAME VARCHAR2 Specifies the name of the preference to be created.
DESCRIPTION VARCHAR2 Specifies the description for the preference.
OBJECT_NAME VARCHAR2 Specifies the Tile for the preference.

Examples

begin
ctx_ddl.create_preference(
          'NO_JOIN',
          'Text engine that does not use any printjoins',
          'GENERIC ENGINE');
end;

Notes

CREATE_PREFERENCE must always be preceded by one or more SET_ATTRIBUTE calls, which set the attribute values for the specified Tile.

Once CREATE_PREFERENCE is called, the buffer used to store the attributes that were set for the preference is cleared. If the preference creation failed, all of the attributes must be entered again before calling CREATE_PREFERENCE.

CREATE_SOURCE

The CTX_DDL.CREATE_SOURCE procedure creates a text loading source for a column.

Syntax

CREATE_POLICY(NAME, COLSPEC, DESCRIPTION, REFRESH,
              ENGINE_PREF, TRANSLATOR_PREF, READER_PREF)

Argument Datatype Purpose
NAME VARCHAR2 Specifies the name of the source to be created.
COLSPEC VARCHAR2 Specifies the column (and table) to which the source is assigned.
DESCRIPTION VARCHAR2 Specifies the description of the source.
REFRESH NUMBER Specifies the elapsed time, in minutes, before a ConText server checks the specified directory for new files to be loaded.
ENGINE_PREF VARCHAR2 Specifies the name of the Loader Engine preference assigned to the source.
TRANSLATOR_ PREF VARCHAR2 Specifies the name of the Translator preference assigned to the policy.
READER_PREF VARCHAR2 Specifies the name of the Reader preference assigned to the source.

Examples

begin
ctx_ddl.create_source(name         => 'MY_SOURCE',
                      colspec      => 'DOCS.TEXT',
                      desrcription => 'Source for loading',
                      reader_pref  => 'DOCS_DIRECTORY');
end;

In this example, the default Loader Engine and Translator preferences are used.

Notes

COLSPEC must be a LONG or LONG RAW column, because load servers only support loading text into LONG or LONG RAW columns.

If a Loader Engine, Reader, or Translator preference belonging to another user is used to create a source, the fully-qualified name of the preference must be used.

The first time the source directory is scanned for files to load is SYSDATE (of source creation) + REFRESH. Subsequent scans occur at regular intervals specified by REFRESH.

CREATE_TEMPLATE_POLICY

The CTX_DDL.CREATE_TEMPLATE_POLICY procedure creates a policy that does not have a reference to a text column. It is identical to CTX_DDL.CREATE_POLICY, except the COLSPEC argument is not included.

The policy can be used as a template policy for other policies in the user's schema. If CTXSYS uses CREATE_TEMPLATE_POLICY to create a template policy, the policy is available to all ConText users.

Syntax

CREATE_TEMPLATE_POLICY(POLICY_NAME, SOURCE_POLICY,
                       DESCRIPTION, TEXTKEY, LINENO,
                       DSTORE_PREF, COMPRESSOR_PREF
                       FILTER_PREF, LEXER_PREF,
                       WORDLIST_PREF, STOPLIST_PREF,
                       ENGINE_PREF)

Argument Datatype Purpose
POLICY_NAME VARCHAR2 Specifies the name of the template policy to be created.
SOURCE_ POLICY VARCHAR2 Specifies the name of a policy on which the template policy to be created is based.
The default is DEFAULT_POLICY.
DESCRIPTION VARCHAR2 Specifies the description of the template policy.
TEXTKEY VARCHAR2 Specifies the column in the table that stores the unique ID (textkey) for each document.
LINENO VARCHAR2 Specifies the column that stores the unique ID for each document section) in a master-detail table.
DSTORE_PREF VARCHAR2 Specifies the name of the Data Store preference assigned to the policy.
COMPRESSOR_ PREF VARCHAR2 Specifies the name of the Compressor preference assigned to the policy (Compressors are not currently provided or supported by ConText Option).
FILTER_PREF VARCHAR2 Specifies the name of the Filter preference assigned to the policy.
LEXER_PREF VARCHAR2 Specifies the name of the Lexer preference assigned to the policy.
WORDLIST_ PREF VARCHAR2 Specifies the name of the Wordlist preference assigned to the policy.
STOPLIST_ PREF VARCHAR2 Specifies the name of the Stoplist preference assigned to the policy.
ENGINE_PREF VARCHAR2 Specifies the name of the Engine preference assigned to the policy.

Examples

See CTX_DDL.CREATE_POLICY

DROP_INDEX

The CTX_DDL.DROP_INDEX procedure deletes the index for the column defined in the specified policy.

Syntax

DROP_INDEX(POLICY_NAME)

Argument Datatype Purpose
POLICY_NAME VARCHAR2 Specifies the name of the policy for which the index is deleted.

Examples

execute ctx_ddl.drop_index('MY_POLICY')

DROP_POLICY

The CTX_DDL.DROP_POLICY procedure deletes the specified policy from the ConText data dictionary.

Syntax

DROP_POLICY(POLICY_NAME)

Argument Datatype Purpose
POLICY_NAME VARCHAR2 Specifies the name of the policy to be dropped.

Examples

execute ctx_ddl.drop_policy('MY_POLICY')

Notes

If the specified policy has an existing index, the index must be dropped using CTX_DDL.DROP_INDEX before the policy can be dropped.

DROP_PREFERENCE

The CTX_DDL.DROP_PREFERENCE procedure deletes the specified preference from the ConText data dictionary.

Syntax

DROP_PREFERENCE(PREFERENCE_NAME)

Argument Datatype Purpose
PREFERENCE_ NAME VARCHAR2 Specifies the name of the preference to be dropped.

Examples

execute ctx_ddl.drop_preference('MY_ENGINE')

Notes

If the specified preference is currently used in a policy, the policy must be dropped using CTX_DDL.DROP_PREFERENCE before the policy can be dropped.

DROP_SOURCE

The CTX_DDL.DROP_SOURCE procedure deletes the specified text loading source from the ConText data dictionary. A source can be dropped at any time.

Syntax

DROP_SOURCE(SOURCE_NAME)

Argument Datatype Purpose
SOURCE_NAME VARCHAR2 Specifies the name of the source to be dropped.

Examples

execute ctx_ddl.drop_source('MY_LOADER')

OPTIMIZE_INDEX

The CTX_DDL.OPTIMIZE_INDEX procedure optimizes the index for the column defined in the specified policy.

Syntax

OPTIMIZE_INDEX(POLICY_NAME, OPTTYP, THRESHOLD, PARALLEL,
               SWITCH_NEW, DROP_OLD)

Argument Datatype Purpose
POLICY_NAME VARCHAR2 Specifies the name of the policy for the index to be optimized.
OPTTYP NUMBER Specifies the type of optimization performed for the index:
DR_OPTIMIZE_LAZY_ DELETES (use original index table to remove references for deleted/modified documents)
DR_OPTIMIZE_ COMPACT_INDEXES (use original index table to compact index fragments)
DR_OPTIMIZE_ COMPACT_NEW (use mirror index table to compact index fragments)
DEFRAGMENT_TO_ NEW_TABLE (use mirror index table to compact index fragments and remove deleted/modified document references)
DEFRAGMENT_ IN_PLACE (use original index table to compact index fragments and remove deleted document references)
The default depends on the value set for the DEFAULT_OPTIMIZE attribute in the BASIC ENGINE Tile (see notes).
THRESHOLD NUMBER Specifies the threshold, as a percentage, under which a term's index strings are not compacted during in-place compaction.
The default is 50.
PARALLEL NUMBER Specifies the number of ConText servers to be used in parallel to perform two-table optimization.
The default is 1.
SWITCH_NEW BOOLEAN For internal use only.
DROP_OLD BOOLEAN For internal use only.

Examples

begin
ctx_ddl.optimize_index('MY_POLICY',
                      opttyp => ctx_ddl.defragment_in_place,
                      parallel => 2);
end;

Notes

Optimization cannot be performed for an index while any other operation (i.e. creation, updating, deletion) is being performed on the index.

OPTTYP must be fully qualified with the PL/SQL package name (CTX_DDL) as shown in the examples.

The default for OPTTYP is the value specified for the DEFAULT_OPTIMIZE attribute (BASIC ENGINE Tile) in the Engine preference of the policy for the text column to be optimized. If no value was specified for DEFAULT_OPTIMIZE when the Engine preference for the policy was created, the default is DEFRAGMENT_TO_NEW_TABLE.

DEFRAGMENT_IN_PLACE does not use THRESHOLD. If OPTTYP is DEFRAGMENT_IN_PLACE, OPTIMIZE_INDEX ignores any value specified for THRESHOLD.

PARALLEL is used only for two-table compaction and two-table combined reference deletion and compaction.

THRESHOLD is used only for in-place compaction. THRESHOLD specifies the percentage under which ConText Option compacts a term's index fragments (rows) if the compaction will result in the number of fragments for the term being reduced to more than or equal to the percentage specified.

For example, a THRESHOLD of 60 indicates the number of fragments for a given term must be be reduced to 60% or more of the total number of pre-optimization fragments for in-place compaction to take place.

RESUME_FAILED_INDEX

The CTX_DDL.RESUME_FAILED_INDEX procedure resumes an unsuccessful text DDL operation (index creation/optimization).

Note: RESUME_FAILED_INDEX should be called only after the problem that caused the failure has been corrected or removed.

RESUME_FAILED_INDEX uses the ConText index log to determine the point of failure for the index and the point from which to proceed with indexing/optimization.

Depending on the stage at which the text DDL operation failed, RESUME_FAILED_INDEX may start the operation from the beginning, in which case, CREATE_INDEX or OPTIMIZE_INDEX serves the same purpose as RESUME_FAILED_INDEX and can be called in its place.

Because RESUME_FAILED_INDEX automatically determines where to resume a failed DDL operation, the user should consult the index log before calling RESUME_FAILED_INDEX to decide whether to call CREATE_INDEX/OPTIMIZE_INDEX instead.

Syntax

RESUME_FAILED_INDEX(POLICY_NAME, OPERATION, PARALLEL,
                    OPTTYP, SWITCH_NEW, DROP_OLD)

Argument Datatype Purpose
POLICY_NAME VARCHAR2 Specifies the index (through the policy) that requires an Oracle index.
OPERATION NUMBER Specifies the operation that was being performed on the index at the time of failure:
1 (creation)
2 (optimization)
The default is 1.
PARALLEL NUMBER If OPERATION is 1 (index creation), then this argument specifies the degree of parallelism used for creating the index.
The default is 1.
OPTTYP NUMBER If OPERATION is 2 (optimization), then this argument specifies the method of two-table optimization to use:
DR_OPTIMIZE_ COMPACT_NEW (use mirror index table to compact index fragments)
DEFRAGMENT_TO_ NEW_TABLE (use mirror index table to compact index fragments and remove deleted/modified document references)
The default depends on the value set for the DEFAULT_OPTIMIZE attribute in the BASIC ENGINE Tile (see notes).
SWITCH_NEW BOOLEAN For internal use only.
DROP_OLD BOOLEAN For internal use only.

Examples

begin
ctx_ddl.resume_failed_index('MY_POLICY',
                  operation => 2,
                  parallel  => 2,
                  opttyp    => ddl.defragment_to_new_table);
end;

In this example, optimization (OPERATION => 2) is resumed with a parallelism level of 2 for the index for MY_POLICY. The type of optimization performed is compaction and garbage collection combined.

Notes

Only the owner of the policy and CTXSYS can resume creation of an Oracle index on a index.

OPTTYP must be fully qualified with the PL/SQL package name (CTX_DDL) as shown in the examples.

SET_ATTRIBUTE

The CTX_DDL.SET_ATTRIBUTE procedure assigns values to Tile attributes used in the CTX_DDL.CREATE_PREFERENCE procedure.

Syntax

SET_ATTRIBUTE(NAME, VALUE, SEQ)

SET_ATTRIBUTE(NAME, VALUE1, VALUE2 SEQ)

Argument Datatype Purpose
NAME VARCHAR2 Specifies the attribute to which a value is assigned.
VALUE VARCHAR2 VALUE specifies the value assigned to the attribute.
VALUE1 VARCHAR2 VALUE1 specifies the value assigned to the first attribute (used only for the EXECUTBLE attribute for the BLASTER Tile).
VALUE2 VARCHAR2 Specifies the value assigned to the second attribute (used only for the EXECUTBLE attribute for the BLASTER Tile).
SEQ NUMBER Specifies the sequence number assigned to the attribute (only required for creating preferences that use Tiles which support multiple values for the same attribute)
The default is 1.

Examples

execute ctx_ddl.set_attribute('INDEX_MEMORY', '3000000')

In the example above, the INDEX_MEMORY attribute is assigned approximately 3 megabytes of memory. The INDEX_MEMORY attribute belongs to the GENERIC ENGINE Tile and is used for allocating indexing memory.

Notes

SET_ATTRIBUTE writes the specified attribute values to an internal buffer. Once all of the attributes for a particular Tile have been set, CTX_DDL.CREATE_PREFERENCE is called to create a preference for the Tile

Any errors that may occur from entering incorrect values for SET_ATTRIBUTE are not reported until CREATE_PREFERENCE is called.

When CREATE_PREFERENCE is called, the buffer used to store the attributes for the preference is cleared. If the preference creation failed, all of the attributes must be entered again before calling CREATE_PREFERENCE.

CTX_DDL.CLEAR_ATTRIBUTE can be used to manually clear all attributes in the buffer.

SEQ is only used with the Tiles that support multiple values for the same attribute (i.e. BLASTER FILTER and GENERIC STOP LIST). For all the other Tiles, SEQ is not required and should not be set.

A call to SET_ATTRIBUTE that uses the same SEQ value as a previous call to SET_ATTRIBUTE overrides the previously set attribute in the buffer..

UPDATE_POLICY

The CTX_DDL.UPDATE_POLICY procedure updates an existing policy description and/or the preferences specified in the argument string. It can only be called for policies assigned to columns for which ConText Option has not yet generated an index.

Syntax

UPDATE_POLICY(POLICY_NAME, DESCRIPTION,
              DSTORE_PREF, COMPRESSOR_PREF, FILTER_PREF,
              LEXER_PREF, WORDLIST_PREF, STOPLIST_PREF,
              ENGINE_PREF)

Argument Datatype Purpose
POLICY_NAME VARCHAR2 Specifies the name of the policy to be updated.
DESCRIPTION VARCHAR2 Specifies the new description of the policy.
DSTORE_PREF VARCHAR2 Specifies the name of the new Data Store preference for the policy.
COMPRESSOR_ PREF VARCHAR2 Specifies the name of the new Compressor preference (Compressors are not currently provided or supported by ConText Option).
FILTER_PREF VARCHAR2 Specifies the name of the new Filter preference for the policy.
LEXER_PREF VARCHAR2 Specifies the name of the new Lexer preference for the policy.
WORDLIST_ PREF VARCHAR2 Specifies the name of the new Wordlist preference for the policy.
STOPLIST_PREF VARCHAR2 Specifies the name of the new Stoplist preference for the policy.
ENGINE_PREF VARCHAR2 Specifies the name of the new Engine preference for the policy.

Examples

begin
ctx_ddl.update_policy(policy_name   => 'MY_POLICY',
                      dstore_pref   => 'CTX.MD_BINARY');
end;

Notes

If a preference belonging to another user is used to update a policy, the fully-qualified name of the preference must be used.

UPDATE_SOURCE

The CTX_DDL.UPDATE_SOURCE procedure updates the description, text column, refresh rate, and preferences for the text loading source specified in the argument string. UPDATE_SOURCE can be called at any time for any existing source.

Syntax

UPDATE_SOURCE(NAME, COLSPEC, DESCRIPTION, REFRESH, NEXT,
              ENGINE_PREF, TRANSLATOR_PREF, READER_PREF)

Argument Datatype Purpose
NAME VARCHAR2 Specifies the name of the source to be updated.
COLSPEC VARCHAR2 Specifies the new text column referenced in the source.
DESCRIPTION VARCHAR2 Specifies the new description of the source.
REFRESH NUMBER Specifies the new refresh rate, in minutes, for the source.
NEXT DATE Specifies a date and time for the initial scan of updated source by available Loader servers.
ENGINE_PREF VARCHAR2 Specifies the name of the new text loading Engine preference for the source.
TRANSLATOR_ PREF VARCHAR2 Specifies the name of the new text loading Translator perference for the source.
READER_PREF VARCHAR2 Specifies the name of the new text loading Reader preference for the source.

Examples

begin
ctx_ddl.update_policy(policy_name   => 'MY_POLICY',
                      dstore_pref   => 'CTX.MD_BINARY');
end;

Notes

If a Loader Engine, Reader, or Translator preference belonging to another user is used to update a source, the fully-qualified name of the preference must be used.

NEXT specifies the date and time that an updated source is initially scanned by ConText servers running with the Loader (R) personality.

The next scan of the source occurs at NEXT + REFRESH, then all subsequent scans occur at regular intervals specified by REFRESH.

ConText Index Update and Management - CTX_DML

The CTX_DML PL/SQL package is used to manage DML Operations. CTX_DML contains the following stored procedures and functions:

NAME TYPE DESCRIPTION
REINDEX Procedure Specifies reindexing for a document
SYNC Procedure Batches all pending requests in DML Queue and enables ConText servers with DDL personality to process the batches
SYNC_QUERY Function Returns a time-stamp in the form of a date for the batches generated by SYNC

Table 10 - 4. CTX_DML Procedures and Functions (Page 1 of 1)

REINDEX

The CTX_DML.REINDEX procedure is used to write a row to the DML Queue for a specified document. The index for the document is then created/updated according to the DML method being used (immediate or batch).

REINDEX can be used to reindex documents that have errored during DDL or DML. It can also be used to provide DML processing on a view. Views cannot have a trigger assigned, meaning that DML operations on a view cannot be sent to the DML Queue by way of the trigger that is automatically created when a table is indexed.

Finally, it can be used to notify the system of updates to documents stored externally. If a document uses the OSFILE Data Store, REINDEX can be called when the document is updated to ensure that the update is recorded in the DML Queue.

Syntax

REINDEX(POLICY, PK)

REINDEX(CID, PK)

Argument Datatype Purpose
POLICY VARCHAR2 Specifies name of policy for text column where document to be reindexed is stored.
CID NUMBER Specifies identifier for column where document to be reindexed is stored.
PK VARCHAR2 Specifies ID for document to be reindexed.

Examples

execute ctx_dml.reindex('MY_POLICY', '1')

execute ctx_dml.reindex(3451, '1')

Notes

REINDEX does not perform a COMMIT. After REINDEX is called for a document, COMMIT must be performed to save the request in the DML Queue.

REINDEX uses either the policy name or the column ID to identify the column where the document to be reindexed is stored.

SYNC

The CTX_DML.SYNC procedure bundles all pending rows in the DML Queue at the time it is called and enables ConText servers with the DDL personality to process the rows as a single batch (if parallelism is not specified) or as a group of batches (if parallelism is specified).

A time stamp can be specified to limit the rows in the batch to those rows with a time stamp equal to or less than the time stamp specified. CID is used to limit SYNC to a particular text column. Otherwise, SYNC is performed for every text column in the database.

Syntax

SYNC(TIMESTAMP, POL, PARALLEL)

Argument Datatype Purpose
TIMESTAMP DATE Specifies the time at which you want the batch DML to start.
The default is SYSDATE.
POL VARCHAR2 Specifies the policy for the text column for which SYNC is performed.
PARALLEL NUMBER Specifies the number of ConText servers used to process the operation.
The default is 1.
TESTING NUMBER For internal use only.
TIMEOUT NUMBER For internal use only.

Examples

execute ctx_dml.sync(PARALLEL=>2)

SYNC_QUERY

The CTX_DML.SYNC_QUERY function returns a DATE which is the lower bound to which rows in the DML Queue have been indexed. CID can be used to limit SYNC_QUERY to a particular text column. Otherwise, SYNC_QUERY returns the DATE value for all text columns.

Syntax

SYNC_QUERY(CID)

Argument Datatype Purpose
CID NUMBER Specifies the text column for which SYNC_QUERY is called.
CUR_DATE DATE Specifies the date from which to perform the query synchronization

Returns

DATE

Examples

select ctx_dml.sync_query(3) from dual;

Thesaurus Management - CTX_THES

The CTX_THES PL/SQL package is used to manage thesauri in the ConText Option thesaurus tables. CTX_THES contains the following stored procedures and functions:

NAME TYPE DESCRIPTION
CREATE_PHRASE Function Adds a phrase to the specified thesaurus or modifies the information about the phrase in the thesaurus
CREATE_THESAURUS Procedure Creates the specified thesaurus
DROP_THESAURUS Procedure Drops the specified thesaurus from the thesaurus tables

Table 10 - 5. CTX_DML Procedures and Functions (Page 1 of 1)

Note: The remaining procedures and functions in CTX_THS are used to enable the thesaurus operators in query expressions.

For more information about the thesaurus operators, see Oracle ConText Option Application Developer's Guide.

CREATE_PHRASE

The CTX_THES.CREATE_PHRASE function adds a new entry or updates an existing entry in the named thesaurus.

Syntax

CREATE_THESAURUS(TNAME, PHRASE, REL, RELNAME)

Argument Datatype Purpose
TNAME VARCHAR2 Name of the thesaurus in which a new entry is added or an existing entry is updated.
PHRASE VARCHAR2 The text of the entry to be added/modified.
REL VARCHAR2 The text of the entry that is related to the new/modified entry.
RELNAME VARCHAR2 The relationship between the two entries:
SYN, BT, NT, BTG, NTG, BTP, NTP, RT, TT

Returns

NUMBER

Examples

begin
ctx_thes.create_phrase('my_thes','car',
                       'transportation,'BTN');
end;

CREATE_THESAURUS

The CTX_THES.CREATE_THESAURUS procedure creates an empty thesaurus with the specified name in the thesaurus tables.

Syntax

CREATE_THESAURUS(NAME)

Argument Datatype Purpose
NAME VARCHAR2 Specifies the name of the thesaurus to be created.

Examples

execute ctx_ths.create_thesaurus('my_thes');

Notes

To enter phrases in the thesaurus, use CTX_THES.CREATE_PHRASE or use the Thesaurus Maintenance screen in the ConText Option administration tool.

DROP_THESAURUS

The CTX_THES.DROP_THESAURUS procedure deletes all the entries from the thesaurus tables for the specified thesaurus.

Syntax

DROP_THESAURUS(NAME)

Argument Datatype Purpose
NAME VARCHAR2 Specifies the name of the thesaurus to be dropped.

Examples

execute ctx_ths.drop_thesaurus('my_thes');

Product Information - CTX_INFO

The CTX_INFO PL/SQL package is used to obtain information about the installed version of ConText Option. CTX_INFO contains the following stored procedures and functions:

NAME TYPE DESCRIPTION
GET_INFO Procedure Returns the status and version number for the installed ConText Option
GET_STATUS Function Returns the status of ConText Option
GET_VERSION Function Returns the version number for the installed ConText Option

Table 10 - 6. CTX_DML Procedures and Functions (Page 1 of 1)

GET_INFO

The CTX_INFO.GET_INFO procedure calls the GET_VERSION and GET_STATUS functions in CTX_INFO to return version and status information for ConText Option.

Syntax

GET_INFO(PRODUCT, VERSION, STATUS)

Argument Datatype Purpose
PRODUCT VARCHAR2 Specifies the product for which information is returned.
The only product for which information can be obtained is OCO (ConText Option)
VERSION VARCHAR2 (OUT) Specifies the version of the product.
STATUS VARCHAR2 (OUT) Specifies the status of the product.

Examples

declare
	version varchar2(20);
	status varchar2(20);
begin
	ctx_info.get_info(CTX_INFO.OCO, version, status);
	dbms_output.put_line ('OCO version is '||version||');
	dbms_output.put_line ('OCO status is '||status||');
end;

Notes

PRODUCT must be fully qualified with the PL/SQL package name (CTX_INFO) as shown in the examples.

GET_STATUS

The CTX_INFO.GET_STATUS function returns the product status for ConText Option.

Syntax

GET_STATUS(PRODUCT)

Argument Datatype Purpose
PRODUCT VARCHAR2 Specifies the product for which a status returned.
The only product for which information can be obtained is OCO (ConText Option).

Returns

VARCHAR2

Examples

declare
	status varchar2(60);
begin
	status := ctx_info.get_status(CTX_INFO.OCO);
	dbms_output.put_line ('OCO status is '||status||');
end;

Notes

PRODUCT must be fully qualified with the PL/SQL package name (CTX_INFO) as shown in the examples.

GET_VERSION

The CTX_INFO.GET_VERSION function returns the version number for the version of ConText Option.

Syntax

GET_VERSION(PRODUCT)

Argument Datatype Purpose
PRODUCT VARCHAR2 Specifies the product for which a version number is returned.
The only product for which information can be obtained is OCO (ConText Option).

Returns

NUMBER (Version number for ConText Option)

Examples

declare
	version number;
begin
	version := ctx_info.get_version(CTX_INFO.OCO);
	dbms_output.put_line ('OCO version is '||version||');
end;

Notes

PRODUCT must be fully qualified with the PL/SQL package name (CTX_INFO) as shown in the examples.

Prev Next

Library

Product

Contents

Index

*NAME*	*TYPE*	*DESCRIPTION*
CHANGE_MASK	Procedure	Modifies the personality mask for a ConText server
GET_QUEUE_STATUS	Function	Returns the status of the specified queue
RECOVER	Procedure	Cleans up database objects for deleted text tables
SET_QUERY_BUFFER_SIZE	Procedure	Increases the size of the pipe used for queries
SHUTDOWN	Procedure	Shuts down a single ConText server or all currently running ConText servers
UPDATE_QUEUE_STATUS	Procedure	Updates the status of the specified queue

Argument	Datatype	Purpose
NAME	VARCHAR2	Specifies the name (internal ID) of the server for which you are changing the personality mask.
PERSONALITY_ MASK	VARCHAR2	Specifies the new personality mask that you want to assign to the server. Can be any combination of: R, Q, D, M, or L The default is QDM.