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:email@example.com 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 /afs/ir/group/spires/WWW/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://web.stanford.edu/group/spires/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 www? 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.