NAME

       ns_register_adp,  ns_register_proc,  ns_unregister_adp, ns_unregister_proc - Facilities to
       manage mappings for HTTP requests to Tcl procedures 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.  Specialized 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  extension.   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_unregister_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 support 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_register_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 variable 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 procedure  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