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; -schema, -meta, -metax, -metadn, -metaid, -schgen, -schfdo, -strFields; Variable files; lsflds

Variable files

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

ARS methods

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

-strFields, strIn, strOut;

arsquot;

-maxRetrieve

Utility Methods

strquot, strquot2, arsquot;

cptran, cpcon;

strtime, timestr, timeadd;

dsquot, dsquot1;

dsdump, dsparse, dscmp, dsmerge, dsunique;

fload, fstore;

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

SLOTS

Slots

-cgi

=> undef || CGI object

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

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

(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; CGI::Carp::set_message() may be used also.

See also -warn, -cpcon

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

-lang

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

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

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

-pswd

=> undef || ''

(Connection) ARS password string to login with

-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 || [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.
[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.

-storable

=> 1 || 0

(Variable files) Use Storable module for variable files? Or Data::Dumper will be used.

-srv

=> undef || 'ARS server name'

(Connection) ARS server name to connect

-strFields

=> 1 || 0

(ARS methods) Translate ARS field values using metadata and conversion sub{}s (-meta, -metaid, -metadn)?

-usr

=> undef || 'ARS user name'

(Connection) ARS user name to login under

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

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

METHODS

Methods

ars_errstr () -> $ARS::ars_errstr

(Error Processing and Echo) Last ARS error.

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.

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.

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

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

fload (?-opt, filename) -> content

(Utility Methods) Load data from file. Options: '-b' - binmode. See also 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.

-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

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, logfile ||'', run command || [command line] || sub{}, soon command || [command line])

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

soon (minutes, 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.

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-load' => sub{}(self, -slotName) specified, it will be used to fill unexisted file.

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

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.

VERSION

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