Janus Web Server $functions

The Janus Web Server $functions, prefixed with $Web_, are used to extend User Language programs so that they can present "dynamic" data-based web pages, can identify information about the client, can process "cookies" for persistent client data storage, and can process client form input, among other things.

Except where noted, these $functions can only be called by User Language programs running on a Janus Web Server thread; if called by a user who is not running as a Janus Web Server thread, the results of the $function will be meaningless. See "Janus Web Server application coding considerations" for instructions on how to debug a Janus Web Server application.

A grouping of the $functions by their purpose is presented in "Janus Web Server $function categories".; Other pages (by function name) give a complete explanation of each of the Janus Web Server $functions, including a brief description, expected arguments, values returned, syntax diagram, and examples.

Janus Web Server $function categories

The Janus Web Server $functions can be categorized as shown in these subsections.

Output processing functions

`$Web_Done`	Break the connection with a return message.
`$Web_Flush`	Clear the contents of the client buffer.
`$Web_Form_Done`	Sends the current output page if request was a GET or redirects back to itself if request was a POST.
`$Web_Off`	Suspend adding terminal output to the client buffer.
`$Web_On`	Resume adding terminal output to the client buffer.
`$Web_Output_Content`	Retrieve current output buffer contents.
`$Web_Proc_Send` (or `$Web_ProcSend`)	Add contents of a procedure to the client buffer.
`$Web_Put_Binary` (or `$Web_Put_Bin`)	Add binary string to the client buffer.
`$Web_Put_Text`	Add text string to the client buffer.
`$Web_Sub`	Sets a delimiter for symbolic substitution during $Web_ProcSend or the SEND subcommand of the ON command.
`$Web_Type`	Set the content type.
Global drop-down lists	There is a group of $functions for creating a drop-down list in the buffer; this group is summarized in "Drop-down lists: HTML <select>".

Drop-down lists: HTML <select>

One useful construct on HTML forms is called the "drop-down" list; these are provided by the HTML select element. This provides the browser user with a list of items, allowing the user to click on the item or items of choice; each of these items is an HTML option element (thus a drop-down list may also be called a "select options list").

Often, the option list comes from a metadata file or some other source in your database that changes very infrequently. Because they come from a database, you don't want to hand-code them in a program. And because they change infrequently, you don't want to incur the overhead of deriving them from the database for each web request.

Janus Web Server helps you create drop-down lists using the "$Web_Sel*" functions (summarized below). The $Web_Sel* functions offer:

Saved global select elements

The $Web_Save_Sel function saves a select option list of values and descriptions; this saved global element can be used to build a select element as part of the web response output. Global select elements are identified by a character string name, and they are shared by all users in a Model 204 Online.

Access to the global select elements is very fast, but they are not optimized for updating. If there are frequent changes to the information deriving a select option list, some technique other than global select elements should be used.

Specification of selected attribute

The selected attribute of the option elements is specified at the time that a select element is built. It can be specified in either of these ways:

As a character string that is equal to the value of a select option.
As the name of a request parameter that has the selected options' values — providing easy support for "multiple" select elements, and saving you the code to extract the parameter values when building the option list.

Validation of values

A set of CHECK $functions is provided to ensure that the value(s) specifying the selected options is indeed among the option values.

Delimited string select elements

As an alternative to the global select elements, you can specify the values and descriptions of a select options list completely at runtime. This gives you some coding convenience, and it gives you a common paradigm for select options, even in those cases that are not appropriate for global select elements.

User-supplied select

There are several attributes that you may want to supply on the <select> tag. Rather than introducing some arguments to the $Web_Sel* functions for these attributes, you simply provide the <select> tag, usually by means of a Print statement. The $Web_Sel* functions that build the select option list usually supply the </select> tag, but you can bypass this with the NOENDSEL option, if needed.

Syntax for HTML select

The syntax for the HTML select element is simply:

<select sel_attrs> <option opt_attrs> opt_content <option opt_attrs> opt_content </select>

The components of note for the $Jan_Web functions are:

<select> There are several attributes that you may wish to supply on the <select> tag; rather than introducing some arguments to the $Web_Sel* functions for these attributes, you simply provide the <select> tag, usually by means of a Print statement.

sel_attrs

The select attributes of interest are:

multiple With this attribute, the user can click on multiple items in the options list, and the selected attribute can be provided in multiple <option> elements in the list. If the multiple attribute is not used, only one option can be selected, both in terms of the option attribute, and in terms of the user's actions (clicking an option will de-select the currently selected option). Also, a non-multiple select element causes the first option in the list to be the default selected element, while a multiple select element has no default selected element.

name The name attribute associates an identifier with the select element. When the form containing a <select> is submitted by the user, the form parameter whose name is this identifier is returned, with one occurrence for each selected option in the list.

opt_attrs

The option attributes of interest are:

selected	This indicates the option (or options, in a multiple select element) that is (or are) pre-selected when the form is displayed on the user's browser. Selected options are highlighted on the browser display, for example, by reverse video. In a non-multiple `select` element, if no `option` is specified with the `selected` attribute, the first option in the list is selected by default.
value	If this option is selected, this indicates the value assigned to an occurrence of the form parameter associated with the `select` element. If the `value` attribute is omitted, the content of the `option` is used as the value. To simplify the setting of defaults with the `$Web_Sel*` functions, the terminology is changed slightly; see the discussion below.

</option> Most browsers do not require the </option> tag at the end of the option element; to save a few bits, the $Web_Sel* functions normally do not supply the </option> tag. If you want to have it generated, use the ENDOPT option on the $Web_Sel* function that generates your select option list.

</select> The $Web_Sel* functions that build the select option list usually supply the </select> tag, but you can, if needed, bypass this with the NOENDSEL option.

Strictly speaking, each option element in a select options list may have a value attribute, which can be used to identify the option element. When a form containing a select options list is sent as a web request, the form parameter identified by the <select> name attribute has as its values all of the value attributes of all the options in the list that the user selected at the browser, for example by clicking on them.

If an option element does not have a value attribute, the "content" of the option element is used as its value. The content of the element is always used as the display on the browser for the option. Therefore, in HTML terms, every option element has a content, which is always displayed on the browser, and it may optionally have a value attribute, which may be different from the content, and is used to identify which options have been selected.

Since the manipulation of drop-down lists in Janus Web Server programming primarily involves manipulation of the option element values, we discuss the value attribute and the content of the option element from a different perspective. The content of the option element is called its description, which is the string displayed on the browser. By default, this is the same as the value of the option element. When you specify an option element in Janus Web Server, you always specify its value, and the description is optional, even though in terms of HTML syntax the option element always has a content, and its value attribute is optional.

A typical form application processes the user input; if there are errors, the form is redisplayed with messages and with form fields filled in as the user filled them in. To send the form with the same options selected that the user clicked on, the $Web_Sel* functions have a separate argument specifying the options to be selected, and it also allows you to simply specify a parameter name (typically, the <select name>) whose values specify the options to be selected.

$Web_Sel* functions

The $Web_Sel* functions are summarized in the following list. See "$Web_Sel* example" for an extended example using many of the $Web_Sel* functions.

`$Web_Del_Sel`	Deletes a global select element, preventing its further use and freeing any CCATEMP pages used by it.
`$Web_Save_Sel`	Creates a global select element and saves the list of values and, optionally, corresponding description strings, in CCATEMP pages.
`$Web_Sel`	Builds the options list for a select element; options list taken from a global select element created by `$Web_Save_Sel`; selected option specified by character string.
`$Web_Sel_Check`	Validates that a string matches one of the options of a global select element.
`$Web_Selp`	Builds the options list for a select element; options list taken from a global select element created by `$Web_Save_Sel`; selected option specified by parameter name.
`$Web_Selp_Check`	Validates that each value of a form and/or isindex parameter matches one of the options of a global select element.
`$Web_Selps`	Builds the options list for a select element; options list taken from a delimited list of strings; selected option specified by parameter name.
`$Web_Selps_Check`	Validates that each value of a form and/or isindex parameter matches one of a delimited list of strings.
`$Web_Sels`	Builds the options list for a select element; options list taken from a delimited list of strings; selected option specified by character string.
`$Web_Sels_Check`	Validate that a string matches one of a delimited list of strings.
`$Web_Selsp`	Builds the options list for a select element; options list taken from a delimited list of strings; selected option specified by parameter name. (`$Web_Selsp` is a synonym for `$Web_Selps`.)
`$Web_Selsp_Check`	Validates that each value of a form and/or isindex parameter matches one of a delimited list of strings. (`$Web_Selsp_Check` is a synonym for `$Web_Selps_Check`.)

Form input processing functions

`$Web_Form_Action`	Retrieves the current URL along with isindex data if present.
`$Web_Form_Action_Len`	Retrieves the length of the current URL along with isindex data if present.
`$Web_Form_Len`	Retrieve the length of a field value in a form.
`$Web_Form_Line`	Retrieve the value of line in a field in a form.
`$Web_Form_Name`	Retrieve the name of a field in a form.
`$Web_Form_Num_Line`	Retrieve the number of lines in a field in a form.
`$Web_Form_Parm`	Retrieve the value of a field in a form.
`$Web_Form_Parm_Len`	Retrieve the length of a field value in a form.
`$Web_Form_Parm_Line`	Retrieve the value of line in a field in a form.
`$Web_Form_Parm_Num_Line`	Retrieve the number of lines in a field in a form.
`$Web_Num_Form`	Retrieve the number of fields in a form.

Isindex data/URL parameter processing functions

URL parameters and "isindex data" are two terms for the same thing.

`$Web_IsIndex_Len`	Retrieve the length of an isindex field value.
`$Web_IsIndex_Line` (or `$Web_IsIndex_Parm_Line`)	Retrieve the value of line in an isindex field.
`$Web_IsIndex_Name`	Retrieve the name of an isindex field.
`$Web_IsIndex_Num_Line` (or `$Web_IsIndex_Parm_Num_Line`)	Retrieve the number of lines in an isindex field.
`$Web_IsIndex_Parm`	Retrieve the value of an isindex field.
`$Web_IsIndex_Parm_Len`	Retrieve the length of a field value in a form.
`$Web_IsIndex_Parm_Lstr`	Retrieve the value of an isindex field as a `Longstring`.
`$Web_Num_IsIndex`	Retrieve the number of isindex fields.
`$Web_Num_URL_Parm`	Retrieve the number of URL parameters.
`$Web_URL_Parm_Len`	Retrieve the length of a URL parameter value.
`$Web_URL_Parm_Line`	Retrieve the value of line in an URL parameter.
`$Web_URL_Parm_Lstr`	Retrieve the value of a URL parameter as a `Longstring`.
`$Web_URL_Parm_Name`	Retrieve the name of an URL parameter.
`$Web_URL_Parm_Num_Line`	Retrieve the number of lines in an URL parameter.
`$Web_URL_Parm`	Retrieve the value of an URL parameter.

Form or isindex data/URL parameter processing $functions

URL parameters and "isindex data" are two terms for the same thing.

`$Web_Len`	Retrieve the length of a URL parameter or form field value.
`$Web_Line`	Retrieve the value of line in a URL parameter or form field.
`$Web_Name`	Retrieve the name of a URL parameter or form field.
`$Web_Num_Line`	Retrieve the number of lines in a URL parameter or form field.
`$Web_Parm`	Retrieve the value of a URL parameter or form field.
`$Web_Parm_Len`	Retrieve the length of a field value in a form.
`$Web_Parm_Line`	Retrieve the value of line in a URL parameter or form field.
`$Web_Parm_Num_Line`	Retrieve the number of lines in a URL parameter or form field.
`$Web_Num`	Retrieve the number of URL parameter or form fields.

Header processing $functions

`$Web_Hdr_Len`	Retrieve the length of a field value in a request header.
`$Web_Hdr_Name`	Retrieve the name of a field in a request header.
`$Web_Hdr_Parm`	Retrieve the value of a field in a request header.
`$Web_Num_Hdr`	Retrieve the number of fields in a request header.

Cookie processing $functions

`$Web_Cookie_Len`	Retrieve the length of a cookie value.
`$Web_Cookie_Name`	Retrieve the name of a cookie.
`$Web_Cookie_Parm`	Retrieve the value of a cookie.
`$Web_Get_Cookie`	Retrieve the value of a cookie.
`$Web_Get_Cookie_Lstr`	Retrieve the value of a cookie into a `Longstring`.
`$Web_Num_Cookie`	Retrieve the number of cookies in a request.
`$Web_Set_Cookie`	Set Persistent Client State cookies.
`$Web_Set_Cookie_Lstr`	Set the value of a cookie from a `Longstring`.

Date processing $functions

`$Web_Date`	Get the current (GMT) date and time in seconds.
`$Web_DateND`	Get the current (GMT) date in days.
`$Web_DateNM`	Get the current (GMT) date and time in milliseconds.
`$Web_DateNS`	Get the current (GMT) date and time in seconds.
`$Web_Date2D`	Convert a character format date and time to number of seconds.
`$Web_Date2N`	Convert a character format date and time to number of seconds.
`$Web_Date2ND`	Convert a character format date and time to number of days.
`$Web_Date2NM`	Convert a character format date and time to number of milliseconds.
`$Web_Date2NS`	Convert a character format date and time to number of seconds.
`$Web_D2Date`	Convert a number of seconds to web time format.
`$Web_ND2Date`	Convert a number of days to web time format.
`$Web_NM2Date`	Convert a number of milliseconds to web time format.
`$Web_NS2Date`	Convert a number of seconds to web time format.
`$Web_N2Date`	Convert a number of seconds to web time format.

File upload $functions

`$Web_File_Content`	Upload data into a `Longstring`.
`$Web_List_Receive` (or `$Web_List_Recv`	Upload data into a `$list`.
`$Web_Proc_Receive` (or `$Web_Proc_Recv`)	Upload data into a procedure.

Saved $list and record set $functions

`$Web_Restore_List`	Restore a `$list`.
`$Web_Restore_Recset`	Restore a list or a foundset.
`$Web_Save_List`	Save a $list.
`$Web_Save_Recset`	Save a list or a foundset.

SSL-related $functions

`$Web_Cert_Info`	Retrieve information from a client certificate received from a web client.
`$Web_Cert_Levels`	Determine the number of levels in a client certificate received from a web client.
`$Web_Cipher`	Determine which SSL cipher, if any, is being used for a connection.
`$Web_End_Ses`	Terminate a logical login session created with `SSLSES` or `SESCOOKIE`.
`$Web_Protocol`	Determine which network security protocol, if any, is being used for a connection.
`$Web_Secure`	Determine if connection is on a secure (SSL or TLS) port.

User authentication related $functions

`$Web_LogMsg`	Retrieve a saved logon messages.
`$Web_Num_LogMsg`	Retrieve the number of saved logon messages.
`$Web_Password`	Determine password sent by browser.
`$Web_Realm`	Set the security realm before sending an "Unauthorized".
`$Web_User`	Determine userid sent by browser.

Miscellaneous $functions

`$Web`	Determine whether running a web request.
`$Web_Browser`	Check browser release and brand/type.
`$Web_Expire`	Set response entity expiration date.
`$Web_Input_Content`	Retrieve form or upload information into a `Longstring`.
`$Web_IPAddr`	Get the dotted IP address of the browser.
`$Web_Last_Modified`	Indicate time response entity was last updated.
`$Web_Port`	Get the name of the port of the Web Server.
`$Web_NoCache`	Set HTTP response headers so fresh page is displayed.
`$Web_Response`	Set any HTTP response header parameter.
`$Web_Screen`	Change or retrieve current 3270 screen mapping rules.
`$Web_Set`	Change certain Janus Web parameters.
`$Web_Redirect`	Redirect processing to another server.
`$Web_URL_Encode`, `$Web_URL_Encode_Lstr`	Encode data so that it can be properly made part of a URL, especially for isindex data.
`$Web_URL_Decode`, `$Web_URL_Decode_Lstr`	Decode data that is in URL encoded format, most likely as a URL parameter or a form parameter.

CALLing Sirius $functions

As of version &soopv of the Sirius Mods, you can invoke many of the Sirius $functions using a User Language CALL statement instead of assigning the function result to a %variable. For example:

%l = $ListNew $ListAdd(%L, 'Once upon a midnight dreary') $ListAdd(%L, 'As I pondered weak and weary') Call $List_Print(%l)

You can CALL such $functions and still test for their return code, if necessary. For example:

Call $List_Print(%l) If $List_Print(%l) Then

This "callability" is an optional approach; it does not replace %variable assignment.

The callable $functions are indicated as such in their individual function descriptions. Typically they are $functions that do more than simply return a value, and the value they return is primarily an indicator of whether the function completed successfully. $ListCnt, for example, is a (non-callable) $function that just returns a value.