Oracle8 ConText Cartridge Administrator's Guide Release 2.3 A58165-01 |
Library | Product | Contents | Index

# 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
- CTX_SVC: Services Queue Administration
- CTX_INFO: Product Information

## 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:

- R (Loader)
- Q (Query)
- D (DDL)
- M (DML)
- L (Linguistic)

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:

- TEXT_QUEUE (DDL and Query pipes)
- DML_QUEUE
- SERVICES_QUEUE

### 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:

- 0 or NULL (Normal)
- 1 (Immediate)
- 2 (Abort)

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:

- TEXT_QUEUE (DDL and Query pipes)
- DML_QUEUE
- SERVICES_QUEUE qstatus

Specify the action to perform on the queue:

- DISABLE_QUEUE
- ENABLE_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

    declare
    version varchar2(20);
    status varchar2(20);
    begin
      ctx_info.get_info('CTX_INFO.OCO', :version, :status);
      dbms_output.put_line ('OCO version is '||version||');
      dbms_output.put_line ('OCO status is '||status||');
    end;

### Notes

product must be fully qualified with the PL/SQL package name (CTX_INFO) as shown in the examples.

## 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

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

### Notes

product must be fully qualified with the PL/SQL package name (CTX_INFO) as shown in the example.

## GET_VERSION

The GET_VERSION function returns the version number for the version of 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

    declare
    version number;
    begin
      version := ctx_info.get_version('CTX_INFO.OCO');
      dbms_output.put_line ('OCO version is '||version||');
    end;

### Notes

product must be fully qualified with the PL/SQL package name (CTX_INFO) as shown in the example.

Prev | Next
| Copyright © 1997 Oracle Corporation. All Rights Reserved. |
Library | Product | Contents | Index