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

AOLserver                                              4.5                          ns_register_proc(3aolserver)