DBMS_AQADM

功能描述

Vastbase G100在Oracle兼容模式下支持内置包DBMS_AQADM的部分接口功能，该内置包提供了查询和设置会话相关状态的方法。

注意事项

该功能仅在数据库兼容模式为Oracle时能够使用（即创建DB时DBCOMPATIBILITY='A'），在其他数据库兼容模式下不能使用该特性。

常量

该内置包包含以下常量：

参数	常量	说明
message grouping	DBMS_AQADM NONE(0)	用于为队列指定消息分组。
message grouping	DBMS_AQADM TRANSACTIONAL(1)	此常量已定义，但功能不支持。
queue_type	DBMS_AQADM NORMAL_QUEUE(0)	与create_queue函数一起使用，用于指定queue_type。
	DBMS_AQADM EXCEPTION_QUEUE(1)	与create_queue一起使用，用于指定queue_type。注意：异常队列支持出队操作。
	DBMS_AQADM NON_PERSISTENT_QUEUE(2)	此常量已定义，但功能不支持。
retention_time	0,1,2...	与create_queue一起使用，用于指定retention_time。
retention_time	DBMS_AQADM INFINITE(-1)	与create_queue一起使用，用于指定retention_time。
aq$_purge_options_t.delivery_mode	DBMS_AQADM PERSISTENT(0)	存储在表中的信息。
	DBMS_AQADM BUFFERED(1)	此常量已定义，但功能不支持。
	DBMS_AQADM PERSISTENT_OR_BUFFERED(2)	此常量已定义，但功能不支持。

子程序

该内置包当前包含以下子程序：

函数	描述
CREATE_QUEUE_TABLE	创建队列表。
DROP_QUEUE_TABLE	删除队列表。
ALTER_QUEUE_TABLE	修改现有队列表。
PURGE_QUEUE_TABLE	从队列中删除消息。
CREATE_QUEUE	在现有队列表中创建队列。
DROP_QUEUE	删除队列。
ALTER_QUEUE	修改现有队列。
START_QUEUE	为指定队列启用入队或出队。
STOP_QUEUE	在指定队列禁止入队或出队。

CREATE_QUEUE_TABLE

语法格式

CREATE_QUEUE_TABLE(
queue table         IN VARCHAR2,
queue_payload_type  IN VARCHAR2
storage_clause      IN VARCHAR2         DEFAULT NULL,
sort list           IN VARCHAR2         DEFAULT NULL,
multiple_consumers  IN BOOLEAN          DEFAULT FALSE,
message_grouping    IN BINARY_INTEGER   DEFAULT NONE,
comment             IN VARCHAR2         DEFAULT NULL,
auto_commit         IN BOOLEAN          DEFAULT TRUE,
primary_instance     IN BINARY_INTEGER  DEFAULT 0,
secondary_instance  IN BINARY_INTEGER   DEFAULT 0,
compatible          IN VARCHAR2         DEFAULT NULL,
secure              IN BOOLEAN          DEFAULT FALSE)

参数说明

queue table

即将创建的队列表名称。
queue_payload_type

存储在队列表中的用户自定义数据类型。
storage_clause

队列表的存储参数，其被包含在创建队列表的建表语句中。
- 当前版本只强制实施TABLESPACE选项，为了实现兼容性而支持其他选项，但被忽略。
- 可使用TABLESPACE子句指定将在其中创建表的表空间名称。
storage_clause可以是以下一项或多项：
```
TABLESPACE tablespace_name |
PCTFREE integer |
PCTUSED integer |
INITRANS integer |
MAXTRANS integer |
STORAGE storage option 
```
其中storage option可以是以下一项或多项：
```
MINEXTENTS integer |
MAXEXTENTS integer |
PCTINCREASE integer |
INITIAL size_clause |
NEXT |
FREELISTS integer |
OPTIMAL size_clause |
BUFFER_POOL {KEEP|RECYCLE|DEFAULT}
```
sort_list

控制队列的出队顺序。指定将用于对队列进行升序排序的列名称。当前可取值如下：
- enq_time,priority
- priority,enq_time
- priority
- enq_time
若未指定本字段，则所有队列按照入队时间升序排列，满足先进先出机制。
multiple_consumers

如果指定，则multiple_consumers必须为FALSE。
message_grouping

如果指定，则message_grouping必须为NONE。
comment

用户自定义的列表描述。
auto_commit

为了实现兼容性而支持本参数，但被忽略。
primary_instance

为了实现兼容性而支持本参数，但被忽略。
secondary_instance

为了实现兼容性而支持本参数，但被忽略。
compatible

为了实现兼容性而支持本参数，但被忽略。
secure

为了实现兼容性而支持本参数，但被忽略。

示例

1、创建类型。

CREATE TYPE work_order as object (name VARCHAR2(20));

2、创建队列表。

declare 
begin 
DBMS_AQADM.CREATE_QUEUE_TABLE 
(queue_table => 'work_order_table', 
queue_payload_type => 'work_order', 
comment => 'Work order message queue table'); 
END; 
/

3、再次创建队列表时报错队列表已存在。

declare
begin
DBMS_AQADM.CREATE_QUEUE_TABLE
(queue_table => 'work_order_table',
queue_payload_type => 'work_order',
comment => 'Work order message queue table');
END;
/

返回信息如下：

ERROR:  call dbms_aqadm.create_queue_table failed.
ECODE:  P0001.
REASON: Queue table work_order_table has existed!
CONTEXT:  SQL statement "CALL dbms_aqadm.create_queue_table(queue_table => 'work_order_table',queue_payload_type => 'work_order',comment => 'Work order message queue table')"
PL/pgSQL function inline_code_block line 3 at PERFORM

4、查询所有队列表，列式展示查询结果。

\x
select * from all_dequeue_queues;

查询结果为：

-[ RECORD 1 ]---+-----------------------
owner           | public
name            | aq$_work_order_table_e
queue_table     | work_order_table
qid             | 2
queue_type      | EXCEPTION_QUEUE
max_retries     | 0
retry_delay     | 0
enqueue_enabled | NO
dequeue_enabled | NO
retention       | 0
user_comment    | exception queue
network_name    |

5、删除队列表并查询。

declare 
begin 
DBMS_AQADM.drop_QUEUE_TABLE 
(queue_table => 'work_order_table', 
force => TRUE); 
END; 
/ 

select * from all_dequeue_queues;

返回结果为如下，表示查询为空：

(No rows)

DROP_QUEUE_TABLE

语法格式

DROP_QUEUE_TABLE(
queue_table     IN VARCHAR2,
force           IN BOOLEAN      DEFAULT FALSE,
auto_commit     IN BOOLEAN      DEFAULT TRUE)

参数说明

queue_table

即将删除的队列表名称。
force
- FALSE表示如果队列表中存在任何队列则操作失败，默认情况。
- TRUE表示删除队列表时，表中所有队列被自动停止和删除。
auto_commit

为了实现兼容性而支持此参数，但被忽略。

示例

参见CREATE_QUEUE_TABLE的示例。

ALTER_QUEUE_TABLE

语法格式

ALTER_QUEUE_TABLE (
queue_table        IN VARCHAR2,
comment            IN VARCHAR2       DEFAULT NULL,
primary_instance   IN BINARY_INTEGER DEFAULT 0,
secondary_instance IN BINARY_INTEGER DEFAULT 0)

参数说明

queue_table

队列表的名称。
comment

使用comment参数可以提供有关队列表的注释。
primary_instance

为了实现兼容性而支持此参数，但被忽略。
secondary_instance

为了实现兼容性而支持此参数，但被忽略。

示例

1、创建类型和队列表。

CREATE TYPE work_order_1141864 as object (name VARCHAR2(200)); 

call DBMS_AQADM.CREATE_QUEUE_TABLE ( 
queue_table => 'work_order_1141864_1', 
queue_payload_type => 'work_order_1141864', 
storage_clause =>'TABLESPACE pg_default', 
comment =>'sknn');

2、修改不存在的队列表。

call DBMS_AQADM.alter_QUEUE_TABLE(queue_table => 'work_order_1141655_1',comment=> '修改后的注释',primary_instance =>1, secondary_instance =>1);

返回报错结果如下：

ERROR:  call dbms_aqadm.alter_queue_table failed.
ECODE:  P0001.
REASON: Queue table work_order_1141655_1 does not exist!

3、修改存在的队列表。

call DBMS_AQADM.alter_QUEUE_TABLE(queue_table => 'work_order_1141864_1',comment=> '修改后的注释',primary_instance =>1, secondary_instance =>1);

返回结果为如下，表示修改队列表成功：

 alter_queue_table
-------------------

(1 row)

PURGE_QUEUE_TABLE

语法格式

PURGE_QUEUE_TABLE(
queue_table     IN VARCHAR2,
purge_condition IN VARCHAR2,
purge_options   IN aq$_purge_options_t)

参数说明

queue_table

指定待删除消息的队列表的名称。
purge_condition

指定清除队列表时的清除条件，清除条件必须是一个WHERE子句（不带where关键字）。清除条件是基于视图aq\$队列表名中的列，并且使用qtview来限定aq\$队列表名中的列。如果清除队列表中所有队列，则此参数设置为'' 或NULL。
purge_options

purge_options是aq$_purge_options_t类型的对象。aq$_purge_options_t类型指定可用于清除队列表的选项。
- 创建aq$_purge_options_t类型的语法格式：
```
CREATE TYPE AQ$_PURGE_OPTIONS_T IS RECORD (
block  BOOLEAN,
delivery_mode  INTEGER );
```
- 属性说明：
  - block：boolean类型。在表中所有队列上是否持有排他锁。取值包括如下：
    
    FALSE（默认值），表示表中所有队列上不存在排他锁。不阻塞并发的入队和出队，但可能造成清除操作失败。
    
    TRUE，表示在进行当前清除操作时，在队列表的所有队列持有排他锁，并发的入队和出队将被阻塞，但清除操作总是可以成功执行。
  - delivery_mode：Integer类型。指定将清除的消息类型。唯一可接受的值为DBMS_AQADM.PERSISTENT。

示例

1、创建类型和队列表。

CREATE TYPE work_order_1141914 as object (id int,name VARCHAR2(200));

call DBMS_AQADM.CREATE_QUEUE_TABLE (
queue_table => 'work_order_1141914_1',
queue_payload_type => 'work_order_1141914');

2、创建普通队列。

call DBMS_AQADM.CREATE_QUEUE ( queue_name => 'workorder_1141914', queue_table => 'work_order_1141914_1', comment => 'This queue contains pending work orders.',dependency_tracking=>false,auto_commit => true);
call DBMS_AQADM.CREATE_QUEUE ( queue_name => 'workorder_1141914_1', queue_table => 'work_order_1141914_1', comment => 'This queue contains pending work orders.',dependency_tracking=>false,auto_commit => true);
call DBMS_AQADM.CREATE_QUEUE ( queue_name => 'workorder_1141914_2', queue_table => 'work_order_1141914_1', comment => 'This queue contains pending work orders.',dependency_tracking=>false,auto_commit => true);
call DBMS_AQADM.CREATE_QUEUE ( queue_name => 'workorder_1141914_3', queue_table => 'work_order_1141914_1', comment => 'This queue contains pending work orders.',dependency_tracking=>false,auto_commit => true);

3、启动队列。

call DBMS_AQADM.start_QUEUE(queue_name => 'workorder_1141914');
call DBMS_AQADM.start_QUEUE(queue_name => 'workorder_1141914_1');
call DBMS_AQADM.start_QUEUE(queue_name => 'workorder_1141914_2');
call DBMS_AQADM.start_QUEUE(queue_name => 'workorder_1141914_3');

4、在匿名块中调用DBMS_AQ.enqueue函数，并查询类型的数量。

declare
c1 dbms_AQ.enqueue_options_t;
c2 dbms_AQ.message_properties_t;
v1 raw(16);
o1 work_order_1141914;
BEGIN
o1:=work_order_1141914(1,'message');
dbms_AQ.enqueue(queue_name => 'workorder_1141914',enqueue_options => c1,message_properties => c2,payload => o1,msgid => v1);
dbms_AQ.enqueue(queue_name => 'workorder_1141914_1',enqueue_options => c1,message_properties => c2,payload => o1,msgid => v1);
dbms_AQ.enqueue(queue_name => 'workorder_1141914_2',enqueue_options => c1,message_properties => c2,payload => o1,msgid => v1);
dbms_AQ.enqueue(queue_name => 'workorder_1141914_3',enqueue_options => c1,message_properties => c2,payload => o1,msgid => v1);
end;
/

select count(*) from aq$work_order_1141914_1;

查询结果为：

 count
-------
     4
(1 row)

5、在匿名块中调用DBMS_AQADM.purge_queue_table函数，并查询类型的数量。

DECLARE
p1 dbms_aqadm.aq$_purge_options_t;
BEGIN
dbms_aqadm.purge_queue_table(queue_table => 'work_order_1141914_1',purge_condition=> '',purge_options=>p1);
end;
/

select count(*) from aq$work_order_1141914_1;

查询结果为如下，表示已完成清理所有信息：

 count
-------
     0
(1 row)

CREATE_QUEUE

语法格式

CREATE_QUEUE(
queue_name            IN VARCHAR2,
queue_table           IN VARCHAR2,
queue_type            IN BINARY_INTEGER    DEFAULT 0,
max_retries           IN NUMBER            DEFAULT 0,
retry_delay           IN NUMBER            DEFAULT 0,
retention_time        IN NUMBER            DEFAULT 0,
dependency_tracking   IN BOOLEAN           DEFAULT FALSE,
comment               IN VARCHAR2          DEFAULT NULL,
auto_commit           IN BOOLEAN           DEFAULT TRUE)

参数说明

queue_name

即将被创建的队列名称，在schema内是唯一的。
queue_table

队列所属队列表名称。
queue_type

队列的类型。queue_type取值如下：
- DBMS_AQADM.NORMAL_QUEUE：此值指定普通队列（默认值）。
- DBMS_AQADM.EXCEPTION_QUEUE：此值指定新队列是异常队列。异常队列仅支持出队操作。
max_retries

一个队列消息使用REMOVE模式出队时尝试的最大次数。当应用在执行dequeue后发生rollback则对应增加RETRY_COUNT。当失败的尝试次数达到max_retries指定的值之后，消息移动到异常队列。

默认值为0。
retry_delay

延迟时间，单位为秒，默认值为0，表示消息应尽快被重试。如果max_retries设置为0，则此参数不生效。
retention_time

指定消息在出队之后在队列表中保留的时间长度。单位：秒。
- 指定为默认值0时，表示消息在出队之后不应保留。
- NUMBER表示保留的秒数。
- 指定为INFINITE时，表示永久保留消息。
dependency_tracking

保留供将来使用，默认是FALSE，不允许为TRUE。
comment

用户指定的队列说明。
auto_commit

为了实现兼容性而支持此参数，但被忽略。

示例

1、创建类型和队列表。

CREATE TYPE work_order_1141864 as object (name VARCHAR2(200)); 

call DBMS_AQADM.CREATE_QUEUE_TABLE ( 
queue_table => 'work_order_1141864_1', 
queue_payload_type => 'work_order_1141864', 
storage_clause =>'TABLESPACE pg_default', 
comment =>'sknn');

2、创建普通队列，并查询队列信息。

call DBMS_AQADM.CREATE_QUEUE ( queue_name => 'workorder_1141864', queue_table => 'work_order_1141864_1', comment => 'This queue contains pending work orders.',dependency_tracking=>false,auto_commit => true); 

select max_retries,retry_delay from all_dequeue_queues where name = 'workorder_1141864';

查询队列信息结果如下：

 max_retries | retry_delay
-------------+-------------
             |           0
(1 row)

3、修改max_retries参数。

call DBMS_AQADM.alter_queue ( queue_name => 'workorder_1141864', max_retries => 4);

4、查询队列信息。

select max_retries,retry_delay from all_dequeue_queues where name = 'workorder_1141864';

结果显示为如下，表示成功修改max_retries参数。

 max_retries | retry_delay
-------------+-------------
           4 |           0
(1 row)

5、删除队列。

call DBMS_AQADM.drop_queue ( queue_name => 'workorder_1141864', auto_commit => true);

返回结果为如下，表示删除队列成功：

 drop_queue
-------------

(1 row)

DROP_QUEUE

语法格式

DROP_QUEUE(
queue_name  IN VARCHAR2,
auto_commit IN BOOLEAN      DEFAULT TRUE)

参数说明

queue_name

即将删除的队列名称
auto_commit

为了实现兼容性而支持此参数，但被忽略。

示例

删除队列参见DBMS_AQADM.start_queue的示例。

ALTER_QUEUE

语法格式

ALTER_QUEUE(
queue_name         IN VARCHAR2,
max_retries        IN NUMBER      DEFAULT NULL,
retry_delay        IN NUMBER      DEFAULT NULL,
retention_time     IN NUMBER      DEFAULT NULL,
auto_commit        IN BOOLEAN     DEFAULT TRUE,
comment            IN VARCHAR2    DEFAULT NULL)

参数说明

queue_name

即将修改的队列名称
max_retries

默认值为0。表示一个队列消息使用REMOVE模式出队时尝试的最大次数。当应用在执行dequeue后发生rollback则对应增加RETRY_COUNT。当失败的尝试次数达到max_retries指定的值之后，消息移动到异常队列。
retry_delay

延迟时间，单位为秒，默认值为0，表示消息应尽快被重试。如果max_retries设置为0，则此参数不生效。
retention_time

指定消息在出队之后在队列表中保留的时间长度。单位：秒。
- 指定为默认值0时，表示消息在出队之后不应保留。
- NUMBER表示保留的秒数
- 指定为INFINITE时，表示永久保留消息。
auto_commit

为了实现兼容性而支持此参数，但被忽略。
comment

用户指定的队列说明，起到注释的作用。

示例

参见DBMS_AQADM.create_queue的示例。

START_QUEUE

语法格式

START_QUEUE(
queue_name      IN VARCHAR2,
enqueue         IN BOOLEAN    DEFAULT TRUE,
dequeue         IN BOOLEAN    DEFAULT TRUE)

参数说明

queue_name

指定要启动的队列的名称。
enqueue
- 指定TRUE（默认）时，启用排队。
- 指定FALSE时，保持当前设置不变。
dequeue
- 指定TRUE（默认）时，启用出队。
- 指定FALSE时，保持当前设置不变。

示例

1、创建类型和队列表。

CREATE TYPE work_order_1141927 as object (name VARCHAR2(200));

call DBMS_AQADM.CREATE_QUEUE_TABLE (
queue_table => 'work_order_1141927_1',
queue_payload_type => 'work_order_1141927',
storage_clause =>'TABLESPACE pg_default',
comment =>'sknn');

2、创建普通队列。

call DBMS_AQADM.CREATE_QUEUE ( queue_name => 'workorder_1141927', queue_table => 'work_order_1141927_1', comment => 'This queue contains pending work orders.',dependency_tracking=>false,auto_commit => true);

3、调用start_queue函数。

call dbms_AQADM.start_queue(queue_name => 'workorder_1141927');

返回信息如下，表示函数执行成功：

 start_queue
-------------

(1 row)

4、删除队列提示未停止。

call DBMS_AQADM.DROP_QUEUE(queue_name => 'workorder_1141927');

显示信息如下，报错表示队列未停止，则不能删除：


ERROR:  call dbms_aqadm.drop_queue failed.
ECODE:  P0001.
REASON: Cannot delete queue workorder_1141927 because the queue has not been stopped!

5、停止队列后删除。

call dbms_AQADM.stop_queue(queue_name => 'workorder_1141927');
call DBMS_AQADM.DROP_QUEUE(queue_name => 'workorder_1141927');

返回结果如下，分别表示成功停止队列和删除队列：

 stop_queue
------------

(1 row)

 drop_queue
------------

(1 row)

STOP_QUEUE

语法格式

STOP_QUEUE(
queue_name    IN VARCHAR2,
enqueue       IN BOOLEAN      DEFAULT TRUE,
dequeue       IN BOOLEAN      DEFAULT TRUE,
wait          IN BOOLEAN      DEFAULT TRUE)

参数说明

queue_name

指定要停止的队列的名称。
enqueue
- 指定TRUE（默认）时，禁用排队。
- 指定FALSE时，保持当前设置不变。
dequeue
- 指定TRUE（默认）时，禁用出队。
- 指定FALSE时，保持当前设置不变。
wait
- 指定为TRUE时，表示服务器等待任何未完成的事务完成，然后再应用指定的更改。在等待停止队列时，在指定队列中不允许任何事务排队或取消排队。
- 指定为FALSE时，立即停止队列。

示例

参见DBMS_AQADM.start_queue的示例。

VastbaseG100

DBMS_AQADM

功能描述

注意事项

常量

子程序

CREATE_QUEUE_TABLE

DROP_QUEUE_TABLE

ALTER_QUEUE_TABLE

PURGE_QUEUE_TABLE

CREATE_QUEUE

DROP_QUEUE

ALTER_QUEUE

START_QUEUE

STOP_QUEUE

弹框头部