HTTP_VARIABLE function [Web service]

Returns the value of an HTTP variable.

Syntax

HTTP_VARIABLE( var-name [ , instance [ , attribute ] ] )

Parameters

var-name – The name of an HTTP variable.
instance – If more than one variable has the same name, the instance number of the field instance, or NULL to get the first one. Useful for SELECT lists that permit multiple selections.
attribute – In a multi-part request, the attribute can specify a header field name which returns the value of the header for the multi-part name.
When an attribute is not specified, the returned value is %-decoded and character-set translated to the database character set. UTF %-encoded data is supported in this mode.

The attribute can also be one of the following modes:
- '@BINARY' – Returns a x-www-form-urlencoded binary data value. This mode indicates that the returned value is %-decoded and not character-set translated. UTF-8 %-encoding is not supported in this mode since %-encoded data are simply decoded into their equivalent byte representation.
- '@TRANSPORT' – Returns the raw HTTP transport form of the value, where %-encodings are preserved.

Returns

LONG VARCHAR.

Note: The result data type is a LONG VARCHAR. If you use HTTP_VARIABLE in a SELECT INTO statement, you must have an Unstructured Data Analytics Option license or use CAST and set HTTP_VARIABLE to the correct data type and size.

Remarks

This function returns the value of the named HTTP variable. It is used when processing an HTTP request within a web service.

If var-name does not exist, the return value is NULL.

When the web service request is a POST, and the variable data is posted as multipart/form-data, the HTTP server receives HTTP headers for each individual variable. When the attribute parameter is specified, the HTTP_VARIABLE function returns the associated multipart/form-data header value from the POST request for the particular variable. For a variable representing a file, an attribute of Content-Disposition, Content-Type, and @BINARY would return the filename, media-type, and file contents respectively.

Normally, all input data goes through character set translation between the client (for example, a browser) character set, and the character set of the database. However, if @BINARY is specified for attribute, the variable value is returned without going through character set translation or %-decoding. This may be useful when receiving binary data, such as image data, from a client.

This function returns NULL when the specified instance does not exist or when the function is called from outside of an execution of a web service.

Standards and compatibility

SQL/2008 – Vendor extension.

Examples

When used within a stored procedure that is called by an HTTP web service, the following example retrieves the values of the HTTP variables indicated in the sample URL.

-- http://sample.com/demo/ShowDetail?product_id=300&customer_id=101
BEGIN
  DECLARE v_customer_id LONG VARCHAR;
  DECLARE v_product_id LONG VARCHAR;
  SET v_customer_id = HTTP_VARIABLE( 'customer_id' );
  SET v_product_id = HTTP_VARIABLE( 'product_id' );
  CALL ShowSalesOrderDetail( v_customer_id, v_product_id );
END;

When used within a stored procedure that is called by an HTTP web service, the following statements request the Content-Disposition and Content-Type headers of the image variable:

SET v_name = HTTP_VARIABLE( 'image', NULL, 'Content-Disposition' );
SET v_type = HTTP_VARIABLE( 'image', NULL, 'Content-Type' );

When used within a stored procedure that is called by an HTTP web service, the following statement requests the value of the image variable in its current character set, that is, without going through character set translation:

SET v_image = HTTP_VARIABLE( 'image', NULL, '@BINARY' );