Oracle Built−in Packages- P32 pdf

RETURN BOOLEAN
IS
call_status INTEGER;
BEGIN
call_status := DBMS_PIPE.REMOVE_PIPE(pipename_IN);
RETURN (call_status = 0);
EXCEPTION
WHEN cannot_use_pipe OR null_pipename
THEN
RETURN FALSE;
END closepipe;
END dbpipe;
NOTE: It is good practice to remove pipes explicitly when they are no longer needed. This
can sometimes be difficult, since database pipes are typically shared by multiple sessions, so
it is hard to know when they can be removed. Empty pipes that have not been removed will
eventually be aged out of the shared pool by Oracle.
3.1.3.3 The DBMS_PIPE.RESET_BUFFER procedure
The DBMS_PIPE.RESET_BUFFER procedure resets the session message buffer's internal pack and unpack
indicators, effectively discarding the contents of the buffer. The header for this procedure follows:
PROCEDURE DBMS_PIPE.RESET_BUFFER;
The program does not raise any package exceptions.
3.1.3.3.1 Example
This example shows the use of RESET_BUFFER at the beginning of a program that packs a PL/SQL record
into a message.
The pack_send_request procedure can be found in the pipesvr package discussed in the "Section 3.1.7"
section. The following code has been excerpted from that example package:
/* Filename on companion disk: pipesvr.sql */*
PROCEDURE pack_send_request
(request_rec_IN IN request_rectype
,return_code_OUT OUT NUMBER)
IS

BEGIN
/* discard any previous unsent message items */
DBMS_PIPE.RESET_BUFFER;
/* pack message in standard order */
DBMS_PIPE.PACK_MESSAGE(request_protocol);
DBMS_PIPE.PACK_MESSAGE(request_rec_IN.response_pipe);
DBMS_PIPE.PACK_MESSAGE(request_rec_IN.service);
/*
|| send message to request pipe nowait
*/
return_code_OUT := DBMS_PIPE.SEND_MESSAGE
(pipename => request_pipe
,timeout => 0);
END pack_send_request;
Oracle advises that the RESET_BUFFER procedure should not generally be needed. I make sure, however, to
use it in the following places:
•
[Appendix A] What's on the Companion Disk?
3.1.3 Managing Pipes and the Message Buffer 146
Exception handlers of programs using UNPACK_MESSAGE procedures
•
At the beginning of programs designed to pack specific messages into the buffer using
PACK_MESSAGE procedures
In handling unpack exceptions, it is safe practice to initialize the message buffer after an unexpected item type
is encountered. When packing messages, it is important to be sure that only the intended message items are
packed into the buffer. By resetting the message buffer, programs can protect themselves from sending any
previously packed but unsent message items.
3.1.3.4 The DBMS_PIPE.PURGE procedure
The PURGE procedure empties the named pipe of all messages. The header for this procedure is,
PROCEDURE DBMS_PIPE.PURGE

(pipename IN VARCHAR2);
where the pipename parameter is the name of the database pipe to be emptied.
3.1.3.4.1 Exceptions
The program does not raise any package exceptions. The following Oracle exceptions are raised if the user
attempts to purge a pipe belonging to another user or passes a NULL pipename:
Number Description
ORA−23322 Insufficient privileges to access pipe
ORA−23321 Pipename may not be NULL
3.1.3.4.2 Restrictions
Note the following restrictions on calling PURGE:
•
Pipenames are limited to 128 bytes in length, are case−insensitive, and cannot contain NLS
characters.
•
Pipenames must not begin with "ORA$", as these names are reserved for use by Oracle Corporation.
3.1.3.4.3 Example
This example shows a procedure that will purge all pipes to which the calling user has access. The
purge_all_pipes procedure can be found in the dbpipe package discussed in "Section 3.1.7." You will need
SELECT privilege on SYS.V_$DB_PIPES to create the package.
/* Filename on companion disk: dbpipe.sql */*
PACKAGE BODY dbpipe
IS
cannot_use_pipe EXCEPTION;
PRAGMA EXCEPTION_INIT(cannot_use_pipe,−23322);
PROCEDURE purge_all_pipes
IS
/* gets names of all pipes */
CURSOR all_pipes_cur
IS
[Appendix A] What's on the Companion Disk?

3.1.3 Managing Pipes and the Message Buffer 147
SELECT name
FROM sys.v_$db_pipes;
BEGIN
FOR all_pipes_rec IN all_pipes_cur
LOOP
BEGIN
DBMS_PIPE.PURGE(all_pipes_rec.name);
/* ignore cannot_use_pipe exception */
EXCEPTION
WHEN cannot_use_pipe
THEN
null;
WHEN OTHERS
THEN
RAISE;
END;
END LOOP;
END purge_all_pipes;
END dbpipe;
Emptying a pipe using PURGE releases the SGA memory associated with the pipe. Oracle can then reclaim
this memory for other uses based on normal least−recently−used (LRU) aging of the shared pool.
WARNING: Pipes that are not in use, but still have unpurged messages in them, waste SGA
memory because they cannot be aged out of the shared pool. Very large pipes in this
condition can lead to serious database performance problems.
Note also that calling PURGE may cause the user session's message buffer to be overwritten by messages
discarded from the pipe. Be sure to send any message packed in the session buffer prior to calling PURGE.
Expert technical reviewer Dan Clamage points out that this is because the implementation of PURGE is "to
simply do RECEIVE_MESSAGE with timeout = 0 until the pipe is empty."
The PURGE procedure will implicitly create a public pipe of the given name if one does not already exist.

This is somewhat nonintuitive, in that emptying a nonexistent pipe causes a new empty pipe to exist.
3.1.3.5 The DBMS_PIPE.UNIQUE_SESSION_NAME function
The UNIQUE_SESSION_NAME function returns a string value that is constant for a given session and
unique among all sessions currently connected to the database. Here's the header for this program:
FUNCTION DBMS_PIPE.UNIQUE_SESSION_NAME
RETURN VARCHAR2;
The program does not raise any package exceptions.
3.1.3.5.1 Example
This example creates a pipe with a name unique to the session for receiving messages intended specifically for
this session.
DECLARE
/*
|| declare and initialize my_pipename variable with
|| string unique to session
*/
my_pipename VARCHAR2(128) := DBMS_PIPE.UNIQUE_SESSION_NAME;
call_status INTEGER;
[Appendix A] What's on the Companion Disk?
3.1.3 Managing Pipes and the Message Buffer 148
BEGIN
/*
|| create pipe as public so anyone can send message to it
*/
call_status := DBMS_PIPE.CREATE_PIPE
(pipename => my_pipename
,private => FALSE);
END;
Applications in which user sessions receive messages on database pipes usually create a unique pipe for each
session to use. This helps ensure that sessions get only messages intended for them. As illustrated in the
previous example, UNIQUE_SESSION_NAME is often used to generate pipe names that are unique to the

session.
3.1.4 Packing and Unpacking Messages
The PACK_MESSAGE, PACK_MESSAGE_RAW, PACK_MESSAGE_ROWID, UNPACK_MESSAGE,
UNPACK_MESSAGE_RAW, UNPACK_MESSAGE_ROWID, and NEXT_ITEM_TYPE programs are used
to pack messages into your session's local message buffer and unpack them from this buffer.
3.1.4.1 The DBMS_PIPE.PACK_MESSAGE procedure
The PACK_MESSAGE procedure is used to pack items of datatypes VARCHAR2, NUMBER, or DATE into
the user's session's local message buffer. The header for this program follows:
PROCEDURE DBMS_PIPE.PACK_MESSAGE
(item IN VARCHAR2 | NUMBER | DATE);
Note that you must specify VARCHAR2 or NUMBERor DATE.
In Oracle8, the VARCHAR2 version of PACK_MESSAGE is somewhat different, as follows:
PROCEDURE DBMS_PIPE.PACK_MESSAGE
(item IN VARCHAR2 CHARACTER SET ANY_CS);
The item parameter is the message of the particular type that is packed into the message buffer.
3.1.4.1.1 Exceptions
The program does not raise any package exceptions. The Oracle.06558 Oracle exception is raised if the
message buffer becomes full and no more items can be packed.
3.1.4.1.2 Restrictions
Note that the user session message buffer is limited to 4096 bytes.
3.1.4.1.3 Example
The following example creates a procedure to pack and send a PL/SQL record to a database pipe. Notice the
overloading of PACK_MESSAGE, which packs items of different datatypes into the local message buffer
using the same procedure call.
/* Filename on companion disk: pipex1.sql */*
DECLARE
/*
|| PL/SQL block illustrating use of
|| DBMS_PIPE.PACK_MESSAGE to pack and send
[Appendix A] What's on the Companion Disk?

3.1.4 Packing and Unpacking Messages 149
|| a PL/SQL record to a pipe
*/
TYPE friend_rectype IS RECORD
(name VARCHAR2(60)
,birthdate DATE
,weight_lbs NUMBER
);
friend_rec friend_rectype;
PROCEDURE pack_send_friend
(friend_rec_IN IN friend_rectype
,pipename_IN IN VARCHAR2)
IS
call_status INTEGER;
BEGIN
/*
||notice the PACK_MESSAGE overloading
*/
DBMS_PIPE.PACK_MESSAGE(friend_rec_IN.name);
DBMS_PIPE.PACK_MESSAGE(friend_rec_IN.birthdate);
DBMS_PIPE.PACK_MESSAGE(friend_rec_IN.weight_lbs);
call_status := DBMS_PIPE.SEND_MESSAGE
(pipename=>pipename_IN,timeout=>0);
IF call_status != 0
THEN
DBMS_OUTPUT.PUT_LINE('Send message failed');
END IF;
END pack_send_friend;
BEGIN
/*

|| OK, now use the procedure to send a friend_rec
*/
friend_rec.name := 'John Smith';
friend_rec.birthdate := TO_DATE('01/14/55','MM/DD/YY');
friend_rec.weight_lbs := 175;
pack_send_friend(friend_rec,'OPBIP_TEST_PIPE');
END;
As in the example, it is good practice to encapsulate the packing and sending of an entire message as part of a
logical program unit. Otherwise, additional calls to PACK_MESSAGE could add unexpected items to a
message before sending, perhaps causing confusion on the receiving end.
3.1.4.2 The DBMS_PIPE.PACK_MESSAGE_RAW procedure
The PACK_MESSAGE_RAW procedure packs an item of datatype RAW into the user session's local
message buffer. Here's the header for this program:
PROCEDURE DBMS_PIPE.PACK_MESSAGE_RAW
(item IN RAW);
The parameter is the item to be packed into the message buffer.
3.1.4.2.1 Exceptions
The program does not raise any package exceptions. The ORA−06558 Oracle exception is raised if the
message buffer becomes full and no more items can be packed.
[Appendix A] What's on the Companion Disk?
3.1.4 Packing and Unpacking Messages 150