docs.roxen.comBack to normal mode
DocsRoxen2.1Programmer ManualPike
Copyright © 2001, Roxen Internet Software
Suggestions, comments & compliments
manuals@roxen.com

Script

How to make pike scripts and how to use them within (and possibly also independent of) roxen.

Pike scripts differ from e g CGI or Perl scripts, by being run inside of Roxen WebServer instead of as an external process. They share the characteristics of being executed when a user tries to access them, but they have the added benefit of easy access to all Roxen API:s, being written in the server's native language. This makes them much more efficient, generally respond faster and use less resources. It is also possible for them to cache data between requests, since they will stay resident after being loaded and compiled.

Since Pike scripts are run internally in the web server they have security implications, a Pike script can do anything the web server can. It is however possible to run them in a mode where a separate process is created for each request. This is safe, but on the other hand you miss much of the advantages of Pike scripts mentioned above.

API Methods

  • void create()

    create, although not strictly a part of the Roxen API, is called once when instantiating the script during compilation, and never again.

  • string|mapping parse(RequestID id)

    The method parse gets executed for each request to the script. It returns either a string containing RXML code or a response mapping created via one of the response methods (Roxen.http_string_answer and friends).

  • int no_reload(RequestID id)

    Normally, scripts are kept resident within the server between request after having once been compiled. They are, as one might expect, automatically reloaded if they (or any file they have inherited) have changed on disk. This behaviour can be altered by adding a no_reload function to your script. The no_reload function, when present, overrules this behaviour. If it returns zero, the script is reloaded, if it returns one, it is not. It gets called before each new request after the first one (when it was originally compiled).

    By default, pike scripts can be reloaded by requesting them with the pragma no-cache header. This is achieved in Netscape by pressing reload and, unfortunately, not at all, in Internet Explorer. You may easily devise any reloading policy by testing data from the id object; this example reloads the script when the query variable "reload" is set:

    int no_reload(RequestID id)
{
  return !!id->variables->reload;
}

An example script:

int count = 0;

mapping parse(RequestID id)
{
  string times, reply = #"<html><head>
<title>Hello World</title>
</head><body>
<h1>Hello, world!</h1>

<p>(Did you know that I've hailed the
world %s since I was loaded?)</p>
</body></html>";

  switch(++count)
  {
    case 1: times = "just once"; break;
    case 2: times = "twice already"; break;
    default: times = "a smashing " + count + " times";
  }
  return Roxen.http_string_answer(sprintf(reply, times));
}