<P>Netplex allows you to write 'CGI' (<I>Common Gateway Interface</I>) programs which dynamically generate a response when a client accesses them. By using CGI programs you can provide interactive facilities for the users accessing your server. You may have seen access counters on WWW pages which display a small graphic showing how many times the page has been accessed - this is an example of a CGI program.</P>
<P>The CGI program is either a normal program (BASIC, Absolute, Utility) or an OS script (Obey, Command, etc.) kept in a special directory, which once invoked produce output that the client can interpret. In the case of the access counter program mentioned above, the output is a GIF image.</P>
<P>CGI programs are usually referenced from a normal, static, WWW page, acting as a utility to the master page. For example, a form, when the user presses the 'Submit' button, will ask the server for a URL similar to :</P>
<P>This means that the CGI program specified by the URL "http://bronze.netplex.net/cgi-bin/form" will be invoked with the parameters "name=Zaphod+Beeblebrox". The '?' character separates the URL of the program and the parameters to be passed to the program. Also, several named parameters can be passed by separating them with the '&' symbol. For example : </P>
<P>Once invoked, the program will generate its output, which the server will then despatch to the client. This type of retrieval is the 'GET' method.</P>
<P>The other method used is 'POST', this is different to GET in that instead of appending the parameters to the URL, it sends them as a 'packet' of data (officially called an 'entity') accompanying the request. This has the advantage of allowing much larger amounts of data to be passed, since URLs are limited to a fixed number of characters. POSTs are the preferred method of submitting form data.</P>
<P>In the case of the access counter program mentioned above, the parameters passed to it will be an ID for the user's WWW page. The counter program will look up the ID in its database, find the number of times the counter has been requested, increment it, and then generate a GIF file of the number of requests.</P>
<P>Writing CGI programs for use with Netplex is fairly easy, as BASIC can be used to implement them quickly. To start with an example, here's a web-enabled Hello World program :</P>
<P>The first two PRINT statements are part of the header that is sent to the client. The first line tells the client that the document is HTML text and the second, empty line, terminates the header. Both lines are terminated by 'CHR$(13);CHR$(10);' as the usual PRINT line ending is inapropriate for header fields which must be terminated by CR,LF. The other lines are a simple HTML 'page' which will be displayed in the browser.</P>
<P>As far as things go, this program isn't very interesting - it doesn't actually do anything <I>different</I> every time you run it, which is the point of the CGI system. An easy modification to make it produce different output every time is to replace "Hello World!" with TIME$, which returns the current time :</P>
<P>Now, when the program is fetched, it will return the current time.</P>
<P>To learn more about CGI programming, examine the <A HREF="#examples">examples</A> given below.</P>
<H3>The CGI Library</H3>
<P>A library of BASIC functions for use in CGI programs is provided, referenced by the file <Netplex$Dir>.CGILibrary. In order to use them, you should use the following instructions at the start of your program :</P>
<PRE><P>
LIBRARY "<Netplex$Dir>.CGILibrary"
PROCcgi_init
</P></PRE>
<P>This will set up an error handler, dimension a 256-byte block of memory called misc% and will set the variables cgi_in% and cgi_out% to the handles of the input and output data streams respectively.</P>
<P>The library provides the following routines :</P>
<DD>Given the Content-Type and Content-Length, this routine generates an appropriate response header. Content_type$ is given as 'image/gif', 'text/html', etc. Content_length% is the amount of data you are going to be sending, or -1 if you don't know. Note that you <EM>must</EM> use this routine, as it handles compatibility with HTTP/1.1 requests.
<DT><B>PROCcgi_statusline(code%,phrase$)</B>
<DD>If you need to, you may generate an entire HTTP response yourself, including headers. Cgi_statusline outputs the initial HTTP status line, which informs the recipient of the version of HTTP in use, the response status code and a short phrase indicating the server's response. You must call cgi_statusline before anything else that will cause output.
<DT><B>PROCcgi_headerline(name$,value$)</B>
<DD>This routine takes care of outputting HTTP headers with the correct line endings. Name$ is the name of the header field and value$ is its value, so cgi_headerline("Cookie","name=cookie_monster") will generate the header line "Cookie: name=cookie_monster".
<DT><B>PROCcgi_error</B>
<DD>This is automatically called when an error occurs. It cleans up any temporary files and generates an HTML page describing the error.
<DT><B>FNcgi_nextelement</B>
<DD>Returns the next element passed to the program (POST only).
<DT><B>FNcgi_nextelementdecoded</B>
<DD>As above, but translates all of the escape codes first, by calling FNcgi_decodeelement.
<DT><B>FNcgi_decodeelement(e$)</B>
<DD>Translates all the escape characters (e.g. '%7e') in e$, and returns the translated string.
<DT><B>FNstring_readtoctrl(RETURN p%)</B>
<DD>Returns the string pointed to by p%, and updates p% to point to the first unread character.
<DT><B>FNcase_lower(s$)</B>
<DD>Returns the given string, in lower case.
<DT><B>FNcase_upper(s$)</B>
<DD>Returns the given string, in upper case.
<DT><B>FNsystem_getvar(var$)</B>
<DD>Returns the value of the named system variable as a string.
<DT><B>FNmime(filetype%)</B>
<DD>Converts a filetype to a MIME Content-Type.
</DL>
<H3>CGI System Variables</H3>
<P>Netplex passes information to CGI programs via a set of system variables, which use the prefixes 'CGI$' and 'HTTP$'. Note that this is different to CGI on non-RISC OS servers which have different rules regarding system variables. For example, CGI$ServerSoftware is used rather than SERVER_SOFTWARE. This means that anyone porting CGI software or scripts from other platforms must take this into account, and adjust all references to system variables.</P>
<P>Only some of the following variables may be set, depending on the method the client used and the information it passed.</P>
<H5>Static Variables</H5>
<I>Variables which are constant for the duration of the server.</I>
<DL>
<DT>CGI$ServerSoftware
<DD>Contains the name and version of the server software, e.g. 'Netplex/0.09 (05 Oct 1996)'.
<DT>CGI$ServerName
<DD>Is the fully qualified name of the server. At startup, Netplex will attempt to resolve this from the Inet$LocalIP variable.
<DT>CGI$GatewayInterface
<DD>Always set to "GGI/1.1".
<DT>CGI$ServerPort
<DD>Set to the port that the server is operating on.
</DL>
<H5>Dynamic Variables</H5>
<I>Variables which change according to the request.</I>
<DL>
<DT>CGI$ServerProtocol
<DD>HTTP/1.0 or HTTP/0.9 depending on the request received.
<DT>CGI$RequestMethod
<DD>This is set to the request method that was used to retrieve the file, e.g. GET or POST.
<DT>CGI$PathInfo
<DD>If you specify the URL http://mercury.netplex.net/cgi-bin/imagemap/dthomas then if the program imagemap exists in the cgi-bin directory, PathInfo will be set to 'dthomas'.
<DT>CGI$PathTranslated
<DD>This is the same as above but is prefixed with the path of the web page directory. With the above example it would be something like, 'ADFS::IDEDisc4.$.Internet.WWW.dthomas'.
<DT>CGI$ScriptFilename
<DD>The full RISC OS filename of the program. For example 'ADFS::IDEDisc4.$.Internet.WWW.cgi-bin.process'.
<DT>CGI$ScriptName
<DD>The URL path of the program. For example '/cgi-bin/process'.
<DT>CGI$QueryString
<DD>The data passed in the URL, which followed the '?'. Used by GET requests to pass parameters to CGI programs.
<DT>CGI$RemoteHost
<DD>The name of the client machine, or the dotted-IP address if unknown.
<DT>CGI$RemoteAddr
<DD>The dotted-IP address of the client machine.
<DT>CGI$AuthType
<DD>If Client Authentication is in use then this will be set to 'Basic'.
<DT>CGI$AuthUser
<DD>If Client Authentication is in use then this will be set to the username of the client 'logged in'.
<DT>CGI$ContentType
<DD>The type of data that has been submitted to the program. (Applies to POST only).
<DT>CGI$ContentLength
<DD>The length of the data that that has been submitted to the program. (Applies to POST only).
</DL>
<H5>HTTP Header Fields</H5>
<I>The header fields, as submitted by the client.</I>
<DL>
<DD>It depends entirely on the client as to what you will find set in the HTTP variables.
</DL>
<P>There is also another system variable, although not strictly linked to CGI programs, which is useful to have. It is Netplex$WebPagesDir which gives the name of the root web page directory.</P>
<H3>Notes</H3>
<UL>
<LI>Netplex checks the requested URL for '/cgi-bin/' and will invoke the program <B>only</B> if it is inside a 'cgi-bin' directory <B>and</B> is of type Command, Utility, BASIC, Absolute or Obey, otherwise it will be served as a file.
<LI>CGI directories do not need to be in the root web page directory, e.g. you could have http://iron.netplex.net/~bob/cgi-bin/ which would still work OK. You can have multiple cgi-bin directories if you want (in different directories, of course).
<LI>In order for CGI$PathInfo to be correct, you must <B>not</B> use subdirectories within the cgi-bin directories.
<LI>The first line of CGI output is parsed, if it begins 'HTTP/1' then it is assumed that the CGI program has generated the entire header itself and Netplex will not attach any header fields of its own.
</UL>
<HR WIDTH="50%">
<A NAME="examples"><H2>Examples</H2></A>
<P><DL>
<DT><B><A HREF="cgi-bin/time">Time</A></B>
<DD>A CGI program which when retrieved displays the time.
<DD>A CGI program which when retrieved displays the query string that was passed to the program. In this case the query string is 'This+is+the+query+example'.
<DT><B><A HREF="form">Form</A></B>
<DD>An HTML page containing a Form which when submitted is sent to a CGI program called 'form' which displays the results. This uses the POST method rather than GET.
<DT><B><A HREF="cgi-bin/tasks">Tasks</A></B>
<DD>Dynamically builds an HTML page of information about all running tasks on your machine.
<DT><B><A HREF="cgi-bin/info">Info</A></B>
<DD>Provides information on the system variables used by Netplex to inform CGI programs of their parameters.
<DT><B><A HREF="cgi-bin/dir">Dir</A></B>
<DD>An advanced version of the Query program which uses self-references to enable the user to traverse a directory structure and serve files. It defaults to using 'ADFS::4.$', which may not be applicable to your system. It will only list Public-readable files.
<BR>(Note: ArcWeb isn't fond of this program, due to its slightly non-standard use of URLs).
</DL></P>
<P><B>Note :</B> These programs are provided purely for demonstration purposes. You should not allow open access to your machine with these programs present - particularly Dir as it allows unrestricted access to any filing system on your machine.</P>
