










            The directory user interface DE

                      Paul Barker
            Department of Computer Science

               University College London
                    United Kingdom

                   February 9, 1993



1  Introduction

DE (which stands for Directory Enquiries) is a
directory user interface primarily intended to serve as
a public access user interface.  However, the
burgeoning number of configurable options are making DE
highly suitable as an interface to be used as a
personally customised tool.  This trend will continue
with further releases of DE.
It is primarily aimed at the novice user, although more
sophisticated users should find that it is flexible
enough to answer the majority of queries they wish to
pose.
The major functional enhancement in this version of DE
over that released with ISODE-8 is that of ``power
searching''.  This allows a user to find a person's
entry in the Directory, even when they do not know the
person's organisation name.  This feature was the one
most often requested by users of earlier versions of
DE. There are several other goodies!  UFN
(user-friendly naming) searches are also now supported,
although this feature needs more work.  A browser mode
can now be configured although the browser code is not
available with this release.  An experimental QOS
feature is also included.  DE keeps track of the speed
with which queries are answered, and uses this simple
database to inform the user of the likely delay in


                           1







getting a response to their particular query.
DE can now also be linked with the LDAP (Lightweight
Directory Access Protocol) libraries produced by Tim
Howes of the University of Michigan.  The source has
also been reorganised to facilitate translation into
other langauges.
DE has more features than those discussed below.
However, the program has extensive on-line help as it
is envisaged that it will often be used in environments
where neither on-line help nor paper documentation will
be available.

2  Using DE

2.1  Starting up

DE will work quite happily without any knowledge of the
user's terminal type, assuming a screen size of 80 x 24
in the absence of terminal type information.  If,
however, the user's terminal type is not recognised by
the system, the user will be prompted to try and enter
an alternative.  The user can examine a list of valid
terminal types; typing <CR> accepts a terminal type of
``dumb''.
It is possible to configure DE to force confirmation of
screen lengths of greater than 24 lines -- this helps
with WAN access as some virtual terminal protocols do
not propagate the screen size.


2.2  Initial Menu

DE now optionally offers a menu on program start-up
which allows a user to select a usage mode.  At the
moment the mode choices are as follows:

S For simple queries.  This is the style of querying
    which has been offered by earlier versions of DE.
    It is ideal when the user know the organisation of
    the person for whom they are searching for details.
    This mode also provides some browsing
    functionality.



                           2







P For power searching.  This is a new mode of searching
    and is ideal when the user knows the name of the
    person they are looking for (as well as the country
    they work in), but does not know the name of the
    organisation.

B For browsing.  This mode offers a user a navigational
    style of querying the Directory.  It is more
    flexible than the ``simple'' mode, but more
    cumbersome.  The code to implement the browser
    comes as a separate release.

I Brief instructions explaining the program modes and
    how to use the program.

? Allows the user to examine the help screens - it is
    also always possible to get help during the course
    of a query.

Q Quit the program.

2.2.1  Switching between modes

The menu provides a way of selecting a querying mode.
It is possible to configure the program (details will
follow) to go straight into a particular mode.
Furthermore, it is also possible to switch between
modes by typing a mode letter at the prompt for a
person's name.  ``s'' selects simple query mode, ``p''
selects power searching, ``b'' selects the browser and
``m'' selects the menu above.

2.3  Simple search mode

This is the mode which will suffice for the vast
majority of queries.  It will not allow the user to get
into every ``corner'' of the Directory, but instead
provides clear prompts, requires no knowledge of
address syntaxes, uses sensible defaults, and is
usually quite fast.  Basically, you have got to have a
good reason to want to use one of the other modes
(there is only one other mode at the moment, but a full
browsing mode will be coming soon).


                           3







2.3.1  Searching for a Person

In this mode, the interface prompts the user for input
with the following four questions (note that it is
possible to optionally suppress the department
question):

    Simple query mode selected
    Person's name, q to quit, * to list people, ? for help
    :- barker
    Dept name, * to list depts, <CR> to search all depts, ? for help
    :- cs
    Organisation name, <CR> to search `ucl', * to list orgs, ? for help
    :-
    Country name, <CR> to search `gb', * to list countries, ? for help
    :-

Note from the above example that it is possible to
configure the interface so that local values are
defaulted:  RETURN accepts ``ucl'' for organisation,
and ``gb'' for country.  The above query returns a
single result which is displayed thus:

    United Kingdom
      University College London
        Computer Science
          Paul Barker
            telephoneNumber       +44 71-380-7366
            electronic mail       P.Barker@cs.ucl.ac.uk
            favouriteDrink        guinness
                                  16 year old lagavulin
            roomNumber            G21

If several results are found for a single query, the
user is asked to select one from the entries matched.
For example, searching for ``jones'' in ``physics'' at
``UCL'' in ``GB'' produces the following output:


    United Kingdom
      University College London

    Got the following approximate matches.  Please select one from the
    list by typing the number corresponding to the entry you want.

                           4








        1 Faculty of Mathematical and Physical Sciences
        2 Medical Physics and Bio-Engineering
        3 Physics and Astronomy
        4 Psychiatry
        5 Psychology

Selecting ``Physics and Astronomy'' by simply typing
the number 3, the search continues, and the following
is displayed:

    United Kingdom
      University College London
        Physics and Astronomy

    Got the following approximate matches.  Please select one from the
    list by typing the number corresponding to the entry you want.

         1 C L Jones     +44 71-380-7139
         2 G O Jones     +44 71-387-7050 x3468  geraint.jones@ucl.ac.uk
         3 P S Jones     +44 71-387-7050 x3483
         4 T W Jones     +44 71-380-7150

In this condensed format, telephone and email
information is displayed.

2.3.2  Searching for other information

Information for organisations can be found by
specifying null entries for the person and department.
Information for departments can be found by specifying
null input for the person field.
Information about rooms and roles can be found as well
as for people by, for example, entering ``secretary''
in the person's name field.

2.3.3  Looking for entries held under localities

Much of the current Directory Information Tree conforms
to the abstraction offered by DE, which is people
within departments within organisations within
countries.  However, an increasing number of
organisations are being registered under locality


                           5







entries underneath the respective country entries.  DE
does not offer a further prompt at the initial asking
for query details, but offers to search localities if
an organisation cannot be found and locality entries
exist in the country in which the search is being made.
The following example shows what happens when a search
for the ``widget corp'' within Australia fails to find
an entry for that company immediately under the
Australia node.

    No organisations match `widget corp'

    Checking to see if entry might be under a locality

    Found the following entries.  Please select one from the list
    by typing the number corresponding to the entry you want.

    Australia
       1 ACT
       2 NSW
       3 NT
       ...
    Locality name, * to list localities, ? for help

The user types in the locality name or corresponding
number, and that locality is then searched for the the
organisation.  If that search fails, the user is
offered the chance to search further localities until
success is achieved or the search is abandoned.

2.3.4  Searching by use of User-Friendly Naming

A style of querying which is becoming increasingly
popular is that of User-Friendly Naming (UFN). The
essence of this style of query formulation is that a
user types in a sequence of strings which represent the
sought person's name, department (often omitted),
organisation, locality (often omitted) and country.
Note that the ``name and address'' is entered in paper
envelope order.  It is possible to reduce the number of
components which have to be typed by locally
configuring a UFN environment - see the file
.../dsap/ufnrc in the ISODE source distribution for


                           6







more details.
User-friendly naming is invoked by entering the UFN at
the prompt for the person's name.  If a UFN is entered
(the program decides it has a UFN by looking for commas
in the entered name), the other prompts are not offered
and a UFN search is made.  The following is an example
of usage.

    Person's name, q to quit, * to list people, ? for help
    :- barker, ucl, gb

    Searching ...

    GB
     University College London
      Computer Science
       Paul Barker
            commonName            Paul Barker
            electronic mail       P.Barker@cs.ucl.ac.uk

As before, if a large number of matches are found, the
user is invited to select from the list offered.  If
none are selected, the program may try and find the
entry elsewhere -- it depends on how closely what the
user types matches the names of entries in the
Directory.

2.3.5  Interrupting

If the user wishes to abandon a query or correct the
input of a query (maybe the user has mis-typed a name),
control-C resets the interface so that it is waiting
for a fresh query.  Typing ``q'' at prompts other than
the person prompt results in the user being asked to
confirm if they wish to quit.  If the user replys
``n'', the interface resets as if control-C had been
pressed.

2.4  Power Searching

This mode is ideal for those queries where you know a
person's name, but do not know the organisation for
which they work.


                           7







The prompts are the same as for the simple mode of
querying, although in this case there is no insistence
that the user enters an organisation name.  Usage is
best explained by a few examples.  The first example
shows how to search for someone called ``barker''
anywhere within Britain:

    Power (multiple organisation) search mode selected
    Person's name, q to quit, ? for help
    :- barker
    Dept name, <CR> to search all depts, ? for help
    :-
    Organisation name, <CR> to search all organisations, ? for help
    :-
    Country name, * to list countries, ? for help
    :- gb

The resulting output will look something like this:

    Initiating searches to 61 organisations................
    Waiting for results ...

      Brunel University
        Administration
             1  Mr F Barker       0895 123456
        Computer Science
             2  Mr G Barker       0895 234567
      University College London
        Computer Science
             3  Paul Barker       071 380 7366    P.Barker@cs.ucl.ac.uk
      etc ...

    You can select one from the list of entries found, or start another query.
    The following options are available:

    nn      Type the number corresponding to the entry you want
    l       To list the results again
    s       To list organisations which were searched
    f       To list organisations which could not be searched (probably because
            of server failure)
    <CR>    To do another multiple organisation search
    q       To quit power searching



                           8







    Enter option: 3

and entry is displayed in full as before.
The scope of the querying can be limited by entering
some organisation details and/or department details.
The following example looks for someone called
``Johnson'' in organisations with London in their name:

    Power (multiple organisation) search mode selected
    Person's name, q to quit, ? for help
    :- johnson
    Department name, <CR> to search all depts, ? for help
    :-
    Organisation name, ? for help
    :- london
    Country name, <CR> to search `-', * to list countries, ? for help
    :- gb

This example shows how to look for someone called Jones
in a Physics department in any organisation in Great
Britain.

    Power (multiple organisation) search mode selected
    Person's name, q to quit, ? for help
    :- jones
    Department name, <CR> to search all depts, ? for help
    :- physics
    Organisation name, ? for help
    :-
    Country name, * to list countries, ? for help
    :- gb


2.5  Quitting

Type ``q'' (or optionally ``quit'' --- see below) at
the prompt for a person's name.  Type ``q'' at other
prompts, and the user is asked to confirm if they wish
to quit.  If the use replys ``n'', the interface resets
back to the person prompt to allow a query to be
entered afresh.




                           9







3  Run-time configuration of DE

DE is configurable either through a user's private
tailor file or by a system wide tailor file.  DE tries
to read a user's .derc file in their HOME directory.
If no such file exists, the system wide detailor file
is read -- this file is situated along with all the
help files in a directory called de/ under ISODE's
ETCDIR.

3.1  Highly recommended options

The detailor file contains a number of tailorable
variables, of which the following are highly
recommended:

dsa_address: This is the address of the access point
    DSA. If two or more dsa_address lines are given, the
    first dsa_address is tried first, the second
    dsa_address is tried if connecting to the first
    address fails.  Third and subsequent dsa_address
    entries are ignored.  If there is no dsa_address
    entry in the detailor file, the first value in the
    dsaptailor file is used.

        dsa_address:Internet=128.16.6.8+17003
        dsa_address:Internet=128.16.6.10+17003

ldapServer: If the program has been linked with the
    LDAP libraries, DE must talk to an LDAP server.
    The hostname of the server is configured by this
    variable.


        ldapServer:pluto

username: This is the username with which the DUA binds
    to the Directory.  It is not strictly mandatory,
    but you are strongly encouraged to set this up.  It
    will help you to see who is connecting to the DSA.

        username:@c=GB@o=X-Tel Services Ltd@cn=Directory Enquiries



                          10







initialMode: This configures the program start-up mode.
    The program can be set-up to start in simple search
    mode, power search mode, or in a menu.  These
    options are selected by the letters `s', `p' and
    `m' respectively.  The default start-up option is
    simple search mode.

        initialMode:m

browserAvail: This allows the optional browser to be
    configured, such that it appears as an option on
    the menu.  The default is off.

        browserAvail:off

3.2  Variables you will probably want to configure

You will almost certainly want to set at least some of
these to suit your local system:

welcomeMessage: This is the welcoming banner message.
    The default is ``Welcome to the Directory
    Service''.

        welcomeMessage:Welcome to DE

byebyeMessage: This enables/disables the display of a
    message on exiting DE. This variable takes the
    values ``on'' and ``off''.  The message displayed
    is the contents of the file debyebye, which should
    be placed in the same directory as all DE's help
    files.  The default is not to display an exit
    message.


        byebyeMessage:on

byebyeScreenTime: If the byebyeMessage is displayed,
    this variable allows the program to be paused for
    the requested number of seconds, and thus ensure
    that the display of the message is retained on the
    screen.  This is done as some access points clear
    the screen immediately the program exits.  The
    default time is 0 seconds.

                          11







        byebyeScreenTime:10

default_country: This is the name of the country to
    search by default:  e.g., ``GB''.

        default_country:gb

default_org: This is the name of the organisation to
    search by default:  e.g., ``University College
    London''

        default_org:University College London

default_dept: This is the name of the department
    (organisational unit) to search by default:  e.g.,
    ``Computing''.  This will usually be null for
    public access duas.


        default_dept:

3.3  Attribute tailoring

The following configuration options all concern the
display of attributes.  The settings in the detailor
file will probably be OK initially.

commonatt: These attributes are displayed whatever type
    of object is being searched for, be it an
    organisation, a department, or a person.

        commonatt:telephoneNumber
        commonatt:facsimileTelephoneNumber

orgatt: These attributes are displayed (as well as the
    common attributes --- see above) if an entry for an
    organisation is displayed.


        orgatt:telexNumber

ouatt: These attributes are displayed (as well as the
    common attributes --- see above) if an entry for an
    organisational unit (department) is displayed.

                          12







        ouatt:telexNumber

prratt: These attributes are displayed (as well as the
    common attributes --- see above) if an entry for a
    person, room or role is displayed.

        prratt:rfc822Mailbox
        prratt:roomNumber

mapattname: This attribute allows for meaningful
    attribute names to be displayed to the user.  The
    attribute names in the quipu oidtables may be
    mapped onto more user-friendly names.  This allows
    for language independence.

        mapattname:facsimileTelephoneNumber fax
        mapattname:rfc822Mailbox electronic mail


mapphone: This allows for the mapping of international
    format phone numbers into a local format.  It is
    thus possible to display local phone numbers as
    extension numbers only and phone numbers in the
    same country correctly prefixed and without the
    country code.

        mapphone:+44 71-380-:
        mapphone:+44 71-387- 7050 x:
        mapphone:+44 :0

greybook: In the UK, big-endian domains are used in
    mail names.  By setting this variable on, it is
    possible to display email addresses in this order
    rather than the default little-endian order.

        greyBook:on

country: This allows for the mapping of the 2 letter
    ISO country codes (such as GB and FR) onto locally
    meaningful strings such as, for English speakers,
    Great Britain and France.

        country:AU Australia


                          13







        country:AT Austria
        country:BE Belgium

3.4  Miscellaneous tailoring

There are a number of miscellaneous variables which may
be set.

localOrgOnly: If this variable is set, only the person
    and department questions are asked and querying is
    restricted to the organisation and country
    specified in the variables default_country and
    default_org.  The intention is that DE could be
    used thus by telephone operators doing local
    look-ups.  If this variable is set, it forces the
    setting of the initialMode variable to simple mode.
    The default setting is off.

        localOrgOnly:on


password: This is the password associated with the
    entry specified by the username variable.  If a
    password is specified the interface tries to bind
    using simple authentication.  If the password is
    wrong, the bind fails and an appropriate message is
    displayed.

        password: thepassword

maxPersons: If a lot of matches are found, DE will
    display the matches in a short form, showing email
    address and telephone number only.  Otherwise full
    entry details are displayed.  This variable allows
    the number of entries which will be displayed in
    full to be set --- the default is 3.

        maxPersons:2

inverseVideo: Prompts are by default shown in inverse
    video.  Unset this variable to turn this off.

        inverseVideo:on


                          14







delogfile: Searches are by default are logged to the
    file de.log in ISODEs LOGDIR. They can be directed
    elsewhere by using this variable.

        delogfile:/tmp/delogfile

logLevel: The logging can be turned off.  It can also
    be turned up to give details of which search
    filters are being successful --- this will
    hopefully allow some tuning of the interface.

     o  Level 0 --- turns the logging off.

     o  Level 1 (the default level) --- logs binds,
        searches, unbinds

     o  Level 2 --- gives level 1 logs, and logging
        analysis of which filters have been successful
        and which failed

        logLevel:2

qos: This variable enables the qos feature.  If this
    feature is used, the user is presented with
    tailored messages as to the likely progress of the
    query according to which part of the DIT is being
    queried.  A simple database is maintained to
    support this option.  This database is maintained
    in a file called de.qos in ISODEs LOGDIR. (Under
    LDAP, the default directory is ``/tmp'' - this may
    be overridden with a Makefile option.)  At present
    there are no tools for maintaining this database,
    and it should be cleared periodically.  More
    details are given in the note ``DE Quality of
    Service''.  The default for this variable is
    ``off''.


        qos:off

remoteAlarmTime: A remote search is one where the
    country and organisation name searched for not the
    same as the defaults.  If the search has not
    completed within a configurable number of seconds,

                          15







    a message is displayed warning the user that all
    may not be well.  The default setting is 30
    seconds.  The search, however, continues until it
    returns or is interrupted by the user.

        remoteAlarmTime:30

localAlarmTime: As for remoteAlarmTime, except for
    local searches.  The default setting is 15 seconds.

        localAlarmTime:15

quitChars: The number of characters of the word
    ``quit'' which a user must type to exit.  The
    default setting is 1 character.


        quitChars:1

allowControlCtoQuit: This enables or disables the
    feature where a user may exit the program by typing
    control-C at the prompt for a person's name.  The
    default setting is on.

        allowControlCtoQuit:on

wanAccess: This enables the feature where a user is
    asked to confirm that the size of their terminal is
    really greater than 24 lines.  This helps with
    telnet access if the screen size is not propagated.
    The default setting is off.

        wanAccess:off

deptQ: This allows the department question to be turned
    off.  The default setting is on.


        deptQ:on

fuzzyMatching: DE uses fuzzy matching if exact and
    substring matching fails.  This option allows fuzzy
    matching to be turned off completely - many users
    find the results of fuzzy matching to be too

                          16







    unpredictable to be useful.  The default setting is
    on.

        fuzzyMatching:on

browserPath: This allows a browser to be exec'ed from a
    non-standard place.  If this is omitted, the
    browser is assumed to be in the ISODE or LDAP
    BINDIR as appropriate.  Note that the variable
    should the full pathname of the executable, and not
    just the directory where the executable may be
    found.

        browserPath:/usr/local/bin/browser


4  Dynamic tailoring

It is possible for a user to modify some variables used
by DE while running the program.  In particular, this
allows a user to recover from a situation where the
terminal emulation is not working correctly --- an
apparently frequent occurrence!
Dynamic tailoring of variables is offered by use of the
SETTINGS help screen.  Typing ?settings at any prompt
will display the current settings of dynamically
alterable variables.  The user is then offered the
opportunity of modifying the variables.  Variables
which may currently be altered in this way are:

termtype: The user's terminal type, as set in the UNIX
    ``TERM'' environment variable.

invvideo: Turn inverse video ``on'' (if the terminal
    supports it) or ``off''.

cols: Set the width of the screen to a number of
    columns.

lines: Set the length of the screen to a number of
    lines.




                          17







5  Compile time configuration of DE

5.1  LDAP configuration

The directory containing the DE source code has a
file called README.LDAP which explains the minor
differences in configuration required to build DE
with the University of Michigan's LDAP libraries.
Questions regarding the LDAP distribution should be
sent to <ldap-support@terminator.cc.umich.edu>.

5.2  Language configuration

All the strings used by DE (with the exception of a
few of the DEBUG variety) have now been gathered
together in a file called messages.h.  This is
intended to facilitate translation of the program
into languages other than English.  The help files
which also need to be translated should keep their
existing names, but a mapping facility is now
provided such that a user can refer to these
screens/files by language independent names.























                      18
