Ph -- provide a perl API for talking to CSO ph servers.
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 wil 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.
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.
Querysubroutine.) 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.
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.
quitrequest before closing, to be polite to the server. This is also called automatically by the package destructor, if necessary. No return value is used.
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
answermethod rather than the less secure
clearmethod 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!
siteinfoph 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, Inc. You can reach the author at the e-mail address firstname.lastname@example.org.