callback (public)

 callback [ -catch ] [ -impl impl ] callback [ args... ]

Defined in packages/acs-bootstrap-installer/tcl/00-proc-procs.tcl

Invoke the registered callback implementations for the given callback. The callbacks terminate on error unless -catch is provided. The value returned by the callback function is determined by the return codes from the callback implementations.

The callbacks are executed one level below the calling function so passing arrays to a callback can be done normally via

upvar arrayname $arrayref

The return codes returned from the implementation are treated as follows:

return -code ok or "return"
With a plain return, a non-empty return value will be lappended to the list of returns from the callback function
return -code error or "error"
errors will simply propagate (and no value returned) unless -catch is specified in which case the callback processing will continue but no value will be appended to the return list for the implementation which returned an error.
return -code return
Takes the return value if the implementation returning -code return and returns a one element list with that return value. Note that this means if you have code which returns return -code return {x y}, you will get {{x y}} as the return value from the callback. This is done in order to unambiguously distinguish a pair of callbacks returning x and y respectively from this single callback.
return -code break
return the current list of returned values including this implementations return value if non-empty
return -code continue
Continue processing, ignore the return value from this implementation

Switches:
-catch (boolean) (optional)
if catch specified errors in the callback will be caught, tracebacks logged as errors to the server log, but other callbacks called and the list of returns still returned. If not given an error simply is passed further on.
-impl (defaults to "*") (optional)
invoke a specific implementation rather than all implementations of the given callback
Parameters:
callback - the callback name without leading or trailing ::
Returns:
list of the returns from each callback that does a normal (non-empty) return

See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_proc_create_callback ad_proc_create_callback (test acs-tcl) callback callback test_ad_proc_create_callback->callback test_ad_proc_fire_callback ad_proc_fire_callback (test acs-tcl) test_ad_proc_fire_callback->callback ad_print_stack_trace ad_print_stack_trace (public) callback->ad_print_stack_trace acs_mail_lite::inbound_queue_pull acs_mail_lite::inbound_queue_pull (private) acs_mail_lite::inbound_queue_pull->callback acs_mail_lite::load_mails acs_mail_lite::load_mails (private) acs_mail_lite::load_mails->callback acs_mail_lite::send_immediately acs_mail_lite::send_immediately (private) acs_mail_lite::send_immediately->callback ad_proc ad_proc (public) ad_proc->callback calendar::item::delete calendar::item::delete (public) calendar::item::delete->callback

Testcases:
ad_proc_create_callback, ad_proc_fire_callback
Source code:
    if {$callback eq ""} {
        error "callback: no callback name given"
    }
    # see that the contract exists and call the contract for
    # arg validation -- ::callback::${callback}::contract is an
    # empty function that only runs the ad_proc generated arg parser.

    if {[info commands ::callback::${callback}::contract] eq ""} {
        error "Undefined callback $callback"
    }
    ::callback::${callback}::contract {*}$args

    set returns {}

    set base ::callback::${callback}::impl
    foreach procname [lsort [info commands ${base}::$impl]] {
        set c [catch {::uplevel 1 [::list $procname {*}$args]} ret]
        switch -exact $c {
            0 { # code ok
                if { $ret ne "" } {
                    lappend returns $ret
                }
            }
            1 { # code error - either rethrow the current error or log
                if {$catch_p} {
                    ns_log Error "callback $callback error invoking $procname: $ret\n[ad_print_stack_trace]\n"
                } else {
                    return -code $c -errorcode $::errorCode -errorinfo $::errorInfo $ret
                }
            }
            2 { # code return -- end processing and return what we got back.
                return [list $ret]
            }
            3 { # code break -- terminate return current list of results.
                if { $ret ne "" } {
                    lappend returns $ret
                }
                return $returns
            }
            4 { # code continue -- just skip this one
            }
            default {
                error "Callback return code unknown: $c"
            }
        }
    }

    if {$impl ne "*" && ![info exists c] && !$catch_p} {
        error "callback $callback implementation $impl does not exist"
    }

    return $returns
XQL Not present:
Generic, PostgreSQL, Oracle
[ hide source ] | [ make this the default ]
Show another procedure: