KE::Statistics perl module

The KE::Statistics perl module provides a set of objects to make the creation of tasks easier. The module is located in the utils/KE directory on the EMu server.

KE::Statistics - A set of objects usable by periodic scripts.

use KE::Statistics;

my %Title =
(
      "0"     => "Records by Table",            # English title
      "1"     => "Enregistrements par table",   # French title
);

sub
Periodic
{
      my $session = shift;
      my $date = shift;
      my $period = shift;

      my $users = $session->users();
      my $tables = $session->tables();
      my $operations = $session->operations("eregistry");

      my $query = "Select all from eregistry where Key1 = " .
                  $session->quote() . "User" . $session->quote();
      my $results = $session->search($query);

      while ($results->next())
      {
              my $key = $results->text("Key1");
              ...
      }
      $results->close();

      my $stats = $session->statistics();
      my $yesterday = $date->yesterday();
      $stats->setDate($yesterday);
      $stats->setDateFrom($yesterday);
      $stats->setDateTo($yesterday);
      $stats->setKey1("Records By Table");
or
          $stats->setTitle($period, \%Title);

      $stats->setValue("3");
      $stats->write();
}

The KE::Statistics module provides a set of objects to facilitate the generation of records for the estatistics table. The Periodic Tasks subsystem provides a plug-in mechanism that allows new tasks to be added to the existing framework. Each task is contained within a perl library (.pl file) and must contain at least one function, the Periodic($session, $date, $period) method.

The arguments are:

$session

A KE::Statistics::Session object provides a connection to the back-end database environment. The object may be used to gather information to generate statistical values and to create estatistics records.

$date

A KE::Statistics::Date object contains the date and time at which the Periodic Tasks subsystem was invoked. The $date object is used to determine the date/time range of the statistical information for the task invoked.

$period

A string that contains the name of the time period for the task being run. Typical periods include hourly, daily, weekly and monthly. Administrators may create new periods (e.g. fortnightly) as required, in which case $period will contain the name of the new period.

The Periodic() function is called by the Periodic Tasks subsystem at a scheduled time (e.g. hourly, daily, weekly, monthly, etc.) to create records in the estatistics table.

The following objects are provided within the module:

A KE::Statistics::Session object is used to gather information from the back-end server. The object may query any table or set of tables to allow statistical information to be generated. A set of methods allows information about the server environment to be gathered (e.g. list of registered users, list of tables, etc.).

As a Session object is provided as an argument to the Periodic() function, it is not necessary to create the object yourself, rather the supplied object should be used (which is efficient as only one Session object is used by all tasks invoked in the current execution). As the Session object is shared, you must not close() it in your task.

new()

 

$session = KE::Statistics::Session->new();

Creates a connection to the server environment. As the Periodic Tasks subsystem provides a Session object to your task, it is not necessary to use this method. The return value is an instance of a Session object.

search($texql)

 

$results = $session->search("count(select all from eparties)");

Executes a TexQL query statement on the server. The $texql argument may be any valid TexQL query statement. The return value is a KE::Statistics::ResultSet object. If the query statement is invalid, an undef value is returned.

statistics()

 

$stats = $session->statistics();

After your tasks have generated statistical information, it is necessary to write the data into estatistics records. The KE::Statistics::Statistics object provides a convenient object for creating estatistics records. The statistics() method returns a Statistics object that may be used to create the records.

quote()

 

$texql = "select all from eparties where NamLast contains " . $session->quote() . "Badenoff" . $session->quote();

When building TexQL statements, non-numeric values must be enclosed within quotes. The quote character is configurable and is set to avoid escaping characters within values. The default quote character is \001 (CTRL+A). The quote() method returns the current quote character.

close()

 

$session->close();

Once all communication with the server environment is complete, the connection needs to be closed so that system resources can be returned to other users. The close() method terminates a Session connection. As the Periodic Tasks subsystem handles the creation and closing of the session, you should not call this method.

users()

 

foreach my $user (@{$session->users()})

The users() method returns a reference to a list of registered users in the server environment. The list is built from records in the server registry (eregistry table).

tables()

 

foreach my $table (@{$session->tables()})

The tables() method returns a reference to a list of tables in the server environment. The Table Access Registry entry is used to build the list of tables.

operations($table)

 

foreach my $operation (@{$session->operations("eparties")})

The operations() method returns a reference to a list of audit operations enabled for the table supplied in the $table argument. The list returned is populated by operations defined by texaudit. Use texaudit -h to get a complete list of the available operations.

A KE::Statistics::ResultSet object is returned by the KE::Statistics::Session->search($texql) method. The object provides access to the records returned as a result of the specified query. Once you have finished dealing with the ResultSet object, it is necessary to close() it so that system resources can be returned to other users.

new()

 

$results = KE::Statistics::ResultSet->new($cursor)

A ResultSet object provides a convenient mechanism for dealing with a query cursor ($cursor). The cursor is returned by the server environment when a search has completed. As a ResultSet object is returned by KE::Statistics::Session->search($texql), it is not necessary to create instances of ResultSet objects.

next()

 

while ($results->next())

When a ResultSet object is returned by KE::Statistics::Session->search($texql), the current record is positioned before the first record. The next() method moves the current record position to the next matching record. A value of 0 is returned if you are past the last matching record, otherwise 1 is returned.

text($column)

 

$value = $results->text("NamLast");

The text() method returns the value for the column specified by $column argument. The value is returned as a string. If the column does not exist, an undef value is returned.

close()

 

$results->close();

Once you have finished with the records in the ResultSet object, you should close() the object so that server resources are returned to users. If you do not close a ResultSet object, it will be closed by the Periodic Tasks subsystem once it has completed processing all tasks.

In order to make the manipulation of dates easier, the KE::Statistics::Date object is provided. The object contains a breakdown of a date ({year}, {month}, {day}, {hour}, {minute} and {second}). A number of methods are provided that allow the date/time to be manipulated.

To help with arithmetic manipulation of dates the julianNumber() method is provided to return the Julian date (see http://en.wikipedia.org/wiki/Julian_day for details). The integer part of the floating point number returned represents the day number, while the fractional part encodes the time within the day. Normal arithmetic may be applied to the number. The julianDate() method is used to convert a Julian date to a Dateobject. For example, the following code could be used to find the date three days back from today:

$now = KE::Statistics::Date->new();
$then = KE::Statistics::Date->julianDate($new->julianNumber() - 3);

Subtracting two Julian dates will result in the number of days, hours, minutes and seconds between them:

$diff = $now - $then;

When using dates with TexQL query statements, always specify the date in ODBC format (yyyy-mm-dd). The dateText() method provides the value in the correct format. Similarly, time values should be specified using a 24 hour clock (HH:MM:SS). The timeText() method provides the value formatted correctly.

Encoding dates as a Julian number with the time as the fractional component can lead to issues when subtracting dates, as the result represents the number of days, hours, minutes and seconds between the two dates. If you need to find the number of days between two dates, it is necessary to clear the time component before applying the subtraction:

$date1->set(undef, undef, undef, 0, 0, 0);
$date2->set(undef, undef, undef, 0, 0, 0);
$days = abs($date2->julianNumber() - $date1->julianNumber());

While this not a bug, it is something to keep in mind when manipulating Julian date numbers.

new($year, $month, $day, $hour, $minutes, $seconds)

 

$date = KE::Statistics::Date->new();
$date = KE::Statistics::Date->new(2009, 02, 11);
$date = KE::Statistics::Date->new(2009, 02, 11, 16, 55, 02);

The new() method creates a new instance of a Date object. Up to six arguments may be provided to initialise the Date object with a given date and / or time. If any arguments are missing, the component for the current date/time is used. Thus, calling new() without any arguments provides a Date object with the current date and time.

clone()

 

$newdate = $date->clone();

The clone() method creates a copy of a Date object initialised with the same date/time as the calling Date object.

yesterday()

 

$yesterday = $date->yesterday();

Returns a new Date object initialised with yesterday's date. The value is 24 hours before the calling Date object; that is, the time component is not changed.

lastHour()

 

$newdate = $date->lastHour();

Returns a new Date object initialised with the date/time one hour before the date/time of the calling Date object.

lastSecond()

 

$newdate = $date->lastSecond();

Returns a new Date object initialised with the date/time one second before the date/time of the calling Date object.

lastWeek()

 

$newdate = $date->lastWeek();

Returns a new Date object initialised with the date/time one week before the date/time of the calling Date object.

lastMonth()

 

$newdate = $date->lastMonth();

Returns a new Date object initialised with the date/time one month before the date/time of the calling Date object. If the resulting date is past the end of the month, the last day of the month is used.

set($year, $month, $day, $hour, $minute, $second)

 

$date->set(2010, 12, 14); $date->set(undef, undef, undef, 0, 0, 0);

The set() method allows any component of a Date object to be assigned a value. If undef is provided for a component, the component's current value is maintained. If a component is missing, a value of undef is assumed.

compare($date)

 

if ($date1->compare($date2) == 0)

The compare() method compares two Date objects for equality. The return value can be used to determine the equality of the objects:

-1 - date argument is lower than date object
0 - date argument is same as Date object
+1 - date argument is greater than Date object

compareDate($date)

 

if ($date1->compareDate($date2) == 0)

The compareDate() method compares two Date objects for equality at the date level. The time component is ignored. The return value can be used to determine the equality of the object's dates:

-1 - date argument is lower than date object
0 - date argument is same as date object
+1 - date argument is greater than Date object

compareTime($date)

 

if ($date1->compareTime($date2) == 0)

The compareTime() method compares two Date objects for equality at the time level. The date component is ignored. The return value can be used to determine the equality of the object's times:

-1 - date argument is lower than date object
0 - date argument is same as date object
+1 - date argument is greater than date object

dateText()

 

$texql = "select all from eaudit where AudDate = DATE" .

$session->quote() . $date->dateText() . $session->quote();

The dateText() method returns a text representation of the object's date in ODBC format (yyyy-mm-dd). The value is suitable for DATE values in TexQL queries regardless of the date format used on the server.

timeText()

 

$texql = "select all from eaudit where AudTime = TIME" .

$session->quote() . $date->timeText() . $session->quote();

The timeText() method returns a text representation of the object's time in ODBC format (HH:MM:SS). The value is suitable for TIME values in TexQL queries regardless of the time format used on the server.

julianNumber($date)

 

$julian = $date->julianNumber();

The return value of julianNumber() is a floating point number representing the day number in the integer part and the time (in 1/86400th of a second) in the fractional part. Note that the Julian number for a day represents midday for the given day. Any time before midday will have an integer value one less than any time after midday. To get the Julian number for any time within a day it is necessary to add 0.5 before calling int(). Thus:

$daynumber = int($date->julianNumber() + 0.5);

returns the Julian day number. See http://en.wikipedia.org/wiki/Julian_day for details.

julianDate($number)

 

$date = KE::Statistics::Date->julianDate($number);

A Date object is returned containing the date and time expressed by the Julian date number passed as an argument. The julianDate() method provides a mechanism for getting a Date object after some date numeric arithmetic has been performed.

weekDay()

 

$day = ("Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat")[$date->weekDay()];

Returns the numeric day of the week for the given Date object, where 0 = Sunday, 6 = Saturday.

The KE::Statistics::Statistics object is designed to provide easy insertions into the estatistics table. A Statistics object allows the columns within a record to be set and the record written. A check is made to see if the record already exists in the table and if so an update is performed rather than an insertion. This allows periodic tasks to be re-run to refresh data without duplicate records being created.

An estatistics record consists of four main components:

Keys

A hierarchy of up to ten Keys may be specified. The Keys are used to define the variables used to arrive at the statistical value. The first Key should contain a title defining what the statistical value is. For example:

Key1: Audit Statistics by Operation by Module by User (daily)
Key2: delete
Key3: elocations
Key4: bill

allows you to determine from Key1 what information is being stored. The next three Keys are the variables (Operation, Module, user) available. The above convention should be used so users can easily locate records within the estatistics table.

Date

Three date fields exist in estatistics: DateExact, DateFrom and DateTo. The DateExact field is filled if the statistical value represents a period of a day or less (that is daily or hourly), otherwise it is left empty. The DateFrom and DateTo fields should always be filled with the commencement and completion dates respectively.

Time

Three time fields exist in estatistics: TimeExact, TimeFrom and TimeTo. The TimeExact field is filled if the statistical value represents a single point of time in a day, otherwise it is left empty. If the period is a range of time in a day, the TimeFrom and TimeTo fields should be filled with the commencement and completion times respectively.

value

The value is the statistical datum associated with the set of defined Keys for the given date and / or time. For example, a value of 10 with the above Keys would indicate user bill has deleted 10 location records for the specified date/time period.

When completing an estastitics record, the appropriate fields should be filled based on the period the value covers.

new($session)

 

$stats = KE::Statistics::Statistics->new($session);

A new instance of a Statistics object tied to the supplied Session ($session) is created. You should not create instances of a Statistics object directly, rather $session->statistics() should be used as this ties the created object to the session.

setDate($date)

 

$stats->setDate($date);

Sets the DateExact column in estatistics to the value of the Date object supplied. The DateExact column should be filled if the statistic record is for a particular day (that is, daily) or a time range within a day (that is, hourly).

setDateFrom($date)

 

$stats->setDateFrom($date);

Sets the DateFrom column in estatistics to the value of the Date object supplied. The DateFrom column should always be filled. It contains the starting date for the statistics period.

setDateTo($date)

 

$stats->setDateTo($date);

Sets the DateTo column in estatistics to the value of the Date object supplied. The DateTo column should always be filled. It contains the finishing date for the statistics period.

setTime($date)

 

$stats->setTime($date);

Sets the TimeExact column in estatistics to the value of the Date object supplied. The TimeExact column should only be filled if the statistic record is for a single point in time, otherwise the column should be left empty.

setTimeFrom($date)

 

$stats->setTimeFrom($date);

Sets the TimeFrom column in estatistics to the value of the Date object supplied. The TimeFrom column contains the starting time for the statistics period. It should only be filled for statistic records for a single point in time, or a time range (that is hourly).

setTimeTo($date)

 

$stats->setTimeTo($date);

Sets the TimeTo column in estatistics to the value of the Date object supplied. The TimeTo column contains the completion time for the statistics period. It should only be filled for statistic records for a single point in time, or a time range (that is hourly).

languageSupported()

 

$value = $session->languageSupported();

Returns the value for the server environment Registry entry:

System|Setting|Language|Supported

languageDelimiter()

 

$value = $session->languageDelimiter();

Returns the value for the server environment language delimiter by first checking the environment variable EMULANGDELIM and then the value of the Registry entry:

System|Setting|Language|Delimiter

setTitle($period, %title)

 

$stats->setTitle($period, %title);

Multiple language alternative to set the setKey1($value) method.
Sets the Key1 column in estatistics to the title in the appropriate language(s).
The title parameter is a Perl hash with each entry having a numeric key of the number for the appropriate language (see the System|Setting|Language|Supported Registry entry) and a text value for the title in that language.

setKey1($value)

 

$stats->setKey1($value);

Sets the Key1 column in estatistics to the value supplied.

setKey2($value)

 

$stats->setKey2($value);

Sets the Key2 column in estatistics to the value supplied.

setKey3($value)

 

$stats->setKey3($value);

Sets the Key3 column in estatistics to the value supplied.

setKey4($value)

 

$stats->setKey4($value);

Sets the Key4 column in estatistics to the value supplied.

setKey5($value)

 

$stats->setKey5($value);

Sets the Key5 column in estatistics to the value supplied.

setKey6($value)

 

$stats->setKey6($value);

Sets the Key6 column in estatistics to the value supplied.

setKey7($value)

 

$stats->setKey7($value);

Sets the Key7 column in estatistics to the value supplied.

setKey8($value)

 

$stats->setKey8($value);

Sets the Key8 column in estatistics to the value supplied.

setKey9($value)

 

$stats->setKey9($value);

Sets the Key9 column in estatistics to the value supplied.

setKey10($value)

 

$stats->setKey10($value);

Sets the Key10 column in estatistics to the value supplied.

setValue($value)

 

$stats->setValue($value);

Sets the value column in estatistics to the value supplied. The statistical value is a floating point number.

write()

 

The write() method saves the data in the Statistics object to the estatistics table. If a record already exists with the same Keys, dates and times, the value is updated, otherwise a new record is created.