12 Oracle Ultra Search Administration PL/SQL APIs

This chapter provides reference information on PL/SQL APIs available for use with Oracle Ultra Search. The APIs are grouped as follows:

Instance-Related APIs
Schedule-Related APIs
Crawler Configuration APIs

The following tables show the contents of each API group.

Table 12-1 shows the Instance-Related APIs.

Table 12-1 Instance-Related APIs

Name	Function
CREATE_INSTANCE	create an Oracle Ultra Search instance
DROP_INSTANCE	drop an Oracle Ultra Search instance
GRANT_ADMIN	grant instance administrator privileges
REVOKE_ADMIN	revoke instance administrator privileges
SET_INSTANCE	operate on an Oracle Ultra Search instance

Table 12-2 shows the Schedule-Related APIs.

Table 12-2 Schedule-Related APIs

Name	Function
CREATE_SCHEDULE	create a crawler schedule
DROP_SCHEDULE	drop a crawler schedule
INTERVAL	generate a schedule interval string
SET_SCHEDULE	run, resume, or stop a schedule
UPDATE_SCHEDULE	update a crawler schedule

Table 12-3 shows the Crawler Configuration APIs.

Table 12-3 Crawler Configuration APIs

Name	Function
IS_ADMIN_READONLY	check if a crawler configuration setting is read-only
SET_ADMIN_READONLY	make a read-only crawler configuration
UPDATE_CRAWLER_CONFIG	update crawler configurations

Instance-Related APIs

This section provides reference information for using the instance-related APIs.

CREATE_INSTANCE

Use this procedure to create an Oracle Ultra Search instance.

Syntax

OUS_ADM.CREATE_INSTANCE(
  inst_name     IN VARCHAR2,
  schema_name   IN VARCHAR2,
  password      IN VARCHAR2 DEFAULT NULL,
  lexer         IN VARCHAR2 DEFAULT NULL,
  stop_list     IN VARCHAR2 DEFAULT NULL,
  data_store    IN VARCHAR2 DEFAULT NULL,
  snapshot      IN NUMBER DEFAULT ous_adm.NO,
);

inst_name: The name of the instance.
schema_name: The name of the schema.
password: The password for the schema.
lexer: The Oracle Text index lexer preference.
stop-list: The Oracle Text index stoplist preference.
data_store: The Oracle Text index datastore preference.
snapshot: If OUS_ADM is set to YES, create an instance for the snapshot.

Example

OUS_ADM.CREATE_INSTANCE('Scott instance','scott','tiger');

DROP_INSTANCE

Use this procedure to drop an Oracle Ultra Search instance.

Syntax

OUS_ADM.DROP_INSTANCE(
  inst_name IN VARCHAR2
);

inst_name: The name of the instance to drop.

Example

OUS_ADM.DROP_INSTANCE('Scott instance')

GRANT_ADMIN

Use this procedure to grant instance administrator privileges to the specified user either for the current instance or all the instances.

Syntax

OUS_ADM.GRANT_ADMIN (
 user_name     IN VARCHAR2,
 user_type     IN NUMBER DEFAULT DB_USER,
 scope         IN NUMBER DEFAULT CURRENT_INSTANCE,
 grant_option  IN NUMBER DEFAULT NO_OPTION
);

user_name: The name of the user to whom the administrator privilege should be assigned.
user_type: The user type (OUS_ADM.DB_USER: database user, OUS_ADM.LDAP_USER: lightweight single sign-on user).
scope: The scope of the granting; CURRENT_INSTANCE or ALL_INSTANCE.
grant_options: Options for granting privileges: NO_OPTION or WITH_GRANT, which enables the grantee to grant the privilege to other users.

Example

OUS_ADM.GRANT_ADMIN('scott',ous_adm.DB_USER, ous_adm.ALL_INSTANCE);

REVOKE_ADMIN

Use this procedure to revoke instance administrator privileges from the specified user .

Syntax

OUS_ADM.REVOKE_ADMIN (
 user_name  IN VARCHAR2,
 user_type  IN NUMBER DEFAULT DB_USER,
 scope      IN NUMBER DEFAULT CURRENT_INSTANCE
);

user_name: The name of the user whose privileges are to be revoked.
user_type: The user type (OUS_ADM.DB_USER: database user, OUS_ADM.LDAP_USER: lightweight single sign-on user).
scope: The scope of the granting; CURRENT_INSTANCE or ALL_INSTANCE.

Example

OUS_ADM.REVOKE_ADMIN('scott',ous_adm.DB_USER);

SET_INSTANCE

Use this procedure to operate on an Oracle Ultra Search instance. Almost all OUS_ADM APIs require SET_INSTANCE be called first.

Syntax

This procedure takes two forms. In the first, you specify the name of the instance to be set.

OUS_ADM.SET_INSTANCE(
  inst_name IN VARCHAR2
);

inst_name: The name of the instance to be set.

In the second form, you specify the ID of the instance to be set.

OUS_ADM.SET_INSTANCE(
  inst_id IN NUMBER
);

inst_id: The ID of the instance to be set.

Example

OUS_ADM.SET_INSTANCE('Scott Instance');

Schedule-Related APIs

This section provides reference information for using the schedule related APIs.

CREATE_SCHEDULE

Use this procedure to create a crawler schedule. It returns an ID for the schedule.

Syntax

OUS_ADM.CREATE_SCHEDULE (
 name            IN VARCHAR2,
 interval        IN VARCHAR2,
 crawl_mode      IN NUMBER DEFAULT REGULAR_CRAWL,
 recrawl_policy  IN NUMBER DEFAUL RECRAWL_WHEN_MODIFIED,
 crawler_id      IN NUMBER DEFAULT LOCAL_CRAWLER
) return number;

name: The name of the schedule.
interval: The schedule interval. This is a string generated from the OUS_INTERVAL function.
crawl_mode: The crawl mode can be REGULAR_CRAWL, CRAWL_ONLY, or INDEX_ONLY.
recrawl_policy: The recrawl condition can be RECRAWL_WHEN_MODIFIED or RECRAWL_ON_EVERYTHING.
crawler_id: The ID of the crawler used to run the schedule. This can be LOCAL_CRAWLER or the remote crawler ID.

Example

This example creates a crawler schedule that mandates only crawling a marketing Web site with no indexing; it is started every 6 hour by the local crawler.

schedule_id := OUS_ADM.CREATE_SCHEDULE('marketing site schedule',
            OUS_ADM.INTERVAL(ous_adm.HOURLY,6), ous_adm.CRAWL_ONLY);

DROP_SCHEDULE

Use this procedure to drop a crawler schedule.

Syntax

OUS_ADM.DROP_SCHEDULE (
 name IN VARCHAR2
);

name: The name of the schedule to be dropped.

Example

OUS_ADM.DROP_SCHEDULE('marketing site schedule');

INTERVAL

Use this function to generate a schedule interval string.

Syntax

OUS_ADM.INTERVAL (
 type        IN NUMBER,
 frequency   IN NUMBER DEFAULT 1,
 start_hour  IN NUMBER DEFAULT 1,
 start_day   IN NUMBER DEFAULT 1
) return varchar2;

type: The schedule interval type. This permitted values are defined as package constants: HOURLY, DAILY, WEEKLY, MONTHLY, and MANUAL.
frequency: The schedule frequency. This depends on the interval type, it can be "every x number of hours/days/weeks/months." Not used for MANUAL interval type.
start_hour: The schedule's launching hour, in 24-hour format, where 1 represents 1 AM. Not used for HOURLY and MANUAL schedules.
start_day: The schedule's start day; this parameter is only used for WEEKLY and MONTHLY intervals. The day of the week is specified as 0 through 6, where 0 is Sunday; the day of the month is specified as 1 through 31.)

Examples

This specifies an interval of every 5 days starting at 6 PM:

OUS_ADM.INTERVAL(OUS_ADM.DAILY, 5, 18);

This specifies launch-on-demand:

OUS_ADM.INTERVAL(OUS_ADM.MANUAL);

This specifies every 2 weeks on Monday, starting at 6 AM:

OUS_ADM.INTERVAL(type=>OUS_ADM.WEEKLY,frequency=>2,start_day=>2,start_hour=>6);

This specifies every 3 months, starting on the first day of the month at 11 PM:

OUS_ADM.INTERVAL(OUS_ADM.MONTHLY, 3, 23, 1);

SET_SCHEDULE

Use this procedure to run, resume, or stop a schedule.

Syntax

OUS_ADM.SET_SCHEDULE (
 name       IN VARCHAR2,
 operation  IN NUMBER
);

name: The name of the schedule.
operation: This may be EXECUTE, RESUME, or STOP.

Example

OUS_ADM.SET_SCHEDULE('marketing site schedule', ous_adm.EXECUTE);

UPDATE_SCHEDULE

Use this procedure to update a crawler schedule.

Syntax

OUS_ADM.UPDATE_SCHEDULE (
 name       IN VARCHAR2,
 operation  IN NUMBER,
 value      IN VARCHAR2 DEFAULT null
);

name

The name of the schedule that is to be updated.

operation

The desired update operation.

Some operations may need a value. Possible values include RENAME, ADD_DS, REMOVE_DS, SET_INTERVAL, CRAWL_MODE, RECRAWL_POLICY, and SET_CRAWLER. Values that are not permitted include ENABLE_SCHEDULE and DISABLE_SCHEDULE.

value

This parameter is context-sensitive to the update operation. It can be a new schedule name (RENAME), a data source name (ADD_DS or REMOVE_DS), an interval string (SET_INTERVAL), a crawl mode value (CRAWL_MODE), a recrawl policy (RECRAWL), or a crawler ID (SET_CRAWLER).

Examples

OUS_ADM.UPDATE_SCHEDULE('marketing site schedule', ous_adm.SET_INTERVAL, 
       OUS_ADM.INTERVAL(ous_adm.HOURLY,3);
)

OUS_ADM.UPDATE_SCHEDULE('marketing site schedule', OUS_ADM.RENAME, 
       'marketing site');

OUS_ADM.UPDATE_SCHEDULE('marketing site', OUS_ADM.ADD_DS, 
       'marketing primary site');

OUS_ADM.UPDATE_SCHEDULE('marketing site', ous_adm. DISABLE_SCHEDULE);

OUS_ADM.UPDATE_SCHEDULE('marketing site', 
       OUS_ADM.RECRAWL_POLICY, ous_adm.RECRAWL_ON_EVERYTHING);

In this example, 1001 is the ID of a remote crawler:

OUS_ADM.UPDATE_SCHEDULE('marketing site', ous_adm.CRAWLER_ID, 1001);

Crawler Configuration APIs

This section provides reference information for using the crawler configuration APIs.

SET_ADMIN_READONLY

Use this procedure to prevent a crawler configuration setting from being modified from the administration GUI page. This procedure is useful when a setting, such as the location of a cache directory, should not be controlled by the administration GUI, for example, when employees who manage the server do not manage the Oracle Ultra Search.

Syntax

OUS_ADM.SET_ADMIN_READONLY (
 config_name IN NUMBER,
 read_only   IN NUMBER DEFAULT YES,
 crawler_id  IN NUMBER DEFAULT LOCAL_CRAWLER
);

config_name

The name of the crawler configuration setting. Possible values are:

Configuration Name	Description
`CC_CACHE_DIRECTORY`	crawler cache directory path
`CC_CACHE_SIZE`	size of the cache in megabytes
`CC_CACHE_DELETION`	enable/disable removing cache files after indexing
`CC_LOG_DIRECTORY`	crawler log file location

read_only

Set to YES to prevent the setting from being modified from the GUI.

crawler_id

The ID of the crawler whose configuration you are modifying. This may be set either to LOCAL_CRAWLER or the ID of a remote crawler.

Examples

OUS_ADM.SET_ADMIN_READONLY(ous_adm.CC_CACHE_DIRECTORY, ous_adm.YES);

OUS_ADM.SET_ADMIN_READONLY(ous_adm.CC_LOG_DIRECTORY,ous_adm.NO)

IS_ADMIN_READONLY

Use this function to check whether a crawler configuration setting is read-only or not. IS_ADMIN_READONLY returns 1 if the configuration is read-only, 0 if it is not.

Syntax

OUS_ADM.IS_ADMIN_READONLY (
  config_name  IN NUMBER,
  crawler_id   IN NUMBER DEFAULT LOCAL_CRAWLER
) return number;

config_name

The name of the crawler configuration. Possible values are:

Configuration Name	Description
`CC_CACHE_DIRECTORY`	crawler cache directory path
`CC_CACHE_SIZE`	size of the cache in megabytes
`CC_CACHE_DELETION`	enable/disable removing cache files after indexing
`CC_LOG_DIRECTORY`	crawler log file location

crawler_id

The ID of the crawler whose configuration you are checking. This may be set either to LOCAL_CRAWLER or the ID of a remote crawler.

Example

If OUS_ADM.IS_ADMIN_READONLY(ous_adm.CC_CACHE_DIRECTORY) then  …end if;

UPDATE_CRAWLER_CONFIG

Use this procedure to update crawler configurations.

Syntax

OUS_ADM.UPDATE_CRAWLER_CONFIG (
 config_name   IN NUMBER,
 config_value  IN VARCHAR2
);

config_name

The name of the crawler configuration.

config_value

The configuration value. Possible values are:

Configuration Name	Description	Value
`CC_CACHE_DIRECTORY`	crawler cache directory path	any valid directory path
`CC_CACHE_SIZE`	size of the cache in megabytes	any positive integer
`CC_CACHE_DELETION`	enable/disable removing cache files after indexing	`OUS_ADM.DELETE_CACHE` or `OUS_ADM_KEEP_CACHE`
`CC_LOG_DIRECTORY`	crawler log file location	any valid directory path
`CC_DATABASE`	connection string to the backend database	any valid JDBC connection string
`CC_PASSWORD`	database connection password for the crawler to connect to the database	database connect password for the schema that owns the instance
`CC_JDBC_DRIVER`	JDBC driver type used by the local crawler	`OUS_ADM.THIN_DRIVER` or `OUS_ADM.OCI_DRIVER`

Example

OUS_ADM.UPDATE_CRAWLER_CONFIG(ous_adm.CC_CACHE_DIRECTORY,
          '/private1/ultrasearch/cache/');OUS_ADM.UPDATE_CRAWLER_CONFIG(ous_adm.CC_CACHE_SIZE,15);