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

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.