ARSObject

 view release on metacpan or  search on metacpan

lib/ARSObject.pod  view on Meta::CPAN

				}
		);
  print $s->dsdump($hac);


=head1 DESCRIPTION

This module is intended for capable scripts above L<ARS|ARS> module
(L<../../ARSPerl/index.html>).

It caches metadata alike L<Remedy::ARSTools|Remedy/ARSTools>,
but uses L<Data::Dumper|Data/Dumper> or L<Storable|Storable> module.
And metadata model is directly given from ARS::ars_GetFieldTable()/ARS::ars_GetField(),
unlike L<ARSOOForm|ARSOOForm> and L<Remedy::ARSTools|Remedy/ARSTools>.
And additional description level (C<-metadn>/C<-metaid>) added to unify field names
and extend conversion capabilities of field values.

Field names and values are translated (C<-strFields>/C<strIn>/C<strOut>)
as possible.

C<query>() method supports iterator sub{} and uses ARS::ars_GetListEntry(), 
ARS::ars_GetListEntryWithFields(), ARS::ars_GetEntry() calls
as appropriate with parameters given.

C<entry>(), C<entryIns>(), C<entryUpd>(), C<entryDel>() methods 
are usual to manipulate records.

C<entryNew>() method may be used to form new record hash with default values for C<entryIns>().

C<entryDif>() method may be used to minimise data for C<entryUpd>().

C<AUTOLOAD>() method is to call 'ARS::ars_XXX' functions as methods.

Special processing added for 'HPD:Help Desk' ITSM Suite form.

C<Variable files> may be used to cache any data.

Misc C<Utility Methods> intended for strings, dates, data structures.

C<Utility Objects> added to simplify and unify access to 
L<DBI|DBI>, L<CGI|CGI>, L<Net::SMTP|Net/SMTP> modules.



=back


=head1 CLASSIFICATION

=over


=item Creation and Configuration

C<new>, C<set>, C<Slots>


=item Error Processing and Echo

C<-die>, C<-warn>, C<-echo>, C<-cpcon>/C<cpcon>;
C<ars_errstr>, C<dbierrstr>


=item Connection

C<connect>(C<-srv> => server, C<-usr> => name, C<-pswd> => password, C<-lang> => language);
C<-ctrl>

C<dbiconnect>(C<-dbiconnect>); C<-dbi>


=item Metadata

C<connect>; C<arsmeta>, C<arsmetamin>; C<schema>,...; C<lsflds>;
C<-schema>, C<-meta>/C<-meta-min>/C<-meta-sql>, C<-metax>, C<-metadn>, C<-metaid>, C<-schgen>, C<-schfdo>, C<-strFields>;
C<Variable files>



=item Variable files

C<-vfbase>, C<-storable>;
C<vfname>, C<vfload>, C<vfstore>, C<vfclear>, C<vfdata>, C<vfhash>, C<vfdistinct>


=item ARS methods

C<connect>, C<query>, C<entry>, C<entryNew>, C<entryIns>, C<entryUpd>, C<entryDel>, C<entryBLOB>, C<AUTOLOAD>;

C<-strFields>, C<strIn>, C<strOut>;

C<arsquot>;

C<-maxRetrieve>



=item Utility Methods

C<strquot>, C<strquot2>, C<arsquot>;

C<cptran>, C<cpcon>;

C<strtime>, C<timestr>, C<timeadd>;

C<dsquot>, C<dsquot1>;

C<dsdump>, C<dsparse>, C<dscmp>, C<dsmerge>, C<dsunique>;

C<fopen>, C<fload>, C<fstore>, C<fdirls>;

C<soon>



=item Utility Objects

C<dbi>, C<-dbi>, C<dbiconnect>, C<-dbiconnect>;
C<dbiquery>, C<dbido>; C<dbierrstr>

C<cgi>, C<-cgi>, C<cgiconnect>;
C<cgipar>, C<cgiesc>, C<cgitfrm>, C<cgitext>, C<cgistring>, C<cgiselect>, C<cgiddlb>

C<smtp>, C<-smtp>, C<smtpconnect>, C<-smtphost>; C<smtpsend>



=item SQL Data Store Methods

C<arsmetasql>, C<sqlname>, C<dbidsmetasync>, C<dbidsrpl>, C<dbidsquery>;

C<-meta-sql>; C<-sqlschema>;

C<-sqlname>, C<-sqlntbl>, C<-sqlncol>, C<-sqlninc>



=item CGI Form Presenter

C<-fpl> => [-formdb=>'...',-record=>'...', {action field},.. {view/edit field},.., {button field},..}]

C<-fphc> => {'cgi field name' => {field definition},..}

C<-fphd> => {'db field name' => {field definition},..}

C<cfprun>, C<cfpaction>, C<cfpv>, C<cfpvv>, C<cfpvl>, C<cfpvp>

* action field: C<-name>.., C<-preact> || C<-action>, C<-widget>=>undef, C<-used>=>condition sub{}

* key field: C<-name>.., C<-key>=>1, C<-readonly>=>1

* text: C<-widget>=>'html'

* edit field: C<-name>..,

* computed: C<-name>.., C<-computed>=>sub{}

* readonly: C<-name>.., C<-readonly>=>1

* do not store: C<-name>.., C<-entryIns>=>0, C<-entryUpd>=>0, C<-vfstore>=>0

* list&refresh: C<-name>.., C<-onchange>=>1, C<-labels>, C<-values>

* optional button field: C<-name>.., C<-action>=>1, C<-used>=>condition



=item CGI Form Presenter - Field Definitions

(for each field inside C<CGI Form Presenter - Fields>)

C<-name>, C<-namecgi>, C<-namedb>, C<-metadb> => 'field name'

C<-namelbl>, C<-namecmt> => 'text for user'

C<-namehtml> => sub{} -> 'html for user'

C<-formdb> => 'name', C<-record> => 'name' || 'nameRowNumber'

C<-used>, C<-unused> => boolean || 'field name' || ['field',...] || condition sub{}

C<-entryIns>, C<-entryUpd>, C<-vfstore> => !exists ||false

C<-preact> || C<-action> => 'action name' || action sub{} -> success

C<-vfname> => 'name', C<-vfrenew>, C<-vfedit>, C<-vftran> => boolean

C<-key> => boolean

C<-master> => 'field name'

C<-computed>, C<-value> => value || ['field from'] || sub{} -> value

C<-undef> => value

C<-values> => [value,..] || sub{}, C<-labels> => {value => label,..} || sub{}; C<-lbtran>, C<-lbadd> => boolean

C<-reset> => 'field name' || ['field',...] || condition sub{}

C<-change> => {set field values}

C<-error>, C<-warn> => sub{} -> 'text'

C<-widget> => {definitions for cgi field in the C<Utility Objects>} || html || sub{}->html
Field definitions may be used also:
C<-action> => 1;
C<-labels>, C<-values>;
C<-disabled>, C<-readonly>, C<-hidden>, C<-onchange> => boolean.

C<-widget0> => html above C<-widget> || sub{} -> html

C<-widget1> => html below C<-widget> || sub{} -> html


=back


=head1 SLOTS

=over

=item Slots


=item -action

	=> not exists 
	|| sub{}({self}, action, '-action'
		, {key field}, $_= key value, key pv
		, {field db name=>value,..}, prev return)
		-> success || {field db name => value}
	|| 'entryIns' || 'entryUpd' || 'entryDel' || 'entrySave'
	|| 1

(C<CGI Form Presenter - Field Definitions>)
Action to execute after the form performance,
should be at the top of the form, before C<-key> fields.
May be several actions with the same C<-namecgi>.
1 - action button, it should to be at the bottom of the form.
For 'entrySave' action, 'entryUpd' is used when non-empty key value,
'entryDel' otherwise with non-empty previous key value.

See also C<-preact>.


=item -cgi

	=> undef || CGI object

(C<Utility Objects>)
L<CGI|CGI> utility object.
See also C<cgi> method.



=item -change

	=> not exists
	|| {field name => value || sub{}({self}, {field}, $_ =value),..}
	|| {value=>{field name => value,..},..}

(C<CGI Form Presenter - Field Definitions>)
Change field values when this field changed.
This may be defined also as C<-values> or C<-labels>.



=item -computed

	=> not exists || value || [field name] || sub{}({self},{field}) -> value

(C<CGI Form Presenter - Field Definitions>)
Computed field value evaluator.
See also C<-value>.


=item -cpcon

	=> undef || sub{}(self, arg,...) -> translated

(C<Error Processing and Echo>)
Translation sub{} for error messages and C<-echo> printout.
I.e. sub{$_[0]->C<cptran>('ansi'=>'oem',@_[1..$#_])}


=item -ctrl

	=> undef || ARS control struct

(C<Connection>)
ARS control struct from ARS::ars_Login()



=item -dbi

	=> undef || DBI object

=item -dbiconnect

	=> undef || connection string || [connect args]

(C<Utility Objects>)
L<DBI|DBI> utility object and connect specification to create it.
See also C<dbi> and C<dbiconnect> methods.



=item -die

	=> undef || sub{}

	=> set(-die => 'Carp' || 'CGI::Carp' || 'CGI::Carp qw(fatalsToBrowser warningsToBrowser)' || 'CGI::Die')

(C<Error Processing and Echo>)
Error die sub{}.
The most C<Methods> dies when error.
Call C<set>(C<-die> => 'Carp') to use L<Carp|Carp> module.
Call C<set>(C<-die> => 'CGI::Carp fatalsToBrowser') to use L<CGI::Carp|CGI/Carp> module.

See also C<-diemsg>, C<-warn>, C<-cpcon>


=item -diemsg

	=> undef || sub{}(string)

Message for C<-die>, alike L<CGI::Carp|CGI/Carp>::set_message()



=item -echo

	=> 0 | 1

(C<Error Processing and Echo>)
Echo printout switch.
Temporarilly may be used as an argument for specific methods.
alike C<query> and C<entryIns>.



=item -entryNo

	=> entryIns()

(C<ARS methods>)
The logical number of the entry inserted by C<entryIns>().



=item -error

	=> not exists
	|| sub{}({self}, {field}, $_ =field value, previous value) -> 'error text'
	|| 'error text for empty field'

(C<CGI Form Presenter - Field Definitions>)
Field value error evaluator
See also C<-warn>.



=item -fpl

	=> [-formdb=>'...',-record=>'...'
	, {action field},.. {view/edit field},.., {button field},..}]

=item -fphc

	=> {'cgi field name' => {field definition},..}

=item -fphd

	=> {'db field name' => {field definition},..}

(C<CGI Form Presenter>)
Definitions of fields:
list of field in order to be evaluated,
field definitions by cgi names,
field definitions by ARS names.



=item -formdb

	=> 'db form name'

(C<CGI Form Presenter - Field Definitions>)
db form name, may be defined as a 
special C<-fpl> entry before field definitions.


=item -key

	=> => not exists || boolean

(C<CGI Form Presenter - Field Definitions>)
Key database field?


=item -labels

	=> not exists || {value=>label,..} || {value=>{{-label=>label, field=>value,..},..}
	|| sub{}({self},{field},$_=value) -> {value=>label,..}

(C<CGI Form Presenter - Field Definitions>)
Labels for the drop-down list box field.
If no C<-values>, this will be generated automatically.
Special {-name=>name, field=>value,..} form is to define C<-change>.
See also C<-values>.



=item -lbtran

=item -lbadd

	=> not exists || true || false (default)

lib/ARSObject.pod  view on Meta::CPAN

=item -vfbase

	=> 'script file path name-' || 'base file path name' || 'directory path/'

(C<Variable files>)
Variable files base path name, used by C<vfstore>(), C<vfload>(), C<vfname>().
Default is formed from script file name without extensions and with '-' added.


=item -vfname 

	=> not exists || '-slotName'

=item -vfrenew

	=> not exists || boolean

=item -vfedit

	=> not exists || boolean

=item -vftran

	=> not exists || boolean

(C<CGI Form Presenter - Field Definitions>)
Short name of the C<Variable File>
to read record from with C<-action>=>'vfentry' or C<-action>=>'vfhash';
or to renew or update after C<-action>=>'entryIns' || 'entryUpd' || 'entryDel'
May be used with C<-action> or C<-key> field.

C<-vfrenew> - renew variable file after 'entryIns' || 'entryUpd' || 'entryDel'

C<-vfedit> - update variable file after 'entryIns' || 'entryUpd' || 'entryDel'

C<-vftran> - translate value with C<-labels> for variable file


=item -warn

	=> undef

(C<Error Processing and Echo>)
Error warn sub{}.
Call C<set>(C<-die> => 'Carp') to use L<Carp|Carp> module,
or C<set>(C<-die> => 'CGI::Carp') to use L<CGI::Carp|CGI/Carp> module.
See also C<-cpcon>.


=item -warn

	=> not exists
	|| sub{}({self}, {field}, $_ =field value, previous value) -> 'warning text'
	|| 'warning text for empty field'

(C<CGI Form Presenter - Field Definitions>)
Field value warning evaluator.
See also C<-error>.



=item -warnmsg

	=> undef || sub{}(string)

Message for C<-warn>, alike C<-diemsg>.



=item -widget

	=> not exists || undef == skip || 'html'
	|| sub{}({self}, {field}, value, previous value) -> html
	|| {option=>value,..}

(C<CGI Form Presenter - Field Definitions>)
Definition of html field to display (C<Utility Objects>):

	not exists - use default widget,
	undef - field not included in form,
	'html' - html to display,
		hidden field with previous value added if '-namecgi'
	sub{} -> html to display,...
	{option=>value,..} - parameters for 'cgi...' or 'CGI' field

Field definitions may be used also to generate default widget:
C<-action> => 1;
C<-labels>, C<-values>;
C<-disabled>, C<-readonly>, C<-hidden>, C<-onchange> => boolean.



=item -widget0

=item -widget1

	=> not exists || 'html'
	|| sub{}({self}, {field}, value, previous value) -> html

(C<CGI Form Presenter - Field Definitions>)
html to display above and below C<-widget>



=back



=head1 METHODS

=over

=item Methods



=item ars_errstr () -> $ARS::ars_errstr

(C<Error Processing and Echo>)
Last ARS error.


=item arsmeta (-param => value,...)

(C<Metadata>)
Load/refresh ARS metadata (C<vfload>/C<vfstore>(C<-meta>), C<-metadn>, C<-metaid>).
Called from C<connect>.
May be called without C<connect> if metadata file exists.
See also C<arsmetamin>.


=item arsmetamin (-param => value,...)

(C<Metadata>)
Refresh minimal ARS metadata set (C<vfstore>(C<-meta-min>)) after C<connect>/C<arsmeta> call.
Load minimal ARS metadata instead of or after C<connect>/C<arsmeta> call.
Loading of minimal metadata set is faster then loading all metadata with C<arsmeta>.
Minimal metadata set includes explicit 'enumLimits' and 'time' fields.

Synopsis: Refreshing C<-meta-min>:

	$s->set(-schgen =>3);
	$s->connect();
	$s->arsmetamin();


=item arsmetasql (-param => value,...)

(C<Metadata>, C<SQL Data Store Methods>)

Load SQL Data Store metadata or refresh this from ARS metadata after C<connect>/C<arsmeta> call.
The SQL Data Store is intended for data replicated from ARS using C<dbidsrpl>() calls.
Database table and column names are escaped ARS form and field names.
Metadata is stored in C<-meta-sql> variable file.

Synopsis: Refreshing C<-meta-sql>:

	$s->set(-schgen =>3);
	$s->connect();
	$s->dbi();
	$s->arsmetasql();
	$s->dbidsmetasync();

See also C<sqlname>(), C<dbidsmetasync>(), C<dbidsrpl>(), C<dbidsquery>()


=item arsquot (string) -> escaped and quoted for ARS

Quote and escape string for ARS.
See also C<strquot>/C<strquot2>



=item AUTOLOAD ()

(C<ARS methods>)
Use object->arsXXX() syntax for ARS:ars_XXX(ctrl,...) calls.



=item cfpaction ({action} || 'action', '-preact'||'-action', {key field}) -> success

(C<CGI Form Presenter>)
Action evaluator, called from C<cfprun>(),
may be called from C<-action> or C<-preact> sub{}.


=item cfpl ('field name' || {field definition}) -> [possible field values]

(C<CGI Form Presenter>)
List of C<-values> of the field, may be used in sub{}s executed by C<cfprun>.


=item cfpp ('field name' || {field definition}) -> previous field value

(C<CGI Form Presenter>)
Previous value of the field, may be used in sub{}s executed by C<cfprun>.


=item cfprun (? msg sub{}(self, 'label', 'comment'), ? form row sub{}(self, {field}, 'html'), ? 'form start html', ? 'form end html') -> success

(C<CGI Form Presenter>)
Evaluate C<-fpl> and present html form with actions.
The order of the fields is important, it is preferred to refer from
the field definition to previous fields, not to subsequent.


=item cfpv ('field name' || {field definition}) -> current field value

(C<CGI Form Presenter>)
Current value of the field, may be used in sub{}s executed by C<cfprun>.


=item cfpvv ('field name' || {field definition}) -> current or default field value

(C<CGI Form Presenter>)
Current or default value of the field, may be used in sub{}s executed by C<cfprun>.



=item C<cgi> () -> CGI object

=item C<cgi> (CGI->new args) -> CGI object

(C<Utility Objects>)
Access to L<CGI|CGI> object in C<-cgi>.
It will be automatically created with C<cgiconnect>() if not exists.



=item cgiconnect (CGI args) -> CGI object

(C<Utility Objects>)
Connect to L<CGI|CGI>.



=item cgiddlb (-name=>name, ?-title=>comment, ?-values=>[values], ?-labels=>{value=>display,..}, ?-default=>value, ?-override=>bool,...) -> drop-down list box HTML

(C<Utility Objects>)
Generate drop-down list box HTML using L<CGI|CGI> widgets.
This is alike C<cgiselect>, but more complex.

 -strict=> - disable text editing, allow only to choose value from list



=item cgiesc (string) -> escaped string

(C<Utility Objects>)
Escape string to HTML using L<CGI|CGI>->escapeHTML(@_)



=item cgitfrm (?-table=>{table attrs}, ?-tr=>{tr attrs}, ?-td=>{...}, ?-th=>{...}, [cell value,...],...) -> HTML

(C<Utility Objects>)
Generate simple HTML form in table layout using L<CGI|CGI>->start_form(),
L<CGI|CGI>->table(), L<CGI|CGI>->end_form().
'th' tag will be used for simple strings as usual labels, 'td' tag - for strings started with HTML tags.



=item cgipar() -> parameters

=item cgipar(name) -> value

=item cgipar(name, value)

(C<Utility Objects>)
Get or set L<CGI|CGI> parameter - L<CGI|CGI>->param(@_)



=item cgiselect (-name=>name, ?-title=>comment, ?-values=>[values], ?-labels=>{value=>display,..}, ?-default=>value, ?-override=>bool,...) -> selection HTML field

(C<Utility Objects>)
Generate selection field HTML using L<CGI|CGI>->popup_menu(@_)

 -onchange=>1 - reload form when value changed



=item cgistring (-name=>name, ?-title=>comment, ?-default=>value, ?-override=>bool, ?-size=>number, ?-maxlength=>number,...) -> text HTML field

(C<Utility Objects>)
Generate text field HTML using L<CGI|CGI>->textfield(@_)



=item cgitext(-name=>name, ?-title=>comment, ?-default=>value, ?-override=>bool, ?-rows=>number, ?-columns=>number,...) -> textarea HTML field

(C<Utility Objects>)
Generate HTML textarea field using L<CGI|CGI>->textarea(@_)



=item connect (-param => value,...) -> connected


(C<Connection>)
Connect to ARS server with ARS::ars_Login()
or verify existed connection with ARS::ars_VerifyUser().
Load metadata (C<vfload>/C<vfstore>(C<-meta>), C<-metadn>, C<-metaid>).



=item cpcon (string,...) -> translated string,...

(C<Error Processing and Echo>)
Translate strings to console codepage using C<-cptran>.



=item cptran (fromCP, toCP, string,...) -> translated string,...

(C<Utility Methods>)
Translate strings between codepages using L<Encode|Encode>.



=item dbi() -> DBI object

(C<Utility Objects>)
Access to L<DBI|DBI> object. C<dbiconnect> will be used if empty C<-dbi>.


=item dbiconnect (?-dbiconnect=> connection string || [DBI->connect args]) -> DBI object

(C<Utility Objects>)
Connect to L<DBI|DBI> database using C<-dbiconnect>.


=item dbido (dbi do args, , ?-echo=>1) -> dbi do result


(C<Utility Objects>)
Execute L<DBI|DBI> 'do' using C<dbi>.
Use -echo=>1 to output command to STDOUT.



=item dbidsmetasync (-echo => 0 || 1)

(C<Metadata>, C<SQL Data Store Methods>)

Sync SQL Data Store schema with metadata generated by C<arsmetasql>().
Uses C<dbi>(), C<-meta-sql>, C<-sqlschema>.
Calls C<dbido>('CREATE TABLE...') and C<dbido>('ALTER TABLE...').

lib/ARSObject.pod  view on Meta::CPAN

-query => undef || ARS query string

-filter => undef || filter sub{}(self, {args}, {-meta-sql}->{tableName}, {ARS record}, {Data Store record}) -> allow

-lim_rf => undef || max number of records read from ARS, C<query>(-limit).
The number of the records fetched really may be incremented by counting timestamps duplicated.
Without timestamps, additional queries will be invoked when '-lim_rf' records fetched.

-lim_or => undef || max number of 'OR keyField=keyValue' pairs

-pk => undef || primary key ARS field name, default is obtained from C<-meta-sql>

-timestamp => undef || 0 || 'Modified Date' timestamp ARS field name, default is obtained from C<-meta-sql>

-ckpush => undef || 1 || 0 - insert, update, delete ARS records according to '_arsobject_insert', '_arsobject_update', '_arsobject_delete' column values.

-ckdel => undef || 0 || 1 - check records deleted from ARS and replicate deletions to the Data Store,
this is expensive and slow, so default if off.

-ckupd => undef || 1 || 0 - check and replicate updates from ARS to the Data Store,
based on timestamps of records if availeble

-unused => undef || SQL where clause part to delete unused records from Data Store table. "ARS field name"s and "ARS form name"s may be used.

-sleep => undef || seconds to L<perlfunc::sleep|perlfunc> between calls to ARS.



=item dbidsquery (-param => value) -> ({fieldName => fieldValue,...},...)

(C<SQL Data Store Methods>)

Query data from SQL Data Store.
Uses C<dbi>(), C<-meta-sql>, C<-sqlschema>.
Any C<dbi>() method may be used for SQL Data Store, 
but C<dbidsquery> understands "ARS form name"s and "ARS field name"s
in addition to "sql table name"s and "sql column name"s.
Records are returned as hash refs with ARS field names available,
otherwise SQL column names.
Parameters:

-echo => undef || 0 || 1

-form => ARS form name

-fields => undef || '*' || 'SQL SELECT clause' || [fieldName ||fieldId ||colName,...].
Empty value requests all fields, '*' - all fields or columns.

-query => undef || SQL WHERE clause

-filter => undef || filter sub{}(self, {fieldName => fieldValue,...}) -> allow

-order => [fieldName||fieldId => 1||2,... colName||colNumber => 'asc'||'desc',...] || 'SQL ORDER BY clause'

-undefs => undef || 1 || 0 - include undefined values to records returned

"ARS form name", "ARS field name", "ARS form name"."ARS field name" may be used
in '-fields' and '-query'.


=item dbierrstr () -> dbi->errstr

(C<Error Processing and Echo>)
Last L<DBI|DBI> error, <dbi>->errstr



=item dbiquery (dbi query args, ?-echo=>1) -> dbi cursor object

(C<Utility Objects>)
Query L<DBI|DBI> database using C<dbi>, 'prepare', 'execute'.
Use -echo=>1 to output command to STDOUT.



=item dscmp (data1, data2) -> cmp

(C<Utility Methods>)
Compare two data structures alike L<cmp|perlop>.



=item dsdump (data structure) -> dump string

(C<Utility Methods>)
Stringify any data structure using L<Data::Dumper|Data/Dumper>.
This string may be loaded back with C<dsparse>().



=item dsmerge (array ref,...) -> [merged array]

=item dsmerge (hash ref,...) -> {merged hash}

(C<Utility Methods>)
Sequentally assign elements of data structures given to result data structure.



=item dsparse (perl string) -> data structure

(C<Utility Methods>)
Convert C<dsdump>ed string to data structure.



=item dsquot (data structure) -> stringified

=item dsquot1 (data structure) -> stringified, defined elements only

(C<Utility Methods>)
Quote (stringify) any data structure to human readable form.



=item dsunique (item,...) -> (unique items)

(C<Utility Methods>)
Find unique items in the list given.



=item entry (-form=>name, -id=>entryId,...) -> {entry}