ARSObject

 view release on metacpan or  search on metacpan

lib/ARSObject.pod  view on Meta::CPAN

=head1 NAME

ARSObject - high level interface above ARS module

=head1 SYNOPSIS

  use ARSObject;
  my $s =ARSObject->new(-srv =>'ip address',-usr => 'username',-pswd =>'******'
		,-storable => 0
		,-schema =>['BMC.CORE:BMC_ComputerSystem','BMC.CORE:BMC_ApplicationSystem']
		,-metaid =>{
		'1' => 'RequestId'
		,'6' => 'ModifiedDate'
		,'179' => 'InstanceId'
		,'1000000001' => {fieldName=>'Company'}
		,'200000020' => 'Name'
		});
  $s->connect();
  my $hac ={};
  $s->query(-from=>'BMC.CORE:BMC_ComputerSystem'
			,-where=>"('DatasetId'=\"BMC.ASSET\")"
				." AND ('Company'=\"$company\")"
			,-fields=>['Name', 'ModifiedDate', 'RequestId', 'InstanceId', 'ShortDescription', 'InstanceId', 'DatasetId', 'TokenId', 'OwnerName', 'OwnerContact', 'TagNumber', 'Description', 'HostName', 'Domain', 'Workgroup', 'CMDBRowLevelSecurity', 'Company', ...
			,-order=>['Name']
			,-for=>sub{$hac->{$_[3]->{Name}} =$_[3];
				}
		);
  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>;

lib/ARSObject.pod  view on Meta::CPAN

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)

(C<CGI Form Presenter - Field Definitions>)
Translate list box value with C<-labels> if needed?
Add field value to C<-values> if not listed?



=item -lang

	=> '' || 'ARS language' || 'en_US' || 'ru_RU'...

(C<Connection>)
ARS language to use for session, i.e. 'en_US'



=item -master

	=> not exists || 'master field name'

(C<CGI Form Presenter - Field Definitions>)
Name of the field containg value for this field.



=item -metadb

	=> not exists || 'ARS field name'

(C<CGI Form Presenter - Field Definitions>)
ARS field name to be used for field metadata:
C<-name>, C<-namelbl>, C<-labels>, C<-value>, etc.



=item -name

	=> not exists || 'common field name'

=item -namecgi

	=> not exists || 'cgi field name'

=item -namedb

	=> not exists || 'ARS field name'

=item -namelbl

	=> not exists || 'field label'

=item -namecmt

	=> not exists || 'comment text'

=item -namehtml

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

(C<CGI Form Presenter - Field Definitions>)

lib/ARSObject.pod  view on Meta::CPAN

	=> 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();

lib/ARSObject.pod  view on Meta::CPAN

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...').



=item dbidsrpl (-param => value)

(C<SQL Data Store Methods>)

Replicate ARS data to the SQL Data Store.
Uses C<dbi>(), C<-meta-sql>, C<-sqlschema>.
Parameters:

-echo => undef || 0 || 1

-form => ARS form name

-fields => undef || '*' || fields to replicate, alike C<query>(-fields)

-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>)

lib/ARSObject.pod  view on Meta::CPAN

Parameters:

-form | -schema | -from | -into  => schema or form name

-id=>entryId

-echo=>1 # output command to STDOUT

-field=>fieldId | fieldName

-file=>path, -set=>boolean # when using file for BLOB field data

-set=>data # when updating BLOB field from scalar data



=item entryDel (-form=>form, -id=>entryId, ?-echo=>1) -> id

(C<ARS methods>)
Delete record into ARS using ARS::ars_DeleteEntry().
Parameters:

-form | -into | -schema => schema or form name

-id=>entryId

-echo=>1 # output command to STDOUT



=item entryDif ({old field => value,...}, {new field => value,...}, ?exclude empty) -> {values to update} | undef

(C<ARS methods>)
Distinguish the difference between two hashes of field => value.
Returns undef when no difference.



=item entryIns (-form=>form, ?-echo=>1, field => value,...) -> id | self

(C<ARS methods>)
Insert new record into ARS using ARS::ars_CreateEntry().
Field names are translated to ids using C<-metadn>/C<-meta>.
Field values are translated with C<strIn> when C<-strFields>.

Specially for 'HPD:Help Desk': 'Incident Number' value will be generated if it is 1.

Parameters:

-form | -into | -schema => schema or form name

-echo=>1 # output command to STDOUT

field === internalId | fieldName



=item entryNew (-form=>form, field=>value,...) -> {field=>value,...}

(C<ARS methods>)
Form field => value hash for a new ARS record using values given and default values in C<-meta>.
This may be not needed, C<entryIns> may be sufficient.
Field names are translated to ids using C<-metadn>/C<-meta>.
Field values are translated with C<strOut> when C<-strFields>.

Specially for 'HPD:Help Desk': 'Incident Number' value will be generated if it is 1.




=item entryUpd (-form=>form, -id=>entryId, ?-echo=>1, field=>value,...) -> id

(C<ARS methods>)
Update record into ARS using ARS::ars_SetEntry().
Field names are translated to ids using C<-metadn>/C<-meta>.
Field values are translated with C<strIn> when C<-strFields>.
Parameters:

-form | -into | -schema => schema or form name

-id=>entryId

-echo=>1 # output command to STDOUT

field === internalId | fieldName



=item fdirls (?-opt, path, ? filter sub{}(self, path, $_ =entry)) -> (entry,...)

=item fdirls (..., []) -> [entry,...]

(C<Utility Methods>)
List directory contents.



=item fload (?-opt, filename) -> content

(C<Utility Methods>)
Load data from file.
Options: '-b' - L<binmode|perlfunc>.
See also C<fstore>.



=item fopen (?-opt, filename) -> IO::File object

(C<Utility Methods>)
Open file with L<IO::File|IO/File> object.
Options: '-b' - L<binmode|perlfunc>.
See also C<fload>, C<fstore>.



=item fstore (?-opt, filename, string,...) -> success

(C<Utility Methods>)
Store strings to file.
Options: '-b' - L<binmode|perlfunc>.
Filename may be started with '>>' to add data to file.