JANUS WEB ON: Difference between revisions

Revision as of 22:52, 12 September 2011

<section begin="desc" />Assign actions to URLs<section end="desc" />

The JANUS WEB ON command indicates the action to be taken when a request for a specified URL (the url value), which is not redirected, is determined to be allowed access. If an incoming request for a URL has no associated ON rule, the browser requesting the URL is sent a "Not Found" response.

Syntax

JANUS WEB ON command syntax

Portname, method, and url are described under the JANUS WEB command. The remaining parameters for the JANUS WEB ON command are described on the following pages. NB A JANUS WEB ON command must always include exactly one action parameter, either SEND, RECV, or CMD. The other parameters in the following sections are optional.

CMD cmd [AND cmd [AND...]]

This parameter indicates that cmd is to be issued as a Model 204 command just as if it had been entered by a user. Multiple commands can be specified by separating the commands with the "AND" keyword.

Each cmd can contain wildcards just as for url. The wildcard characters in cmd are replaced by the incoming request characters that match the corresponding wildcard characters in url. For example, if url is /SUBSYS/*, cmd is *, and a request for URL ./SUBSYS/SUBSYSMGMT is received, the command SUBSYSMGMT is executed -- most likely resulting in the subsystem SUBSYSMGMT being invoked.

If url is /INCLUDE/TEST/*, cmd is INCLUDE WEB.TEST.*, and a request for URL TEST/DISPLAY is received, the command INCLUDE WEB.TEST.DISPLAY is executed.

If url is /INCLUDE/*/*, the CMD clause contains .'INCLUDE *' AND 'INCLUDE *', and a request for the URL .TEST/DISPLAY is received, the commands INCLUDE TEST and INCLUDE DISPLAY are executed.

Note that unless cmd consists of a single word, it must be enclosed in single quotes.

Under Sirius Mods 6.3 and later, wildcard substitution is also performed on files or groups listed in the OPEN clause (JANUS WEB ON). For example, given this rule:

JANUS WEB WEBPORT ON /TEST?/* OPEN FILE QA* CMD 'I *'

The URL /test5/queequeg would result in the file QA5 being opened and procedure QUEEQUEG inside QA5 being INCLUDEd.

Also under Sirius Mods 6.3 and later, variable data from a URL can be substituted out of order by indicating the wildcard match position after a double-quote character. For example, given this rule:

JANUS WEB WEBPORT ON /*/TEST?/* OPEN FILE TEST CMD 'I MOBY"2,*'

The URL /xyz/test5/tashtego would result in the file TEST being opened and the command "I MOBY5,TASHTEGO" being issued. As this example illustrates, an asterisk after a positional replacement string uses the replacment string after the positional string.

It is possible with positional replacement strings to re-use replacement strings. For example, given this rule:

JANUS WEB WEBPORT ON /TEST* OPEN FILE TEST - CMD 'I A"1' AND 'I B"1' and 'I C"1'

The URL /test3 would result in the file TEST being opened and the commands I A3, I B3 and, .I C3 being issued.

The default procedure file or group at the time the first cmd is executed will be either that specified in the OPEN clause of the JANUS WEB ON command or, if that is not present, the default file or group resulting from the port definition. The default procedure file or group at the time of subsequent cmd executions is whatever happens to be the default after the execution of the preceding cmd.

CMD is valid for any method -- the command executed can be used to send data back to the browser for the GET and POST methods, and used to receive data from the browser for the PUT method.

cmd can be any Model 204 command, subject to standard authorization requirements. Commands that require additional terminal input, such as a response to a password prompt or a "DO YOU REALLY WANT TO" prompt, will not work correctly as an ON rule command. In addition to standard Model 204 commands, the WEBRUN command is also available in web ON rule commands. WEBRUN invokes an APSY subsystem, but it bypasses the APSY login procedure for a procedure specified on the WEBRUN command.

The WEBRUN format is:

WEBRUN subsys proc [parms]

Where:

subsys	is an APSY subsystem
proc	is the APSY procedure to run instead of the login procedure
parms	are (optional) command line parameters for the subsystem

The WEBRUN command makes it possible for a single subsystem to service many different URLs without going through a login procedure that routes to the appropriate procedure for each URL. This provides both performance and coding simplicity benefits. As an example of the latter, when a procedure is invoked via WEBRUN, the APSY communications global is set to the exit value before the procedure is invoked, so unless the procedure explicitly sets the communications global, termination of the procedure causes the subsystem to be exited.

SEND pname

This parameter indicates that the procedure pname is to be sent to the browser when url is requested.

pname can contain wildcards just like url can. The wildcard characters in pname are replaced by the incoming request characters that match the corresponding wildcard characters in url. For example, if url is /ALBAN/*, pname is *.HTML, and a request for URL /ALBAN/BERG is received, procedure BERG.HTML is sent.

The procedure is always sent from the default procedure file or group, which is either that specified in the OPEN clause of the JANUS WEB ON command or, if that is not present, the default file or group resulting from the port definition.

SEND is invalid for a JANUS WEB ON command that includes the PUT method.

RECV pname

This parameter indicates that the procedure pname is to be received from the browser when url is sent in a PUT request.

pname can contain wildcards just like url can. The wildcard characters in pname are replaced by the incoming request characters that match the corresponding wildcard characters in url. For example, if url is /ANTON/*.HTML, pname is .HTML_, and a PUT request for URL /ANTON/WEBERN is received, procedure HTML_WEBERN is updated from the data sent with the PUT request.

The procedure is always received into the default procedure file or group, which will be either that specified in the OPEN clause of the JANUS WEB ON command or, if that is not present, the default file or group resulting from the port definition.

RECV is invalid for a JANUS WEB ON command that includes the GET or POST method.

RECEIVE is an acceptable synonym for RECV.

AUDTERM | NOAUDTERM

AUDTERM indicates that messages that go to the Janus Web Server thread "terminal" when $Web_Off is in effect (either explicitly or implicitly) should be logged to the journal as RK lines; NOAUDTERM indicates that they should not be logged.

This parameter can be used to override the default setting of AUDTERM or a NOAUDTERM setting on the JANUS DEFINE command for the port for a specific set of URLs (see ). (Note: NOAUDTERM became the default JANUS DEFINE port setting starting with Version 6.0 of the Sirius Mods.)

The AUDTERM and NOAUDTERM parameters are mutually exclusive.

AUTODONE | NOAUTODONE

AUTODONE indicates that a return to Model 204 command mode after execution of the last JANUS WEB ON cmd is to be treated as an implicit $Web_Done. NOAUTODONE indicates that a return to Model 204 command mode after execution of the last cmd is not to be treated as an implicit $Web_Done.

This parameter can be used to override the default setting of AUTODONE or a NOAUTODONE setting on the JANUS DEFINE command for the port for a specific set of URLs (see ).

AUTOON | NOAUTOON

AUTOON indicates that the execution of the first JANUS WEB ON cmd is to be treated as an implicit $Web_On; NOAUTOON indicates that it is not.

This parameter can be used to override a AUTOON or NOAUTOON setting on the JANUS DEFINE command for the port for a specific set of URLs (see ).

The AUTOON and NOAUTOON parameters are mutually exclusive.

BASE64 | BINARY | TEXT

This parameter option indicates whether data received from a browser is to be encoded using base64, binary, or EBCDIC encoding before being saved to a Model 204 procedure, and whether data sent to the browser is in binary or text (EBCDIC) format.

BASE64 only makes sense for data received in a request using the PUT method, so it is not valid in an ON rule that indicates SEND. Base64 encoding is a way of storing binary data using only standard displayable characters, thus simplifying certain operations on procedures containing such data. The cost of this simplification is that there is (barely measurable) overhead in translating the data to and from base64 encoding, and the size of the stored data is approximately 33% greater with base64 encoding than with binary encoding.

Base64 encoding is the default for received non-text data, and it is probably the best option, except in cases where even the slightest extra application overhead is intolerable.

BINARY indicates that:

Data sent to a browser is to be sent as binary data, that is, not translated from EBCDIC to ASCII regardless of the mime type.
Data received from a browser is to be encoded using binary encoding before being saved to a Model 204 procedure.

Binary encoded data is stored in specially formatted procedures that contain a few extra overhead characters in addition to the binary data. Binary data often contains non-displayable characters, so it can be difficult to work with. Nevertheless, binary encoding is the most efficient way of storing non-text data in Model 204 procedure files.

TEXT indicates that:

Data sent to a browser is to be sent as text data, that is, translated from EBCDIC to ASCII regardless of the mime type.
Data received from a browser is to be translated from ASCII to EBCDIC before being saved to a Model 204 procedure.

Storing data as text facilitates editing of the text data in the Model 204 environment and hence is a good way of storing HTML or plain text data.

The BASE64, BINARY, and TEXT parameters are mutually exclusive.

CLOSEIMMED | NOCLOSEIMMED

This parameter option overrides the default or explicit JANUS DEFINE setting of the CLOSEIMMED/NOCLOSEIMMED parameter. For more information, see .

CLOSEREAD | NOCLOSEREAD

This parameter option overrides the default or explicit JANUS DEFINE setting of the CLOSEREAD/NOCLOSEREAD parameter. For more information, see JANUS DEFINE.

COMPRESS level

COMPRESS indicates the level of compression to be performed on outgoing content. This parameter can be used to override the default setting of COMPRESS on the JANUS DEFINE command for the port for a specific set of URLs ().

The COMPRESS parameter is available in Sirius Mods 6.3 and later, and it has these values:

0	Perform no compression.
1	Perform deflate compression only.
2	Perform deflate compression and Huffman encoding.

The COMPRESS setting can be overridden on an application basis with $Web_Set('COMPRESS').

CR | CRLF | LF

These parameter options indicate the ASCII character(s) that separate lines of text data.

CR	Indicates that lines of text data should be separated by the carriage return (X'0D') character.
CRLF	Indicates that lines of text data should be separated by the carriage return and line feed (X'0D0A') characters.
LF	Indicates that lines of text data should be separated by the line feed (X'0D') character.

These parameters are mutually exclusive, and they have no effect if the BINARY option is specified for a Janus Sockets () port.

EXPIRE time

This parameter indicates that the expiration time of the page should be set to the specified (relative or absolute) date and time.

Relative expiration times are indicated with a plus (+) or minus (-) sign followed by a number of seconds, as in EXPIRE +7200 or EXPIRE -3600. Absolute expiration time must be specified in either YYMMDD or YYMMDDHHMISS format.

An EXPIRE time specification in an ON rule is useful as an alternative to setting expire times via $Web_Expire. It is is probably most useful for relatively static content such as static text or images that are sent via SEND in the ON rule rather than as part of command processing.

FORMREDIRWAIT nnnn

This parameter overrides the default or explicit JANUS DEFINE setting of the FORMREDIRWAIT parameter. For more information, see .

FORMPOSTWAIT nnnn

This parameter overrides the default or explicit JANUS DEFINE setting of the FORMPOSTWAIT parameter. For more information, see .

MAXTEMP nnnn

This parameter overrides the default or explicit JANUS DEFINE setting of the MAXTEMP parameter. For more information, see .

MSGSEND | NOMSGSEND

This parameter overrides the default or explicit JANUS DEFINE setting of the MSGSEND/NOMSGSEND parameter. For more information, see .

OPEN FILE | GROUP fgname [[WITH] priv]

This parameter indicates that before any action is performed, the indicated file or group is to be opened. If neither the qualifier FILE nor GROUP is present, Janus Web Server tries to open a permanent group called fgname. If there is no group by that name, it attempts to open a file by that name.

If priv is not specified, the file or group is opened with privileges of X'0221', unless the ON rule also specifies RECV in which case it is opened with privileges of X'1239'. This allows displaying and including procedures in the indicated file or group in all cases, and it allows the updating of procedures in the RECV case. priv must be specified as a hexadecimal value that starts with .X' and ends with ' (single quote). For example, X'BBBF', X'1234', and X'222F' are all valid privileges.

The keyword WITH can be specified between the file or group name and the open privileges, but it is not required.

The implicit or explicit open privileges are used regardless of the OPENCTL and PRIVDEF settings for the file or group.

It is possible to have one file or group opened as a result of the OPEN parameter on the port definition, and to have a second opened as a result of an OPEN in the JANUS WEB ON command. The port open always happens first, which means that file or group fgname always becomes the default file or group before the ON action (SEND, RECV, or CMD) is performed.

To open more than one file or group with an OPEN clause, use the AND keyword to specify additional files or groups after the first file or group in the JANUS WEB ON. When the first command specified in a CMD clause or a SEND clause is executed, the first file or group specified in an OPEN clause will be the default and current file or group.

There is no point in specifying more than one file or group in a JANUS WEB ON command that contains a SEND or RECEIVE, since only the first file or group will be searched for by the SEND or received by the RECEIVE.

Some examples of valid OPEN clauses are :

... OPEN FILE MATISSE ... OPEN MONET WITH X'0569' ... OPEN RENOIR AND GROUP IMPRSNST WITH X'0221' ... OPEN FILE GAUGIN X'0221' AND FILE MANET X'BFFF'

Under Sirius Mods 6.3 and later, wildcard substitution is performed on files or groups listed in the OPEN clause, as well as in the CMD clause. For example, with the following rule, the URL /test5/queequeg would cause the file QA5 to be opened and the procedure QUEEQUEG inside QA5 to be INCLUDEd:

JANUS WEB WEBPORT ON /TEST?/* OPEN FILE QA* CMD 'I *'

RAWINPUTONLY | NOTRAWINPUTONLY

RAWINPUTONLY indicates that, regardless of the POST data content-type set by the client, Janus Web Server should save the raw input stream of an HTTP POST, and should refrain from parsing the input content into form fields. This is very similar to the port definition RAWINPUT parameter except that:

RAWINPUTONLY can be an ON rule parameter, so it can be set for specific URLs.
RAWINPUT does not prevent Janus Web Server from trying to parse the form parameters if the content-type header for the POST is set to application/x-www-form-urlencoded or multipart/form-data. RAWINPUTONLY prevents this parsing, so it protects Janus Web Server applications from errors in this parsing. These errors include invalid-form-data errors and request-buffer-full errors.

NOTRAWINPUTONLY can be used to override the default setting of RAWINPUTONLY on the JANUS DEFINE command for the port for a specific set of URLs. If RAWINPUTONLY is specified on a port definition, RAWINPUTONLY on a JANUS WEB ON rule for the port is redundant, but harmless.

The RAWINPUTONLY parameter for JANUS WEB ON rules is, perhaps, most useful for allowing requests with a large number of parameters to be processed without having to allocate an extremely large request buffer to hold all the posted parameters. In fact, if there are enough form parameters, the maximum request buffer size (65535 bytes) may not be sufficient to hold all the form data in a post.

In this case, the RAWINPUTONLY parameter is the only way to prevent the request from failing with this error:

MSIR.0353 Insufficient Web request buffer space

If the RAWINPUTONLY parameter is in effect for a URL, the form fields are no longer available with the $Web_form and $Web_Parm functions (that is, the multiple functions whose names begin with these characters), though the $Web_parm, $Web_isindex, and $Web_URL_Parm functions can still be used to access URL parameters.

When using RAWINPUTONLY, the only way to process the form parameters is by retrieving them into a longstring using the $Web_Input_Content function. .el method. To separate the various parameters, this longstring must then be parsed and (usually) URL decoded. If the POST used the default form data encoding of .application/x-www-form-urlencoded, each parameter/value pair is separated with an ampersand (&amp.). Processing is considerably more complicated if the encoding is .multipart/form-data.

For Janus SOAP customers, the Stringlist class ParseLines method provides a simple, efficient way of parsing a form parameter list with .application/x-www-form-urlencoded encoding:

%formParms is object stringList %formParms = new %formParms:parseLines($Web_Input_Content('TEXT'), ' &')

This produces a Stringlist that contains items of the format .fieldname=value. Assuming that none of the form field names have been URL encoded by the browser (a reasonable assumption for most Latin-character field names), this Stringlist is in a format that can be easily, though not simply, searched.

For example, the following code locate's the field named OrderNumber:

%itemNum = %formParms:locate('Order=', , 1, 6)

There are some things worth noting here:

The search is case sensitive, though the Locate method does have a case-insensitive search flag. Fortunately, almost all browsers return form field names in the case that was specified in the <input> tags. Still, the case-insensitive search parameter could be set for Locate if needed.
The equal sign is specified to prevent accidental matches on other fields that begin with "Order", such as, "OrderDate". While it can be left off if the programmer is confident there won't be such accidental matches, this is not recommended.
The column range is also specified to prevent accidental matches. While an equal sign should be URL encoded by the browser -- so an "Order=" in a value (encoded as "Order%") should not cause an accidental match -- one could still get an accidental match with, say, "PreviousOrder=". Specifying the column range also makes the search more efficient by limiting it to the start of each Stringlist item.
For form field names that are used more than once on a form, the values beyond the first would need to be retrieved by specifying a starting item number (second) parameter on the Locate method.

Once the desired item number is located, the next step is to retrieve the value. In the case of a field name with a known length, this can be done easily with the Item method and the $Lstr_Substr function:

%itemNum = %formParms:locate('Order=', , 1, 6) %order = $Lstr_Substr(%formParms:item(%itemNum), 7)

Unfortunately, the value in %order above will be URL encoded, that is, spaces will be replaced by plus signs, and any special characters (such as ampersands or equal signs) will be encoded with a percent sign followed by the hexadecimal value of the ASCII code. For example, the string 90% = 9/10 would be encoded as .90%25+%3D+9%2F10. Before Sirius Mods Version 6.8, there was no URL decode function (although, there is a $Web_URL_ENCODE to do URL encoding), so URL decoding must be done in User Language.

Such decoding could be easily packaged in a method or complex subroutine. For example, the following shared method in a class called URL performs this decoding:

class URL public shared function decode(%value is longstring) is longstring end public shared function decode(%value is longstring) is longstring %pos is float %value = $Lstr_Translate(%value, ' ', '+') %pos = 1 repeat forever %pos = $Lstr_Index(%value, '%', %pos) if not %pos then loop end end if %value = $Lstr_Substr(%value, 1, %pos - 1) with - $ebcdic($x2c($Lstr_Substr(%value, %pos + 1, 2) )) with - $Lstr_Substr(%value, %pos + 3) %pos = %pos + 1 end repeat return %value end function end class

With this function available, the value in %order in the previous example can be easily URL-decoded:

%itemNum = %formParms:locate('Order=', , 1, 6) %order = $Lstr_Substr(%formParms:item(%itemNum), 7) %order = %(url):decode(%order)

For non-Janus SOAP customers, the processing performed by the Decode function could be placed inside a complex subroutine where %value is an Output parameter.

In Sirius Mods Version 6.8 and later, the $Web_URL_Decode and $web_url_decode_lstr functions obviate the need for the User Language method to do URL decoding:

%itemNum = %formParms:locate('Order=', , 1, 6) %order = $Lstr_Substr(%formParms:item(%itemNum), 7) %order = $web_url_decode_lstr(%order)

Obvioulsy, because $Web is writtent in assembler, it will be much more efficient than the comparable method written in User Language

The RAWINPUTONLY parameter is available in Sirius Mods Version 6.7 and later.

SSI

This parameter indicates that the sent document should be scanned for "Server Side Include" tags.

WRAPJS

This parameter indicates that output text is to be embedded in JavaScript document.write methods where double quotes inside the document.write parameter are "escaped" with a backslash (\) character. This is useful for embedding HTML from one URL into another -- there is no HTML tag to embed the contents of one URL inside an HTML page, but there is such a tag for JavaScript: the <script src="..."> tag. So by making HTML look like JavaScript, one can take advantage of this facility for HTML.

The WRAPJS parameter is available in Sirius Mods Version 6.2 and later.

XTAB xtabname

This parameter associates a translate table with this URL set. The translate table must already have been defined with JANUS LOADXT, or the JANUS WEB command will fail.

This parameter is optional. If it is omitted, the port default translate table is used.

If you override the default translate table with a Janus ON rule, the new table is used to translate any form POST data and PUT entities. Any text data returned to the browser is also translated with the new translate table.

The URL and any request headers, including ISINDEX data and cookies, are translated with the old translate table, since this data has already been received before the ON rule is executed. .pa

References

See: List of Janus commands and List of JANUS WEB subcommands

@@ Line 32: / Line 32: @@
 '''Portname''', '''method''', and '''url''' are described under the [[JANUS WEB]] command. The remaining parameters for the JANUS WEB ON command are described on the following pages. NB ''A JANUS WEB ON command must always include exactly one action parameter, either SEND, RECV, or CMD. The other parameters in the following sections are optional.''
-<div id="cmd"></div>
+===CMD cmd [AND cmd [AND...]]<div id="cmd"></div>===
-===CMD cmd [AND cmd [AND...]]===
 This parameter indicates that '''cmd''' is to be issued as a ''Model 204'' command just as if it had been entered by a user. Multiple commands can be specified by separating the commands with the "AND" keyword.