                        Days Open Sample Program

This directory contains a sample program that illustrates how to use the API of
the AR System to add functionality that is not built into the AR System
product.

NOTE:  This file contains some introductory comments and notes about the
       program.  There are additional comments in the code itself that explain
       the approach taken and provide hints about other strategies that might
       be used to adapt the program to other uses.


The Problem
-----------

To provide some context for this example, we will provide a brief description
of an area where the sample program might be used:

We need to be able to generate reports that show the number of days a problem
has been open.  In addition, we want to be able to generate statistics on the
average open time (both for entries still open and for ones that have been
closed).  And, we want to be able to let users easily query for entries that
have been opened for a specified length of time.

At first glance, these operations seem easy.  That is until you consider the
requirement to count only WORKING days.  This means that all weekends are
excluded from the count AND any company holidays need to be removed.  This is
important as a problem opened on Friday and closed on Monday should only count
as being opened for 1 day not 3.

This new field makes querying easy for all the users as any allowance for
weekends and holidays has already been done.  Also, it provides a field that
can be manually updated by an Administrator if there is some reason that the
number of days open for a specific problem needs to be adjusted to be different
from the difference computed automatically (for example, there was an agreement
on a specific problem that the customer's holidays did not count and there was
a customer holiday during the time the problem was being worked on that was
not a holiday for your company).

So, now that we have this value, what good is it to us.  We may need this data
to determine whether we are complying with a contract (problems will be fixed
within 5 working days).  Or, we may use it to determine when we are getting
close to a requirement (check for anything open for 4 days because they will
be past contract requirements tomorrow).  Or, we may simply want to report the
number of days or the average number of days a problem or group of problems
was open.

With this introduction, lets take a quick look at the program:


The daysOpen Program
--------------------

Specifically, this program is used to calculate the number of days a problem
has been open.  It will exclude weekends and holidays (read from a holiday
file) from the calculation.

The command options for the program are all positional parameters on the
command line.  The code can easily be rewritten to hard-code the values, or
to make them keyword parameters, or to load them from a configuration file.

The program can be used to update a single entry or to update all entries
that have been closed less than 7 days or are not closed yet (to keep a
running tally of the number of days so far).

The target schema for this program is any schema as long as there are three
fields as follows:

     Create-date    The date the problem was created (generally the core field
                       create-date -- id = 3)
     Closed-date    The date the problem was resolved.  This must be a date/time
                       type field
     Days-Opened    The field containing the result of the days opened
                       calculation.  This must be an integer type field


You pass the program the name of the schema and server to access, the entryId
of a specific field to update (all fields if blank) and the ids of the
three fields noted above.  Optionally, you can pass a holiday file.  The format
of the command is as follows:

   daysOpen  schema  server  entryId  create-date-id  closed-date-id
             days-opened-id  [holiday-filename]

   where
      schema          The name of the schema whose records to update
      server          The server the schema is located on
      entryId         The id of a specific entry to update.  Enter a value of ""
                      to specify an empty string to update all.
      create-date-id  The field id of the create-date field
      closed-date-id  The field id of the closed-date field
      days-opened-id  The field id of the days opened field
      holiday-filename The filename of the holiday file.  If not specified,
                       the name defaults to holiday.txt


The login to the AR System is hard coded to the user Demo with no password.
You can change this hard-coded value or make it a parameter that is passed to
the program for flexibility.


Disclaimer
----------

The goal for this program is to show a real-world, useful example of a program
that uses the AR System API.  You can take this example as a pattern and alter
it in whatever way you need to adapt the functionality to your environment.

The program is provided as an example showing how to use the API, it is not
a supported feature of the product.
