$Ent Tab: Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
(Automatically generated page update) |
||
| (39 intermediate revisions by 3 users not shown) | |||
| Line 2: | Line 2: | ||
<span class="pageSubtitle">retrieve/modify character entity substitution table</span> | <span class="pageSubtitle">retrieve/modify character entity substitution table</span> | ||
<p class=" | <p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $Ent_Tab function.</p> | ||
This function retrieves or modifies the current active character entity translation table. This table is used by <var>$Ent</var> and the | This function retrieves or modifies the current active character entity translation table. This table is used by <var>$Ent</var> and the <var>Print</var> and <var>Html/Text</var> statements when <var>[[$Ent_Print]]</var> is set to <code>VAR</code> or <code>ON</code>. | ||
<var>$Ent_Tab</var> accepts one argument and returns a string result. | <var>$Ent_Tab</var> accepts one argument and returns a string result. | ||
==Syntax== | ==Syntax== | ||
<p class="syntax">< | <p class="syntax"><span class="term">%result</span> = $Ent_Tab(string) | ||
</p> | </p> | ||
===Syntax terms=== | |||
<table class="syntaxTable"> | |||
<tr><th>%result</th> | |||
<td>Set to the character entity substitution table before the call.</td></tr> | |||
<tr><th>%string</th> | |||
<td>The new entity translation table to be used by <var>$Ent</var> and <var>$Ent_Print</var>. It contains a blank-delimited set of token pairs, the first of each pair being the character to undergo substitution and the second the entity name to be substituted. | |||
<p> | |||
The default substitution string which is set at the start of every request is <code>< lt & amp " quot</code>. </p> | |||
<p> | |||
An ampersand (&) is always placed in front of the entity name and a semicolon (;) after when substitution is performed, so these should not be specified in the entity name. Alphanumeric characters '''must''' be specified as the their hexadecimal EBCDIC value, for example the "A" character, must be specified as <code>C1</code>. There is almost never a need to do character entity substitution for alphanumeric characters but this capability is provided for completeness. </p> | |||
<p> | |||
The space or blank character must always be specified as <code>40</code>. Occasionally one might want blanks to be represented as non-breaking spaces, generally indicated by <code>&nobsp;</code>. All other characters can be specified by the EBCDIC character or their hexadecimal values. </p> | |||
<p> | |||
The first parameter is an optional parameter and, if not specified <var>$Ent_Tab</var> simply returns the current character-entity translation table.</p></td></tr> | |||
</table> | |||
==Usage notes== | |||
<ul> | |||
<li>Specifying an invalid substitution table for <var>$Ent_Tab</var> causes request cancellation. | |||
<li>The return value from <var>$Ent_Tab</var> contains no leading or trailing spaces, contains only a single space between tokens, represents any alphanumeric characters as their hexadecimal values and all other characters as themselves, even if these characters are non-displayable. This is the most compact possible representation of a character entity substitution table so there need be no worries about truncation of the result of a <var>$Ent_Tab</var> call at 255 characters — the result of the <var>$Ent_Tab</var> call will always be the same length or shorter than the value used to set the substitution table. | |||
The return value for <var>$Ent_Tab</var> is the <var>$Ent_Tab</var> setting before the function call which makes it easy to save the <var>$Ent_Tab</var> setting and then restore it. In addition, the fact that a <var>$Ent_Tab</var> without parameters simply returns the current substitution table makes it easy to add entities to the current table. | <li>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 <code>&lt;</code> 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 <code>&</code>, "<" to <code>&lt;</code> and the double-quote character to <code>&quot;</code>. | ||
<li>The return value for <var>$Ent_Tab</var> is the <var>$Ent_Tab</var> setting before the function call which makes it easy to save the <var>$Ent_Tab</var> setting and then restore it. In addition, the fact that a <var>$Ent_Tab</var> without parameters simply returns the current substitution table makes it easy to add entities to the current table. | |||
</ul> | |||
==Example== | |||
In this example, the "nobsp" character entity is added to the current substitution table so that blanks in a converted string will be sent as non-breaking spaces, ensuring that the string will not be split to different lines: | In this example, the "nobsp" character entity is added to the current substitution table so that blanks in a converted string will be sent as non-breaking spaces, ensuring that the string will not be split to different lines: | ||
<p class="code"> | <p class="code">* Add nobsp to table, save old table | ||
%ENT_TAB = $Ent_Tab( $Ent_Tab WITH ' 40 nobsp') | |||
HTML | |||
Thank you {& %NAME} for visiting our web site. | |||
It is always a pleasure serving you and | |||
{& %COMPANY} | |||
END HTML | |||
* Back to old table | |||
%ENT_TAB = $Ent_Tab(%ENT_TAB) | |||
</p> | </p> | ||
If a character is specified in the substitution string more than once, the last specification is used — this makes it easy to temporarily override a character entity substitution using the above save and restore technique. So in the above example the local code does not need to worry about whether or not blanks were already undergoing character entity translation. | |||
==Products authorizing {{PAGENAMEE}}== | |||
<ul class="smallAndTightList"> | <ul class="smallAndTightList"> | ||
<li>[[Sirius functions]]</li> | <li>[[List of $functions|Sirius functions]]</li> | ||
<li>[[Fast/Unload User Language Interface]]</li> | <li>[[Fast/Unload User Language Interface]]</li> | ||
<li>[[Janus Open Client]]</li> | <li>[[Media:JoclrNew.pdf|Janus Open Client]]</li> | ||
<li>[[Janus Open Server]]</li> | <li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li> | ||
<li>[[Janus Sockets]]</li> | <li>[[Janus Sockets]]</li> | ||
<li>[[Janus Web Server]]</li> | <li>[[Janus Web Server]]</li> | ||
<li> | <li>Japanese functions</li> | ||
<li>[[Sir2000 Field Migration Facility]]</li> | <li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li> | ||
</ul> | </ul> | ||
[[Category:$Functions|$Ent_Tab]] | [[Category:$Functions|$Ent_Tab]] | ||
Latest revision as of 22:51, 20 September 2018
retrieve/modify character entity substitution table
Note: Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $Ent_Tab function.
This function retrieves or modifies the current active character entity translation table. This table is used by $Ent and the Print and Html/Text statements when $Ent_Print is set to VAR or ON.
$Ent_Tab accepts one argument and returns a string result.
Syntax
%result = $Ent_Tab(string)
Syntax terms
| %result | Set to the character entity substitution table before the call. |
|---|---|
| %string | The new entity translation table to be used by $Ent and $Ent_Print. It contains a blank-delimited set of token pairs, the first of each pair being the character to undergo substitution and the second the entity name to be substituted.
The default substitution string which is set at the start of every request is
An ampersand (&) is always placed in front of the entity name and a semicolon (;) after when substitution is performed, so these should not be specified in the entity name. Alphanumeric characters must be specified as the their hexadecimal EBCDIC value, for example the "A" character, must be specified as
The space or blank character must always be specified as The first parameter is an optional parameter and, if not specified $Ent_Tab simply returns the current character-entity translation table. |
Usage notes
- Specifying an invalid substitution table for $Ent_Tab causes request cancellation.
- The return value from $Ent_Tab contains no leading or trailing spaces, contains only a single space between tokens, represents any alphanumeric characters as their hexadecimal values and all other characters as themselves, even if these characters are non-displayable. This is the most compact possible representation of a character entity substitution table so there need be no worries about truncation of the result of a $Ent_Tab call at 255 characters — the result of the $Ent_Tab call will always be the same length or shorter than the value used to set the substitution table.
- 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
<character entity. A default character entity substitution table is provided which does the basic required character entity mappings for HTML and XML of "&" to&, "<" to<and the double-quote character to". - The return value for $Ent_Tab is the $Ent_Tab setting before the function call which makes it easy to save the $Ent_Tab setting and then restore it. In addition, the fact that a $Ent_Tab without parameters simply returns the current substitution table makes it easy to add entities to the current table.
Example
In this example, the "nobsp" character entity is added to the current substitution table so that blanks in a converted string will be sent as non-breaking spaces, ensuring that the string will not be split to different lines:
* Add nobsp to table, save old table %ENT_TAB = $Ent_Tab( $Ent_Tab WITH ' 40 nobsp') HTML Thank you {& %NAME} for visiting our web site. It is always a pleasure serving you and {& %COMPANY} END HTML * Back to old table %ENT_TAB = $Ent_Tab(%ENT_TAB)
If a character is specified in the substitution string more than once, the last specification is used — this makes it easy to temporarily override a character entity substitution using the above save and restore technique. So in the above example the local code does not need to worry about whether or not blanks were already undergoing character entity translation.