This is a cookbook for creating your own web-based applications that interface with SPIRES on your.host. If you have an account on your.host, you can set up your own web pages, and create a SPIRES protocol subfile that lets you accept web-based data fields of information, and act upon that information to produce a requested result. To begin with, I've included below several samples of HTML that you could place in your web page <HTML> ... </HTML>, to specify the fields. <FORM ACTION="http://your.host/cgi-bin/suspires.pl" method=post name="f"> <INPUT NAME="PROTOCOL" TYPE="hidden" VALUE="your.protocol.name"> <INPUT NAME="XEQFILE" TYPE="hidden" VALUE="your.xeq.subfile.name"> <P>Enter Search Command: <A HREF="http://your.host/~yourname/srchelp.html">Help Searching</A><BR> <B>Search: </B> <INPUT NAME="RAWCMD" TYPE="text" SIZE="60" VALUE="find "><BR> <B>Password: </B> <INPUT NAME="PASSWD" TYPE="password" SIZE="20" VALUE=""><BR> <HR> Format by: <SELECT NAME="FORMAT"> <OPTION VALUE="" SELECTED>Default</OPTION> <OPTION VALUE="DISPLAY">Display</OPTION> <OPTION VALUE="REPORT">Report</OPTION> <OPTION VALUE="SPONSOR">Sponsor</OPTION> <OPTION VALUE="LABELS">Labels</OPTION> <OPTION VALUE="EXCEL">Excel</OPTION> </SELECT><BR> Sort by: <SELECT NAME="SEQUENCE"> <OPTION VALUE="" SELECTED>No Sort</OPTION> <OPTION VALUE="zip(d)">Zip Code - Descending</OPTION> <OPTION VALUE="zip">Zip Code - Ascending</OPTION> <OPTION VALUE="label.name">First Name</OPTION> <OPTION VALUE="lastname">Last Name</OPTION> </SELECT><BR> <INPUT TYPE="submit" VALUE="Perform Search"> <INPUT TYPE="reset" VALUE="Reset/Clear Form"> <INPUT TYPE="hidden" NAME="USERID" VALUE="thedate/secretword"> </P> </FORM> This is a sample <FORM...> ... </FORM> that controls the fields. Below is how this FORM would appear on your web page:
There are two primary field types:
<SELECT NAME="name">
<OPTION VALUE="return" SELECTED>Display</OPTION>
<OPTION VALUE="return.value">Display value</OPTION>
</SELECT>
The <SELECT ...> ... </SELECT> field is a pull-down menu of choices.
It doesn't make sense to use this for a single choice. When there
are multiple choices, one of them should have the " SELECTED" keyword
to indicate which choice is initially displayed on the web page.
The text appearing before </OPTION> is displayed on the web page.
For whichever choice is in effect when the page is sent to the web
server, the NAME and VALUE "text" of that choice is returned.
<INPUT TYPE="type" NAME="name" VALUE="value" SIZE="size" >
There are several types associated with the TYPE of INPUT fields:
1. "text" This is a straight text field. You normally give a
SIZE="size" to indicate the size of the input box in characters.
You should also give an initial VALUE, as in the RAWCMD example.
However, if no VALUE is given, the field is initially blank.
Such INPUT fields must have a NAME for data to be returned.
2. "hidden" This is also a text field. It isn't displayed.
The NAME and associated VALUE are returned to you. This is
a way of communicating information without the user seeing it.
3. "password" This is also a text field, but user input is NOT
displayed as it is typed into the input box. PASSWD in the
example is such a field. It must have a NAME to be returned.
4. "reset" This field appears as a button with the VALUE shown
as the text inside the button. When pressed, RESET occurs.
5. "submit" This is also a button, with VALUE shown as the text
inside the button. When pressed, the FORM is sent to the
web server according the the "method" given with FORM ACTION.
If there is a NAME associated with this button, this field
is included in the data sent, just like the "text" fields.
If there is more than one "submit" button, only the one that
is pressed is sent (if it has a NAME). They can all have the
same NAME, in which case the VALUE would be your only way to
distinguish which button was pressed. Or they could all have
different NAMEs with the same VALUEs. Or a combination. It
is your responsibility to be able to distinguish which button
was pressed. But if you don't care, or there's only one such
"submit" button, then there's no reason to give NAMEs to them.
6. "check box" and "radio button" These are a couple of the other
ways to communicate information from your forms back to the system.
For much more information, visit the following site:
To communicate with SPIRES, you must begin with the following:
<FORM ACTION="http://your.host/cgi-bin/suspires.pl" method=post name="f">
This is the driver that gets you into SPIRES, and reads all your
input fields. Furthermore, you need to have <INPUT ...> fields
with NAME/VALUE of PROTOCOL/your.proto, and XEQFILE/xeq.subfile.
For example:
<INPUT NAME="PROTOCOL" TYPE="hidden" VALUE="GENOLOGY.SEARCH">
<INPUT NAME="XEQFILE" TYPE="hidden" VALUE="WCK.PROTOS">
The XEQ subfile (WCK.PROTOS in this example) must be selectable
by GS.WWW since that's the SPIRES account associated with the
web server (wwwuser). The PROTOCOL must exist in that subfile.
When your protocol gets control, the following are all defined:
1. All your NAME/VALUE fields (INPUT and/or SELECT) are
stored in dynamic variables which have NAME as their
name, and VALUE as their value.
2. All your NAME/VALUE fields (INPUT and/or SELECT) are
stored in triples: $make(#name,0,#value)
This is done to make it easy to process as a group.
3. $DISNUM contains the count of the number of NAME/VALUE pairs.
4. $DESTVAL contains the fully-qualified /tmp-path name of the
active file that is to receive your output web page.
That name is also available from: $syseval(lastuse)
5. $PARM contains the name of your protocol (PROTOCOL=name).
6. $XEQ contains the name of your xeq subfile (XEQFILE=name).
7. $PROXYID contains the Unix Process ID number that is the
basis for the active file directory (other than $DESTVAL).
8. $PRISMID contains '~yourname' from the env HOME variable.
9. $CGINAME contains all but the last field from env REQUEST_URI.
10. $PROXYNAME contains 'your.host' name from env HTTP_HOST.
These last three can be used in constructing html references.
See the WEBMODS protocol in the WEBPAGES subfile.
There is a /tmp-directory created in which active files may be
created. This directory (and its content) is destroyed when you
return your resultant web page, which MUST be in $DESTVAL file.
Initially, the $DESTVAL active file contains debugging information.
You must empty this active file before putting your resultant web
page there, and then it must begin with either of these:
Content-type: text/plain
Content-type: text/html
Choose one of those, and then follow with a blank line. Here
is a sample of protocol code for creating the proper header:
scr *
wdse Content-type: text/plain
wdse
There MUST be more than this that you add, possible as little
as another blank line. Here is a sample protocol that will
echo back to you your input fields:
* DEBUG
!set nostop echo
open
let PREFIX = $syseval(prefix)
pick 0
eval $syseval('active:W')
scr *
wdse Content-Type: text/html
wdse
wdse <html><title>Debug Info</title><body><pre>
in act cont show dynvar
in act cont show triples
wdse </pre></body></html>
return
To execute this protocol, the web page would contain:
<INPUT NAME="PROTOCOL" TYPE="hidden" VALUE="DEBUG">
This sample protocol demonstrates several things.
It switches to a temporary active file, and gets
its path (prefix), placing it in a dynamic variable.
It then switches back to the original active file.
The next command insures we can WRITE this file.
We then scratch it, to insure it is empty, and
place our response in it, beginning with the required
header lines. That's all there is to it.
In your protocol, you could be passed NAME/VALUE pairs
that are VARIABLE = "value" pairs on the SPIRES side,
and you would use them to select subfiles, do searches,
choose formats, choose actions (like SEQUENCE), and
eventually do commands like: IN ACTIVE CONTINUE ...
But be aware that any subfiles you select must be selectable
by GS.WWW because that's the account running your protocol.
Wylbur does NOT function with GS.WWW, so you can't do any
Wylbur commands. You can use your protocol subfile as a
place to store canned web pages to be returned. You can
even make "changes" to those web pages before outputting.
Here is an example:
scr *
wdse Content-Type: text/html
wdse
select myprotos ; assumed to have FORMAT = $PROTOCOL;
reference nextpage.html
/perform chngref 'thedate/secretword' to '$UDATE,#PASSWD'
for *
in active cont cln using output.cmd display
save * rep
return
Notice that the PASSWD field is included in the output page from
the INPUT passed to this protocol. So we've communicated back to
the new page the information sent from the input page. Since this
is a "hidden" field, it will be passed on to the next protocol,
which would be specified in the PROTOCOL field of the output page.
My thanks to Travis Brooks at SLAC for providing the seed code for
the suspires.pl driver. As in anything in life, we are not alone.
Dick Guertin
Click on this link to return to the main SUSPIRES index.