Version 1.2

ArsBaseClass is the basis of an object-oriented approach to ARSPerl.

For more information, see the comments at the beginning of

	ArsBaseClass.pm.

In a nutshell, to use:

	1. edit ArsBaseClass.pm
		- set $ARSUSER to something reasonable
		- set $ARSPASS to something reasonable
		- set $ARSSERVER to something reasonable

	(you may have to edit "ars-gen-subclass" and supply the correct perl path)

	2. run "ars-gen-subclass" for the schemata you're interested in
		- ./ars-gen-subclass <schema-name> > SchemaName.pm

	3. edit your newly generated subclasses as described in the comments
	   at the top of ArsBaseClass.pm.  In particular, in the CLASS_DATA
	   structure set "query => 1" for each field that you want retrieved
	   during a "normal" record-fetch (i.e., using the standard fetch
	   mechanism).  Set "query => 0" for all fields seldom referred to
	   or that are very large.  (see comments in "ArsBaseClass.pm".

	4. optionally add your own methods for producing multiple objects
	   from a single query (object factory).  See the 
	   "getRecordsByCustomerName()" class method in the example
	   subclass "ExampleSubClass.pm".


Probably the achilles heel of this approach is the risk of a subclass
becoming out-of-sync with its corresponding schema.  In order to offset
this risk, I include a method for checking the congruity of the
subclass, called "schemaChanged()", which will query ARS anew and
perform a comparison between the ARS fields and the CLASS_DATA
structure, and return any discrepencies.  To simplify keeping
subclass modules in sync with their corresponding ARS schematas,
I have added the ability to "ars-gen-subclass" to 'edit' an existing
subclass module, which really means the subclass module is scanned
beforehand for customizations and a new module is produced which
contains the previously found customizations.

The advantage to my approach is the utter simplicity of the interface:

	$obj = SchemaName->new;
	$obj->field_name("new value");
	$obj->write;

and you have created a new record in ARS.

** Lack of transactions **

There is no explicit mechanism for arbitrating access to ARS.  If
you want, you can fetch a record, wait a week, process according to
those values you retrieved a week ago, and write new values back to
ARS.  This may perhaps overwrite newer, more valid data for that
record.  Keep in mind that the write() method only writes changed data
to ARS, thus you need worry only about fields that you have modified.

Normally, you needn't worry about such things because most scripts
fetch data, perform some operations on the data which last a fraction
of a second, and then write the changes to ARS.

If you are concerned about such matters, I have provided a method
called recordModified(), which you can call before you call write().
If someone else has written the record between the time that you
fetched it and when you called recordModified(), it will return a
Perl true.  It's up to you to handle such cases.  You can re-fetch
the record using reload() and then go through your processing (and
subsequent call to recordModified()), for example.

Of course, there is a chance that the record will be modified between
when you call recordModified() and write().  To the best of my knowledge
there is no mechanism in ARS (transactions, for example) to avoid this
risk.

** Field types **

"ars-gen-subclass" ignores fields of type "control", "trim", "page"
and "table".  From my understanding of ARS, this is appropriate.

ArsBaseClass handles fields of type "enum", "diary" and "attach" specially.

	- the string associated with enumerated values is transparently
	  converted from and to the enumerated value
	- see comments in ArsBaseClass.pm for diary field handling

All other fields are handled normally, i.e., the field-values are
passed one-to-one to and from ARS.  For example fields of type "time"
get no special handling; the units are epoch-seconds (standard UNIX
time format).

There may be other fields that need special handling.  
These will probably require additional work to get working.

Please let me know if:

	- you find this useful.
	- you have ideas for improving it.


March, 2004
Rob Urban (urban@tru64.org>
Munich