template::query (public)

 template::query statement_name result_name type sql [ args... ]

Defined in packages/acs-templating/tcl/query-procs.tcl

Public interface to template query api. This routine parses the arguments and dispatches to the query command specified by the type argument.

Parameters:

statement_name (required)

Standard db_api query name

result_name (required)

Tcl variable name when doing an uplevel to set the returned result

type (required)

The query type

sql (required)

The sql to be used for the query

Options:

-maxrows

Limits the query results of a multirow query to a fixed number of rows.

-cache

Cache the query results keyed on an identifier that is unique for both the query and the bind variables used in the query. The cached result reflects any initial specification of maxrows and startrows.

-refresh

Force a query to be performed even if it is cached, and refresh the cache.

Only applicable if the cache option is specified as well. Does not affect a previously specified timeout period.

-timeout

The maximum period of time for which the cached results are valid in seconds. Only applicable for persistently cached results.

-persistent

Cache the query results persistently, so that all subsequent requests use the results.

Returns:

1 if query was a success, 0 if it failed

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Source code:

    set sql [string trim $sql]
    set full_statement_name [db_qd_get_fullname $statement_name]

    #set beginTime [clock clicks -milliseconds]

    template::util::get_opts $args

    if { ! [info exists opts(uplevel)] } {
        set opts(uplevel) 2
    } else {
        set opts(uplevel) [expr {2 + $opts(uplevel)}]
    }

    # check the cache for a valid cached query result and return if so
    # otherwise continue to perform the query and cache the results afterwards

    if { [info exists opts(cache)] && [get_cached_result $result_name $type] } {
        return $opts(result)
    }

    if { ! [info exists opts(maxrows)] } {
        set opts(maxrows) 10000
    }

    db_with_handle db {
        set ret_code [template::query::$type $full_statement_name $db $result_name $sql]
    }

    if { [info exists opts(cache)] } {

        # cache the query result
        template::set_cached_result
    }

    #set timeElapsed [expr ([clock clicks -milliseconds] - $beginTime)]
    #ns_log Notice "Query performed in: $timeElapsed ms"

    return $ret_code

XQL Not present:

Generic, PostgreSQL, Oracle