The use of arrays in API methods and interoperability documents is generally not recommended, as they can be problematic to translate into some programming languages and often reflect a poor, unnormalized data model. Nevertheless, their use is sometimes necessary to preserve compatibility with legacy application code, if for no other reason. For such cases, you can use a standard approach for representing arrays inside QDocs.
Arrays are represented according to the SOAP encoding scheme in order to better support the automatic generation of Java client stubs from the WSDL files using non-QAD tools. Various QDoc-specific limitations are imposed in order to simplify the SOAP syntax by eliminating those features not required by any QAD applications.
QDoc arrays are elements that contain multiple occurrences of only one simple element. The element for the array as a whole is named according to the same conventions as other elements in the QDoc, based on QAD application usage.
Arrays of complex elements, multi-dimensional arrays, and arrays of arrays (jagged arrays) are not allowed in QDocs.
The approach used to represent arrays in QDocs differs depending on which QDoc specification is being used.
QDoc Specification 1.1
In the QDoc 1.1 specification the array structure has been modified to improve the ability of applications from vendors such as Progress to recognize the syntax for arrays.
The array structure in QDoc specification version 1.1 has multiple entries of the node if it is an array. Indexing is achieved by the order in which it appears in the XML.
Note: In the QDoc 1.1 specification, every entry of an array must be included in a QDoc in order to pass values. Partial or “sparse” arrays are not allowed. QDoc 1.0, which followed SOAP encoding rules, did not impose this constraint.
The QDoc 1.0 specification used the following structure for arrays:
The equivalent array in the QDoc 1.1 specification would look like this:
Note: The handling of arrays was updated in QDoc 1.1 to adopt literal encoding in place of the SOAP encoding standard used in QDoc 1.0. The reason for this was that SOAP encoding imposed extra complexity on XML schemas and WSDLs, and was not widely supported by XML tools in the industry.
QDoc Specification 1.0
In QDoc specification 1.0 the single component element is named entry in all QDocs regardless of usage, with entry defined in the QDoc common namespace so as not to conflict with the name of any QAD application array. Every array described in a QDoc version 1.0 XML schema is declared as a restriction of the base type enc:Array. Every QDoc instance contains itemType and arraySize attributes associated with the following SOAP encoding namespace URI:
The value of itemType can be any one of the following: string, Boolean, decimal, int, date, time, anyType. (anyType is the theoretical supertype of all other types, somewhat like Object in Java.) The value of arraySize is an integer denoting the maximum size or extent of the array, or the asterisk character (*) if that value is not known.
Because SOAP 1.0 requires that arrays be included in their entirety (that is, no partial arrays), a means is needed to distinguish an array element that is being set to an empty value by a QDoc from one that is not being changed by the QDoc.
This is the same problem of specifying empty versus default values, except that in the case of arrays it is not possible to skip an empty element in order to designate that the default value should be used. See Default, Empty, and Null Values
In order to resolve the problem, the QDoc-defined entry element has one required attribute index and one optional attribute skip, also defined in the QDoc common namespace. The index attribute identifies each entry of the array. The skip attribute indicates whether the entry should be skipped or defaulted if set to true. If the skip attribute is set to true, the content of its containing entry element is ignored.
Syntactically, the indexed entries of the array can appear in any order. However, by convention, they should always be sequenced in ascending index order. For example, the following QDoc fragment would represent a six-member numeric array called orderQuantity containing two empty, two skipped, and two non-empty elements.
<!-- Entries 1, 3 are set to empty and 4, 6 are skipped -->
<qcom:entry index="4" skip="true"/>
<qcom:entry index="6" skip="true">ignore!</qcom:entry>
The following is the XML schema definition for this fragment, defined using SOAP conventions:
The following is the XML schema fragment defining the entry element and its index and skip attributes in the QDoc common namespace:
<attribute name="index" type="positiveInteger"
<attribute name="skip" type="boolean"/>