Text and Html statements: Difference between revisions

Revision as of 18:58, 17 February 2011

The HTML or TEXT statement

The Html (or Text) statement in User Language is a general purpose alternative to a series of Print statements for producing a fair amount of literal data. Primarily for use with Janus Web Server (hence the name Html), it is available with many Sirius products. It is most useful when PRINT output is captured or directed by some means. It is also quite useful for populating a StringList with a large amount of mostly constant text. This latter capability is provided by the To option of the Html/Text statement.

In this section, “HTML block” refers to either the Html or Text block.

The Html block can be used to produce print output of largely literal or static data. For example, sending output to a browser with Janus Web Server often requires a significant quantity of static text for HTML directives. Rather than placing this static data inside quotes in a Print statement, the Html block will automatically assign text as print output. Any Model 204 expression, including simple %variable values or $function invocations, can be placed inside an Html block, as long as it is enclosed inside the expression start and end characters. The default start and end characters are the curly brackets ( { ) and ( } ).

The following is an example of an Html statement specification:

html
<form method="POST" action="processform">
<br>
Last name: <input type="text"
name="lname" value="{%LNAME}">
</form>
end html

The syntax of the Html and Text blocks is shown below:

 Html [options]
 body
 block_end_line

or

 Text [options]
 body
 block_end_line

options, body, and block_end_line are discussed below.

The components of the Html or Text block are discussed in the following sections. The Html (or Text) block can be used in contexts other than the production of a web page. For example, it can be used:

To store lines in a temporary procedure or sequential dataset, using the USE command
To populate a StringList, using the To option on the Html/Text statement
To populate a $list, using the $LIST_CAPTURE function
To send lines over a Janus Sockets connection, using the $SOCK_CAPTURE function
To prepare output processed by some other program, when the output is created by something like a BATCH2 or RCL connection to Model 204 Here are some advantages of the Html/Text block:
User Language is visually close to the output.
Literal text does not need to be enclosed in apostrophes.
The Print keyword is not necessary.
Any valid Model 204 expression can be included inside an Html block, not just literals, %variables, fieldnames, $functions, and a few other constructs.
The With and And keywords are not needed between expressions.
Apostrophes do not need to be doubled, as in:

 print 'Just say ''No'''

The following is an example of an Html block using JavaScript to illustrate applications of the Html/Text options:

html nocont exprs '!{' expre '}!'
<html>
<head>
<title>My Javascript Page</title>
</head>
!{$sir_date('Wkd Mon DD YYYY HH:MI:SS')}!
<br>
<body>
<script>
<!--
name=prompt("Person's name","Type name here");
end html

%s1='if (name=="'
fr where rectype='PHONE'
  %s1 = %s1 with with name -
        with '") {document.write("' with extn with '")}'
  %s1='else if (name=="'
end for

html nocont exprs '!{' expre '}!'
  else {alert ("Unkown person")};
  -->
  </script>
  </body>
  </html>
end html

Html statement options used in this example:

Nocont is used to turn off continuations signified by trailing dashes. In the JavaScript, dashes are used in an input line that prevents browsers without JavaScript from displaying script as literal output.
Exprs and Expre let you use characters other than the curly brackets ( { } ) to demarcate expressions. The curly bracket characters are necessary in JavaScript.

The Html block is available to any customer who owns any of the following products:

Fast/Unload User Language Interface
Janus SOAP
Janus Sockets
Janus Web Server
Sirius Functions

The Html block is also available if the Limited Janus Web Server capability is available.

Options: Html or Text block options

The various options for an Html or Text block are introduced after the Html or Text keyword. They are described in the following subsections.

Data, Print, Audit, or Trace

These keywords indicate that the Html block consists of only the text that follows the keyword on the logical line: that is, there is no End Html statement to end the block. The Print, Audit, and Trace keywords provide the same functionality as the PrintText, AuditText, TraceText statements. These statements, along with ReturnText, and SetText (which don't have Text/Html statement keyword equivalents) are sometimes called targeted Text statements.

Prior to Sirius Mods version 7.2, only the Data keyword had this effect, and the Print, Audit, and Trace keywords did not exist. The ReturnText and SetText stetements were added to the Text statement in Sirius Mods version 7.8.

Any Html statement keywords that appear after a Data, Print, Audit, or Trace keyword are processed not as keywords but simply as text. If you want to specify keywords in addition to a Data, Print, Audit, or Trace keyword, they must appear before Data, Print, Audit, or Trace to be treated as a keyword.

All other Html block processing, including expression processing, is performed on the line as if it were inside an Html block. The exception is Nodummy processing, because dummy string replacement is performed before the Html statement is parsed.

Data or Print

Either of these keywords can be thought of as providing a single-line Html/Text statement which can still be much easier to type and read than a User Language PRINT statement, as in:

 html data Don't need to worry about apostrophes
 test print {%i} + {%j} = {%i + %j}

The following is an equivalent alternative to the second statement in the preceding example.

 PrintText {%i} + {%j} = {%i + %j}

The PrintText statement has the same effect as a Text Print statement. The PrintText keyword is simply a merging and reordering of Text Print to emphasize the principle action. The lone difference between PrintText and Text Print is that PrintText cannot be used if you want to include other Html/Text options, as in:

 text noexpr print The set is {2, 3, 5, 8, 13, ...}

The Data keyword is available in Sirius Mods 6.2 and later. The Print keyword and the PrintText statement are available in Sirius Mods 7.2 and later.

Audit

This keyword provides a single-line Html/Text statement that functions like a User Language AUDIT statement, that is, routing subsequent text to the audit trail.

For example, this statement directs the text content to the audit trail:

 text audit It ({$time}) was the best of times

The following is an equivalent alternative to the preceding example.

 AuditText It ({$time}) was the best of times

As with the PrintText keyword above, the AuditText statement has the same effect as a Text Audit statement, except it cannot be used if you want to include additional Html/Text options.

The Audit keyword and the AuditText statement are available as of Sirius Mods 7.2.

Trace

This keyword provides a single-line Html/Text statement that is the same as a User Language TRACE statement, that is, routing subsequent text to the trace destination (which may be the audit trail, print device, or CCATEMP trace table, or a combination of them). For example, this statement directs the text content by default to the audit trail:

 text trace This day ({$date}) is unlike any other

The following is an equivalent alternative to the preceding example.

 TraceText This day ({$date}) is unlike any other

As with the PrintText keyword above, the TraceText statement has the same effect as a Text Trace statement, except it cannot be used if you want to include additional Html/Text options. The Trace keyword and the TraceText statement are available as of Sirius Mods 7.2. The Trace statement is described in detail in the SirFact Reference Manual.

Ent_print

The Ent_print keyword overrides the current $ENT_PRINT setting for character entity translation over the Html block. Ent_print must be followed by one of these keywords:

Off	No character entity translation will occur over the Html block.
On	All data printed by the Html statement will undergo character entity translation.
Var	Only the results of expressions will undergo character entity translation.

Character entity translation is the process of converting a single character that might be problematic in certain contexts to a more verbose but non-problematic equivalent. For example, if a “less than” sign (<) appears in HTML text, it should typically be represented as “<” to prevent an HTML processor from mistakenly interpreting it as the start of an HTML tag.

When entity translation is performed, the default translations are “&” to “&”, “<” to “<” and the double quotation mark character (") to “"”. These defaults should be sufficient for most HTML and XML applications (though XML might also require translation of the single quotation mark character (') to “'” if attributes are enclosed in single quotation marks), but they can be modified with the $ENT_TAB function.

The Ent_print keyword is a compile-time option that affects only what is inside the Html block and that is not affected by evaluation time setting of $ENT_PRINT, even within the Html block. If no Ent_print keyword is present on the Html statement, character entity translation is controlled by the evaluation-time $ENT_PRINT setting. Automatic character entity translation and the Ent_print keyword on the Html/Text statement are only available in Sirius Mods 6.2 and later.

LiteralsToTemp

The LiteralsToTempt option indicates that the literal data in the statement is stored in CCATEMP rather than STBL, avoiding excessive demands on STBL space. Designed for a Text statement with an unusually large amount of literal data, this is an alternative to setting the X'01' bit of the SIRCOMP user parameter (which performs the same function).

Nocom or Nocomments

The Nocomments (abbreviated Nocom) option indicates that lines beginning with an asterisk (*) are not comment lines. For example:

  HTML NOCOM
  * This line will go to the output
  END HTML

Nocont or Nocontinuations

The Nocontinuations (abbreviated Nocont) option causes trailing dashes to cease being treated as line continuations. For example, the following statement will cause the output to appear on two separate lines:

 HTML NOCONT
  English:             B-
  Social Studies:      C
  END HTML

Nodum or Nodummy

The Nodummy (abbreviated Nodum) option stops dummy string substitution. For example, the following statement will cause the literal string ?&W to be output without global variable substitution:

 HTML NODUM
 Hello, ?&W
 END HTML

Noell or Noellipses

With the Noellipses (abbreviated Noell) option, a trailing ellipsis (...) is not treated as a concatenation operator. For example:

 HTML NOELL
 These lines are not joined...
 They will appear on different lines.
  END HTML

Noexpr or Noexpressions

If you do not want expression substitution, specify Noexpr or Noexpressions. For example:

 HTML NOEXPR
 {This will be sent directly to output}
 END HTML

Raw

The Raw option acts as Nocom, Nocont, Nodum, Noell, and Noexpr all at once.

Noend

The Noend option eliminates the block end line. Thus, the block will terminate at the end of the procedure. For example:

 PROC FOO
 HTML NOEND
 Now we are in HTML.
 END HTML
 Still in HTML.
 END PROC

Exprs or Exprstart

The Exprstart (abbreviated Exprs) option specifies a string, up to three characters long, that begins an expression within the block body. The default is a left curly brace ( { ). For example:

html exprs go expre stp
  The answer is go8*9stp
end html

It is probably best to use start and end sequences that are not likely to occur in the literal text in the Html/Text block and that clearly demarcate expressions from literal text. The "go" and "stp" in the example above are actually not very good choices.

If the expression start string occurs in the input text, you can “double” the expression start string, instead of using the Exprs option. For example:

html
   <script>
     {{alert("User error")}
   </script>
end html

Note that because the double open-curly-brace is not treated as an expression start, the close-curly-brace is not treated as an expression end since the compiler is not processing an expression where it appears. This illustrates the point that generally there is no need to change the expression end character as its presence is irrelevant in non-expression contexts and an unquoted close-curly-brace cannot occur in a User Language expression. Probably the only compelling reason to change the expression end characters is aesthetics or readability — one might want the expression end to mirror the expression start:

html exprs '{<' expre '>}'
   <script>
     var foobar = "{<%foobar>}"
     if (foobar == '') {alert("Need a value for foobar")}
   <script>
end html

One can even use the same set of characters as expression start and end characters:

html exprs // expre //
   <script>
     var foobar = "//%foobar//"
     if (foobar == '') {alert("Need a value for foobar")}
   <script>
  end html

The above example is simply intended to illustrate a point and should not be considered a recommendation.

Note: If you use multiple special characters to demarcate expressions, you are advised to enclose those characters in single quotation marks (as above) in your Exprs and Expre specifications. Otherwise, multiple-character combinations involving certain special characters (including these six, for example: = ¬ ( ) < > ) cause M204.0580 errors.

Expre or Exprend

The Exprend (abbreviated Expre) option specifies a string that ends an expression within the block body. The default is a right curly brace ( } ).

End

To set your own block_end_line, you can use the End option. If the text of the line you are specifying contains spaces, enclose it in single quotation marks, as in:

 End 'END TEXT BLOCK'

The default block_end_line value is End Html (for the Html block) or End Text (for the Text block).

To %stringList | Audit | Print | Trace

The To option lets you direct the contents of the Html or Text block to a StringList or to the destinations associated with the User Language statements Audit, Print, or Trace. To %stringlist Here is how Text To populates a StringList with some names:

 %jumps is object stringList
 ...
 %jumps = new
 text to %jumps
 Axel
 Flip
 Lutz
 Salchow
 Toe Loop
 Wally
 end text

There are many advantages to using Html To or Text To over a plain Html statement wih $LIST_CAPTURE:

$LIST_CAPTURE or an equivalent is not available for StringLists.
Because Html To does not go through generic Print processing, it has a somewhat more efficient processing path, that is, it uses less CPU.
Because Html To does not go through generic Print processing, the generated quads take somewhat less space.
An Html To block does not affect the current $LIST_CAPTURE setting, so it eliminates the need to worry about saving and restoring the $LIST_CAPTURE setting.
A To option on an Html statement is simply less and cleaner code than an Html statement inside a $LIST_CAPTURE bracket.
If an expression inside an Html To block invokes a User Language method, and that method does a Print statement, the output of that Print statement does not end up on the StringList target of the Html statement. Inside a $LIST_CAPTURE bracket, the output of such a Print statement ends up on the $LIST_CAPTURE's target $list.

The To option of the Html/Text statement appends to the target StringList, so it does not instantiate the stringList if it is null. In fact, a null StringList target for an Html To results in a null-pointer request-cancelling error.

Even if the ultimate target of an Html/Text statement is a plain $list, the Html To can still be used to gain some of the benefits of this structure without much extra code by using the Stringlist object MoveFromId and MoveToId methods:

 %htmlList is object stringList
 %list is float
 ...
 %list = $listNew
 ...
 %htmlList = new
 %htmlList:modeFromId(%list)
 text to %htmlList
 This gets added to the $list.
 end text
 %htmlList:modeToId(%list)

To Audit, To Print, To Trace

These options direct the contents of an Html or Text block or line to the destinations associated with the User Language statements Audit, Print, or Trace. Respectively these destinations are the journal/audit trail, the current print output device, or the trace destination (which may be the audit trail, print device, or CCATEMP trace table, or a combination of them).

For example, the following statement directs the Text block content to the audit trail:

 text to audit
 Now ({$time}) is the time for all good men
 to come to the aid of their company.
 end text

To direct a single line of output, you can use the Data keyword (Data, Print, Audit, or Trace) as in the following:

 text to audit Data It ({$time}) was the best of times

Or, simpler, you can use the Audit keyword like this:

 text Audit It ({$time}) was the best of times

Body: Html or Text block body=

Each line of an Html or Text block, up to the block_end_line, creates a line of literal output, with the following substitutions:

Expressions	An expression is begun by a left brace ( { ) or a user-defined string specified with the Exprs option, and it is ended by a right brace ( } ) or a user-defined string specified with the Expre option. Text within the expression is evaluated as if it were the right-hand side of a User Language assignment; that value is produced, rather than literal output.
Dummy strings	Normally, as in other Model 204 input, dummy strings are substituted under the control of the SUB parameter. This can be suppressed with the Nodummy option, which may be useful if your block contains strings like “what the heck??!!”.
Continuation	Continuation allows text from multiple lines to be printed on one line by adding a hyphen (-) to all preceding lines in the block. All spacing and indentation following the hyphen is ignored. This option works inside an expression.
Ellipses	Ellipses allow text from multiple command lines to be printed on one line by adding three dots (...) to all preceding command lines. Leading spaces will be included. This option will not work inside an expression.
Indentation	Except for continuation lines, the output of a line is indented by as many spaces as the input is indented relative to the Html or Text statement that begins the block.

block_end_line: Html or Text block end

By default, the line that ends an Html or Text block is End Html for an Html block, or it is End Text for a Text block. You can specify your own end line with the End option, as described above in “End”.

Printing of expression results

Model 204 expressions enclosed in the expression start and end characters are printed as if the result of the expression were placed literally in the place of the expression in the HTML block. For example, Text Print {$date} produces a result like 08-02-29.

Character entity substitution

Under Sirius Mods 6.2 and later, the result of the expression might undergo character entity substitution under control of the $ENT_PRINT setting or the Ent_print parameter on the Html/Text statement. An expression can explicitly override the default $ENT_PRINT and Ent_print processing by immediately following the expression start character(s) with one of the following special characters:

&	Perform character entity substitution regardless of the current $ENT_PRINT setting and the Ent_print setting on the Html statement.
!	Do not perform character entity substitution, regardless of the current $ENT_PRINT setting and the Ent_print setting on the Html statement.
*	Do not print the results of the expression. This can be useful if embedding a $function that itself prints output, such as $LIST_PRINT or $WEB_SEL, or a $function that simply sets some environmental parameter (such as $WEB_SET or $RESETN) whose return value should not be displayed.

Note: The asterisk (*) suppresses the printing of the return code but not the output from a $LIST_PRINT or $WEB_SEL function.

In the following example, character entity substitution is explicitly suppressed for the contents of %FONT and explicitly forced for %COMMENT, and the return code from $LIST_PRINT is suppressed:

 HTML
  {!%FONT}This is in a fancy font</font>
  <input type="text" name="comment" value="{&%COMMENT}">
  <br>And here's some stuff<br>
  {*$LIST_PRINT(%LIST)}
  END HTML

The {~} directive

The special expression {~} directs the compiler to replace this expression with the literal chartacter content of the next expression appearing on the same line. So

 printText {~} = {1234:nextPrime}

produces "1234:nextPrime = 1237". The evaluation of the expression following {~} is carried out as usual. As of Sirius Mods 7.8, one can also specific a ~= directive, as in

 printText {~=1234:nextPrime}

which produces "1234:nextPrime=1237". The ~= directive can optionally be followed by spaces before the expression but will always produce no spaces before or after the equals sign on output. If more control of spacing is required, the simple {~} directive should be used, instead.

Table Usage

While the Html/Text statement can provide a convenient typing shorthand relative to a host of Print statements, and it can make code considerably more readable, it does not necessarily use any less table space than the comparable Print statements.

Under Sirius Mods version 6.6 and later, however, table space can be saved with the Html/Text statement, as follows:

By using the To clause and sending the Html/Text statement output directly to a StringList, the amount of QTBL space used is reduced.
If the X'01' bit is set in the SIRCOMP user parameter when a program is compiled, string literals are saved in CCATEMP rather than STBL. Since Html/Text statements often have a large quantity of literal text, they can use a lot of STBL space, so the STBL space savings of the SIRCOMP X'01' bit can be great.

The drawback to having string literals in CCATEMP rather than STBL is that the access path to the data is somewhat longer, that is, slightly more CPU is required to access it. When the Html/Text statement uses a To clause, the extra overhead of CCATEMP data access is reduced, because Html/Text To processing keeps the CCATEMP pages holding literal data open over as many literals as possible.

Furthermore, for pre-compiled APSY procedures, the literals in CCATEMP do not need to be APSY loaded, and they are shared among all users of a procedure. Finally, if a user with a large number of Html/Text statement literals is serverswapped, there is less data to server-swap if literals are kept in CCATEMP (although, the data in CCATEMP does take buffer pool space and might require CCATEMP I/O).

So there is probably no good general rule of thumb regarding whether the SIRCOMP X'01' bit should be set. Probably, unless a site is struggling with server size problems, it is best and simplest to just keep the literals in STBL.