sa_set_http_option system procedure

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.

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.

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.