CGI Syntax
Tasks
Ring Mode and Instance Files
Limits
Bugs
Revision History


CGI Syntax

(Vertical bar denotes a choice of arguments; an item in brackets is a placeholder for real text, and anything else should be treated as a literal.)

name=[username]|newcomer
task=a|d|e|f|g|h|j|k|l|m|n|p|s|t|u

Other arguments may be required for certain tasks (see below for details):

here=[ID of current or desired site]
inst=[instance.sequence (assigned by the CGI, see below)]
code=[user's password]
site=[URL of site]
desc=[description of site or name of list]
info=[various miscellaneous info]
conf=[confirmation of user password]

No arguments are required. If Nibelung is called with no arguments or an invalid username, it produces the master list (list of lists) page. There are two optional bare arguments for this:
nibelung?bydate sorts the master list by date added;
nibelung?byname sorts alphabetically by ring name.
At present the default is to sort by name.

If called with a valid username and no task, it goes into ring mode (i.e. the frame) for that user's list. If called with the special user name "newcomer," it produces the new list creation page (and all other arguments are ignored).

No tasks are valid without a user name. If no user, or "newcomer," is specified, tasks and other arguments are ignored.


Tasks

Only the first letter of each task need be specified.

List. Opens the list mode window for the user's list. The list mode window only lists sites, unless the 'code' argument is also correctly provided; it then offers all the list editing options as well.

Next, Previous. Ring mode navigation. Rewrites the instance file (see next section, below) and then repaints the entire frameset with new information. Normally these commands are only sent while Nibelung is in ring mode. If these commands are entered by hand, they will force Nibelung into ring mode anyway. Requires 'here' and uses 'inst.' 'Inst' is filled in automatically by the CGI the first time ring mode is entered, as described below.

Goto. Opens the specified "here" site, jumping into ring mode with that site as the starting point. This is used as the task for an entry-point URL for a site that wants to say, "Hey, look, I'm in this ring!"

Add. Adds a new site to the user's list. Requires a correct 'code.' Also needs 'site,' 'desc,' and 'here.' 'Here,' in this case, is the new ID to assign to that site. 'Site' is the URL, and 'desc' is the name that will appear for that URL. 'Info' - not required - is used for private info on that site, which will only be displayed to the list owner.

Delete. Removes the 'here' site from the list. Requires a correct 'code.'

Edit. Changes the 'here' site's URL, description, or private info, using fields in the same way as Add. Requires a correct 'code.'

Freeze, Unfreeze. Freeze moves the 'here' site into the inactive site list. Site will appear in list mode but not ring mode. Requires a correct 'code.' Unfreeze does the opposite.

Hide, Show. These tasks control a flag in the master list which determines whether this user's list will be displayed when someone requests the master list. It does not hide the site from hand-entered tasks - otherwise the user herself wouldn't be able to use a hidden list! It merely makes the list less visible to the world. Requires a correct 'code.'

Move. Rearranges items in the active list by moving the 'here' site. 'info' controls where to move it; possible values are t|b|u|d, for top of list, bottom of list, up one position, down one position. Requires a correct 'code.'

Join. Creates a new, empty list for the user; adds the user to the master file. 'Code' and 'conf' must both match; this is the user's new password. 'Site' is the user's name, 'desc' is the title of the user's list, and 'info' is the user's email. All three are required. 'Desc' is used on both the master list and the site's list page; the other two are used on the site's list page only.

Title. Changes the name of the list or the list owner's name. Requires a correct 'code.' New name in 'site,' new title in 'desc.'

Kill. Removes the user's list and also removes the user from the master file. Requires both 'code' and 'conf' to match.


Ring Mode and Instance Files

The ring mode works by creating an instance file - a small temporary HTML document - then dynamically sending a fresh frameset, with that instance file as the narrow top frame, and the current ring site in the main frame.

This is designed to defeat frame limitations, i.e. each frame in the frameset has to point to a hard document somewhere; we cannot dynamically send one of the frames at the same time we are sending the frameset. Hence the instance files.

Further subterfuge: The instance file changes name every time the user progresses or retreats through the ring. This forces the instance file to reload when the new frameset is sent, even if their browser is set to cache liberally.

Instance files are named in the format [ringname].[inst].[seq].htm, where inst is a number unique to that particular ring user, and seq is a number unique to each step through the ring. The 'inst' argument contains the most recent inst and seq with a decimal point between.

When the CGI receives this argument, it increments seq by one, and renames the old instance file. Renaming is slightly faster than unlinking the file, but even so, this causes a noticeable speed hit when walking the ring. If we neither renamed nor deleted old sequences, we'd have a huge amount of dead instance files lying around. This way each instance has a maximum of one instance file at a time.

The big speed hit is the first time the user enters ring mode for that ring and that session (i.e. no 'inst' argument is yet available to pass back to the CGI). In the absence of an 'inst,' the CGI looks through all the instance files that match the ringname, to see if there's an instance that's been unmodified for more than 6 hours. If there is, it reuses that instance number (beginning sequence at 1). If not, it picks the lowest unused instance number. This directory-walking takes a while.

The six-hour scan is to prevent proliferation of instance files. There is a better method (see the bug list).


Limits

As noted, instance files get recycled after they haven't been used for six hours. This is arbitrary - see the bug list below.

No more than 100 sites will be allowed in the list. This is done very simply by disabling the Add command once there are 100 sites. Note that this applies to the active list only, which is a hole, but we're not in a big hurry to plug it.

The email address will be verified through mailback, and also used to check that a user doesn't have more than one list. This isn't an utterly stringent policy but no one better get greedy.

Usernames, passwords and site IDs should not contain any characters outside of a-z, 0-9, and _, are not case sensitive, and must be between three and ten characters long.


Bugs

The expiration of instance files after six hours is completely arbitrary and isn't really Nibelung's job. The reason there's a problem in the first place is that we don't have a reliable cue for "user's done with ring mode now, we can clean up the instance file." A better method would be to cron a Perl script which deletes instance files after ___ hours of inactivity. The difficulty is not in writing this script; we're not sure if our ISP allows user-run cron jobs.

Some sites have poorly-behaved JavaScript code which tries to send (apparently) to ALL the windows present, including Nibelung's window ... and in some cases this creates an error about not being able to send commands to windows outside the site's own domain. This is not Nibelung's fault; Nibelung ignores JScript entirely. Unfortunately we do not see an easy way to correct this. More unfortunately, several popular web stats counters have this problem.

An "Access error" has been reported under IE, in circumstances which are not yet clear.

As noted on the list page when editing sites, most of the major editing commands apply to the active list only, which means (for example) that you'd have to move a site from the inactive to the active list in order to edit or delete it.


Revision History (newest at bottom)

March 16-18, 1999 - initial creation, debugging, etc.

March 19, 1999 - Added the sequence number to force reloading (see above). Added links to the master list and main page on any ring's list page. Changed the behavior of 'goto' to load the site in ring mode, instead of unframed. Fixed 'hide,' 'show,' and 'title' so they don't display incorrect information when reloading list.

March 22, 1999 - Made ring navigation frame resizable, for those people who have ungodly huge default fonts.

June 3, 1999 - Raised max number of sites to 100. Added "inactive sites" feature. Added a link back to ring mode from the list page, and other list page reformatting.

July 7, 1999 - Changed the placement of the URL and the links in the navigation frame; the resizability, noted above, wasn't an adequate solution. This way the links should always be usable, and some URLS were so long they were being shoved down onto a second line anyway. Changed master list format to include the names of the ring owners. Added an automatic mailout of the email-verification message for new users. Changed internal URLs to point to nibelung.org instead of impudence.com. Added a 'move' task (see above). Not the best method of doing it, but we're reaching the limits of what can be done with CGI forms. Fixed a bug in the site count (list page) ... 'edit' and 'delete' should be disabled when there are no sites, and 'move' requires at least two, but the inactive sites were being counted in the same lot, which messed up the numbers.

August 31, 1999 - My ISP's web server software suddenly decided that the default file permissions were going to be non-writable. That meant that every time one of the CGIs altered a page (i.e. travelling a ring or changing its info) the page wouldn't be usable! If you were travelling your ring today and you saw "Forbidden" in the top frame, this is why. Changed this CGI (and all my others) to explicitly set file permissions after changing a file.

September 8, 1999 - Added internal logging, so I could keep track of when new rings were being added and what errors were occurring.

October 28, 1999 - Changed list format; now it's possible to enter ring mode from any site (using 'goto' task), or view a site in the same window (previously, list mode sites always opened a new window). Also, slipped in new logos (a few days before); hopefully the big title logo will stop people from asking "Why is it called Nibelung?" :) Moved the main logo to the left on dynamic pages, and switched to a bigger "niblet" logo (this is the small logo in ring mode). Gave niblet a border and resized frame to match. These latter logo changes are for the possibility of advertising - it hasn't happened yet, but it might.

April 2001 - The site moved to a new ISP which required me to change from using 'bin' to using 'cgi-bin,' and as a result everyone's URLs broke. Having immense amounts of trouble sending out notification of this; maybe one or two people will think to check here, but I doubt it.

8 October 2003 - About time, eh? Added an announcement line to ring frame for admin announcements; changed email addresses to be a little more spamproof; tweaked output format for pages; added an activity stamp so we can see which rings have been accessed in editing mode and when, for cleanout purposes; added ability to sort master list display alphabetically.

11 June 2007 - Made user email addresses more spamproof.


nibelung home



Nibelung CGI and pages copyright 1999-2007 t.belton.
The Nibelung maintainers are not responsible
for individual ring or journal contents.

Questions? Comments? Something not working right?
Send mail to valkyries at nibelung dot org.
Please put [Nibelung] at the beginning of the subject
line or it may be deleted as spam.