query-procs.tcl

Database Query API for the ArsDigita Templating System

Location:
packages/acs-templating/tcl/query-procs.tcl
Created:
29 September 2000
Authors:
Karl Goldstein <karlg@arsdigita.com>
Stanislav Freidin <sfreidin@arsdigita.com>
CVS Identification:
$Id: query-procs.tcl,v 1.50.2.8 2022/12/29 12:52:06 gustafn Exp $

Procedures in this file

Detailed information

multirow (public, deprecated)

 multirow [ -ulevel ulevel ] [ -local ] [ -unclobber ] op name \
    [ args... ]
Deprecated. Invoking this procedure generates a warning.

multirow is really template::multirow or possibly template::query::multirow depending on context. the "template::" or "template::query::" may be omitted depending on what the namespace is. .tcl pages are evaluated in the template:: namespace. DEPRECATED: namespace should actually NOT be omitted

Switches:
-ulevel
(defaults to "1") (optional)
-local
(boolean) (optional)
-unclobber
(boolean) (optional)
Parameters:
op
name
See Also:

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

Testcases:
No testcase defined.

template::cache (public)

 template::cache command cache_key [ args... ]

Generic Caching

Parameters:
command
cache_key

Partial Call Graph (max 5 caller/called nodes):
%3 bug_tracker::bug::cache_flush bug_tracker::bug::cache_flush (public) template::cache template::cache bug_tracker::bug::cache_flush->template::cache forum::flush_templating_cache forum::flush_templating_cache (public) forum::flush_templating_cache->template::cache template::paginator::create template::paginator::create (public) template::paginator::create->template::cache template::paginator::init template::paginator::init (private) template::paginator::init->template::cache template::paginator::reset template::paginator::reset (public) template::paginator::reset->template::cache acs::clusterwide acs::clusterwide template::cache->acs::clusterwide

Testcases:
No testcase defined.

template::get_cached_result (private)

 template::get_cached_result name type

Looks in the appropriate cache for the named query result If a valid result is found, then sets the result in the returning stack frame.

Parameters:
name - Name of cached result-set
type - Type of query
Returns:
1 if result was successfully retrieved, 0 if failed

Partial Call Graph (max 5 caller/called nodes):
%3 template::query template::query (public) template::get_cached_result template::get_cached_result template::query->template::get_cached_result acs::clusterwide acs::clusterwide template::get_cached_result->acs::clusterwide template::multirow template::multirow (public) template::get_cached_result->template::multirow

Testcases:
No testcase defined.

template::multirow (public)

 template::multirow [ -ulevel ulevel ] [ -local ] [ -unclobber ] \
    command name [ args... ]

Create/Manipulate a multirow datasource (for use with <multiple> tags)

template::multirow create datasourcename column [column ...]
creates a multirow datasource of datasourcename
template::multirow extend datasourcename column [column ...]
extend adds a column to an existing multirow
template::multirow append datasourcename value [value ...]
appends the row to an existing multirow.
template::multirow pop datasourcename
pops a row off an existing multirow, returning a list of the rows keys gand values
template::multirow size datasourcename
returns the rowcount
template::multirow columns datasourcename
returns the columns in the datasource
template::multirow get datasourcename rownum [column]
returns the row of data (or the particular row/column if column is provided)
template::multirow set datasourcename rownum column value
set an element value
template::multirow foreach datasource code
evaluate code block for each row (like db_foreach)
template::multirow upvar datasource [new_name]
upvar the multirow, aliasing to new_name if provided
template::multirow unset datasource
unset multirow
template::multirow sort datasource -lsort-switch col1 col2
Sort the multirow by the column(s) specified. The value sorted by will be the values of the columns specified, separated by the space character. Any switches specified before the columns will be passed directly to the lsort command.
template::multirow exists datasource
Return 1 if the multirow datasource exists, 0 if it doesn't.

Switches:
-ulevel
(defaults to "1") (optional)
Used in conjunction with the "local" parameter to specify how many levels up the multirow variable resides.
-local
(boolean) (optional)
If set, the multirow will be looked for in the scope the number of levels up given by ulevel (normally the caller's scope), instead of the [template::adp_level] scope, which is the default.
-unclobber
(boolean) (optional)
This only applies to the 'foreach' command. If set, will cause the proc to not overwrite local variables. Actually, what happens is that the local variables will be overwritten, so you can access them within the code block. However, if you specify -unclobber, we will revert them to their original state after execution of this proc.
Parameters:
command - Multirow datasource operation: create, extend, append, pop, size, get, set, foreach, upvar
name - Name of the multirow datasource
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_db__transaction_bug_3440 db__transaction_bug_3440 (test acs-tcl) template::multirow template::multirow test_db__transaction_bug_3440->template::multirow test_templates_and_scripts templates_and_scripts (test acs-templating) test_templates_and_scripts->template::multirow test_util_user_messages util_user_messages (test acs-tcl) test_util_user_messages->template::multirow template::adp_level template::adp_level (public) template::multirow->template::adp_level template::util::is_nil template::util::is_nil (public) template::multirow->template::util::is_nil acs_user::demote_user acs_user::demote_user (public) acs_user::demote_user->template::multirow ad_context_bar_multirow ad_context_bar_multirow (public) ad_context_bar_multirow->template::multirow ad_dimensional ad_dimensional (public) ad_dimensional->template::multirow ad_page_contract ad_page_contract (public) ad_page_contract->template::multirow apm_build_repository apm_build_repository (private) apm_build_repository->template::multirow

Testcases:
db__transaction_bug_3440, util_user_messages, templates_and_scripts

template::query (public)

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

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 - Standard db_api query name
result_name - Tcl variable name when doing an uplevel to set the returned result
type - The query type
sql - 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):
%3 packages/bookmarks/www/bookmark-edit.tcl packages/bookmarks/ www/bookmark-edit.tcl template::query template::query packages/bookmarks/www/bookmark-edit.tcl->template::query packages/bookmarks/www/bookmark-view.tcl packages/bookmarks/ www/bookmark-view.tcl packages/bookmarks/www/bookmark-view.tcl->template::query db_qd_get_fullname db_qd_get_fullname (public) template::query->db_qd_get_fullname db_with_handle db_with_handle (public) template::query->db_with_handle template::get_cached_result template::get_cached_result (private) template::query->template::get_cached_result template::set_cached_result template::set_cached_result (private) template::query->template::set_cached_result template::util::get_opts template::util::get_opts (public) template::query->template::util::get_opts

Testcases:
No testcase defined.

template::query::dml (private)

 template::query::dml statement_name db name sql

Process an SQL statement that is not a query; perhaps update or insert

Parameters:
statement_name - Standard db_api statement name used to hook into query dispatcher
db - Database handle
name - Tcl variable name to use when setting the result
sql - Query to use when processing this command

Partial Call Graph (max 5 caller/called nodes):
%3 db_exec db_exec (public) template::query::dml template::query::dml template::query::dml->db_exec

Testcases:
No testcase defined.

template::query::flush_cache (private)

 template::query::flush_cache cache_match

Flush the cached queries where the query name matches the specified string match

Parameters:
cache_match - Name of query to match for cache flushing

Partial Call Graph (max 5 caller/called nodes):
%3 acs::clusterwide acs::clusterwide template::query::flush_cache template::query::flush_cache template::query::flush_cache->acs::clusterwide

Testcases:
No testcase defined.

template::query::multilist (private)

 template::query::multilist statement_name db result_name sql

Process a multilist query.

Parameters:
statement_name - Standard db_api statement name used to hook into query dispatcher
db - Database handle
result_name - Tcl variable name to use when setting the result
sql - Query to use when processing this command

Partial Call Graph (max 5 caller/called nodes):
%3 db_exec db_exec (public) template::query::multilist template::query::multilist template::query::multilist->db_exec

Testcases:
No testcase defined.

template::query::multirow (private)

 template::query::multirow statement_name db result_name sql

Process a multirow query. Use an array for each row in the result. Arrays are named name0, name1, name2 etc. The variable name.rowcount is also defined for checking and iteration.

Parameters:
statement_name - Standard db_api statement name used to hook into query dispatcher
db - Database handle
result_name - Tcl variable name to use when setting the result
sql - Query to use when processing this command
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 db_exec db_exec (public) template::query::multirow template::query::multirow template::query::multirow->db_exec

Testcases:
No testcase defined.

template::query::nestedlist (private)

 template::query::nestedlist statement_name db result_name sql

Creates a data source where the values for each row are returned as a list. Rows are grouped according to the column values specified in the -groupby option See template::util::lnest for more details.

Parameters:
statement_name - Standard db_api statement name used to hook into query dispatcher
db - Database handle
result_name - Tcl variable name to use when setting the result
sql - Query to use when processing this command

Partial Call Graph (max 5 caller/called nodes):
%3 db_exec db_exec (public) template::util::lnest template::util::lnest (public) template::query::nestedlist template::query::nestedlist template::query::nestedlist->db_exec template::query::nestedlist->template::util::lnest

Testcases:
No testcase defined.

template::query::onelist (private)

 template::query::onelist statement_name db result_name sql

Process a onelist query.

Parameters:
statement_name - Standard db_api statement name used to hook into query dispatcher
db - Database handle
result_name - Tcl variable name to use when setting the result
sql - Query to use when processing this command

Partial Call Graph (max 5 caller/called nodes):
%3 db_exec db_exec (public) template::query::onelist template::query::onelist template::query::onelist->db_exec

Testcases:
No testcase defined.

template::query::onerow (private)

 template::query::onerow statement_name db result_name sql

Process a onerow query. Use a single array to store the results.

Parameters:
statement_name - Standard db_api statement name used to hook into query dispatcher
db - Database handle
result_name - Tcl variable name to use when setting the result
sql - Query to use when processing this command

Partial Call Graph (max 5 caller/called nodes):
%3 db_exec db_exec (public) template::query::onerow template::query::onerow template::query::onerow->db_exec

Testcases:
No testcase defined.

template::query::onevalue (private)

 template::query::onevalue statement_name db result_name sql

Process a onevalue query. Use a single array to store the results.

Parameters:
statement_name - Standard db_api statement name used to hook into query dispatcher
db - Database handle
result_name - Tcl variable name to use when setting the result
sql - Query to use when processing this command

Partial Call Graph (max 5 caller/called nodes):
%3 db_exec db_exec (public) template::query::onevalue template::query::onevalue template::query::onevalue->db_exec

Testcases:
No testcase defined.

template::set_cached_result (private)

 template::set_cached_result

Places a query result in the appropriate cache.

Partial Call Graph (max 5 caller/called nodes):
%3 template::query template::query (public) template::set_cached_result template::set_cached_result template::query->template::set_cached_result

Testcases:
No testcase defined.

template::url (public)

 template::url command [ args... ]

Maintains an ns_set of parameters that can be bulk converted to URL parameters. It is not clear if this API makes a lot of sense, many alternatives exist to export parameters in various forms...

Parameters:
command - one of 'set_param *name* *value*' (set a parameter), 'get_param *name* *default*' (get a parameter value), or 'get_query' (export all parameters as URL query).
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 template::filter template::filter (public) template::url template::url template::filter->template::url

Testcases:
No testcase defined.
[ show source ]