Table of Contents
This chapter briefly introduces the DBMS_PIPE package, and describes how to use the procedures and functions of the package.
DBMS_PIPE supports communication between sessions on the same instance. A pipe in this package has a similar concept as a pipe used in UNIX series, but it is implemented based on a data structure in tbPSM RDBMS by using a mechanism different from that of the OS.
Since this package only supports communication within the same instance, it cannot be used in TAC.
This section describes the procedures and functions provided by the DBMS_PIPE package, in alphabetical order.
Explicitly creates a public or private pipe for communication.
Details about the CREATE_PIPE function are as follows:
Prototype
DBMS_PIPE.CREATE_PIPE ( pipename IN VARCHAR2, maxpipesize IN PLS_INTEGER DEFAULT 8192, private IN BOOLEAN DEFAULT TRUE ) RETURN PLS_INTEGER;
Parameter
Parameter | Description |
---|---|
pipename | Name of the pipe to create. Must be unique within the instance. Used with SEND_MESSAGE and RECEIVE_MESSAGE. |
maxpipesize | Maximum allowed space for messages on the pipe. (Default value: 8,192 Bytes) |
private |
|
Return Value
Value | Description |
---|---|
0 | Pipe has been created successfully. |
Example
DECLARE status pls_integer; BEGIN status := DBMS_PIPE.CREATE_PIPE('tbpipe', 1000, false); END;
Gets the data type of the next item in the local message buffer. Data can be read by calling RECEIVE_MESSAGE to save the data in the local buffer, NEXT_ITEM_TYPE to get the data type, and then UNPACK_MESSAGE procedure appropriate for the type.
Details about the NEXT_ITEM_TYPE function are as follows:
Prototype
DBMS_PIPE.NEXT_ITEM_TYPE RETURN PLS_INTEGER;
Return Value
Value | Description |
---|---|
0 | There is no more item. |
9 | Item data type is VARCHAR2. |
Example
DECLARE
status pls_integer;
type pls_integer;
BEGIN
status := DBMS_PIPE.RECEIVE_MESSAGE('tbpipe');
type := DBMS_PIPE.NEXT_ITEM_TYPE;
-- Call UNPACK_MESSAGE procedure appropriate for the type
END;
Creates a message in the local message buffer. This procedure saves a unit data (item) in the local buffer, and SEND_MESSAGE can be called to combine one or more items into a message and send it.
Details about the PACK_MESSAGE procedure are as follows:
Prototype
DBMS_PIPE.PACK_MESSAGE ( item IN VARCHAR2 );
Parameter
Parameter | Description |
---|---|
item | Item to save to the local buffer. |
Example
DECLARE
msg VARCHAR2(2000);
BEGIN
msg := 'tibero';
DBMS_PIPE.PACK_MESSAGE(msg);
END;
Purges all data saved in a pipe.
Details about the PURGE procedure are as follows:
Prototype
DBMS_PIPE.PURGE ( pipename IN VARCHAR2 );
Parameter
Parameter | Description |
---|---|
pipename | Name of the pipe to purge all saved data from. |
Example
BEGIN DBMS_PIPE.PURGE('tbpipe'); END;
Reads a message saved in a pipe to the local buffer.
Details about the RECEIVE_MESSAGE function are as follows:
Prototype
DBMS_PIPE.RECEIVE_MESSAGE ( pipename IN VARCHAR2, timeout IN INTEGER DEFAULT MAXWAIT ) RETURN PLS_INTEGER;
Parameter
Parameter | Description |
---|---|
pipename | Name of the pipe from which to read a message. |
timeout | Waiting time for a message in seconds. (Default value: MAXWAIT, 86,400,000 (1,000 days)) |
Return Value
Value | Description |
---|---|
0 | A message has been read from the pipe to the local buffer. |
1 | A specified timeout expired. |
Example
DECLARE status pls_integer; BEGIN status := DBMS_PIPE.RECEIVE_MESSAGE('tbpipe'); END:
Empties all messages from local read and write buffers in order to read/write to/from a new pipe.
Details about the RESET_BUFFER procedure are as follows:
Prototype
DBMS_PIPE.RESET_BUFFER;
Example
BEGIN DBMS_PIPE.RESET_BUFFER; END:
Deletes an explicitly created pipe and all messages in the pipe. When an instance is terminated without calling this function, the pipe will still be deleted.
If a pipe is deleted successfully or this function is called for an already deleted pipe, 0 is returned.
Details about the REMOVE_PIPE function are as follows:
Prototype
DBMS_PIPE.REMOVE_PIPE ( pipename IN VARCHAR2 ) RETURN PLS_INTEGER;
Parameter
Parameter | Description |
---|---|
pipename | Name of the pipe to remove. |
Return Value
Value | Description |
---|---|
0 | Pipe and all messages in the pipe have been deleted successfully. |
Example
DECLARE status pls_integer; BEGIN status := DBMS_PIPE.REMOVE_PIPE('tbpipe'); END;
Saves messages from the local buffer to a pipe. Accumulated items are sent as a single message by calling PACK_MESSAGE one or more times.
If a non-existent pipe name is used as an argument, a private pipe is created implicitly.
Details about the SEND_MESSAGE function are as follows:
Prototype
DBMS_PIPE.SEND_MESSAGE ( pipename IN VARCHAR2, timeout IN INTEGER DEFAULT MAXWAIT, maxpipesize IN INTEGER DEFAULT 8192 ) RETURN PLS_INTEGER;
Parameter
Parameter | Description |
---|---|
pipename | Name of the pipe to send the message to. |
timeout | Waiting time for a message. (Unit: second, default value: MAXWAIT, 86,400,000 (1,000 days)) |
maxpipesize | Maximum message size that can be sent to the pipe. If a message exceeds this size, it cannot be written to a pipe. (Unit: byte, default value: 8,192 bytes) |
Return Value
Value | Description |
---|---|
0 | A message in the local buffer has been successfully saved to the pipe. |
1 | A specified timeout expired. |
Example
DECLARE msg VARCHAR2(2000); status pls_integer; BEGIN msg := 'tibero1'; DBMS_PIPE.PACK_MESSAGE(msg); msg := 'tibero2'; DBMS_PIPE.PACK_MESSAGE(msg); status := DBMS_PIPE.SEND_MESSAGE('tbpipe'); END;
Returns a unique session name used to identify a specific session among all sessions connected to the database. Whenever this function is called from the same session, the same name is always returned. A session can use this function to specify a pipe name that can only be used in its own session.
Details about the UNIQUE_SESSION_NAME function are as follows:
Prototype
DBMS_PIPE.UNIQUE_SESSION_NAME RETURN VARCHAR2;
Return Value
A unique name within the session.
Example
DECLARE status pls_integer; begin status := DBMS_PIPE.CREATE_PIPE(DBMS_PIPE.UNIQUE_SESSION_NAME, 1000, false); status := DBMS_PIPE.SEND_MESSAGE(DBMS_PIPE.UNIQUE_SESSION_NAME); status := DBMS_PIPE.RECEIVE_MESSAGE(DBMS_PIPE.UNIQUE_SESSION_NAME); status := DBMS_PIPE.REMOVE_PIPE(DBMS_PIPE.UNIQUE_SESSION_NAME); END;
Reads an item saved in the local message buffer. A session calls RECEIVE_MESSAGE to read a message from a pipe to the local read buffer, and then calls UNPACK_MESSAGE to read each item of the message from the buffer.
Details about the UNPACK_MESSAGE procedure are as follows:
Prototype
DBMS_PIPE.UNPACK_MESSAGE ( item OUT VARCHAR2 );
Parameter
Parameter | Description |
---|---|
item | Item to read from the local buffer. |
Example
DECLARE msg VARCHAR2(2000); BEGIN DBMS_PIPE.UNPACK_MESSAGE(msg); END;