|Oracle9i Supplied PL/SQL Packages and Types Reference
Release 1 (9.0.1)
Part Number A89852-02
DBMS_PIPE package lets two or more sessions in the same instance communicate. Oracle pipes are similar in concept to the pipes used in UNIX, but Oracle pipes are not implemented using the operating system pipe mechanisms.
Information sent through Oracle pipes is buffered in the system global area (SGA). All information in pipes is lost when the instance is shut down.
Depending upon your security requirements, you may choose to use either a public or a private pipe.
This chapter discusses the following topics:
You may create a public pipe either implicitly or explicitly. For implicit public pipes, the pipe is automatically created when it is referenced for the first time, and it disappears when it no longer contains data. Because the pipe descriptor is stored in the SGA, there is some space usage overhead until the empty pipe is aged out of the cache.
You create an explicit public pipe by calling the
CREATE_PIPE function with the
private flag set to
FALSE. You must deallocate explicitly-created pipes by calling the
The domain of a public pipe is the schema in which it was created, either explicitly or implicitly.
Each public pipe works asynchronously. Any number of schema users can write to a public pipe, as long as they have
EXECUTE permission on the
DBMS_PIPE package, and they know the name of the public pipe. However, once buffered information is read by one user, it is emptied from the buffer, and is not available for other readers of the same pipe.
The sending session builds a message using one or more calls to the
PACK_MESSAGE procedure. This procedure adds the message to the session's local message buffer. The information in this buffer is sent by calling the
SEND_MESSAGE function, designating the pipe name to be used to send the message. When
SEND_MESSAGE is called, all messages that have been stacked in the local buffer are sent.
A process that wants to receive a message calls the
RECEIVE_MESSAGE function, designating the pipe name from which to receive the message. The process then calls the
UNPACK_MESSAGE procedure to access each of the items in the message.
You explicitly create a private pipe by calling the
CREATE_PIPE function. Once created, the private pipe persists in shared memory until you explicitly deallocate it by calling the
REMOVE_PIPE function. A private pipe is also deallocated when the database instance is shut down.
You cannot create a private pipe if an implicit pipe exists in memory and has the same name as the private pipe you are trying to create. In this case,
CREATE_PIPE returns an error.
Access to a private pipe is restricted to:
An attempt by any other user to send or receive messages on the pipe, or to remove the pipe, results in an immediate error. Any attempt by another user to create a pipe with the same name also causes an error.
As with public pipes, you must first build your message using calls to
PACK_MESSAGE before calling
SEND_MESSAGE. Similarly, you must call
RECEIVE_MESSAGE to retrieve the message before accessing the items in the message by calling
The pipe functionality has several potential applications:
Security can be achieved by use of
grant execute on the
DBMS_PIPE package by creating a pipe using the
private parameter in the
CREATE_PIPE function and by writing cover packages that only expose particular features or pipenames to particular users or roles.
This is the maximum time to wait attempting to send or receive a message.
DBMS_PIPE package subprograms can return the following errors:
Pipename may not be null. This can be returned by the
Insufficient privilege to access pipe. This can be returned by any subprogram that references a private pipe in its parameter list.
Explicitly creates a pipe (necessary for private pipes).
Builds message in local buffer.
Sends message on named pipe: This implicitly creates a public pipe if the named pipe does not exist.
Copies message from named pipe into local buffer.
Returns datatype of next item in buffer.
Accesses next item in buffer.
Removes the named pipe.
Purges contents of named pipe.
Purges contents of local buffer.
Returns unique session name.