returnstatus-cmds - Return a complete HTTP status message
These commands return a complete response to the client using a variety of different HTTP status codes. On contrary to the lower level commands like ns_return these commands are designed to ease consistent behavior in common success, redirect or error situations. Like with ns_return all queued headers, such as those set by ns_setcookie (see ns_cookie) or via ns_conn outputheaders and ns_set put, are added to the default headers and sent in the response.
These commands return 0 (zero) if the response was successfully sent to the client and 1 if the write to the connection failed. They will raise an error if no connection is available, e.g. they are called from a non-connection thread or the response has already been sent and the connection closed.
After the command returns the connection is returned to the driver thread to be closed or monitored for keep-alive. The calling connection thread can then continue to execute code, e.g. to cleanup resources or for logging.
Custom error pages may be specified in the server configuration file to override the default HTML message which is returned, for those commands which return one.
NOTE: The script does not end at the time these commands are invoked. When used in an ADP page, ns_adp_abort or ns_adp_return should be called to end script processing after e.g. ns_returnredirect.
Return a response with status code 200, OK. No body content is sent.
Return a response with status code 301, Moved. A Location header will be set with the given url.
Use this response to signal that the resource identified by the requested URL has permanently moved to a new location. The client should request the new URL instead of the old one in the future.
Return a response with status code 302, Found. The Location header will be set to the url if given. For non-fully qualified target addresses, the URL is completed with the location when configured via ns_locationproc.
Use this response to signal that the resource identified by the requested URL has temporarily moved to a new location. The client should continue to request the old URL.
Return a response with status code 400, Bad Request using the given reason in the HTML message.
Use this response to signal that the client sent a malformed request and should not try again without modifications.
Return a response with status code 401, Access Denied. A WWW-Authenticate header will be set using the realm specified in the configuration file option ns/server:realm.
Use this response to signal that the user is not authorized to access the URL, and to trigger HTTP basic authorization. The client may present a pop-up window for the user to enter their username and password.
NB: The username and password will be sent in plain text.
Return a response with status code 403, Forbidden.
Use this response to signal that the authentication information the client supplied are insufficient to grant them access to the requested URL.
Return a response with status code 404, Not Found.
Use this response to signal that the content the client requested could not be located given the URL that was requested.
Return a response with status code 503, Unavailable.
Use this response to signal that the server is too busy to deliver the requested resource or is undergoing maintenance.
Return a response with the given status code and the error message wrapped in HTML.
Use this command to return an HTTP status response to the client which is not covered by the above commands, or to customize the HTML message.
Return a response with the given status code and an HTML message with the given title and message.
Use this command to return an arbitrary response to the client. Some HTTP responses are expected not to return body content. Check RFC 2616 for details.
NB: You should be careful what you put in the title and message. It may be tempting to use data which the client has sent you such as a form variable, but it may not be what you expect.
Note: The script does not end at the time this command is invoked. ns_adp_abort or ]cmd ns_adp_return] should be called to end script processing after ns_returnforbidden.
The body of the response which is returned for a variety of status codes can be customized by registering a new resource which should be returned in its place. The new resource may be a static, Tcl or ADP page, or a registered procedure or ADP. These redirects are used for providing customized (templated) error pages.
ns_section "ns/server/server1/redirects" {
ns_param 404 /notfound.adp
ns_param 503 /busy.html
}
The realm used for HTTP Basic authentication is set server-wide:
ns_section "ns/server" {
ns_param realm "Example"
}
Use a custom error message to notify users when the hamsters which turn the wheels that run the server are on lunch break:
ns_register_proc GET /service {
set hour [clock format [clock seconds] -format %H]
if {$hour >= 12 && $hour <= 13} {
ns_returnerror 503 "Gone for lunch. Back at 2pm."
return
}
ns_returnok
}