ARSObject

 view release on metacpan or  search on metacpan

lib/ARSObject.pod  view on Meta::CPAN

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>)
Compare two data structures alike L<cmp|perlop>.



=item dsdump (data structure) -> dump string

(C<Utility Methods>)

lib/ARSObject.pod  view on Meta::CPAN

=item lsflds (additional field properties) -> list of field descriptions

(C<Metadata>)
List field descriptions from C<-meta>.
May be useful when scripting.
Or set C<-storable> => 0 and view C<vfname>(C<-meta>) file.



=item new (param => value,...) -> ARSObject

(C<Creation and Configuration>)
Create ARSObject.



=item query (-form => schema name, -where => condition,...) -> list of records

=item query (..., -for => sub(self, form, id|string, ?{record}){die "last\n", die "next\n"}) -> self

(C<ARS methods>)
Query records from ARS.

Field names are translated to ids using C<-metadn>/C<-meta>.

Result set values are translated with C<strOut> when C<-strFields>.

Values in the query condition should be converted to ARS representation explicitly:
strings should be quoted with C<arsquot>(), dates - converted with C<timestr>().

Field names or ids in the query condition should be enclosed in ' single quotes.

Parameters:

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

-fields =>undef
# if '-fields' parameter omited, list of record IDs will be returned as a result set.

-fields => [{fieldId=>1, columnWidth=>number, separator=>"\t"} | {fieldName=>name, width=>number} | {field=>name|id, width=>number},...]
# result set is strings up to 128 bytes, ARS::ars_GetListEntry() used.

-fields => [fieldId | fieldName,...]
# result set is hash refs for each record, ARS::ars_GetListEntryWithFields() used.

-fields => '*' | '*-$' | 1, -xfields=>sub{}(self, field) || [fieldName| fieldId,...]
# result set is hash refs for each record, ARS::ars_GetListEntryWithFields() used.
# use '*-$' to excude currency and attachment fields.
# use '*-f' to excude attachment fields.

-fetch => '*' | 1 | [fieldId|fieldName,...]
# result set is hash refs for each record, ars_GetEntry() used for each row, this is slow.

-where | -query => search condition string
# Syntax:
'fieldId' || 'fieldName' - fields;
"string value" - strings;
digits - numeric value, number of seconds as date value;
strIn(form, fieldName, value) - to encode value for '-where'

-order | -sort => [fieldId | fieldName => (1||2) | ('asc'|'desc'),...]
# sort order, 1 - asc, 2 - desc

-first ||-start => firstRetrieve # ARS::ars_GetListEntry() parameter

-limit ||-max => maxRetrieve # ARS::ars_GetListEntry() parameter

-for ||-foreach => sub(self, form, id|string, ?{record}){die "last\n", die "next\n"} -> self
# iterator sub{} for each row

-echo => 1
# output query and details to STDOUT



=item schema () -> {schemaName => {metadata},...}

=item schema (schema name) -> {schema metadata} || undef

=item schfld (schema) -> {fieldName=>{field metadata},...}

=item schfld (schema, field name | meta) -> {field metadata} || undef

=item schid (schema, field '-metaid' | id) -> {fieldName=>'name', FieldId=>id}

=item schdn (schema, field '-metadn' | name) -> {fieldName=>'name', FieldId=>id}

=item schvals (schema, field name | id | meta) -> [itemNumber,...] || undef

=item schlbls (schema, field name | id | meta) -> {itemNumber => itemName,...} || undef

=item schlblsl (schema, field name | id | meta) -> {itemNumber => localised itemName,...} || undef

(C<Metadata>)
Access to ARS metadata loaded by C<connect>, C<arsmeta>, C<arsmetamin>.

 

=item set (param => value,...) -> self

=item set (param) -> value

(C<Creation and Configuration>)
Configure ARSObject.



=item smtp() -> Net::SMTP object

(C<Utility Objects>)
Access to L<Net::SMTP|Net/SMTP> object. 
C<smtpconnect> will be used if empty C<-smtp>.



=item smtpconnect (?-smtphost=> name) -> Net::SMTP object

(C<Utility Objects>)

lib/ARSObject.pod  view on Meta::CPAN

Execute the script periodically, run command immediately, soon command after delay specified.
Log file name may be full file name, else C<vfname>(file name) will be used.
If run command is empty, soon command will be scheduled.
If soon command is empty, sleep(minutes*60) will be used, otherwise 'at' MSWin32 scheduling command.
If !defined(minutes), soon command will be deleted from schedule and run command will be executed once.



=item sqlname (formName, ?fieldName, ?forceMetaUpd) -> sql name

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

Get SQL Data Store table or column name converted from ARS form and field name.
Used by C<arsmetasql>().
Uses C<-sqlname>, C<-sqlntbl>, C<-sqlncol>, C<-sqlninc> settings.



=item strIn (schema, fieldId | fieldName | field metadata, value) -> converted

(C<ARS methods>)
Convert value for ARS internal field value representation.
Called automatically when C<-strFields>. 
Should be called explicitly from C<strIn> sub{} in C<-metadn>/C<-metaid>.
May need to be called explicitly forming C<query> condition.
See also C<strOut>, C<-strFields>.



=item strOut (schema, fieldId | fieldName | field metadata, fieldValue) -> converted

(C<ARS methods>)
Convert ARS field value for external representation.
Called automatically when C<-strFields>. 
Should be called explicitly from C<strOut> sub{} in C<-metadn>/C<-metaid>
and when parsing strings result from C<query>.
See also C<strIn>, C<-strFields>.



=item strquot (string) -> escaped and quoted with ''

=item strquot2 (string) -> escaped and quoted with ""

(C<Utility Methods>)
Quote and escape string.
See also C<arsquot>



=item strtime (?mask, L<time|perlfunc> ||L<localtime|perlfunc> ||L<gmtime|perlfunc>) -> stringified

(C<Utility Methods>)
Stringify time value by mask.
Default mask is 'yyyy-mm-dd hh:mm:ss' (ISO).
L<POSIX::strftime|POSIX> uses different mask agreement.
See also C<timestr>.


=item timeadd (seconds, add years, ?months, ?days, ?hours, ?minutes, ?seconds) -> seconds incremented

(C<Utility Methods>)
Add values given to time given. Calculation via L<POSIX::mktime|POSIX>.



=item timestr (?mask, stringified time) -> seconds

(C<Utility Methods>)
Convert stringified with C<strtime> time string to seconds form 
with L<POSIX::mktime|POSIX>



=item vfclear (-slotName) -> true

(C<Variable files>)
Clear data loaded from variables file by C<vfload>(-slotName).
Reset data buffers of C<vfdata>() and C<vfhash>().



=item vfdata (-slotName) -> data structure

=item vfdata (-slotName, index) -> numbered element of data array

=item vfdata (-slotName, filter sub{}(self, -slot, index, $_=elem)) -> [record,...]

(C<Variable files>)
Access to data of variables file.
Automatically C<fload>s it.
Data structure will be treated as an array ref when index or filter argument used.



=item vfdistinct (-slotName, keyName) -> [value,...]

=item vfdistinct (-slotName, keyName, filter sub{}(self, -slot, keyName, keyValue, $_=elem)) -> [value,...]

(C<Variable files>)
Distinct values from C<vfdata>,
alike [sort keys %{C<vfhash>(-slotName, keyName)}].
Each element of C<vfdata>(-slotName) should be a hash with 'keyName' element.



=item vfhash (-slotName, keyName) -> {keyName=>{key => value},...}

=item vfhash (-slotName, keyName, keyValue) -> {key => value}

=item vfhash (-slotName, keyName, keyValue, key) -> value || undef if !ref(keyValue)

=item vfhash (-slotName, keyName, filter sub{}(self, -slot, keyName, keyValue, $_=elem)) -> {keyName=>{key => value},...}

(C<Variable files>)
Direct access to C<vfdata> using key name and value.
Each element of C<vfdata>(-slotName) array should be a hash with 'keyName' element.
C<vfdata> array will be automatically cached into hash "-slotName/keyName".



=item vfload (partial file name || -slotName) -> data structure

=item vfload (-slotName, ?create, ?renew ||renew period seconds) -> data structure

(C<Variable files>)
Load data structure from variables file using C<fload> and C<-storable>/C<dsparse>.
File absent may be created. 
File existed may be renewed immediatelly or if it is older then renew period.

If '-slotName' specified, this slot will contain loaded data structure.

If '-slotName-calc' => sub{}(self, -slotName) specified, file will not be used at all, 
data will be calculated on demand.

If '-slotName-load' => sub{}(self, -slotName) specified, it will be used to fill unexisted file.



=item vfname (partial name || -slotName) -> full var file path name in the filesystem

(C<Variable files>)
Convert partial file name to full, based on C<-vfbase>, for variables file.
Leading '-' will be excluded.



=item vfrenew (-slotName, ?renew period seconds) -> vfstore()/vfload()

(C<Variable files>)
Renew variables file using C<vfstore>() inside C<vfload>() with '-slotName-load' sub{}.
If no period or when period ==1 file will be renewed immediatelly.
Else file will be renewed only if it is older then period.



=item vfstore (partial file name, data structure) -> success

=item vfstore (-slotName) -> success

(C<Variable files>)
Store data to variables file using C<-storable>/C<dsdump> and C<fstore>.

If '-slotName' specified, this slot should contain data structure to be stored.

If '-slotName-storable' => switch specified, it will be used instead of C<-storable>.




=back


=head1 VERSION

=over

=head2 2013-02-05

Publishing 0.57 version


=head2 2012-05-16

Publishing 0.56 version


=head2 2012-04-24

Added field localisation metadata, see source code for 'fieldLbll' and 'fieldLbvl'.

Updated C<lsflds>().

Added C<schlblsl>().

Added C<-strFields> => 2 - translate ARS enum field values using at first
localisation metadata ('fieldLbvl').

Extended C<arsmetamin>() data with 'time' fields.

Added C<-metadb> to C<CGI Form Presenter - Field Definitions>.



=head2 2012-03-23

New C<SQL Data Store Methods>