This topic describes the XMLLib functions and variable
definitions.
The following table lists the system functions in the XMLLib library.
Table 1. XMLLib system functionsSystem 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:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Rational Business Developer supports these EGL annotations: @XMLRootElement, @XMLElement and @XMLAttribute (for
iSeries, see the following restriction on attributes).
- 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:
- 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.