DirList2 Server - General Information
Introduction
DirList2 Server is an implementation of the DirList2 specification, both developed by Steven Lawrance. The original DirList Server was a relatively simple CGI program that would poke user home directories, looking for valid web sites to compile for a list of web sites at Bryant College. Since then, a demand for online e-mail addresses changed the course of that program to use a different file format, be more flexible, and eventually allow remote administration. Today, DirList2 can now look and feel like a usable database through the DirList2ODBC driver.
System Object Description Directory entries Stores directory entries and any defined extended data for each entry. Classifications Data that is not predefined in the fields that directory entries have can be defined as classification object and, optionally, have a list of values that extended data values within directory entries can point to. Sorting tables Consistent with DirList2's goal towards high-speed web list generation, different sorting parameters must be predefined in the system. A web page retrieving directory lists tells DirList2 what sort table to use by its ID, and the server will simply read the list of pointers in the sorting table and write each directory entry in the order that they are pointed to in that sorting table. User database For secure web administration, the user database stores the usernames, passwords, and permissions for administration of the DirList2 indexes. Global variables Several variables that the system uses for its operation are stored in the header of the index file.
DirList2 Server defines three different search levels that grant different levels of search ability to a user:
Search Level Number Description NONE 0 You do not have any search rights. ALL 1 You have unrestricted search rights. SOME 2 You have restricted search rights based on a predefined set of rules:
1. All text-based fields using a substring search must have at least three characters in it.
2. If searching the EMailAddress field, the required three characters in substring searches must be to the left of @
3. NOT cannot be used in the search criteriaWhen editing a user, be sure to use the Number for the search level when adjusting it.
In order to allow selective editing in the user database, the user level of a user determines which users that user can modify and/or delete in the user database and which ones cannot be altered. Please note that while anyone with OPERATION_GETUSERS access in the server can view the data of any user, the password is never sent to anyone; instead, any clients using the web administration interface will get blank passwords for the fields, even if it is logged in as the Administrator; it is a write-only field.
A user level means that you can alter users that have the same or higher user level. As a result, the user or users with the lowest user level can alter any user's parameters while the user or users with the highest user level can only edit themself/themselves. Due to this strange security model, it is recommended that very few users have access to OPERATION_MODIFYUSERS and OPERATION_DELETEUSERS, but for those that do have that access, the user level can give you some degree of control as to which user(s) a user can modify.
Sort tables speed up sorted list retrieval by sorting data right before index file saves. Pointers to the file locations of each directory entry are stored in the sort table in the order that they appeared in when they were sorted. When a list is being generated, the server simply reads the sort table pointers and writes each relevant directory entry in the order that they appear in the list of pointers.
When defining directory entries, you can sort into a theoretically infinite number of levels, though usually it is quite rare to get past 3 or 4 levels during most sorts unless if the data is very similar. The only limit is the length of the string, which happens to max out at 2^32-1. The levels are delimited by commas, and no spaces should exist anywhere in the string. You can sort by regular directory data fields, extended data fields, or a combination of the two.
Here is a list of build-in fields and their numbers:
Field Number USERNAME 1 FIRSTNAME 2 LASTNAME 4 LASTNAMEFIRST 8 SEPARATENAMES 16 FLAGS 32 WEBSITE 64 128 TELEPHONE 256 Each level can be one or more fields. To use more than one field in a level, simply add the numbers of the two fields that you want to use. When added, the order between those fields is in increasing field number, so FIRSTNAME would be sorted before WEBSITE, and WEBSITE before EMAIL, for example. If you added FIRSTNAME and LASTNAME but want to have the last name sorted first, simply add LASTNAMEFIRST to that number. Remember that this approach is not required. You can just as easily use two levels in the string and simply put LASTNAME before FIRSTNAME to achieve the same results (that is, you can use "4,2" instead of "14"; it's your choice). Note that adding SEPARATENAMES has no effect on sort tables; it is only used when generating a list of directory entries.
When you want to use extended data, simply use the classification identifier as the number and append either s or o to the end of the number, depending on what type of data you are sorting by. If you are trying to sort by the strings in the extended data, use s. To include values that are not in the classification type definition in the sort (aka, "other" values), you must use s. Otherwise, the next level, if any, is used to differentiate any directory entries that equal and have "other" values defined. If you are sorting by the value identifiers (aka, ordinal values), use o.
If you want to sort descending, place the letter d right after the number. If it's for extended data, the d can appear before or after the s or o. If d is not specified, an ascending sort is assumed.
Here are some example sort strings:
Sort String Description 2,4 First name ascending and then last name ascending 4,1d Last name ascending and then username descending 1o,2ds,4 Classification 1 by ascending value ID, classification 2 by string descending, and then last name 14d Last name descending and then first name descending (2 + 4 + 8 = 14) Note that sort table zero is always sorted by USERNAME. This happens to be the native sort order of the actual database. As a result, sort table zero always exists and cannot be deleted, nor can it be viewed because it does not physically exist in the file. Instead, it implicitly exists by the actual order of the directory entries in the database.
Copyright (c) 2000, 2002, 2004, 2007 Steven Lawrance
Copyright (c) 1999-2000 Bryant College
Written by Steven Lawrance
DirList2 Server Version: 2.9
Last Revision: 03-24-2004