This is a database layer for Perl scripts, implementing triggers, record versioning, access control at the record level, file attachments to records, materialised views. There is a web user interface also.

Based on DBI and DB_File data engines. Based on CGI for user interface.

Currently implemented and tested on Win32 Apache and IIS (considering w32IISdpsn warnings).

CGI::Bus, the previous project, was: focused on CGI user interface to database tables, not database metaphor; too complex in record version control programming; too complex and surplus in architecture and setup.

Many of relational databases have not explicit record level access control. It may be implemented via views and triggers, within another application code. Fields for readers and authors names are useful, further needs dependences between records.

Can I query and view data not from concrete tables but from database? It may be implemented via materialized views metaphor, using triggers. Further needs uniform record identifiers, to point to any record from any record, or URL. Full-text queries are also useful.

All application codes are concentrated at the server. Why programmer needs to use different programming languages to implement triggers and stored procedures in the database and another procedures in the web server? Why user interface hooks may not be considered as a kind of triggers?

Should be interesting a separate 'triggers server'? Or this may be considered as a kind of application servers?

Alike Wikis, may include record level access control, file attachments, forms, views and queries, may progress towards database metaphor. But transition from from initial hypertext metaphor to database may require a great effort in implementation.

One of the problems is repeating cursor loops in recUpd (one for '0R' trigger and one inside dbiUpd) and recDel (for '0R' trigger and dbiDel or recUpd). The last loop is always effectively implemented inside DBI SQL databases, but for DB_Files it should be implemented implicitly inside dbiUpd or dbiDel. To implement efficacious '1R' triggers inside recUpd or recDel, and also for effectiveness of DB_Files, dbiUpd and dbiDel should not be oriented to the groups of rows, or there should be a fast additional single row oriented interface. Also recDel should use a fast single row oriented interface of recUpd. So, there should be two interfaces to recUpd, dbiUpd and dbiDel for effectiveness. But this is difficult in develop and test.

Slots are available via set call or $self->{-name} syntax. See initialize source for preferred to be defined in new call slots. Table and Form description (-table, -form) slots, special data fields, and another keywords are denoted specially. The first value listed is the default.

-fieldTable/Form Description slot contains reference to array of field descriptions. Ordinary field description is a hash ref with a keys listed below. Also may be used when display single record form sub{}s and layout markup strings.

(User Interface - Field Description) Field value check. Performed after -recTrim0A and -null conversion preceding recIns or recUpd operation. $_ represents field value, may be read and assigned; $@ intended for constraint violation message.

(SubObjects) DBI connection arguments string or array, used in dbi call. Started with 'DBI:Proxy:hostname=127.0.0.1...' connection string starts DBI::ProxyServer process if not found connecting, i.e. 'dbi:Proxy:hostname=127.0.0.1;port=3334;proxy_no_finish=1;dsn=DBI:mysql:...'. See also -dbistart.

(Field Description) Drop-down list box with editable input and produced on button press selection list. recSel, recUnion, cgiQuery, cgiQueryFv, hreverse results may be returned by sub{}. See also -ddlbmult, -ddlbtgt

(Field Description) Drop down list box targets. '+' marks multivalue fields. 'multi' mark considered as boolean digit or values delimiter. Single field name will be represented with submit button, array will be represented with javascript buttons; default is current field. See -ddlb.

(Table/Form Description, Field Description) Table or Field name as used inside SQL database engine, or SQL expression. Table name for application is explained as -table key. Field name for application is explained as -fld.

(Table/Form Description - Field Description) Reference to array of field descriptions. Ordinary field description is a hash ref, see Field Description. When display a single record form also may be used layout markup strings, text strings, sub{}routines. Text or result of sub{} evaluation will be outputted. Tabular form layout hints: '' continues labels and fields in the current row, "\n" continues on next row(s), "\t" skips cell(s), "\f" finishes tabular layout, '</table>' finishes tabular layout and labels of the fields. See also -colspan and -lblhtbr.

-frmLso0A trigger will be called for each -frmLso value and may be used to change -pcmd emulating user defined query parameters. -frmLso0C trigger may be used to modify immediate arguments of Ñ<cgiQuery> issue.

-frmLso1C and -frmLso2C triggers may be used to modify htmlMenu comment and cgiList first column header. urlOpt and htmlMQH methods may be useful.

(Table/Form Description) Index table (Materialised Views) indication. Scalar 'true' value is used for indexes should be updated from -recIndex0R indexing trigger. Sub{} used as condition for inclusion of particular record from particular table into index. -ixrec used to obtain values for inclusion/exclusion

(Table/Form Description) Index table (Materialised Views) records former. May directly create ('+') or delete ('-') index records, or return values of records to be included or excluded. See also -ixcnd

(Table Description, Form Description, Field Description) Label or external name of the object to be displayed to user, default (international) or user language specific. See also -cmt, -lblhtml, -inp, -inphtml

(User Identification) Login URL part, where web server authentication of users is estimated. Web server virtual directory with user authentication required. Authentication may be required for one virtual directory and may be unnecessary for another.

(User Interface) User Interface forms list. Default will be generated from -form and -table. One of special postfixes below may be supplied to form name in -menuchs, while -menuchs1 is expected for '+' only:

(Database Description, Table/Form Description - Record level Access Control, Templates) Field(s) to store names of user(s) to be considered as actors of record. Used for -urole clause of recSel. Default is about -rvcUpdBy.

(Database Description, Table/Form Description - Record level Access Control) Field(s) to store names of user(s) to be considered as a managers of record. Used for -urole clause of recSel. Default is about -rvcInsBy.

(Database Description, Table/Form Description - Record level Access Control, Templates) Field(s) to store names of user(s) to be considered as principals of record. Used for -urole clause of recSel. Default is about -rvcInsBy.

(Database Description, Table/Form Description - Record level Access Control, Templates) Field(s) to store names of user(s) to be considered as users of record. Used for -urole clause of recSel. Default is about -racPrincipal.

(Database Description, Table/Form Description - Record ID References) Fields may contain references to another records. Scalar reference may be in form 'record id' or 'table//id'. Embedded into text references are considered as '_key=table//id' or '_key=id%3Dtable//id' URL parts. See also tvmReferences, tfvReferences.

(Database Description, Table Description, Form Description; all executed) Record changing trigger before each row. Executed in recIns and recUpd before -recIns0R and -recUpd0R. May be used to provide absolutely computed values when record storing. See also -recChg0W, -recEdt0R.

(Database Description, Table Description, Form Description; all executed) Record changing trigger before each row written. Executed immediatelly before writing record to database, in recIns and recUpd, after -recChg0R, -recIns0R, -recUpd0R, -recInsID. May be used when key generated for new record needded, i.e. for smtpSend. See also -recChg0R, -recEdt0R.

(Database Description, Table Description, Form Description; all executed) recDel triggers before command ('0C'), before each row ('0R'), after command ('1C'). When record versioning, update triggers will be executed too, within.

(Database Description, Table Description, Form Description; all executed) Record editing trigger before each row. Executed after -recForm0R/-recFlim0R and before -recChg0R. May be used to translate values or provide absolutely computed values during record editing or storing. See also -recChg0R.

Record display triggers starting ('0A') or ending ('1A') any record edit or display action, except recDel ending and recQBF. Called by User Interface, -recForm0A after -recTrim0A but before -recEdt0A, -recForm1A after -recEdt1A.

May be used to provide computed for display values. See also -recEdt0A, -recChg0R, -recEdt1A; -recForm0C, -recForm0R, -recFlim0R, -recForm1C.

(Database Description, Table Description, Form Description; all executed) recNew triggers before ('0') and after command ('1C'). If key value available, a sample record will be fetched and provided to -recNew0C trigger to add some field values from sample record.

(Database Description, Table/Form Description - Record level Version Control) Field to store ID of the actual version of this record. If this field is empty, the record is the last version, actual. If this field is not empty, the record is an old version or is checked-out.

(Database Description, Table/Form Description - Record level Version Control) Check-out state of record: Field name and state value. If record is check out, old version will not be created at record update. And file attachments may be edited. Check-out record may be checked-in -rvcActPtr record. Distinguish from -rvcChgState, which could not be checked-in.

(Database Description, Table/Form Description - Record level Version Control) Field name to store record's state and list of the change state values. When record is in change state, old version will not be created at record update. And file attachments may be edited. Distinguish from -rvcCkoState, which may be checked-in.

(Database Description, Table/Form Description - Record level Version Control) Field for time version record written when. To keep the end of actuality period of version record started with -rvcUpdWhen. recUpd fills this field with -rvcUpdWhen of actual record when recording its old version.

(User Interface) URL may be opened in the '_search' frame of the browser when -search button pressed or -search web request parameter specified. I.e. sub{$_[0]->urlCmd('',-form=>'navigator.psp',-cmd=>'frmCall')}. A frameset with 'LEFT' and 'RIGHT' frames will be used if URL =~/\b_frame=RIGHT\b/. See also -logo.

Fields one of may be used to search for record by its wiki name. Default candidates are defined at database level. Table may be excluded from search using false value. See also -opt for '-hrefs' and 'wikn://'.

Processor for requests for -wikn and -wikq. Should convert -wikn/-wikq request parameters to -table/-qkey, may use database. -wikq request parameter may be table name to be used to search for -wikn or any value to be processed by -wikq sub{}. Else -wikn will be processed.

User Interface. Outputs record's form via output, used by cgiRun for record and QBF operations (see -recXXX). See Table/Form Description for form specifications and -field for formatting considerations. See htmlField for independent widgets. Use tfdRFD or -inp for file attachments. Use cgiList and -field for embedded views.

User Interface. Lists data rows via output, used by cgiRun for cgiQuery results. '!h' option turns off table header. See Table/Form Description, -query, recSel for query and list specifications, additional query/list clauses are -field to use instead of -data, and -display to use instead of -flg values of -field.

User Interface. Forms and starts query using recSel. Returns cursor. Used by cgiRun, with cgiList follows. See Table/Form Description, -query, cgiList and recSel for query and list specifications. See also cgiQueryFv and cgiSel.

Misc Data methods. Reverses hierarchical source data values. Source array ref or cursor will be reversed to a hash ref, string will be reversed to a string. Hierarchy may be marked inside values with a split char, i.e. 'value/subvalue/...'. Original source data values are used for keys of the result. Values of the result are joinreversesplit of the source values.

Misc Data methods. Converts parameters given to the list to print HTML tag with 'name', 'attributes' and optional 'content' tags inside. Leading '-' signs in attribute names are ignored. Values are escaped. Newlines string may be the last parameter to format output. The list structure will not be documented. See also xmlsTag, outhtm

User Interface. Generates menu bar styled hyperlink HTML with query options. May be used within -frmLso1C. Display value may be defined using -label option for text or immediate -html option. Hyperlink will be highlited if current query matches options defined. The last matched call may be inspected in $s->{-pcmd}->{-htmlMQH}.

Database Operation. Determines if current user corresponds to one of the roles listed for record given. Checks or computes -editable special field if '0' role listed. May be used for conditions in -recFlim0R, i.e. $_[3] && recActor(@_[1..3],...) && recActLim(@_[1..3],...)

Database Operation. Deletes record(s) into database, under '-key' or '-where' conditions. Returns command hash ref or the result of recUpd. When Record level Version Control, operation will be passed to recUpd, but recDel triggers (-recForm0C, -recDel0C, -recForm0R, -recFlim0R, -recDel0R, -recDel1C) will be executed anyway.

Database Operation. Recalculates record, new or existing in database. Original field values obtained via recRead(-table=>name, -key=>{original recKey}) and added to new data given if not exists; -recForm0C, -recForm0R, -recFlim0R, -recForm1C triggers executed.

Database Operation. Inserts record(s) into database. Returns record successfully inserted or data hash ref. Given field values are used to initiate new record's hash ref; -recForm0C and -recIns0C triggers are executed; -rvcInsBy-rvcUpdBy, -rvcInsWhen, -rvcUpdWhen fields are filled. Data to be inserted may be given from prototype record via recRead(-table=>name, -key=>{original recKey}), or recSel cursor. After all given values applied, -recForm0R, -recFlim0R, -recEdt0R, <-recChg0R>, -recIns0R, -recInsID, -recChg0W triggers executed and record is inserted into database. At last, <-recIns1R> and -recForm1C triggers are executed.

See also recNew and recForm, but they are not required to prepare data to be inserted.

Database Operation. Reads newest record from database according to field names described and record data given. Attempts including lookup arguments from last. Supplies target with values fetched, returns record fetched. Useful for fetching default field values within triggers. May be not implemented for non-sql Database Engines. Command options used are -table => table name, -version => switch including versions of records, -excl => switch excluding record given.

Database Operation. Creates a new data record to be inserted into database. Given field values are used to initiate new record's hash ref; -recForm0C and -recNew0C triggers are executed; -rvcInsBy-rvcUpdBy, -rvcInsWhen, -rvcUpdWhen fields are filled. Prototype's field values may be obtained from '-proto' or via recRead(-table=>name, -key=>{prototype key}), but are not used instead of -recNew0R. -recForm0R, -recFlim0R, -recEdt0R, -recNew1C, -recForm1C triggers are executed at last. The following calls may be recForm and recIns.

Database Operation. Retrieves records from database. Some substitutions may be available in SQL WHERE in addition to options above: '#urole(role)', '#urole(role, name)', '#ftext(string)'. Cursor's slot -rec with hash ref {field alias || name => value,...} is bound as field variables. Cursor's slot -rfr contains array ref with references to values in -rec in order of -data list. At least fetch, fetchrow_arrayref, fetchrow_hashref, finish, close methods are supported by cursor. See also -recSel0C, recList, recRead.

Database Operation. Updates record(s) into database, under '-key' or '-where' conditions. With '-optrec', record will be inserted if not present. Returns record updated if one only, or data hash ref if zero or more then one record updated. See also -recForm0C, -recUpd0C, -recForm0R, -recFlim0R, -recChg0R, -recUpd0R, -recChg0W, -recUpd1C, -recForm1C triggers.

Record File Attachments. Removes record's file attachments directory and cleans the path bottom-up. Record should be -editable with -file, which are Data Record Special fields provided by Database Operation.

User Identification. Returns display name for user or group name given. Returns name given if cannot translate. udispq is intended as a quick version to be used for cgiList. See -udisp to extend default behaviour.

Called internally with rational refresh interval, may be called from Command Line.

pthForm('var','ualist') file is for uglist. pthForm('var','uagroup') file may be used as Apache's 'AuthGroupFile'. See source code for specifications.

Using ugfile(), -AuthGroupFile/-AuthUserFile or -PlainGroupFile/-PlainUserFile should not be set. This slots should be set only to externally controlled files. I.e. to files produced via "$0 -call ugfile ugf_w32 0 s" Command Line.

User Identification. Returns user ('-u') and group ('-g') names using filter given in array ([]) or hash ({}) ref; '<>' option forces comment notation for hash ref 'd' is used for udisp, 'c' forms group comments to display names. Default is both ('-ug') in array ref ([]). Uses -AuthUserFile and -AuthGroupFile, or ugfile. Considers -userln and -usernt. See also ldapLst.

User Identification. Returns string of e-mail addresses for string of user names given. Short names will not be supplied with -smtpdomain, it will be used by smtpSend(). See also uglist('-@c') and ugfile() for limitations and details.

Misc Data methods. Escapes and unescapes to and from URL format. urlCat only escapes and catenates arguments, whereas urlCmd replaces leading '-' with '_' in names and stringfies data structures with strdata. See also htmlEscape.

Misc Data methods. Converts parameters given to the list to print XML tag with 'name', 'attributes' and optional 'content' tags inside. Leading '-' signs in attribute names are ignored. Values are escaped. Newlines string may be the last parameter to format output. The list structure will not be documented. See also htlsTag, outxml

Triggers may be defined (in execution order) at database level, table level, form level. Common trigger sub{} arguments are

($self, {command}, {new field => value}, {prev field => value})

Values for 'by-command' triggers are given from arguments of command. Values for 'by-row' triggers are corresponded to a whole record. Previous values are available only in 'by-row' triggers only for existed records. Previous values are not available in recNew and recIns. New valies are not available in recDel. So, new or previous values may be not available is -recForm0R, -recFlim0R, -recEdt0R, -recChg0R, -recChg0W.

Redesign of -recForm0C triggers position, now always called first in command. New -recForm0R triggers added. -recIns0C and -recRead0C triggers repositioned just after -recForm0C. Triggers Interface extended.

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

Without specially written agreement prohibited to use completely, partially or in ideas for impairing nature industries in Archangel region (wood and timber, geological and mining, space and war); Russian procrastination structures and kgbists.