XMLCHAR Function

Purpose

Dumps data from a structure as XML into a buffer. The XML can then be passed to other applications, including code using the PL/I SAX parser.

Syntax

XMLCHAR(x, p, n)

Parameters

x is a structure-reference.

The structure-reference x must contain only string and numeric data.

The structure-reference x can contain substructures. However, any contained substructure can not use an asterisk (*) in place of a name. You can use an asterisk can as a base element name, but the unnamed element is not written to the target buffer.

p is the address of the target buffer.

n is the length of the target buffer.

The buffer length must have a computational type. It is converted to FIXED BINARY(31,0).

The buffer length must be a non-negative length.

Description

The XMLCHAR function returns the number of bytes written to the buffer. If the buffer is too small, the structure data is truncated and the number of bytes needed for the buffer to contain the structure is returned.

The following occurs when the data from the specified structure is dumped to a buffer as XML:

Each name in the structure is written. Structures are initially enclosed in "<" and ">", then later enclosed in "</" and ">"
Numeric and bit data are converted to characters
Leading and trailing blanks are trimmed where possible.

All characters less than a space are replaced with a space.

All carriage returns are replaced with the string: 

All < characters are replaced with the string: <

All > characters are replaced with the string: >

All single quote characters are replaced with the string: '

All double quote characters are replaced with the string: "

All & characters are replaced with the string: &

Examples

This code sample:

XMLCHAR: PROC() OPTIONS(MAIN);

DCL 1 REDSOX,
     5 WINS(5) FIXED BIN(31) INIT(1,2,3,4,5),
     5 PITCHERS(5) CHAR(15) VARYING
       INIT('Clay Buchholtz',
            'Jon Lester',
            'John Lackey',
            'Ryan Dempster',
            'Koji Uehara');

DCL BUFFER CHAR(4000);
DCL LEN    FIXED BIN(31);

LEN = XMLCHAR(REDSOX, ADDRDATA(BUFFER), STG(BUFFER));
PUT SKIP LIST(SUBSTR(BUFFER, 1, LEN));

END;

Writes the following to the buffer.

<REDSOX><WINS>1</WINS><WINS>2</WINS><WINS>3</WINS><WINS>4</WINS><WINS>5</WINS><PITCHERS>Clay Buchholtz</PITCHERS><PITCHERS>Jon Lester</PITCHERS><PITCHERS>John Lackey</PITCHERS><PITCHERS>Ryan Dempster</PITCHERS><PITCHERS>Koji Uehara</PITCHERS></REDSOX>

Note: Default variable names in the generated XML are all in upper case. Use the CASE(ASIS) suboption of the XML compiler option to indicate that the names appear in their declared case.

Restrictions

None.