Oracle PLSQL Language- P28

PROCEDURE DBMS_AQ.ENQUEUE q_schema IN VARCHAR2 DEFAULT NULL q_name IN VARCHAR2, corrid IN VARCHAR2 DEFAULT NULL, transactional IN BOOLEAN:= TRUE, priority IN POSITIVE DEFAULT 1, de

The Oracle Library

Navigation

Copyright (c) 2000 O'Reilly & Associates All rights reserved

Previous: C.2

DBMS_ALERT

Appendix CBuilt-In Packages

Next: C.4 DBMS_DDL

C.3 Oracle AQ, the Advanced Queueing Facility

Oracle8 offers the Oracle Advanced Queuing facility (Oracle AQ) which implements deferred

execution of work There are two packages you will use to implement advanced queuing:

DBMS_AQ, which contains the queuing procedures themselves, and DBMS_AQADM, which lets you perform administrative tasks They make extensive use of PL/SQL record structures, as you will see in the individual program interfaces below For more detail on these records and how to

manipulate their contents, see Oracle Built-in Packages

PROCEDURE DBMS_AQ.ENQUEUE

(q_schema IN VARCHAR2 DEFAULT NULL

q_name IN VARCHAR2,

corrid IN VARCHAR2 DEFAULT NULL,

transactional IN BOOLEAN:= TRUE,

priority IN POSITIVE DEFAULT 1,

delay IN DATE DEFAULT NULL,

expiration IN NATURAL:= 0,

relative_msgid IN NUMBER DEFAULT NULL,

seq_deviation IN CHAR DEFAULT A,

exception_queue_schema IN VARCHAR2 DEFAULT NULL,

exception_queue IN VARCHAR2 DEFAULT NULL,

reply_queue_schema IN VARCHAR2 DEFAULT NULL,

reply_queue IN VARCHAR2 DEFAULT NULL,

PROCEDURE DBMS_AQ.DEQUEUE

(q_schema IN VARCHAR2 DEFAULT NULL,

q_name IN VARCHAR2,

msgid IN RAW DEFAULT NULL,

corrid IN VARCHAR2 DEFAULT NULL,

deq_mode IN CHAR DEFAULT `D',

wait_time IN NATURAL DEFAULT NULL,

transactional IN BOOLEAN:= true,

out_msgid OUT NUMBER,

out_corrid OUT VARCHAR2,

priority OUT POSITIVE,

delay OUT DATE,

expiration OUT NATURAL,

retry OUT NATURAL,

exception_queue_schema OUT VARCHAR2,

exception_queue OUT VARCHAR2,

reply_queue_schema OUT VARCHAR2,

reply_queue OUT VARCHAR2,

user_data OUT any_object_type);

C.3.2.1 The

CREATE_QUEUE_TABLE procedure

The CREATE_QUEUE_TABLE procedure creates a queue table A queue table is the named

repository for a set of queues and their messages A queue table may contain numerous queues, each

of which may have many messages But a given queue and its messages may exist in only one queue table The specification is:

PROCEDURE DBMS_AQADM.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);

C.3.2.2 The

DROP_QUEUE_TABLE procedure

The DROP_QUEUE_TABLE procedure drops an existing queue table An error is returned if the queue table does not exist The force parameter specifies whether all existing queues in the queue table are stopped and dropped automatically or manually If manually (i.e., FALSE), then the queue administrator must stop and drop all existing queues within the queue table using the

DBMS_AQADM.STOP_QUEUE and DBMS_AQADM.DROP_QUEUE procedures The

specification is:

PROCEDURE DBMS_AQADM.DROP_QUEUE_TABLE

(queue_table IN VARCHAR2,

force IN BOOLEAN default FALSE,

auto_commit IN BOOLEAN default TRUE);

C.3.2.3 The

CREATE_QUEUE procedure

The CREATE_QUEUE procedure creates a new message queue within an existing queue table An error is returned if the queue table does not exist The required queue_name parameter specifies the name of the new message queue to create All queue names must be unique within the schema The specification is:

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

C.3.2.4 The

ALTER_QUEUE procedure

The ALTER_QUEUE procedure modifies properties of an existing message queue It returns an error

if the message queue does not exist Currently, you can alter only the maximum retries, retry delay, retention time, rentention delay and auto-commit properties; Oracle will augment this list in future releases The specification is:

PROCEDURE DBMS_AQADM.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);

force IN BOOLEAN default FALSE,

auto_commit IN BOOLEAN default TRUE);

C.3.2.6 The

START_QUEUE procedure

The START_QUEUE procedure enables an existing message queue for enqueuing and dequeuing It returns an error if the message queue does not exist The default is to enable both The specification is:

PROCEDURE DBMS_AQADM.START_QUEUE (

queue_name IN VARCHAR2,

enqueue IN BOOLEAN DEFAULT TRUE,

dequeue IN BOOLEAN DEFAULT TRUE);

C.3.2.7 The

STOP_QUEUE procedure

The STOP_QUEUE procedure disables an existing message queue for enqueuing and dequeuing It returns an error if the message queue does not exist The default is to disable both enqueuing and dequeuing The wait parameter specifies whether to wait for outstanding transactions or to return immediately The wait option is highly dependent on outstanding transactions If outstanding

transactions exist, then wait will either hang until the transactions complete or return an error of

ORA-24203, depending on whether the wait parameter is set to true or false The specification is:

PROCEDURE DBMS_AQADM.STOP_QUEUE

(queue_name IN VARCHAR2,

enqueue IN BOOLEAN DEFAULT TRUE,

dequeue IN BOOLEAN DEFAULT TRUE,

wait IN BOOLEAN DEFAULT TRUE);

Previous: C.2

DBMS_ALERT

Oracle PL/SQL Programming, 2nd Edition

Next: C.4 DBMS_DDL

The Oracle Library

Navigation

Copyright (c) 2000 O'Reilly & Associates All rights reserved

Previous: C.3 Oracle AQ,

the Advanced Queueing

Facility

Appendix CBuilt-In Packages

Next: C.5 DBMS_ JOB

C.4 DBMS_DDL

The DBMS_DDL package provides access to some of the SQL DDL statements from within stored procedures

C.4.1 The ALTER_COMPILE procedure

The ALTER_COMPILE procedure can be used to programmatically force a recompile of a stored object The specification is:

PROCEDURE DBMS_DDL.ALTER_COMPILE

(type VARCHAR2,

schema VARCHAR2,

name VARCHAR2);

C.4.2 The ANALYZE_OBJECT procedure

A call to ANALYZE_OBJECT lets you programmatically compute statistics for the specified object The specification is:

estimate_rows NUMBER DEFAULT NULL,

estimate_percent NUMBER DEFAULT NULL);

Previous: C.3 Oracle AQ,

the Advanced Queueing

Facility

Oracle PL/SQL Programming, 2nd Edition

Next: C.5 DBMS_ JOB

C.3 Oracle AQ, the

Advanced Queueing Facility

The Oracle Library

Navigation

Copyright (c) 2000 O'Reilly & Associates All rights reserved

Previous: C.4 DBMS_DDL Appendix C

Built-In Packages

Next: C.6 DBMS_LOB (PL/SQL8 Only)

C.5 DBMS_ JOB

The DBMS_ JOB package provides a way for you to schedule jobs from within the Oracle RDBMS

A job is a call to a single stored procedure You can submit a job to run once or on a recurring basis Once a job has been submitted, you can check on the status of the job by viewing a data dictionary table You can also change the parameters of the job with the CHANGE procedure When you submit

a job, you must provide a string that describes that job to the DBMS_ JOB package and specify a job execution interval

C.5.1 The BROKEN procedure

The Oracle Server considers a job to be broken if it has tried and failed 16 times to run the job At this point, Oracle marks the job as broken and will no longer try to run the job until either (a) you mark the job as fixed or (b) you force the job to execute with a call to the RUN procedure Use the BROKEN procedure to mark the job as fixed and specify the next date on which you want the job to run The specification is:

PROCEDURE DBMS_JOB.BROKEN

(job IN BINARY_INTEGER,

broken IN BOOLEAN,

next_date IN DATE DEFAULT SYSDATE);

C.5.2 The CHANGE procedure

Use the CHANGE procedure to change one or all of the attributes of a job The specification is:

Use the INTERVAL procedure to change the interval for which a queued job is going to run The specification is:

PROCEDURE DBMS_JOB.INTERVAL

(job IN BINARY_INTEGER,

interval IN VARCHAR2);

C.5.4 The ISUBMIT procedure

The ISUBMIT procedure submits a new job with a specified job number to the queue The difference between ISUBMIT and SUBMIT (described later in this section) is that ISUBMIT specifies a job number, whereas SUBMIT returns a job number generated by the DBMS_JOB package The

specification is:

PROCEDURE DBMS_JOB.ISUBMIT

(job IN BINARY_INTEGER,

what IN VARCHAR2,

next_date in DATE DEFAULT SYSDATE

interval IN VARCHAR2 DEFAULT 'NULL',

no_parse in BOOLEAN DEFAULT FALSE);

C.5.5 The NEXT_DATE procedure

Use the NEXT_DATE procedure to change when a queued job is going to run The specification is:

PROCEDURE DBMS_JOB.NEXT_DATE

(job IN BINARY_INTEGER,

next_date IN DATE);

C.5.6 The REMOVE procedure

Use the REMOVE procedure to remove a job from the queue If the job has started execution, you cannot remove it from the queue The specification is:

PROCEDURE DBMS_JOB.REMOVE (job IN BINARY_INTEGER);

C.5.7 The RUN procedure

Use the RUN procedure to force a job to be executed immediately, regardless of the values for

next_date and interval stored in the job queue The specification is:

PROCEDURE DBMS_JOB.RUN (job IN BINARY_INTEGER);

C.5.8 The SUBMIT procedure

The SUBMIT procedure submits jobs to the queue The specification is:

PROCEDURE DBMS_JOB.SUBMIT

(job OUT BINARY_INTEGER,

what IN VARCHAR2,

next_date IN DATE DEFAULT SYSDATE,

interval IN VARCHAR2 DEFAULT 'NULL',

no_parse IN BOOLEAN DEFAULT FALSE);

C.5.9 The USER_EXPORT procedure

The USER_EXPORT procedure is used to extract the job string from a job in the queue The specification is:

PROCEDURE DBMS_JOB.USER_EXPORT

(job IN BINARY_INTEGER,

mycall OUT VARCHAR2);

C.5.10 The WHAT procedure

Use the WHAT procedure to change what a queued job is going to run The specification is:

C.4 DBMS_DDL Book Index C.6 DBMS_LOB (PL/SQL8

Previous: C.5 DBMS_ JOB Appendix C

(dest_lob IN OUT CLOB CHARACTER SET ANY_CS,

src_lob IN CLOB CHARACTER SET DEST_LOB%CHARSET);

offset_1 IN INTEGER := 1,

offset_2 IN INTEGER := 1)

RETURN INTEGER;

FUNCTION DBMS_LOB.COMPARE

(lob_1 IN CLOB CHARACTER SET ANY_CS,

lob_2 IN CLOB CHARACTER SET LOB_1%CHARSET,

(dest_lob IN OUT CLOB CHARACTER SET ANY_CS,

src_lob IN CLOB CHARACTER SET DEST_LOB%CHARSET,

amount IN OUT INTEGER,

PROCEDURE DBMS_LOB.ERASE

(lob_loc IN OUT BLOB,

amount IN OUT INTEGER,

offset IN INTEGER := 1);

PROCEDURE DBMS_LOB.ERASE

(lob_loc IN OUT CLOB CHARACTER SET ANY_CS,

amount IN OUT INTEGER,

Use the filegetname procedure to translate a BFILE locator into its directory alias and filename

components The specification is:

PROCEDURE DBMS_LOB.FILEGETNAME

(file_loc IN BFILE,

dir_alias OUT VARCHAR2,

filename OUT VARCHAR2);

C.6.9 The

FILEISOPEN function

The fileisopen function returns 1 if the BFILE is already open The specification is:

FUNCTION DBMS_LOB.FILEISOPEN (file_loc IN BFILE) RETURN

(file_loc IN OUT BFILE,

open_mode IN BINARY_INTEGER := FILE_READONLY);

C.6.11 The

GETLENGTH function

Use the getlength function to return the length of the specified LOB in bytes or characters, depending

on the type of LOB The specifications are:

FUNCTION DBMS_LOB.GETLENGTH (lob_loc IN BLOB) RETURN

(lob_loc IN CLOB CHARACTER SET ANY_CS,

pattern IN VARCHAR2 CHARACTER SET LOB_LOC%CHARSET,

(lob_loc IN CLOB CHARACTER SET ANY_CS,

amount IN OUT BINARY_INTEGER,

offset IN INTEGER,

buffer OUT VARCHAR2 CHARACTER SET LOB_LOC%CHARSET);

(lob_loc IN OUT CLOB CHARACTER SET ANY_CS,

newlen IN INTEGER);

C.6.16 The

WRITE procedure

Call the write procedure to write a specified number of bytes or characters from a buffer variable into

a LOB at a specified position The specifications are:

PROCEDURE DBMS_LOB.WRITE

(lob_loc IN OUT BLOB,

amount IN OUT BINARY_INTEGER,

offset IN INTEGER,

buffer IN RAW);

PROCEDURE DBMS_LOB.WRITE

(lob_loc IN OUT CLOB CHARACTER SET ANY_CS,

amount IN OUT BINARY_INTEGER,

offset IN INTEGER,

buffer IN VARCHAR2 CHARACTER SET LOB_LOC%CHARSET);

Previous: C.5 DBMS_ JOB Oracle PL/SQL

Programming, 2nd Edition

Next: C.7 DBMS_LOCK

The Oracle Library

Navigation

Copyright (c) 2000 O'Reilly & Associates All rights reserved

Previous: C.6 DBMS_LOB

(PL/SQL8 Only)

Appendix CBuilt-In Packages

Next: C.8 DBMS_MAIL

C.7 DBMS_LOCK

The DBMS_LOCK package provides you with access to the Oracle Lock Management (OLM)

services With OLM, you can request a lock of a particular type, assign it a name that can then be used as a handle to this lock, modify the lock, and even release the lock A lock you create with the DBMS_LOCK package has all the functionality of a lock generated by the Oracle RDBMS, including deadlock detection and view access through SQL*DBA and the relevant virtual tables

C.7.1 The ALLOCATE_UNIQUE procedure

The ALLOCATE_UNIQUE procedure allocates a unique lock handle for the specified lock name The specification is:

PROCEDURE DBMS_LOCK.ALLOCATE_UNIQUE

(lockname IN VARCHAR2,

lockhandle OUT VARCHAR2,

expiration_secs IN INTEGER DEFAULT 864000);

C.7.2 The CONVERT function

The CONVERT function converts a lock from one type or mode to another The specifications are:

The function returns the status of the attempt to change the mode, as shown below:

Invalid lock handle The handle was not found on the DBMS_LOCK_ALLOCATED table

C.7.3 The RELEASE function

The RELEASE function releases the specified lock This specifications are:

FUNCTION DBMS_LOCK.RELEASE (id IN INTEGER) RETURN INTEGER;FUNCTION DBMS_LOCK.RELEASE (lockhandle IN VARCHAR2)

C.7.4 The REQUEST function

The REQUEST function requests a lock of the specified mode The specifications are:

FUNCTION DBMS_LOCK.REQUEST

(id IN INTEGER,

lockmode IN INTEGER DEFAULT X_MODE,

timeout IN NUMBER DEFAULT MAXWAIT,

release_on_commit IN BOOLEAN DEFAULT FALSE)

RETURN INTEGER;

FUNCTION DBMS_LOCK.REQUEST

(lockhandle IN VARCHAR2,

lockmode IN INTEGER DEFAULT X_MODE,

timeout IN NUMBER DEFAULT MAXWAIT,

release_on_commit IN BOOLEAN DEFAULT FALSE)

RETURN integer;

The function returns the status of the attempt to obtain the lock; the codes are identical to those shown above for the convert function

C.7.5 The SLEEP procedure

The SLEEP procedure suspends the current session for a specified period of time (in seconds) The specification is:

PROCEDURE DBMS_LOCK.SLEEP (seconds IN NUMBER);

Previous: C.6 DBMS_LOB

(PL/SQL8 Only)

Oracle PL/SQL Programming, 2nd Edition

Next: C.8 DBMS_MAIL

C.6 DBMS_LOB (PL/SQL8

Only)

The Oracle Library

Navigation

Copyright (c) 2000 O'Reilly & Associates All rights reserved

Previous: C.7

DBMS_LOCK

Appendix CBuilt-In Packages

Next: C.9 DBMS_OUTPUT

C.8 DBMS_MAIL

The DBMS_MAIL package provides an interface to Oracle Office (formerly Oracle*Mail) To use this package you must first install the Oracle Office product

C.8.1 The SEND procedure

The SEND procedure provides a programmatic interface to the Oracle*Mail send-message facility Use the SEND module to send an Oracle*Mail message The specification is:

Next: C.9 DBMS_OUTPUTC.7 DBMS_LOCK Book Index C.9 DBMS_OUTPUT

The Oracle Library

Navigation

Copyright (c) 2000 O'Reilly & Associates All rights reserved

Previous: C.8

DBMS_MAIL

Appendix CBuilt-In Packages

Next: C.10 DBMS_PIPE

C.9 DBMS_OUTPUT

Of all the packages in this appendix, the DBMS_OUTPUT package is the one you will find yourself using most frequently This package allows you to display information to your session's output device

in a buffer as your PL/SQL program executes As such, it serves as just about the only easily

accessible means of debugging your PL/SQL Version 2 programs DBMS_OUTPUT is also the

package you will use to generate reports from PL/SQL scripts run in SQL*Plus

C.9.1 The DISABLE procedure

The DISABLE procedure disables all calls to the DBMS_OUTPUT package (except for ENABLE, described next) It also purges the buffer of any remaining lines of information After you execute this command, any calls to PUT_LINE and other modules will be ignored and you will not see any output The specification is:

PROCEDURE DBMS_OUTPUT.DISABLE;

C.9.2 The ENABLE procedure

The ENABLE procedure enables calls to the other DBMS_OUTPUT modules If you do not first call ENABLE, then any other calls to the package modules are ignored The specification is:

PROCEDURE DBMS_OUTPUT.ENABLE (buffer_size IN INTEGER

DEFAULT 2000);

C.9.3 The GET_LINE procedure

The GET_LINE procedure retrieves one line of information from the buffer The specification is:

PROCEDURE DBMS_OUTPUT.GET_LINE

(line OUT VARCHAR2,

status OUT INTEGER);

C.9.4 The GET_LINES procedure

The GET_LINES procedure retrieves multiple lines from the buffer with one call It reads the buffer into a PL/SQL string table The specification is:

PROCEDURE DBMS_OUTPUT.GET_LINES

(lines OUT CHARARR,

numlines IN OUT INTEGER);

C.9.5 The NEW_LINE procedure

The NEW_LINE procedure inserts an end-of-line marker in the buffer Use NEW_LINE after one or more calls to PUT in order to terminate those entries in the buffer with a newline marker The

specification is:

PROCEDURE DBMS_OUTPUT.NEW_LINE;

C.9.6 The PUT procedure

The PUT procedure puts information into the buffer, but does not append a newline marker into the buffer Use PUT if you want to place information in the buffer (usually with more than one call to PUT), but not also automatically issue a newline marker The specifications are:

PROCEDURE DBMS_OUTPUT.PUT (A VARCHAR2);

PROCEDURE DBMS_OUTPUT.PUT (A NUMBER);

PROCEDURE DBMS_OUTPUT.PUT (A DATE);

C.9.7 The

PUT_LINE procedure

The PUT_LINE procedure puts information into the buffer and then appends a newline marker into the buffer The specifications are:

PROCEDURE DBMS_OUTPUT.PUT_LINE (A VARCHAR2);

PROCEDURE DBMS_OUTPUT.PUT_LINE (A NUMBER);

PROCEDURE DBMS_OUTPUT.PUT_LINE (A DATE);

Previous: C.8

DBMS_MAIL

Oracle PL/SQL Programming, 2nd Edition

Next: C.10 DBMS_PIPE

The Oracle Library

Navigation

Copyright (c) 2000 O'Reilly & Associates All rights reserved