$Web Done: Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
mNo edit summary |
||
| Line 2: | Line 2: | ||
<span class="pageSubtitle"><section begin="desc" />Send Web response<section end="desc" /></span> | <span class="pageSubtitle"><section begin="desc" />Send Web response<section end="desc" /></span> | ||
$Web_Done signals completion of a request. | |||
This callable $function (see [[Calling_Sirius_Mods_$functions|Calling Sirius Mods $functions]]) accepts two optional arguments and returns a numeric result code. | |||
==Syntax== | ==Syntax== | ||
<p class="syntax"><section begin="syntax" /> % | <p class="syntax"><section begin="syntax" /> %rc = $Web_Done( status_code, message ) | ||
<section end="syntax" /></p> | <section end="syntax" /></p> | ||
===Syntax terms=== | |||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th> | <tr><th>%rc</th> | ||
<td> | <td>A numeric variable containing return codes: | ||
<table> | |||
<tr><th>0</th> | <tr><th>0</th> | ||
<td>Completed successfully</td></tr> | <td>Completed successfully</td></tr> | ||
<tr><th>-1</th> | <tr><th>-1</th> | ||
<td>Not a web thread</td></tr> | <td>Not a web thread</td></tr> | ||
</table></td></tr> | |||
<tr><th>status_code</th> | |||
<td>Used in many cases for automatic browser error or exception handling, these codes are summarized [[#Status codes|below]].</td></tr> | |||
<tr><th>message</th> | |||
<td>Further elucidation of the error. In some cases, displayed verbatim to the browser's user. </td></tr> | |||
</table> | </table> | ||
Status codes and their associated messages are standardized for most Web Servers. The standards are available for browsing in Chapter 9 of the | ===Status codes=== | ||
Status codes and their associated messages are standardized for most Web Servers. The standards are available for browsing in Chapter 9 of the HTTP [http://www.w3.org/pub/WWW/Protocols/HTTP/1.0/spec.html working draft]. | |||
The standard codes are: | The standard codes are: | ||
| Line 70: | Line 63: | ||
</td></tr></table> | </td></tr></table> | ||
==Usage notes== | |||
<ul> | |||
<li>Invoking $Web_Done closes the client connection, optionally sending the status code and message text to the user. Once $Web_Done is invoked, the thread may continue processing but no more calls to $Web* functions are allowed, and nothing further may be sent to the client. | |||
The connection to the client is also broken by a ''Model 204'' LOGOFF or any return to command level. These are perfectly valid ways of terminating requests. The function of $Web_Done is to send the status code and error message and terminate the connection; hence no further information will be sent to the client. | |||
<li>Of potential value when monitoring your application, the Sirius statistic JWEBERRS reports the number of times that ''[[Janus Web Server]]'' returned one of the 4xx status codes. Also, the JSCREENS statistic counts the number of times ''Janus Web Server'' incremented the SCREENS statistic. These statistics are available as of ''Sirius Mods'' version 7.6, and they are retrievable or viewable with $SyStat or ''[[SirMon]]''. | |||
</ul> | |||
==Examples== | |||
Use $Web_Done in error routines and to sever client connections with custom messages: | Use $Web_Done in error routines and to sever client connections with custom messages: | ||
<p class="code"> SECURE: IN AUTHS FD UID = %USER | <p class="code">SECURE: IN AUTHS FD UID = %USER | ||
END FIND | |||
CT_SEC: COUNT RECORDS IN SECURE | |||
IF NOT COUNT IN CT_SEC THEN | |||
%X = $Web_Done('403','Forbidden') | |||
STOP | |||
END IF | |||
</p> | </p> | ||
[[Category:Janus Web Server $functions|$Web_Done]] | [[Category:Janus Web Server $functions|$Web_Done]] | ||
Revision as of 16:37, 6 June 2012
<section begin="desc" />Send Web response<section end="desc" />
$Web_Done signals completion of a request. This callable $function (see Calling Sirius Mods $functions) accepts two optional arguments and returns a numeric result code.
Syntax
<section begin="syntax" /> %rc = $Web_Done( status_code, message ) <section end="syntax" />
Syntax terms
| %rc | A numeric variable containing return codes:
| ||||
|---|---|---|---|---|---|
| status_code | Used in many cases for automatic browser error or exception handling, these codes are summarized below. | ||||
| message | Further elucidation of the error. In some cases, displayed verbatim to the browser's user. |
Status codes
Status codes and their associated messages are standardized for most Web Servers. The standards are available for browsing in Chapter 9 of the HTTP working draft.
The standard codes are:
| 200 | OK |
|---|---|
| 201 | Created |
| 202 | Accepted |
| 204 | No Content |
| 301 | Moved Permanently |
| 302 | Moved Temporarily |
| 304 | Not Modified |
| 400 | Bad Request |
| 401 | Not Authorized (logon required) |
| 403 | Forbidden |
| 404 | Not Found |
| 500 | Internal Server Error |
| 501 | Not Implemented |
| 502 | Bad Gateway |
| 503 | Service Unavailable |
Usage notes
- Invoking $Web_Done closes the client connection, optionally sending the status code and message text to the user. Once $Web_Done is invoked, the thread may continue processing but no more calls to $Web* functions are allowed, and nothing further may be sent to the client. The connection to the client is also broken by a Model 204 LOGOFF or any return to command level. These are perfectly valid ways of terminating requests. The function of $Web_Done is to send the status code and error message and terminate the connection; hence no further information will be sent to the client.
- Of potential value when monitoring your application, the Sirius statistic JWEBERRS reports the number of times that Janus Web Server returned one of the 4xx status codes. Also, the JSCREENS statistic counts the number of times Janus Web Server incremented the SCREENS statistic. These statistics are available as of Sirius Mods version 7.6, and they are retrievable or viewable with $SyStat or SirMon.
Examples
Use $Web_Done in error routines and to sever client connections with custom messages:
SECURE: IN AUTHS FD UID = %USER END FIND CT_SEC: COUNT RECORDS IN SECURE IF NOT COUNT IN CT_SEC THEN %X = $Web_Done('403','Forbidden') STOP END IF