C.10 DBMS_PIPE

Appendix C
Built-In Packages
 

The DBMS_PIPE package provides a way for sessions in the same database instance to communicate with each other. One of the most useful aspects of Oracle pipes is that pipe communication is asynchronous: you need not COMMIT a transaction in order to initiate pipe-related activity, as is necessary with the DBMS_ALERT package. You can send a message through and receive a message from a pipe at any time. Indeed, more than one session can read or write to the same pipe.

C.10.1 The CREATE_PIPE function

With PL/SQL Release 2.2 only, the CREATE_PIPE function allows you to explicitly request the creation of a pipe, either public or private. The specification is:

FUNCTION DBMS_PIPE.CREATE_PIPE    (pipename IN VARCHAR2,     maxpipesize IN INTEGER DEFAULT 8192,     private IN BOOLEAN DEFAULT TRUE) RETURN INTEGER;

The function returns a numeric status code. If it returns 0, then the pipe was created successfully.

C.10.2 The NEXT_ITEM_TYPE function

The NEXT_ITEM_TYPE function returns the type of the next item in the local message buffer. Data is put in the message buffer with both the PACK_MESSAGE and the RECEIVE_MESSAGE procedures. Use NEXT_ITEM_TYPE to decide which kind of variable you should use to receive the data from the buffer with the overloaded UNPACK_MESSAGE module. The specification is:

FUNCTION DBMS_PIPE.NEXT_ITEM_TYPE RETURN INTEGER;

where the return value for the function is one of the following:

0

No more items in buffer

9

VARCHAR2

6

NUMBER

12

DATE

C.10.3 The PACK_MESSAGE procedure

The PACK_MESSAGE procedure packs an item into the message buffer for your session. A pipe message item may have a datatype of VARCHAR2, NUMBER, or DATE. The specifications are:

PROCEDURE DBMS_PIPE.PACK_MESSAGE (item IN VARCHAR2); PROCEDURE DBMS_PIPE.PACK_MESSAGE (item IN NUMBER); PROCEDURE DBMS_PIPE.PACK_MESSAGE (item IN DATE);

C.10.4 The PURGE procedure

The PURGE procedure empties the contents of the named pipe. The specification is:

PROCEDURE DBMS_PIPE.PURGE (pipename IN VARCHAR2);

C.10.5 The RECEIVE_MESSAGE function

The RECEIVE_MESSAGE function receives a message from the named pipe and copies the contents of that message to the local message buffer. Once you receive the message into the buffer, you can use the UNPACK_MESSAGE procedure to extract the items from the buffer into local variables. The specification is:

FUNCTION DBMS_PIPE.RECEIVE_MESSAGE    (pipename IN VARCHAR2, timeout IN INTEGER DEFAULT MAXWAIT) RETURN INTEGER;

The function returns a status, which will be one of the following INTEGER values:

0

Successful receipt of message

1

Timed out waiting to receive a message

2

Record in pipe too big for buffer; this should never happen

3

Receipt of message was interrupted

C.10.6 The REMOVE_PIPE function

The REMOVE_PIPE function removes a pipe from shared memory. This function must be called to remove a pipe created explicitly with CREATE_PIPE. If your pipe is created implicitly, then it will be removed with a call to PURGE or whenever the pipe is emptied. The specification is:

FUNCTION DBMS_PIPE.REMOVE_PIPE (pipename IN VARCHAR2) RETURN INTEGER; 

C.10.7 The RESET_BUFFER procedure

The RESET_BUFFER procedure clears the buffer so that both PACK_MESSAGE and UNPACK_MESSAGE will work from the first item. The specification is:

PROCEDURE DBMS_PIPE.RESET_BUFFER;

C.10.8 The SEND_MESSAGE function

The SEND_MESSAGE function sends the contents of the local message buffer to the named pipe. The specification is:

FUNCTION DBMS_PIPE.SEND_MESSAGE   (pipename IN VARCHAR2,    timeout IN INTEGER DEFAULT MAXWAIT,    maxpipesize IN INTEGER DEFAULT 8192) RETURN INTEGER;

The function returns a status code as follows:

0

Successful receipt of message

1

Timed out waiting to send a message

3

Sending of message was interrupted

C.10.9 The UNIQUE_SESSION_NAME function

The UNIQUE_SESSION_NAME function returns a name that is unique among the sessions currently connected to the database. You can use this function to obtain a name for a pipe that you know will not be in use by any other sessions. The specification is:

FUNCTION DBMS_PIPE.UNIQUE_SESSION_NAME RETURN VARCHAR2;

C.10.10 The UNPACK_MESSAGE procedure

The UNPACK_MESSAGE procedure unpacks the next item from the local message buffer and deposits it into the specified local variable. The specification is:

PROCEDURE DBMS_PIPE.UNPACK_MESSAGE (item OUT VARCHAR2); PROCEDURE DBMS_PIPE.UNPACK_MESSAGE (item OUT NUMBER); PROCEDURE DBMS_PIPE.UNPACK_MESSAGE (item OUT DATE);


C.9 DBMS_OUTPUTC.11 DBMS_ROWID (PL/SQL8 Only)

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



Oracle PL/SQL Programming
Oracle PL/SQL Programming: Covers Versions Through Oracle Database 11g Release 2 (Animal Guide)
ISBN: 0596514468
EAN: 2147483647
Year: 2004
Pages: 234
Authors: Steven Feuerstein, Bill Pribyl
BUY ON AMAZON

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net