PH(1L)              UNIX Programmer's Manual               PH(1L)

NAME
     ph - CCSO Nameserver client (on-line phone book)

SYNOPSIS
     ph [ -s server ] [ -p port ] [ -t type ] [ -f field1,field2,...  ]
        [ -mMrRbBTlLF ] query
     ph [ -s server ] [ -p port ] [ -t type ] [ -f field1,field2,...  ]
        [ -h topic ] [ -mMnNrRbBTlLFcC

DESCRIPTION
     Ph queries the CCSO Nameserver, a database of University
     faculty, staff, and students.  The database contains nearly
     all the information in the Student/Staff Directory (the
     University phone book), as well as other information,
     including electronic mail addresses.

     Ph may be used in two ways; interactively or with command-
     line arguments.

     If given arguments, ph will treat the arguments as a query
     and return the results of the query.  For example,

          ph paul pomes

     would return the entry for the maintainer of ph , Paul
     Pomes.  For more information on what types of queries you
     may make, see the QUERIES section below.

     If given no arguments, ph will enter interactive mode, print
     a prompt, and wait for commands.  Interactive mode will be
     discussed in detail below.

     Ph is not intended for the generation of mailing lists.
     Therefore, it will refuse any requests resulting in more
     than a small number of matches.  This is not negotiable.

OPTIONS
     Ph recognizes the following options.  They may be specified
     in the PH environment variable, given on the command line,
     or set with the switch command from inside ph.  Options
     given with the switch command override all others; options
     given on the command line override those in the PH environ-
     ment variable.

     -n   Do not read the .netrc file.  This option has meaning
          only when using ph in interactive mode (see below for
          descriptions of the .netrc file and interactive mode).

     -N   Do read the .netrc file.  This is the default.

     -r   Do not reformat alias and email fields to show alias-
          based e-mail addresses.

     -R   Reformat alias and email fields to show alias-based e-
          mail addresses.  This is the default.

     -b   Do not beautify query responses; print them in gory
          detail, complete with response codes.

     -B   Beautify query responses.  This is the default.

     -m   Do not use a paging program (like more(1)) when print-
          ing responses.

     -M   Use a paging program.  This is the default.

     -l   Do not label field values with field names when print-
          ing queries.

     -L   Label field values with field names when printing
          queries.  This is the default.

     -t type
          Use type as a default type on queries.  This is just
          like adding type=type to all queries.  The -t option
          can be overriden by specifying an explicit type in the
          query, as in, "ph pomes type=phone".

     -T   Do not specify any type by default; this is the
          default.

     -s server
          Use server as a Nameserver host, instead of the default
          host.  A list of suitable servers may be found with the
          query "ph alias=ns-servers".

     -p port
          Connect to the tcp port port, instead of the default
          port.

     -c   Do not wait for confirmation of edit commands.  This is
          the default.

     -C   Wait for confirmation of edit commands (see edit
          below).

     -f field1,field2,...
          Return fields field1,field2,... instead of the default
          list of fields, if no return clause is specified on
          queries.  This is just like adding "return field1
          field2 ..." to all queries.

     -F   Return default list of fields; this is the default.

     -h topic
          Display a list of on-line help topics.  If the -h
          option is followed by the name of one of the on-line
          help topics, the help screen for topic will be
          displayed.

QUERIES
     The Nameserver's database contains over 70,000 entries.
     Each entry is comprised of multiple fields, each containing
     information about the entry.  Each field has a name that is
     descriptive of what the field contains; for example, the
     field named address contains the office mail address of the
     person in question (for more information on fields, see the
     description of the fields command in the INTERACTIVE section
     below).

     By default, queries are assumed to refer to the name or
     nickname field of the entry.  Therefore, saying "ph john
     doe" looks for entries whose name or nickname field contains
     "john" and "doe".  Fields other than the name and nickname
     fields must be specified; for example,

          ph pomes address=DCL

     would return entries with name or nickname "pomes" whose
     address contained "DCL."

     Matching in ph is done on a word-by-word basis.  That is,
     both the query and the entry are broken up into words, and
     the individual words are compared.  Although ph is insensi-
     tive to case, it otherwise requires words to match exactly,
     with no characters left over; "john" does not match "john-
     son", for example.  This behavior may be overriden by the
     use of normal shell metacharacters ("?" to match any single
     character, "*" to match zero or more characters, and "[]" to
     match a single character from a set of characters).

     Ph will display only entries that match all of the specifi-
     cations in the query.  For example,

          ph paul pomes

     will return all entries with both "paul" and "pomes" in the
     name or nickname fields.

     Ph returns a certain set of fields by default.  It is possi-
     ble to ask for different fields in a query.  This is done by
     specifying the return keyword and listing the fields of
     interest.  For example,

          ph paul pomes return email

     would print only the electronic mail address of the main-
     tainer of ph.  You may also ask for all fields in the entry
     by using "all" as a field name.  This will show you every
     field you are allowed to see in the entry.

     All output from ph is sent through more(1) (or whatever pro-
     gram is specified in the PAGER environment variable).

INTERACTIVE MODE
     If ph is given no arguments, it enters interactive mode,
     where it prompts for, executes, and displays the results of
     Nameserver commands.  Interactive mode provides access to
     more Nameserver features than mere queries.  Some of these
     features require the user to identify him/her self to ph by
     use of the login command; others do not.  Commands may be
     abbreviated, provided enough characters are given to distin-
     guish them from other commands.

     .netrc file
          Ph reads the same .netrc file as does ftp (see ftp(1)).
          If it finds a machine named "ph" that has a login and a
          password specified for it, ph will automatically do a
          login command, using the values from the .netrc file.
          Ph will silently refuse to use a .netrc file that has
          any permissions for group or other (see chmod(1)).

     Public Commands

     The following commands do not require the user to be logged
     in to the Nameserver:

     help [topic]
               Provides explanations of Nameserver commands.
               Given no arguments, help lists the available help
               topics.  Given a topic as an argument, help will
               print help for that topic.  A list of commands and
               a one-line description of each command may be
               obtained by requesting the topic commands.

     query     Performs Nameserver queries exactly like non-
               interactive ph queries except that metacharacters
               do not have to be quoted.

     fields    Lists the fields currently in use in the
               Nameserver.  For each field, a display like the
               following (admittedly ugly) is produced:

               -200:2:email:max 64 Lookup Public Default Change
               -200:2:email:Preferred electronic mail address.
               ...

               The leading number is a reply code from the
               Nameserver.  The next number is the field number.
               Following the field number is the name of the
               field, the maximum length of the field, and the
               attributes for the field.  The second line has, in
               addition to repeated reply code, number, and name,
               a one-line description of the field.

               The attributes determine how a field may be used.
               Lookup means the field may be searched in a query.
               Indexed means the field is indexed (at least one
               Indexed field must be included in every query).
               Default means the field is displayed by default.
               Change means that users may change the field.

     set option[=value]
               Allows Nameserver options to be set.  These
               options are for future use.

     switch  -option [value]
               Allows ph options to be set.  See the OPTIONS sec-
               tion above.

     quit      Exits ph.

     login alias
               Identifies the user to the Nameserver.  Alias is
               your Nameserver alias, a unique name for you in
               the Nameserver; it is printed in ph queries, as
               the first thing after "email to:":

               email to: p-pomes@uiuc.edu (paul@uxc.cso.uiuc.edu)

               In this case, the alias is "p-pomes".  You will be
               prompted for your Nameserver password when you
               give the login command, unless you are using ph
               from the login in your email field (the one in
               parentheses on the "email to:" line), and your
               system administrator has made ph "setuid root", in
               which case no password will be required.

               Your Nameserver password is not the same as your
               system password; the only way to discover your
               Nameserver password is to bring yourself and a
               University ID to the CCSO Accounting Office in
               1420 DCL.  Because of abuses in the past, pass-
               words cannot be given out via email, phone, or to
               third parties.

               You are allowed to change your Nameserver alias;
               there are, however, restrictions on Nameserver
               aliases; they must be unique within the
               Nameserver, they cannot be common names ("david"
               is right out), and they can only contain letters,
               digits, dashes (-) and periods (.).

     Commands Requiring Login

     The following commands require that the user executing them
     be logged in to the Nameserver.

     passwd [alias]
               Changes your Nameserver password.  You will be
               asked to type your new password twice.  Ph will
               complain if your password is too short or contains
               only numbers (although it does allow such pass-
               words).  Privileged users may change the passwords
               of certain other users by specifying the alias of
               the other user when giving the passwd command.

     me        Lists the Nameserver entry of the currently
               logged-in user.

     edit field [alias]
               Allows ph users to change those fields in their
               entry that have the Change attribute set.  Edit
               will retrieve the value of the named field (if a
               value exists), and will allow the user to edit the
               value with vi(1) (the EDITOR environment variable
               may be used to override the use of vi).  The
               changed value will then be reinserted in the
               Nameserver.  If the -C option is in effect, the
               message, "Change the value [y]?" will be printed
               after the editing is finished.  Pressing return
               alone, or anything beginning with "y", will make
               ph change the value; anything beginning with "n"
               will make ph discard the changes.

     make field=value [field2=value2...]
               Allows ph users to change those fields in their
               entry that have the Change attribute set.  Make
               will set the specified field(s) to the specified
               value(s) in the entry of the currently logged in
               user.

     add       Adds entries to the Nameserver.  This is a
               privileged command.

     delete    Deletes entries from the Nameserver.  This is a
               privileged command.

     logout    Undoes the effects of a login command.

QUERY EXAMPLES
     Here are some examples to clarify ph queries.  Each example
     is preceded by a description of the desired effect.  It is
     assumed that the queries are being done with ph from the
     command line, rather than by using the interactive mode of
     ph.  The only difference for interactive mode is that meta-
     characters would not have to be quoted or escaped.

     Find the ph entry for Paul Pomes:

          ph paul pomes

     Find the ph entry for P. Pomes, where the rest of the first
     name is not known:

          ph p\* pomes

     Find Alonzo Johnson (or is that JohnsEn?):

          ph alonzo johns\?n
      or
          ph alonzo johns\[eo\]n

     Find Paul P., where the rest of the last name is unknown:

          ph paul p\*

     The last query fails because it matches too many entries.
     It is therefore necessary to narrow the search.  Suppose it
     is known that Paul P. has an office in DCL:

          ph paul p\* address=DCL

     Alternately, suppose Paul P. works for CCSO.  You might try:

          ph paul p\* department=CCSO

     When that failed, a good next guess would be:

          ph paul p\* department=computing

     The moral of the story is that fields in ph generally con-
     tain whatever the user wishes them to contain, and, hence,
     there may be many different spellings and abbreviations for
     any particular field (some fields are exceptions, including
     the name field, which is always the full name, as known to
     the University, of the person involved).  It pays to make
     liberal use of metacharacters and creativity when searching
     fields other than name.

     Suppose all that is wanted is the full name and electronic
     mail address of P. Pomes:

          ph p\* pomes return name email

RENAMING PH
     If ph is invoked with a name other than ph, slightly dif-
     ferent option processing is done.  For the sake of an exam-
     ple, let us assume ph was invoked with the name, "unit".
     The following consequences obtain:

     Ph will assume an option of "-t unit".  Ph will read the
     UNIT environment variable, after reading the PH environment
     variable, and before reading command-line options.

     This feature allows the easy installation of entry-type
     specific lookup commands, as well as custom configuration of
     those commands.

BUGS
     Separate words in a query are allowed to match the same word
     in the entry; "ph s\* smith" is functionally equivalent to
     "ph smith", because the "s*" is allowed to match "smith".

     Ph does some looking about in the commands you give it, but
     does not understand the full syntax of Nameserver commands.
     This can occasionally lead to mistakes, especially when
     dealing with quoted strings.

DISTRIBUTION
     Source code for ph is available by anonymous ftp to
     uxc.cso.uiuc.edu, in the file pub/ph.tar.Z.  The complete
     system, including source for the qi(8) server side is in the
     file pub/qi.tar.Z.  This source works on 4.[23]BSD UNIX sys-
     tems.  Any troubles encountered porting ph to a particular
     system are of interest to the maintainer of ph, as are ports
     done to other operating systems.

SEE ALSO
     The CCSO Nameserver - An Introduction, by Steven Dorner;
     updated by Paul Pomes.
     The CCSO Nameserver - Server-Client Protocol, by Steven
     Dorner; updated by Paul Pomes.
     qi(8)

AUTHOR
     Steve Dorner (sdorner@qualcomm.com), Qualcomm, Inc.  (form-
     erly at the University of Illinois Computing and Communica-
     tions Services Office)

     The code is now maintained by Paul Pomes (p-pomes@uiuc.edu),
     University of Illinois Computing and Communications Services
     Office.
