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

lib/ARSObject.pod  view on Meta::CPAN

=item -sqlname

	=> undef || sub{}(self, ARS name) -> SQL name

(C<SQL Data Store Methods>)
sub{} to escape ARS name to the SQL name, 
may be used instead of C<-sqlntbl> and C<-sqlncol>.
See also C<-sqlninc>.
See 'sub sqlnesc' in the source code as an example.


=item -sqlncol

	=> undef || sub{}(self, ARS field name) -> SQL col name

(C<SQL Data Store Methods>)
sub{} to escape ARS field name to the SQL column name, see also C<-sqlntbl>, C<-sqlninc>.
See 'sub sqlnesc' in the source code as an example.


=item -sqlninc

	=> undef || sub{}(self, SQL name) -> SQL name incremented

(C<SQL Data Store Methods>)
sub{} to increment SQL name, used after C<-sqlname>/C<-sqlntbl>/C<-sqlncol>
when the same SQL name already exists.
See 'sub sqlninc' in the source code as an example.


=item -sqlntbl

	=> undef || sub{}(self, ARS form name) -> SQL table name


(C<SQL Data Store Methods>)
sub{} to escape ARS form name to the SQL table name, see also C<-sqlncol>, C<-sqlninc>.
See 'sub sqlnesc' in the source code as an example.


=item -sqlschema

	=> undef || SQL schema name

(C<SQL Data Store Methods>)
SQL schema name for C<dbidsmetasync>(), C<dbidsrpl>(), C<dbidsquery>().


=item -storable

=item -meta-storable

=item <-vfname>-storable

	=> 1 || 0

(C<Variable files>)
Use L<Storable|Storable> module for variable files, metadata file, or another particular file?
Or L<Data::Dumper|Data/Dumper> will be used.
See also C<vstore>().



=item -srv

	=> undef || 'ARS server name'

(C<Connection>)
ARS server name to connect


=item -strFields

	=> 1 || 0 || 2

(C<ARS methods>)
Translate ARS field values using metadata and conversion sub{}s.
1 - using 'enumLimits' and C<strtime>/C<timestr>('yyyy-mm-dd hh:mm:ss'), 
2 - using at first localisation metadata for enum fields ('fieldLbvl').



=item -undef

	=> not exists || value 

(C<CGI Form Presenter - Field Definitions>)
Field value to be treated as undef or null for database.
See also C<-value>.



=item -used

	=> not exists == 1 || boolean || 'field name' || ['field name',..] 
	|| sub{}({self}, {field})

=item -unused

	=> not exists == 0 || boolean || 'field name' || ['field name',..]
	|| sub{}({self}, {field})

(C<CGI Form Presenter - Field Definitions>)
Condition to use or unuse field in the screen and actions.


=item -usr

	=> undef || 'ARS user name'

(C<Connection>)
ARS user name to login under



=item -value

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

lib/ARSObject.pod  view on Meta::CPAN

=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}

(C<ARS methods>)
Get record from ARS using ARS::ars_GetEntry().

Parameters:

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

-id => entryId

-fields => [internalId | fieldName,...]

-for => {} # steady hash to store each entry fetched

-echo=>1 # output command to STDOUT



=item entryBLOB (-form=>form, -id=>entryId, -field=>fieldId|fieldName) -> data

=item entryBLOB (..., -set=>data) -> id

=item entryBLOB (..., -file=>path, ?-set=>1) -> id