Oracle® Ultra Search Administrator's Guide
10g Release 2 (10.1.2) Part No. B14041-01 |
|
Previous |
Next |
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.
Table 11-1 shows the Instance-Related APIs.
Table 11-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 11-2 shows the Schedule-Related APIs.
Table 11-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 11-3 shows the Crawler Configuration APIs.
Table 11-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 |
This section provides reference information for using the instance-related APIs.
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, );
The name of the instance.
The name of the schema.
The password for the schema.
The Oracle Text index lexer preference.
The Oracle Text index stoplist preference.
The Oracle Text index datastore preference.
If OUS_ADM
is set to YES
, create an instance for the snapshot.
Example
OUS_ADM.CREATE_INSTANCE('Scott instance','scott','tiger');
Use this procedure to drop an Oracle Ultra Search instance.
Syntax
OUS_ADM.DROP_INSTANCE( inst_name IN VARCHAR2 );
The name of the instance to drop.
Example
OUS_ADM.DROP_INSTANCE('Scott instance')
Use this procedure to grant instance administrator privileges to the specified user either for the current instance or all 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 );
The name of the user to whom the administrator privilege should be assigned.
The user type (OUS_ADM.DB_USER
: database user, OUS_ADM.LDAP_USER
: lightweight single sign-on
user).
The scope of the granting; CURRENT_INSTANCE
or ALL_INSTANCE
.
Options for granting privileges: NO_OPTION
or WITH_GRANT
, which allows the grantee to grant the privilege to other users.
Example
OUS_ADM.GRANT_ADMIN('scott',ous_adm.DB_USER, ous_adm.ALL_INSTANCE);
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 );
The name of the user whose privileges are to be revoked.
The user type (OUS_ADM.DB_USER
: database user, OUS_ADM.LDAP_USER
: lightweight single sign-on
user).
The scope of the granting; CURRENT_INSTANCE
or ALL_INSTANCE
.
Example
OUS_ADM.REVOKE_ADMIN('scott',ous_adm.DB_USER);
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 set.
OUS_ADM.SET_INSTANCE( inst_name IN VARCHAR2 );
The name of the instance to set.
In the second form, you specify the ID of the instance to set.
OUS_ADM.SET_INSTANCE( inst_id IN NUMBER );
The ID of the instance to set.
Example
OUS_ADM.SET_INSTANCE('Scott Instance');
This section provides reference information for using the schedule related APIs.
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;
The name of the schedule to create.
The schedule interval. This is a string generated from the OUS_INTERVAL function.
The crawl mode can be REGULAR_CRAWL
, CRAWL_ONLY
, or INDEX_ONLY
.
The recrawl condition can be RECRAWL_WHEN_MODIFIED
or RECRAWL_ON_EVERYTHING
.
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);
Use this procedure to drop a crawler schedule.
Syntax
OUS_ADM.DROP_SCHEDULE ( name IN VARCHAR2 );
The name of the schedule to drop.
Example
OUS_ADM.DROP_SCHEDULE('marketing site schedule');
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;
The schedule interval type. This allowed values are defined as package constants: HOURLY
, DAILY
, WEEKLY
, MONTHLY
, and MANUAL
.
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.
The schedule's launching hour, in 24-hour format, where 1 represents 1 AM. Not used for HOURLY
and MANUAL
schedules.
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);
Use this procedure to run, resume, or stop a schedule.
Syntax
OUS_ADM.SET_SCHEDULE ( name IN VARCHAR2, operation IN NUMBER );
The name of the schedule.
This may be EXECUTE
, RESUME
, or STOP
.
Example
OUS_ADM.SET_SCHEDULE('marketing site schedule', ous_adm.EXECUTE);
Use this procedure to update a crawler schedule.
Syntax
OUS_ADM.UPDATE_SCHEDULE ( name IN VARCHAR2, operation IN NUMBER, value IN VARCHAR2 DEFAULT null );
The name of the schedule to update.
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 allowed include ENABLE_SCHEDULE
and DISABLE_SCHEDULE
.
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);
This section provides reference information for using the crawler configuration APIs.
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;
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 |
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;
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 from the administration GUI; this might be the case, for example, when the people managing the server machine do not also manage 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 );
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 |
Set to YES
to prevent the setting from being modified from the GUI.
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)
Use this procedure to update crawler configurations.
Syntax
OUS_ADM.UPDATE_CRAWLER_CONFIG ( config_name IN NUMBER, config_value IN VARCHAR2 );
The name of the crawler configuration.
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);