NAME
    Rose::DBx::CannedQuery::Glycosylated - Some sugar for
    Rose::DBx::CannedQuery

SYNOPSIS
      use Rose::DBx::CannedQuery::Glycosylated;
      my $qry = Rose::DBx::CannedQuery::Glycosylated->new(
                  rdb_class => 'My::DB',
                  rdb_params => { type => 'real', domain => 'some' },
                  sql => 'SELECT * FROM table WHERE attr = ?',
                  verbose => 3, logger => $my_debug_logsink,
                  name => "$table scan"
                );

      # Typical CannedQuery execution, with trace messages built in
      foreach my $row_hash ( $qry->do_one_query(@bind_vals) ) {
        do_something($row_hash);
      }

      # Resultset too big to copy?  Fetch just a chunk, and use array
      # references rather than hash references
      foreach my $row ( $qry->do_one_query_ref($bind_ref, [ [], 2000 ]) ) {
        do_something($row);
      }

      # Package up several query executions, again with trace messages
      my %conditions = assemble_query_criteria();
      generate_result_table($qry->do_many_queries(\%conditions));

DESCRIPTION
    This class provides a lightly sweetened flavor of
    Rose::DBx::CannedQuery, intended to simplify the job of running multiple
    instances of a particular query, while providing feedback to the user.
    It doesn't (much) alter the way the query interacts with the database,
    but is intended to abstract out some of the "chrome" often repeated in
    code that tried to keep the user informed as the queries execute.

  ATTRIBUTES
    Instances of Rose::DBx::CannedQuery::Glycosylated have all of the
    attributes supplied by Rose::DBx::CannedQuery and MooX::Role::Chatty. In
    addition, one new attribute is added:

    name
        A string identifying this particular query; it is used in log
        messages to help you figure out which query is executing.

        If you do not provide a value, it defaults to the start of the SQL
        used to build the query.

  METHODS
    do_one_query([*@bind_values*])
        Execute the query, passing the list of bind values specified in
        *@bind_values*, analogously to Rose::DBx::CannedQuery::results.
        Returns the list of resultant rows in array context, or the number
        of rows returned in scalar context.

        If the "verbose" in MooX::Role::Chatty attribute is 3 or higher, an
        informational message is output (showing the bind values, if any)
        prior to execution, and a second message showing the result count is
        output after execution.

    do_one_query_ref([*$bind_values*, *$query_opts*])
        Execute the query, passing the bind values specified in
        *$bind_values*, which must be a reference to an array of bind
        values, as documented in "resultref" in Rose::DBx::CannedQuery.
        Returns the array reference containng the results of the query.

        If *query_opts* is an array reference, it is passed unchanged to
        "resultref" in Rose::DBx::CannedQuery. If it is a simple
        (non-reference) scalar, the value is passed to "fetchall_arrayref"
        in DBI as the $max_rows parameter. If you want resultset rows as
        array references for efficiency, or want to actually retrieve a
        slice of the results for each row, you need to supply *query_opts*
        as an array reference that provides $slice, and optionally
        $max_rows.

        If the "verbose" attribute is 3 or higher, an informational message
        is output (showing the bind values, if any) prior to execution, and
        a second message showing the result count is output after execution.

    do_many_queries([*$param_sets*])
        Execute the query several times via "do_one_query", using different
        bind values (and possibly query options) each time, and collect the
        results.

        The *$param_sets* parameter is typically a hash reference, where the
        keys are strings naming each set of parameters. If you don't care to
        name your sets of bind values, you may also simply pass in a
        reference to an array of (array references containing) query
        parameters.

        The value of each element in *$param_sets* is an array reference. If
        the array contains simple sclars, they are treated as a list of bind
        parameter values. If the first element is itself an array reference,
        then that element is used as *$bind_vals* and the next element as
        *$query_opts* (as taken by "do_one_query_ref").

        If you pass in *$param_sets* as a hash reference, the return value
        is a hash reference, with the keys again being the names of the
        parameter sets, and the values being array references containing the
        results for that set of bind values. If you pass in an array
        reference, an array reference is returned, which contains array
        references holding the results for each parameter set;
        unsurprisingly, resultset elements are in the same order as the bind
        value sets you passed in.

        Trace messages are output as described above for "do_one_query". In
        addition, if the "verbose" attribute is 2 or higher, an
        informational message is output for each bind set.

EXPORT
    None.

SEE ALSO
    Rose::DBx::CannedQuery and MooX::Role::Chatty for more information on
    specific behavior.

    Rose::DBx::MoreConfig (or Rose::DB) for more information on managing the
    underlying DBI conncetions.

BUGS AND CAVEATS
    Are there, for certain, but have yet to be cataloged.

VERSION
    version 1.00

AUTHOR
    Charles Bailey <cbail@cpan.org>

COPYRIGHT AND LICENSE
    Copyright (C) 2015 by Charles Bailey

    This software may be used under the terms of the Artistic License or the
    GNU General Public License, as the user prefers.

