XMLENCOD: XML-Encoding Characters

How to:

The XMLENCOD function encodes the following five standard characters when they are encountered in a string:

Character Name

Character

Encoded Representation

ampersand

&

&

greater than symbol

>

>

less than symbol

<

&lt;

double quotation mark

"

&quot;

single quotation mark (apostrophe)

'

&apos;

Syntax: How to XML-Encode Characters

XMLENCOD(inlength, source_string, option, outlength,  output)

where:

inlength

Integer

Is the length of the field containing the source character string, or a field that contains the length.

source_string

Alphanumeric

Is the name of the field containing the source character string or a string enclosed in single quotation marks (').

option

Integer

Is a code that specifies whether to process a string that already contains XML-encoded characters. Valid values are:

  • 0, the default, which cancels processing of a string that already contains at least one XML-encoded character.
  • 1, which processes a string that contains XML-encoded characters.
outlength

Integer

Is the length of the output character string, or a field that contains the length.

Note: The output length, in the worst case, could be six times the length of the input.

output

Integer

Is the field that contains the result, or the format of the output value enclosed in single quotation marks.

Example: XML-Encoding Characters

The file XMLFUNCS is a .csv file that contains some unencoded characters and some XML-encoded characters. The Master File is:

FILE = XMLFUNCS, SUFFIX=COM,$
SEGNAME = SEG01, SEGTYPE=S1,$
FIELD=INSTRING, ALIAS=CHARS, USAGE=A30,ACTUAL=A30,$

The contents of the file follow:

CHARS: &  < >  ,$
ENCODED: &amp; &gt;  ,$
ENCODED: &quot; &apos;   ,$
MIXED:  &amp;  < &gt;   ,$

XMLENCOD XML-encodes any of the supported characters to produce OUTSTRING1, and processes every input string regardless of whether it already contains XML-encoded characters. For OUTSTRING2, it only encodes those strings that do not contain any XML-encoded characters. Note that some viewers automatically decode the encoded values for display, so the output is produced in plain text format (FORMAT WP):

FILEDEF XMLFUNCS DISK xmlfuncs.csv
DEFINE FILE XMLFUNCS
OUTSTRING1/A30=XMLENCOD(30,INSTRING,1,30,'A30');
OUTSTRING2/A30=XMLENCOD(30,INSTRING,0,30,'A30'); 
END
TABLE FILE XMLFUNCS
PRINT INSTRING OUTSTRING1 IN 24 OUTSTRING2 IN 48
ON TABLE SET PAGE NOPAGE
ON TABLE PCHOLD FORMAT WP
END

In OUTSTRING1, the supported characters have been XML-encoded, and output is produced even if the input string contains encoded characters. OUTSTRING2 is only produced when no XML-encoded characters exist in the input string:

 INSTRING               OUTSTRING1              OUTSTRING2   
 --------               ----------              ----------              
 CHARS: &  < >          CHARS: &amp;  &lt; &gt; CHARS: &amp;  &lt; &gt; 
 ENCODED: &amp; &gt;    ENCODED: &amp; &gt;                             
 ENCODED: &quot; &apos; ENCODED: &quot; &apos;                          
 MIXED:  &amp;  < &gt;  MIXED:  &amp;  &lt; &gt;