G Using the wwv_context APIs

G.1.1 add_attribute_section

procedure add_attribute_section(
    p_attributeid     in number,
    p_attributesiteid in number
) 

Adds a new section to the section groups used by the Item and Page indexes. The section group corresponds to an attribute. This changes the index metadata only, it does not update the index data itself. The new sections can be searched but the indexes themselves are not changed.

The indexes are changed only if they exist; if the indexes do not exist, this procedure has no effect.

Parameters:

p_attributeId - ID of the attribute section to add.

p_attributeSiteId - Site ID of the attribute section to add.

G.1.2 commit_sync

procedure commit_sync(
    p_index       in varchar2
    p_commit_sync in boolean
)

(Oracle Database 10g or later) Specifies whether an Oracle Text index is synchronized immediately after data is committed to your portal, or needs to be synchronized manually using wwv_context.sync (see sync).

If you choose to synchronize an index manually or your database is earlier than Oracle Database 10g, you can run wwv_context.sync directly or create a job that calls wwv_context.sync at regular intervals. wwv_context.sync ignores any index where commit_sync is set to true. See also, Section 8.3.5.4, "Scheduling Index Synchronization".

Parameters:

p_index - The name of the index. One of the Index Name Constants.

p_commit_sync - Determines whether the index synchronizes immediately after a commit. Set commit_sync to true if you want the index to synchronize automatically whenever data is committed in your portal. Set commit_sync to false if you want to synchronize the index manually using wwv_context.sync.

Exception:

INVALID_INDEX - The name of the index was not recognized.

G.1.3 create_index

procedure create_index(
    p_index in varchar2
) 

Creates a specific, named Oracle Text index. See also, Section 8.3.3, "Oracle Text Indexes".

Use this procedure for troubleshooting purposes only. Under normal circumstances, use create_missing_indexes to create all of the indexes that are missing, or createindex to drop invalid indexes and then re-create the preferences and missing indexes.

Parameters:

p_index - The name of the index you want to create. One of the Index Name Constants.

Exceptions:

INVALID_INDEX - The name of the index was not recognized.

G.1.4 create_missing_indexes

procedure create_missing_indexes(
    p_indexes out wwsbr_array
) 

Creates all of the Oracle Text indexes that are missing. An index is considered to be present if it exists according to the view ctx_user_indexes.

This procedure does not check to see if the existing indexes are valid. Use the procedure drop_invalid_indexes to drop any indexes that are not entirely valid.

This procedure creates empty indexes. To populate the indexes you must mark them as 'requiring re-indexing' using the procedure touch_index(p_indexes wwsbr_array), and then you must synchronize the indexes.

This procedure does not create Oracle Text Datastore and Filter preferences; these preferences must already exist. Use the procedure create_prefs to create the preferences, if they do not exist.

Parameters:

p_indexes - Returns an array containing the list of indexes created.

G.1.5 create_prefs

procedure create_prefs

Creates the Datastore and Filter preferences which are both used when creating Oracle Text indexes. See also, Section 8.3.3.2, "Oracle Text Index Preferences".

This procedure does not create any of the Lexer preferences. Use the script sbrimtlx.sql located in the directory ORACLE_HOME/portal/admin/plsql/wws to create Lexer preferences. See also, Section 8.3.3.5, "Multilingual Functionality (Multilexer)".

Oracle Text preferences must exist before the indexes are created. Subsequent changes to these preferences do not take effect until the Oracle Text indexes are dropped and re-created.

G.1.6 createindex

procedure createindex(
    p_language in  varchar2 default wwnls_api.nls_default_language,
    p_message  out varchar2
) 

Creates Oracle Text indexes used by OracleAS Portal. See Section 8.3.3, "Oracle Text Indexes" for more information.

This high level procedure performs the following tasks:

• Drops all existing preference objects.

• Drops any invalid indexes.

• Re-creates Oracle Text preferences.

• Creates indexes that are missing (initially empty).

• Marks all indexable OracleAS Portal content as requiring re-indexing, for all new indexes.

• Synchronizes indexes, that is, first populates and then optimizes the indexes.

This procedure is equivalent to:

wwv_context.drop_prefs;
wwv_context.drop_invalid_indexes;
wwv_context.create_prefs;
wwv_context.create_missing_indexes(l_indexes);
wwv_context.touch_index(l_indexes);
wwv_context.sync;
wwv_context.optimize;

G.1.7 drop_all_indexes

procedure drop_all_indexes

Drops all the Oracle Text indexes used by OracleAS Portal.

This procedure does not drop the Oracle Text preferences. Use the procedure drop_prefs to do this.

G.1.8 drop_index

procedure drop_index(
    p_index in varchar2
) 

Drops a specific, named Oracle Text index. This procedure does not validate that the index exists.

Parameters:

p_index - The name of the index you want to drop. One of the Index Name Constants.

Exceptions:

INVALID_INDEX - The name of the index was not recognized.

G.1.9 drop_invalid_indexes

procedure drop_invalid_indexes

Drops invalid Oracle Text indexes only, that is, valid Oracle Text indexes are not dropped.

An index is considered to be valid, if the following status columns, in the following views, are all set to 'VALID':

• user_indexes.status

• user_indexes.domidx_status

• user_indexes.domidx_optstatus

• ctx_user_indexes.idx_status

If any status column is not valid or, if the index does not have an entry in both views, it is considered to be invalid and will be dropped. See Section 8.3.8, "Viewing the Status of Oracle Text Indexes" for more information.

G.1.10 drop_prefs

procedure drop_prefs

Drops the Oracle Text Datastore and Filter preferences. See also, Section 8.3.3.2, "Oracle Text Index Preferences".

Datastore and Filter preferences are used when creating the Oracle Text indexes. This procedure does not drop any of the Lexer preferences that are created using the script sbrimtlx.sql. The script is located in the directory ORACLE_HOME/portal/admin/plsql/wws.

G.1.11 dropindex

procedure dropindex(
    p_language in varchar2 default wwnls_api.nls_default_language,
    p_message  out varchar2
) 

Drops all existing Oracle Text indexes used by OracleAS Portal. See also, Section 8.3.3, "Oracle Text Indexes".

This procedure is equivalent to:

wwv_context.drop_prefs;
wwv_context.drop_all_indexes;

G.1.12 optimize

procedure optimize(
    p_optlevel in varchar2 default ctx_ddl.optlevel_full,
    p_maxtime  in number   default null,
    p_token    in varchar2 default null
) 

Optimizes all existing Oracle Text indexes used by OracleAS Portal. Each index is optimized by calling the Oracle Text procedure ctx_ddl.optimize_index().

The parameters for this procedure are the same as those required by the Oracle Text procedure ctx_ddl.optimize_index.

Parameters:

p_optlevel - The optimization level, one of FULL, FAST or TOKEN.

p_maxtime - The time (in minutes) that Oracle Text spends optimizing the indexes.

p_token - Token to optimize (when doing TOKEN optimization).

You will find additional information in the Oracle Text Reference on the Oracle Technology Network (OTN), http://www.oracle.com/technology/products/text/index.html.

G.1.13 set_parallel_degree

procedure set_parallel_degree(
    p_index           in varchar2,
    p_parallel_degree in pls_integer
) 

Sets the degree of parallelism used when an index is synchronized using the procedure wwv_context.sync (see sync). On a multi-processor computer you can run the synchronization operation in parallel. If you use multiple processors during synchronization it can speed up indexing, especially when you have large amounts of data to index.

The default setting is 1, no parallelism. A number greater than 1 turns on parallel synchronization. If you specify a parallel degree that is higher than the total number of processors available in your database server, the degree of parallelism achieved during synchronization might be smaller than requested.

You will find additional information in the Oracle Text Reference on OTN, http://www.oracle.com/technology/products/text/index.html.

Parameters:

p_index - The name of the index. One of the Index Name Constants.

p_parallel_degree - The degree of parallelism to use when the specified index is synchronized.

Exceptions:

INVALID_SETTING - The format or value of p_parallel_degree was not recognized.

INVALID_INDEX - The name of the index was not recognized.

INTERNAL_EXCEPTION - An unexpected internal error occurred.

G.1.14 set_sync_memory

procedure set_sync_memory(
    p_index  in varchar2,
    p_memory in varchar2
) 

Specifies the amount of runtime memory that Oracle Text may use when synchronizing an index using the procedure wwv_context.sync (see sync). You can enter the memory value in bytes, or use the suffixes K, B or G to indicate that the value is in kilobytes, megabytes, or gigabytes respectively. For example, enter the value 10000 to specify 10000 bytes, or 10K to specify 10 kilobytes.

When the memory specified becomes full, the data is written to the database. The more frequently this happens, the slower the indexing performance becomes and the Oracle Text indexes also become more fragmented. Fragmentation can slow down portal search queries. Specifying smaller amounts of memory will impact performance and increase index fragmentation, but might be useful when runtime memory is scarce.

If you set p_memory to Null, the default index memory setting is used. This default value is set using the configurable Oracle Text system parameter DEFAULT_INDEX_MEMORY. If you want to specify a different value, it must be less than the Oracle Text system parameter MAX_INDEX_MEMORY.

For more information, see Oracle Text Reference on OTN, http://www.oracle.com/technology/products/text/index.html.

Parameters:

p_index - The name of the index. One of the Index Name Constants.

p_memory - The maximum amount of memory used to synchronize this index.

Exceptions:

INVALID_SETTING - The format or range of p_memory was not recognized.

INVALID_INDEX - The name of the index was not recognized.

INTERNAL_EXCEPTION - An unexpected internal error occurred.

G.1.15 set_use_doc_index

procedure set_use_doc_index(
p_value in boolean )

Specifies whether the Document index is required. See also, Section 8.3.7, "Disabling Document and URL Indexing".

The value is cached for the duration of the session to avoid repeated requests for this information.

Parameters:

p_value - Either true or false. When set to true, the Document index is required.

G.1.16 set_use_url_index

procedure set_use_url_index(
p_value in boolean )

Specifies whether the URL index is required. See Section 8.3.7, "Disabling Document and URL Indexing" for more information.

The value is cached for the duration of the session to avoid repeated requests for this information.

Parameters:

p_value - Either true or false. When set to true, the URL index is required.

G.1.17 sync

procedure sync

Synchronizes all Oracle Text indexes used by OracleAS Portal. Each index is synchronized by calling the Oracle Text procedure ctx_ddl.sync_index(). This procedure re indexes any rows that have been updated since the last synchronization. After synchronization, newly added or updated content can be searched. See also, Section 8.3.5.1, "Synchronizing Oracle Text Indexes".

Before synchronization, the pending queue is updated for the table wwsbr_url$. This table contains values for all the URLs attributes stored in OracleAS Portal. Rows from this queue are removed when the URL value is equal to the value of the constant wwv_context_util.g_noindex. Rows are set to this value to indicate that the original URL was not indexable by Oracle Text, for example, URLs such as those beginning with https:// or javascript:.

You will find additional information on ctx_ddl.sync_index in Oracle Text Reference documentation on OTN, http://www.oracle.com/technology/products/text/index.html.

G.1.18 touch_index(p_indexes wwsbr_array)

procedure touch_index(
    p_indexes in wwsbr_array
) 

Touches content for one or more indexes. When an index is touched, all the index content is marked as requiring synchronization. See Section 8.3.5.6, "Synchronizing All the Index Content" for more information.

Once index content is marked in this way, use the procedure sync to re index the marked content.

Note that this procedure operates across multiple virtual private portal subscribers, it is not confined to the current subscriber. The procedure switches to each subscriber in turn and returns back to the original subscriber when complete.

Parameters:

p_indexes - An array containing index names to touch. One or more of the Index Name Constants.

G.1.19 touch_index

procedure touch_index(
    p_index in varchar2 default null
) 

Touches content for a single index or for all indexes. This procedure is a convenient way to touch a single, named index. Alternatively, you can use the procedure to touch all indexes, by passing the value null. See also, Section 8.3.5.6, "Synchronizing All the Index Content".

This procedure calls touch_index(p_indexes wwsbr_array) mentioned earlier.

Parameters:

p_index - The name of the index to touch, or null to touch all indexes. When specifying a name, use of one of the Index Name Constants.

Refer to Section G.1.18, "touch_index(p_indexes wwsbr_array)" for more information.

G.1.20 update_index_prefs

procedure update_index_prefs

Updates the current Oracle Text index datastore preferences. This procedure is valid only for database versions earlier than Oracle Database 10g.

When datastore preferences are modified after the indexes are created, the changes are not applied to the indexes automatically. Use this procedure to apply datastore preference changes to the Oracle Text indexes.

No action is taken for any indexes that are missing.

G.2.1 checkindex

function checkindex(
    p_force in boolean default false
) return boolean

Checks whether all required Oracle Text indexes exist. The Document and URL indexes are optional, so the presence and validity of these indexes are determined by calls to valid_doc_index and valid_url_index. See also, Section 8.3.7, "Disabling Document and URL Indexing".

The value returned by checkindex is cached for the duration of the session. Whenever true is passed to p_force, the status of Oracle Text indexes is re-evaluated, regardless of any previously cached value.

Parameters:

p_force - Either true or false. When set to true, Oracle Text indexes are checked.

Returns:

Returns true if all required indexes exist and are valid.

G.2.2 doc_index

function doc_index
return boolean

Checks whether the Document index is required (using get_use_doc_index) and usable (using valid_doc_index).

Returns:

Returns true if the Document index is both required and valid.

G.2.3 get_commit_sync

function get_commit_sync(
  p_index in varchar2)
return boolean

Determines whether an index synchronizes immediately after data commits to your portal, or if it must be synchronized manually. See also, commit_sync.

Parameters:

p_index - The name of the index. One of the Index Name Constants.

Returns:

Returns true if the index is configured to synchronize immediately after data is committed to your portal. Returns false if the index is configured to synchronize manually.

G.2.4 get_parallel_degree

function get_parallel_degree(
    p_index in varchar2)
return boolean

Gets the degree of parallelism used when an index is synchronized using the procedure wwv_context.sync (see sync). On a multi-processor computer you can run the synchronization operation in parallel. If you use multiple processors during synchronization it can speed up indexing, especially when you have large amounts of data to index.

The default setting is 1, no parallelism. A number greater than 1 turns on parallel synchronization. If the parallel degree is higher than the total number of processors available in your database server, the degree of parallelism achieved during synchronization might be smaller than that requested.

You will find additional information in the Oracle Text Reference on OTN, http://www.oracle.com/technology/products/text/index.html.

Parameters:

p_index - The name of the index. One of the Index Name Constants.

Returns:

Returns the degree of parallelism used when synchronizing the specified index.

Exceptions:

INVALID_INDEX - The name of the index was not recognized.

INTERNAL_EXCEPTION - An unexpected internal error occurred.

G.2.5 get_sync_memory

function get_sync_memory(
    p_index in varchar2)
return boolean

Gets the amount of runtime memory (in bytes) that Oracle Text may use when synchronizing an index using the procedure wwv_context.sync (see sync).

When this memory becomes full, the data is written to the database. The more frequently this happens, the slower the indexing performance becomes and the Oracle Text indexes also become more fragmented. Fragmentation can slow down portal search queries. Small amounts of memory will impact performance and increase index fragmentation, but might be useful when runtime memory is scarce.

A Null value indicates that the default index memory setting is used. This default value is set using the configurable Oracle Text system parameter DEFAULT_INDEX_MEMORY. For more information, see Oracle Text Reference on OTN, http://www.oracle.com/technology/products/text/index.html.

Parameters:

p_index - The name of the index. One of the Index Name Constants.

Returns:

Returns the amount of memory (in bytes) used when synchronizing the specified index.

Exceptions:

INVALID_INDEX - The name of the index was not recognized.

INTERNAL_EXCEPTION - An unexpected internal error occurred.

G.2.6 get_use_doc_index

function get_use_doc_index
return boolean

Determines whether the Document index is required. See also, Section 8.3.7, "Disabling Document and URL Indexing".

The value is cached for the duration of the session to avoid repeated requests for this information.

Returns:

Returns true if the Document index is required.

G.2.7 get_use_url_index

function get_use_url_index
return boolean

Determines whether the URL index is required. See also, Section 8.3.7, "Disabling Document and URL Indexing".

The value is cached for the duration of the session to avoid repeated requests for this information.

Returns:

Returns true if the URL index is required.

G.2.8 valid_doc_index

function valid_doc_index
return boolean

Determines whether the Document index is in a valid, usable state. See also, Section 8.3.7, "Disabling Document and URL Indexing". The function checkindex is called, if it has not yet been called.

The value is cached for the duration of the session to avoid repeated requests for this information.

Returns:

Returns true if the Document index exists and is valid.

G.2.9 valid_url_index

function valid_url_index
return boolean

Determines whether the URL index is in a valid, usable state. See also, Section 8.3.7, "Disabling Document and URL Indexing". The function checkindex is called, if it has not yet been called.

The value is cached for the duration of the session to avoid repeated requests for this information.

Returns:

Returns true if the URL index exists and is valid.

G.2.10 url_index

function url_index
return boolean

Checks whether the URL index is required (using get_use_url_index) and usable (using valid_url_index).

Returns:

Returns true if the URL index is both required and valid.

G.3.1 Index Name Constants

Use the following constants to identify the Oracle Text indexes used by OracleAS Portal:

• Page index - wwv_context.PAGE_TEXT_INDEX

• Document index - wwv_context.DOC_TEXT_INDEX

• Perspective index - wwv_context.PERSPECTIVE_TEXT_INDEX

• Item index - wwv_context.ITEM_TEXT_INDEX

• Category index - wwv_context.CATEGORY_TEXT_INDEX

• URL index - wwv_context.URL_TEXT_INDEX

PAGE_TEXT_INDEX

PAGE_TEXT_INDEX constant varchar2(30) := 'WWSBR_CORNER_CTX_INDX'

DOC_TEXT_INDEX

DOC_TEXT_INDEX constant varchar2(30) := 'WWSBR_DOC_CTX_INDX'

PERSPECTIVE_TEXT_INDEX

PERSPECTIVE_TEXT_INDEX constant varchar2(30) := 'WWSBR_PERSP_CTX_INDX'

ITEM_TEXT_INDEX

ITEM_TEXT_INDEX constant varchar2(30) := 'WWSBR_THING_CTX_INDX'

CATEGORY_TEXT_INDEX

CATEGORY_TEXT_INDEX constant varchar2(30) := 'WWSBR_TOPIC_CTX_INDX'

URL_TEXT_INDEX

URL_TEXT_INDEX constant varchar2(30) := 'WWSBR_URL_CTX_INDX'

G.3.2 Oracle Text AUTO_FILTER Format Constants

The Document and URL indexes uses AUTO_FILTER to convert documents into a plain text format suitable for indexing. Not all document types need to be filtered; some document types can be indexed directly. AUTO_FILTER uses the following settings to determine which documents require filtering:

• BINARY_FORMAT - indicates that a document is a format, other than plain text or HTML, but supported by AUTO_FILTER, such as PDF. Such documents are converted into an indexable text format (providing the binary format is supported by AUTO_FILTER).

• TEXT_FORMAT - indicates that a document is either plain text or HTML. When specified, the document is not filtered, but might be character set converted.

• IGNORE - indicates that a document need not be indexed at all; for example, image files.

BINARY_FORMAT

BINARY_FORMAT constant varchar2(10) := 'BINARY';

TEXT_FORMAT

TEXT_FORMAT   constant varchar2(10) := 'TEXT';

IGNORE

IGNORE        constant varchar2(10) := 'IGNORE';

G.3.3 Oracle Text Job Constants

Use these constants for managing Oracle Text maintenance jobs:

• SYNC_JOB_PREF - the preference name for storing the synchronization job ID. Used by the index synchronization script textjsub.sql. See also, Section 8.3.5.4, "Scheduling Index Synchronization".

• OPTIMIZE_JOB_PREF - the preference name for storing the optimization job ID. Used by the index optimization script optjsub.sql. See also, Section 8.3.5.8, "Scheduling Index Optimization".

SYNC_JOB_PREF

SYNC_JOB_PREF constant varchar2(20) := 'text_sync_jobid';

OPTIMIZE_JOB_PREF

OPTIMIZE_JOB_PREF constant varchar2(20) := 'text_optimize_jobid';

G.3.4 URL Unsuitable for Indexing Constant

The absolute URL value used to indicate that a row should not be indexed. The URL index is created on the wwsbr_url.absolute_url column and this column is populated by a trigger.

If a URL is not suitable for indexing, such as URLs beginning with javascript:, this constant value is used. See also, Section 8.3.6.2, "Unsupported URLs".

G_NOINDEX

G_NOINDEX constant varchar2(15) := 'wwsbr_noindex'