"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".
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)]);
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.
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
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)
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.
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.
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?
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.
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.