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.