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