\chapter{DE}
\label{DUA:de}

DE (which stands for {\bf D}irectory {\bf E}nquiries) is a directory user
interface primarily intended to serve as a public access user interface.  It
is a successor to, and borrows something of the style of, the {\em dsc} 
interface released in a previous version.
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.  

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.

\section {Using DE}

\subsection {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 \verb+<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.

\subsection {Searching for a Person}

The interface prompts the user for input with the following four questions:

\begin{quote}\footnotesize\begin{verbatim}
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
:- 
\end{verbatim}\end{quote}

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:

\begin{quote}\footnotesize\begin{verbatim}
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
\end{verbatim}\end{quote}

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:

\begin{quote}\footnotesize\begin{verbatim}
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.

    1 Faculty of Mathematical and Physical Sciences
    2 Medical Physics and Bio-Engineering
    3 Physics and Astronomy
    4 Psychiatry
    5 Psychology
\end{verbatim}\end{quote}

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

\begin{quote}\footnotesize\begin{verbatim}
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
\end{verbatim}\end{quote}

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

\subsection {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.

\subsection{Interrupting}

If the user wishes to abandon a query or correct the input of a query (maybe
the user has mis-typed a name), {\em 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 {\em control-C} had been
pressed.

\subsection{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 to allow a
query to be entered afresh.

\section {Configuration of DE}

As DE is intended as a public access dua, it is only configurable on a
system-wide basis.
DE installs help files and the \file{detailor} file into a directory 
called \file{de/} under \verb+ISODE+'s ETCDIR.

\subsection{Highly recommended options}

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

\begin{description}

\item [\verb+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 \file{detailor} file, the first value in the
\file{dsaptailor} file is used.

\begin{quote}\small\begin{verbatim}
dsa_address:Internet=128.16.6.8+17003
dsa_address:Internet=128.16.6.10+17003
\end{verbatim}\end{quote}

\item [\verb+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.

\begin{quote}\footnotesize\begin{verbatim}
username:@c=GB@o=X-Tel Services Ltd@cn=Directory Enquiries
\end{verbatim}\end{quote}

\end{description}

\subsection{Variables you will probably want to configure}

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

\begin{description}

\item [\verb+welcomeMessage+:]  This is the welcoming banner message.  The 
default is ``Welcome to the Directory Service''.

\begin{quote}\small\begin{verbatim}
welcomeMessage:Welcome to DE
\end{verbatim}\end{quote}

\item [\verb+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 
{\em debyebye,} which should be placed in the same directory as all
DE's help files.  The default is not to display an exit message.
 
\begin{quote}\small\begin{verbatim}
byebyeMessage:on
\end{verbatim}\end{quote}
  
\item [\verb+default\_country+:]  This is the name of the country to search by
default: e.g., ``GB''.

\begin{quote}\small\begin{verbatim}
default_country:gb
\end{verbatim}\end{quote}


\item [\verb+default\_org+:]  This is the name of the organisation to search by
default: e.g., ``University College London''

\begin{quote}\small\begin{verbatim}
default_org:University College London
\end{verbatim}\end{quote}

\item [\verb+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.

\begin{quote}\small\begin{verbatim}
default_dept:
\end{verbatim}\end{quote}

\end{description}

\subsection{Attribute tailoring}

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

\begin{description}

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

\begin{quote}\small\begin{verbatim}
commonatt:telephoneNumber
commonatt:facsimileTelephoneNumber
\end{verbatim}\end{quote}

\item [\verb+orgatt+:]  These attributes are displayed (as well as the common
attributes --- see above) if an entry for an organisation is displayed.

\begin{quote}\small\begin{verbatim}
orgatt:telexNumber
\end{verbatim}\end{quote}

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

\begin{quote}\small\begin{verbatim}
ouatt:telexNumber
\end{verbatim}\end{quote}

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

\begin{quote}\small\begin{verbatim}
prratt:rfc822Mailbox
prratt:roomNumber
\end{verbatim}\end{quote}

\item [\verb+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.  

\begin{quote}\small\begin{verbatim}
mapattname:facsimileTelephoneNumber fax
mapattname:rfc822Mailbox electronic mail
\end{verbatim}\end{quote}

\item [\verb+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.

\begin{quote}\small\begin{verbatim}
mapphone:+44 71-380-:
mapphone:+44 71-387- 7050 x:
mapphone:+44 :0
\end{verbatim}\end{quote}

\item [\verb+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.

\begin{quote}\small\begin{verbatim}
greyBook:on
\end{verbatim}\end{quote}

\item [\verb+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.

\begin{quote}\small\begin{verbatim}
country:AU Australia
country:AT Austria
country:BE Belgium
\end{verbatim}\end{quote}

\end{description}

\subsection{Miscellaneous tailoring}

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

\begin{description}

\item [\verb+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.

\begin{quote}\small\begin{verbatim}
maxPersons:2
\end{verbatim}\end{quote}

\item [\verb+inverseVideo+:]  Prompts are by default shown in inverse video.  
Unset this variable to turn this off.

\begin{quote}\small\begin{verbatim}
inverseVideo:on
\end{verbatim}\end{quote}

\item [\verb+delogfile+:]  Searches are by default are logged to the file
\file{de.log}
in \verb+ISODE+s LOGDIR.  They can be directed elsewhere by using this
variable.

\begin{quote}\small\begin{verbatim}
delogfile:/tmp/delogfile
\end{verbatim}\end{quote}

\item [\verb+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.

\begin{itemize}
\item Level 0 --- turns the logging off.
\item Level 1 (the default level) --- logs binds, searches, unbinds
\item Level 2 --- gives level 1 logs, and logging analysis of which
filters have been successful and which failed
\end{itemize}

\begin{quote}\small\begin{verbatim}
logLevel:2
\end{verbatim}\end{quote}

\item [\verb+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, 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.

\begin{quote}\small\begin{verbatim}
remoteAlarmTime:30
\end{verbatim}\end{quote}

\item [\verb+localAlarmTime+:]  As for {\em remoteAlarmTime}, except for 
local searches. The default setting is 15 seconds.

\begin{quote}\small\begin{verbatim}
localAlarmTime:15
\end{verbatim}\end{quote}

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

\begin{quote}\small\begin{verbatim}
quitChars:1
\end{verbatim}\end{quote}

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

\begin{quote}\small\begin{verbatim}
allowControlCtoQuit:on
\end{verbatim}\end{quote}

\item [\verb+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.

\begin{quote}\small\begin{verbatim}
wanAccess:on
\end{verbatim}\end{quote}

\end{description}

\section{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 {\tt ?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:

\begin{description}

\item [\verb+termtype+] The user's terminal type, as set in the UNIX ``TERM''
environment variable.

\item [\verb+invvideo+] Turn inverse video ``on'' (if the terminal 
supports it) or ``off''

\item [\verb+cols+] Set the width of the screen to a number of columns

\item [\verb+lines+] Set the length of the screen to a number of lines

\end{description}
