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/Procedure | Return Type | Description |
|---|---|---|
CREATE_PIPE(pipename [, maxpipesize ] [, private ]) | INTEGER | Explicitly create a private pipe if private is “true” (the default) or a public pipe if private is “false”. |
NEXT_ITEM_TYPE | INTEGER | Determine the data type of the next item in a received message. |
PACK_MESSAGE(item) | n/a | Place item in the session’s local message buffer. |
PURGE(pipename) | n/a | Remove unreceived messages from the specified pipe. |
RECEIVE_MESSAGE(pipename [, timeout ]) | INTEGER | Get a message from a specified pipe. |
REMOVE_PIPE(pipename) | INTEGER | Delete an explicitly created pipe. |
RESET_BUFFER | n/a | Reset the local message buffer. |
SEND_MESSAGE(pipename [, timeout ] [, maxpipesize ]) | INTEGER | Send a message on a pipe. |
UNIQUE_SESSION_NAME | VARCHAR2 | Obtain a unique session name. |
UNPACK_MESSAGE(item OUT) | n/a | Retrieve 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