CFHT HOME RPM Web Server User's Manual

up: RPM Info next: RPM Tech Manual prev: RPM Installation

Server URL-Directives

The server has several special options to select various modes. These options are specified as part of the URL that the browser uses. Options are separated from the URL by a `?' and the options are separated from each other by `+' signs. For example: 

  http://hostname/index.html?rpmsource=1
will tell rpm to send fancy fontified source of index.html rather than the html itself.

The options that are recognized by the current version include:

rpmcard=NAME
Causes a page using the RPM CardFile tag to be loaded with card NAME displayed in front by default.

rpmsource=1
Sends entire document to browser in <PRE> mode. Angle brackets are sent as entities so you can see the raw markup. Various parts of the SGML tags are color-highlighted for easier reading.

rpmplaintext=1
Sends entire document to browser as plain ascii text. Similar to rpmsource except in this case there really is no HTML markup in the output generated. This is useful for pages that are supposed to generate a specific type of raw format to be read by a robot client at the other end. (Created for TCS coordinate server.)

rpmdebug=1
Instructs RPM to write verbose debugging information to the log entry for the current access. If the current access is for an HTML file, this option also causes the entire debugging output to be included in the response sent to the browser.

rpmdynamic=1
If the browser supports netscape's ``server-push'' mode, this option will cause the connection to stay open indefinitely (or until the browser leaves the document) and rpm will automatically refresh the display whenever a significant change occurs in the source file. The effects of this option are automatically canceled for browsers that do not support the mode.

rpmdemo=1
A customizable ``demo wrapper'' will be included above the real file. This wrapper can contain company logo, a button to see the rpmsource version of the current document, or anything else that can be specified in RPM's macro language.

rpmmacros=1
This option is implied whenever the filename ends in `.rpm'. It tells rpm to pre-process the source file for any SGML tags appearing in { }'s. If an html file has any {} tags embedded in the text, you will either need to rename it to `*.rpm' or add `?rpmmacros' to the URL.

rpmslide=1
This option should not be used. It's just in the docs here to remind me to remove it from rpm.

rpmnomargin=1
Causes RPM to generate a netscape FRAMEs document with only a single frame that references the desired document. The only purpose of this is to eliminate the margins on netscape's canvas.

rpmpost=1
There are two standard ways of reading variables from a client. The first is a FORM with METHOD=GET, and the second is METHOD=POST. RPM prefers the latter, because the form data is sent privately, in an HTTP header from the client to the server. With the GET method, the form data is part of the URL. RPM will ignore form data that is part of a URL, unless one of the variables is rpmpost=1. In that case, it will do the following:
  • Remove rpm*= from the list first.
  • Parse and handle the rest of the variables as if they were posted.
  • Generate a new form that will switch back to the POST method on subsequent submit actions. (This necessitates that rpmpost=1 and all the posted variables will be removed, but other rpm*= will be kept so that settings like debugging or profiling will stick.)
This feature is used internally to implement IMG tags which have a SRC that it is the output of a form posting. For example, the TFM tool wants to generate a plot based on current form input values. To do this without temporary files, the RPM server must generate a URL with all the variables encoded in the query string just like a GET request. These are then passed to the script and the output of the script is inserted into the document, all without using a single temporary file.

You can also use this feature to send data to RPM forms from another FORM using the GET method, or from a link which needs to pre-load certain values into a form. For example:

https://rpm.cfht.hawaii.edu/~megacam/tfm/ is the normal URL to go to the TFM tool, while https://rpm.cfht.hawaii.edu/~megacam/tfm/index.rpm?rpmpost=1&TFM_NAME=Alternate+Title would load it with a different title pre-loaded into the form.

rpmtimings=1
If this is added to a URL of a text or HTML file, the server will attempt to approximate the amount of time it took for the document to reach the client. For finer control over this feature, see information on {CONFIG timings=...}.

rpmprofile=1
If this is added to a URL of a text or HTML file, the server will time each step involved in document preparation and add a table of server performance values to the end of the document. To time everything, including server setup, see {CONFIG profile=...}.

rpmcrashtest=1
This can be used to test if you have the desired setup for handling unexpected signals. See the installation manual for more details.

rpmhead=1
Users should not worry about this option. However, the purpose of this internally is to let RPM know that a JavaScript form has decided to POST new values, but will not be refreshing itself with new HTML content at the end of the request. Instead, the RPM server should only process the {Head} section of the document and then return content-type image/gif with either a transparent image or a red or yellow block (if an error or warning occurred.) The JavaScript code that generated this special request is going to be expecting a GIF to come back from the server, and it will replace a fixed GIF at the lower corner of the RPM form with whatever comes back to indicate success or failure.

Builtin Image Generation

Gif's are the primary way to put graphics on Web pages, currently. Often it is useful to have Gif's that look like common user-interface pieces. Another use might entail showing the user feedback of where they clicked on an image by adding additional text or graphics to a background-gif. Doing things like this with separate Gif files can quickly lead to a need for hundreds of separate gifs.

The RPM Server can generate/overlay some simple Gifs on the fly, without the need to keep all of those images around. The language for generating these images is integrated into special URL's that begin with `/imggen?' followed by a series of one or more graphics library function calls (passed to libgd) separated by `+'s. For example: 

  https://rpm.cfht.hawaii.edu/imggen?funcname1(param='value')+funcname2(param1='value',param2='value')
Here is the complete list of `funcname's that are supported so far. Any or all of the parameters to the functions can be omitted, and the defaults shown below will be used. If the default value says current it means the value from the most recent command that had this parameter specified will be used. If the default value says center, the center of the current canvas will be calculated. DO NOT pass center or current in the URL's themselves. Simply omit the parameter all together if you want something centered or drawn with "current" settings. Order of the parameters does not matter. Unrecognized parameter names are ignored to provide upward compatibility.

size(width=35,height=35)
As the first function in the list this will set up a canvas of width X height pixels for subsequent drawing commands. If there are no subsequent drawing commands, this generates a transparent spacer of any desired size.
If after the first function in the list this function should resize or clip the current canvas, but this is not yet supported.
Examples:
[]-/imggen?size(width=50,height=10)
[]-/imggen?size(width=50,height=10)+text(s='hello')

image(file='filename.gif',cx=center,cy=center)
As the first function in the list cx and cy are ignored and the image is loaded as a background for subsequent drawing commands. If there are no subsequent drawing commands, you might as well load the image directly from the server, without using imggen.
If after the first function in the list this results in the specified image being overlayed ontop of the current canvas with its center falling on (cx,cy). This is not yet supported.
Examples:
[]-/imggen?image(file='shutter-open.gif')
[]-/imggen?size(width=50,height=20)+image(file='lamp-on.gif',cx=30,cy=11)

text(s='text',size=+0,cx=center,cy=center)
As the first function in the list cx and cy are ignored and an automatically-sized image is generated with the specified text written on it. size can be on of +0, +1, +2, -1, or -2.
If after the first function in the list a text label centered at (cx,cy) is drawn on the current canvas.
Examples:
[]-/imggen?text(s='hello')
[]-/imggen?image(file='shutter-open.gif')+text(s='oben',size=-1)

button()
As the first function in the list it doesn't make much sense to use it this way, but it creates a blank button.
If after the first function in the list the current canvas is made to look like Motif-ish button with beveled edges. The current canvas may contain text, images, or anything else that is possible with the other drawing commands.
Examples:
[]-/imggen?text(s='hello')+button()
[]-/imggen?image(file='lamp-on.gif')+button()

The rest have not yet been implemented, but here is what is planned:


dot(size=8,color=current,cx=center,cy=center)
As the first function in the list cx and cy are ignored and an image with a filled circle of the desired size and color is generated.
If after the first function in the list the dot is overlayed on the current canvas, centered around (cx,cy).
Examples:

box(width=8,height=8,color=current,cx=center,cy=center)
Works just like dot except it draws a rectangle.
Examples:

line(x1=0,y1=0,x2=34,y2=34,color=current)
Draws a line on the current canvas from (x1,y1) to (x2,y2) in the desired color.
Examples:

Syntax

The server-side macros specified in an SGML format. Use of the { and } characters instead is legal, and is specified in the DTD for RPM forms. NESTED TAGS and alternate QUOTING characters are not. These are rarely used, but if they are, an RPM form is technically in violation of the SGML specification.

TAG DELIMTERS
Tags are enclosed in { } instead of < >.

NESTED TAGS
Tags may be nested, and will be evaluated recursively until there are no (unescaped) {'s left.

QUOTING
Values can be quoted in " ", but ( ) and ` ' are also accepted for RPM tags. When dealing with nested tags, one of the latter two choices is required, because unique open-quote and close-quote characters are needed.

LITERAL CHARACTERS
If a backslash preceeds any character (including another backslash) then that character loses any special meaning it might have otherwise had and is eventually sent to the browser as a literal character. Note that sequences like \t, \n, and \r currently just print t, n, and r. URL-style escape sequences (a percent symbol followed by two hex digits) are not supported.

This is most often used to embed real { and } characters in RPM forms (for example, for hardcoded JavaScript.)


CASE INSENSITIVE
Tagnames and argument names are case insensitive, but the values are often case sensitive (especially when the value is a filename or URL.) This is consistent with the behavior of HTML tags.

CLOSING TAGS OPTIONAL
A tag named {FOO} would typically have a matching {/FOO} tag that blocks out the region of the document which FOO should affect. But many custom tags are just macro calls that create their own output rather than somehow affecting a a block of text in the document. For these cases, the closing tags don't make much sense, and are therefore optional. Thus, the generic syntax for a tag in RPM format is: 
     {TAGNAME ARGNAME=`value' ARG2NAME=`value' ...}
or
     {TAGNAME ARGNAME=(value) ARG2NAME=(value) ...}
or
     {TAGNAME ARGNAME="value" ARG2NAME="value" ...}

Location Specifiers

Many RPM tags take a loc (location) argument, which specifies the filename and access method for a local database or executable. It may be necessary to combine loc with a method attribute as well: 
     "{TagName loc=/path/to/file.dat method=rpm}"
or
     "{TagName loc=/path/to/executable method=opt}"
or
     "{TagName loc=/path/to/file.rpm}"
The latter only works if the filename's extension happens to be the same as the access method for that database. Paths are resolved by the same routine that resolves paths for RPM documents. Whatever relationship they have to the actual file system depends on how RPM is configured.

In HForms, TagNames are one of Var, Set, Load, or Save.

Currently supported methods include:

method=par
Values live in the "cur" field of a CFHT par file. No support for named substitutions (%varname) is provided, but aliases (->) are supported. Importing a par method is the equivalent of performing a "getcur" and Exporting a par is equivalent to a "putcur". If the loc field of a Var or Import or Export tag ends in ".par", method=par is assumed.
method=rpm
Values are the arguments of the first RPM tag in a file. Like par, values can be Imported or Exported. If the loc field of a Var or Import or Export tag ends in ".rpm", method=rpm is assumed.
method=env
This one applies only to Export actions. Values are to be passed as environment variables to an executable, specified in the loc= attribute. The executable will echo back "name=value\n" on stdout for each name that it has an updated value for.
method=opt
Also applies just to Export actions. Similar to env: except that values are passed as command-line options in the form --name=value. The external program can update form variables in the same way by echoing on stdout.
method=genh
When using genh, the loc= attribute should be a par file. After saving the public variables in this par file, the genh method will run the handler by the same name (without the ".par" at the end.) It is expected that the handler will know that being called with no arguments means to check what has changed in its par file. For this, an additional status.par file is probaby needed so it can determine which values are updated. See geckoh for examples of this.
method=xmit
This is similar to method=env, except the stdout of the program is saved in a buffer. This buffer can be sent to the client using a Transmit tag immediately after.

Tags

The set of tags supported by RPM depends on the DTD library it is linked with. Currently, the only choice here in the HForm DTD, embodied in libHForm. The tags of the HForm DTD are described in a separate document:

HForm DTD and tags.

1997 February 13 by Sidik Isani isani@cfht.hawaii.edu