PH(3pm)

💖 NAME 💖

Net::PH — bestie, it's the 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, exactly as described in the CCSO Nameserver -- Server-Client Protocol. And like its siblings in the Net:: family, the Net::PH object inherits methods from Net::Cmd. Slay. 👑

---

🎀 CONSTRUCTOR 🎀

new ( [ HOST ] [, OPTIONS ])

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

Okay so this is the constructor for a brand new Net::PH object, no cap. HOST is the name of the remote host you want a PH connection to, periodt.

If HOST is not given, then the SNPP_Host specified in Net::Config will be used. (Yes bestie, SNPP_Host, that's literally what it says, we do not question the lore. 💀)

OPTIONS is an optional list of named options, passed in a hash-like fashion with key and value pairs, iykyk. The possible options are:

• Port — the port number to connect to on the remote host. 🔌
• Timeout — the 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 — turns on the printing of debugging information to STDERR. 🐛

---

✨ METHODS ✨

Unless otherwise stated, all methods return either a true or a false value, and true means the operation was a success, obviously. When a method says it returns a value, failure gets 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 the matching entries. 🔍

The SEARCH argument is a reference to a HASH which contains field/value pairs — those get passed to the Nameserver as the search criteria.

RETURN is optional, but if you give it, it should be a reference to a list containing the field names to be returned. 💅

The alternative syntax is to pass strings instead of references, like:

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

Then SEARCH is a string passed to the Nameserver as the search criteria. And listen — these strings 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 that will contain the field names to be returned.

Each match from the server comes back as a HASH where the keys are the field names and the values are Net::PH:Result objects (code, value, field, text). Iconic.

It 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 the matching entries. 🔧

The SEARCH argument is a reference to a HASH containing field/value pairs that get passed to the Nameserver as the search criteria.

The MAKE argument is a reference to a HASH containing field/value pairs that get passed to the Nameserver, and those will set new values to the designated fields.

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

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

Then SEARCH is a string passed to the Nameserver as the search criteria. Again, bestie: these strings should not contain any carriage returns, or else the query command might fail or return invalid data. 🙈

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

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

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 gets sent back to the server. 🔐

If ENCRYPT is not given, or is false, then the password will be sent in clear text — and that is not recommended, bestie, do not do that. 😭

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 that HASH are the field names, and the values are Net::PH:Result objects (code, value, field, text). 🗂️

In an array context, it returns a two element array. The first element is a reference to a HASH as described above, and the second element is a reference to an array containing the tag names in the order that they were returned from the server. Order matters, bestie! 🌸

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 adds 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 containing field/value pairs that get 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');

Then FIELD_VALUES is a string consisting of field/value pairs that the new entry will contain. And yes: these strings 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 deletes existing entries from the Nameserver database. You must successfully call login before this method can be used. 🔑

Note that this method deletes entries from 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. Bye bestie! 👋

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 instead. 📝

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 that HASH are the field names and the 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> and 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 $

---

And that's a wrap, bestie!! 🌈✨ This whole lil masterpiece is documented as perl v5.36.0, dated 2022-10-13 — go be the main character of your own nameserver queries. 💅🦋