DBMS_PIPE v16
The DBMS_PIPE package lets you send messages through a pipe in or between sessions connected to the same database cluster.
The table shows the procedures and functions available in the DBMS_PIPE package:
| 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 wasn't previously created by the CREATE_PIPE function. For example, if the SEND_MESSAGE function is executed using a nonexistent pipe name, a new implicit pipe is created with that name. An explicit pipe is created using the CREATE_PIPE function in which the first parameter specifies the pipe name for the new pipe.
Pipes are also categorized as private or public. Only the user who created the pipe can access a private pipe. Even a superuser can't access a private pipe that was created by another user. Any user who has access to the DBMS_PIPE package can access a public pipe.
You can create a public pipe only by using the CREATE_PIPE function with the third parameter set to FALSE. You can use the CREATE_PIPE function 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. You then use the SEND_MESSAGE function to send the message through the pipe.
Receipt of a message involves the reverse operation. You use the RECEIVE_MESSAGE function to get a message from the specified pipe. The message is written to the session’s local message buffer. You then use The UNPACK_MESSAGE procedure 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 is 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