$Ent Print: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (1 revision)
(No difference)

Revision as of 00:37, 26 October 2012

Set automatic character entity substitution

Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $Ent_Print function.

This function retrieves or sets the current automatic character entity substitution setting for PRINT and HTML/TEXT statements. At the start of every request the $Ent_Print setting is OFF meaning no character entity substitution is done for the output from PRINT or HTML statements.

$Ent accepts one argument and returns a string result.

The first argument is the new setting of automatic character entity substitution and must be either

OFF which means no character entity substitution will be done on PRINT or HTML/TEXT statement output.
ON which means character entity substitution will be done on all PRINT and HTML/TEXT statement output.
VAR which means character entity substitution will be done only on variable PRINT and HTML/TEXT statement output, that is anything that is not a string literal or a static variable in a PRINT statement and anything inside a start/end expression bracket in an HTML statement.

This is an optional argument and if not specified or specified as null, the current $Ent_Print setting is not altered.

Syntax

<section begin="syntax" />%result = $Ent_Print(val) <section end="syntax" />

%result is set to the $Ent_Print setting before the call.

Specifying an invalid value for $Ent_Print causes request cancellation.

The $Ent_Print setting can be overridden in an HTML/TEXT statement by the ENT_PRINT setting on that statement or by the special * or ! characters following the expression start string in an expression.

Character entity substitution replaces characters that have special meaning to an HTML or XML processor with their character entity representation. For example, the "<" is represented as the "&lt;" character entity. A default character entity substitution table is provided which does the basic required character entity mappings for HTML and XML of "&amp." to "&amp.amp;", "<" to "&lt;" and the double quote character to "&quot;". The active character entity substitution table can be modified with $Ent_Tab $Ent_Tab.

The return value for $Ent_Print is the $Ent_Print setting before the function call which makes it easy to save the $Ent_Print setting and then restore it. In this example, $Ent_Print is set to 'ON' and then restored to its previous setting.

SUBROUTINE HEADER %ENT_PRINT IS STRING LEN 32 * I'm too lazy to type all those &lt;'s %ENT_PRINT = $Ent_Print('ON') PRINT '<<<<<<<<<<<<<< Header >>>>>>>>>>>>>>' * But shouldn't mess with $Ent_Print setting %ENT_PRINT = $Ent_Print('ON')

Generally, the most useful setting for $Ent_Print is VAR because it's hard to be sure that variable data whether it comes from a database field or from user input doesn't contain special HTML or XML characters. Literal strings, on the other hand, are likely to contain XML or HTML tags so should not undergo character entity substitution. Occasionally, it is useful to place HTML or XML tags in a %variable. If possible, that variable should be STATIC so a VAR setting for $Ent_Print will not modify it. If this is not possible, it is probably best to use the HTML/TEXT statement where a single character after the expression start character(s) (an & or a !) can explicitly force or prevent character entity translation.

Products authorizing $Ent_Print