3.20 UTL_HTTP

Table of Contents Previous Next


3 Built-In Packages : 3.20 UTL_HTTP

The UTL_HTTP package provides a way to use the HTTP or HTTPS protocol to retrieve information found at an URL. Advanced Server supports the following functions and procedures:
BEGIN_REQUEST(url, method, http_version)
END_REQUEST(r IN OUT)
END_RESPONSE(r IN OUT)
GET_BODY_CHARSET(charset OUT)
GET_FOLLOW_REDIRECT(max_redirects OUT)
GET_HEADER(r IN OUT, n, name OUT, value OUT)
Returns the nth header of the HTTP response.
GET_HEADER_BY_NAME(r IN OUT, name, value OUT, n)
GET_RESPONSE(r IN OUT)
READ_LINE(r IN OUT, data OUT, remove_crlf)
READ_RAW(r IN OUT, data OUT, len)
READ_TEXT(r IN OUT, data OUT, len)
REQUEST_PIECES(url, max_pieces)
SET_FOLLOW_REDIRECT(max_redirects)
SET_FOLLOW_REDIRECT(r IN OUT, max_redirects)
SET_HEADER(r IN OUT, name, value)
SET_TRANSFER_TIMEOUT(r IN OUT, timeout)
WRITE_LINE(r IN OUT, data)
WRITE_RAW(r IN OUT, data)
WRITE_TEXT(r IN OUT, data)
Advanced Server's implementation of UTL_HTTP is a partial implementation when compared to Oracle's version. Only those functions and procedures listed in the table above are supported.
In Advanced Server, an HTTP 4xx or HTTP 5xx response produces a database error; in Oracle, this is configurable but FALSE by default.
In Advanced Server, the UTL_HTTP text interfaces expect the downloaded data to be in the database encoding. All currently-available interfaces are text interfaces. In Oracle, the encoding is detected from HTTP headers; in the absence of the header, the default is configurable and defaults to ISO-8859-1.
The UTL_HTTP exceptions that can be raised in Oracle are not recognized by Advanced Server. In addition, the error codes returned by Advanced Server are not the same as those returned by Oracle.
There are various public constants available with UTL_HTTP. These are listed in the following tables.
The following table contains UTL_HTTP public constants defining HTTP versions and port assignments.
The following table contains UTL_HTTP public status code constants.
The UTL_HTTP package declares a type named HTML_PIECES, which is a table of type VARCHAR2 (2000) indexed by BINARY INTEGER. A value of this type is returned by the REQUEST_PIECES function.
3.20.2 REQ
The REQ record type holds information about each HTTP request.
3.20.3 RESP
The RESP record type holds information about the response from each HTTP request.
The BEGIN_REQUEST function initiates a new HTTP request. A network connection is established to the web server with the specified URL. The signature is:
BEGIN_REQUEST(url IN VARCHAR2, method IN VARCHAR2 DEFAULT 'GET ', http_version IN VARCHAR2 DEFAULT NULL) RETURN UTL_HTTP.REQ
The BEGIN_REQUEST function returns a record of type UTL_HTTP.REQ.
url is the Uniform Resource Locator from which UTL_HTTP will return content.
method is the HTTP method to be used. The default is GET.
http_version is the HTTP protocol version sending the request. The specified values should be either HTTP/1.0 or HTTP/1.1. The default is null in which case the latest HTTP protocol version supported by the UTL_HTTP package is used which is 1.1.
The END_REQUEST procedure terminates an HTTP request. Use the END_REQUEST procedure to terminate an HTTP request without completing it and waiting for the response. The normal process is to begin the request, get the response, then close the response. The signature is:
END_REQUEST(r IN OUT UTL_HTTP.REQ)
r is the HTTP request record.
The END_RESPONSE procedure terminates the HTTP response. The END_RESPONSE procedure completes the HTTP request and response. This is the normal method to end the request and response process. The signature is:
END_RESPONSE(r IN OUT UTL_HTTP.RESP)
r is the HTTP response record.
The GET_BODY_CHARSET program is available in the form of both a procedure and a function. A call to GET_BODY_CHARSET returns the default character set of the body of future HTTP requests.
GET_BODY_CHARSET(charset OUT VARCHAR2)
charset is the character set of the body.
The following is an example of the GET_BODY_CHARSET function.
The GET_FOLLOW_REDIRECT procedure returns the current setting for the maximum number of redirections allowed. The signature is:
GET_FOLLOW_REDIRECT(max_redirects OUT INTEGER)
max_redirects is maximum number of redirections allowed.
3.20.9 GET_HEADER
The GET_HEADER procedure returns the nth header of the HTTP response. The signature is:
GET_HEADER(r IN OUT UTL_HTTP.RESP, n INTEGER, name OUT VARCHAR2, value OUT VARCHAR2)
r is the HTTP response record.
n is the nth header of the HTTP response record to retrieve.
name is the name of the response header.
value is the value of the response header.
The GET_HEADER_BY_NAME procedure returns the header of the HTTP response according to the specified name. The signature is:
GET_HEADER_BY_NAME(r IN OUT UTL_HTTP.RESP, name VARCHAR2, value OUT VARCHAR2, n INTEGER DEFAULT 1)
r is the HTTP response record.
name is the name of the response header to retrieve.
value is the value of the response header.
n is the nth header of the HTTP response record to retrieve according to the values specified by name. The default is 1.
The GET_HEADER_COUNT function returns the number of HTTP response headers. The signature is:
GET_HEADER_COUNT(r IN OUT UTL_HTTP.RESP) RETURN INTEGER
r is the HTTP response record.
3.20.12 GET_RESPONSE
The GET_RESPONSE function sends the network request and returns any HTTP response. The signature is:
GET_RESPONSE(r IN OUT UTL_HTTP.REQ) RETURN UTL_HTTP.RESP
This function returns a UTL_HTTP.RESP record.
r is the HTTP request record.
The GET_RESPONSE_ERROR_CHECK procedure returns whether or not response error check is set. The signature is:
GET_RESPONSE_ERROR_CHECK(enable OUT BOOLEAN)
enable returns TRUE if response error check is set, otherwise it returns FALSE.
The GET_TRANSFER_TIMEOUT procedure returns the current, default transfer timeout setting for HTTP requests. The signature is:
GET_TRANSFER_TIMEOUT(timeout OUT INTEGER)
timeout is the transfer timeout setting in seconds.
3.20.15 READ_LINE
The READ_LINE procedure returns the data from the HTTP response body in text form until the end of line is reached. A CR character, a LF character, a CR LF sequence, or the end of the response body constitutes the end of line. The signature is:
READ_LINE(r IN OUT UTL_HTTP.RESP, data OUT VARCHAR2, remove_crlf BOOLEAN DEFAULT FALSE)
r is the HTTP response record.
data is the response body in text form.
Set remove_crlf to TRUE to remove new line characters, otherwise set to FALSE. The default is FALSE.
3.20.16 READ_RAW
The READ_RAW procedure returns the data from the HTTP response body in binary form. The number of bytes returned is specified by the len parameter. The signature is:
READ_RAW(r IN OUT UTL_HTTP.RESP, data OUT RAW, len INTEGER)
r is the HTTP response record.
data is the response body in binary form.
Set len to the number of bytes of data to be returned.
3.20.17 READ_TEXT
The READ_TEXT procedure returns the data from the HTTP response body in text form. The maximum number of characters returned is specified by the len parameter. The signature is:
READ_TEXT(r IN OUT UTL_HTTP.RESP, data OUT VARCHAR2, len INTEGER)
r is the HTTP response record.
data is the response body in text form.
Set len to the maximum number of characters to be returned.
3.20.18 REQUEST
The REQUEST function returns the first 2000 bytes retrieved from a user-specified URL. The signature is:
url is the Uniform Resource Locator from which UTL_HTTP will return content.
The REQUEST_PIECES function returns a table of 2000-byte segments retrieved from an URL. The signature is:
REQUEST_PIECES(url IN VARCHAR2, max_pieces NUMBER IN DEFAULT 32767) RETURN UTL_HTTP.HTML_PIECES
url is the Uniform Resource Locator from which UTL_HTTP will return content.
max_pieces specifies the maximum number of 2000-byte segments that the REQUEST_PIECES function will return. If max_pieces specifies more units than are available at the specified url, the final unit will contain fewer bytes.
The SET_BODY_CHARSET procedure sets the default character set of the body of future HTTP requests. The signature is:
SET_BODY_CHARSET(charset VARCHAR2 DEFAULT NULL)
charset is the character set of the body of future requests. The default is null in which case the database character set is assumed.
The SET_FOLLOW_REDIRECT procedure sets the maximum number of times the HTTP redirect instruction is to be followed in the response to this request or future requests. This procedures has two signatures:
SET_FOLLOW_REDIRECT(max_redirects IN INTEGER DEFAULT 3)
SET_FOLLOW_REDIRECT(r IN OUT UTL_HTTP.REQ, max_redirects IN INTEGER DEFAULT 3)
r is the HTTP request record.
max_redirects is maximum number of redirections allowed. Set to 0 to disable redirections. The default is 3.
3.20.22 SET_HEADER
The SET_HEADER procedure sets the HTTP request header. The signature is:
SET_HEADER(r IN OUT UTL_HTTP.REQ, name IN VARCHAR2, value IN VARCHAR2 DEFAULT NULL)
r is the HTTP request record.
name is the name of the request header.
value is the value of the request header. The default is null.
The SET_RESPONSE_ERROR_CHECK procedure determines whether or not HTTP 4xx and 5xx status codes returned by the GET_RESPONSE function should be interpreted as errors. The signature is:
SET_RESPONSE_ERROR_CHECK(enable IN BOOLEAN DEFAULT FALSE)
Set enable to TRUE if HTTP 4xx and 5xx status codes are to be treated as errors, otherwise set to FALSE. The default is FALSE.
The SET_TRANSFER_TIMEOUT procedure sets the default, transfer timeout setting for waiting for a response from an HTTP request. This procedure has two signatures:
SET_TRANSFER_TIMEOUT(timeout IN INTEGER DEFAULT 60)
SET_TRANSFER_TIMEOUT(r IN OUT UTL_HTTP.REQ, timeout IN INTEGER DEFAULT 60)
r is the HTTP request record.
timeout is the transfer timeout setting in seconds for HTTP requests. The default is 60 seconds.
3.20.25 WRITE_LINE
The WRITE_LINE procedure writes data to the HTTP request body in text form; the text is terminated with a CRLF character pair. The signature is:
WRITE_LINE(r IN OUT UTL_HTTP.REQ, data IN VARCHAR2)
r is the HTTP request record.
data is the request body in TEXT form.
The following example writes data (Account balance $500.00) in text form to the request body to be sent using the HTTP POST method. The data is sent to a hypothetical web application (post.php) that accepts and processes data.
Assuming the web application successfully processed the POST method, the following output would be displayed:
3.20.26 WRITE_RAW
The WRITE_RAW procedure writes data to the HTTP request body in binary form. The signature is:
WRITE_RAW(r IN OUT UTL_HTTP.REQ, data IN RAW)
r is the HTTP request record.
data is the request body in binary form.
The following example writes data in binary form to the request body to be sent using the HTTP POST method to a hypothetical web application that accepts and processes such data.
The text string shown in the HEXTORAW function is the hexadecimal translation of the text Testing POST method in HTTP request.
Assuming the web application successfully processed the POST method, the following output would be displayed:
3.20.27 WRITE_TEXT
The WRITE_TEXT procedure writes data to the HTTP request body in text form. The signature is:
WRITE_TEXT(r IN OUT UTL_HTTP.REQ, data IN VARCHAR2)
r is the HTTP request record.
data is the request body in text form.
The following example writes data (Account balance $500.00) in text form to the request body to be sent using the HTTP POST method. The data is sent to a hypothetical web application (post.php) that accepts and processes data.
Assuming the web application successfully processed the POST method, the following output would be displayed:

3 Built-In Packages : 3.20 UTL_HTTP

Table of Contents Previous Next