Oracle9i Supplied PL/SQL Packages and Types Reference
Release 1 (9.0.1)

Part Number A89852-02
Go To Documentation Library
Go To Product List
Book List
Go To Table Of Contents
Go To Index

Master Index


Go to previous page Go to next page


The 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.


Pipes are independent of transactions. Be careful using pipes when transaction control can be affected. 

This chapter discusses the following topics:

Public Pipes, Private Pipes, and Pipe Uses

Public Pipes

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 REMOVE_PIPE function.

The domain of a public pipe is the schema in which it was created, either explicitly or implicitly.

Writing and Reading Pipes

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.

Private Pipes

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 UNPACK_MESSAGE.

Pipe Uses

The pipe functionality has several potential applications:

Security, Constants, and Errors


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.


maxwait   constant integer := 86400000; /* 1000 days */ 

This is the maximum time to wait attempting to send or receive a message.


DBMS_PIPE package subprograms can return the following errors:

Table 41-1 DBMS_PIPE Errors
Error  Description 

Pipename may not be null. This can be returned by the CREATE_PIPE function, or any subprogram that takes a pipe name as a parameter.  


Insufficient privilege to access pipe. This can be returned by any subprogram that references a private pipe in its parameter list. 

Summary of DBMS_PIPE Subprograms

Table 41-2 DBMS_PIPE Package Subprograms  
Subprogram  Description 

"CREATE_PIPE Function" 

Explicitly creates a pipe (necessary for private pipes). 

"PACK_MESSAGE Procedure" 

Builds message in local buffer. 

"SEND_MESSAGE Function" 

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. 

"NEXT_ITEM_TYPE Function" 

Returns datatype of next item in buffer. 


Accesses next item in buffer. 

"REMOVE_PIPE Function" 

Removes the named pipe. 

"PURGE Procedure" 

Purges contents of named pipe. 

"RESET_BUFFER Procedure" 

Purges contents of local buffer. 


Returns unique session name. 

Go to previous page Go to next page
Copyright © 1996-2001, Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Go To Product List
Book List
Go To Table Of Contents
Go To Index

Master Index