Net::PH

NET::PH(1)            User Contributed Perl Documentation           NET::PH(1)



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 fasion, 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, falure 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.

           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 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 the 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";
               }

           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).

           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 sucessfully call the login manpage before this mathod can
           be used.

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

           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.

       delete( FIELD_VALUES )

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

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

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

           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 Namesever, 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
       the Net::Cmd manpage

AUTHORS
       Graham Barr <Graham.Barr@tiuk.ti.com> Alex Hristov <hristov@slb.com>

ACKNOWLEDGEMENTS
       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 the University of Illinois Board of Trustees, and by
       CSNET.

       All other code is Copyright (c) 1996 Graham Barr
       <Graham.Barr@tiuk.ti.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.




3rd Berkeley Distribution    perl 5.003, patch 07                   NET::PH(1)