Oracle Built−in Packages- P33 pot

3.1.4.2.2 Restrictions Note that the user session's local message buffer is limited to 4096 bytes. 3.1.4.2.3 Example In this example, a hex string is converted to RAW, packed into the session buffer using the PACK_MESSAGE_RAW procedure, and sent to a pipe. /* Filename on companion disk: pipex1.sql */* DECLARE hex_data VARCHAR2(12):='FFEEDDCCBBAA'; raw_data RAW(6); call_status INTEGER; BEGIN /* create some raw data */ raw_data := HEXTORAW(hex_data); /* || pack and send raw data on pipe */ DBMS_PIPE.PACK_MESSAGE_RAW(raw_data); call_status := DBMS_PIPE.SEND_MESSAGE('OPBIP_TEST_PIPE'); IF call_status != 0 THEN DBMS_OUTPUT.PUT_LINE('Send message failed'); END IF; END; Applications that need to send large or sensitive data items through database pipes may benefit from using compression and/or encryption on the data and packing the results using PACK_MESSAGE_RAW. 3.1.4.3 The DBMS_PIPE.PACK_MESSAGE_ROWID procedure The PACK_MESSAGE_ROWID procedure packs an item of datatype ROWID into the user session's local message buffer. The header for this program follows: PROCEDURE DBMS_PIPE.PACK_MESSAGE_ROWID (item IN ROWID); The item parameter is the ROWID to pack into the message buffer. 3.1.4.3.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. 3.1.4.3.2 Restrictions Note that the user session's local message buffer is limited to 4096 bytes. 3.1.4.3.3 Example This (somewhat contrived) example shows a trigger that places the ROWIDs of new or modified rows of the emp table into a database pipe. /* Filename on companion disk: pipex1.sql */* CREATE OR REPLACE TRIGGER emp_AIU [Appendix A] What's on the Companion Disk? 3.1.4 Packing and Unpacking Messages 151 AFTER INSERT OR UPDATE ON emp FOR EACH ROW DECLARE rowid_pipename VARCHAR2(20) := 'ROWID_PIPE'; call_status INTEGER; BEGIN /* || pack and send the rowid to a pipe */ DBMS_PIPE.PACK_MESSAGE_ROWID(:NEW.rowid); call_status := DBMS_PIPE.SEND_MESSAGE(rowid_pipename); IF call_status != 0 THEN RAISE_APPLICATION_ERROR(−20001, 'Trigger emp_AIU failed'); END IF; END; 3.1.4.4 The DBMS_PIPE.UNPACK_MESSAGE procedure The UNPACK_MESSAGE procedure unpacks the next item from the local message buffer when the item is of datatype VARCHAR2, NUMBER, or DATE. The header for this procedure follows: PROCEDURE DBMS_PIPE.UNPACK_MESSAGE (item OUT VARCHAR2 | NUMBER | DATE); In Oracle8, the VARCHAR2 version of UNPACK_MESSAGE is somewhat different, as follows: PROCEDURE DBMS_PIPE.UNPACK_MESSAGE (item OUT VARCHAR2 CHARACTER SET ANY_CS); The item parameter is the variable into which the next buffer item is unpacked. 3.1.4.4.1 Exceptions The program does not raise any package exceptions. The following Oracle exceptions are raised if the message buffer contains no more items, or if the item parameter does not match the datatype of the next item in the buffer: Number Description ORA−06556 The pipe is empty; cannot fulfill the UNPACK_MESSAGE request ORA−06559 Wrong datatype requested, 2; actual datatype is 1 3.1.4.4.2 Example This example shows a procedure using UNPACK_MESSAGE to receive and unpack the PL/SQL record type used in the example for PACK_MESSAGE. Note that even though UNPACK_MESSAGE is overloaded on datatype, the correct version needs to be called for the next item in the buffer, or an ORA−06559 error will be raised. This example is a companion to the PACK_MESSAGE example. Together these two examples illustrate a complete pack, send, receive, and unpack DBMS_PIPE communications cycle. /* Filename on companion disk: pipex1.sql */* set serveroutput on size 100000 DECLARE /* || PL/SQL block illustrating use of || DBMS_PIPE.UNPACK_MESSAGE to receive and || unpack a PL/SQL record from a pipe [Appendix A] What's on the Companion Disk? 3.1.4 Packing and Unpacking Messages 152 */ TYPE friend_rectype IS RECORD (name VARCHAR2(60) ,birthdate DATE ,weight_lbs NUMBER ); friend_rec friend_rectype; PROCEDURE receive_unpack_friend (friend_rec_OUT OUT friend_rectype ,pipename_IN IN VARCHAR2) IS call_status INTEGER; BEGIN call_status := DBMS_PIPE.RECEIVE_MESSAGE (pipename=>pipename_IN,timeout=>0); /* ||NOTE: UNPACK_MESSAGE overloaded but we must || call the correct version */ DBMS_PIPE.UNPACK_MESSAGE(friend_rec_OUT.name); DBMS_PIPE.UNPACK_MESSAGE(friend_rec_OUT.birthdate); DBMS_PIPE.UNPACK_MESSAGE(friend_rec_OUT.weight_lbs); END receive_unpack_friend; BEGIN /* || OK test the procedure, get rec from other example */ receive_unpack_friend(friend_rec,'OPBIP_TEST_PIPE'); /* display results */ DBMS_OUTPUT.PUT_LINE('Friend name: '||friend_rec.name); DBMS_OUTPUT.PUT_LINE('Friend birthdate: '|| TO_CHAR(friend_rec.birthdate)); DBMS_OUTPUT.PUT_LINE('Friend weight: '|| TO_CHAR(friend_rec.weight_lbs)); END; Here is output from running the previous script after running the PACK_MESSAGE example script: Friend name: John Smith Friend birthdate: 14−JAN−55 Friend weight: 175 PL/SQL procedure successfully completed. As illustrated in the example, it is good practice to encapsulate the receipt and unpacking of messages into a single logical program unit. Message items must be unpacked in the same order in which they were packed. NOTE: The numeric datatype identifiers in the ORA−06559 message do not match the item type values returned by the NEXT_ITEM_TYPE function. 3.1.4.5 The DBMS_PIPE.UNPACK_MESSAGE_RAW procedure The UNPACK_MESSAGE_RAW procedure unpacks the next item from the local message buffer when the item is of datatype RAW. The header for this program follows: PROCEDURE DBMS_PIPE.UNPACK_MESSAGE_RAW (item OUT RAW); [Appendix A] What's on the Companion Disk? 3.1.4 Packing and Unpacking Messages 153 The item parameter is the RAW variable into which the next buffer item is unpacked. 3.1.4.5.1 Exceptions The program does not raise any package exceptions. The following Oracle exceptions are raised if the message buffer contains no more items or the item parameter does not match the datatype of the next item in the buffer: Number Description ORA−06556 The pipe is empty; cannot fulfill the UNPACK_MESSAGE request ORA−06559 Wrong datatype requested, 2; actual datatype is 1 3.1.4.5.2 Example In this example, a message with a raw data item is received, unpacked using the UNPACK_MESSAGE_RAW procedure, and displayed. /* Filename on companion disk: pipex1.sql */* set serveroutput on size 100000 DECLARE hex_data VARCHAR2(12); raw_data RAW(6); call_status INTEGER; BEGIN /* || receive and unpack the raw message */ call_status := DBMS_PIPE.RECEIVE_MESSAGE('OPBIP_TEST_PIPE'); DBMS_PIPE.UNPACK_MESSAGE_RAW(raw_data); /* display results */ hex_data := RAWTOHEX(raw_data); DBMS_OUTPUT.PUT_LINE('hex of raw: '||hex_data); END; Output from running this script immediately after the PACK_MESSAGE_RAW example script: hex of raw: FFEEDDCCBBAA PL/SQL procedure successfully completed. Note that the numeric datatype identifiers in the ORA−06559 message do not match the item type values returned by the NEXT_ITEM_TYPE function. 3.1.4.6 The DBMS_PIPE.UNPACK_MESSAGE_ROWID procedure The UNPACK_MESSAGE_ROWID procedure unpacks the next item from the local message buffer when the item is of datatype ROWID. Here's the header for this program: PROCEDURE DBMS_PIPE.UNPACK_MESSAGE_ROWID (item OUT ROWID); The item parameter is the ROWID variable into which the next message buffer item is unpacked. 3.1.4.6.1 Exceptions The program does not raise any declared exceptions. The following Oracle errors are raised if the message buffer contains no more items or the item parameter does not match the datatype of the next item in the buffer: [Appendix A] What's on the Companion Disk? 3.1.4 Packing and Unpacking Messages 154 Number Description ORA−06556 The pipe is empty; cannot fulfill the UNPACK_MESSAGE request ORA−06559 Wrong datatype requested, 2; actual datatype is 1 3.1.4.6.2 Example In this example, the database pipe that is filled by the EMP_AIU trigger from the example for PACK_MESSAGE_ROWID is emptied using UNPACK_MESSAGE_ROWID. /* Filename on companion disk: pipex1.sql */* set serveroutput on size 100000 DECLARE rowid_pipename VARCHAR2(20) := 'ROWID_PIPE'; temp_rowid ROWID; call_status INTEGER:=0; BEGIN /* || receive and unpack all rowids from pipe */ WHILE call_status = 0 LOOP call_status := DBMS_PIPE.RECEIVE_MESSAGE (pipename=>rowid_pipename, timeout=>0); IF call_status = 0 THEN DBMS_PIPE.UNPACK_MESSAGE_ROWID(temp_rowid); /* display rowid results */ DBMS_OUTPUT.PUT_LINE(ROWIDTOCHAR(temp_rowid)); END IF; END LOOP; END; / The script output looks like this: SQL> 14 rows updated. Commit complete. AAAA6OAAGAAAA0FAAA AAAA6OAAGAAAA0FAAB AAAA6OAAGAAAA0FAAC AAAA6OAAGAAAA0FAAD AAAA6OAAGAAAA0FAAE AAAA6OAAGAAAA0FAAF AAAA6OAAGAAAA0FAAG AAAA6OAAGAAAA0FAAH AAAA6OAAGAAAA0FAAI AAAA6OAAGAAAA0FAAJ AAAA6OAAGAAAA0FAAK AAAA6OAAGAAAA0FAAL AAAA6OAAGAAAA0FAAM AAAA6OAAGAAAA0FAAN AAAA6OAAGAAAA0FAAN PL/SQL procedure successfully completed. In the previous example, the unusual looking ROWIDs are the result of running the test on an Oracle8 database. (Remember that ROWID formats have changed in Oracle8.) [Appendix A] What's on the Companion Disk? 3.1.4 Packing and Unpacking Messages 155 . unusual looking ROWIDs are the result of running the test on an Oracle8 database. (Remember that ROWID formats have changed in Oracle8 .) [Appendix A] What's on the Companion Disk? 3.1.4. procedure follows: PROCEDURE DBMS_PIPE.UNPACK_MESSAGE (item OUT VARCHAR2 | NUMBER | DATE); In Oracle8 , the VARCHAR2 version of UNPACK_MESSAGE is somewhat different, as follows: PROCEDURE DBMS_PIPE.UNPACK_MESSAGE . unpacked. 3.1.4.4.1 Exceptions The program does not raise any package exceptions. The following Oracle exceptions are raised if the message buffer contains no more items, or if the item parameter