sa_set_http_option system procedure

Permits a web service to set an HTTP option for process control.

Syntax

sa_set_http_option( 
optname 
, val
)

Arguments

optname – Use this CHAR(128) parameter to specify a string containing the name of one of the HTTP options.
The supported options are:
- CharsetConversion – Use this option to control whether the result set is to be automatically converted from the character set encoding of the database to the character set encoding of the client. The only permitted values are ON and OFF. The default value is ON.
- AcceptCharset – Use this option to specify the web server's preferences for a response character set encoding. One or more character set encodings may be specified in order of preference. The syntax for this option conforms to the syntax used for the HTTP Accept-Charset request-header field specification in RFC2616 Hypertext Transfer Protocol.
  An HTTP client such as a web browser may provide an Accept-Charset request header which specifies a list of character set encodings ordered by preference. Optionally, each encoding may be given an associated quality value (q=qvalue) which represents the client's preference for that encoding. By default, the quality value is 1 (q=1). Here is an example:
```
Accept-Charset: iso-8859-5, utf-8;q=0.8
```
  A plus sign (+) in the AcceptCharset HTTP option value may be used as a shortcut to represent the current database character set encoding. The plus sign also indicates that the database character set encoding should take precedence if the client also specifies the encoding in its list, regardless of the quality value assigned by the client.
  
  An asterisk (*) in the AcceptCharset HTTP option may be used to indicate that the web service should use a character set encoding preferred by the client, as long as it is also supported by the server, when client and server do not have an intersecting list.
  
  When sending the response, the first character set encoding preferred by both client and web service is used. The client's order of preference takes precedence. If no mutual encoding preference exists, then the web service's most preferred encoding is used, unless an asterisk (*) appears in the web service list in which case the client's most preferred encoding is used.
  
  If the AcceptCharset HTTP option is not used, the most preferred character set encoding specified by the client and supported by the server is used. If none of the encodings specified by the client are supported (or the client does not send an Accept-Charset request header) then the database character set encoding is used.
  
  If a client does not send an Accept-Charset header then one of the following actions are taken:
  - If the AcceptCharset HTTP option has not been specified then the web server will use the database character set encoding.
  - If the AcceptCharset HTTP option has been specified then the web server will use its most preferred character set encoding.
  If a client does send an Accept-Charset header then one of the following actions are taken:
  - If the AcceptCharset HTTP option has not been specified then the web server will attempt to use one of the client's preferred character set encodings, starting with the most preferred encoding. If the web server does not support any of the client's preferred encodings, it will use the database character set encoding.
  - If the AcceptCharset HTTP option has been specified then the web server will attempt to use the first preferred character set encoding common to both lists, starting with the client's most preferred encoding. For example, if the client sends an Accept-Charset header listing, in order of preference, encodings iso-a, iso-b, and iso-c and the web server prefers iso-b, then iso-a, and finally iso-c, then iso-a will be selected.
```
Web client: iso-a, iso-b, iso-c
Web server: iso-b, iso-a, iso-c
```
    If the intersection of the two lists is empty, then the web server's first preferred character set is used. From the following example, encoding iso-d will be used.
```
Web client: iso-a, iso-b, iso-c
Web server: iso-d, iso-e, iso-f
```
    If an asterisk ('*') was included in the AcceptCharset HTTP option, then emphasis would be placed on the client's choice of encodings, resulting in iso-a being used. Essentially, the use of an asterisk guarantees that the intersection of the two lists will not be empty.
  The ideal situation occurs when both client and web service use the database character set encoding since this eliminates the need for character set translation and improves the response time of the web server.
  
  If the CharsetConversion option has been set to OFF, then AcceptCharset processing is not performed.
- SessionID – Use this option to create, delete or rename an HTTP session. The database connection is persisted when a web service sets this option to create an HTTP session but sessions are not persisted across server restarts. If already within a session context, this call will rename the session to the new session ID. When called with a NULL value, the session will be deleted when the web service terminates.
  The generated session keys are limited to 128 characters in length and unique across databases if multiple databases are loaded.
- SessionTimeout – Use this option to specify the amount of time, in minutes, that the HTTP session persists during inactivity. This time-out period is reset whenever an HTTP request uses the given session. The session is automatically deleted when the SessionTimeout is exceeded.
val – Use this LONG VARCHAR parameter to specify the value to which the named option should be set.

Remarks

Use this procedure within statements or procedures that handle web services to set options.

When sa_set_http_option is called from within a procedure invoked through a web service, and either the option or option value is invalid, an error is returned.

Privileges

None

Side effects

None

Examples

The following example illustrates the use of sa_set_http_option to indicate the web service's preference for database character set encoding. The UTF-8 encoding is specified as a second choice. The asterisk (*) indicates that the web service is willing to use the character set encoding most preferred by the client, provided that it is supported by the web server.

CALL sa_set_http_option( 'AcceptCharset', '+,UTF-8,*');

The following example illustrates the use of sa_set_http_option to correctly identify the character encoding in use by the web service. In this example, the web server is connected to a 1251CYR database and is prepared to serve HTML documents containing the Cyrillic alphabet to any web browser.

CREATE OR REPLACE PROCEDURE cyrillic_html()
RESULT (html_doc XML)
BEGIN
  DECLARE pos INT;
  DECLARE charset VARCHAR(30);
  CALL sa_set_http_option( 'AcceptCharset', 'iso-8859-5, utf-8' );
  SET charset = CONNECTION_PROPERTY( 'CharSet' );
  -- Change any IANA labels like ISO_8859-5:1988 
  -- to ISO_8859-5 for Firefox.
  SET pos = LOCATE( charset, ':' );
  IF pos > 0 THEN
    SET charset = LEFT( charset, pos - 1 );
  END IF;
  CALL sa_set_http_header( 'Content-Type', 'text/html; charset=' || 
        charset );
  SELECT  '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">' || 
    XMLCONCAT(
      XMLELEMENT('HTML',  
        XMLELEMENT('HEAD',
          XMLELEMENT('TITLE', 'Cyrillic characters')
        ),
        XMLELEMENT('BODY',
          XMLELEMENT('H1', 'First 5 lowercase Russian letters'),
          XMLELEMENT('P', UNISTR('\u0430\u0431\u0432\u0433\u0434'))
        )
      )
    );
END;

CREATE SERVICE cyrillic 
TYPE 'RAW'
AUTHORIZATION OFF 
USER DBA
AS CALL cyrillic_html();

To illustrate the process of establishing the correct character set encoding to use, consider the following Accept-Charset header delivered by a web browser such as Firefox to the web service. It indicates that the browser prefers ISO-8859-1 and UTF-8 encodings but is willing to accept others.

Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7

The web service will not accept the ISO-8859-1 character set encoding since the web page to be transmitted contains Cyrillic characters. The web service prefers ISO-8859-5 or UTF-8 encodings as indicated by the call to sa_set_http_option. In this example, the UTF-8 encoding will be chosen since it is agreeable to both parties. The database connection property CharSet indicates which encoding has been selected by the web service. The sa_set_http_header procedure is used to indicate the HTML document's encoding to the web browser.

Content-Type: text/html; charset=UTF-8

If the web browser does not specify an Accept-Charset, then the web service defaults to its first preference, ISO-8859-5. The sa_set_http_header procedure is used to indicate the HTML document's encoding.

Content-Type: text/html; charset=ISO_8859-5

The following example sets a unique HTTP session identifier:

BEGIN
  DECLARE sessionid VARCHAR(30);
  DECLARE tm TIMESTAMP;
  SET tm = NOW(*);
  SET sessionid = 'MySessions_' ||
      CONVERT( VARCHAR, SECONDS(tm)*1000 + DATEPART(millisecond,tm));
  SELECT sessionid;
  CALL sa_set_http_option('SessionID', sessionid);
END;

The following example sets the time-out for an HTTP session to 5 minutes:

CALL sa_set_http_option('SessionTimeout', '5');