ToXmlDoc (Record function)
Return in an XmlDoc the fields and values of the Record object's record (Record class)
[Requires Janus SOAP]
This method returns in a Janus SOAP XmlDoc object the fields and values of the method Record object. You can specify options to display in uppercase or lowercase, as well as to output the values of the fields as XML attributes or as XML text of the field XML element.
ToXmlDoc is available in Sirius Mods version 7.3 and later.
Syntax
%doc = record:ToXmlDoc[( [AttributeValues= boolean], - [AttributeNames= boolean], [NamesToLower= boolean], - [AllowUnreversible= boolean], - [CodepageTable= boolean], [Base64Encode= boolean], - [CharacterMap= characterToUnicodeMap], - [AllowNull= boolean])] Throws CharacterTranslationException
Syntax terms
| %doc | An XmlDoc object variable to contain the record data. |
|---|---|
| %rec | An instantiated Record object variable. |
| AttributeValues= bool | This name required argument (AttributeValues) is a boolean value that indicates whether a field value will be displayed as XML text or as an XML attribute (belonging to its field, which is displayed as an XmlDoc element).
For example, |
| AttributeNames= bool | This name required argument (AttributeNames) is a boolean value that indicates whether field names are to be displayed within their XML document elements as the element name or as the value of a “name” attribute.
For example, <APSUBUND>COMM</APSUBUND> is element-name format, and the following is name-as-attribute format: <field name="APSUBUND"> COMM </field> The default value as of Sirius Mods version 7.6 (and maintenance back to version 7.3) is True, which produces name-as-attribute format. Formerly, the default value was False. The name-as-attribute format from the True option is better suited to operations on the XmlDoc, particularly a record copying operation. The element-name format from the False option is useful for displaying field names that are not valid as XML element names (for example, names with embedded spaces). For more information about handling non-valid XML names, see "Usage Notes", below. |
| NamesToLower= bool | This name required argument (NamesToLower) is a boolean value that indicates whether field name data is to be displayed in lowercase characters. The default value is False, which produces uppercase output.
|
| AllowUnreversible= bool | This name required argument (AllowUnreversible) is a boolean value that indicates whether a request is cancelled if a field name would be changed irreversibly by lowercasing or by replacing with a period the characters that would be invalid in an XML document.
For example, as described in "Usage Notes" below, fields FOO BAR and FOO%BAR would both produce the element name |
Usage notes
- If any fields have name characters that are not valid when displayed
as an XML element name, or if they have characters that are non-displayable when the
name is formatted as an attribute value,
the ToXmlDoc method converts the problematic characters to periods.
For example, if field
FOO BARhas valueXXX, the AttributeNames parameter value isFalse, and the NamesToLower and AttributeValues parameters are set toTrue, the resulting display would be:<foo.bar value="XXX">
- If NamesToLower is set to
True, any field name containing lowercase characters is considered unreversible; reversing would involve converting the names to uppercase. To avoid request cancellation because of this, you must set toTruethe AllowUnreversible parameter. - If a field value contains non-displayable characters, the ToXmlDoc output
data is automatically base64 encoded, and an attribute called
encodingis added to the field's XML element with a value ofbase64. For example, consider this request:OPENC FILE ALEXQA b %r is object record in file alexqa %doc is object xmlDoc %r = new(3) %doc = %r:toXmlDoc(attributeNames=false, - attributeValues=true, - namestoLower=true) %doc:print print %doc:value('/Record/bar/@value') - :base64toString:stringToHex end
If field BAR in record 3 contains X'00000040', the request might display this:
<Record file="ALEXQA" number="3"> <foo value="ABC4"/> <bar value="AAAAQA==" encoding="base64"/> </Record> 00000040
- The ToXmlDoc method will add BLOB values to the output
XmlDoc, no matter how large they are.
A BLOB field will have
a
reservedattribute added to the field element if more bytes were reserved in the BLOB than are in the actual value. - Typically, before they proceed, PAI, $list-fieldi, and other code that extracts fields by name from a record automatically get a share lock on a record if it appears to be unlocked. The ToXmlDoc method insists that the Record object be locked at least in share mode, therefore it gets no locks while it operates. No locks are required for a sorted record or in single-user mode.
Examples
The display of field data below is produced by the following request:
OPENC FILE CCASYS b %r is object record in file ccasys %r = new(1) %r:toXmlDoc:print %r:toXmlDoc(namesToLower=true):print %r:toXmlDoc(attributeValues=true):print %r:toXmlDoc(attributeValues=true, attributeNames=false, - namestoLower=true):print end
The following are sample results:
<Record file="CCASYS" number="1"> <field name="APSURTYP"> SDEF </field> <field name="APSUNM"> SUBSYSMGMT </field> <field name="APSUBUND"> COMM </field> <field name="APSUERRC"> ERROR </field> ... <Record file="CCASYS" number="1"> <field name="apsurtyp"> SDEF </field> <field name="apsunm"> SUBSYSMGMT </field> <field name="apsubund"> COMM </field> <field name="apsuerrc"> ERROR </field> ... <Record file="CCASYS" number="1"> <field name="APSURTYP" value="SDEF"/> <field name="APSUNM" value="SUBSYSMGMT"/> <field name="APSUBUND" value="COMM"/> <field name="APSUERRC" value="ERROR"/> ... <Record file="CCASYS" number="1"> <apsurtyp value="SDEF"/> <apsunm value="SUBSYSMGMT"/> <apsubund value="COMM"/> <apsuerrc value="ERROR"/> ...