This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Persistent/File, Next: Persistent/LDAP, Prev: Persistent/DataType/VarChar, Up: Module List A Persistent Class implemented using a Text File ************************************************ NAME ==== Persistent::File - A Persistent Class implemented using a Text File SYNOPSIS ======== use Persistent::File; use English; # import readable variable names like $EVAL_ERROR eval { ### in case an exception is thrown ### ### allocate a persistent object ### my $person = new Persistent::File('people.txt'); ### define attributes of the object ### $person->add_attribute('firstname', 'ID', 'VarChar', undef, 10); $person->add_attribute('lastname', 'ID', 'VarChar', undef, 20); $person->add_attribute('telnum', 'Persistent', 'VarChar', undef, 15); $person->add_attribute('bday', 'Persistent', 'DateTime', undef); $person->add_attribute('age', 'Transient', 'Number', undef, 2); ### query the datastore for some objects ### $person->restore_where(qq{ lastname = 'Flintstone' and telnum =~ /^[(]?650/ }); while ($person->restore_next()) { printf "name = %s, tel# = %s\n", $person->firstname . ' ' . $person->lastname, $person->telnum; } }; if ($EVAL_ERROR) { ### catch those exceptions! ### print "An error occurred: $EVAL_ERROR\n"; } ABSTRACT ======== This is a Persistent class that uses text files to store and retrieve objects. This class can be instantiated directly or subclassed. The methods described below are unique to this class, and all other methods that are provided by this class are documented in the *Note Persistent: Persistent, documentation. The *Note Persistent: Persistent, documentation has a very thorough introduction to using the Persistent framework of classes. This class is part of the Persistent base package which is available from: http://www.bigsnow.org/persistent ftp://ftp.bigsnow.org/pub/persistent DESCRIPTION =========== Before we get started describing the methods in detail, it should be noted that all error handling in this class is done with exceptions. So you should wrap an eval block around all of your code. Please see the *Note Persistent: Persistent, documentation for more information on exception handling in Perl. METHODS ======= new - Object Constructor ------------------------ use Persistent::File; eval { my $person = new Persistent::File($file, $field_delimiter); }; croak "Exception caught: $@" if $@; Allocates an object. This method throws Perl execeptions so use it with an eval block. Parameters: These are the same as for the *datastore* method below. datastore - Sets/Returns the Data Store Parameters -------------------------------------------------- eval { ### set the data store ### $person->datastore($file, $field_delimiter); ### get the data store ### $file = $person->datastore(); }; croak "Exception caught: $@" if $@; Returns (and optionally sets) the data store of the object. This method throws Perl execeptions so use it with an eval block. Parameters: $file File to use as the data store. $field_delimiter Delimiter used to separate the attributes of the object in the data store. This argument is optional and will be initialized to the value of the special Perl variable $; (or $SUBSCRIPT_SEPARATOR if you are using the English module) as a default. Returns: $file File used as the data store. insert - Insert an Object into the Data Store --------------------------------------------- eval { $person->insert(); }; croak "Exception caught: $@" if $@; Inserts an object into the data store. This method throws Perl execeptions so use it with an eval block. Parameters: None. Returns: None. See the *Note Persistent: Persistent, documentation for more information. update - Update an Object in the Data Store ------------------------------------------- eval { $person->update(); }; croak "Exception caught: $@" if $@; Updates an object in the data store. This method throws Perl execeptions so use it with an eval block. Parameters: *@id* Values of the Identity attributes of the object. This argument is optional and will default to the Identifier values of the object as the default. This argument is useful if you are updating the Identity attributes of the object and you already have all of the attribute values so you do not need to restore the object (like a CGI request with hidden fields, maybe). So you can just set the Identity attributes of the object to the new values and then pass the old Identity values as arguments to the update method. For example, if Pebbles Flintstone married Bam Bam Rubble, then you could update her last name like this: ### Pebbles already exists in the data store, but we don't ### ### want to do an extra restore because we already have ### ### all of the attribute values ### $person->lastname('Rubble'); $person->firstname('Pebbles'); ### set the rest of the attributes ... ### $person->update('Flintstone', 'Pebbles'); Or, if don't want to set all of the object's attributes, you can just restore it and then update it like this: ### restore object from data store ### if ($person->restore('Flintstone', 'Pebbles')) { $person->lastname('Rubble'); $person->update(); } Returns: $flag A true value if the object previously existed in the data store (it was updated), and a false value if not (it was inserted). See the *Note Persistent: Persistent, documentation for more information. save - Save an Object to the Data Store --------------------------------------- eval { $person->save(); }; croak "Exception caught: $@" if $@; Saves an object to the data store. The object is inserted if it does not already exist in the data store, otherwise, it is updated. This method throws Perl execeptions so use it with an eval block. Parameters: None. Returns: $flag A true value if the object previously existed in the data store (it was updated), and a false value if not (it was inserted). See the *Note Persistent: Persistent, documentation for more information. delete - Delete an Object from the Data Store --------------------------------------------- eval { $person->delete(); }; croak "Exception caught: $@" if $@; Deletes an object from the data store. This method throws Perl execeptions so use it with an eval block. Parameters: *@id* Values of the Identity attributes of the object. This argument is optional and will default to the Identifier values of the object as the default. Returns: $flag A true value if the object previously existed in the data store (it was deleted), and a false value if not (nothing to delete). See the *Note Persistent: Persistent, documentation for more information. restore - Restore an Object from the Data Store ----------------------------------------------- eval { $person->restore(@id); }; croak "Exception caught: $@" if $@; Restores an object from the data store. This method throws Perl execeptions so use it with an eval block. Parameters: *@id* Values of the Identity attributes of the object. This method throws Perl execeptions so use it with an eval block. Returns: $flag A true value if the object previously existed in the data store (it was restored), and a false value if not (nothing to restore). See the *Note Persistent: Persistent, documentation for more information. restore_where - Conditionally Restoring Objects ----------------------------------------------- use Persistent::File; eval { my $person = new Persistent::File('people.txt', '|'); $person->restore_where( "lastname = 'Flintstone' and telnum =~ /^[(]?650/", "lastname, firstname, telnum DESC" ); while ($person->restore_next()) { print "Restored: "; print_person($person); } }; croak "Exception caught: $@" if $@; Restores objects from the data store that meet the specified conditions. The objects are returned one at a time by using the *restore_next* method and in a sorted order if specified. This method throws Perl execeptions so use it with an eval block. Since this is a Perl based Persistent class, the *restore_where* method expects the $where argument to use Perl expressions. Parameters: $where Conditional expression for the requested objects. The format of this expression is similar to a SQL WHERE clause. This argument is optional. $order_by Sort expression for the requested objects. The format of this expression is similar to a SQL ORDER BY clause. This argument is optional. Returns: $num_of_objs The number of objects that match the conditions. See the *Note Persistent: Persistent, documentation for more information. SEE ALSO ======== *Note Persistent: Persistent,, *Note Persistent/Base: Persistent/Base,, *Note Persistent/DBM: Persistent/DBM,, *Note Persistent/Memory: Persistent/Memory, NOTES ===== You may notice some lock files (with a '.lock' extension) in the same directory as your data files. These are used to control access to the data files. BUGS ==== This software is definitely a work in progress. So if you find any bugs please email them to me with a subject of 'Persistent Bug' at: winters@bigsnow.org And you know, include the regular stuff, OS, Perl version, snippet of code, etc. AUTHORS ======= David Winters COPYRIGHT ========= Copyright (c) 1998-2000 David Winters. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Persistent/LDAP, Next: Persistent/Memory, Prev: Persistent/File, Up: Module List A Persistent Class implemented using a LDAP Directory ***************************************************** NAME ==== Persistent::LDAP - A Persistent Class implemented using a LDAP Directory SYNOPSIS ======== use Persistent::LDAP; use English; # import readable variable names like $EVAL_ERROR eval { ### in case an exception is thrown ### ### allocate a persistent object ### my $person = new Persistent::LDAP('localhost', 389, 'cn=Directory Manager', 'test1234', 'ou=Engineering,o=Big Snow Org,c=US'); ### declare attributes of the object ### $person->add_attribute('uid', 'ID', 'String'); $person->add_attribute('userpassword', 'Persistent', 'String'); $person->add_attribute('objectclass', 'Persistent', 'String'); $person->add_attribute('givenname', 'Persistent', 'String'); $person->add_attribute('sn', 'Persistent', 'String'); $person->add_attribute('cn', 'Persistent', 'String'); $person->add_attribute('mail', 'Persistent', 'String'); $person->add_attribute('telephonenumber', 'Persistent', 'String'); ### query the datastore for some objects ### $person->restore_where('& (objectclass=person)(mail=*bigsnow.org)', 'sn, givenname'); while ($person->restore_next()) { printf("name = %s, email = %s\n", $person->givenname . ' ' . $person->sn, $person->mail); } }; if ($EVAL_ERROR) { ### catch those exceptions! ### print "An error occurred: $EVAL_ERROR\n"; } ABSTRACT ======== This is a Persistent class that uses a LDAP directory to store and retrieve objects. This class can be instantiated directly or subclassed. The methods described below are unique to this class, and all other methods that are provided by this class are documented in the *Note Persistent: Persistent, documentation. The *Note Persistent: Persistent, documentation has a very thorough introduction to using the Persistent framework of classes. This class is part of the Persistent LDAP package which is available from: http://www.bigsnow.org/persistent ftp://ftp.bigsnow.org/pub/persistent DESCRIPTION =========== Before we get started describing the methods in detail, it should be noted that all error handling in this class is done with exceptions. So you should wrap an eval block around all of your code. Please see the *Note Persistent: Persistent, documentation for more information on exception handling in Perl. METHODS ======= new - Object Constructor ------------------------ use Persistent::LDAP; eval { my $obj = new Persistent::LDAP($host, $port, $bind_dn, $password, $base_dn); }; croak "Exception caught: $@" if $@; Allocates an object. This method throws Perl execeptions so use it with an eval block. Parameters: These are the same as for the *datastore* method below. datastore - Sets/Returns the Data Store Parameters -------------------------------------------------- eval { ### set the data store ### $ldap = $obj->datastore($host, $port, $bind_dn, $password, $base_dn); ### or set it like this ### $ldap = $obj->datastore($ldap, $base_dn); ### get the data store ### $ldap = $obj->datastore(); }; croak "Exception caught: $@" if $@; Returns (and optionally sets) the data store of the object. This method throws Perl execeptions so use it with an eval block. Parameters: $host Hostname or IP address of the remote (LDAP Directory) server $port Port to connect to on the remote server $bind_dn Bind to the LDAP directory with the given DN $password Password for the bind DN $base_dn The base DN to start all searches/updates $ldap (also a return value) Connection to the LDAP directory insert - Insert an Object into the Data Store --------------------------------------------- eval { $obj->insert(); }; croak "Exception caught: $@" if $@; Inserts an object into the data store. This method throws Perl execeptions so use it with an eval block. Parameters: None. Returns: None. See the *Note Persistent: Persistent, documentation for more information. update - Update an Object in the Data Store ------------------------------------------- eval { $obj->update(); }; croak "Exception caught: $@" if $@; Updates an object in the data store. This method throws Perl execeptions so use it with an eval block. Parameters: *@id* Values of the Identity attributes of the object. This argument is optional and will default to the Identifier values of the object as the default. This argument is useful if you are updating the Identity attributes of the object and you already have all of the attribute values so you do not need to restore the object (like a CGI request with hidden fields, maybe). So you can just set the Identity attributes of the object to the new values and then pass the old Identity values as arguments to the update method. For example, if Pebbles Flintstone married Bam Bam Rubble, then you could update her last name like this: ### Pebbles already exists in the data store, but we don't ### ### want to do an extra restore because we already have ### ### all of the attribute values ### $person->uid('pflintstone'); ### new value of ID attribute ### $person->sn('Rubble'); ### new lastname ### $person->commonname('Pebbles'); ### old firstname ### ### set the rest of the attributes ... ### $person->update('prubble'); ### old value of ID attribute ### Or, if don't want to set all of the object's attributes, you can just restore it and then update it like this: ### restore object from data store ### if ($person->restore('pflintstone')) { $person->uid('prubble'); $person->sn('Rubble'); $person->update(); } Returns: $flag A true value if the object previously existed in the data store (it was updated), and a false value if not (it was inserted). See the *Note Persistent: Persistent, documentation for more information. save - Save an Object to the Data Store --------------------------------------- eval { $person->save(); }; croak "Exception caught: $@" if $@; Saves an object to the data store. The object is inserted if it does not already exist in the data store, otherwise, it is updated. This method throws Perl execeptions so use it with an eval block. Parameters: None. Returns: $flag A true value if the object previously existed in the data store (it was updated), and a false value if not (it was inserted). See the *Note Persistent: Persistent, documentation for more information. delete - Delete an Object from the Data Store --------------------------------------------- eval { $obj->delete(); ### or ### $obj->delete(@id); }; croak "Exception caught: $@" if $@; Deletes an object from the data store. This method throws Perl execeptions so use it with an eval block. Parameters: *@id* Values of the Identity attributes of the object. This argument is optional and will default to the Identifier values of the object as the default. Returns: $flag A true value if the object previously existed in the data store (it was deleted), and a false value if not (nothing to delete). See the *Note Persistent: Persistent, documentation for more information. restore - Restore an Object from the Data Store ----------------------------------------------- eval { $obj->restore(@id); }; croak "Exception caught: $@" if $@; Restores an object from the data store. This method throws Perl execeptions so use it with an eval block. Parameters: *@id* Values of the Identity attributes of the object. This method throws Perl execeptions so use it with an eval block. Returns: $flag A true value if the object previously existed in the data store (it was restored), and a false value if not (nothing to restore). See the *Note Persistent: Persistent, documentation for more information. restore_where - Conditionally Restoring Objects ----------------------------------------------- use Persistent::LDAP; eval { ### allocate a persistent object ### my $person = new Persistent::LDAP('localhost', 389, 'cn=Directory Manager', 'test1234', 'ou=Engineering,o=Big Snow Org,c=US'); ### query the datastore for some objects ### $person->restore_where('& (objectclass=person)(mail=*bigsnow.org)', 'sn, givenname'); while ($person->restore_next()) { printf("name = %s, email = %s\n", $person->givenname . ' ' . $person->sn, $person->mail); } }; croak "Exception caught: $@" if $@; Restores objects from the data store that meet the specified conditions. The objects are returned one at a time by using the *restore_next* method and in a sorted order if specified. This method throws Perl execeptions so use it with an eval block. Since this is a LDAP implemented Persistent class, the *restore_where* method expects a RFC-2254 compliant LDAP search filter as the first argument, $where. Please see the `Net::LDAP::Filter' documentation or RFC-2254 for more information. A good starting point for finding RFCs on the web is the following: http://www.yahoo.com/Computers_and_Internet/Standards/RFCs/ The second argument, $order_by, should be a valid SQL ORDER BY clause. Which is just a comma separated list of attribute values to sort by with an optional ASC or DESC token to sort in ascending or descending order. Please refer to a SQL reference for a more detailed explanation of ORDER BY clauses. Since LDAP directories allow multiple values for an attribute, when an attribute with multiple values is used to sort by (used in an ORDER BY clause), only the first value of the attribute is used for sorting. For more information on attributes with multiple values, please see the following section in this document on using accessor methods. Parameters: $where Conditional expression for the requested objects. This is a RFC-2254 compliant LDAP search filter. This argument is optional. $order_by Sort expression for the requested objects. The format of this expression is similar to a SQL ORDER BY clause. This argument is optional. Returns: $num_of_objs The number of objects that match the conditions. See the *Note Persistent: Persistent, documentation for more information. Accessor Methods - Accessing the Attributes of an Object -------------------------------------------------------- eval { ### getting attribute values ### my $mail = $person->mail(); ### a single value ### my @classes = $person->objectclass(); ### multiple values ### ### setting attribute values ### $person->mail($newmail); ### a single value ### my @new_classes = ('top', 'person', 'organizationalPerson'); $person->objectclass(@new_classes); ### multiple values ### $person->objectclass(\@new_classes); ### multiple values by ref ### }; croak "Exception caught: $@" if $@; Sets/gets the value(s) of the attributes of the object. Since this method is implemented using a LDAP directory, multiple values for an attribute are allowed. So in order to handle this, the accessor methods can be used in an array context or a scalar context. If the attribute has only a single value then access it in a scalar context. And if the attribute allows multiple values then access it in an array context. If the attribute has multiple values and it is accessed in a scalar context only the first value will be returned but if a single value is passed to it then the attribute will be set to the single scalar value. Example: $person->objectclass('top', 'person', 'inetOrgPerson'); $class = $person->objectclass(); ### $class == 'top' ### @classes = $person->objectclass(); ### @classes == ('top', 'person', 'inetOrgPerson') ### This method throws Perl execeptions so use it with an eval block. Parameters: $value or *@values* or *\@values* Value(s) of the attribute of the object. The value(s) can be either a single scalar value, an array of multiple values, or a reference to an array of multiple values. Returns: $value or *@values* Returns a scalar value if used in a scalar context and returns an array when used in an array context. See the *Note Persistent: Persistent, documentation for more information. data - Accessing the Attribute Data of an Object ------------------------------------------------ eval { ### set the attributes ### $person->data({givenname => 'Marge', sn => 'Simpson'}); ### get and print the attributes ### my $href = $person->data(); print "name = ", $href->{'givenname'} . ' ' . $href->{'sn'}; print "email = ", $href->{'mail'}; }; croak "Exception caught: $@" if $@; Returns or sets all of the values of the attributes. If an attribute has multiple values then a reference to an array of values is returned for that attribute. And to set multiple values to an attribute, a reference to an array of values should be passed. Example: ### get the multiple values for the attribute ### my $href = $person->data(); my @classes = @{$href->{'objectclass'}}; ### superfluous copy ### print "objectclasses = ", join(', ', @classes), "\n"; ### set the multiple values for the attribute ### my @new_classes = ('top', 'person'); $person->data({objectclass => \@new_classes}); This method throws Perl execeptions so use it with an eval block. Parameters: \%hash A hash with keys that are the names of the attributes and values that are the values of the attributes. This argument is optional and is used for setting the value(s) of the attributes. Returns: \%hash Same as the argument above except that it is the returned value(s) of the attributes. See the *Note Persistent: Persistent, documentation for more information. SEE ALSO ======== *Note Persistent: Persistent,, *Note Persistent/Base: Persistent/Base, BUGS ==== This software is definitely a work in progress. So if you find any bugs please email them to me with a subject of 'Persistent Bug' at: winters@bigsnow.org And you know, include the regular stuff, OS, Perl version, snippet of code, etc. AUTHORS ======= David Winters COPYRIGHT ========= Copyright (c) 1998-2000 David Winters. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Persistent/Memory, Next: Ph, Prev: Persistent/LDAP, Up: Module List A Persistent Class implemented using Memory (RAM) ************************************************* NAME ==== Persistent::Memory - A Persistent Class implemented using Memory (RAM) SYNOPSIS ======== use Persistent::Memory; use English; # import readable variable names like $EVAL_ERROR eval { ### in case an exception is thrown ### ### allocate a persistent object ### my $person = new Persistent::Memory(); ### define attributes of the object ### $person->add_attribute('firstname', 'ID', 'VarChar', undef, 10); $person->add_attribute('lastname', 'ID', 'VarChar', undef, 20); $person->add_attribute('telnum', 'Persistent', 'VarChar', undef, 15); $person->add_attribute('bday', 'Persistent', 'DateTime', undef); $person->add_attribute('age', 'Transient', 'Number', undef, 2); ### query the datastore for some objects ### $person->restore_where(qq{ lastname = 'Flintstone' and telnum =~ /^[(]?650/ }); while ($person->restore_next()) { printf "name = %s, tel# = %s\n", $person->firstname . ' ' . $person->lastname, $person->telnum; } }; if ($EVAL_ERROR) { ### catch those exceptions! ### print "An error occurred: $EVAL_ERROR\n"; } ABSTRACT ======== This is a Persistent class that uses memory (RAM) to store and retrieve objects. This can be useful when you want to create a cache of objects (i.e. a server-side web cache). This class can be instantiated directly or subclassed. The methods described below are unique to this class, and all other methods that are provided by this class are documented in the *Note Persistent: Persistent, documentation. The *Note Persistent: Persistent, documentation has a very thorough introduction to using the Persistent framework of classes. This class is part of the Persistent base package which is available from: http://www.bigsnow.org/persistent ftp://ftp.bigsnow.org/pub/persistent DESCRIPTION =========== Before we get started describing the methods in detail, it should be noted that all error handling in this class is done with exceptions. So you should wrap an eval block around all of your code. Please see the *Note Persistent: Persistent, documentation for more information on exception handling in Perl. METHODS ======= new - Object Constructor ------------------------ use Persistent::Memory; eval { my $person = new Persistent::Memory($field_delimiter); }; croak "Exception caught: $@" if $@; Allocates an object. This method throws Perl execeptions so use it with an eval block. Parameters: These are the same as for the *datastore* method below. datastore - Sets/Returns the Data Store Parameters -------------------------------------------------- eval { ### set the data store ### $person->datastore($field_delimiter); ### get the data store ### $href = $person->datastore(); }; croak "Exception caught: $@" if $@; Returns (and optionally sets) the data store of the object. This method throws Perl execeptions so use it with an eval block. Parameters: $field_delimiter Delimiter used to separate the attributes of the object in the data store. This argument is optional and will be initialized to the value of the special Perl variable $; (or $SUBSCRIPT_SEPARATOR if you are using the English module) as a default. Returns: $href Reference to the hash used as the data store. insert - Insert an Object into the Data Store --------------------------------------------- eval { $person->insert(); }; croak "Exception caught: $@" if $@; Inserts an object into the data store. This method throws Perl execeptions so use it with an eval block. Parameters: None. Returns: None. See the *Note Persistent: Persistent, documentation for more information. delete - Delete an Object from the Data Store --------------------------------------------- eval { $person->delete(); }; croak "Exception caught: $@" if $@; Deletes an object from the data store. This method throws Perl execeptions so use it with an eval block. Parameters: *@id* Values of the Identity attributes of the object. This argument is optional and will default to the Identifier values of the object as the default. Returns: $flag A true value if the object previously existed in the data store (it was deleted), and a false value if not (nothing to delete). See the *Note Persistent: Persistent, documentation for more information. restore - Restore an Object from the Data Store ----------------------------------------------- eval { $person->restore(@id); }; croak "Exception caught: $@" if $@; Restores an object from the data store. This method throws Perl execeptions so use it with an eval block. Parameters: *@id* Values of the Identity attributes of the object. This method throws Perl execeptions so use it with an eval block. Returns: $flag A true value if the object previously existed in the data store (it was restored), and a false value if not (nothing to restore). See the *Note Persistent: Persistent, documentation for more information. restore_where - Conditionally Restoring Objects ----------------------------------------------- use Persistent::Memory; eval { my $person = new Persistent::Memory('|'); $person->restore_where( "lastname = 'Flintstone' and telnum =~ /^[(]?650/", "lastname, firstname, telnum DESC" ); while ($person->restore_next()) { print "Restored: "; print_person($person); } }; croak "Exception caught: $@" if $@; Restores objects from the data store that meet the specified conditions. The objects are returned one at a time by using the *restore_next* method and in a sorted order if specified. This method throws Perl execeptions so use it with an eval block. Since this is a Perl based Persistent class, the *restore_where* method expects the $where argument to use Perl expressions. Parameters: $where Conditional expression for the requested objects. The format of this expression is similar to a SQL WHERE clause. This argument is optional. $order_by Sort expression for the requested objects. The format of this expression is similar to a SQL ORDER BY clause. This argument is optional. Returns: $num_of_objs The number of objects that match the conditions. See the *Note Persistent: Persistent, documentation for more information. SEE ALSO ======== *Note Persistent: Persistent,, *Note Persistent/Base: Persistent/Base,, *Note Persistent/DBM: Persistent/DBM,, *Note Persistent/Memory: Persistent/Memory, NOTES ===== This Persistent class does not lock the data store (a hash in this case) before reading or writing it. This should not be a problem unless you are using threaded Perl or forking processes that share an object of this class. BUGS ==== This software is definitely a work in progress. So if you find any bugs please email them to me with a subject of 'Persistent Bug' at: winters@bigsnow.org And you know, include the regular stuff, OS, Perl version, snippet of code, etc. AUTHORS ======= David Winters COPYRIGHT ========= Copyright (c) 1998-2000 David Winters. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Ph, Next: PlotCalendar/DateDesc, Prev: Persistent/Memory, Up: Module List provide a perl API for talking to CSO ph servers. ************************************************* 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 *Note IO/Socket: IO/Socket, support and associated perl modules installed. You wil also need to use perl 5.003 or later. (See *Note Perl: (perl.info)perl,.) You should already be familiar with perl data structures and perl references. If not, read *Note Perldata: (perl.info)perldata, and *Note Perlref: (perl.info)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! 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*.  File: pm.info, Node: PlotCalendar/DateDesc, Next: PlotCalendar/DateTools, Prev: Ph, Up: Module List Perl extension for interpreting a file of periodic (like weekly) events and assigning actual dates to them. Used to feed the calendar plotting software. *********************************************************************************************************************************************************************************************************************************** NAME ==== PlotCalendar::DateDesc - Perl extension for interpreting a file of periodic (like weekly) events and assigning actual dates to them. Used to feed the calendar plotting software. SYNOPSIS ======== require PlotCalendar::DateDesc; my ($month, $year) = (3,1999); # ---- set the month and year my $trans = PlotCalendar::DateDesc->new($month, $year); # ---- parse a description and return the day of the month my $day = 'first monday and third monday'; print "$day : ",join(',',@{$trans->getdom($day)}),"\n"; $day = 'last monday and third monday'; print "$day : ",join(',',@{$trans->getdom($day)}),"\n"; $day = 'last fri and third Monday'; print "$day : ",join(',',@{$trans->getdom($day)}),"\n"; # ---- parse a description and return the date as mm/dd/yyyy $day = 'last fri and third Monday'; print "$day dates: ", join(',',@{$trans->getdates($day)}),"\n"; What gets returned by both routines is a pointer to an array of answers DESCRIPTION =========== input descriptions may be one of : a day of the week (monday, tuesday, etc) a qualified day of the week (first monday, second tuesday, last sunday) compound statements are allowed : mon and wed, first mon and third mon Qualifiers are : first, second, third, fourth, fifth, last Compounds are only formed with 'and' and are not associative AUTHOR ====== Alan Jackson March 1999 ajackson@icct.net SEE ALSO ======== PlotCalendar::Month PlotCalendar::Day  File: pm.info, Node: PlotCalendar/DateTools, Next: PlotCalendar/Day, Prev: PlotCalendar/DateDesc, Up: Module List This is an all perl replacement for parts of Date::Calc. I'd love to use it, but I ran into trouble installing the compiled C onto my hosting service account, since I can't do a compile over there (it'd cost $$) So I have reproduced those functions I needed in perl. Oh well. ************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************ NAME ==== PlotCalendar::DateTools - This is an all perl replacement for parts of Date::Calc. I'd love to use it, but I ran into trouble installing the compiled C onto my hosting service account, since I can't do a compile over there (it'd cost $$) So I have reproduced those functions I needed in perl. Oh well. SYNOPSIS ======== require PlotCalendar::DateTools; my ($day, $month, $year) = (5,3,1999); my $dayname = 'Tuesday'; # ---- initialize tool my $dow = Day_of_Year($yr,$mon,$day); my $numdays = Days_in_Month($yr,$mon); my $dow = Decode_Day_of_Week($dayname); my $dowfirst = Day_of_Week($yr,$mon,$day); my ($nyr, $nmon, $nday) = Add_Delta_Days($yr,$mon,$day, $numdays); my $dayname = Day_of_Week_to_Text($dow) my $month = Month_to_Text($mon); my $doy = Day_of_Year($year,$mon,$day); DESCRIPTION =========== A perl-only clone of a subset of Date::Calc AUTHOR ====== Alan Jackson April 1999 ajackson@icct.net REQUIREMENTS ============ Requires modules : Exporter Carp Time::DaysInMonth Time::JulianDay SEE ALSO ======== PlotCalendar::Month PlotCalendar::Day  File: pm.info, Node: PlotCalendar/Day, Next: PlotCalendar/Month, Prev: PlotCalendar/DateTools, Up: Module List Generate ascii or html for a single day in a calendar ***************************************************** NAME ==== PlotCalendar::Day - Generate ascii or html for a single day in a calendar SYNOPSIS ======== Creates a Day object for plotting as ASCII, HTML, or in a Perl/Tk Canvas. Intended to be gathered together by Month.pm to create a traditional calendar. DESCRIPTION =========== Measurements in pixels because - well, because. It seemed simpler when I made the decision. And it works for both Tk and HTML. The day is laid out like this : ------------------------------------------ | | | | | digit | digit | Main day name | | | | | | | | | | | | | |---------|--------| | <- bgcolmain | | | | | | | Optional text | | . | | | | Optional Text | | . | | . | | . | | . | | Optional text | | . | | . | | . | | . | ------------------------------------------ Globals : height, width, dayfont, mainfont, optfont, fgcol, bgcolmain, digit Optionals : dayname, optext[...] Font sizes in HTML translate as (rounding up) : 6->-1 8->+0 10->+1 12->+2 14->+3 Various quantities can be set globally, or over-ridden for specific cases. This is really meant to be called by month.pm to construct a calendar, but calling it with a *really big size* is a way to "zoom in" on a given day EXAMPLE ======= require PlotCalendar::Day; my $digit=10 ; # do it for the tenth my $day = PlotCalendar::Day->new($digit); # These are values with default settings, so these are optional ------------ size of whole thing in pixels, X,Y $day -> size(100,100); ------------ Global foreground and background colors $day -> color('BLACK','#33cc00',); $day -> color('WHITE','RED',); ------------ Font sizes for digits, dayname, and optional text $day -> font('14','10','8'); ------------ styles for digits, dayname, and optional text ------------ b=bold, i=italic, u=underline, n=normal $day -> style('bi','nbu','i'); ------------ Clip text to avoid wrapping? (yes/no) $day -> cliptext('yes'); # HTML only options ------------ is it allowed to expand vertically if there is too much text? $day -> htmlexpand('yes'); # These values are defaulted to blank ------------ day name $day -> dayname('Groundhog Day'); ------------ if set, name is a hotlink $day -> nameref(''); ------------ if set, text string is a hotlink. Note that an array is getting ------------ passed. Text is passed as an array also. Each line of text is ------------ an array element. THis example hotlinks only the first 2 lines. $day -> textref('',''); ------------ unload what I set my @size = $day->size; my @color = $day->color; my @font = $day->font; my @text = $day->text; my $dayname = $day->dayname; # So, what do we have now? ------------ Create an ascii text cell #my $text = $day -> gettext; ------------ Create and return html for a cell in a table my $html = $day -> gethtml; ------------ Create and return Tk code (not implemented yet) #my $tk = $day -> gettk; print "\n"; print "

Normal Day

\n"; print "\n"; print $html; print "
\n"; AUTHOR ====== Alan Jackson March 1999 ajackson@icct.net