ToXmlDoc (Record function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
mNo edit summary
Line 1: Line 1:
{{Template:Record:ToXmlDoc subtitle}}
{{Template:Record:ToXmlDoc subtitle}}


This method returns in a [[Janus SOAP]] <var>XmlDoc</var> object the fields and values of
This method returns in a [[Janus SOAP]] <var>XmlDoc</var> object the fields and values of
Line 19: Line 18:
<td>An instantiated <var>Record</var> object variable.
<td>An instantiated <var>Record</var> object variable.
</td></tr>
</td></tr>
<tr><th><var>AttributeValues= bool</var></th>
<tr><th><var>AttributeValues</var></th>
<td>This name required argument (<var>AttributeValues</var>) 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 <var>XmlDoc</var> element).
<td>This name required argument (<var>AttributeValues</var>) 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 <var>XmlDoc</var> element).
For example, <code><APSUBUND>COMM</APSUBUND></code> is text format, and <code><APSUBUND value="COMM"/></code> is attribute value format.
For example, <code><APSUBUND>COMM</APSUBUND></code> is text format, and <code><APSUBUND value="COMM"/></code> is attribute value format.
The default value is <var>False</var>, which produces text format.
The default value is <var>False</var>, which produces text format.
</td></tr>
</td></tr>
<tr><th><var>AttributeNames= bool</var></th>
<tr><th><var>AttributeNames</var></th>
<td>This name required argument (<var>AttributeNames</var>) 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 &amp;amp;amp;ldquo;name&amp;amp;amp;rdquo; attribute.
<td>This name required argument (<var>AttributeNames</var>) 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 &amp;amp;amp;ldquo;name&amp;amp;amp;rdquo; attribute.
For example, <code><APSUBUND>COMM</APSUBUND></code> is element-name format, and the following is name-as-attribute format: <p class="code"> <field name="APSUBUND">    COMM  </field> </p>
For example, <code><APSUBUND>COMM</APSUBUND></code> is element-name format, and the following is name-as-attribute format: <p class="code"> <field name="APSUBUND">    COMM  </field> </p>
Line 31: Line 30:
For more information about handling non-valid XML names, see [[#Usage Notes|"Usage Notes"]], below.
For more information about handling non-valid XML names, see [[#Usage Notes|"Usage Notes"]], below.
</td></tr>
</td></tr>
<tr><th><var>NamesToLower= bool</var></th>
<tr><th><var>NamesToLower</var></th>
<td>This name required argument (<code>NamesToLower</code>) is a boolean value that indicates whether field name data is to be displayed in lowercase characters. The default value is <code>False</code>, which produces uppercase output.
<td>This name required argument (<code>NamesToLower</code>) is a boolean value that indicates whether field name data is to be displayed in lowercase characters. The default value is <code>False</code>, which produces uppercase output.
</td></tr>
</td></tr>
<tr><th><var>AllowUnreversible= bool</var></th>
<tr><th><var>AllowUnreversible</var></th>
<td>This name required argument (<code>AllowUnreversible</code>) 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.
<td>This name required argument (<code>AllowUnreversible</code>) 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|"Usage Notes"]] below, fields FOO BAR and FOO%BAR would both produce the element name <code>FOO.BAR</code> if AttributeNames is set to <code>False</code>. This will cause request cancellation unless AllowUnreversible is set to <code>True</code>.
For example, as described in [[#Usage Notes|"Usage Notes"]] below, fields FOO BAR and FOO%BAR would both produce the element name <code>FOO.BAR</code> if AttributeNames is set to <code>False</code>. This will cause request cancellation unless AllowUnreversible is set to <code>True</code>.

Revision as of 22:03, 20 April 2011

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 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, <APSUBUND>COMM</APSUBUND> is text format, and <APSUBUND value="COMM"/> is attribute value format. The default value is False, which produces text format.

AttributeNames 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 &amp;amp;ldquo;name&amp;amp;rdquo; 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 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 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 FOO.BAR if AttributeNames is set to False. This will cause request cancellation unless AllowUnreversible is set to True. The default value is False, which allows request cancellation to alert you about unreversible field names.

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 BAR has value XXX, the AttributeNames parameter value is False, and the NamesToLower and AttributeValues parameters are set to True, 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 to True the AllowUnreversible parameter.
  • If a field value contains non-displayable characters, the ToXmlDoc output data is automatically base64 encoded, and an attribute called encoding is added to the field's XML element with a value of base64. 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 reserved attribute 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"/> ...

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=ToXmlDoc_(Record_function)&oldid=44350"