sa_set_http_option system procedure

Permits a web service to set an HTTP option in the result.

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.
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 within an HTTP result set.

The supported options are:

CharsetConversion Use this option to control whether the result set is to be automatically converted from the character set of the database to the character set of the client. The only permitted values are ON and OFF. The default value is ON. See Using automatic character set conversion.
AcceptCharset Use this option to specify the response character set used for XML, SOAP, and HTTP web services. The syntax for this option conforms to the syntax used for the HTTP Accept-Charset request-header field specification in the RFC2616 Hypertext Transfer Protocol.
To specify a list of acceptable charsets, the HTTP client can include an Accept-Charset request header within the request sent to the database server. The Accept-Charset request header specifies which charset the database server should use for its response. When sending the response, a charset supported by both the client and database server is used.

When the Accept-Charset request header is not specified, the charset most preferred by the client and supported by the database server is used. If the database server does not support any of the charsets specified by the client, or an Accept-Charset request header is not specified, the database charset is used.

If the client does not send an Accept-Charset request header, the database server uses the first charset specified by the AcceptCharset option.

If the client specifies an Accept-Charset request header and a charset list is also specified by an AcceptCharset HTTP option, the charset most preferred by the client and supported by the database server is used. If the database server does not support any of the charsets specified by the client, the first charset specified by the AcceptCharset HTTP option is used.

A plus sign (+) in the AcceptCharset HTTP option instructs the database server to use the database charset. For example, ( ‘AcceptCharset’, ‘+,UTF-8,*’). Whenever possible, the dbcharset is used, even if the client prefers a charset that is common to both the client and database server. Using the dbcharset for the response eliminates the need for translation and improves the response time of the database server.

An asterisk (*) in the AcceptCharset HTTP option instructs the database server to use a charset from the client Accept-Charset list. If a common charset does not exist, the first charset specified by the AcceptCharset option is used.
SessionId Use this option to supply a name for an HTTP session. For example, sa_set_http_option( 'SessionId', 'my_app_session_1' ) sets the ID for an HTTP session to my_app_session_1. SessionId must be a non-NULL string. For more information about HTTP sessions, see Using HTTP sessions.
SessionTimeout Use this option to specify the amount of time, in minutes, the HTTP session persists during inactivity. The SessionTimeout option is reset when an HTTP request using the session sends a response.

Permissions

None

Side effects

None

Examples

The following example specifies the use of the dbcharset when it can be accepted. If dbcharset cannot be accepted, UTF-8 is specified as an alternative. If UTF-8 cannot be used, the asterisk (*) specifies the use of the charset most preferred by the client and supported by the database server:

sa_set_http_option( ‘AcceptCharset’, ‘+,UTF-8,*’);

The following pseudo code illustrates how the AcceptCharset option is used:

if -- client sends an Accept-Charset header then
      if -- no AcceptCharset HTTP option set then
            if -- at least one of the client charsets are supported then
                  use most preferred client charset that is also supported by the server
            else
                  use dbcharset
            end if;
      else -- an AcceptCharset HTTP option was set
               if -- at least one of the client charsets is also in the HTTP option charset list 
                     and is supported by the server then use most preferred client charset that 
                     is also in the HTTP option charset list and is supported by the server(1)
              else
                     use the first charset listed in the AcceptCharset HTTP option
           end if;
     end if
else -- client did not send an Accept-Charset header
     if -- no AcceptCharset HTTP option set then
           use dbcharset
        else -- an AcceptCharset HTTP option was set
                use the first charset listed in the AcceptCharset HTTP option
        end if
end if;

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

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

Discuss this page in DocCommentXchange.
Send feedback about this page using email.