View source for $Ent Tab

{{DISPLAYTITLE:$Ent_Tab}}
<span class="pageSubtitle">retrieve/modify character entity substitution table</span>

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

==Syntax==
<p class="syntax"><span class="term">%result</span> = $Ent_Tab(string)
</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; amp " quot</code>. </p>
<p>
An ampersand (&amp;) 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>&amp;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 &#x2014; 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. 

<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>&amp;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;amp;" to <code>&</code>, "<" to <code>&amp;lt;</code> and the double-quote character to <code>&amp;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:
<p class="code">&#42; Add nobsp to table, save old table
%ENT_TAB = $Ent_Tab( $Ent_Tab WITH ' 40 nobsp')
 
HTML
Thank you {&amp; %NAME} for visiting our web site.
It is always a pleasure serving you and
{&amp; %COMPANY}
END HTML
 
&#42; Back to old table
%ENT_TAB = $Ent_Tab(%ENT_TAB)
</p>

If a character is specified in the substitution string more than once, the last specification is used &#x2014; 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">
<li>[[List of $functions|Sirius functions]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li>
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Web Server]]</li>
<li>Japanese functions</li>
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li>
</ul>

[[Category:$Functions|$Ent_Tab]]