This document contains Frequently Asked Questions about the
suspires web interface. The paragraphs are arranged by Q and A.
Q: How do I create a protocols subfile for the Web Interface?
A: You could start with the following file definition:
FILE = .WEBPROTO;
RECORD-NAME = PROTO;
DEFINED-BY = $PROTOCOL;
SUBFILE-NAME = xxxPROTO;
GOAL-RECORD = PROTO;
ACCOUNTS = ., GS.WWW;
FORMAT = $PROTOCOL;
You only need replace the "xxxPROTO" name on the SUBFILE-NAME
line by a subfile name of your choosing. You might also want
to change the FILE name, or simply use an existing protocols
subfile that you own. Just be sure it can be selected by GS.WWW
Q: How do I insure the SUBFILE-NAME isn't already being used?
A: In SPIRES, do the following commands:
-> select filedef
-> find subfile <mysubfilename> @acct gs.www
Substitute for <mysubfilename> the actual name, such as xxxPROTO
in this sample. If the result is non-zero, you have a conflict and
must choose a different subfile name. If you get a zero result,
the subfile name is unique from GS.WWW's perspective, which is all
you care about for the moment.
If your subfile name is unique, you can ADD your file definition
to FILEDEF, and compile your file.
-> use <your file definition source>
-> select filedef
-> add
-> /compile $key
Q: Where can I place my Web pages?
A: Your initial Web page, the one that contains the FORM ACTION
that gets you started in SPIRES, should be placed in a directory
named "public_html", which should be a sub-directory of your home
directory. Place your Web page(s) there.
You can also place subsequent Web pages there, those that are used
later in your processing; OR ... you can place subsequent Web pages
in you protocols subfile, which makes it very easy to output.
On Macintosh systems, it is common to use "Sites" instead of "public_html",
and perl scripts usually have to go in /Library/WebServer/CGI-Executables
which is referenced as "cgi-bin" in php and html web pages.
Q: Are there any other things about public_html I should know?
A: YES. Your Web pages, documents, and images must all be
accessible by "wwwuser", and should all be classified as executable
files. That usually means applying the following Unix commands:
Unixprompt> cd ~/public_html
Unixprompt> chmod 755 *
The "cd" command gets you to your public_html directory where
your Web pages and other web-related stuff should be stored.
The "chmod" command sets access/execute permits on ALL of the
current contents of public_html. If you create another file
later, you may have to "chmod 755 thatfile" to set its permits.
Q: How does the Web Server know what types of documents I have?
A: The Web Server uses file suffixes to distinguish the files.
Your main Web Page (and others containing HTML) should end in
the .html or .htm suffix. Plain text files should end in .txt
or .text, and images or pictures normally end in .gif or .jpg
or some other picture-format indicator. Executable scripts,
like the driver for this SPIRES Web Interface are written in
Unix programming languages. The interface is in "perl" (.pl).
This FAQ page is just plain text (.txt), like the MAN page.
Q: What does a basic Web Page look like?
A: The following is a stripped down model of a Web Page:
<HTML>
<HEAD>
<TITLE>Your Title goes here</TITLE>
<!-- For the IMG SRC shown below, the "images" directory -->
<!-- must be within your "public_html" directory. -->
</HEAD>
<BODY>
<!-- Comment: start a new paragraph -->
<P><IMG SRC="images/atwork.gif" ALT="Work"><BR>
<I>This page is always under construction.</I></P>
<P> </P> <!-- This is an empty paragraph spacer -->
<H2>Summer Fun</H2> <!-- This is a heading -->
<HR> <!-- This is a horizontal line break -->
<!-- 169 == (C) symbol -->
<ADDRESS>
© Your Name /
<A HREF=mailto:yourname@email_provider.domain>(yourname@email_provider.domain)</A>
</ADDRESS>
</BODY>
</HTML>
Replace "yourname" in this model by your Unix account name.
At Stanford that usually means: mailto:sunetid@stanford.edu
Also, for all your IMG SRC, you may create the "images"
directory as a sub-directory of "public_html", and copy the image
into that directory. Here are the Unix commands to do all that:
Unixprompt> cd
Unixprompt> cd public_html
Unixprompt> mkdir images
Unixprompt> cd images
Unixprompt> cp -p ~guertin/public_html/images/atwork.gif .
Be careful with that last command. There is an ending dot isolated
from the filename. Be sure to include that trailing dot.
Q: Where do I place my FORM ACTION ... /FORM code?
A: Anywhere within the BODY ... /BODY.
Q: Are there other HTML constructs?
A: Plenty, especially TABLE ... /TABLE, and UL ... /UL that
permit multi-column table presentations, and indentation.
You should check the Web itself for HTML Guides, URLs such as:
http://www.w3.org/MarkUp/Guide
Q: Are there restrictions on the NAMEs I use in my FORM?
A: Only use NAMEs that are acceptible by SPIRES as Variable
or Element names. In particular, Element names allow dots,
dashes and underscores, and Variable names only allow them
if you delimit the variable's name when referenced in SPIRES.
Therefore, we recommend NAMEs without special characters.
All NAMEs are forced to UPPER case in SPIRES.
Q: What other variables may I use?
A: Any that don't conflict with your SELECT or INPUT NAMEs.
There is no need to DECLARE ... ENDDECLARE any variables.
You are running an uncompiled protocol ($XEQ subfile).
Q: Why are triples created?
A: This is another way to store: Variable = value
and it permits Element names, and you can "group" and "sort"
and do other useful things with triples that would be more
difficult to do with a set of dynamic variables. For example,
you could eliminate all NAME/VALUE input that has a null-value
by eliminating them from the triples: eval $unmake($any,0,'')
Q: What restrictions are there on VALUEs?
A: None, but if they contain quotes or apostrophes they may not
be "balanced". VALUEs are $SQU'd and then stored. Mixed or
lower case is preserved.
Q: What restrictions are there on the $DESTVAL output file?
A: Initally the file is empty, and therefore you can create it
by outputting lines to it using WDSE or IN ACTIVE ..., etc. But
once created, if you "use" something else and then try to come
back to the original file, you must reestablish write permission:
use wyl.gg.uuu.some.other.file
; do something with that.
/use $DESTVAL ; go back to the original file.
eval $syseval('active:w') ; reestablish write permission.
Of course the best thing is to stick with $DESTVAL throughout.
Q: What about other "output" files?
A: You can do anything to SPIRES databases that permit update,
but those subfiles must be selectable by GS.WWW account. As for
active files, you're given $DESTVAL, which you MUST return. All
other active files for "output" must be chosen with PICK or OPEN
commands. These are the "actinn.file" datasets that are stored
in a private directory unique to each Web session. You may do
anything with these datasets, they are your "scratch pads".
You may NOT establish write permission with any other datasets,
other than the $DESTVAL or scratch pads. That's because several
sessions could be executing at the same time, and "output" from
one session could clobber the same datasets being used by another.
Q: Can I create HTML output using existing databases?
A: Yes, by using the HTML area, but this is cumbersome.
You could also write your own formats to output HTML.
But, you might be better off creating text/plain output.
Q: If I can't use Wylbur to edit output, what can I do?
A: This is one of the reasons for placing canned-output pages
as records in your xeq protocols subfile. The NAME of the
record can indicate its content: text or html, such as:
* Sample.text
This is the sample text record to be output to the user.
But I want to call you by %yourname% in all messages.
Here is a way to do that.
Assuming you added this record to your protocols subfile, you
can SELECT your protocols subfile (accessible by GS.WWW), and
REFERENCE a record, such as this one. You can then "edit" it
from within SPIRES itself, and then output the edited record.
Note that the edited record is NOT replaced in the protocols
subfile. Only the in-core REFERENCE record is altered.
Here is a relatively complete example, including creation of
the header in the $DESTVAL active file:
scr *
wdse Content-type: text/plain
wdse
/select $XEQ
reference "Sample.text"
if $no : return wdse No Sample.text record.
/perform chngref '%yourname' to '$username'
for *
in active continue using output.cmd display
return ; we are done
Q: What is does PERFORM CHNGREF do?
A: This command changes strings within a set of elements in a
referenced record. For details, explain PERFORM CHNGREF at:
Q: I got an "Internal Server Error" as a response. Why? A: Usually this is an indication that you didn't return the $DESTVAL file with the proper header and/or content. Your output to $DESTVAL must begin with a Content-type line, followed by a blank line, followed by your response web page. If the content is just plain text, your header must indicate: Content-type: text/plain If the content is <html> ... </html>, then indicate this: Content-type: text/html For example, you could do something like this as you start: scr * wdse Content-type: text/plain wdse If you're not sure what is happening, call Dick Guertin for debugging assistance. It is possible to get a "trace" of what is happening, but only by altering the driver page to point to a different driver than "suspires.pl". And only Dick can read the trace. This should be a "last resort". Try debugging it ourself first. Ask yourself these questions: 1. Did I create the "public_html" directory under my account? 2. Did I "chmod 755 ..." on the directories and their content? 3. Am I outputting the necessary headers? 4. Did I give GS.WWW access to my protocol subfile? 5. Is my driver Web page correctly defined in HTML? Q: Is there another form besides POST that can be used? A: YES, there is a METHOD=GET method which is especially useful with <A HREF ...> </A> links in which you wish to pass the variable=values directly. You must convert almost all special characters into %xx codes to prevent them from being misinterpreted by your Browser. The special characters are converted to %xx codes as follows: In a PROTOCOL: let temp = $html(encode,#temp) In a FORMAT or USERPROC: UPROC = set cval = $html(encode,$cval); Replace #temp or $cval by any appropriate #variable or $variable. Here is an example of an <A HREF ...> </A> that can you can send to the suspires interface to execute a specified PROTOCOL, and pass other parms as well: <A HREF="http://lindy.stanford.edu/~guertin/suspires.pl?PROTOCOL=name &SEARCH=find+term+%22The%20Last%20Command%22">The Last Command</A> There are only a few things special in the example above. Notice that '+' is used in place of blank (find+term+ ...), but %20 is also used within the value, which is quoted (%22 through %22). If the original value contained quotes, they would have to be doubled, and then translated to %22 by $html(encode,..). If you want to have '+' in place of blank throughout the <A HREF="string">, then you should translate '%20' to '+' with the $change function after doing encode. Notice that the target PROTOCOL is given by the first parm, which is given following a '?' character that immediately follows the call to the suspires.pl interface. Other variable=value pairs follow the PROTOCOL specification, separated by the '&' character. In this example, we have a SEARCH=expression in which 'The Last Command' is the actual search value, encoded by $html(encode,...). That same search value appears as the link-value of the HREF-link, between the > and </A>. That should be translated by $html(translate,...). Q: Can suspires be used on platforms other than lindy? A: YES! The suspires capability can be installed on a wide variety of other platforms, especially on Mac OS X systems like 10.3.9, 10.4.x, etc. These systems come with Apache installed, and that's all you need to turn your Macintosh into a Web Server, using suspires logic as the interface to Spires Databases. There are some differences. For example, public_html belonging to an individual user becomes Sites belonging to an individual user. That's where you store your html and php scripts. The "a href" and "img src" links refer to your Macintosh as the host, and yourname, like this: "http://your.macintosh.host.name/~yourname/your.html" The ~yourname translates into /Users/yourname/Sites where your.html is stored. Of course, you would substitute your login name for "yourname". "your.macintosh.host.name" would be your computer's host name, which is found by using System Preferences > Network > Network Status to get your IP address, and then use the "host" command in Utilities/Terminal.app to get your computer's host name. The executable scripts, like "suspires.pl", are kept in a common system location sharable by all users on the Macintosh machine. Usually there is only one user, by OS X allows multiple users, each of whom would have their own Sites folder. All executables however are shared in what is called "cgi-bin", which is actually: /Library/WebServer/CGI-Executables Therefore, the FORM ACTION would look something like this: "http://your.macintosh.host.name/cgi-bin/suspires.pl"
Click on this link to read about installing SUSPIRES on Mac OSX.