Skip Headers
Oracle® Ultra Search Administrator's Guide
11g Release 1 (11.1)

B28330-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

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