Chapter 8 Other Options of the Writer

Other Options of the Writer

Canonicalize()

The XSL: XML () method writes XML nodes in normalized form. This method has the following signature:

method Canonicalize(node As %XML.Node, ByRef PrefixList, formatXML As %Boolean = 0) as %Status
Copy the code

• nodeIs a subtree of the document as an instance of % xml.node.
• PrefixListIs one of the following:
  • For inclusion normalization, willPrefixListSpecified as"C14n".

In this case, the output is in the form of XML Canonicalization Version 1.0, from https://www.w3.org/TR/xml-c14n.

• For exclusive normalization, willPrefixListSpecifies a multidimensional array with the following nodes:

• FormatXMLControl format. If format XML is true, the writer uses the format specified for the writer instance, not the format specified by the XML normalization specification. Therefore, the output is not canonical XML, but canonical XML has been namespaced. This option is used to output fragments of XML documents, such as Web servicesProcessBodyNode()SOAP body in callback) is useful while still having some control over the format.

Hidden attribute

Hidden properties of the writer instance affect the output of properties with object values. This class of attributes allows you to force all such output to be hidden, that is, force the output to contain the ID of the referenced object rather than the object’s details. This property interacts with XMLDEFAULTREFERENCEONS and XMLREFERENCEONS(object property parameters in XML enabled), as shown in the following table. The following table shows the resulting output for each case:

Effect of Shallow = 1

The Shallow property does not affect properties whose value is a serial object or that have a non-object value.

Summary Property

The Summary property of the writer instance controls whether the entire XML-enabled object is exported or only its Summary; It can be one of the following values:

• value0Exports the entire object; This is the default setting.
• value1Only the properties listed as a summary are exported.

As described when an object is projected into XML, the summary of the object is specified by its XMLSUMMARY in the class parameter; It is a comma-separated list of properties. For example, generate output for the XML-enabled Person class, and the default output looks like this:

<Persons>
 <Person>
  <Name>Xenia,Yan T.</Name>
  <DOB>1986-10-21</DOB>
 </Person>
 <Person>
  <Name>Vivaldi,Ashley K.</Name>
  <DOB>1981-01-25</DOB>
 </Person>
</Persons>
Copy the code

Set the XMLSUMMARY of the Person class to “Name”. In this case, if the writer had set the Summary property to 1, the output would look like this:

<Persons>
 <Person>
  <Name>Xenia,Yan T.</Name>
 </Person>
 <Person>
  <Name>Vivaldi,Ashley K.</Name>
 </Person>
</Persons>
Copy the code

Base64LineBreaks properties

This can be for %Binary properties, or for %xsd.base64Binary properties. To do this, set the Base64LineBreaks property of the writer instance to 1. In this case, the writer inserts a newline/carriage return character after every 76 characters. The default value for this property is 0.

CycleCheck properties

The CycleCheck property of a writer instance controls whether the writer checks for any loops (dead-loops) within a reference object that could cause an error. The default value is 1, which means that the writer does check the period.

If you are sure there are no cycles, set CycleCheck to 0 to slightly improve performance.

Other examples: writer with optional Settings

For users of the % xml. Writer attribute, the following methods may be useful. It takes an input parameter, which is a string that names the writer “version.” Each writer version corresponds to a specific setting of the properties of the writer instance.

Class Util.XmlUtils Extends %RegisteredObject
{

/// Returns the writer with these attributes given wname
ClassMethod CreateWriter(wname) As %XML.Writer
{
	set w=##class(%XML.Writer%).New(a)set w.Indent=1
	set w.IndentChars=""
	if wname="DefaultWriter" {
		set w.Indent=0  ; set back to default
	}
	elseif wname="EncodedWriter" {
		set w.Format="encoded"
	}
	elseif wname="EncodedWriterRefInline" {
		set w.Format="encoded"
		set w.ReferencesInline=1
	}
	elseif wname="AttQualWriter" {
		set w.AttributeQualified=1
	}
	elseif wname="AttUnqualWriter" {
		set w.AttributeQualified=0 ; default
	}
	elseif wname="ElQualWriter" {
		set w.ElementQualified=1 ; default
	}
	elseif wname="ElUnqualWriter" {
		set w.ElementQualified=0
	}
	elseif wname="ShallowWriter" {
		set w.Shallow=1
	}
	elseif wname="SOAPWriter1.1" {
		set w.Format="encoded"
		set w.ReferencesInline=1
	}
	elseif wname="SOAPWriter1.2" {
		set w.Format="encoded12"
		set w.ReferencesInline=1
	}
	elseif wname="SummaryWriter" {
		set w.Summary=1
	}
	elseif wname="WriterNoXmlDecl" {
		set w.NoXMLDeclaration=1
	}
	elseif wname="WriterRefInline" {
		set w.ReferencesInline=1
	}
	elseif wname="WriterRuntimeIgnoreNull" {
		set w.RuntimeIgnoreNull=1
	}
	elseif wname="WriterSuppressXmlns" {
		set w.SuppressXmlns=1
	}
	elseif wname="WriterUTF16" {
		set w.Charset="UTF-16"
	}
	elseif wname="WriterWithDefNS" {
		set w.DefaultNamespace="www.Def.org"
	}
	elseif wname="WriterWithDefNSSuppressXmlns" {
		set w.DefaultNamespace="www.Def.org"
		set w.SuppressXmlns=1
	}
	elseif wname="WriterWithDtdSettings" {
		set w.DocType ="MyDocType"
		set w.SystemID = "http://www.mysite.com/mydoc.dtd"
		set w.PublicID = "- / / / / W3C DTD XHTML 1.0 Transitional / / EN"
		set w.InternalSubset = "" 
	}
	elseif wname="WriterXsiTypes" {
		set w.OutputTypeAttribute=1
	}
	quit w
}

}

Copy the code

The following snippet shows an example of how to use this method to help generate a document:

/// method to write one to a file
ClassMethod WriteOne(myfile, cls, element, wname, ns, local, rootns)
{
    set writer=##class(Util.XmlUtils).CreateWriter(wname)
    set mydir="e:/temp/"
    set comment="Output for the class: "_cls
    set comment2="Writer settings: "_wname
    
    if $extract(mydir,$length(mydir))'="/" {set mydir=mydir_"/"} set file=mydir_myfile set status=writer.OutputToFile(file) if $$$ISERR(status) { do $System.Status.DisplayError(status) quit } set status=writer.WriteComment(comment) if $$$ISERR(status) { do $System.Status.DisplayError(status) quit } set status=writer.WriteComment(comment2) }Copy the code

Notice that the output will include two comment lines. The name of an XML-enabled class that represents the display in the file. The other indicates the name of the writer Settings used to generate the file. The output directory is centrally controlled (by parameters), and this generic method includes parameters passed to RootElement() and Object() methods.