EGL library XMLLib

This topic describes the XMLLib functions and variable definitions.

The following table lists the system functions in the XMLLib library.

Table 1. XMLLib system functions
System function and invocation	Description
convertFromXML (XMLstring in, variable out)	Converts an XML string into a non-structured record.
result = convertToXML (variable in)	Converts a non-structured record into an XML string.

Compatibility considerations and restrictions for COBOL generation:

For all systems:
1. The EGL language only passes flexible records to the functions in XMLLib. The debugger, JavaGen or RUI do not support structured records as arguments to the XMLLib functions. Therefore, CobolGen also does not support these structured records. To avoid this restriction, you can always create a compatible flexible record from your structured records, and do a move byName statement to move the data to or from it.
2. Although the debugger, JavaGen and RUI can handle a field of type Any to be passed to the XMLLib function, CobolGen cannot handle this. Because CobolGen requires that the generator produces COBOL code specific to the EGL record being passed. This prevents the ability of passing a field of type Any as the function argument.
3. EGL supports dynamic arrays, whether they are dynamic arrays of strings, chars, other primitive types, or dynamic arrays of records. However, EGL does not support multiple levels of dynamic arrays. This means you cannot code dynamic arrays of records, where an element in that record is also a dynamic array.
4. When you use dynamic arrays in the flexible record, the default number of entries is 100. If an initial size is specified for the dynamic array, the size will be used, unless it is overridden by the maxSize annotation for the dynamic array. MaxSize is used as the first choice for size, followed by initial size, and then the default of 100. The generator needs to know a size, because a fixed-length COBOL structure must be created for the COBOL compiler.
5. When you use strings in the flexible record, the default length is 256 characters, unless the maxLen annotation is specified. MaxLen is used as the first choice for the maximum size, followed by the default of 256. The generator needs to know a length, because a fixed-length COBOL structure must be created for the COBOL compiler.
6. The maximum size of the string that is created or used by the XMLLib functions is 32767 characters. However, the symbolic parameter MAXIMUMSTRINGSIZE can overwrite the maximum allowed length. Therefore, you can use larger sizes if necessary. Note that this affects the maximum size of all strings that are generated with the symbolic parameter. Essentially, it generally can affect the COBOL compiler work areas and the size of the program load module. Also note that if you pass a larger string to another program, that program also needs the increased MAXIMUMSTRINGSIZE; otherwise, some of the string data might be truncated when used.
7. You can define more than one occurrence of the same record as part of the flexible record being passed, as long as these occurrences are at the top level. However, you cannot define the same record more than once as part of an embedded record.
8. Rational Business Developer supports these EGL annotations: @XMLRootElement, @XMLElement and @XMLAttribute (for iSeries, see the following restriction on attributes).
9. The @XMLRootElement, @XMLElement and @XMLAttribute annotations can support the Name annotation sub-value. If the sub-value for the Name annotation is defined, it will be used; otherwise, the field name is used as is, without conversion to upper case.
For iSeries systems:
1. When you use the convertToXML function, the iSeries COBOL compiler does not support the attributes argument. This means that any of the xxx="..." attributes created in the XML will not happen when you create XML. However, the generated COBOL source that EGL produces supports any incoming attributes, which means that the convertFromXML function will support attributes in the XML, even though the iSeries COBOL compiler cannot.