-
If you are working with an object that might be invalid, call the %ValidateObject() method of that object and check the returned status. If the object is not valid, the XML would also not be valid.
%XML.WriterOpens in a new tab does not validate the object before exporting it. This means that if you have just created an object and have not yet validated it, the object (and hence the XML) could be invalid (because, for example, a required property is missing).
-
Create an instance of the %XML.WriterOpens in a new tab class and optionally set its properties.
In particular, you might want to set the following properties:
-
Indent — Controls whether the output is generated within indentation and line wrapping (if Indent equals 1) or as a single long line (if Indent equals 0). The latter is the default. See Details on Indent Option.
-
IndentChars — Specifies the characters used for indentation. The default is a string of two spaces. This property has no effect if Indent is 0.
-
Charset — Specifies the character set to use. See Specifying the Character Set of the Output.
For readability, the examples in this documentation use Indent equal to 1.
Also see Properties That Affect the Prolog and Other Properties of the Writer.
-
Specify an output destination.
By default, output is written to the current device. To specify the output destination, call one of the following methods before starting to write the document:
-
OutputToDevice() — Directs the output to the current device.
-
OutputToFile() — Directs the output to the specified file. You can specify an absolute path or a relative path. Note that the directory path must already exist.
-
OutputToString() — Directs the output to a string. Later you can use another method to retrieve this string.
-
OutputToStream() — Directs the output to the specified stream.
-
Start the document. You can use the StartDocument() method. Note that the following methods implicitly start a document if you have not started a document via StartDocument(): Write(), WriteDocType(), RootElement(), WriteComment(), and WriteProcessingInstruction().
-
Optionally write lines of the prolog of the document. You can use the following methods:
-
Optionally specify the default namespace. The writer uses this for classes that do not have a defined XML namespace. See Specifying the Default Namespace.
Optionally add namespace declarations to the root element. To do so, you can invoke several utility methods before starting the root element. See Adding Namespace Declarations.
-
Start the root element of the document. The details depend on whether the root element of that document corresponds to an InterSystems IRIS object. There are two possibilities:
-
The root element might correspond directly to an InterSystems IRIS object. This is typically the case if you are generating output for a single object.
In this case, you use the RootObject() method, which writes the specified XML-enabled object as the root element.
-
The root element might be merely a wrapper for a set of elements, and those elements are InterSystems IRIS objects.
In this case, you use the RootElement() method, which inserts the root-level element with the name you specify.
Also see Writing the Root Element.
-
If you used the RootElement() method, call methods to generate the output for one or more elements inside the root element. You can write any elements within the root element, with any order or logic you choose. There are several ways that you can write an individual element, and you can combine these techniques:
-
You can use the Object() method, which writes an XML-enabled object. You specify the name of this element, or you can use the default, which is defined by the object.
-
You can use the Element() method, which writes the start tag for an element, with the name you provide. Then you can write content, attributes, and child elements, by using methods such as WriteAttribute(), WriteChars(), WriteCData(), and others. A child element could be another Element() or could be an Object(). You use the EndElement() method to indicate the end of the element.
-
You can use the %XML.ElementOpens in a new tab class and construct an element manually.
See Constructing an Element Manually for further details.
-
If you used the RootElement() method, call the EndRootElement() method. This method closes the root element of the document and decreases the indentation (if any), as appropriate.
-
If you started the document with StartDocument(), call the EndDocument() method to close the document.
-
If you directed the output to a string, use the GetXMLString() method to retrieve that string.
There are many other possible organizations, but note that some methods can be called only in some contexts. Specifically, once you start a document, you cannot start another document until you end the first document. If you try to do so, the writer method returns the following status:
Note:
The methods described here are designed to enable you to write specific units to the XML document, but in some cases, you may need more control. The %XML.WriterOpens in a new tab class provides an additional method, Write(), which you can use to write an arbitrary string into any place in the output.
Also, you can use the Reset() method to reinitialize the writer properties. This is useful if you have generated an XML document and want to generate another one without creating a new writer instance.