NAME

ARSObject - high level interface above ARS module

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', 'Region', 'AssetLifecycleStatus']
			,-order=>['Name']
			,-for=>sub{$hac->{$_[3]->{Name}} =$_[3];
				}
		);
  print $s->dsdump($hac);

DESCRIPTION

This module is intended for capable scripts above ARS module ("../ARSPerl/index.html" in ..).

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

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

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

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

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

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

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

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

Variable files may be used to cache any data.

Misc Utility Methods intended for strings, dates, data structures.

Utility Objects added to simplify and unify access to DBI, CGI, Net::SMTP modules.

CLASSIFICATION

Creation and Configuration

new, set, Slots

Error Processing and Echo

-die, -warn, -echo, -cpcon/cpcon; ars_errstr, dbierrstr

Connection

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

dbiconnect(-dbiconnect); -dbi

Metadata

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

Variable files

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

ARS methods

connect, query, entry, entryNew, entryIns, entryUpd, entryDel, entryBLOB, AUTOLOAD;

-strFields, strIn, strOut;

arsquot;

-maxRetrieve

Utility Methods

strquot, strquot2, arsquot;

cptran, cpcon;

strtime, timestr, timeadd;

dsquot, dsquot1;

dsdump, dsparse, dscmp, dsmerge, dsunique;

fopen, fload, fstore, fdirls;

soon

Utility Objects

dbi, -dbi, dbiconnect, -dbiconnect; dbiquery, dbido; dbierrstr

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

smtp, -smtp, smtpconnect, -smtphost; smtpsend

SQL Data Store Methods

arsmetasql, sqlname, dbidsmetasync, dbidsrpl, dbidsquery;

-meta-sql; -sqlschema;

-sqlname, -sqlntbl, -sqlncol, -sqlninc

CGI Form Presenter

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

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

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

cfprun, cfpaction, cfpv, cfpvv, cfpvl, cfpvp

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

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

* text: -widget=>'html'

* edit field: -name..,

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

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

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

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

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

CGI Form Presenter - Field Definitions

(for each field inside CGI Form Presenter - Fields)

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

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

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

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

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

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

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

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

-key => boolean

-master => 'field name'

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

-undef => value

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

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

-change => {set field values}

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

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

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

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

SLOTS

Slots

-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

(CGI Form Presenter - Field Definitions) Action to execute after the form performance, should be at the top of the form, before -key fields. May be several actions with the same -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 -preact.

-cgi

=> undef || CGI object

(Utility Objects) CGI utility object. See also cgi method.

-change

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

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

-computed

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

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

-cpcon

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

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

-ctrl

=> undef || ARS control struct

(Connection) ARS control struct from ARS::ars_Login()

-dbi

=> undef || DBI object

-dbiconnect

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

(Utility Objects) DBI utility object and connect specification to create it. See also dbi and dbiconnect methods.

-die

=> undef || sub{}

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

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

See also -diemsg, -warn, -cpcon

-diemsg

=> undef || sub{}(string)

Message for -die, alike CGI::Carp::set_message()

-echo

=> 0 | 1

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

-entryNo

=> entryIns()

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

-error

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

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

-fpl

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

-fphc

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

-fphd

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

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

-formdb

=> 'db form name'

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

-key

=> => not exists || boolean

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

-labels

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

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

-lbtran

-lbadd

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

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

-lang

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

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

-master

=> not exists || 'master field name'

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

-metadb

=> not exists || 'ARS field name'

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

-name

=> not exists || 'common field name'

-namecgi

=> not exists || 'cgi field name'

-namedb

=> not exists || 'ARS field name'

-namelbl

=> not exists || 'field label'

-namecmt

=> not exists || 'comment text'

-namehtml

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

(CGI Form Presenter - Field Definitions) Field names, label, comment text. If -name exists, it's value may be used as -namedb, and escaped value may be used as -namecgi.

-maxRetrieve

=> 0 || number of rows

(ARS methods) Max number of rows to retrieve from ARS server with query method.

-meta

=> {...}

(Metadata) Forms metadata from ARS server:

{formName}->{-fields}->{fieldName}=>{},

{formName}->{-fldids}->{fieldId}=>{}.

Futher data model is directly given from ARS::ars_GetFieldTable()/ARS::ars_GetField() excluding -metax.

Additional parameters may be: 'fieldLbl' => label, 'fieldLblc' => label cmt

-metaid

=> {fieldId => {fieldName=>'name',FieldId=>id, strIn|strOut=>sub{}},...}

-metadn

=> {fieldName => {fieldName=>'name',FieldId=>id, strIn|strOut=>sub{}},...}

(Metadata) Commonly used fields with common names and value translation. Data translation sub{}s may be specified as

'strOut'|'strIn' => sub(self,form,{field},$_=value){} -> translated value.

This sub{}s may use strOut() and strIn methods.

-metax

=> ['displayInstanceList','permissions']

(Metadata) Field parameters to exclude from -meta to decrease memory usage.

-meta-min

(Metadata)

Used by arsmetamin internally.

-meta-sql

=> undef || {SQL Data Store metadata}

(Metadata, SQL Data Store Methods, Variable files) SQL Data Store metadata loaded or refreshed by arsmetasql()/sqlname():

{tableName}->{-cols}->{sqlName}=>{fieldName, sqlName,...}

{tableName}->{-fields}->{fieldName}=>sqlName

{tableName}->{-ids}->{fieldId}=>sqlName

{-forms}->{formName}->{tableName}

-preact

=> not exists
|| sub{}({self}, action, '-preact'
	, {key field}, $_= key value, key pv
	, {field db name=>value,..})
	-> success || {field db name => value}
|| 'vfentry' || 'vfhash' || 'entry' || 'entryNew'

(CGI Form Presenter - Field Definitions) Action to execute before the form performance, should be at the top of the form, before -key fields. May be several actions with the same -namecgi. Alternative key field name may be passed as CGI->param(action-name). See alco -action.

-pswd

=> undef || ''

(Connection) ARS password string to login with

-record

=> 'record name' || 'nameRowNumber'

(CGI Form Presenter - Field Definitions) Record name, if several records in screen, may be defined as a special -fpl entry after -formdb entry. Record name may be followed by row number.

-reset

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

(CGI Form Presenter - Field Definitions) Condition to reset field value. If -values and field value unfound, it will be reset also.

-schema

=> undef || [form name, form name...]

(Metadata) ARS forms or schemas to use. Metadata will be loaded to -meta and may be cached with vfname(-meta) if -schgen.

-schfdo

=> 0 || 1

(Metadata) Include display only fields (AR_FIELD_OPTION_DISPLAY) into schema.

-schgen

=> 1 || 0 
|| 2 || 3 || [schema,...]

(Metadata) Cache metadata from ARS server using vfname(-meta)? Or each session get metadata from ARS server.

0 - get metadata from server, do not use cache file.
1 - generate cache file if not exists, else load this file.
2 - renew schema definitions using timestamps.
3 - renew schema always.
[schema,...] - list of schemas to renew.

-smtp

=> undef || Net::SMTP object

-smtphost

=> undef || SMTP host name

(Utility Objects) Net::SMTP utility object and connect specification to create it. See also smtp and smtpconnect methods.

-sqlname

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

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

-sqlncol

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

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

-sqlninc

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

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

-sqlntbl

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

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

-sqlschema

=> undef || SQL schema name

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

-storable

-meta-storable

<-vfname>-storable

=> 1 || 0

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

-srv

=> undef || 'ARS server name'

(Connection) ARS server name to connect

-strFields

=> 1 || 0 || 2

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

-undef

=> not exists || value 

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

-used

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

-unused

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

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

-usr

=> undef || 'ARS user name'

(Connection) ARS user name to login under

-value

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

(CGI Form Presenter - Field Definitions) Default field value or field value evaluator. See also -computed.

-values

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

(CGI Form Presenter - Field Definitions) Values for the drop-down list box field Special {-name=>name, field=>value,..} form is to define -change. See also -labels.

-vfbase

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

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

-vfname

=> not exists || '-slotName'

-vfrenew

=> not exists || boolean

-vfedit

=> not exists || boolean

-vftran

=> not exists || boolean

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

-vfrenew - renew variable file after 'entryIns' || 'entryUpd' || 'entryDel'

-vfedit - update variable file after 'entryIns' || 'entryUpd' || 'entryDel'

-vftran - translate value with -labels for variable file

-warn

=> undef

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

-warn

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

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

-warnmsg

=> undef || sub{}(string)

Message for -warn, alike -diemsg.

-widget

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

(CGI Form Presenter - Field Definitions) Definition of html field to display (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: -action => 1; -labels, -values; -disabled, -readonly, -hidden, -onchange => boolean.

-widget0

-widget1

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

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

METHODS

Methods

ars_errstr () -> $ARS::ars_errstr

(Error Processing and Echo) Last ARS error.

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

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

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

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

Synopsis: Refreshing -meta-min:

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

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

(Metadata, SQL Data Store Methods)

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

Synopsis: Refreshing -meta-sql:

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

See also sqlname(), dbidsmetasync(), dbidsrpl(), dbidsquery()

arsquot (string) -> escaped and quoted for ARS

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

AUTOLOAD ()

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

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

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

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

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

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

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

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

(CGI Form Presenter) Evaluate -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.

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

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

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

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

cgi () -> CGI object

cgi (CGI->new args) -> CGI object

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

cgiconnect (CGI args) -> CGI object

(Utility Objects) Connect to CGI.

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

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

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

cgiesc (string) -> escaped string

(Utility Objects) Escape string to HTML using CGI->escapeHTML(@_)

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

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

cgipar() -> parameters

cgipar(name) -> value

cgipar(name, value)

(Utility Objects) Get or set CGI parameter - CGI->param(@_)

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

(Utility Objects) Generate selection field HTML using CGI->popup_menu(@_)

-onchange=>1 - reload form when value changed

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

(Utility Objects) Generate text field HTML using CGI->textfield(@_)

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

(Utility Objects) Generate HTML textarea field using CGI->textarea(@_)

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

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

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

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

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

(Utility Methods) Translate strings between codepages using Encode.

dbi() -> DBI object

(Utility Objects) Access to DBI object. dbiconnect will be used if empty -dbi.

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

(Utility Objects) Connect to DBI database using -dbiconnect.

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

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

dbidsmetasync (-echo => 0 || 1)

(Metadata, SQL Data Store Methods)

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

dbidsrpl (-param => value)

(SQL Data Store Methods)

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

-echo => undef || 0 || 1

-form => ARS form name

-fields => undef || '*' || fields to replicate, alike 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, 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 -meta-sql

-timestamp => undef || 0 || 'Modified Date' timestamp ARS field name, default is obtained from -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 perlfunc::sleep between calls to ARS.

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

(SQL Data Store Methods)

Query data from SQL Data Store. Uses dbi(), -meta-sql, -sqlschema. Any dbi() method may be used for SQL Data Store, but 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'.

dbierrstr () -> dbi->errstr

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

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

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

dscmp (data1, data2) -> cmp

(Utility Methods) Compare two data structures alike cmp.

dsdump (data structure) -> dump string

(Utility Methods) Stringify any data structure using Data::Dumper. This string may be loaded back with dsparse().

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

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

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

dsparse (perl string) -> data structure

(Utility Methods) Convert dsdumped string to data structure.

dsquot (data structure) -> stringified

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

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

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

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

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

(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

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

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

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

(ARS methods) Retrieve BLOB field using ARS::ars_GetEntryBLOB() or update BLOB field using entryUpd(). 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

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

(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

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

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

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

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

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

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

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

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

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

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

-id=>entryId

-echo=>1 # output command to STDOUT

field === internalId | fieldName

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

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

(Utility Methods) List directory contents.

fload (?-opt, filename) -> content

(Utility Methods) Load data from file. Options: '-b' - binmode. See also fstore.

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

(Utility Methods) Open file with IO::File object. Options: '-b' - binmode. See also fload, fstore.

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

(Utility Methods) Store strings to file. Options: '-b' - binmode. Filename may be started with '>>' to add data to file. See also fload.

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

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

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

(Creation and Configuration) Create ARSObject.

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

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

(ARS methods) Query records from ARS.

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

Result set values are translated with strOut when -strFields.

Values in the query condition should be converted to ARS representation explicitly: strings should be quoted with arsquot(), dates - converted with 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

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

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

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

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

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

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

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

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

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

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

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

set (param) -> value

(Creation and Configuration) Configure ARSObject.

smtp() -> Net::SMTP object

(Utility Objects) Access to Net::SMTP object. smtpconnect will be used if empty -smtp.

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

(Utility Objects) Connect to Net::SMTP host using -smtphost.

smtpsend (-from || -sender => name, -to || -recipient => [name,...], -data => smtp data || (-subject => string, -text || -html => text)) -> Net::SMTP::dataend

(Utility Objects) Send Net::SMTP e-mail using smtp.

soon (minutes number || sub{}, logfile ||'', run command || [command line] || sub{}, soon command || [command line] || [])

soon (minutes number || sub{}, logfile ||'', run command || [command line] || sub{})

soon (minutes number || sub{}, logfile ||'', '', soon command || [command line])

Execute the script periodically, run command immediately, soon command after delay specified. Log file name may be full file name, else 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.

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

(Metadata, SQL Data Store Methods)

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

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

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

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

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

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

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

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

strtime (?mask, time ||localtime ||gmtime) -> stringified

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

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

(Utility Methods) Add values given to time given. Calculation via POSIX::mktime.

timestr (?mask, stringified time) -> seconds

(Utility Methods) Convert stringified with strtime time string to seconds form with POSIX::mktime

vfclear (-slotName) -> true

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

vfdata (-slotName) -> data structure

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

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

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

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

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

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

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

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

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

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

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

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

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

(Variable files) Load data structure from variables file using fload and -storable/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.

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

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

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

(Variable files) Renew variables file using vfstore() inside 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.

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

vfstore (-slotName) -> success

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

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

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

VERSION

2013-02-05

Publishing 0.57 version

2012-05-16

Publishing 0.56 version

2012-04-24

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

Updated lsflds().

Added schlblsl().

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

Extended arsmetamin() data with 'time' fields.

Added -metadb to CGI Form Presenter - Field Definitions.

2012-03-23

New SQL Data Store Methods

2011-10-26

New entryBLOB

2011-09-27

Publishing 0.55 version

2011-01-06

New arsmeta, arsmetamin. Documented schema.

2011-01-26

CGI Form Presenter added.

2010-11-22

Publishing 0.54 version, with several enhancements and corrections.

New -diemsg, -warnmsg, fdirls().

vfload - increased performance of loading text file, implemented text/binary format autodetection.

2010-10-09

Publishing 0.53 version, with several enhancements and corrections.

2010-08-25

strOut() method may return original enum value when cannot translate it.

vfstore()/vfload() extended with '-slotName-storable' switch.

2010-08-20

query(...,-fields=>'*',...) syntax added.

2010-07-01

Publishing 0.52 version, with several enhancements and corrections.

2010-06-08

Publishing 0.51 version, with several changes, enhancements and corrections.

2010-04-17

Publishing 0.50 version. I have two prototype scripts using this module.

2010-03-30

Documentation file written

2010-03-24

Detached

2010-03-02

Started inside a script

LICENSE

This is free software; you can use redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Andrew V Makarow <makarow at mail.com>, for Bank of Russia in Archangel

cpanm ARSObject

perl -MCPAN -e shell
install ARSObject