XMLCHAR

XMLCHAR dumps data from a structure as XML into a buffer. It returns a size_t ¹ value that indicates 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.

x

Reference to a structure or DEFINE STRUCTURE type.

The reference x must conform to the following rules:

It must contain only computational data, that is, only string and numeric data. However, it must not contain any GRAPHIC, UCHAR, WIDECHAR, or WIDEPIC elements.
It may contain arrays, but if it is an array itself, it must be completely subscripted.
It may contain substructures, but any contained substructure must not use an asterisk (*) in place of a name. However, an asterisk may be used as the name of a base element, but in that case, the unnamed element will not be written to the target buffer.
If x is a reference to a structure, it must not contain any DEFINE STRUCTURE types.

p

Address of the target buffer.

n

Length of the target buffer.

The buffer length must be nonnegative and must have a computational type. The buffer length is converted to type size_t.

When the XML output is created, it follows these rules:

When a variable has the XMLCONTENT attribute, the variable is presented as tagless text
When no variable has the XMLATTR attribute, each name in the structure is written out, first enclosed in "<" and ">" and later enclosed in "</" and ">".
When a variable has the XMLATTR attribute, the field is presented as an attribute of its containing structure.
When a variable has the XMLOMIT attribute, the field is omitted if it has a null value.
Numeric and bit data is converted to character.
Leading and trailing blanks are trimmed wherever possible.

Note: By default the names of the variables in the generated XML output are all in upper case. The CASE(ASIS) suboption of the XML compiler option can be used to specify that the names appear in the case in which they were declared.

Example of using XMLCHAR

This example is based on the following code fragment:

    dcl buffer   char(800);
    dcl written  fixed bin(31);
    dcl next     pointer;
    dcl left     fixed bin(31);
    dcl
      1 a,
       2 a1,
         3 b1 char(8),
         3 b2 char(8),
       2 a2,
         3 c1 fixed bin,
         3 c2 fixed dec(5,1);

    b1 = ' t1';
    b2 = 't2';
    c1 = 17;
    c2 = -29;
    next = addr(buffer);
    left = stg(buffer);
    written = xmlchar( a, next, left );
    next += written;
    left -= written;

The following bytes would be written to the buffer, and written would be set equal to 72.

<A><A1><B1>t1</B1><B2>t2</B2></A1><A2><C1>17</C1><C2>-29.0</C2></A2></A>