DBMS_PIPE v11

The DBMS_PIPE package provides the capability to send messages through a pipe within or between sessions connected to the same database cluster.

The procedures and functions available in the DBMS_PIPE package are listed in the following table:

Function/ProcedureReturn TypeDescription
CREATE_PIPE(pipename [, maxpipesize ] [, private ])INTEGERExplicitly create a private pipe if private is “true” (the default) or a public pipe if private is “false”.
NEXT_ITEM_TYPEINTEGERDetermine the data type of the next item in a received message.
PACK_MESSAGE(item)n/aPlace item in the session’s local message buffer.
PURGE(pipename)n/aRemove unreceived messages from the specified pipe.
RECEIVE_MESSAGE(pipename [, timeout ])INTEGERGet a message from a specified pipe.
REMOVE_PIPE(pipename)INTEGERDelete an explicitly created pipe.
RESET_BUFFERn/aReset the local message buffer.
SEND_MESSAGE(pipename [, timeout ] [, maxpipesize ])INTEGERSend a message on a pipe.
UNIQUE_SESSION_NAMEVARCHAR2Obtain a unique session name.
UNPACK_MESSAGE(item OUT)n/aRetrieve the next data item from a message into a type-compatible variable, item.

Pipes are categorized as implicit or explicit. An implicit pipe is created if a reference is made to a pipe name that was not previously created by the CREATE_PIPE function. For example, if the SEND_MESSAGE function is executed using a non-existent pipe name, a new implicit pipe is created with that name. An explicit pipe is created using the CREATE_PIPE function whereby the first parameter specifies the pipe name for the new pipe.

Pipes are also categorized as private or public. A private pipe can only be accessed by the user who created the pipe. Even a superuser cannot access a private pipe that was created by another user. A public pipe can be accessed by any user who has access to the DBMS_PIPE package.

A public pipe can only be created by using the CREATE_PIPE function with the third parameter set to FALSE. The CREATE_PIPE function can be used to create a private pipe by setting the third parameter to TRUE or by omitting the third parameter. All implicit pipes are private.

The individual data items or “lines” of a message are first built-in a local message buffer, unique to the current session. The PACK_MESSAGE procedure builds the message in the session’s local message buffer. The SEND_MESSAGE function is then used to send the message through the pipe.

Receipt of a message involves the reverse operation. The RECEIVE_MESSAGE function is used to get a message from the specified pipe. The message is written to the session’s local message buffer. The UNPACK_MESSAGE procedure is then used to transfer the message data items from the message buffer to program variables. If a pipe contains multiple messages, RECEIVE_MESSAGE gets the messages in FIFO (first-in-first-out) order.

Each session maintains separate message buffers for messages created with the PACK_MESSAGE procedure and messages retrieved by the RECEIVE_MESSAGE function. Thus messages can be both built and received in the same session. However, if consecutive RECEIVE_MESSAGE calls are made, only the message from the last RECEIVE_MESSAGE call will be preserved in the local message buffer.

create_pipe next_item_pipe pack_message purge receive_message remove_pipe reset_buffer send_message unique_session_name unpack_message comprehensive_example