Oracle Built−in Packages- P34 docx

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.7 The DBMS_PIPE.NEXT_ITEM_TYPE function The NEXT_ITEM_TYPE function returns a number indicating the datatype of the next item in the user session's message buffer. The header for this function follows: FUNCTION DBMS_PIPE.NEXT_ITEM_TYPE RETURN INTEGER; The return value will be one of the following: Item Type Description 0 No more items in buffer 6 NUMBER 9 VARCHAR2 11 ROWID 12 DATE 23 RAW The program does not raise any package exceptions. 3.1.4.7.1 Example The following PL/SQL block contains an inline procedure called unpack_all_items, which can unpack any message and display its contents using DBMS_OUTPUT. The unpack_all_items procedure uses NEXT_ITEM_TYPE to determine which version of UNPACK_MESSAGE to call for each item. /* Filename on companion disk: pipex2.sql */* set serveroutput on size 100000 DECLARE call_stat INTEGER; PROCEDURE unpack_all_items IS /* || declare temp variables of all message item types */ temp_varchar2 VARCHAR2(2000); temp_date DATE; temp_number NUMBER; temp_rowid ROWID; temp_raw RAW(2000); next_item INTEGER:=0; BEGIN next_item := DBMS_PIPE.NEXT_ITEM_TYPE; /* || unpack by item type and convert to varchar2 */ WHILE next_item > 0 LOOP IF next_item = 9 THEN DBMS_PIPE.UNPACK_MESSAGE(temp_varchar2); [Appendix A] What's on the Companion Disk? 3.1.4 Packing and Unpacking Messages 156 ELSIF next_item = 6 THEN DBMS_PIPE.UNPACK_MESSAGE(temp_number); temp_varchar2 := 'NUMBER: '||TO_CHAR(temp_number); ELSIF next_item = 11 THEN DBMS_PIPE.UNPACK_MESSAGE_ROWID(temp_rowid); temp_varchar2 := 'ROWID: '||ROWIDTOCHAR(temp_rowid); ELSIF next_item = 12 THEN DBMS_PIPE.UNPACK_MESSAGE(temp_date); temp_varchar2 := 'DATE: '|| TO_CHAR(temp_date,'YYYY:MM:DD:HH24:MI:SS'); ELSIF next_item = 23 THEN DBMS_PIPE.UNPACK_MESSAGE_RAW(temp_raw); temp_varchar2 := 'RAW: '||RAWTOHEX(temp_raw); ELSE temp_varchar2 := 'Invalid item type: '||TO_CHAR(next_item); END IF; /* || display item and determine next item */ DBMS_OUTPUT.PUT_LINE(temp_varchar2); next_item := DBMS_PIPE.NEXT_ITEM_TYPE; END LOOP; END unpack_all_items; BEGIN /* empty pipe */ DBMS_PIPE.PURGE('OPBIP_TEST_PIPE'); /* initialize buffer */ DBMS_PIPE.RESET_BUFFER; /* pack in some data of different types */ DBMS_PIPE.PACK_MESSAGE('HELLO THERE'); DBMS_PIPE.PACK_MESSAGE(123456789); DBMS_PIPE.PACK_MESSAGE(SYSDATE); DBMS_PIPE.PACK_MESSAGE_RAW(HEXTORAW('FFDDEE2344AA')); /* send and receive the message */ call_stat := DBMS_PIPE.SEND_MESSAGE('OPBIP_TEST_PIPE'); call_stat := DBMS_PIPE.RECEIVE_MESSAGE('OPBIP_TEST_PIPE'); /* call the generic unpack procedure */ unpack_all_items; END; Here is output from running the example script: SQL> @pipex2.sql HELLO THERE NUMBER: 123456789 DATE: 1998:02:01:12:01:19 RAW: FFDDEE2344AA [Appendix A] What's on the Companion Disk? 3.1.4 Packing and Unpacking Messages 157 PL/SQL procedure successfully completed. The unpack_all_items inline procedure is a prototype for the procedure of the same name found in the dbpipe package, discussed in the "Section 3.1.7" section. NOTE: The item type values returned by the NEXT_ITEM_TYPE function do not match the numeric datatype identifiers in the ORA−06559 message. 3.1.5 Sending and Receiving Messages Use DBMS_PIPE's SEND_MESSAGE and RECEIVE_MESSAGE functions to send and receive messages on the pipe you have created. 3.1.5.1 The DBMS_PIPE.SEND_MESSAGE function The SEND_MESSAGE function sends a message on the named pipe. The message sent is whatever has been packed into the user session's current message buffer. The header for this program follows: FUNCTION DBMS_PIPE.SEND_MESSAGE (pipename IN VARCHAR2 ,timeout IN INTEGER DEFAULT MAXWAIT ,maxpipesize IN INTEGER DEFAULT 8192) RETURN INTEGER; Parameters are summarized in the following table. Parameter Description pipename Name of the database pipe timeout Time in seconds to wait for message to be sent maxpipesize Maximum size in bytes of the pipe The value returned is one of the following: Return Value Description 0 Success 1 Timed out 3 Interrupted 3.1.5.1.1 Exceptions The program does not raise any package exceptions. The following Oracle exceptions are raised if the user attempts to receive a message on a pipe belonging to another user or on a NULL pipename: Number Description ORA−23322 Insufficient privileges to access pipe ORA−23321 Pipename may not be NULL 3.1.5.1.2 Restrictions Note the following restrictions on calling SEND_MESSAGE: • [Appendix A] What's on the Companion Disk? 3.1.5 Sending and Receiving Messages 158 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.5.1.3 Example This example shows the use of SEND_MESSAGE to send a message based on a PL/SQL record out on a database pipe. The pack_send_request procedure can be found in the pipesvr package discussed in the "Section 3.1.7" section. /* 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; The SEND_MESSAGE function will implicitly create a public pipe if the pipe specified by the pipename parameter does not already exist. Be careful not to assume that the call to SEND_MESSAGE has been successful. Note that in this example, the value returned by the call to SEND_MESSAGE is passed out of the pack_send_request procedure to its caller, so it will be the caller's responsibility to handle a nonzero return value. Calls to SEND_MESSAGE will wait for up to the value of the timeout parameter in seconds for the call to complete. Applications using database pipes that stay full of messages may incur lengthy wait times or timeouts. When using SEND_MESSAGE under these circumstances, be careful to specify a timeout that users can tolerate. Applications experiencing frequent timeouts or long waits when calling SEND_MESSAGE may benefit by increasing the size of the database pipe. This can be done by specifying a value for the maxpipesize parameter that is greater than the current maximum size of the pipe. 3.1.5.2 The DBMS_PIPE.RECEIVE_MESSAGE function The RECEIVE_MESSAGE function is used to fetch a message from the named pipe into the user session's message buffer. The header for this program follows: FUNCTION DBMS_PIPE.RECEIVE_MESSAGE (pipename IN VARCHAR2 ,timeout IN INTEGER DEFAULT MAXWAIT) [Appendix A] What's on the Companion Disk? 3.1.5 Sending and Receiving Messages 159 RETURN INTEGER; Parameters are summarized in the following table. Parameter Description pipename Name of the database pipe timeout Time in seconds to wait for message to be received The function returns one of the following values: Return Value Description 0 Success 1 Timed out 2 Message too big for buffer 3 Interrupted 3.1.5.2.1 Exceptions The program does not raise any package exceptions. The following Oracle exceptions are raised if the user attempts to receive a message on a pipe belonging to another user or on a NULL pipename: Number Description ORA−23322 Insufficient privileges to access pipe ORA−23321 Pipename may not be NULL 3.1.5.2.2 Restrictions Note the following restrictions on calling RECEIVE_MESSAGE: • 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.5.2.3 Example This example shows the use of the RECEIVE_MESSAGE function to receive a message based on a PL/SQL record from a database pipe. The receive_unpack_request procedure can be found in the pipesvr package discussed in the "Section 3.1.7" section. /* Filename on companion disk: pipesvr.sql */* PROCEDURE receive_unpack_request (timeout_IN IN INTEGER ,request_rec_OUT OUT request_rectype ,return_code_OUT OUT NUMBER) IS /* temp variables */ temp_protocol request_protocol%TYPE; temp_return_code NUMBER; BEGIN [Appendix A] What's on the Companion Disk? 3.1.5 Sending and Receiving Messages 160 . Interrupted 3.1.5.1.1 Exceptions The program does not raise any package exceptions. The following Oracle exceptions are raised if the user attempts to receive a message on a pipe belonging to another. NLS characters. • Pipenames must not begin with "ORA$", as these names are reserved for use by Oracle Corporation. 3.1.5.1.3 Example This example shows the use of SEND_MESSAGE to send a message. Interrupted 3.1.5.2.1 Exceptions The program does not raise any package exceptions. The following Oracle exceptions are raised if the user attempts to receive a message on a pipe belonging to another