Provided by: libnet-ph-perl_2.21-7_all bug

NAME

       Net::PH - CCSO Nameserver Client class

SYNOPSIS

           use Net::PH;

           $ph = Net::PH->new("some.host.name",
                              Port    => 105,
                              Timeout => 120,
                              Debug   => 0);

           if($ph) {
               $q = $ph->query({ field1 => "value1" },
                               [qw(name address pobox)]);

               if($q) {
               }
           }

           # Alternative syntax

           if($ph) {
               $q = $ph->query('field1=value1',
                               'name address pobox');

               if($q) {
               }
           }

DESCRIPTION

       "Net::PH" is a class implementing a simple Nameserver/PH client in Perl as described in
       the CCSO Nameserver -- Server-Client Protocol. Like other modules in the Net:: family the
       "Net::PH" object inherits methods from "Net::Cmd".

CONSTRUCTOR

       new ( [ HOST ] [, OPTIONS ])
               $ph = Net::PH->new("some.host.name",
                                  Port    => 105,
                                  Timeout => 120,
                                  Debug   => 0
                                 );

           This is the constructor for a new Net::PH object. "HOST" is the name of the remote
           host to which a PH connection is required.

           If "HOST" is not given, then the "SNPP_Host" specified in "Net::Config" will be used.

           "OPTIONS" is an optional list of named options which are passed in a hash like
           fashion, using key and value pairs. Possible options are:-

           Port - Port number to connect to on remote host.

           Timeout - Maximum time, in seconds, to wait for a response from the Nameserver, a
           value of zero will cause all IO operations to block.  (default: 120)

           Debug - Enable the printing of debugging information to STDERR

METHODS

       Unless otherwise stated all methods return either a true or false value, with true meaning
       that the operation was a success. When a method states that it returns a value, failure
       will be returned as undef or an empty list.

       query( SEARCH [, RETURN ] )
               $q = $ph->query({ name => $myname },
                               [qw(name email schedule)]);

               foreach $handle (@{$q}) {
                   foreach $field (keys %{$handle}) {
                       $c = ${$handle}{$field}->code;
                       $v = ${$handle}{$field}->value;
                       $f = ${$handle}{$field}->field;
                       $t = ${$handle}{$field}->text;
                       print "field:[$field] [$c][$v][$f][$t]\n" ;
                   }
               }

           Search the database and return fields from all matching entries.

           The "SEARCH" argument is a reference to a HASH which contains field/value pairs which
           will be passed to the Nameserver as the search criteria.

           "RETURN" is optional, but if given it should be a reference to a list which contains
           field names to be returned.

           The alternative syntax is to pass strings instead of references, for example

               $q = $ph->query('name=myname',
                               'name email schedule');

           The "SEARCH" argument is a string that is passed to the Nameserver as the search
           criteria. The strings being passed should not contain any carriage returns, or else
           the query command might fail or return invalid data.

           "RETURN" is optional, but if given it should be a string which will contain field
           names to be returned.

           Each match from the server will be returned as a HASH where the keys are the field
           names and the values are "Net::PH:Result" objects (code, value, field, text).

           Returns a reference to an ARRAY which contains references to HASHs, one per match from
           the server.

       change( SEARCH , MAKE )
               $r = $ph->change({ email => "*.domain.name" },
                                { schedule => "busy");

           Change field values for matching entries.

           The "SEARCH" argument is a reference to a HASH which contains field/value pairs which
           will be passed to the Nameserver as the search criteria.

           The "MAKE" argument is a reference to a HASH which contains field/value pairs which
           will be passed to the Nameserver that will set new values to designated fields.

           The alternative syntax is to pass strings instead of references, for example

               $r = $ph->change('email="*.domain.name"',
                                'schedule="busy"');

           The "SEARCH" argument is a string to be passed to the Nameserver as the search
           criteria. The strings being passed should not contain any carriage returns, or else
           the query command might fail or return invalid data.

           The "MAKE" argument is a string to be passed to the Nameserver that will set new
           values to designated fields.

           Upon success all entries that match the search criteria will have the field values,
           given in the Make argument, changed.

       login( USER, PASS [, ENCRYPT ])
               $r = $ph->login('username','password',1);

           Enter login mode using "USER" and "PASS". If "ENCRYPT" is given and is true then the
           password will be used to encrypt a challenge text string provided by the server, and
           the encrypted string will be sent back to the server. If "ENCRYPT" is not given, or
           false then the password will be sent in clear text (this is not recommended)

       logout()
               $r = $ph->logout();

           Exit login mode and return to anonymous mode.

       fields( [ FIELD_LIST ] )
               $fields = $ph->fields();
               foreach $field (keys %{$fields}) {
                   $c = ${$fields}{$field}->code;
                   $v = ${$fields}{$field}->value;
                   $f = ${$fields}{$field}->field;
                   $t = ${$fields}{$field}->text;
                   print "field:[$field] [$c][$v][$f][$t]\n";
               }

           In a scalar context, returns a reference to a HASH. The keys of the HASH are the field
           names and the values are "Net::PH:Result" objects (code, value, field, text).

           In an array context, returns a two element array. The first element is a reference to
           a HASH as above, the second element is a reference to an array which contains the tag
           names in the order that they were returned from the server.

           "FIELD_LIST" is a string that lists the fields for which info will be returned.

       add( FIELD_VALUES )
               $r = $ph->add( { name => $name, phone => $phone });

           This method is used to add new entries to the Nameserver database. You must
           successfully call login before this method can be used.

           Note that this method adds new entries to the database. To modify an existing entry
           use change.

           "FIELD_VALUES" is a reference to a HASH which contains field/value pairs which will be
           passed to the Nameserver and will be used to initialize the new entry.

           The alternative syntax is to pass a string instead of a reference, for example

               $r = $ph->add('name=myname phone=myphone');

           "FIELD_VALUES" is a string that consists of field/value pairs which the new entry will
           contain. The strings being passed should not contain any carriage returns, or else the
           query command might fail or return invalid data.

       delete( FIELD_VALUES )
               $r = $ph->delete('name=myname phone=myphone');

           This method is used to delete existing entries from the Nameserver database.  You must
           successfully call login before this method can be used.

           Note that this method deletes entries to the database. To modify an existing entry use
           change.

           "FIELD_VALUES" is a string that serves as the search criteria for the records to be
           deleted. Any entry in the database which matches this search criteria will be deleted.

       id( [ ID ] )
               $r = $ph->id('709');

           Sends "ID" to the Nameserver, which will enter this into its logs. If "ID" is not
           given then the UID of the user running the process will be sent.

       status()
           Returns the current status of the Nameserver.

       siteinfo()
               $siteinfo = $ph->siteinfo();
               foreach $field (keys %{$siteinfo}) {
                   $c = ${$siteinfo}{$field}->code;
                   $v = ${$siteinfo}{$field}->value;
                   $f = ${$siteinfo}{$field}->field;
                   $t = ${$siteinfo}{$field}->text;
                   print "field:[$field] [$c][$v][$f][$t]\n";
               }

           Returns a reference to a HASH containing information about the server's site. The keys
           of the HASH are the field names and values are "Net::PH:Result" objects (code, value,
           field, text).

       quit()
               $r = $ph->quit();

           Quit the connection

Q&A

       How do I get the values of a Net::PH::Result object?

           foreach $handle (@{$q}) {
               foreach $field (keys %{$handle}) {
                   $my_code  = ${$q}{$field}->code;
                   $my_value = ${$q}{$field}->value;
                   $my_field = ${$q}{$field}->field;
                   $my_text  = ${$q}{$field}->text;
               }
           }

       How do I get a count of the returned matches to my query?

           $my_count = scalar(@{$query_result});

       How do I get the status code and message of the last $ph command?

           $status_code    = $ph->code;
           $status_message = $ph->message;

SEE ALSO

       Net::Cmd

AUTHORS

       Graham Barr <gbarr@pobox.com> Alex Hristov <hristov@slb.com>

ACKNOWLEDGMENTS

       Password encryption code ported to perl by Broc Seib <bseib@purdue.edu>, Purdue University
       Computing Center.

       Otis Gospodnetic <otisg@panther.middlebury.edu> suggested passing parameters as string
       constants. Some queries cannot be executed when passing parameters as string references.

               Example: query first_name last_name email="*.domain"

COPYRIGHT

       The encryption code is based upon cryptit.c, Copyright (C) 1988 by Steven Dorner, and Paul
       Pomes, and the University of Illinois Board of Trustees, and by CSNET.

       All other code is Copyright (c) 1996-1997 Graham Barr <gbarr@pobox.com> and Alex Hristov
       <hristov@slb.com>. All rights reserved. This program is free software; you can
       redistribute it and/or modify it under the same terms as Perl itself.

       $Id: //depot/ph/PH.pm#2 $