Ns register trace

Man page: http://aolserver.com/man/4.0/tcl/ns_filter.html

---

NAME

ns_register_trace - Register a void trace filter for a method/URL combination

SYNOPSIS

ns_register_trace method urlPattern procName ?context?

DESCRIPTION

ns_register_trace registers a Tcl procedure as a trace for the specified method/URL combination. After the server handles the request for the specified method on an URL that matches the URLpattern, IF no error occurred, it calls the trace procedure with the connection id and any arguments (args) specified. The URLpattern can contain standard string-matching characters. For example, these are valid URLpatterns:

/employees/*.tcl /accounts/*/out 

The procedure to be registered can recieve optional arguments specified in context. Unlike filters registered with ns_register_filter, traces registered with this command do not get passed the usual why (aka when) argument, however, the why argument must still be present and must be optional (unless your procedure takes 3 or more arguments), i.e. your procedure call signature can be one of these variants:

ns_register_trace GET /* mytrace "param1 param2"
proc mytrace {} ;#will not receive any arguments
proc mytrace {args) ;# will not receive any arguments!
proc mytrace {context args} ;# will receive the context or "" (if context is a list of arguments, the first element will go into context and subsequent elements will be elements of args)
proc mytrace {conn context args} ;# same as above only first argument will contain the connid
proc mytrace {context {why "void"}} ;# will receive the context or "", which should not be a list of arguments
proc mytrace {conn context {why "void"}} ;# same as above only first argument will contain the connid
proc mytrace {conn arg1 arg2} ;# context must be a list of exactly two arguments which will be received in arg1 and arg2 respectively, your first parameter must be the connid
proc mytrace {conn arg1 arg2 arg3} ;# context must be a list of exactly three arguments which will be received in arg1, arg2 and arg3 respectively, your first parameter must be the connid
...

The server detects the number of arguments in your procedure only the first time it is invoked as a filter/trace. Therefore if you change the number of arguments after this, this change will not be recognized until after a server restart.

Note ns_register_trace is similar to ns_register_proc except that the pattern-matching for the URL is performed differently. With ns_register_proc, the specified URL is used to match that URL and any URL below it in the hierarchy. Wildcards such as "*" are meaningful for ns_register_proc only for the final part of the URL, such as /scripts/*.tcl. With ns_register_trace, the URLpattern is used to match URLs as a string with standard string-matching characters. ns_register_proc results in a single match, whereas multiple ns_register_trace's can be matched and will be called.

This command differs from ns_register_filter trace in that traces registered with this command only run if the request (or a trace filter registered with ns_register_filter trace) did not result in an error (having a trace filter registered with ns_register_filter trace return anything other than "filter_ok", "filter_return", or "filter_break" is equivalent to resulting in an error).

In addition, the return value (including a thrown error) of any trace registered with this command is ignored, hence the name void trace filter. Because the return value is ignored it is not possible for a trace registered with this command to prevent execution of the next trace or the subsequent C-level ServerTraces (i.e. access logging).

SEE ALSO

ns_register_filter