NAME

Ph -- provide a perl API for talking to CSO ph servers.

SYNOPSIS

    use Ph;

NOTICE

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.)

DESCRIPTION

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.)

CONSTRUCTOR

new ( [ARGS])

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.

GLOBALS

$DefaultPhPort

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.

$DefaultPhServer

The default ph server to use if not specified in the arguments to Connect. This defaults to 'ns'.

METHODS

The following methods are provided as part of the API.

Add ENTRY

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.

Change QUERY CHANGES

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.

Connect SERVER PORT

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.

Delete ENTRY

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.

Disconnect

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.

ErrorMessage CODE

This returns a string representation of the message associated with the result code returned by the server.

Fields

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

GetLastCode

This returns the last positive result code returned by the Ph server.

GetLastMessage

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.

IsConnected

This returns a boolean value which indicates whether or not an active connection to a server has been established.

Login ALIAS PASSWORD

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.

Logout

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!

Query QUERY FIELDS

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};

SiteInfo

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.

Version

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.

AUTHOR

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 garrett@qualcomm.com.