Chapter 56. UTL_HTTP
Prev   Next

Chapter 56. UTL_HTTP

Table of Contents

56.1. Overview
56.2. Constants
56.2.1. HTTP Version Constant
56.2.2. HTTP Port Constant
56.2.3. Status Code Constants
56.3. Types
56.3.1. HTML_PIECES
56.3.2. req
56.3.3. resp
56.4. Exceptions
56.5. Functions
56.5.1. BEGIN_REQUEST
56.5.2. GET_RESPONSE
56.5.3. REQUEST
56.6. Procedures
56.6.1. END_RESPONSE
56.6.2. GET_BODY_CHARSET
56.6.3. GET_DETAILED_EXCP_SUPPORT
56.6.4. GET_TRANSFER_TIMEOUT
56.6.5. READ_TEXT
56.6.6. SET_BODY_CHARSET
56.6.7. SET_DETAILED_EXCP_SUPPORT
56.6.8. SET_HEADER
56.6.9. SET_RESPONSE_ERROR_CHECK
56.6.10. SET_TRANSFER_TIMEOUT
56.6.11. WRITE_TEXT
56.7. URL
56.8. Example

This chapter briefly introduces the UTL_HTTP package based on HTTP/1.1, and describes how to use the procedures and functions of the package.

56.1. Overview

UTL_HTTP provides client roles based on the web standard (RFC2616) HTTP protocol. It offers subprograms for manipulating the protocol at low-level or simply getting a web page.

56.2. Constants

56.2.1. HTTP Version Constant

HTTP version type.

Details about the HTTP version constants are as follows:

HTTP_VERSION_1      CONSTANT VARCHAR2(10) := 'HTTP/1.1';
DEFAULT_HTTPS_PORT  CONSTANT PLS_INTEGER := 443;

56.2.2. HTTP Port Constant

Network port number used in HTTP.

Details about the HTTP port constants are as follows:

DEFAULT_HTTP_PORT   CONSTANT PLS_INTEGER := 80;
DEFAULT_HTTPS_PORT  CONSTANT PLS_INTEGER := 443;

56.2.3. Status Code Constants

Status of a response received from the server through the HTTP protocol.

Details about the status code constants are as follows in alphabetical order:

HTTP_CONTINUE                   CONSTANT PLS_INTEGER := 100;
HTTP_SWITCHING_PROTOCOLS        CONSTANT PLS_INTEGER := 101;
HTTP_OK                         CONSTANT PLS_INTEGER := 200;
HTTP_CREATED                    CONSTANT PLS_INTEGER := 201;
HTTP_ACCEPTED                   CONSTANT PLS_INTEGER := 202;
HTTP_NON_AUTHORITATIVE_INFO     CONSTANT PLS_INTEGER := 203;
HTTP_NO_CONTENT                 CONSTANT PLS_INTEGER := 204;
HTTP_RESET_CONTENT              CONSTANT PLS_INTEGER := 205;
HTTP_PARTIAL_CONTENT            CONSTANT PLS_INTEGER := 206;
HTTP_MULTIPLE_CHOICES           CONSTANT PLS_INTEGER := 300;
HTTP_MOVED_PERMANENTLY          CONSTANT PLS_INTEGER := 301;
HTTP_FOUND                      CONSTANT PLS_INTEGER := 302;
HTTP_SEE_OTHER                  CONSTANT PLS_INTEGER := 303;
HTTP_NOT_MODIFIED               CONSTANT PLS_INTEGER := 304;
HTTP_USE_PROXY                  CONSTANT PLS_INTEGER := 305;
HTTP_TEMPORARY_REDIRECT         CONSTANT PLS_INTEGER := 307;
HTTP_BAD_REQUEST                CONSTANT PLS_INTEGER := 400;
HTTP_UNAUTHORIZED               CONSTANT PLS_INTEGER := 401;
HTTP_PAYMENT_REQUIRED           CONSTANT PLS_INTEGER := 402;
HTTP_FORBIDDEN                  CONSTANT PLS_INTEGER := 403;
HTTP_NOT_FOUND                  CONSTANT PLS_INTEGER := 404;
HTTP_NOT_ACCEPTABLE             CONSTANT PLS_INTEGER := 406;
HTTP_PROXY_AUTH_REQUIRED        CONSTANT PLS_INTEGER := 407;
HTTP_REQUEST_TIME_OUT           CONSTANT PLS_INTEGER := 408;
HTTP_CONFLICT                   CONSTANT PLS_INTEGER := 409;
HTTP_GONE                       CONSTANT PLS_INTEGER := 410;
HTTP_LENGTH_REQUIRED            CONSTANT PLS_INTEGER := 411;
HTTP_PRECONDITION_FAILED        CONSTANT PLS_INTEGER := 412;
HTTP_REQUEST_ENTITY_TOO_LARGE   CONSTANT PLS_INTEGER := 413;
HTTP_REQUEST_URI_TOO_LARGE      CONSTANT PLS_INTEGER := 414;
HTTP_UNSUPPORTED_MEDIA_TYPE     CONSTANT PLS_INTEGER := 415;
HTTP_REQ_RANGE_NOT_SATISFIABLE  CONSTANT PLS_INTEGER := 416;
HTTP_EXPECTATION_FAILED         CONSTANT PLS_INTEGER := 417;
HTTP_NOT_IMPLEMENTED            CONSTANT PLS_INTEGER := 501;
HTTP_BAD_GATEWAY                CONSTANT PLS_INTEGER := 502;
HTTP_SERVICE_UNAVAILABLE        CONSTANT PLS_INTEGER := 503;
HTTP_GATEWAY_TIME_OUT           CONSTANT PLS_INTEGER := 504;
HTTP_VERSION_NOT_SUPPORTED      CONSTANT PLS_INTEGER := 505;

56.3. Types

This section describes the types provided by the UTL_HTTP package, in alphabetical order.

56.3.1. HTML_PIECES

Used to get a page from the server in the string array type.

Details about the HTML_PIECES type are as follows:

  • Prototype

    TYPE html_pieces IS TABLE OF VARCHAR2(2000) INDEX BY BINARY_INTEGER;

56.3.2. req

Used to contain request information to send to the server.

Details about the req type are as follows:

  • Prototype

    TYPE req IS RECORD
(
    url             VARCHAR2(32767),
    method          VARCHAR2(64),
    http_version    VARCHAR2(64)
);

  • Field

    NameDescription
    urlWeb page address. For more information, refer to “56.7. URL”.
    method

    Method to request to the server.

    Available values are 'OPTIONS', 'GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'TRACE', and 'CONNECT'. (Others are unsupported)

    http_versionProtocol version. For more information about available values, refer to “56.2.1. HTTP Version Constant”.

56.3.3. resp

Used to contain status information about a response received from the server.

Details about the resp type are as follows:

  • Prototype

    TYPE resp IS RECORD
(
    status_code         PLS_INTEGER,
    reason_phrase       VARCHAR2(256),
    http_version        VARCHAR2(64)
);

  • Field

    NameDescription
    status_code3-digit number that expresses the response status of a request. For more information about available values, refer to “56.2.3. Status Code Constants”.
    reason_phraseBrief description about the status code.
    http_versionProtocol version. For more information about available values, refer to “56.2.1. HTTP Version Constant”.

56.4. Exceptions

The following are exceptions provided by the UTL_HTTP package. For more information, refer to "Exceptions" in “56.5. Functions” and “56.6. Procedures”.

  • BAD_ARGUMENT

  • END_OF_BODY

  • REQUEST_FAILED

56.5. Functions

This section describes the functions provided by the UTL_HTTP package, in alphabetical order.

56.5.1. BEGIN_REQUEST

Establishes a connection to the web server, and determines the method used to send a request to the server.

Details about the BEGIN_REQUEST function are as follows:

  • Prototype

    FUNCTION BEGIN_REQUEST 
(
    url           IN VARCHAR2,
    method        IN VARCHAR2 DEFAULT 'GET',
    http_version  IN VARCHAR2 DEFAULT NULL
) 
RETURN req;

  • Parameter

    ParameterDescription
    urlWeb page address. For more information, refer to “56.7. URL”.
    method

    Method used to send a request to the server.

    Available values are 'OPTIONS', 'GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'TRACE', and 'CONNECT'. (Others are unsupported)

    http_versionProtocol version. For more information about available values, refer to “56.2.1. HTTP Version Constant”.

  • Exception

    ExceptionDescription
    REQUEST_FAILED

    Occurs when communication with the web server fails due to an issue with the request.

    Check if URL is correct and the web server is running normally.

    PKG_TRANSFER_TIMEOUTOccurs when the web server does not respond for more than 20 seconds.

  • Example

    This function cannot be used alone. Refer to “56.8. Example”.

56.5.2. GET_RESPONSE

Sends a request to the web server, reads the response header, and prepares to read the message body. If the message header contains "Content-Length: length", it reads the message body up to the specified length. If it contains "Transfer-Encoding: Chunked", the message body is read until a carriage return or line feed character is reached. If it contains both, the former is ignored.

Details about the GET_RESPONSE function are as follows:

  • Prototype

    FUNCTION GET_RESPONSE 
(
    r  IN OUT NOCOPY req
) 
RETURN resp;

  • Parameter

    ParameterDescription
    rRequest identifier.

  • Exception

    ExceptionDescription
    BAD_ARGUMENTOccurs when this function is called without executing BEGIN_REQUEST or SET_HEADER, or a parameter is used incorrectly.

  • Example

    This function cannot be used alone. Refer to “56.8. Example”.

56.5.3. REQUEST

Sends a request to the specified URL on the web server using the GET method of the HTTP/1.1 standard and returns up to 2,000 bytes of data.

Details about the REQUEST function are as follows:

  • Prototype

    FUNCTION REQUEST
(
    url              IN  VARCHAR2,
    proxy            IN  VARCHAR2 DEFAULT NULL,
    wallet_path      IN  VARCHAR2 DEFAULT NULL,
    wallet_password  IN  VARCHAR2 DEFAULT NULL
) 
RETURN VARCHAR2;

  • Parameter

    ParameterDescription
    urlWeb page address. For more information, refer to “56.7. URL”.
    proxyProxy server name. (Default value: NULL, planned for future versions)
    wallet_pathPath in which a wallet required for a client to use HTTPS is saved. (Default value: NULL, planned for future versions)
    wallet_passwordPassword required to open the wallet. (Default value: NULL, planned for future versions)

  • Exception

    ExceptionDescription
    REQUEST_FAILED

    Occurs when communication with the web server fails due to an issue with the request.

    Check if URL is correct and the web server is running normally.

    PKG_TRANSFER_TIMEOUTOccurs when the web server does not respond for more than 20 seconds.

  • Example

    DECLARE 
    resp VARCHAR2(32767);
BEGIN
    resp := UTL_HTTP.REQUEST('http://www.w3.org/Protocols/');
END;

56.6. Procedures

This section describes the procedures provided by the UTL_HTTP package, in alphabetical order.

56.6.1. END_RESPONSE

Ends an HTTP request by returning and initializing all resources such as buffer memory and socket.

Details about the END_RESPONSE procedure are as follows:

  • Prototype

    PROCEDURE END_RESPONSE 
(
    r  IN OUT NOCOPY resp
);

  • Parameter

    ParameterDescription
    rHTTP response.

  • Example

    This procedure cannot be used alone. Refer to “56.8. Example”.

56.6.2. GET_BODY_CHARSET

Gets the name of the default character set of the message body configured in the session.

Details about the GET_BODY_CHARSET procedure are as follows:

  • Prototype

    PROCEDURE GET_BODY_CHARSET
(
    charset    OUT NOCOPY VARCHAR2
);

  • Parameter

    ParameterDescription
    charsetName of the character set configured in the session (canonical character set name).

  • Example

    DECLARE
  charset varchar(64);
BEGIN
    UTL_HTTP.GET_BODY_CHARSET(charset); -- Canonical character set name 
END;
/

56.6.3. GET_DETAILED_EXCP_SUPPORT

Gets whether the UTL_HTTP package will raise a detailed exception during execution. This information is set in each session.

Details about the GET_DETAILED_EXCP_SUPPORT procedure are as follows:

  • Prototype

    PROCEDURE GET_DETAILED_EXCP_SUPPORT
(
    enable    OUT BOOLEAN
);

  • Parameter

    ParameterDescription
    enableIndicates whether detailed exception is enabled.

  • Example

    DECLARE
  enable BOOLEAN;
BEGIN
    UTL_HTTP.GET_DETAILED_EXCP_SUPPORT(enable); -- Enable detailed exception
END;
/

56.6.4. GET_TRANSFER_TIMEOUT

Gets timeout setting of the current session.

Details about the GET_TRANSFER_TIMEOUT procedure are as follows:

  • Prototype

    PROCEDURE GET_TRANSFER_TIMEOUT
(
    timeout    OUT PLS_INTEGER
);

  • Parameter

    ParameterDescription
    timeoutTimeout setting of the session. (Default value: 50 seconds)

  • Example

    DECLARE
      timeout PLS_INTEGER;
BEGIN 
      utl_http.get_transfer_timeout(var);
END;

56.6.5. READ_TEXT

Reads in the body of the requested page without the header.

Details about the READ_TEXT procedure are as follows:

  • Prototype

    PROCEDURE READ_TEXT
(
    r     IN OUT NOCOPY resp,
    data  OUT NOCOPY VARCHAR2,
    len   IN PLS_INTEGER DEFAULT NULL
);

  • Parameter

    ParameterDescription
    rRequest identifier.
    dataBody without the header.
    len

    Maximum string length to read. The value must be greater than 0.

    If the remaining string length is less than this value, the actual length of the string is read.

  • Exception

    ExceptionDescription
    BAD_ARGUMENTOccurs when this procedure is called without executing GET_RESPONSE, or a parameter is used incorrectly.
    END_OF_BODYOccurs when a read is executed after the end of the body has been reached.

  • Example

    This procedure cannot be used alone. Refer to “56.8. Example”.

56.6.6. SET_BODY_CHARSET

Sets the character set of an HTTP request or response message body.

Details about the SET_BODY_CHARSET procedure are as follows:

  • CASE1

    Specifies the character set for a session when the character set is not specified in an HTTP request or response and the Content-Type is not specified in the message header. If the Content-Type is specified in the message header, this setting is ignored. This can be set for each session.

    • Prototype

      PROCEDURE SET_BODY_CHARSET
(
    charset    IN VARCHAR2 DEFAULT NULL
);

    • Parameter

      ParameterDescription
      charset

      Canonical character set name. (Default value: ISO-8859-1)

      (Example: ASCII, UTF-8, EUC-KR, CP949)

  • CASE2

    Specifies the character set for HTTP request message body when the Content-Type is not specified in the message header (default value: ISO-8859-1). The message body string expressed using a database character set is automatically converted to the specified character set. If the Content-Type is specified in the message header, this setting is ignored. The character set can be specified for a single HTTP request.

    • Prototype

      PROCEDURE SET_BODY_CHARSET
(
    r          IN OUT NOCOPY req, 
    charset    IN VARCHAR2 DEFAULT NULL
);

    • Parameters

      ParameterDescription
      charset

      Canonical character set name. (Default value: ISO-8859-1)

      (Example: ASCII, UTF-8, EUC-KR, CP949)

      reqHTTP request.

  • CASE3

    Specifies the character set for HTTP response message body when the Content-Type is not specified in the message header (default value: ISO-8859-1). The message body string expressed using the specified character set is automatically converted to a database character set. If the Content-Type is specified in the message header, this setting is ignored. The character set can be specified for a single HTTP response.

    • Prototype

      PROCEDURE SET_BODY_CHARSET
( 
    r          IN OUT NOCOPY resp, 
    charset    IN VARCHAR2 DEFAULT NULL
);

    • Parameters

      ParameterDescription
      charset

      Canonical character set name. (Default value: ISO-8859-1)

      (Example: ASCII, UTF-8, EUC-KR, CP949)

      respHTTP response.

  • Exception

    ExceptionDescription
    BAD_ARGUMENTOccurs when the specified character set is invalid.

  • Example

    -- Change the character set for HTTP request/response to UTF-8. 
DECLARE
  req   UTL_HTTP.REQ;
  resp  UTL_HTTP.RESP;
  value varchar(32767);
BEGIN
  req := UTL_HTTP.BEGIN_REQUEST('http://www.naver.com',
                                'GET','HTTP/1.1');
  UTL_HTTP.SET_HEADER(req, 'User-Agent', 'Mozilla/4.0');
  UTL_HTTP.WRITE_TEXT(req, 'test_value');
  UTL_HTTP.SET_BODY_CHARSET(req, 'UTF-8');
  resp := UTL_HTTP.GET_RESPONSE(req);
  UTL_HTTP.SET_BODY_CHARSET(resp, 'UTF-8');
  FOR  i in 1 ..  200000
  LOOP
    UTL_HTTP.READ_TEXT(resp, value);
    DBMS_OUTPUT.PUT_LINE ( value );
  END LOOP;
    UTL_HTTP.END_RESPONSE(resp);
exception when others then
    UTL_HTTP.END_RESPONSE(resp);
end;
/
-- Change the default character set of a session for HTTP requests/responses to UTF-8. 
BEGIN
    UTL_HTTP.SET_BODY_CHARSET('UTF-8');
END;
/

56.6.7. SET_DETAILED_EXCP_SUPPORT

Sets whether the UTL_HTTP package will raise a detailed exception during execution. This information is set in each session.

Details about the SET_DETAILED_EXCP_SUPPORT procedure are as follows:

  • Prototype

    PROCEDURE SET_DETAILED_EXCP_SUPPORT
(
    enable    OUT BOOLEAN DEFAULT FALSE
);

  • Parameter

    ParameterDescription
    enableOption to enable detailed exception.

  • Example

    BEGIN
    UTL_HTTP.SET_DETAILED_EXCP_SUPPORT(false); -- disabled
END;
/

56.6.8. SET_HEADER

Sets a request header to send to the server. This procedure can be executed multiple time to add additional header information.

Details about the SET_HEADER procedure are as follows:

  • Prototype

    PROCEDURE SET_HEADER 
(
    r      IN OUT NOCOPY req,
    name   IN VARCHAR2,
    value  IN VARCHAR2
);

  • Parameter

    ParameterDescription
    rRequest identifier.
    nameHeader name.
    valueHeader value.

  • Example

    This procedure cannot be used alone. Refer to “56.8. Example”.

56.6.9. SET_RESPONSE_ERROR_CHECK

Sets whether GET_RESPONSE handles a status code as an exception if the status code received from a web server is about an error. Status codes between 400 and 599 are about an error.

Details about the SET_RESPONSE_ERROR_CHECK procedure are as follows:

  • Prototype

    PROCEDURE SET_RESPONSE_ERROR_CHECK
(
    enable    IN BOOLEAN DEFAULT FALSE
);

  • Parameter

    ParameterDescription
    enableOption to enable the function of checking a status error. (Default value: FALSE)

  • Example

    DECLARE
  req   UTL_HTTP.REQ;
  resp  UTL_HTTP.RESP;
  value VARCHAR2(1024);
BEGIN
  UTL_HTTP.SET_RESPONSE_ERROR_CHECK(enable => TRUE); -- enabled
  req := UTL_HTTP.BEGIN_REQUEST('http://getstatuscode.com/400','GET', 'HTTP/1.1');
  UTL_HTTP.SET_HEADER(req, 'User-Agent', 'Mozilla/4.0');
  resp := UTL_HTTP.GET_RESPONSE(req);
  UTL_HTTP.END_RESPONSE(resp);
END;
/

56.6.10. SET_TRANSFER_TIMEOUT

Sets timeout for the current session.

Details about the SET_TRANSFER_TIMEOUT procedure are as follows:

  • Prototype

    PROCEDURE SET_TRANSFER_TIMEOUT(timeout    IN PLS_INTEGER);

  • Parameter

    ParameterDescription
    timeoutTimeout setting for the session. (Default value: 50 seconds)

  • Example

    BEGIN 
      utl_http.set_transfer_timeout(30);
END;
/

56.6.11. WRITE_TEXT

Sets a request body to send to the server.

Details about the WRITE_TEXT procedure are as follows:

  • Prototype

    PROCEDURE WRITE_TEXT
(
    r     IN OUT NOCOPY REQ,
    data  IN VARCHAR2
);

  • Parameter

    ParameterDescription
    rRequest identifier.
    dataBody text.

  • Exception

    ExceptionDescription
    BAD_ARGUMENTOccurs when the procedure is called without executing BEGIN_REQUEST or SET_HEADER, or a parameter is used incorrectly.
    END_OF_BODYOccurs when a read is executed after the end of the body has been reached.

  • Example

    This procedure cannot be used alone. Refer to “56.8. Example”.

56.7. URL

URL (Uniform Resource Locator) expresses the server web page address in the following format.

scheme://[user[password]@]host[:port]/[...]

The following describes each item.

ItemDescription
schemeAvailable values are http and https, but https is planned for use in future versions.
userUsed for a proxy server. Planned for future versions.
passwordUsed for a proxy server. Planned for future versions.
hostHTTP server host name.
portPort number used for communication.

56.8. Example

The following reads in an html script from the login page of ims.tmaxsoft.com using BEGIN_REQUEST, SET_HEADER, WRITE_TEXT, GET_RESPONSE, and END_RESPONSE.

DECLARE
  req   UTL_HTTP.REQ;
  resp  UTL_HTTP.RESP;
  value VARCHAR2(1024);
BEGIN
req := UTL_HTTP.BEGIN_REQUEST('http://ims.tmaxsoft.com/tody/auth/login.do', 
                              'POST', 'HTTP/1.1');
  UTL_HTTP.SET_HEADER(req, 'User-Agent', 'Mozilla/4.0');
  UTL_HTTP.WRITE_TEXT(req, 'test_value');
  resp := UTL_HTTP.GET_RESPONSE(req);

  LOOP
    UTL_HTTP.READ_TEXT(resp, value);
    DBMS_OUTPUT.PUT_LINE ( value );
  END LOOP;
EXCEPTION
  WHEN UTL_HTTP.END_OF_BODY THEN
  UTL_HTTP.END_RESPONSE(resp);
END;
/
Prev   Next
Chapter 55. UTL_FILE Home Chapter 57. UTL_I18N