UTL_HTTP , 5 of 59

REQUEST_PIECES Function

This function returns a PL/SQL table of 2000-byte pieces of the data retrieved from the given URL.

Syntax

type html_pieces is table of varchar2(2000) index by binary_integer;

UTL_HTTP.REQUEST_PIECES (

url             IN VARCHAR2,
max_pieces      IN NATURAL DEFAULT 32767,
proxy           IN VARCHAR2 DEFAULT NULL,
wallet_path     IN VARCHAR2 DEFAULT NULL,
wallet_password IN VARCHAR2 DEFAULT NULL)

RETURN html_pieces;

Pragmas

pragma restrict_references (request_pieces, wnds, rnds, wnps, rnps);

Parameters

Table 78-8 shows the parameters for the REQUEST_PIECES function.

Table 78-8 REQUEST_PIECES Function Parameters

Parameter	Description
url	Universal resource locator.
max_pieces	(Optional) The maximum number of pieces (each 2000 characters in length, except for the last, which may be shorter), that `REQUEST_PIECES` should return. If provided, then that argument should be a positive integer.
proxy	(Optional) Specifies a proxy server to use when making the HTTP request. See `set_proxy` for the full format of the proxy setting.
`wallet_path`	(Optional) Specifies a client-side wallet. The client-side wallet contains the list of trusted certificate authorities required for HTTPS request. The format of wallet_path is 'file:/<local-dir-for-client-side-wallet>'. The format of wallet_path on a PC is, for example, file:c:\WINNT\Profiles\<username>\WALLETS, and in Unix is, for example, file:/home/<username>/wallets. When the UTL_HTTP package is executed in the Oracle database server, the wallet is accessed from the database server. Therefore, the wallet path must be accessible from the database server. See `set_wallet` for the description on how to set up an Oracle wallet. Non-HTTPS requests do not require an Oracle wallet.
`wallet_password`	(Optional) Specifies the password required to open the wallet.

Returns

REQUEST_PIECES returns a PL/SQL table of type UTL_HTTP.HTML_PIECES. Each element of that PL/SQL table is a string of maximum length 2000. The elements of the PL/SQL table returned by REQUEST_PIECES are successive pieces of the data obtained from the HTTP request to that URL.

Exceptions

INIT_FAILED
REQUEST_FAILED

Usage Notes

The URL passed as an argument to this function will not be examined for illegal characters, for example, spaces, per the URL specification RFC 2396. The caller should escape those characters with the UTL_URL package. See the comments of the package for the list of legal characters in URLs. Note that URLs should consist of US-ASCII characters only. The use of non-US-ASCII characters in a URL is generally unsafe.

Each entry of the PL/SQL table (the "pieces") returned by this function may not be filled to their fullest capacity. The function may start filling the data in the next piece before the previous "piece" is totally full.

Please see the documentation of the function set_wallet on the use of an Oracle wallet, which is required for accessing HTTPS Web servers.

Unless response error check is turned on, this function does not raise an exception when a 4xx or 5xx response is received from the Web server. Instead, it returns the formatted error message from the Web server:

<HTML> 
<HEAD> 
<TITLE>Error Message</TITLE> 
</HEAD> 
<BODY> 
<H1>Fatal Error 500</H1> 
Can't Access Document:  http://home.nothing.comm. 
<P> 
<B>Reason:</B> Can't locate remote host:  home.nothing.comm. 
<P> 
<P><HR> 
<ADDRESS><A HREF="http://www.w3.org"> 
CERN-HTTPD3.0A</A></ADDRESS> 
</BODY> 
</HTML>

Example

SET SERVEROUTPUT ON 




DECLARE 

x   utl_http.html_pieces; 
len PLS_INTEGER; 

BEGIN 

x := utl_http.request_pieces('http://www.oracle.com/', 100); 
dbms_output.put_line(x.count || ' pieces were retrieved.'); 
dbms_output.put_line('with total length '); 
IF x.count < 1 THEN 


dbms_output.put_line('0'); 

  ELSE 

len := 0; 
FOR i in 1..x.count LOOP 


len := len + length(x(i)); 


END LOOP; 
dbms_output.put_line(i); 

  END IF; 
END; 
/ 
-- Output 
Statement processed. 
4 pieces were retrieved. 
with total length 
7687