Chapter 61. UTL_TCP
Prev   Next

Chapter 61. UTL_TCP

Table of Contents

61.1. Overview
61.2. Types
61.2.1. CONNECTION
61.3. Constants
61.3.1. CRLF
61.4. Procedures and Functions
61.4.1. CLOSE_ALL_CONNECTIONS
61.4.2. CLOSE_CONNECTION
61.4.3. GET_LINE
61.4.4. GET_RAW
61.4.5. GET_TEXT
61.4.6. OPEN_CONNECTION
61.4.7. READ_LINE
61.4.8. READ_RAW
61.4.9. READ_TEXT
61.4.10. WRITE_LINE
61.4.11. WRITE_RAW
61.4.12. WRITE_TEXT

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

61.1. Overview

UTL_TCP provides procedures and functions that can function like TCP/IP clients.

This package is useful for transmitting email and connecting to the Internet for many Internet environments that use TCP/IP protocols.

61.2. Types

This section describes the type provided by the UTL_TCP package.

61.2.1. CONNECTION

Represents a TCP/IP connection object that uses UTL_TCP.

Details about the CONNECTION type are as follows:

  • Prototype

    TYPE CONNECTION IS RECORD (
    pvid            PLS_INTEGER,    
    remote_host     VARCHAR2(255),  
    remote_port     PLS_INTEGER,    
    tx_timeout      PLS_INTEGER     
);

  • Field

    NameDescription
    pvidID of the TCP/IP connection object. Do not modify this ID.
    remote_hostAddress of the connected TCP server.
    remote_portThe port number of the connected TCP server.
    tx_timeout

    Time allowed, in seconds, for a read or write operation that uses TCP communication. After the timeout, a timeout error occurs and the connection is returned.

    • NULL: maintain the connection until a response is received.

    • 0: Close the transaction immediately.

61.3. Constants

61.3.1. CRLF

String with carriage return and line feed characters.

  • Definition

        CRLF CONSTANT VARCHAR2(2) := unistr('\000D\000A');

61.4. Procedures and Functions

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

61.4.1. CLOSE_ALL_CONNECTIONS

Closes all open TCP/IP connections.

Details about the CLOSE_ALL_CONNECTIONS procedure are as follows:

  • Prototype

    UTL_TCP.CLOSE_ALL_CONNECTIONS

  • Example

    DECLARE
    c UTL_TCP.CONNECTION;
BEGIN
    c := UTL_TCP.OPEN_CONNECTION('localhost', 25);
    UTL_TCP.CLOSE_CONNECTION(c);
EXCEPTION WHEN OTHERS THEN
    UTL_TCP.CLOSE_ALL_CONNECTIONS;
END;

61.4.2. CLOSE_CONNECTION

Closes the current TCP/IP connection.

Details about the CLOSE_CONNECTION procedure are as follows:

  • Prototype

    UTL_TCP.CLOSE_CONNECTION 
(
    c IN OUT NOCOPY connection
)

  • Parameter

    ParameterDescription
    cConnection object to close. The type is UTL_TCP.CONNECTION.

  • Example

    DECLARE
    c UTL_TCP.CONNECTION;
BEGIN
    c := UTL_TCP.OPEN_CONNECTION('localhost', 25);
    UTL_TCP.CLOSE_CONNECTION(c);
END;

61.4.3. GET_LINE

Reads and returns a line of text from the remote TCP server. For further information, refer to the description of the READ_LINE function, which is similar to this function.

Details about the GET_LINE function are as follows:

  • Prototype

    UTL_TCP.GET_LINE 
(
    c               IN OUT NOCOPY   connection,
    remove_crlf     IN              BOOLEAN     DEFAULT FALSE,
    peek            IN              BOOLEAN     DEFAULT FALSE
) RETURN VARCHAR2

  • Parameter

    ParameterDescription
    cConnection object to read from. The type is UTL_TCP.CONNECTION.
    remove_crlfIf set to TRUE, CR/LF characters are removed.
    peekIf set to TRUE, data is read without being removed from the TCP input queue.

  • Return Value

    The retrieved text.

  • Example

    DECLARE
    c UTL_TCP.CONNECTION;
    data VARCHAR2(100);
BEGIN
    c := UTL_TCP.OPEN_CONNECTION('localhost', 80);
    data := UTL_TCP.GET_LINE(c); 
END;

61.4.4. GET_RAW

Reads and returns binary data from the remote TCP server. For further information, refer to the description of the READ_RAW function, which is similar to this function.

Details about the GET_RAW function are as follows:

  • Prototype

    UTL_TCP.GET_RAW 
(
    c       IN OUT NOCOPY   connection,
    len     IN              PLS_INTEGER DEFAULT 1,
    peek    IN              BOOLEAN     DEFAULT FALSE
) 
RETURN RAW;

  • Parameter

    ParameterDescription
    cConnection object to read from. The type is UTL_TCP.CONNECTION.
    lenNumber of binary bytes to read. The default value is 1.
    peekIf set to TRUE, data is read without being removed from the TCP input queue.

  • Return Value

    The retrieved binary data.

  • Example

    DECLARE
    c UTL_TCP.CONNECTION;
    data RAW(100);
BEGIN
    c := UTL_TCP.OPEN_CONNECTION('localhost', 80);
    data := UTL_TCP.GET_RAW(c, 10);  -- Requested to retrieve 10 bytes of text.
END;

61.4.5. GET_TEXT

Reads and returns text from the remote TCP server. For further information, refer to the description of the READ_TEXT procedure, which is similar to this function.

Details about the GET_TEXT function are as follows:

  • Prototype

    UTL_TCP.GET_TEXT 
(
    c      IN OUT NOCOPY   connection,
    len    IN              PLS_INTEGER DEFAULT 1,
    peek   IN              BOOLEAN     DEFAULT FALSE
) 
RETURN VARCHAR2;

  • Parameter

    ParameterDescription
    cConnection object to read from. The type is UTL_TCP.CONNECTION.
    lenNumber of binary bytes to read. The default value is 1.
    peekIf set to TRUE, data is read without being removed from the TCP input queue.

  • Return Value

    The retrieved text.

  • Example

    DECLARE
    c UTL_TCP.CONNECTION;
    data VARCHAR2(100);
BEGIN
    c := UTL_TCP.OPEN_CONNECTION('localhost', 80);
    data := UTL_TCP.GET_TEXT(c, 10);  -- Requested to retrieve 10 bytes of text.
END;

61.4.6. OPEN_CONNECTION

Creates a TCP/IP connection to a remote TCP server.

Details about the OPEN_CONNECTION procedure are as follows:

  • Prototype

    UTL_TCP.OPEN_CONNECTION 
(
    remote_host     IN  VARCHAR2,                     
    remote_port     IN  PLS_INTEGER,                  
    tx_timeout      IN  PLS_INTEGER DEFAULT NULL
)  
RETURN UTL_TCP.CONNECTION;

  • Parameter

    ParameterDescription
    remote_hostTCP server address to connect to. The default value is localhost.
    remote_portPort number of the TCP server to connect to.
    tx_timeout

    Time allowed, in seconds, for a read or write operation that uses TCP communication. After the timeout, a timeout error occurs and the connection is returned.

    • NULL: maintain the connection until a response is received.

    • 0: Close the transaction immediately.

  • Return Value

    The UTL_TCP.CONNECTION type object that contains TCP/IP connection information.

  • Example

    DECLARE
    c UTL_TCP.CONNECTION;
BEGIN
    c := UTL_TCP.OPEN_CONNECTION('localhost', 25);
END;

61.4.7. READ_LINE

Reads a line of text from the remote TCP server and returns the number of characters read.

If a timeout value is specified, a TRANSFER_TIMEOUT exception occurs when the timeout expires. If timeout is specified as NULL, a timeout will not occur.

Details about the READ_LINE function are as follows:

  • Prototype

    UTL_TCP.READ_LINE 
(
    c               IN OUT NOCOPY   connection,
    data            IN OUT NOCOPY   VARCHAR2,
    remove_crlf     IN              BOOLEAN     DEFAULT FALSE,
    peek            IN              BOOLEAN     DEFAULT FALSE
) 
RETURN PLS_INTEGER;

  • Parameter

    ParameterDescription
    cConnection object to read from. The type is UTL_TCP.CONNECTION.
    dataRetrieved text.
    remove_crlfIf set to TRUE, CR/LF characters are removed.
    peekIf set to TRUE, data is read without being removed from the TCP input queue.

  • Return Value

    The number of characters read.

  • Example

    DECLARE
    c UTL_TCP.CONNECTION;
    data VARCHAR2(100);
    len PLS_INTEGER;
BEGIN
    c := UTL_TCP.OPEN_CONNECTION('localhost', 80);
    len := UTL_TCP.READ_LINE(c, data); 
END;

61.4.8. READ_RAW

Reads binary data from the remote TCP server and returns the number of bytes read.

If a timeout value is specified, a TRANSFER_TIMEOUT exception occurs when the timeout expires. If timeout is specified as NULL, a timeout will not occur.

Details about the READ_RAW function are as follows:

  • Prototype

    UTL_TCP.READ_RAW 
(
    c      IN OUT NOCOPY   connection,
    data   IN OUT NOCOPY   RAW,
    len    IN              PLS_INTEGER DEFAULT 1,
    peek   IN              BOOLEAN     DEFAULT FALSE
) 
RETURN PLS_INTEGER;

  • Parameter

    ParameterDescription
    cConnection object to read from. The type is UTL_TCP.CONNECTION.
    dataRetrieved data.
    lenNumber of bytes to read.
    peekIf set to TRUE, data is read without being removed from the TCP input queue.

  • Return Value

    Number of bytes read.

  • Example

    DECLARE
    c UTL_TCP.CONNECTION;
    data RAW(100);
    len PLS_INTEGER;
BEGIN
    c := UTL_TCP.OPEN_CONNECTION('localhost', 80);
    len := UTL_TCP.READ_RAW(c, data, 10); 
END;

61.4.9. READ_TEXT

Reads text from the remote TCP server and returns the number of bytes read.

If a timeout value is specified, a TRANSFER_TIMEOUT exception occurs when the timeout expires. If timeout is specified as NULL, a timeout will not occur.

Details about the READ_TEXT function are as follows:

  • Prototype

    UTL_TCP.READ_TEXT 
(
    c     IN OUT NOCOPY   connection,
    data  IN OUT NOCOPY   VARCHAR2,
    len   IN              PLS_INTEGER DEFAULT 1,
    peek  IN              BOOLEAN     DEFAULT FALSE
) 
RETURN PLS_INTEGER;

  • Parameter

    ParameterDescription
    cConnection object to read from. The type is UTL_TCP.CONNECTION.
    dataRetrieved data.
    lenNumber of bytes to read.
    peekIf set to TRUE, data is read without being removed from the TCP input queue.

  • Return Value

    The number of bytes read.

  • Example

    DECLARE
    c UTL_TCP.CONNECTION;
    data VARCHAR2(100);
    len PLS_INTEGER;
BEGIN
    c := UTL_TCP.OPEN_CONNECTION('localhost', 80);
    len := UTL_TCP.READ_TEXT(c, data, 10); 
END;

61.4.10. WRITE_LINE

Transmits a line of text to the remote TCP server. A newline character is appended to the input text before it is transmitted.

Details about the WRITE_LINE function are as follows:

  • Prototype

    UTL_TCP.WRITE_LINE 
(
    c    IN OUT NOCOPY   connection,                       
    data IN              VARCHAR2    DEFAULT NULL
) 
RETURN PLS_INTEGER;

  • Parameter

    ParameterDescription
    cConnection object to transmit to. The type is UTL_TCP.CONNECTION.
    dataText to transmit.

  • Return Value

    The actual number of characters transmitted.

  • Example

    DECLARE
    c UTL_TCP.CONNECTION;
    rc INTEGER;
BEGIN
    c := UTL_TCP.OPEN_CONNECTION('localhost', 80);
    rc := UTL_TCP.WRITE_LINE(c, 'GET / HTTP/1.0');
END;

61.4.11. WRITE_RAW

Transmits binary data to the remote TCP server.

Details about the WRITE_RAW function are as follows:

  • Prototype

    UTL_TCP.WRITE_RAW 
(
    c     IN OUT NOCOPY   connection,                       
    data  IN              RAW,                              
    len   IN              PLS_INTEGER DEFAULT NULL
) 
RETURN PLS_INTEGER;

  • Parameter

    ParameterDescription
    cConnection object to transmit to. The type is UTL_TCP.CONNECTION.
    dataBinary data to transmit.
    lenNumber of bytes to transmit. By default, all data will be transmitted.

  • Return Value

    The actual number of bytes transmitted.

  • Example

    DECLARE
    c UTL_TCP.CONNECTION;
    rc INTEGER;
BEGIN
    c := UTL_TCP.OPEN_CONNECTION('localhost', 80);
    rc := UTL_TCP.WRITE_RAW(c, '0D0A'); -- Binary data whose hex value is 0d 0a 
                                           is transmitted.
END;

61.4.12. WRITE_TEXT

Transmits text data to the remote TCP server.

Details about the WRITE_TEXT function are as follows:

  • Prototype

    UTL_TCP.WRITE_TEXT 
(
    c    IN OUT NOCOPY   connection,                       
    data IN              VARCHAR2,                         
    len  IN              PLS_INTEGER DEFAULT NULL
) 
RETURN PLS_INTEGER;

  • Parameter

    ParameterDescription
    cConnection object to transmit to. The type is UTL_TCP.CONNECTION.
    dataText to transmit.
    lenNumber of characters to transmit. By default, all data will be transmitted.

  • Return Value

    The actual number of characters transmitted.

  • Example

    DECLARE
    c UTL_TCP.CONNECTION;
    rc INTEGER;
BEGIN
    c := UTL_TCP.OPEN_CONNECTION('localhost', 8080);
    rc := UTL_TCP.WRITE_TEXT(c, 'TIBEROTMAX', 6); -- From the text 'TIBEROTMAX',  
                                                     only 'TIBERO
END;
Prev   Next
Chapter 60. UTL_RECOMP Home Chapter 62. UTL_URL