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:

The following tables show the contents of each API group.

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