canonicalize_date¶

Given a string that PostgreSQL might recognize as a date, pass it to the database via the SQL statement:

    SELECT CAST( ? AS date )

and return the resulting status object.

canonicalize_ts¶

Given a string that might be a timestamp, "canonicalize" it by running it through the database in the SQL statement:

    SELECT CAST( ? AS timestamptz )

canonicalize_tsrange¶

Given a string that might be a tsrange, "canonicalize" it by running it through the database in the SQL statement:

    SELECT CAST( ? AS tstzrange )

Returns an App::CELL::Status object. If the status code is OK, then the tsrange is OK and its canonicalized form is in the payload. Otherwise, some kind of error occurred, as described in the status object.

cud¶

Attempts to Create, Update, or Delete a single database record. Takes the following PARAMHASH:

• conn

  The DBIx::Connector object with which to gain access to the database.

• eid

  The EID of the employee originating the request (needed for the audit triggers).

• object

  The Dochazka datamodel object to be worked on.

• sql

  The SQL statement to execute (should be INSERT, UPDATE, or DELETE).

• attrs

  An array reference containing the bind values to be plugged into the SQL statement.

Returns a status object.

Important note: it is up to the programmer to not pass any SQL statement that might affect more than one record.

cud_generic¶

Attempts to execute a generic Create, Update, or Delete database operation. Takes the following PARAMHASH:

• conn

  The DBIx::Connector object with which to gain access to the database.

• eid

  The EID of the employee originating the request (needed for the audit triggers).

• sql

  The SQL statement to execute (should be INSERT, UPDATE, or DELETE).

• bind_params

  An array reference containing the bind values to be plugged into the SQL statement.

Returns a status object.

Important note: it is up to the programmer to not pass any SQL statement that might affect more than one record.

decode_schedule_json¶

Given JSON string representation of the schedule, return corresponding HASHREF.

get_history¶

This function takes a number of arguments. The first two are (1) a SCALAR argument, which can be either 'priv' or 'schedule', and (2) a DBIx::Connector object.

Following these there is a PARAMHASH which can have one or more of the properties 'eid', 'nick', and 'tsrange'. At least one of { 'eid', 'nick' } must be specified. If both are specified, the employee is determined according to 'eid'.

The function returns the history of privilege level or schedule changes for that employee over the given tsrange, or the entire history if no tsrange is supplied.

The return value will always be an App::CELL::Status object.

Upon success, the payload will be a reference to an array of history objects. If nothing is found, the array will be empty. If there is a DBI error, the payload will be undefined.

load¶

Load a database record into an object based on an SQL statement and a set of search keys. The search key must be an exact match: this function returns only 1 or 0 records. Call, e.g., like this:

    my $status = load( 
        conn => $conn,
        class => __PACKAGE__, 
        sql => $site->DOCHAZKA_SQL_SOME_STATEMENT,
        keys => [ 44 ]
    );

The status object will be one of the following:

• 1 record found

  Level "OK", code "DISPATCH_RECORDS_FOUND", payload: object of type 'class'

• 0 records found

  Level "NOTICE", code "DISPATCH_NO_RECORDS_FOUND", payload: none

• Database error

  Level "ERR", code "DOCHAZKA_DBI_ERR", text: error message, payload: none

load_multiple¶

Load multiple database records based on an SQL statement and a set of search keys. Example:

    my $status = load_multiple( 
        conn => $conn,
        class => __PACKAGE__, 
        sql => $site->DOCHAZKA_SQL_SOME_STATEMENT,
        keys => [ 'rom%' ] 
    );

The return value will be a status object, the payload of which will be an arrayref containing a set of objects. The objects are constructed by calling $ARGS{'class'}->spawn

For convenience, a 'count' property will be included in the status object.

make_test_exists¶

Returns coderef for a function, 'test_exists', that performs a simple true/false check for existence of a record matching a scalar search key. The record must be an exact match (no wildcards).

Takes one argument: a type string $t which is concatenated with the string 'load_by_' to arrive at the name of the function to be called to execute the search.

The returned function takes a single argument: the search key (a scalar value). If a record matching the search key is found, the corresponding object (i.e. a true value) is returned. If such a record does not exist, 'undef' (a false value) is returned. If there is a DBI error, the error text is logged and undef is returned.

noof¶

Given a DBIx::Connector object and the name of a data model table, returns the total number of records in the table.

    activities employees intervals locks privhistory schedhistory
    schedintvls schedules tempintvls

On failure, returns undef.

priv_by_eid¶

Given an EID, and, optionally, a timestamp, returns the employee's priv level as of that timestamp, or as of "now" if no timestamp was given. The priv level will default to 'passerby' if it can't be determined from the database.

schedule_by_eid¶

Given an EID, and, optionally, a timestamp, returns the SID of the employee's schedule as of that timestamp, or as of "now" if no timestamp was given.

_st_by_eid

Function that 'priv_by_eid' and 'schedule_by_eid' are wrappers of.

select_single¶

Given a DBIx::Connector object in the 'conn' property, a SELECT statement in the 'sql' property and, in the 'keys' property, an arrayref containing a list of scalar values to plug into the SELECT statement, run a "selectrow_array" and return the resulting list.

Returns a standard status object (see "load" routine, above, for description).

select_set_of_single_scalar_rows¶

Given DBIx::Connector object, an SQL statement, and a set of keys to bind into the SQL statement, assume that the statement can return 0-n records and that each record consists of a single field that must fit into a single scalar value.

split_tsrange¶

Given a string that might be a tsrange, run it through the database using the SQL statement:

    SELECT lower(CAST( ? AS tstzrange )), upper(CAST( ? AS tstzrange ))

If all goes well, the result will be an array ( from, to ) of two timestamps.

Returns a status object.

timestamp_delta_minus¶

Given a timestamp string and an interval string (e.g. "1 week 3 days" ), subtract the interval from the timestamp.

Returns a status object. If the database operation is successful, the payload will contain the resulting timestamp.

timestamp_delta_plus¶

Given a timestamp string and an interval string (e.g. "1 week 3 days" ), add the interval to the timestamp.

Returns a status object. If the database operation is successful, the payload will contain the resulting timestamp.

tsrange_intersection¶

Given two strings that might be tsranges, consult the database and return the result of tsrange1 * tsrange2 (also a tsrange).

tsrange_equal¶

Given two strings that might be equal tsranges, consult the database and return the result (true or false).