Chapter 23. DBMS_PIPE

Table of Contents

23.1. Overview
23.2. Procedures and Functions
23.2.1. CREATE_PIPE
23.2.2. NEXT_ITEM_TYPE
23.2.3. PACK_MESSAGE
23.2.4. PURGE
23.2.5. RECEIVE_MESSAGE
23.2.6. RESET_BUFFER
23.2.7. REMOVE_PIPE
23.2.8. SEND_MESSAGE
23.2.9. UNIQUE_SESSION_NAME
23.2.10. UNPACK_MESSAGE

This chapter briefly introduces the DBMS_PIPE package, and describes how to use the procedures and functions of the package.

23.1. Overview

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.

23.2. Procedures and Functions

This section describes the procedures and functions provided by the DBMS_PIPE package, in alphabetical order.

23.2.1. CREATE_PIPE

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

    ParameterDescription
    pipename

    Name of the pipe to create. Must be unique within the instance.

    Used with SEND_MESSAGE and RECEIVE_MESSAGE.

    maxpipesizeMaximum allowed space for messages on the pipe. (Default value: 8,192 Bytes)
    private
    • TRUE: create a private pipe. (Default)

    • FALSE: create a public pipe.

  • Return Value

    ValueDescription
    0Pipe has been created successfully.
  • Example

    DECLARE
        status pls_integer;
    BEGIN
        status := DBMS_PIPE.CREATE_PIPE('tbpipe', 1000, false);                        
    END;

23.2.2. NEXT_ITEM_TYPE

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

    ValueDescription
    0There is no more item.
    9Item 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;

23.2.3. PACK_MESSAGE

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

    ParameterDescription
    itemItem to save to the local buffer.
  • Example

    DECLARE
        msg VARCHAR2(2000);
    BEGIN
        msg := 'tibero';
        DBMS_PIPE.PACK_MESSAGE(msg);
    END;

23.2.4. PURGE

Purges all data saved in a pipe.

Details about the PURGE procedure are as follows:

  • Prototype

    DBMS_PIPE.PURGE 
    (
        pipename     IN  VARCHAR2
    );
  • Parameter

    ParameterDescription
    pipenameName of the pipe to purge all saved data from.
  • Example

    BEGIN
        DBMS_PIPE.PURGE('tbpipe');
    END;

23.2.5. RECEIVE_MESSAGE

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

    ParameterDescription
    pipenameName 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

    ValueDescription
    0A message has been read from the pipe to the local buffer.
    1A specified timeout expired.
  • Example

    DECLARE
        status  pls_integer;
    BEGIN
        status := DBMS_PIPE.RECEIVE_MESSAGE('tbpipe');
    END:

23.2.6. RESET_BUFFER

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:

23.2.7. REMOVE_PIPE

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

    ParameterDescription
    pipenameName of the pipe to remove.
  • Return Value

    ValueDescription
    0Pipe and all messages in the pipe have been deleted successfully.
  • Example

    DECLARE
        status pls_integer;
    BEGIN
        status := DBMS_PIPE.REMOVE_PIPE('tbpipe');                        
    END;
    

23.2.8. SEND_MESSAGE

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

    ParameterDescription
    pipenameName 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

    ValueDescription
    0A message in the local buffer has been successfully saved to the pipe.
    1A 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;

23.2.9. UNIQUE_SESSION_NAME

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;

23.2.10. UNPACK_MESSAGE

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

    ParameterDescription
    itemItem to read from the local buffer.
  • Example

    DECLARE
        msg VARCHAR2(2000);
    BEGIN
        DBMS_PIPE.UNPACK_MESSAGE(msg);
    END;