$Web Realm

<section begin="desc" />Set web "realm" for "Unauthorized" response<section end="desc" />

$Web_Realm allows the setting of the web "realm" before sending an "Unauthorized" response to the browser.

$Web_Realm is a callable $function, and it takes a single argument and returns a number.

Syntax

<section begin="syntax" />%rc = $Web_Realm( realm_name ) <section end="syntax" />

Syntax terms

%rc	A numeric variable to contain a return code.
realm_name	Specifies the name of the realm to which a userid and password combination applies. This is a required parameter.

Usage notes

• Web realms can serve several purposes:
  • By having multiple realms for a single host, different URLs could be made available to different sets of users.
  • The realm could be used to send an arbitrary message to the browser to appear in a login pop-up window.
  • Realms could be dynamically generated to prevent browsers from caching userids and passwords at public workstations.
• The realm sent by $Web_Realm is not sent to a browser unless a status of 401 ("Unauthorized") is sent to the browser. This means that a $Web_Realm call is meaningless unless followed by a $Web_Done with a status code of 401, for example:

  %rc = $Web_Realm('Toxico Database Systems') %rc = $Web_Done(401, 'Unauthorized')

• If all the $Web_Realm calls for a port in an Online are to have the same realm, it probably makes more sense to set the realm with the WEBREALM parameter on the JANUS DEFINE command for the port.
• While $Web_Realm can be used in any code, its most common use would be in exception rules, especially those associated with logon processing such as LOGONERR and NEWPASSWORD.