 |
|
The Receive_Message()
Function
Oracle Tips by
Burleson
|
The Receive_Message() function is used to receive a message
from the pipe and place the message in a local buffer. The function
has two parameters: pipename and timeout.
FUNCTION Receive_Message (pipename IN varchar2,
timeout IN integer := MAXWAIT)
RETURN integer
The pipename parameter holds the name of the pipe. The
timeout parameter indicates the period of time that the process
will wait for a message to be sent. This parameter defaults to the
value of the DBMS_Pipe.MAXWAIT constant (86,400,000 seconds).
The Receive_Message() function returns an integer value
indicating its result. The return values for the function are listed
in Table 9.3.
|
Table 9.3 Return values for the Receive_Message( )
function. |
|
Return Value |
Meaning |
|
0 |
A message was received. |
|
1 |
No message was received. |
|
2 |
The message in the pipe was too large for the
buffer. |
|
3 |
An error occurred. |
The Remove_Pipe() Function
The Remove_Pipe() function is called to destroy a pipe
created by a call to the Create_Pipe() function. The
Remove_Pipe() function has one parameter:
FUNCTION Remove_Pipe (pipename IN varchar2) RETURN integer
The pipename parameter holds the name of the pipe that is to
be deleted. The function will return 0 if the pipe is successfully
deleted or if the specified pipe does not exist.
The Send_Message() Function
The Send_Message() function is used to send a message
through a pipe. The function accepts one parameter:
FUNCTION Send_Message (pipename IN varchar2) RETURN integer
The pipename parameter holds the name of the pipe through
which the packed message is sent. The function will return one of the
integer values shown in Table 9.4.
|
Table 9.4 Return values of the Send_Message( )
function. |
|
Return Value |
Meaning |
|
0 |
The message was successfully sent. |
|
1 |
The message was not sent due to a timeout.
|
|
3 |
An error occurred while sending the message.
|
The Unique_Session_Name()
Function
The Unique_Session_Name() function returns an integer value
that uniquely identifies a particular session connected to Oracle.
Each session has its own ID number. Calling this function multiple
times from the same session will always yield the same result.
This function is often used to generate a pipename that is specific
to a given session. For instance, both session 18 and session 23 might
want to create the same pipe, but each session has a unique listener.
The Unique_Session_Name() function is called and the resulting
value is appended onto the pipe’s name, yielding a uniquely named pipe
for each session.
This function has no parameters.
The Unpack_Message() Procedure
The Unpack_Message() procedure is used to extract
information from a message. This procedure, like the Pack_Message()
procedure, is overloaded. The implementations of the procedure are as
follows:
PROCEDURE Unpack_Message (item OUT varchar2)
PROCEDURE Unpack_Message (item OUT date)
PROCEDURE Unpack_Message (item OUT number)
PROCEDURE Unpack_Message (item OUT raw)
PROCEDURE Unpack_Message (item OUT ROWID)
Each implementation of the procedure extracts data of a specific
type from the message.
This is an excerpt from the book "High Performance Oracle
Database Automation" by Jonathan Ingram and Donald K.
Burleson, Series Editor. |
