Ph -- provide a perl API for talking to CSO ph servers.
use Ph;
This version of Ph.pm is not compatbile with pre-2.0 versions. Users of older versions (primarily at QUALCOMM) will need to convert their scripts to be compatible with this version of Ph.pm. (This was done to make Ph.pm more object-oriented, allowing multiple connections at once.)
The Ph module provides a uniform API for perl scripts that need to talk to CSO ph servers. It handles many of the messy details automatically. It also maintains an open connection to the server, minimizing the costs of repeated openings and closings of server connections (and the associated costs on the server of repeatedly forking off short-lived processes to service requests made by the client.)
In order to use the Ph protocol module, you will need to have the IO::Socket support and associated perl modules installed. You will also need to use perl 5.003 or later. (See perl.) You should already be familiar with perl data structures and perl references. If not, read perldata and perlref.
It is assumed that you are already familiar with the ph protocol. If you are not, please read The CCSO Nameserver Server-Client Protocol by Steven Dorner and Paul Pomes. It contains all of the descriptions of the various ph requests that one can make. (This API does simplify the problems associated with parsing server responses.)
The constructor takes a number of arguments.
PhServer: Remote Ph server name (default is 'ns').
PhPort: Remove Ph port (default is 'ns', or '105').
Debug: If set, module debugging is enabled.
This constant value is the default port to make connections on if one is not specified as an argument to Connect. Its default value is the value assigned to 'ns' in /etc/services, or 105.
The default ph server to use if not specified in the arguments to Connect. This defaults to 'ns'.
The following methods are provided as part of the API.
This is a request to create a new ph record. The record has fields with values specified by ENTRY, which can be either a reference to an associative array, or it may just be a string itself. Hero login status is required. A boolean return indicates whether the change was successful or not.
This is a request to modify existing ph record(s). The QUERY
is a reference to an associative array, or a query string (Exactly as for
the Query subroutine.) The CHANGES is another reference to an associative array (or
scalar string), containing the field names to be changed, and the new
values that they are to hold. The value returned is the ph result code
returned by the server. NOTE: Fields that are Encrypted (e.g. password) cannot be changed, yet! I will
implement this as soon as I better understand how the encryption works. The
return value is a boolean variable indicating whether or not the change was
successful.
This is a request to establish a connection to a ph server. In addition,
several other requests are sent to the server. They are
id, siteinfo, and fields. The returned values are stored in variables for use later. Only one
connection to a server can be active within a perl program at any one time.
Returns truth on success, false on failure.
This deletes an entire record from the ph server. The record is selected by the query matching ENTRY, which is either a reference to an associative array, or a string query specification. The value returned is the result code returned by the ph server. USE WITH CAUTION! Hero mode is required. Returns true of false to indicate successful or failed results.
This disconnects from the server. It sends the quit request before closing, to be polite to the server. This is also called
automatically by the package destructor, if necessary. No return value is
used.
This returns a string representation of the message associated with the result code returned by the server.
Returns an associative array containing the field attributes for the fields defined by the currently connected ph server. The keys are the field names, and the values are references to an attribute description hash:
name the field name
max the maximum length of the field
desc textual description for the field
* other flags (e.g. Default, Lookup, Public) for the field
This returns the last positive result code returned by the Ph server.
This returns the last message returned by the Ph server. This can be useful in determining the cause of failure -- it sometimes provides more detail than is possible with just the GetLastCode value.
This returns a boolean value which indicates whether or not an active connection to a server has been established.
This request logs into the server, if possible. It should use the
answer method rather than the less secure clear method to encrypt the response. Unfortunately, the cryptit.c file included with the ph distribution is incredibly, well, cryptic! I am not exactly sure what it is doing, and converting it to perl is
proving tiresome. (I have been told that the encryption is based upon a
3-rotor enigma. If anyone is feeling ambitious enough to provide a perl
equivalent, I would be happy to fix this routine.) A truth value is
returned to the caller to indicate whether the login succeeded or not.
Simply put, logout of the ph server! (Obviously, you must be logged in first!) CAUTION: There is a serious bug in some Ph servers which prevents the logout action from removing any privileges. A hero mode session that has been logged out can still destroy the database (accidentally or on purpose). This was discovered the hard way by the author of this package, who had to reenter his entire ph record by hand after running over this bug!
This sends a query to the ph server and builds an array containing references to associative arrays. These associative arrays correspond to matching records, with each field of the match represented by a key in the associative array. QUERY should be a reference to an associative array containing the fields to query for. Alternatively, it can be a string of the form ``field=value ...''.
FIELDS is reference to an array containing the names of the fields to return. If you want to return all fields, just specify the word ``all''. Otherwise, only default fields provided by the server returned. Note that the ph server may enforce certain restrictions about what fields you can view.
The returned value will be an array filled with references to associative arrays. For example, to obtain the phone number of the first person named ``Garrett'' into $phone, you might try this:
@matches = $Ph->Query("name=garrett", "phone");
$phone = $matches[0]->{phone};
Returns an associative array containing the results of the siteinfo
ph request for the currently connected server. Each key corresponds to a
field name in the returned result.
This function is used merely to determine the RCS revision number of the module that you are using. Newer versions may be posted from time to time, and this allows you to determine if you are using the latest version of the Ph module.
This module was written entirely in perl by Garrett D'Amore. It is Copyright 1995, Qualcomm Incorporated and Copyright 1998, 2003 Garrett D'Amore. You can reach the author at the e-mail address garrett@damore.org.