Text and Html statements: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(29 intermediate revisions by 4 users not shown)
Line 1: Line 1:
==The '''HTML''' or '''TEXT''' statement==
==The Html or Text statement==
The '''Html''' (or '''Text''') statement in User Language is a general purpose alternative to a
The <var>Html</var> (or <var>Text</var>) statement in <var class="product">User Language</var> is a general purpose alternative to a
series of Print statements for producing a fair amount of literal data. Primarily for use
series of <var>Print</var> 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
with <var class="product">Janus Web Server</var> (hence the name <code>Html</code>), it is available with many Sirius
products. It is most useful when PRINT output is captured or directed by some means.
products. It is most useful when <var>Print</var> output is captured or directed by some means.
It is also quite useful for populating a StringList with a large amount of mostly constant
It is also quite useful for populating a <var>Stringlist</var> with a large amount of mostly constant
text. This latter capability is provided by the To option of the '''Html/Text''' statement.
text. This latter capability is provided by the <var>[[#toOption|To]]</var> option of the <var>Html</var>/<var>Text</var> statement.
 
In this section, “HTML block” refers to either the '''Html''' or '''Text''' block.
In this section, "Html block" refers to either the <var>Html</var> or <var>Text</var> block.
 
The Html block can be used to produce print output of largely literal or static data. For
The <var>Html</var> 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
example, sending output to a browser with <var class="product">Janus Web Server</var> often requires a significant
quantity of static text for HTML directives. Rather than placing this static data inside
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.
quotes in a <var>Print</var> statement, the <var>Html</var> block will automatically assign text as print output.
Any Model 204 expression, including simple %variable values or $function invocations,
Any <var class="product">Model 204</var> 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
can be placed inside an <var>Html</var> 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 end characters. The default start and end characters are the curly brackets (<tt>{</tt>)
and ( } ).
and (<tt>}</tt>).
 
The following is an example of an '''Html''' statement specification:
The following is an example of an <var>Html</var> statement specification:
<pre>
<p class="code">html
html
<form method="POST" action="processform">
<form method="POST" action="processform">
<br>
&lt;br>
Last name: <input type="text"
Last name: <input type="text" name="lname" value="{%LNAME}">
name="lname" value="{%LNAME}">
</form>
</form>
end html
end html
</pre>
</p>
The syntax of the '''Html''' and '''Text''' blocks is shown below:
 
The syntax of the <var>Html</var> and <var>Text</var> blocks is shown below:
  Html [options]
<p class="syntax"><span class="literal">Html</span> <span class="squareb">[</span><span class="term">options</span><span class="squareb">]</span>
  body
<span class="term">body
  block_end_line
block_end_line</span>
 
</p>
or  
 
or
  Text [options]
  body
<p class="syntax"><span class="literal">Text</span> <span class="squareb">[</span><span class="term">options</span><span class="squareb">]</span>
  block_end_line
<span class="term>body
 
block_end_line</span>
''options'', ''body'', and ''block_end_line'' are discussed below.
</p>
 
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:
<var class="term">options</var>, <var class="term">body</var>, and <var class="term">block_end_line</var> are discussed below.
* 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
The components of the <var>Html</var> or <var>Text</var> block are discussed in the following sections. The <var>Html</var> (or <var>Text</var>) block can be used in contexts other than the production of a web page. For example, it can be used:
* To populate a $list, using the $LIST_CAPTURE function
<ul>
* To send lines over a Janus Sockets connection, using the $SOCK_CAPTURE function
<li>To store lines in a temporary procedure or sequential dataset, using the <var>USE</var> command
* 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:
<li>To populate a <var>Stringlist</var>, using the <var>[[#toOption|To]]</var> option on the <var>Html</var>/<var>Text</var> statement
* User Language is visually close to the output.
<li>To populate a <var>[[$lists|$list]]</var>, using the <var>[[$List_Capture]]</var> function
* Literal text does not need to be enclosed in apostrophes.
<li>To send lines over a <var class="product">Janus Sockets</var> connection, using the <var>[[$Sock_Capture]]</var> function
* The Print keyword is not necessary.
<li>To prepare output processed by some other program, when the output is created by something like a <var>BATCH2</var> or <var>RCL</var> connection to <var class="product">Model 204</var>
* Any valid Model 204 expression can be included inside an Html block, not just literals, %variables, fieldnames, $functions, and a few other constructs.
</ul>
* The With and And keywords are not needed between expressions.
* Apostrophes do not need to be doubled, as in:  
Here are some advantages of the <var>Html</var>/<var>Text</var> block:
 
<ul>
  print <nowiki>'Just say ''No'''</nowiki>
<li><var class="product">User Language</var> is visually close to the output.
 
<li>Literal text does not need to be enclosed in apostrophes.
The following is an example of an Html block using JavaScript to illustrate applications of the '''Html/Text''' options:
<li>The <var>Print</var> keyword is not necessary.
<pre>
<li>Any valid <var class="product">Model 204</var> expression can be included inside an <var>Html</var> block, not just literals, %variables, fieldnames, $functions, and a few other constructs.
html nocont exprs '!{' expre '}!'
<li>The <var>With</var> and <var>And</var> keywords are not needed between expressions.
<li>Apostrophes do not need to be doubled, as in:
<p class="code">print <nowiki>'Just say ''No'''</nowiki> </p>
</ul>
The following is an example of an <var>Html</var> block using JavaScript to illustrate applications of the <var>Html</var>/<var>Text</var> options:
<p class="code">html nocont exprs '!{' expre '}!'
<nowiki><html>
<nowiki><html>
<head>
<head>
Line 71: Line 75:
name=prompt("Person's name","Type name here");
name=prompt("Person's name","Type name here");
end html
end html
 
%s1='if (name=="'
%s1='if (name=="'
fr where rectype='PHONE'
fr where rectype='PHONE'
Line 78: Line 82:
   %s1='else if (name=="'
   %s1='else if (name=="'
end for
end for
 
html nocont exprs '!{' expre '}!'
html nocont exprs '!{' expre '}!'
  else {alert ("Unkown person")};
else {alert ("Unkown person")};
  -->
-->
  </script>
</script>
  </body>
</body>
  </html>
</html>
end html</nowiki>
end html</nowiki>
</pre>
</p>
'''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.
<var>Html</var> statement options used in this example:
* Exprs and Expre let you use characters other than the curly brackets ( { } ) to demarcate expressions. The curly bracket characters are necessary in JavaScript.
<ul>
<li><var>Nocont</var> 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.
<li><var>Exprs</var> and <var>Expre</var> let you use characters other than the curly brackets (<tt>{ }</tt>) to demarcate expressions. The curly bracket characters are necessary in JavaScript.
</ul>
The <var>Html</var> block is available to any customer who owns any of the following products:
<ul>
<li><var class="product">Fast/Unload User Language Interface</var>
<li><var class="product">Janus SOAP</var>
<li><var class="product">Janus Sockets</var>
<li><var class="product">Janus Web Server</var>
<li><var class="product">Sirius Functions</var>
</ul>
The <var>Html</var> block is also available if the <var class="product">Limited Janus Web Server</var> capability is available.


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==
==Options: Html or Text block options==
The various options for an Html or Text block are introduced after the Html or Text
The various options for an <var>Html</var> or <var>Text</var> block are introduced after the <code>Html</code> or <code>Text</code>
keyword. They are described in the following subsections.
keyword. They are described in the following subsections.
===Data, Print, Audit, or Trace===
===Data, Print, Audit, or Trace===
These keywords indicate that the Html block consists of only the text that follows the
These keywords indicate that the <var>Html</var> 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.
keyword on the logical line: that is, there is no <var>End Html</var> statement to end the block.
The Print, Audit, and Trace keywords provide the same functionality as the PrintText, AuditText, TraceText
The <var>Print</var>, <var>Audit</var>, and <var>Trace</var> keywords provide the same functionality as the <var>PrintText</var>, <var>AuditText</var>, <var>TraceText</var>
statements. These statements, along with ReturnText, and SetText (which don't have Text/Html statement keyword equivalents) are sometimes called [[Targeted Text statements|targeted Text statements]].  
statements. These statements, along with <var>ReturnText</var>, and <var>SetText</var> (which don't have <var>Text</var>/<var>Html</var> statement keyword equivalents) are sometimes called [[Targeted Text statements|targeted Text statements]].
 
Prior to Sirius Mods version 7.2, only the Data keyword had this effect, and the Print,
Prior to Sirius Mods version 7.2, only the <var>Data</var> keyword had this effect, and the <var>Print</var>,
Audit, and Trace keywords did not exist. The ReturnText and SetText stetements were added to the Text statement in Sirius Mods version 7.8.
<var>Audit</var>, and <var>Trace</var> keywords did not exist. The <var>ReturnText</var> and <var>SetText</var> stetements were added to the <var>Text</var> statement in <var class="product">Sirius Mods</var> version 7.8.
 
Any Html statement keywords that appear after a Data, Print, Audit, or Trace keyword
Any <var>Html</var> statement keywords that appear after a <var>Data</var>, <var>Print</var>, <var>Audit</var>, or <var>Trace</var> keyword
are processed not as keywords but simply as text. If you want to specify keywords in
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,
addition to a <var>Data</var>, <var>Print</var>, <var>Audit</var>, or <var>Trace</var> keyword, they must appear before <var>Data</var>, <var>Print</var>,
Audit, or Trace to be treated as a keyword.
<var>Audit</var>, or <var>Trace</var> to be treated as a keyword.
 
All other Html block processing, including expression processing, is performed on the
All other <var>Html</var> block processing, including expression processing, is performed on the
line as if it were inside an Html block. The exception is Nodummy processing, because
line as if it were inside an <var>Html</var> block. The exception is <var>Nodummy</var> processing, because
dummy string replacement is performed before the Html statement is parsed.
dummy string replacement is performed before the <var>Html</var> statement is parsed.
 
====Data or Print====
====Data or Print====
Either of these keywords can be thought of as providing a single-line
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
<var>Html</var>/<var>Text</var> statement which can still be much easier to type and read
than a User Language PRINT statement, as in:
than a <var class="product">User Language</var> <var>Print</var> statement, as in:
 
<p class="code">html data Don't need to worry about apostrophes
  html data Don't need to worry about apostrophes
text print {%i} + {%j} = {%i + %j}
  test print {%i} + {%j} = {%i + %j}
</p>
 
The following is an equivalent alternative to the second statement in the
The following is an equivalent alternative to the second statement in the
preceding example.
preceding example:
 
<p class="code">[[PrintText statement|PrintText]] {%i} + {%j} = {%i + %j}
  [[PrintText statement|PrintText]] {%i} + {%j} = {%i + %j}
</p>
 
The ''PrintText'' statement has the same effect as a Text Print statement.
The <var>PrintText</var> statement has the same effect as a <var>Text Print</var> statement.
The ''PrintText'' keyword is simply a merging and reordering of ''Text
The <var>PrintText</var> keyword is simply a merging and reordering of <var>Text
Print'' to emphasize the principle action. The lone difference between
Print</var>to emphasize the principle action. The lone difference between
PrintText and Text Print is that PrintText cannot be used if you want to
<var>PrintText</var> and <var>Text Print</var> is that <var>PrintText</var> cannot be used if you want to
include other Html/Text options, as in:
include other <var>Html</var>/<var>Text</var> options, as in:
 
<p class="code">text noexpr print The set is {2, 3, 5, 8, 13, ...}
  text noexpr print The set is {2, 3, 5, 8, 13, ...}
</p>
 
The Data keyword is available in ''Sirius Mods 6.2'' and later. The Print keyword
The <var>Print</var> keyword and the <var>PrintText</var> statement are available in <var class="product">Sirius Mods</var> 7.2 and later.
and the PrintText statement are available in ''Sirius Mods 7.2'' and later.
 
====Audit====
====Audit====
This keyword provides a single-line Html/Text statement that functions
This keyword provides a single-line <var>Html</var>/<var>Text</var> statement that functions
like a User Language AUDIT statement, that is, routing subsequent text
like a <var class="product">User Language</var> <var>Audit</var> statement, that is, routing subsequent text
to the audit trail.
to the audit trail.
 
For example, this statement directs the text content to the audit trail:
For example, this statement directs the text content to the audit trail:
 
<p class="code">text audit It ({$time}) was the best of times
  text audit It ({$time}) was the best of times
</p>
 
The following is an equivalent alternative to the preceding example.
The following is an equivalent alternative to the preceding example.
 
<p class="code">[[AuditText statement|AuditText]] It ({$time}) was the best of times
  [[AuditText statement|AuditText]] It ({$time}) was the best of times
</p>
 
As with the <var>PrintText</var> keyword above, the <var>AuditText</var> statement has the
As with the PrintText keyword above, the AuditText statement has the
same effect as a <var>Text Audit</var> statement, except it cannot be used if you
same effect as a Text Audit statement, except it cannot be used if you
want to include additional <var>Html</var>/<var>Text</var> <var>Options</var>.
want to include additional Html/Text options.
 
The <var>Audit</var> keyword and the <var>AuditText</var> statement are available as of <var class="product">Sirius Mods</var> 7.2.
The Audit keyword and the AuditText statement are available as of ''Sirius Mods 7.2''.
====Trace====
====Trace====
This keyword provides a single-line <var>Html/Text</var> statement that is the
This keyword provides a single-line <var>Html</var>/<var>Text</var> statement that is the
same as a User Language <var>[[Trace statement|Trace]]</var> statement, that is, routing
same as a <var class="product">User Language</var> <var>[[Trace statement|Trace]]</var> statement, that is, routing
subsequent text to the trace destination (which may be the audit trail,
subsequent text to the trace destination (which may be the audit trail,
print device, or CCATEMP trace table, or a combination of them, as specified in the [[ULTRACE parameter]]).
print device, or CCATEMP trace table, or a combination of them, as specified in the <var>[[ULTRACE parameter]]</var>).
For example, this statement directs the text content by default to the
For example, this statement directs the text content by default to the
audit trail:
audit trail:
Line 174: Line 182:
<p class="code"> [[TraceText statement|TraceText]] This day ({$date}) is unlike any other
<p class="code"> [[TraceText statement|TraceText]] This day ({$date}) is unlike any other
</p>
</p>
As with the <code>PrintText</code> keyword above, the <var>TraceText</var>
As with the <var>PrintText</var> keyword above, the <var>TraceText</var>
statement has the same effect as a <var>Text Trace</var> statement, except it
statement has the same effect as a <var>Text Trace</var> statement, except it
cannot be used if you want to include additional <var>Html/Text</var> options.
cannot be used if you want to include additional <var>Html</var>/<var>Text</var> options.
The <var>Trace</var> keyword and the <var>TraceText</var> statement are available as of <var class="product>Sirius Mods</var> version 7.2.
The <var>Trace</var> keyword and the <var>TraceText</var> statement are available as of <var class="product">Sirius Mods</var> version 7.2.
 
===Ent_print===
===Ent_print===
The Ent_print keyword overrides the current $ENT_PRINT setting for character entity
The <var>Ent_print</var> keyword overrides the current <var>[[$Ent_Print]]</var> setting for character entity
translation over the Html block. Ent_print must be followed by one of these keywords:
translation over the <var>Html</var> block. <var>Ent_print</var> must be followed by one of these keywords:
<table>
<table>
<tr><td>'''Off'''</td><td>No character entity translation will occur over the Html block.</td></tr>
<tr><td><var>Off</var></td><td>No character entity translation will occur over the Html block.</td></tr>
<tr><td>'''On'''</td><td>All data printed by the Html statement will undergo character entity translation.</td></tr>
<tr><td><var>On</var></td><td>All data printed by the Html statement will undergo character entity translation.</td></tr>
<tr><td>'''Var'''</td><td>Only the results of expressions will undergo character entity translation.</td></tr></table>
<tr><td><var>Var</var></td><td>Only the results of expressions will undergo character entity translation.</td></tr></table>
 
Character entity translation is the process of converting a single character that might be
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
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
example, if a "less than" sign (<tt><</tt>) appears in HTML text, it should typically be represented
as <nowiki>&lt;</nowiki> to prevent an HTML processor from mistakenly interpreting it as the start of an
as <code>&amp;lt;</code> to prevent an HTML processor from mistakenly interpreting it as the start of an
HTML tag.
HTML tag.
 
When entity translation is performed, the default translations are &to <nowiki>&amp;</nowiki>, <to
When entity translation is performed, the default translations are "ampersand" (<tt>&</tt>) to <code>&amp;amp;</code>, "less than" (<tt><</tt>) to <code>&amp;lt;</code>, and "double quotation mark" (<tt>"</tt>) to <code>&amp;quot;</code>. These defaults should
<nowiki>&lt;</nowiki> and the double quotation mark character (") to <nowiki>&quot;</nowiki>. These defaults should
be sufficient for most HTML and XML applications (though XML might also require
be sufficient for most HTML and XML applications (though XML might also require
translation of the single quotation mark character (') to <nowiki>&apos;</nowiki> if attributes are
translation of the single quotation mark character (<tt>'</tt>) to <code>&amp;apos;</code> if attributes are
enclosed in single quotation marks), but they can be modified with the $ENT_TAB
enclosed in single quotation marks, but they can be modified with the <var>[[$Ent_Tab]]</var> function.
function.
The <var>Ent_print</var> keyword is a compile-time option that affects only what is inside the <var>Html</var>
block and that is not affected by evaluation time setting of <var>$Ent_Print</var>, even within the
<var>Html</var> block. If no <var>Ent_print</var> keyword is present on the <var>Html</var> statement, character entity
translation is controlled by the evaluation-time <var>$Ent_Print</var> setting.


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===
===LiteralsToTemp===
The LiteralsToTemp option indicates that the literal data in the statement is stored in
The <var>LiteralsToTemp</var> option indicates that the literal data in the statement is stored in
CCATEMP rather than STBL, avoiding excessive demands on STBL space. Designed
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
for a <var>Text</var> 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
to setting the X'01' bit of the <var>[[SIRCOMP parameter|SIRCOMP]]</var> user parameter (which performs the same function).
function).
===Nocom or Nocomments===
===Nocom or Nocomments===
The Nocomments (abbreviated Nocom) option indicates that lines beginning with an
The <var>Nocomments</var> (abbreviated <var>Nocom</var>) option indicates that lines beginning with an
asterisk (*) are not comment lines. For example:
asterisk (<tt>*</tt>) are not comment lines. For example:
 
<p class="code"><nowiki>HTML NOCOM
  <nowiki> HTML NOCOM
* This line will go to the output
  * This line will go to the output
END HTML</nowiki> </p>
  END HTML</nowiki>
===Nocont or Nocontinuations===
===Nocont or Nocontinuations===
The Nocontinuations (abbreviated Nocont) option causes trailing dashes to cease
The <var>Nocontinuations</var> (abbreviated <var>Nocont</var>) option causes trailing dashes to cease
being treated as line continuations. For example, the following statement will cause the
being treated as line continuations. For example, the following statement will cause the
output to appear on two separate lines:
output to appear on two separate lines:
 
<p class="code"><nowiki>HTML NOCONT
<nowiki> HTML NOCONT
English:            B-
  English:            B-
Social Studies:      C
  Social Studies:      C
END HTML</nowiki>  
  END HTML</nowiki>
</p>
 
===Nodum or Nodummy===
===Nodum or Nodummy===
The Nodummy (abbreviated Nodum) option stops dummy string substitution. For
The <var>Nodummy</var> (abbreviated <var>Nodum</var>) option stops dummy string substitution. For
example, the following statement will cause the literal string ?&W to be output without
example, the following statement will cause the literal string <code>?&W</code> to be output without
global variable substitution:
global variable substitution:
 
<p class="code">HTML NODUM
  HTML NODUM
Hello, ?&W
  Hello, ?&W
END HTML </p>
  END HTML
===Noell or Noellipses===
===Noell or Noellipses===
With the Noellipses (abbreviated Noell) option, a trailing ellipsis (...) is not treated as
With the <var>Noellipses</var> (abbreviated <var>Noell</var>) option, a trailing ellipsis (<tt>...</tt>) is not treated as
a concatenation operator. For example:
a concatenation operator. For example:
 
<p class="code">HTML NOELL
  HTML NOELL
These lines are not joined...
  These lines are not joined...
They will appear on different lines.
  They will appear on different lines.
END HTML </p>
  END HTML
===Noexpr or Noexpressions===
===Noexpr or Noexpressions===
If you do not want expression substitution, specify Noexpr or Noexpressions. For
If you do not want expression substitution, specify <var>Noexpr</var> or <var>Noexpressions</var>. For example:
example:
<p class="code">HTML NOEXPR
  HTML NOEXPR
{This will be sent directly to output}
  {This will be sent directly to output}
END HTML </p>
  END HTML
===Raw===
===Raw===
The Raw option acts as Nocom, Nocont, Nodum, Noell, and Noexpr all at once.
The <var>Raw</var> option acts as <var>Nocom</var>, <var>Nocont</var>, <var>Nodum</var>, <var>Noell</var>, and <var>Noexpr</var> all at once.
===Noend===
===Noend===
The Noend option eliminates the block end line. Thus, the block will terminate at the
The <var>Noend</var> option eliminates the block end line. Thus, the block will terminate at the
end of the procedure. For example:
end of the procedure. For example:
  PROC FOO
<p class="code">PROC FOO
  HTML NOEND
HTML NOEND
  Now we are in HTML.
Now we are in HTML.
  END HTML
END HTML
  Still in HTML.
Still in HTML.
  END PROC
END PROC </p>
 
===Exprs or Exprstart===
===Exprs or Exprstart===
The Exprstart (abbreviated Exprs) option specifies a string, up to three characters
The <var>Exprstart</var> (abbreviated <var>Exprs</var>) option specifies a string, up to three characters
long, that begins an expression within the block body. The default is a left curly brace
long, that begins an expression within the block body. The default is a left curly brace (<b>{</b>). For example:
( { ). For example:
<p class="code">html exprs go expre stp
<pre>
html exprs go expre stp
   The answer is go8*9stp
   The answer is go8*9stp
end html
end html
</pre>
</p>
It is probably best to use start and end sequences that are not likely to occur in the literal
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
text in the <var>Html</var>/<var>Text</var> block and that clearly demarcate expressions from literal text. The
"go" and "stp" in the example above are actually not very good choices.
<code>go</code> and <code>stp</code> 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
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:
start string, instead of using the <var>Exprs</var> option. For example:
<pre>
<p class="code"><nowiki>html
<nowiki>html
   <script>
   <script>
     {{alert("User error")}
     {{alert("User error")}
   </script>
   </script>
end html</nowiki>
end html</nowiki>
</pre>
</p>
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 &mdash; one might want the expression end to mirror the expression start:
Note that because the double open-curly-brace (<b>{{</b>) is not treated as an expression start, the close-curly-brace (<b>}</b>) is not treated as an expression end, since the compiler is not processing an expression where it appears.
<pre>
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 <var class="product">User Language</var> expression. Probably the only compelling reason to change the expression end characters is aesthetics or readability &mdash; one might want the expression end to mirror the expression start.
<nowiki>html exprs '{<' expre '>}'
<p class="code"><nowiki>html exprs '{<' expre '>}'
   <script>
   <script>
     var foobar = "{<%foobar>}"
     var foobar = "{<%foobar>}"
Line 293: Line 296:
   <script>
   <script>
end html</nowiki>
end html</nowiki>
</pre>
</p>
One can even use the same set of characters as expression start and end characters:
One can even use the same set of characters as expression start and end characters:
<pre>
<p class="code"><nowiki>html exprs // expre //
<nowiki>html exprs // expre //
   <script>
   <script>
     var foobar = "//%foobar//"
     var foobar = "//%foobar//"
Line 302: Line 304:
   <script>
   <script>
   end html</nowiki>
   end html</nowiki>
</pre>
</p>
The above example is simply intended to illustrate a point and should not be considered a recommendation.
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
'''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
to enclose those characters in single quotation marks (as above) in your <var>Exprs</var> and
Expre specifications. Otherwise, multiple-character combinations involving certain
<var>Expre</var> specifications. Otherwise, multiple-character combinations involving certain
special characters (including these six, for example: = ¬ ( ) < > ) cause M204.0580
special characters (including these six, for example: <code>= , ( ) < ></code> ) cause M204.0580 errors.
errors.
 
===Expre or Exprend===
===Expre or Exprend===
The Exprend (abbreviated Expre) option specifies a string that ends an expression
The <var>Exprend</var> (abbreviated <var>Expre</var>) option specifies a string that ends an expression
within the block body. The default is a right curly brace ( } ).
within the block body. The default is a right curly brace (<b>}</b>).
===End===
===End===
To set your own block_end_line, you can use the End option. If the text of the line you
To set your own <var class="term">block_end_line</var>, you can use the <var>End</var> option. For example:
are specifying contains spaces, enclose it in single quotation marks, as in:
<p class="code">text to %list end listEnd
  End 'END TEXT BLOCK'
  Four score
The default block_end_line value is '''End Html''' (for the Html block) or '''End Text''' (for the
  and seven
Text block).
listEnd
</p>


===The To option for %stringlist, Audit, Print, or Trace===
If the text of the line you
The <var>To</var> option lets you direct the contents of the <var>Html</var> or <var>Text</var> block to a <var>StringList</var> or to the destinations associated with the <var class="product">User Language</var> statements <var>Audit</var>, <var>Print</var>, or <var>Trace</var>.
are specifying contains spaces, enclose it in single quotation marks. For example:
====To %stringlist====
<p class="code">text to %list end 'end text block'
Here is how <var>Text To</var> populates a <var>StringList</var> with some names:
  Our
  forebears
end text block
</p>
 
The default <var class="term">block_end_line</var> value is <code>End Html</code> (for the <var>Html</var> block) or <code>End Text</code> (for the <var>Text</var> block).
<div id="toOption"></div>
 
===To %stringlist, To Audit, To Print, or To Trace===
The <var>To</var> option lets you direct the contents of the <var>Html</var> or <var>Text</var> block to a <var>Stringlist</var> or to the destinations associated with the <var class="product">User Language</var> statements <var>Audit</var>, <var>Print</var>, or <var>Trace</var>.
====To %stringlist [= New]====
The <var>To</var> option, when used to add data to a <var>Stringlist</var>, has an optional <code>= New</code> clause following the <var>Stringlist</var>, which first creates a new <var>Stringlist</var> instance.  Without <code>= New</code>, the data is appended to the <var>Stringlist</var>.
 
Here is how <var>Text To</var> populates a <var>Stringlist</var> with some names:
<p class="code">%jumps is object stringList
<p class="code">%jumps is object stringList
...
...
Line 336: Line 354:
end text
end text
</p>
</p>
 
The <code>text to %jumps = new</code> statement above is an optional simplification (as of <var class="product">Sirius Mods</var> version 7.6) of the sequence:
The <code>text to %jumps = new</code> statement above is an optional simplification (as of <var class="product">Sirius Mods</var> version 7.6) of the sequence:
<p class="code">%jumps = new
<p class="code">%jumps = new
text to %jumps
text to %jumps
</p>
</p>
 
There are many advantages to using <var>Html To</var> or <var>Text To</var> over a plain <var>Html</var> statement
There are many advantages to using <var>Html To</var> or <var>Text To</var> over a plain <var>Html</var> statement
wih <var>$List_Capture</var>:
wih <var>$List_Capture</var>:
* <var>$List_Capture</var> or an equivalent is not available for <var>StringLists</var>.
<ul>
* Because <var>Html To</var> does not go through generic Print processing, it has a somewhat more efficient processing path, that is, it uses less CPU.
<li> <var>$List_Capture</var> or an equivalent is not available for <var>Stringlists</var>.
* Because <var>Html To</var> does not go through generic Print processing, the generated quads take somewhat less space.
<li> Because <var>Html To</var> does not go through generic Print processing, it has a somewhat more efficient processing path, that is, it uses less CPU.
* An <var>Html To</var> block does not affect the current <var>$List_Capture</var> setting, so it eliminates the need to worry about saving and restoring the <var>$List_Capture</var> setting.
<li> Because <var>Html To</var> does not go through generic Print processing, the generated quads take somewhat less space.
* A <var>To</var> option on an <var>Html</var> statement is simply less and cleaner code than an <var>Html</var> statement inside a <var>$List_Capture</var> bracket.
<li> An <var>Html To</var> block does not affect the current <var>$List_Capture</var> setting, so it eliminates the need to worry about saving and restoring the <var>$List_Capture</var> setting.
* If an expression inside an <var>Html To</var> block invokes a User Language method, and that method does a Print statement, the output of that <var>Print</var> statement does not end up on the <var>StringList</var> target of the <var>Html</var> statement. Inside a <var>$List_Capture</var> bracket, the output of such a <var>Print</var> statement ends up on the <var>$List_Capture</var>'s target $list.
<li> A <var>To</var> option on an <var>Html</var> statement is simply less and cleaner code than an <var>Html</var> statement inside a <var>$List_Capture</var> bracket.
 
<li> If an expression inside an <var>Html To</var> block invokes a User Language method, and that method does a Print statement, the output of that <var>Print</var> statement does not end up on the <var>Stringlist</var> target of the <var>Html</var> statement. Inside a <var>$List_Capture</var> bracket, the output of such a <var>Print</var> statement ends up on the <var>$List_Capture</var>'s target $list.
The <var>To</var> option of the <var>Html</var> or <var>Text</var> statement appends to the target <var>StringList</var>, so it does not
</ul>
instantiate the <var>StringList</var> if it is null. In fact, a null <var>StringList</var> target for an <var>Html To</var> results
The <var>To</var> option of the <var>Html</var> or <var>Text</var> statement appends to the target <var>Stringlist</var>, so it does not
instantiate the <var>Stringlist</var> if it is null. In fact, a null <var>Stringlist</var> target for an <var>Html To</var> results
in a null-pointer request-cancelling error.
in a null-pointer request-cancelling error.
 
Even if the ultimate target of an <var>Html</var> or <var>Text</var> statement is a plain $list, the <var>Html To</var> can still
Even if the ultimate target of an <var>Html</var> or <var>Text</var> statement is a plain $list, the <var>Html To</var> can still
be used to gain some of the benefits of this structure without much extra code by using
be used to gain some of the benefits of this structure without much extra code by using
the Stringlist object <var>MoveFromId</var> and <var>MoveToId</var> methods:
the <var>Stringlist</var> object <var>[[MoveFromId (Stringlist subroutine)|MoveFromId]]</var> and <var>[[MoveToId (Stringlist subroutine)|MoveToId]]</var> methods:
 
<p class="code">%htmlList is object stringList
<p class="code">%htmlList is object stringList
%list is float
%list is float
Line 373: Line 392:


====To Audit, To Print, To Trace====
====To Audit, To Print, To Trace====
 
These options direct the contents of an <var>Html</var> or <var>Text</var> block or line to the destinations
These options direct the contents of an <var>Html</var> or <var>Text</var> block or line to the destinations
associated with the User Language statements <var>Audit</var>, <var>Print</var>, or <var>Trace</var>. Respectively
associated with the <var class="product">User Language</var> statements <var>Audit</var>, <var>Print</var>, or <var>Trace</var>. Respectively
these destinations are the journal/audit trail, the current print output device, or the trace
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
destination (which may be the audit trail, print device, or CCATEMP trace table, or a
combination of them).
combination of them).
 
For example, the following statement directs the <var>Text</var> block content to the audit trail:
For example, the following statement directs the <var>Text</var> block content to the audit trail:
 
<p class="code">text to audit
<p class="code">text to audit
   Now ({$time}) is the time for all good men
   Now ({$time}) is the time for all good men
Line 387: Line 406:
end text
end text
</p>
</p>
 
To direct a single line of output, you can use the <var>Data</var> keyword ([[#Data, Print, Audit, or Trace|"Data, Print, Audit, or Trace"]]) as in the following:
To direct a single line of output, you can use the <var>Data</var> keyword ([[#Data, Print, Audit, or Trace|"Data, Print, Audit, or Trace"]]) as in the following:
 
<p class="code">text to audit Data It ({$time}) was the best of times
<p class="code">text to audit Data It ({$time}) was the best of times
</p>
</p>
 
Or, simpler, you can use the <var>Audit</var> keyword like this:
Or, simpler, you can use the <var>Audit</var> keyword like this:
 
<p class="code">text Audit It ({$time}) was the best of times
<p class="code">text Audit It ({$time}) was the best of times
</p>
</p>
 
Furthermore, the [[Targeted Text statements|targeted Text statements]] provide an alternative syntax, in which the "target" (Print, Audit, Trace) is at the start of the statement, making them more "natural" analogues of the <var>Print</var>, <var>Audit</var> and <var>[[Trace statement|Trace]]</var> statements.  For example:
Furthermore, the [[Targeted Text statements|targeted Text statements]] provide an alternative syntax, in which the "target" (<var>Print</var>, <var>Audit</var>, <var>Trace</var>) is at the start of the statement, making them more "natural" analogues of the <var>Print</var>, <var>Audit</var> and <var>Trace</var> statements.  For example:
<p class="code">auditText It ({$time}) was the best of times
<p class="code">auditText It ({$time}) was the best of times
</p>
</p>


==Body: Html or Text block body==
==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
Each line of an <var>Html</var> or <var>Text</var> block, up to the block_end_line, creates a line of literal
output, with the following substitutions:
output, with the following substitutions:
<table border="1">
<table border="1">
<tr><td>Expressions</td><td> 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.</td></tr>
<tr><td>Expressions</td>
<tr><td>Dummy strings</td><td> 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??!!.</td></tr>
<td>An expression is begun by a left brace (<b>{</b>) or a user-defined string specified with the <var>Exprs</var> option, and it is ended by a right brace (<b>}</b>) or a user-defined string specified with the <var>Expre</var> option. Text within the expression is evaluated as if it were the right-hand side of a <var class="product">User Language</var> assignment; that value is produced, rather than literal output.</td></tr>
<tr><td>Continuation</td><td> 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.</td></tr>
<tr><td nowrap>Dummy strings</td>
<tr><td>Ellipses</td><td> 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.</td></tr>
<td>Normally, as in other <var class="product">Model 204</var> input, dummy strings are substituted under the control of the <var>SUB</var> parameter. This can be suppressed with the <var>Nodummy</var> option, which may be useful if your block contains strings like "what the heck??!!".</td></tr>
<tr><td>Indentation</td><td> 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.</td></tr></table>
 
<tr><td>Continuation</td>
<td>Continuation allows text from multiple lines to be printed on one line by adding a hyphen (<b>-</b>) to all preceding lines in the block. All spacing and indentation following the hyphen is ignored. This option works inside an expression.</td></tr>
 
<tr><td>Ellipses</td>
<td>Ellipses allow text from multiple command lines to be printed on one line by adding three dots (<b>...</b>) to all preceding command lines. Leading spaces will be included. This option will not work inside an expression.</td></tr>
 
<tr> <td>Indentation</td>
<td>Except for continuation lines, the output of a line is indented by as many spaces as the input is indented relative to the <var>Html</var> or <var>Text</var> statement that begins the block.</td></tr></table>
===block_end_line: Html or Text block end===
===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
By default, the line that ends an <var>Html</var> or <var>Text</var> block is <var>End Html</var> for an <var>Html</var> block, or it
is End Text for a Text block. You can specify your own end line with the End option,
is <var>End Text</var> for a <var>Text</var> block. You can specify your own end line with the <var>End</var> option,
as described above in “End”.
as described above in [[#End|End]].
===Printing of expression results===
===Printing of expression results===
Model 204 expressions enclosed in the expression start and end characters are printed
<var class="product">Model 204</var> 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
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.
HTML block. For example, <code>Text Print {$date}</code> produces a result like <code>08-02-29</code>.
===Character entity substitution===
===Character entity substitution===
Under ''Sirius Mods 6.2'' and later, the result of the expression might undergo character
The result of the expression might undergo character
entity substitution under control of the $ENT_PRINT setting or the Ent_print parameter
entity substitution under control of the <var>$Ent_Print</var> setting or the <var>Ent_print</var> parameter
on the Html/Text statement. An expression can explicitly override the default
on the <var>Html</var>/<var>Text</var> statement. An expression can explicitly override the default
$ENT_PRINT and Ent_print processing by immediately following the expression start
<var>$Ent_Print</var> and <var>Ent_print</var> processing by immediately following the expression start
character(s) with one of the following special characters:
character(s) with one of the following special characters:
<table border="1">
<table class="thJustBold">
<tr><td>'''&'''</td><td> Perform character entity substitution regardless of the current $ENT_PRINT
<tr><th>&</th>
setting and the Ent_print setting on the Html statement.</td></tr>
<td>Perform character entity substitution regardless of the current <var>$Ent_Print</var>
<tr><td>'''!''' </td><td>Do not perform character entity substitution, regardless of the current
setting and the <var>Ent_print</var> setting on the <var>Html</var> statement.</td></tr>
$ENT_PRINT setting and the Ent_print setting on the Html statement.</td></tr>
<tr><td>'''*'''</td><td>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.</td></tr></table>


'''Note:''' The asterisk (*) suppresses the printing of the return code but not the
<tr><th>!</th>
output from a $LIST_PRINT or $WEB_SEL function.
<td>Do not perform character entity substitution, regardless of the current
<var>$Ent_Print</var> setting and the <var>Ent_print</var> setting on the <var>Html</var> statement.</td></tr>


<tr><th>*</th><td>Do not print the results of the expression. This can be useful if
embedding a $function that itself prints output, such as <var>[[$List_Print]]</var> or <var>[[$Web_Sel]]</var>, or a $function that simply sets some environmental parameter (such as <var>[[$Web_Set]]</var> or <var>[[$Resetn]]</var>) whose return value should not be displayed.</td></tr></table>
<p class="note">'''Note:''' The asterisk (<tt>*</tt>) suppresses the printing of the return code but not the
output from a <var>$List_Print</var> or <var>$Web_Sel</var> function. </p>
In the following example, character entity substitution is explicitly suppressed for the
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
contents of <code>%FONT</code> and explicitly forced for <code>%COMMENT</code>, and the return code from
$LIST_PRINT is suppressed:
<code>$LIST_PRINT</code> is suppressed:
  <nowiki>HTML
 
  {!%FONT}This is in a fancy font</font>
<p class="code"><nowiki>HTML
  <input type="text" name="comment" value="{&%COMMENT}">
{!%FONT}This is in a fancy font</font>
  <br>And here's some stuff<br>
<input type="text" name="comment" value="{&%COMMENT}">
  {*$LIST_PRINT(%LIST)}
<br>And here's some stuff<br>
  END HTML
{*$LIST_PRINT(%LIST)}
</nowiki>
END HTML</nowiki> </p>
<div id="tilde">
<div id="tilde"></div>
<div id="tildeDirectives"></div>
<div id="tildeDirectives"></div>
===The {~} and {~= ... directives}===
===The {~} and {~= ...} directives===
The special expression {~} directs the compiler to replace this expression with the literal
The special expression <b>{~}</b> directs the compiler to replace this expression with the literal
character content of the next expression appearing on the same line. So
character content of the next expression appearing on the same line. So:
<p class="code">printText {~} = {1234:nextPrime}
<p class="code">printText {~} = {1234:nextPrime}
</p>
</p>
displays
displays:
<p class="output">1234:nextPrime = 1237
<p class="output">1234:nextPrime = 1237
</p>
</p>
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
The evaluation of the expression following <b>{~}</b> is carried out as usual. As of Sirius Mods 7.8, you can also specific a <b>~=</b> directive, as in:
<p class="code">printText {~=1234:nextPrime}
<p class="code">printText {~=1234:nextPrime}
</p>
</p>
which displays
This displays:
<p class="output">1234:nextPrime=1237
<p class="output">1234:nextPrime=1237
</p>
</p>
The expression after the ~= directive can be preceded or followed by spaces.
The expression after the <b>~=</b> directive can be preceded or followed by blanks.
Spaces before the expression appear in the output before the expression result (after the equals sign) and spaces after the expression appear in the output after the expression literal (before the equals sign). For example
Blanks before the expression appear in the output before the expression result (after the equal sign), and spaces after the expression appear in the output after the expression literal (before the equal sign). For example,
<p class="code">printText {~= 100:nextPrime  }
<p class="code">printText {~= 100:nextPrime  }
</p>
</p>
displays
displays:
<p class="output">100:nextPrime  = 101
<p class="output">100:nextPrime  = 101
</p>
</p>
If more control of spacing is required, the simple {~} directive should be used, instead.
If more control of spacing is required, the simple <b>{~}</b> directive should be used, instead.
 
As mentioned at the end of the [[#To Audit, To Print, To Trace|"To Audit, To Print, To Trace"]] section above, the <var>PrintText</var> statement is a synonym for the Text Print statement.
As mentioned at the end of the [[#To Audit, To Print, To Trace|To Audit, To Print, To Trace]] section above, the <var>PrintText</var> statement is a synonym for the <var>Text Print</var> statement.
 
==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.


==Table usage==
While the <var>Html</var>/<var>Text</var> statement can provide a convenient typing shorthand relative to a
host of <var>Print</var> statements, and it can make code considerably more readable, it does not
necessarily use any less table space than the comparable <var>Print</var> statements.
Table space can be saved with the <var>Html</var>/<var>Text</var> statement, as follows:
<ul>
<li>By using the <var>[[#toOption|To]]</var> clause and sending the <var>Html</var>/<var>Text</var> statement output directly to a <var>Stringlist</var>, the amount of QTBL space used is reduced.
<li>If the X'01' bit is set in the <var>[[SIRCOMP parameter|SIRCOMP]]</var> user parameter when a program is compiled, string literals are saved in CCATEMP rather than STBL. Since <var>Html</var>/<var>Text</var> statements often have a large quantity of literal text, they can use a lot of STBL space, so the STBL space savings of the <var>SIRCOMP</var> 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
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
access it. When the <var>Html</var>/<var>Text</var> statement uses a <var>To</var> clause, the extra overhead of
CCATEMP data access is reduced, because Html/Text To processing keeps the
CCATEMP data access is reduced, because <var>Html</var>/<var>Text</var> To processing keeps the
CCATEMP pages holding literal data open over as many literals as possible.
CCATEMP pages holding literal data open over as many literals as possible.
 
<p>
Furthermore, for pre-compiled APSY procedures, the literals in CCATEMP do not
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.
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,
Finally, if a user with a large number of <var>Html</var>/<var>Text</var> statement literals is server-swapped,
there is less data to server-swap if literals are kept in CCATEMP
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
(although, the data in CCATEMP does take buffer pool space and might require CCATEMP I/O). </p>
CCATEMP I/O).
</ul>


So there is probably no good general rule of thumb regarding whether the SIRCOMP
So there is probably no good general rule of thumb regarding whether the <var>SIRCOMP</var>
X'01' bit should be set. Probably, unless a site is struggling with server size problems, it
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.
is best and simplest to just keep the literals in STBL.  
 
==See also==
==See also==
<ul>
<ul>

Latest revision as of 20:27, 17 March 2016

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 text 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 Printto 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 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, as specified in the ULTRACE parameter). 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 version 7.2.

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:

OffNo character entity translation will occur over the Html block.
OnAll data printed by the Html statement will undergo character entity translation.
VarOnly 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 &lt; 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 "ampersand" (&) to &amp;, "less than" (<) to &lt;, and "double quotation mark" (") to &quot;. These defaults should be sufficient for most HTML and XML applications (though XML might also require translation of the single quotation mark character (') to &apos; 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.

LiteralsToTemp

The LiteralsToTemp 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. For example:

text to %list end listEnd Four score and seven listEnd

If the text of the line you are specifying contains spaces, enclose it in single quotation marks. For example:

text to %list end 'end text block' Our forebears 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, To Audit, To Print, or To 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 [= New]

The To option, when used to add data to a Stringlist, has an optional = New clause following the Stringlist, which first creates a new Stringlist instance. Without = New, the data is appended to the Stringlist.

Here is how Text To populates a Stringlist with some names:

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

The text to %jumps = new statement above is an optional simplification (as of Sirius Mods version 7.6) of the sequence:

%jumps = new text to %jumps

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 or 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 or 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

Furthermore, the targeted Text statements provide an alternative syntax, in which the "target" (Print, Audit, Trace) is at the start of the statement, making them more "natural" analogues of the Print, Audit and Trace statements. For example:

auditText 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

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 {~} and {~= ...} directives

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

printText {~} = {1234:nextPrime}

displays:

1234:nextPrime = 1237

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

printText {~=1234:nextPrime}

This displays:

1234:nextPrime=1237

The expression after the ~= directive can be preceded or followed by blanks. Blanks before the expression appear in the output before the expression result (after the equal sign), and spaces after the expression appear in the output after the expression literal (before the equal sign). For example,

printText {~= 100:nextPrime }

displays:

100:nextPrime = 101

If more control of spacing is required, the simple {~} directive should be used, instead.

As mentioned at the end of the To Audit, To Print, To Trace section above, the PrintText statement is a synonym for the Text Print statement.

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.

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 server-swapped, 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.

See also