$Ent_Tab

retrieve/modify character entity substitution table

Note: Most Sirius $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 < lt & amp " quot.

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 C1. There is almost never a need to do character entity substitution for alphanumeric characters but this capability is provided for completeness.

The space or blank character must always be specified as 40. Occasionally one might want blanks to be represented as non-breaking spaces, generally indicated by &nobsp;. All other characters can be specified by the EBCDIC character or their hexadecimal values.

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.

Products authorizing $Ent_Tab