Procedures that handle web requests

ASA Database Administration Guide
Using the Built-in Web Server

Procedures that handle web requests

Generally, it is easiest to write a procedure that handles the requests sent to a particular service. In general, your procedure should return a web page. Optionally your procedure can accept arguments, passed as part of the URI, to customize its output.

The following example, however, is much simpler. It demonstrates how simple a service can be. This web service simply returns the phrase "Hello world!".

CREATE SERVICE hello TYPE 'RAW'
      AUTHORIZATION OFF USER DBA
      AS select 'Hello world!'

Start a server with the -xs switch to enable handling of web requests, then request the URL http://localhost/hello from any web browser. The words Hello world will appear in an otherwise plain page.

HTML pages

The above page is displayed in your browser in plain text. This happens because the default HTTP Content-Type is text/plain. To create a more normal web page, formatted in HTML, you must do two things:

Set the http Content-Type header field to text/html so that the browsers will expect HTML.
Include HTML tags in the output.

You can write tags to the output in two ways. One way is to use the phrase TYPE HTML in the CREATE SERVICE statement. Doing so asks Adaptive Server Anywhere to add HTML tags for you. This can work if quite well if, for example, you are returning a table.

The other way is to use TYPE RAW and write out all the necessary tags yourself. This second method provides the most control over the output. Note that specifying type RAW does not necessarily mean the output is not in HTML or XML format. It only tells Adaptive Server Anywhere that it can pass the return value directly to the client without adding tags itself.

The following procedure generates a fancier version of Hello world. For convenience the body of the work is done in the following procedure, which formats the web page.

The built-in procedure sa_set_http_header is used to set the HTTP header type, so browsers will correctly interpret the result. If you omit this statement, your browser will display all the HTML codes verbatim, rather than use them to format the document.

CREATE PROCEDURE hello_pretty_world ()
   RESULT (html_doc long varchar)
   BEGIN
      call dbo.sa_set_http_header( 'Content-Type', 'text/html' );
      select '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">\n'
      || '<html>\n'
          || '<head>\n'
      || '  <title>Hello Pretty World</title>\n'
      || '</head>\n'
          || '<body>\n'
          || '  <h1>Hello Pretty World!</h1>\n'
      || '  <p>(If you see the tags in your browser, check that\n'
      || '      the Content-Type header is set to text/html.)\n'
          || '</body>\n'
          || '</html>';
   END

The following statement creates a service that uses this procedure. The statement calls the above procedure, which generates the Pretty World web page.

CREATE SERVICE hello_pretty_world TYPE 'RAW'
      AUTHORIZATION OFF USER DBA
      AS call hello_pretty_world()

Once you have created the procedure and the service, you are ready to access the web page. Ensure that your database server was started with the -xs switch, which causes it to listen for web requests, then browse to the URL http://localhost/hello_pretty_world.

You see the results formatted in a simple HTML page, with the title Hello Pretty World. You can make the web page as fancy as you wish by including more content, using more tags, using style sheets, or including scripts that run in the browser. In all cases, you create the necessary services to handle the browser's requests.

For more information about built-in stored procedures, see System and catalog stored procedures.

Root services

When no service name is included a URI, Adaptive Server Anywhere looks for a web service named root. The role of root pages is analogous to the role of index.html pages in many traditional web servers.

Root services are handy for creating home pages because they can handle URL requests that contain only the address of your web site. For example, the following procedure and service implement a simple web page that is displayed when you browse to the URL http://localhost.

CREATE PROCEDURE home_page
   RESULT (html_doc long varchar)
   BEGIN
      call dbo.sa_set_http_header( 'Content-Type', 'text/html' );
      select '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">\n'
      || '<html>\n'
          || '<head>\n'
      || '  <title>My Home Page</title>\n'
      || '</head>\n'
          || '<body>\n'
          || '  <h1>My home on the web<h1>\n'
      || '  <p>Thank you for visiting my web site!\n'
          || '</body>\n'
          || '</html>';
   END

CREATE SERVICE root TYPE 'RAW'
      AUTHORIZATION OFF USER DBA
      AS call home_page()

You can access this web page by browsing to the URL http://localhost, as long as you do not specify that database names are mandatory when you start the database server.

Examples

For example, the request in the Quick Start example includes no database name and no parameters. In this request, "/tables" identifies the service.

http://localhost:80/tables

More extensive examples are included in the Samples/HTTP subdirectory of your SQL Anywhere Studio installation.