Mumps Based Web Folders
This
directory contains the Mumps code that produces an hierarchical html
folder presentation as used in the left panel of this site
(http://www.cs.uni.edu/~okane). There are two Mumps programs that
accomplish this. The program index.mps creates the display and
the program tab.mps creates the hierarchical data base that
index.mps uses.
The file folder.list contains
the hierarchy script file. Modify folder.list to create your
own hierarchy. Use the folder.list file as a guide. Entries in the
file are two line pairs, separated by a blank line. Each two line
pair consists of, on line one, the text to be displayed in the panel
next to the open or closed folder. The second line contains the URL
of the window to be displayed.
The number of dots at the beginning of
each line determines the depth. Do not skip levels when increasing
depth. There is little error checking so do it right. Both lines must
have the same number of dots. See the example in folder.list To
increase frustration, be certain not to follow these instructions.
Line one "text" may be valid HTML code including
image tags, font tags, etc. so long as the tag sequence is completed
on the line. If you want to embed double quote marks ("), they
must appear in pairs. That is, "" becomes ". Text
should be kept to a minimum as there is a maximum length to the total
number of bytes in a descriptor hierarchy.
The second line
gives the URL of the display to be associated with the text form the
first line. Following the URL is the name of the target window into
which the URL will be loaded. In the example folder.list, you will
see references to the right frame in a two frame display. Note the
quotation marks around the URL. URL's not prefixed with "http://..."
are relative to the base directory.
You may use other window
names to the right of the "target=" sequence. Some window
names, such as "_top" are defined by your browser. If you
use a name not otherwise in use as a frame name or a reserved name, a
new window will be created.
Generally speaking, only lowest
level nodes (those which will appear with a blueball next to them in
the example) will be clickable.
You can invoke the index in its own
window or in a frame. When invoked into a frame, as in the example in
folder.list, you do something like the following:
<html>
<title> Kevin
O'Kane's Mumps Project Page </title>
<frame
src="index.cgi" name=left scrolling=auto marginwidth=0>
<frame src=blank.html name=right marginwidth=0>
</frameset>
</html>
In this example, two
frames are created and named. The left-hand panel is named "left"
and the web folders are opened in this window. A second frame, named
"right" is created with an initial display containing
"blank.html".
To invoke the web folders directly, you
can use, in addition to the above, with:
<a
href="http://www.aaa.bbb.com/index.cgi> text </a>
The
compiled Mumps program, index.cgi, is a binary executable. Some web
servers require a different file extension or placement of the file
in a particular directory. The file should have its protection codes
set so that it can be executed by the web server.
How to
Build a Folder Set
Compile Mumps programs index.mps and
tab.mps. A copy of the Mumps Compiler (http://www.cs.uni.edu/~okane)
is pr ovided with the distribution. The binary executable of the
compiler is the "mumps.compiler" file. It has been compiled
under Mandrake 8.0 and should
execute on most Mandrake and/or Red Hat
systems with no problem. If, however, you do have a problem, download
the source for the compiler from the reference above and rebuild.
The file "mumps" contains the script to compile a
Mumps programs. For example:
./mumps index
will
compile the "index.mps" file. There are several header
files provided that are used by the compiler. The compiler also
generates header files.
The compiler first translates the Mumps program to a C program and then compiles the C program. Copies of the C programs for index.mps
and tab.mps are also provided. Together with the header files, they can be compiled directly. Binary executables created by this process should
have the .cgi suffix or such other
suffix as your web server requires.
The file index_html
contains an example index.html file to initiate a frame based display
(note: the "." has been changed to an "_" so the
file will be visible in the directory listing). The file "index_cgi"
is a binary executable where the "." has been replaced with
"_". Change it back to a ".".
The file
"tab.cgi" is a binary executable. It reads the hierarchy
description (from standard input) and builds the folder data base
(data.dat and global.dat). Be sure that the executables, directories
and data base (key.dat and data.dat) are executable by the web server
and placed in a directory from which cgi scripts can be executed. The
file tab.cgi converts reads the hierarchy description and builds a
data base (key.dat and data.dat). These data base files are used by
index.cgi. You run tab.cgi in the following manner:
tab.cgi <
folder.list
It will produce many lines of stdout output that
indicates the hierarchy being built. The files key.dat and data.dat
will be set to world rw protections. You may wish to change these.
You can set the group and or owner of the .cgi and .dat file to the
same owner or group as the web server and remove world rw.
The
web server must have read and write permissions to key.dat and
data.dat. It will not work if not. The .cgi file must have xecute
permission by the web server. Both these goals can be achieved by
giving the .dat file world rw permissions and giving the .cgi files
world x permission. This is probably a bad idea. It would be better
to put the files into the same group or ownership as the web server
and disable world permissions except for read.
The Mumps data
base program included in the distribution will open the data files
(*.dat) for Exclusive access. This works flawlessly on single
processor Linux systems. We have, however, reports of multiprocessor
Linux systems, especially those using NFS, that indicate that the
Linux exclusive file lock can malfunction. If it does and two
instances of index.cgi gain access to the same data base, one of them
will detect the other and mark the data base as invalid. We have been
unable to reproduce the error.
Working Details
The program
tab.mps reads the hierarchy and creates Mumps global array
references. These areprinte to stdout as tab.mps executes. At
higher levels of the array reference are the less indented entries
while the more indexted entries reside at lower levels. At each node
is stored the URL associated with the node. The maximum depth is
limited by the maximum length of a global array reference, about 500
bytes at present. There is no effective limit to the numer of tags.
Prefixed to each text tag is a code number. This is not
visible in the displayed window. It is there in order to preserve
the sequencing of the text tags.
The default programs use a
global array named "^lib" for the hierarchy. You may have
other hierachies and the URL from one hierarchy can access another.
To specify a hierarchy other than "^lib", use the following
when referencing the
program:
[http://www.aaa.bbb.com/]index.cgi?array=myhierarchy
(the
bracketed text may be omitted if you are remaining in the same host
directory). The program will create folders based on the entries in
the "^myhierarchy" directory. This would be associated
with lines from the folder.list file of the general form:
....
My Other Tree
.... "index.cgi?array=myhierarchy"
target=left
This permits you to branch from tree to tree.
There are ways of directly entering a tree at a level other than the
top but they are some what complicated and will be documented at a
later date.
From the above, it should also be evident that URL
tages in a hierarchy can cause program execution on the web server.