Sheerpower®
A Guide to the Sheerpower Language


Previous Contents Index

How This Form Works

Each time anyone enters an expression to evaluate (like 2+3), their browser sends the data to your SPINS webserver along with a handler name. In this example, the handler name is EVAL. The SPINS websever then passes the data to the EVAL_HANDLER.SPSRC Sheerpower program. The EVAL_HANDLER handles the request, figures out the result, and sends the result back to the SPINS server. The SPINS server then sends the result back to the browser.

Important Note on the Handler Name

The handler name defined in the source code MUST be defined in UPPER CASE.

18.3.3 How the EVAL_HANDLER Program Works

In order to handle CGI requests, the following steps need to be taken:

First we open our CGI connection to the SPINS server.


    handler_name$ = 'cgi://EVAL' 
    open file cgi_ch: name handler_name$ 

In this example, EVAL is the HANDLER NAME.

Note that the handler name defined in the source code MUST be defined in UPPER CASE.

For higher performance, you can run as many copies of this handler as you wish. The Sheerpower CGI interface will queue all requests to these handlers that have the form:


    http://www.ttinet.com/scripts/spiis.dll/EVAL 

Next we set up a logic loop to wait for requests, handle timeouts, and process each request.


    do
      line input #cgi_ch: method$ 
      if method$ = '' then repeat do
      .. 
      .. 
    loop

18.3.4 Waiting for CGI Requests

The LINE INPUT waits for a request from the SPINS server. When the LINE INPUT completes, the variable METHOD$ will contain one of three values.

In this program, when there is no request from the SPINS server (a timeout), we just go back and try again. In complex applications a program might instead unlock databases, write out statistics, and then go back and try again.

18.3.5 Processing CGI Requests

Now that we have a request from the SPINS server, we have to process the request.


  ask #cgi_ch, symbol 'EXPR': value expr$ 
  if  expr$ = '' then
    print #cgi_ch: '<h2>Thank you for using the Evaluator!</h2>' 
    repeat do
  end if
  
  when exception in
    answer = eval(expr$) 
  use
    answer = extext$ 
  end when
  if dtype(answer) <> 1 then answer = str$(answer) 
  print #cgi_ch: '<h2>'; expr$; ' --> '; answer; '</h2>' 
  
  ask #cgi_ch, symbol 'env:REMOTE_ADDR': value ipaddr$ 
  print #cgi_ch: '(Your IP address is '; ipaddr$; ')' 

This form returns one form variable---the expression to be evaluated (EXPR). We use the Sheerpower ASK instruction to ask for its value.


  ask #cgi_ch, symbol 'EXPR': value expr$ 

If they didn't enter any expression, we just tell them "Thank you...". This is done using the PRINT instruction.

print #cgi_ch: '<h2>Thank you for using the Evaluator!</h2>'

Using EXPR$, we calculate the ANSWER and PRINT the result back to the SPINS server.

print #cgi_ch: '<h2>'; expr$; ' --> '; answer; '</h2>'

Finally, we ask the SPINS server for the "REMOTE_ADDR". This is the IP address of the requestor. Since "REMOTE_ADDR" is an environmental variable, we must put "env:" in front of the symbol name. Once we get the IP address, we PRINT it to the SPINS server---which, in turn, sends the data back to the browser.


  ask #cgi_ch, symbol 'env:REMOTE_ADDR': value ipaddr$ 
  print #cgi_ch: '(Your IP address is '; ipaddr$; ')' 

18.3.6 Building CGI Custom HTTP Headers

By default, Sheerpower automatically builds the CGI required HTTP headers. But, sometimes there is a need to write out your own custom HTTP headers. For example, you might need to write out binary data, or perhaps send a cookie. Here is a sample routine that writes out a HTTP header:


    routine start_http_output 
      ask #cgi_ch, symbol 'env:PATH_INFO': value path_info$ 
      print #cgi_ch: "HTTP/1.1 200 OK" 
      print #cgi_ch: 'Cache-Control: max-age=2, must-revalidate' 
      print #cgi_ch: "Content-type: text/html" 
      print #cgi_ch: 'Referer: ' + path_info$ 
      print #cgi_ch: "Pragma: no-cache" 
      print #cgi_ch: 
      print #cgi_ch: 
    end routine 

Note

When printing out binary data, include a trailing semi-colon at the end of the PRINT instruction:

print #cgi_ch: mybinary$; // notice the trailing semi-colon

18.3.7 CGI Interface Performance Considerations

The Sheerpower CGI interface was designed for very high performance. If the server it is running on has multiple CPUs, full advantage of the CPUs can be taken by running multiple copies of the same HANDLER. A good "rule of thumb" is to run at least two HANDLERS for each CPU on the server. Idle handlers consume very little cpu-time---less than 1/10th of 1% of available CPU-time for each idle handler.

18.3.8 Summary of CGI Environment Variables

FORMAT:


        ASK #cgi_ch, SYMBOL 'ENV:environment_variable : VALUE x$ 

EXAMPLE:

Example 18-3 Environment Variables

// This sample program can be found in 
// Sheerpower/sample/sphandlers/eval_handler.spsrc 
// It is also the sample program used to illustrate 
// and test the CGI Interface in Sheerpower, also 
// in this chapter (Webserver CGI Interface) 
 
declare object answer 
handler_name$ = 'cgi://EVAL' 
 
print 'Eval Handler started '; date$(days(date$), 4);' at '; time$ 
 
open file cgi_ch: name handler_name$ 
do
  line input #cgi_ch: method$ 
  if method$ = '' then repeat do
  ask #cgi_ch, symbol 'EXPR': value expr$ 
  if  expr$ = '' then
    print #cgi_ch: '<h2>Thank you for using the Evaluator!</h2>' 
    repeat do
  end if
 
  when exception in
    answer = eval(expr$)
  use
    answer = extext$ 
  end when
  if dtype(answer) <> 1 then answer = str$(answer) 
  print #cgi_ch: '<h2>'; expr$; ' --> '; answer; '</h2>' 
 
  ask #cgi_ch, symbol 'env:REMOTE_ADDR': value ipaddr$ 
  print #cgi_ch: '(Your IP address is '; ipaddr$; ')' 
 
loop
close #cgi_ch 
stop
 
end

PURPOSE:

The Sheerpower CGI interface allows full access to the SPINS webserver "environment variables". For example, to ask for the QUERY_STRING (the data that follows a "?" in a URL) you would use:


  ask #cgi_ch, symbol 'env:QUERY_STRING': value qstring$ 

The "env:" symbol prefix tells Sheerpower that you are requesting an environment variable and not a form variable.

To PARSE the QUERY_STRING, you would use:


  ask #nn, symbol 'query:VARNAME': value vvalue$ 

This parses the QUERY_STRING (the data after the ?) for the value of the given VARNAME.

DESCRIPTION:

Table 18-2 CGI Environment Variables
  ALL_HTTP Retrieves all HTTP headers that were received. These variables are of the form HTTP_header field name. The headers consist of a null-terminated string with the individual headers separated by line feeds.
  ALL_RAW Retrieves all headers in raw form. The header names and values appear as the client sends them. Currently, proxy servers and other similar applications primarily use this value.
  APPL_MD_PATH Retrieves the metabase path of the application for the ISAPI DLL or the script.
  AUTH_PASSWORD Specifies the value entered in the client's authentication dialog. This variable is only available if Basic authentication is used.
  AUTH_TYPE Specifies the type of authentication used. If the string is empty, then no authentication is used. Possible values are Kerberos, user, SSL/PCT, Basic, and integrated Windows authentication.
  AUTH_USER Specifies the value entered in the client's authentication dialog box.
  CERT_COOKIE Specifies a unique ID for a client certificate. Returned as a string. Can be used as a signature for the whole client certificate.
  CERT_FLAGS If bit0 is set to 1, a client certificate is present. If bit1 is set to 1, the certification authority (CA) of the client certificate is invalid (that is, it is not on this server's list of recognized CAs).
  CERT_ISSUER Specifies the issuer field of the client certificate. For example, the following codes might be O=MS, OU=IAS, CN=user name, C=USA, and so on.
  CERT_KEYSIZE Specifies the number of bits in the Secure Sockets Layer (SSL) connection key size.
  CERT_SECRETKEYSIZE Specifies the number of bits in the server certificate private key.
  CERT_SERIALNUMBER Specifies the serial-number field of the client certificate.
  CERT_SERVER_ISSUER Specifies the issuer field of the server certificate.
  CERT_SERVER_SUBJECT Specifies the subject field of the server certificate.
  CERT_SUBJECT Specifies the subject field of the client certificate.
  CONTENT_LENGTH Specifies the number of bytes of data that the script or extension can expect to receive from the client. This total does not include headers.
  CONTENT_TYPE Specifies the content type of the information supplied in the body of a POST request.
  LOGON_USER The Windows account that the user is logged into.
  HTTP_ACCEPT A variable used to advise the server what types of content your browser can handle.
  HTTP_ACCEPT_ENCODING Defines the type of encoding that may be carried out on content returned to the client.
  HTTP_ACCEPT_LANGUAGE Defines the language or locale to use for: the UI, formatting or collation preferences, about which to provide content or information.
  HTTP_CONNECTION Classes used to manage a HTTP connection to a webserver.
  HTTP_COOKIE A client variable that stores a cookie on the server passed by a HTTP header.
  HTTP_HOST Displays the current domain name.
  HTTP_REFERER A meta-variable used to identify the page where the URL obtained was requested (i.e. the source of the link that was followed).
  HTTP_USER_AGENT This is used to get the user agent string, such as browser name and version , bot, or other program. The syntax is: ask #cgi_ch, symbol 'env:HTTP_USER_AGENT : value agent$
  HTTPS Returns on if the request came in through secure channel (with SSL encryption), or off if the request is for an unsecure channel.
  HTTPS_KEYSIZE Specifies the number of bits in the SSL connection key size.
  HTTPS_SECRETKEYSIZE Specifies the number of bits in server certificate private key.
  HTTPS_SERVER_ISSUER Specifies the issuer field of the server certificate.
  HTTPS_SERVER_SUBJECT Specifies the subject field of the server certificate.
  INSTANCE_ID Specifies the ID for the server instance in textual format. If the instance ID is 1, it appears as a string. This value can be used to retrieve the ID of the Web-server instance, in the metabase, to which the request belongs.
  INSTANCE_META_PATH Specifies the metabase path for the instance to which the request belongs.
  PATH_INFO Specifies the additional path information, as given by the client. This consists of the trailing part of the URL after the script or ISAPI DLL name, but before the query string, if any.
  PATH_TRANSLATED Specifies this is the value of PATH_INFO, but with any virtual path expanded into a directory specification.
  QUERY_STRING Specifies the information that follows the first question mark in the URL that referenced this script.
  REMOTE_ADDR Specifies the IP address of the client or agent of the client (for example gateway, proxy, or firewall) that sent the request.
  REMOTE_HOST Specifies the host name of the client or agent of the client (for example, gateway, proxy or firewall) that sent the request if reverse DNS is enabled. Otherwise, this value is set to the IP address specified by REMOTE_ADDR.
  REMOTE_USER Specifies the user name supplied by the client and authenticated by the server. This comes back as an empty string when the user is anonymous.
  REQUEST_METHOD Specifies the HTTP request method verb.
  SCRIPT_NAME Specifies the name of the script program being executed.
  SERVER_NAME Specifies the server's host name, or IP address, as it should appear in self-referencing URLs.
  SERVER_PORT Specifies the TCP/IP port on which the request was received.
  SERVER_PORT_SECURE Specifies a string of either 0 or 1. If the request is being handled on the secure port, then this will be 1. Otherwise, it will be 0.
  SERVER_PROTOCOL Specifies the name and version of the information retrieval protocol relating to this request.
  SERVER_SOFTWARE Specifies the name and version of the Web server under which the ISAPI extension DLL program is running.
  URL Specifies the base portion of the URL. Parameter values will not be included. The value is determined when SPINS parses the URL from the header.


Previous Next Contents Index