Oracle Built−in Packages- P32 pdf

The header for this procedure follows: PROCEDURE DBMS_PIPE.RESET_BUFFER; The program does not raise any package exceptions.. The following code has been excerpted from that example packa

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:

•

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

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;

/*

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

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