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
Trang 1NOTE: 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
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);
Trang 2ELSIF 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
Trang 3PL/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
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:
•
Trang 4Pipenames 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)
Trang 5RETURN 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
2 Message too big for buffer
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