$Ent Tab

retrieve/modify character entity substitution table

Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Ent_Tab function is to be entered.

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.

The first argument is 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 &OSQ.< lt & amp " quot&CSQ.. 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. Alphanumerics 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 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.

Syntax

<section begin="syntax" />%result = $Ent_Tab(string) <section end="syntax" />

$Ent_Tab Function

%result is set to the character entity substitution table before the call.

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

This $function is new in Version 6.2 of the Sirius Mods.

Products authorizing $Ent_Tab

• Sirius functions
• Fast/Unload User Language Interface
• Janus Open Client
• Janus Open Server
• Janus Sockets
• Janus Web Server
• Japanese functions
• Sir2000 Field Migration Facility