Oracle8 ConText Cartridge Administrator's Guide
Release 2.4
A63820-01

Library

Product

Contents

Index
 

Prev Next

5
PL/SQL Packages - Administration

This chapter provides reference information for using the PL/SQL packages provided with ConText to administer ConText servers and queues, as well as to obtain product information about ConText.

The topics covered in this chapter are:

CTX_ADM: ConText Administration

The CTX_ADM PL/SQL package is used to manage ConText servers and queues.

CTX_ADM contains the following stored procedures and functions:

Name  Description 

CHANGE_MASK 

Modifies the personality mask for a ConText server 

GET_QUEUE_STATUS 

Returns the status of the specified queue 

RECOVER 

Cleans up database objects for deleted text tables 

SET_QUERY_BUFFER_SIZE 

Increases the size of the pipe used for queries 

SHUTDOWN 

Shuts down a single ConText server or all currently running ConText servers 

UPDATE_QUEUE_STATUS 

Updates the status of the specified queue 

 


CHANGE_MASK

The CHANGE_MASK procedure changes the personality mask of the specified ConText server.

Syntax

CTX_ADM.CHANGE_MASK(name             IN VARCHAR2
                    personality_mask IN VARCHAR2 DEFAULT 'QDM');
name

Specify the name (internal identifier) of the server for which you are changing the personality mask.

personality_mask

Specify the new personality mask that you want to assign to the server. Can be any combination of:

Default is QDM.

Examples

execute ctx_adm.change_mask('DRSRV_8025', 'D')

Notes

The names of all currently running ConText servers can be obtained from the CTX_SERVERS or CTX_ALL_SERVERS views.


GET_QUEUE_STATUS

The GET_QUEUE_STATUS function returns the status of the specified ConText queue.

Syntax

CTX_ADM.GET_QUEUE_STATUS(qname IN VARCHAR2)
RETURN VARCHAR2;
qname

Specify the queue/pipe for which you want to return the status:

Returns

Status of the queue, which is one of the following:

ENABLED

The specified queue is enabled.

DISABLED

The specified queue is disabled.

Examples

declare status varchar2(8);
begin
  status := ctx_adm.get_queue_status('DML_QUEUE');
end;

Notes

A status of DISABLED indicates the queue or pipe is inactive and requests in the queue will not be processed by any of the available ConText servers.

When a queue or pipe has a status of DISABLED, the queue continues to accept requests. The ConText administrator should regularly monitor the status of the queues and pipes to prevent accumulation of requests in disabled queues.

To enable a disabled queue, you must call CTX_ADM.UPDATE_QUEUE_STATUS.


RECOVER

The RECOVER procedure deletes all database objects for text tables that have been deleted without first dropping the index or policies for the tables.

Syntax

CTX_ADM.RECOVER;

Examples

execute ctx_adm.recover

Notes

ConText Servers automatically perform recovery approximately every fifteen minutes. CTX_ADM.RECOVER provides a method for users to manually perform recovery on command.


SET_QUERY_BUFFER_SIZE

The SET_QUERY_BUFFER_SIZE procedure sets the size of the database pipe used for queries.

Syntax

CTX_ADM.SET_QUERY_BUFFER_SIZE(buffer_size IN NUMBER);
buffer_size

Specify the size, in bytes, of the query buffer.

Examples

execute ctx_adm.set_query_buffer_size(100000);

Notes

The default size of the buffer is 8192 bytes.

CTX_ADM.SET_QUERY_BUFFER_SIZE can only be used to increase the size of the buffer from the default size.


SHUTDOWN

The SHUTDOWN procedure shuts down the specified ConText server.

Syntax

CTX_ADM.SHUTDOWN(name   IN VARCHAR2 DEFAULT 'ALL',
                 sdmode IN NUMBER   DEFAULT NULL);
name

Specify the name (internal identifier) of the ConText server to shutdown.

Default is ALL.

sdmode

Specify the shutdown mode for the server:

Default is NULL.

Examples

execute ctx_adm.shutdown('DRSRV_3321', 1)

Notes

If you do not specify a ConText server to shut down, CTX_ADM.SHUTDOWN shuts down all currently running ConText servers.

The names of all currently running ConText servers can be obtained from the CTX_SERVERS view.


UPDATE_QUEUE_STATUS

The UPDATE_QUEUE_STATUS procedure is used to change the status of the specified ConText queue (Text, DML, or Services).

For example, the GET_QUEUE_STATUS returns a status of DISABLED for one of the queues. Once the error that caused the queue to become disabled is cleared, UPDATE_QUEUE_STATUS can be called with an action of ENABLE_QUEUE to reactivate the queue.

UPDATE_QUEUE_STATUS can also be used to control request processing in the system. When you disable a queue, you prevent any currently running ConText servers from picking up queued requests until you enable the queue.

Syntax

CTX_ADM.UPDATE_QUEUE_STATUS(qname   IN VARCHAR2,
                            qstatus IN VARCHAR2 DEFAULT ENABLE_QUEUE);
qname

Specify the queue or pipe for which you want to return the status:

qstatus

Specify the action to perform on the queue:

Default is ENABLE_QUEUE.

Examples

execute ctx_adm.update_queue_status(ctx_adm.dml_queue,ctx_adm.enable_queue)

Notes

A queue with a status of DISABLED will remain inactive until it is enabled using UPDATE_QUEUE_STATUS; however, the queue will continue to accept requests. The ConText administrator should regularly monitor the status of the queues and pipes to prevent accumulation of requests in disabled queues.

Both qname and qstatus must be fully qualified with the PL/SQL package name (CTX_ADM) as shown in the examples.

CTX_SVC: Services Queue Administration

The CTX_SVC PL/SQL package is used to query requests in the Services Queue and to manage the queue.

CTX_SVC contains the following stored procedures and functions:

Name  Description 

CANCEL 

Removes a pending request from the Services Queue 

CANCEL_ALL 

Removes all pending requests from the Services Queue 

CANCEL_USER 

Removes a pending request from the Services Queue for the current user 

CLEAR_ALL_ERRORS 

Removes all requests with an error status from the Services Queue 

CLEAR_ERROR 

Removes a request with an error status from the Services Queue 

CLEAR_INDEX_ERRORS 

Removes errored indexing requests from the Services Queue 

CLEAR_LING_ERRORS 

Removes errored Linguistics requests from the Services Queue 

REQUEST_STATUS 

Returns the status of a request in the Services Queue 

 


CANCEL

The CANCEL procedure removes a request with a status of PENDING from the Services Queue.

Syntax

CTX_SVC.CANCEL(request_handle IN NUMBER);
request_handle

Specify the handle, returned by CTX_LING.SUBMIT, of the service request to remove.

Examples

execute ctx_svc.cancel(3321)

Notes

Requests with a status other than pending in the Services Queue cannot be removed using CTX_SVC.CANCEL. To cancel requests that ConText has not yet entered into the Services Queue, use CTX_LING.CANCEL.
 

See Also: 

For more information about the CTX_LING PL/SQL package, see Oracle8 ConText Cartridge Application Developer's Guide

 
 

CANCEL_ALL

The CANCEL_ALL procedure removes all requests with a status of PENDING from the Services Queue.

Syntax

CTX_SVC.CANCEL_ALL;

Examples

execute ctx_svc.cancel_all

CANCEL_USER

The CANCEL_USER procedure removes all requests with a status of PENDING for the current user from the Services Queue.

Syntax

CTX_SVC.CANCEL_USER;

Examples

execute cancel

CLEAR_ALL_ERRORS

The CLEAR_ALL_ERRORS procedure removes all requests (text indexing, theme indexing, and linguistics) that have a status of ERROR in the Services Queue.

Syntax

CTX_SVC.CLEAR_ALL_ERROR;

Examples

execute ctx_svc.clear_all_errors

CLEAR_ERROR

The CLEAR_ERROR procedure can be used to remove a request with a status of ERROR from the Services Queue.

Syntax

CTX_SVC.CLEAR_ERROR(request_handle IN NUMBER);
request_handle

Specify the handle, returned by CTX_LING.SUBMIT, of the errored service request to remove.
 

See Also: 

For more information about SUBMIT and the CTX_LING PL/SQL package, see Oracle8 ConText Cartridge Application Developer's Guide

 
 

Examples

execute clear_error(214)

Notes

If you call CLEAR_ERROR with a 0 (zero) value for request_handle, all requests with a status of ERROR in the Services Queue are removed.

Use the CTX_SVC.REQUEST_STATUS function to return the status of a request in the Services Queue.


CLEAR_INDEX_ERRORS

The CLEAR_INDEX_ERRORS procedure removes all indexing requests that have a status of ERROR in the Services Queue.

Syntax

CTX_SVC.CLEAR_INDEX_ERROR;

Examples

execute ctx_svc.clear_index_errors

CLEAR_LING_ERRORS

The CLEAR_LING_ERRORS procedure removes all Linguistics requests that have a status of ERROR in the Services Queue.

Syntax

CTX_SVC.CLEAR_LING_ERROR;

Examples

execute ctx_svc.clear_ling_errors

REQUEST_STATUS

The REQUEST_STATUS function returns the status of a request in the Services Queue.

Syntax

CTX_SVC.REQUEST_STATUS(request_handle  IN  NUMBER,
                       timestamp       OUT DATE,
                       errors          OUT VARCHAR2)
RETURN VARCHAR2;
request_handle

Specify the handle of the service request, as returned by CTX_LING.SUBMIT.

timestamp

Returns the time at which request was submitted.

errors

Returns the error message stack for the request. The message stack is returned only if the status of the request is ERROR.
 

See Also: 

For more information about SUBMIT and the CTX_LING PL/SQL package, see Oracle8 ConText Cartridge Application Developer's Guide

 
 

Returns

Status of the request, which is one of the following:

PENDING

The request has not yet been picked up by a ConText server.

RUNNING

The request is being processed by a ConText server.

ERROR

The request encountered an error (see errors argument).

SUCCESS

The request completed successfully.

Examples

declare status varchar2(10);
declare timestamp date;
declare errors varchar2(60);
begin
   status := ctx_svc.request_status(3461,timestamp,errors);
   dbms_output.put_line(status,timestamp,substr(errors,1,20);
end;

Notes

Specifying an invalid value for request_handle causes CTX_SVC.REQUEST_STATUS to return a status of SUCCESS.

CTX_INFO: Product Information

The CTX_INFO PL/SQL package is used to obtain information about the installed version of ConText.

CTX_INFO contains the following stored procedures and functions:

Name  Description 

GET_INFO 

Returns the status and version number for the installed ConText 

GET_STATUS 

Returns the status of ConText 

GET_VERSION 

Returns the version number for the installed ConText 

 


GET_INFO

The GET_INFO procedure calls the GET_VERSION and GET_STATUS functions in CTX_INFO to return version and status information for ConText.

Syntax

CTX_INFO.GET_INFO(product IN  VARCHAR2,
                  version OUT VARCHAR2,
                  status  OUT VARCHAR2);
product

Specify the product code for which information is returned. Currently, the only valid value for product is OCO.

version

Specify the version of the product.

status

Specify the status of the product.

Examples

set serveroutput on

declare
  ver varchar2(20);
  stat varchar2(20);
begin
  ctx_info.get_info('OCO', ver, stat);
  dbms_output.put_line ('Version is '||ver);
  dbms_output.put_line ('Status is '||stat);
end;

GET_STATUS

The GET_STATUS function returns the product status for ConText.

Syntax

CTX_INFO.GET_STATUS(product IN VARCHAR2)
RETURN VARCHAR2;
product

Specify the product for which a status returned. Currently, the only valid value for product is OCO.

Returns

The product status for ConText.

Examples

set serveroutput on

declare
  stat varchar2(60);
begin
  stat := ctx_info.get_status('OCO');
  dbms_output.put_line ('Status is '||stat);
end;

GET_VERSION

The GET_VERSION function returns the version number for ConText.

Syntax

CTX_INFO.GET_VERSION(product IN VARCHAR2)
RETURN NUMBER;
product

Specify the product for which a version number is returned. Currently, the only valid value for product is OCO.

Returns

The version number for ConText.

Examples

set serveroutput on

declare
  ver varchar2(20);
begin
  ver := ctx_info.get_version('OCO');
  dbms_output.put_line ('Version is '||ver);
end;



Prev

Next
 
Oracle
Copyright © 1998 Oracle Corporation. 
All Rights Reserved. 

Library

Product

Contents

Index