ns_proc(3)

NAME

ns_register_proc, ns_unregister_proc -commands

SYNOPSIS

Register a procedure for a method/URL combination
ns_register_proc ?-noinherit? method URL myproc ?args?
ns_unregister_proc ?-noinherit? method URL

DESCRIPTION

ns_register_proc

ns_register_proc registers the procname to handle

the specified method/URL combination. When the server gets a

matching request, it calls procname with the connection id and

any arguments specified here.

If -noinherit is specified, the requested URL must

match the specified URL exactly. For example, if the URL speci

fied with ns_register_proc is /foo/bar, procname will not be

called unless the requested URL is exactly /foo/bar.

If -noinherit is not specified, the requested URL

can match the specified URL or any URL below it. For example, if

the URL specified with ns_register_proc is /foo/bar, procname

will be called for /foo/bar, /foo/bar/hmm, and any other URL be

low /foo/bar, provided there is not already another procedure

registered for that exact URL or for an URL with a closer match.

Note that you must use a glob-style matching char

acter if you want inheritance for file names. For example, if you

want /foo/bar to match /foo/bar.html, you must use: ns_regis

ter_proc /foo/bar*

You can register two procedures for any given

method/URL combination by calling ns_register_proc once with the

-noinherit flag set and once without it. Only one of the proce

dures will be called for any given request, depending on whether

the URL was an exact match or not. For example:

ns_register_proc -noinherit GET /foo/bar

Aproc
ns_register_proc GET /foo/bar Bproc
ns_register_proc GET /foo/bar/hmm Cproc

Aproc will be called when the requested URL is ex

actly /foo/bar. Bproc will be called when the requested URL is

below /foo/bar, provided there is not already another procedure

registered to be called for that exact URL or for an URL with a

closer match. Cproc (not Bproc) will be called when the requested

URL is equal to or below /foo/bar/hmm. Syntax for the registered

procedure The conn (connection) argument is optional for proce

dures registered by ns_register_proc if the procedure has 0 or 1

arguments (not including conn). The following examples show the

variations that can be used in this case:

ns_register_proc GET /noargs noargs
ns_register_proc GET /context context fnord
ns_register_proc GET /conncontext conncon

text greeble

proc noargs { } {

ns_returnnotice 200 "noargs"

} ;# noargs

proc context { context } {

ns_returnnotice 200 "context is $con

text"

} ;# context

proc conncontext { conn context } {

ns_returnnotice 200 "conncontext is

$context"

} ;# conncontext

The conn (connection) argument is required for pro

cedures registered by ns_register_proc if the procedure has 2 or

more arguments (not including conn). The conn argument will be

filled automatically with the connection information. The first

argument following conn will always take the value supplied by

ns_register_proc, if there is one, or an empty value. All other

arguments must supply a default value. The following examples

show the variations that can be used in this case:

ns_register_proc GET /twoargs twoargs fnord
ns_register_proc GET /threeargs threeargs

fnord fjord

proc twoargs { conn context { greeble bork }

} {

# Do stuff...

}

proc threeargs { conn context {greeble bork

} { hoover quark } {

# Do stuff...

}

When a GET of /twoargs is requested, the conn argu

ment will be filled automatically, the context argument will be

assigned "fnord" and the greeble argument will be assigned the

default value "bork".

When a GET of /threeargs is requested, the conn ar

gument will be filled automatically, the context argument will be

assigned "fnord" and the greeble argument will be assigned

"fjord", and the hoover argument will be assigned the default

value "quark".

ns_unregister_proc

Unregisters any Tcl or C functions registered with

this method/URL combination and with the same inheritance set

ting. That is, if the -noinherit flag is specified in ns_unregis

ter_proc, the function registered with the -noinherit flag in

ns_register_proc (or the NS_OP_NOINHERIT flag in Ns_RegisterRe

quest) will be unregistered. If -noinherit is omitted, the func

tion registered without the -noinherit flag (or the NS_OP_NOIN

HERIT flag) will be unregistered.

SEE ALSO

ns_adp_include(1), ns_adp_parse(n)

KEYWORDS

register proc url method

AOLserver 4.0

ns_proc(3)