ns_register_proc(3aolserver)				    AOLserver Built-In Commands 			      ns_register_proc(3aolserver)

__________________________________________________________________________________________________________________________________________________

NAME

       ns_register_adp,  ns_register_proc,  ns_unregister_adp,	ns_unregister_proc - Facilities to manage mappings for HTTP requests to Tcl proce-
       dures or ADP files

SYNOPSIS

       ns_register_adp ?-noinherit? method url file
       ns_register_proc ?-noinherit? method url proc ?arg?
       ns_unregister_adp ?-noinherit? method url
       ns_unregister_proc ?-noinherit? method url
_________________________________________________________________

DESCRIPTION

       These commands manage mappings of HTTP request to Tcl procedures or ADP files.  The server will invoke the given procedure or ADP file when
       the corresponding method/url combination is requested.

       The method is normally one of GET or POST although there is no restriction as internally method is always treated simply as a string.  Spe-
       cialized applications, for example, a WebDav file server, could register additional methods such as PUT, DELETE, or BROWSE.

       The url parameter specifies the trailing, pathname portion of an url, for example, /myapp/search.  Requests for the specified  url  or  any
       url's  with  additional	path  elements	which do not have more specific mappings will be handled by the given procedure or ADP file.  This
       behavior can be changed with the optional -noinherit flag in which case only exact match url's will be handled.

       In addition, for the final pathname component, a "glob-style" pattern may also be specified to further restrict the  match.   For  example,
       /myapp/*.adp  would handle requests for all url which start with /myapp and have a final pathname component which ends with the .adp exten-
       sion.  Note that the method cannot be specified as a glob pattern, i.e., attempting to map "*" will map the single character string "*"	as
       the method, it will not map all possible methods.

       Calls to ns_register_proc and ns_register_adp are normally placed in server initialization scripts.  The ns_unregister_proc and ns_unregis-
       ter_adp commands are rarely used, normally only in the context of development or debugging.

       ns_register_adp ?-noinherit? method url file
	      This command maps the given method/url combination to a specific ADP file.  The file argument must be an	absolute  pathname  and  a
	      regular file.  When the server receives a matching request, it will allocate a Tcl interpreter and invoke the ns_adp_include command
	      with the given file, returning the results of the output buffer to the client when the command returns.

	      Note it is also possible to provide mappings for ADP files in the config file as well although those mappings are intended  to  sup-
	      port  mixing  of ADP and static files in the server's basic page root.  Using ns_register_adp can provide more general mappings, not
	      requiring actual ADP files to exist at the corresponding location in the filesystem.

       ns_register_proc ?-noinherit? method url proc ?arg?
	      This command maps the given method/url combination to a Tcl procedure.  When the server receives a matching request, it allocates  a
	      Tcl  interpreter	and  calls  Tcl_Eval  with a script constructed of the procedure with zero, one, or two arguments depending on the
	      arguments expected for the procedure.  If the procedure accepts no arguments, none are passed and the  arg  parameter  to  ns_regis-
	      ter_proc, if given, is ignored.  If it takes one argument, the procedure is passed the optional arg parameter or a null string if no
	      argument was given.  If the procedure accepts two arguments, the first argument will be the "connection id" followed by the argument
	      as  described  for  the  case  of  one  argument.  The connection id is a small string of the form "cns#" where # is a monotonically
	      increasing integer value which will eventually wrap after the server has been running for a long time.  This id is also returned via
	      the  the ns_conn id command.  This connection id is for information purposes only and is is otherwise useless and not required to be
	      passed to any other AOLserver Tcl command.  See the EXAMPLES section for details on how various arguments are  handled  for  request
	      procedures.

       ns_unregister_adp ?-noinherit? method url

       ns_unregister_proc ?-noinherit? method url
	      These  commands are identical and can be used to remove any mapping for the given method/url.  Note that no check is made to confirm
	      the given mapping exists or was in fact a Tcl procedure, ADP file, or some other C-level mapping created with the Ns_RegisterRequest
	      routine.	The optional -noinherit flag, if specified, requests removal of mappings previously made with the -noinherit flag with the
	      commands above or via the NS_OP_NOINHERIT bit set in a call to the Ns_RegisterRequest routine.

EXAMPLES

       The following example demonstrates the use of the -noinherit flag.  Assume the following startup initializations code:

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

       In this case, Aproc will be called when the requested URL is exactly /foo/bar while Bproc will be called when the requested URL is anything
       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.

       The following example demonstrates the multiple forms of which a Tcl procedure can be defined:

	      ns_register_proc GET /zeroargs 0args myarg
	      ns_register_proc GET /onearg 1arg myarg
	      ns_register_proc GET /twoargs 2args myarg
	      ns_register_proc GET /twoargs 2args myarg

	      proc 0args {} {
		  ns_returnnotice 200 "no args"
	      } ;# noargs

	      proc 1arg {arg} {
		  ns_returnnotice 200 "arg: $arg"
	      } ;# context

	      proc 2args {conn arg} {
		  ns_returnnotice 200 "connid: $conn, arg: $arg"
	      } ;# conncontext
       When a request for the /twoargs URL is received, the 2args procedure will be called with the value of the connection id as the  conn  vari-
       able and "myarg" as the value of the arg variable.

       When the server receives a request for /onearg, the server will invoke the 1arg procedure with just "myarg" as the value for the arg proce-
       dure variable.  The connection id, if needed, can be obtained with ns_conn id.

       Finally, when the server receives a request for /zeroargs, the 0args procedure will be called with no options.  The "myarg" value passed to
       ns_register_proc is ignored and the connection id, if needed, can be obtained with ns_conn id.

SEE ALSO

       ns_adp(n), Ns_RegisterRequest(3), Ns_UrlSpecificGet(n), Ns_UrlSpecificSet(n)

KEYWORDS

       request callback, connection

AOLserver								4.5					      ns_register_proc(3aolserver)