MAN page from Old RedHat 6.X libnet-1.0606-1.i386.rpm

Net::PH

Section: User Contributed Perl Documentation (3)
Updated: perl 5.005, patch 03
Index

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 Perlas described in the CCSO Nameserver -- Server-Client Protocol. Like othermodules in the Net:: family the Net::PH object inherits methods fromNet::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 thename of the remote host to which a PH connection is required.

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

OPTIONS is an optional list of named options which are passed ina 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 theNameserver, 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 falsevalue, with true meaning that the operation was a success. When a methodstates that it returns a value, failure will be returned as undef or anempty 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/valuepairs 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 whichcontains 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 carriagereturns, or else the query command might fail or return invalid data.

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

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

Returns a reference to an ARRAY which contains references to HASHs, oneper 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/valuepairs which will be passed to the Nameserver as the search criteria.

The MAKE argument is a reference to a HASH which contains field/valuepairs which will be passed to the Nameserver thatwill 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 carriagereturns, or else the query command might fail or return invalid data.

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

Upon success all entries that match the search criteria will havethe 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 andis true then the password will be used to encrypt a challenge text string provided by the server, and the encrypted string will be sent backto 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 arethe 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 areference to a HASH as above, the second element is a reference to an arraywhich contains the tag names in the order that they were returned from theserver.

FIELD_LIST is a string that lists the fields for which info will bereturned.

add( FIELD_VALUES )

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

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

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

FIELD_VALUES is a reference to a HASH which contains field/valuepairs 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 thenew entry will contain. The strings being passed should not contain anycarriage 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 the login manpage before this method can be used.

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

FIELD_VALUES is a string that serves as the search criteria for therecords 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 itslogs. If ID is not given then the UID of the user running theprocess 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 areNet::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;

AUTHORS

Graham Barr <gbarrAATTpobox.com>Alex Hristov <hristovAATTslb.com>

ACKNOWLEDGMENTS

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

Otis Gospodnetic <otisgAATTpanther.middlebury.edu> suggestedpassing parameters as string constants. Some queries cannot be executed when passing parameters as string references.

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

COPYRIGHT

All other code is Copyright (c) 1996-1997 Graham Barr <gbarrAATTpobox.com>and Alex Hristov <hristovAATTslb.com>. All rights reserved. This program isfree software; you can redistribute it and/or modify it under the sameterms as Perl itself.

This document was created byman2html,using the manual pages.