## XmlDoc Classes

This chapter provides an overview of the XmlDoc class and the XmlNode class and discusses the following topics:

• When to use an XmlDoc object

• XmlDoc object creation

• XmlNode class considerations

• Error handling

• SoapDoc objects consideration

• Scope of XmlDoc and XmlNode objects

• Data type of an XmlDoc or XmlNode object

• XmlDoc classes built-in functions

• XmlDoc class methods

• XmlDoc class property

• XmlNode class methods

• XmlNode class properties

### Understanding XmlDoc Classes

The Extended Markup Language (XML) describes a class of data objects called XML documents. It also partially describes the behavior of computer programs which process them. The XmlDoc class is used to create and manipulate XML data.

The Extended Markup Language (XML) is a method for putting structured data in a text file. Like HTML, XML uses tags, that is, text delimited by brackets (< and >). However, HTML specifies what each tag is, and how it's supposed to be displayed in a browser. XML uses tags only to delimit data. The interpretation of that data is entirely up to the application.

For example, <UL> in HTML specifies an unordered (bulleted) list. However, with XML, it could specify an underlined link.

Each XML document has both a physical and a logical structure:

• Physically, the XML document is composed of units called entities. A document begins in a "root" or document entity.

• Logically, the XML document is composed of declarations, elements, comments, character references, and processing instructions

The CreateXmlDoc function creates an XmlDoc object. An XmlDoc is composed of XmlNode objects. Each XmlNode represents an XML document entity. You can use PeopleCode to create the following types of entities:

• Attribute (specified both by a name and a NamespaceURI)

• CDATA Section

• Comment

• Element

• Entity References

• Process Instruction

• Text

### When to Use an XmlDoc Object

You can use the XmlDoc class to access inbound messages. You can also use the XmlDoc class to create XML messages to be sent out, either synchronously or asynchronously.

All messages must be associated with a message definition. An XmlDoc message must be associated with an unstructured or nonrowset-based message, that is, a message definition that's created without any record definitions.

Use the XmlDoc object if any of the following is true:

• Your message structure doesn’t fit the rowset model.

• Your message data doesn’t come from database records.

• Your third-party source or target node requires non-XML messages.

• Your message uses the SOAP protocol.

### XmlDoc Object Creation

Use the CreateXmlDoc function to create an XmlDoc object. You can create either an empty object, and populate it with data, or you can specify an XML string that is then transformed into an XmlDoc object that you can then manipulate with PeopleCode.

If you're creating an empty XmlDoc object, and you also want to specify a particular document type declaration (DTD) to be used to validate your XML, immediately after you use the CreateXmlDoc function, you should use the CreateDocumentType method to specify the DTD, followed by the CreateDocumentElement method to associate the DTD with the root entity.

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &docTypeNode;
Local XmlNode &rootNode;

&inXMLDoc = CreateXmlDoc("");
&docTypeNode = &inXMLDoc.CreateDocumentType("Personal", "", "Personal.dtd");
&rootNode = &inXMLDoc.CreateDocumentElement("root", "", &docTypeNode);


The preceding PeopleCode program produces the following XML:

<?xml version="1.0"?>
<!DOCTYPE Personal SYSTEM "Personal.dtd">
</root>


After you've created your XmlDoc object, use the GenXmlString method to create an XML string. You can then use an Internet Script (iScript) Response object method to send the string as an XML response.

Internet Script Classes (iScript)

#### Considerations Using a Unique Namespace

In the root tag, the attribute xmlns stands for the XML namespace. This allows you to define namespaces for tag names so that collisions can be avoided and validation logic can be run.

If you do not give a prefix for an XML namespace, but instead define it with the tag (xmlns) followed by a colon (:) and then a unique namespace, for example,

xmlns:psft

For example, this sort of functionality allows you to have two nodes named "Transaction", but one can be referenced by a "psft" namespace and another not, allowing for two nodes with the same name to exist, but each containing different data.

<?xml version="1.0"?>
<root xmlns:psft="http://www.peoplesoft.com">
<psft:Transaction>Value</psft:Transaction>
<Transaction>Another</Transaction>
</root>


Incorrect results can be returned when you have a namespace as in the above example, which belongs to the namespace defined in http://www.people.com. When the system tries to find the path of "root/Transaction", it may return multiple nodes when in fact the end user might only want to return one.

To avoid this, do one of the following:

• Do not use FindNode. Use GetElementByTagName instead. This does not use XPath to resolve entries in the DOM. Instead, it works at a node by node basis, for example, by getting the root node, then getting the transactions node. This code may be a bit more complex to write, but you loose the richness of XPath.

• Give every xmlns attribute a prefix. The system will use XPath correctly and find the node.

#### Considerations Using Rowsets

Unstructured XML should be transformed to structured if you want to use the full rowset abilities. PeopleSoft recommends transforming the data into a rowset-based message.

If you do not want to transform the data, you need to break it up using the Transaction tag around the equivalent of each level zero rowset, as shown in the example.

   <?xml version="1.0" ?>
- <SAMPLE_MSG>
- <Transaction>
- <QE_SALES_ORDER class="R">
<QE_ACCT_ID>26</QE_ACCT_ID>
<QE_ACCOUNT_NAME>APG-65</QE_ACCOUNT_NAME>
<QE_PHONE>(206)544-1264</QE_PHONE>
<QE_FROMROWSET />
<QE_TOROWSET />
<QE_SEND_SOA_BTN />
<QE_SEND_SOS_BTN />
<QE_TRAN_SOA_BTN />
<QE_SEND_SQ_BTN />
<QE_TRAN_SOS_BTN />
<QE_TRAN_APCODE_BTN />
<QE_TRAN_SPCODE_BTN />
<QE_PUBXMLDOC_BTN />
<QE_CLEAR_BTN />
<DESCRLONG />
</QE_SALES_ORDER>
</Transaction>
- <Transaction>
- <QE_SALES_ORDER class="R">
<QE_ACCT_ID>27</QE_ACCT_ID>
<QE_ACCOUNT_NAME>JASON ACCOUNT</QE_ACCOUNT_NAME>
<QE_PHONE>(PHONE NUMBER</QE_PHONE>
<QE_FROMROWSET />
<QE_TOROWSET />
<QE_SEND_SOA_BTN />
<QE_SEND_SOS_BTN />
<QE_TRAN_SOA_BTN />
<QE_SEND_SQ_BTN />
<QE_TRAN_SOS_BTN />
<QE_TRAN_APCODE_BTN />
<QE_TRAN_SPCODE_BTN />
<QE_PUBXMLDOC_BTN />
<QE_CLEAR_BTN />
<DESCRLONG />
</QE_SALES_ORDER>
</Transaction>
</SAMPLE_MSG>

### XmlNode Class Considerations

In general, the XmlNode Class methods and properties can be broken up into the following categories:

 Category Description Add The Addxxx methods add an entity of the specified type to the end of the list of child nodes, and returns a reference to the newly created node. Insert The Insertxxx methods insert an entity of the specified type at the specific location and returns a reference to the newly created node. Get The Getxxx methods return a reference to the specified entity. The Getxxx methods may return a single reference or an array of references. Other The other methods enable you to find a particular entity in an XmlDoc (FindNode), copy data from one node into another, and remove nodes.

#### Accessing and Traversing an XmlNode Object

If you're creating an XmlDoc object, use the CreateDocumentElement, as well as the different Add and Insert methods to create XmlNode objects. These methods return a reference to the newly created node if successful.

Use the XmlNode properties for traversing the data structure (ParentNode, PreviousSibling, NextSibling, and so on.)

You can also use the ChildNodeCount property for looping through all the child nodes of a node.

Use the NodeType property to get the type of the node (element, processing instruction, comment, and so on).

### Error Handling

Use the IsNull property to verify if the XmlNode returned by a method is a valid node. In the following example, a particular node is checked to see if it has another node after it. If it doesn't, a node is added.

Local XmlNode &usernode;

&usernode = &inXMLDoc.DocumentElement.FindNode("/Request/Company/Location/User");

If Not (&MyNode.IsNull) Then
Else
/* Do error processing */
End-If;


### SOAPDoc Object Considerations

A SOAP Message is an ordinary XML document that consists of the following parts:

• A mandatory SOAP envelope

• A mandatory SOAP body

Most of the methods and properties that you use with an XmlDoc or XmlNode can also be used with a SOAPDocument. However, there are a few XmlNode methods that cannot be used with a SOAPDocument. The following methods cannot be used with a SOAPDocument.

• CopyToPSFTMessage

• CreateDocumentType

• InsertCDataSection

• InsertProcessInstruction

SOAPDoc Class

### Scope of XmlDoc and XmlNode Objects

XmlDoc and XmlNode objects can be instantiated only from PeopleCode.

This object can be used anywhere you have PeopleCode, that is, in Application Engine PeopleCode, record field PeopleCode, and so on.

### Data Type of an XmlDoc or XmlNode Object

XmlDoc objects are declared type XmlDoc.

XmlNode objects are declared type XmlNode.

For example:

Component XmlDoc &MyDoc;

Local XmlNode &MyNode;

Note. XmlNode objects can be declared only as type Local.

### XmlDoc Classes Built-in Functions

CreateSOAPDoc

CreateXmlDoc

GetNRXmlDoc

ReValidateNRXmlDoc

Transform

TransformEx

TransformExCache

UpdateXmlDoc

### XmlDoc Class Methods

In this section, we discuss the XmlDoc methods. The methods are discussed in alphabetical order.

#### CopyRowset

Syntax

CopyRowset(&InRowset[, MessageName ][, MessageVersion])

Description

Use the CopyRowset method to copy rowset data to an XmlDoc object.

Warning! If the XmlDoc is not empty, the existing structure and data are replaced with the data and structure from InRowset . If MessageName is not specified, this function makes the best possible XML structure given the passed rowset. Not passing the message name should only occur when using a nonrowset-based message or when using a standalone rowset. For best performance, PeopleSoft recommends to always specify the message name.

Parameters

 &InRowset Specify the variable of an already instantiated and populated rowset to copy data from. MessageName Specify the name of the message that the rowset belongs to, as a string. If the message name is not specified, the best possible XML structure is created. MessageVersion Specify the message version, as a string. If you do not specify a message version, the default message version is used.

Returns

A Boolean value: True, the rowset data copied successfully, False otherwise.

Example

Local XmlDoc &inXMLDoc;
Local boolean &ret;

&inXMLDoc = CreateXmlDoc("");
&ret = &inXMLDoc.CopyRowset(&rs, "<insert message name>", "<insert message⇒
version");


XmlDoc class: CopyToRowset method.

Rowset Class

#### CopyToPSFTMessage

Syntax

CopyToPSFTMessage(targetDoc, srcPath, targetPath)

Description

Use the CopyToPSFTMessage method to copy an XmlDoc to a PeopleSoft message. The srcPath and targetPath parameters enable you to map the data of the XmlDoc (using the XmlDoc structure) to the message (following the message structure.)

The XmlDoc object generally has the following structure:

<?xml version="1.0"?>
<MESSAGE_NAME>
<FieldTypes>
...
</FieldTypes>
<MsgData>
<Transaction>
...
</Transaction>
</MsgData>
</MESSAGE_NAME>


Parameters

 targetDoc Specify the XmlDoc that contains the message structure. srcPath Specify an array of string that contains the mapping path information. targetPath Specify an array of string that contains the mapping path information.

Returns

A number. The values are:

 Value Description 0 Ok 1 Missing PSCAMA structure 2 Missing FieldType structure 3 General Error

Example

Local XmlDoc &srcDoc, &targetDoc;
Local array of string &srcPath, &targetPath;

&srcPath = CreateArrayRept("", 0);
&targetPath = CreateArrayRept("", 0);

&srcDoc = CreateXmlDoc("");
&targetDoc = CreateXmlDoc("");
&ret = &srcDoc.ParseXmlFromURL("c:/temp/source.xml");
&ret = &targetDoc.ParseXmlFromURL("c:/temp/target.xml");

&srcPath.Push("QE_EMPLOYEE");
&srcPath.Push("QE_EMPLOYEE/QE_ACCOUNT_TBL");
&srcPath.Push("QE_EMPLOYEE/QE_JOBCODE");
&srcPath.Push("QE_EMPLOYEE/DEPTID");
&srcPath.Push("EMAIL_MSG_RCD");
&srcPath.Push("EMAIL_MSG_RCD/EMAIL_FILE_RCD");

&targetPath.Push("QE_EMPLOYEE_TG");
&targetPath.Push("QE_EMPLOYEE_TG/QE_ACCOUNT_TBL_TG");
&targetPath.Push("QE_EMPLOYEE_TG/QE_JOBCODE_TG");
&targetPath.Push("QE_EMPLOYEE_TG/DEPTID_TG");
&targetPath.Push("EMAIL_MSG_RCD_TG");
&targetPath.Push("EMAIL_MSG_RCD/EMAIL_FILE_RCD_TG");

&ret = &srcDoc.CopyToPSFTMessage(&targetDoc, &srcPath, &targetPath);

XmlDoc class: CopyRowset method, CopyToRowset method, Array Class .

Message Classes

#### CopyToRowset

Syntax

CopyToRowset(&Rowset, Message_Name, [Message_Version])

Description

Use the CopyToRowset method to copy data from the XmlDoc to an already instantiated rowset.

The rowset must be based on a message object that has the same structure as the XmlDoc. That is, if you have a record at level two in your message and you want that data, you must have the same level zero and level one records in your message as in your XmlDoc.

<?xml version="1.0"?>
<QE_SALES_ORDER>
<QE_ACCT_ID/>
<QE_ACCOUNT_NAME/>
<QE_PHONE/>
<QE_FROMROWSET/>
<QE_TOROWSET/>
<QE_SEND_SOA_BTN/>
<QE_SEND_SOS_BTN/>
<QE_TRAN_SOA_BTN/>
<QE_SEND_SQ_BTN/>
<QE_TRAN_SOS_BTN/>
<QE_TRAN_APCODE_BTN/>
<QE_TRAN_SPCODE_BTN/>
<QE_PUBXMLDOC_BTN/>
<QE_CLEAR_BTN/>
<DESCRLONG/>
</QE_SALES_ORDER>


If you wanted to include the information in the QE_SALES_ORDER record, you would have to have at least the following record structure in your message:

QE_SALES_ORDER

Any records or fields that are in the XmlDoc that aren’t in the message (and vice-versa) are ignored.

Rowsets should be created using the following pseudo code:

Local Message &msg;
Local Rowset &rs;
Local XmlDoc &inXMLDoc;
Local boolean &ret;

&msg = CreateMessage(OPERATION.<insert message name>);
&rs = &msg.GetRowset();
&inXMLDoc = CreateXmlDoc("<insert XML structure here>");
&ret = &inXMLDoc.CopyToRowset(&rs, "<insert message name>", "<insert message⇒
version>");


XmlDoc objects have to follow the Peoplesoft message format:

<?xml version="1.0"?>
<PSmessage>
<MsgData>
<Transaction>
<Record1 class="R">
<Field1>xxx</Field1>
<Field2>yyy</Field2>
...
<Fieldn>nnn</Fieldn>
<Record2>
...
</Record2>
</Record1>
</Transaction>
</MsgData>
</PSmessage>


Warning! If MessageName is not specified, this function makes the best possible flat structure. Not passing the message name should only occur when using a nonrowset-based message or when using a standalone rowset. For best performance, PeopleSoft recommends to always specify the message name.

Parameters

 &InRowset Specify the variable of an already instantiated rowset to copy data to. Message_Name Specify the message name of the message. If the message name is not specified, the best possible flat structure is created. Message_Version Specify the message version, as a string. If the message version is not specified, the default message version is used.

Returns

This function always returns a True value, regardless of the success of the operation.

XmlDoc class: CopyRowset method.

Rowset Class

Message Classes

#### CreateDocumentElement

Syntax

CreateDocumentElement(TagName [, NamespaceURI ] [, &DocType])

where NamespaceURI can have one of the following forms:

URL.URLname

OR a string URL, such as

http://www.peoplesoft.com/

Description

Use the CreateDocumentElement method to create the root element of the document.

For &DocType you must specify an already instantiated document type node using CreateDocumentType.

Parameters

 TagName Specify the name of the tag to be used for the document element. NamespaceURI Specify the URI that contains the Namespaces for the XmlDoc, as a string. &DocType Specify the document type node. This must already be instantiated using CreateDocumentType.

Returns

A reference to an XmlNode object representing the root element.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &docTypeNode;
Local XmlNode &rootNode;

&inXMLDoc = CreateXmlDoc("");
&docTypeNode = &inXMLDoc.CreateDocumentType("Personal", "", "Personal.dtd");
&rootNode = &inXMLDoc.CreateDocumentElement("root", "", &docTypeNode);


The preceding PeopleCode program produces the following XML:

<?xml version="1.0"?>
<!DOCTYPE Personal SYSTEM "Personal.dtd">
<root/>


XmlDoc class: CreateDocumentType method.

#### CreateDocumentType

Syntax

CreateDocumentType(Name, PublicID, SystemID)

Description

Use the CreateDocumentType method to create the document type declaration (a document type node) in the XmlDoc.

You can specify only one document type node for an XmlDoc.

You need to create a document type node only if you have a document type definition (DTD). You don't need to specify a document type declaration in your XML. Generally, the DTD file is used for validating the XML.

If you do specify this type of node when creating an XmlDoc in PeopleCode, you must specify it immediately following the creation statement. Then, you must specify the document type when you create the root node. This means your code should start with the CreateXmlDoc function, creating the XmlDoc object, then use the CreateDocumentType method, followed by the CreateDocumentElement method, creating the root node.

Considerations Using Public and System IDs

You can specify both a public and a system ID. However, if you want to use a system ID only, you must specify a Null string ("") for the public ID. To use a public ID only, you must specify a Null string ("") for the system ID. If the system ID and public ID are both Null (""), then the document type is considered as system.

To use the Personal.dtd as a system ID, you must use the following code:

&DocType = &MyDoc.CreateDocumentType("Personal", "", "Personal.dtd");

This produces the XML:

<!DOCTYPE Personal SYSTEM "Personal.dtd">

To use the Personal.dtd as a public ID, you must use the following code:

&DocType = &MyDoc.CreateDocumentType("Personal", "Personal.dtd", "");

This produces the XML:

<!DOCTYPE Personal PUBLIC "Personal.dtd">

Parameters

 Name Specify the name of the document type declaration as a string. PublicID Specify the public ID of the document type declaration as a string. SystemID Specify the system ID of the document type declaration as a string.

Returns

A reference to an XmlNode object representing the document type element.

Example

The following example creates a document type declaration using the DTD named "Personal".

Local XmlDoc &inXMLDoc;
Local XmlNode &docTypeNode;
Local XmlNode &rootNode;

&inXMLDoc = CreateXmlDoc("");
&docTypeNode = &inXMLDoc.CreateDocumentType("Personal", "", "Personal.dtd");
&rootNode = &inXMLDoc.CreateDocumentElement("root", "", &docTypeNode);


This produces the following XML:

<?xml version="1.0"?>
<!DOCTYPE Personal SYSTEM "Personal.dtd">
<root/>


XmlDoc class: CreateDocumentElement method.

CreateXmlDoc

#### GenFormattedXmlString

Syntax

GenFormattedXmlString()

Description

Use the GenFormattedXmlString method to return an XML string representing the XmlDoc object.

The GenFormattedXmlString method produces an XML string with new line characters and indents. If you want an unformatted XML string, that is, with all the data on a single line, use the GenXmlString method instead.

Parameters

None.

Returns

A formatted XML string.

Example

Local XmlDoc &inXMLDoc;
Local string &outStr;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><PSMessage/>");
&outStr = &inXMLDoc.GenFormattedXmlString();


XmlDoc class: GenXmlString method.

#### GenXmlFile

Syntax

GenXmlFile(path)

Description

Use the GenXmlFile method to write the content of the XmlDoc object to a file. The XML output file will be in UTF-8 format, and its elements will be formatted and named exactly the same as the XML output from the GenFormattedXmlString method.

Parameters

 path Specifies the absolute system path of the destination file.

Returns

A Boolean value: True, if the XML file was saved successfully, False otherwise.

Example

Local XmlDoc &xmldocRoot = CreateXmlDoc(" ");
Local XmlNode &nodeRoot = &xmldocRoot.CreateDocumentElement("root");
.
.
.
&result = &xmldocRoot.GenXmlFile("c:\data.xml");


GenFormattedXmlString

#### GenXmlString

Syntax

GenXmlString()

Description

Use the GenXmlString method to return an XML string representing the XmlDoc object.

The GenXmlString method produces an XML string with all the data on a single line. If you want a formatted XML string, that is, with new line characters and indents, use the GenFormattedXmlString method instead.

Parameters

None.

Returns

An XML string.

Example

Local XmlDoc &inXMLDoc;
Local string &outStr;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><PSMessage/>");
&outStr = &inXMLDoc.GenXmlString();


XmlDoc class: GenFormattedXmlString method.

#### GetElementsByTagName

Syntax

GetElementsByTagName(TagName)

Description

Use the GetElementsByTagName method to return an array of XmlNode objects that match the specified tag name.

If you specify an invalid tag name, an array is still returned, however, it has 0 elements in it.

Parameters

 TagName Specify the tag name that you want to look for.

Returns

An array of XmlNode objects.

Example

Using the following Xml structure:

<?xml version="1.0"?>
<PSmessage>
<MsgData>
<Transaction>
<Record1 class="R">
<Field1>one</Field1>
<Field1>two</Field1>
<Field1>three</Field1>
</Record1>
</Transaction>
</MsgData>
</PSmessage>


The following code finds all of the Field1 elements:

Local array of XmlNode &field1List;

&field1List = &inXMLDoc.GetElementsByTagName("Field1");

If &field1List.Len = 0 Then
/* do error processing */
Else
/* do processing */
End-If;


Array Class.

Syntax

LoadIBContent(Content[, RootTagName])

Description

Use LoadIBContent to load data into an XmlDoc object. This function is primarily used for display purposes, the main use is found in the Integration Broker Monitor for viewing message structures.

When Content is an XML string, the XmlDoc contains the DOM representation of the XML.

When Content is not an XML string, LoadIBContents generates a DOM wrapper.

Parameters

 Content Specify the content of the XmlDoc. RootTagName Specify the root tag name to be used in the XmlDoc object used as the wrapper, if the data is non-Xml. If a root tag name is not specified, and the data is non-Xml, the contents are not wrapped with the default of root tag name of PSMessage.

Returns

This method returns a Boolean value that is always True.

Example

Using the following data:

John Q. Public,1234 West Eastland,925-987-0909
Jane Doe,423 Someplace,234-992-9383


The following PeopleCode program specifies a root name:

Local XmlDoc &inXMLDoc;
Local boolean &ret;
Local string &inStr;

&inStr = "John Q. Public,1234 West Eastland,925-987-0909" | Char(13) | "Jane⇒
Doe,423 Someplace,234-992-9383";

&inXMLDoc = CreateXmlDoc("");


This produces the following:

<?xml version="1.0"?>
<Root>
<data PsNonXml="Yes">
<![CDATA[John Q. Public,1234 West Eastland,925-987-0909
Jane Doe,423 Someplace,234-992-9383]]>
</data>
</Root>


The following PeopleCode program does not specify a root name:

Local XmlDoc &inXMLDoc;
Local boolean &ret;
Local string &inStr;

&inStr = "John Q. Public,1234 West Eastland,925-987-0909" | Char(13) | "Jane⇒
Doe,423 Someplace,234-992-9383";

&inXMLDoc = CreateXmlDoc("");


This produces the following:

<?xml version="1.0"?>
<PSMessage>
<data PsNonXml="Yes">
<![CDATA[John Q. Public,1234 West Eastland,925-987-0909
Jane Doe,423 Someplace,234-992-9383]]>
</data>
</PSMessage>


The following is an example of a valid XML document:

Local XmlDoc &inXMLDoc;
Local boolean &ret;
Local string &inStr;

&inStr = "<?xml version='1.0'?><root/>";

&inXMLDoc = CreateXmlDoc("");


This produces the following:

<?xml version="1.0"?>
<root/>


#### ParseXmlFromURL

Syntax

ParseXmlFromURL(path [, DTDValidation])

Where path can have one of the following forms—a string URL, containing the filename and extension:

http://www.peoplesoft.com/filename.ext

Or an absolute file path, including the filename and extension:

c:\directory\filename.ext

Note. HTTPS is not a supported protocol for path.

Description

Use the ParseXmlFromURL method to convert the XML file located at path into an XmlDoc object that you can then manipulate using PeopleCode. The XmlDoc object executing the method is populated with the XML string after it's been converted. Any data already existing in the XmlDoc object is overwritten.

Using this method also does basic validation of the XML string, comparing it to the document type declaration (DTD) if the DOCTYPE for the DTD is provided in the XML string.

Note. PeopleSoft only supports UTF-8 encoding. Therefore, if the input file is encoded, it must be encoded in UTF-8.

Parameters

 path Specify the URL or file path to the XML that file you want to manipulate. If you specify a string URL, the URL must be contained in quotation marks. Note. HTTPS is not a supported protocol for path. DTDValidation Specify whether to validate a document type definition (DTD.) This parameter takes a Boolean value. If you specify true, the DTD validation occurs if a DTD is provided. If you specify false, and if a DTD is provided, it is ignored and the XML isn't validated against the DTD. The default value for this parameter is false. In the case of application messaging, if a DTD is provided, it's always ignored and the XML isn't validated against the DTD. If the XML cannot be validated against a DTD, an error is thrown saying that there was an XML parse error.

Returns

A Boolean value: True, the XML file converted successfully and was validated, False otherwise. (If the XML file is not valid, the PeopleCode program terminates.)

Example

The following PeopleCode program loads a file from a file path:

Local XmlDoc &inXMLDoc;
Local boolean &ret;

&inXMLDoc = CreateXmlDoc("");
&ret = &inXMLDoc.ParseXmlFromURL("c:\temp\in.xml");


The following PeopleCode program loads a file from a URL:

Local XmlDoc &inXMLDoc;
Local boolean &ret;

&inXMLDoc = CreateXmlDoc("");
&ret = &inXMLDoc.ParseXmlFromURL("http://www.peoplesoft.com/xmlfile.xml");


XmlDoc class: ParseXmlString method.

#### ParseXmlString

Syntax

ParseXmlString(XmlString)

Description

Use the ParseXmlString method to convert the XML string into an XmlDoc object that you can then manipulate using PeopleCode. The XmlDoc object executing the method is populated with the XML string after it's been converted. Any data already existing in the XmlDoc object is overwritten.

Using this method also does basic validation of the XML string, comparing it to the document type declaration (DTD) if the DOCTYPE for the DTD is provided in the XML string.

Parameters

 XmlString Specify an XML string that you want to be able to manipulate using PeopleCode.

Returns

A Boolean value: True, the XML string converted successfully and was validated, False otherwise. (If the XML is not valid, the PeopleCode program terminates.)

Example

Local XmlDoc &inXMLDoc;
Local boolean &ret;
Local string &str;

&str = "<?xml version='1.0'?><root/>";

&inXMLDoc = CreateXmlDoc("");
&ret = &inXMLDoc.ParseXmlString(&str);

If &ret Then
/* do processing */
Else
/* do error processing */
End-If;


XmlDoc class: ParseXmlFromURL method.

### XmlDoc Properties

In this section, we discuss the XmlDoc properties. The properties are discussed in alphabetical order.

#### DocumentElement

Description

This property returns a reference to the root element of the document as an XmlNode.

XmlNode Class.

#### IsNull

Description

This property returns a Boolean value, indicating whether the doc is a valid object. This property returns True if the XmlDoc object is valid, False otherwise.

### XmlNode Class

Unlike C++ and Java programming model, PeopleCode interface uses the root object XmlNode to represent all 11 different derived objects. An XmlNode object can be defined only as local.

### XmlNode Class Methods

Add methods create a new node of the specific type, append this new node to the child list, and return this newly created node, while Insert methods add the node to the specified position.

In this section, we discuss the XmlNode methods. The methods are discussed in alphabetical order.

Syntax

AddAttribute(Name, Value);

Description

Use the AddAttribute method to add an attribute to an XmlNode. A reference to the newly created attribute is returned.

If you specify an attribute name that already exists, the new value you use replaces the existing value, and a reference to the attribute is returned.

Attributes added by the AddAttribute method appear in an arbitrary order in the generated XML.

Parameters

 Name Specify the name of the Attribute that you want to create, as a string. Value Specify the value of the Attribute that you want to create, as a string.

Returns

None.

Example

Here is a set of XML response code.

<?xml version="1.0"?>
<myroot>
<postreqresponse>
<candidate>
<user>
​<location scenery="great" density="low" blank="eh?"/>
​
</user>
</candidate>
</postreqresponse>
</myroot>

Here's the PeopleCode that builds it.

Local XmlDoc &inXMLDoc;
Local XmlNode &postReqNode;
Local XmlNode &candidatesNode;
Local XmlNode &userNode;
Local XmlNode &locationNode;
Local XmlNode &sceneryAtt;
Local XmlNode &densityAtt;
Local XmlNode &blankAtt;
Local boolean &ret;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");



XmlNode class: IsNull property.

Syntax

AddAttributeNS(NamespaceURI, AttributeName, Value)

where NamespaceURI can have one of the following forms:

URL.URLname

OR a string URL, such as

http://www.peoplesoft.com/

Description

Use the AddAttributeNS method to add a namespace attribute to an XmlNode. The new attribute is appended to the list of child nodes.

To insert a Namespace attribute at a particular place in the list of nodes, use the InsertAttributeNS method instead.

A reference to the newly created attribute is returned.

If you specify an attribute name that already exists, the new value you use replaces the existing value, and a reference to the attribute is returned.

Parameters

 NamespaceURI Specify the URI that contains the Namespaces for the XmlDoc, as a string. AttributeName Specify the name of the Attribute that you want to create, as a string. Value Specify the value of the Attribute that you want to create, as a string.

Returns

None.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");


XmlNode class: IsNull property.

Syntax

AddCDataSection(Data)

Description

CDATA sections may occur anywhere character data may occur; they are used to escape blocks of text containing characters which would otherwise be recognized as markup.

To insert a CDATA section at a particular place in the list of nodes, use the InsertCDataSection method instead.

A reference to the newly created CDATA section is returned.

Note. You cannot use this method with a SoapDoc object.

Parameters

 Data Specify the data to be included in the CDATA section as a string.

Returns

A reference to the newly created CDATA section.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;
Local XmlNode &cdataNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");


The preceding PeopleCode program produces the following:

<?xml version="1.0"?>
<myroot>
<child>
<![CDATA[testing...]]>
</child>
</myroot>


XmlNode class: InsertCDataSection method.

Syntax

AddComment(Text)

Description

Use the AddComment method to add a comment to an XmlNode. The new attribute is appended to the list of child nodes.

To insert a comment at a particular place in the list of nodes, use the InsertComment method instead.

A reference to the newly created comment is returned.

Parameters

 Text Specify the text to be used as the comment, as a string.

Returns

A reference to the newly created comment.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;
Local XmlNode &commentNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");
&commentNode = &childNode.AddComment("This is an example of a comment.");


The preceding PeopleCode program produces the following XML:

<?xml version="1.0"?>
<myroot>
<child>
<!--This is an example of a comment.-->
</child>
</myroot>


XmlNode class: InsertComment method.

Syntax

AddElement(TagName)

Description

Use the AddElement method to add an element to the XmlNode. The new element is appended to the list of child nodes.

To insert an element at a particular place in the list of nodes, use the InsertElement method instead.

A reference to the newly created element is returned.

Parameters

 TagName Specify the tag for the new element that you are adding, as a string.

Returns

A reference to the newly created element.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");


The preceding PeopleCode program produces the following XML:

<?xml version="1.0"?>
<myroot>
<child/>
</myroot>


XmlNode class: InsertElement method, GetElement method, GetElementsByTagName method.

Syntax

AddElementNS(NamespaceURI, TagName)

Where NamespaceURI can have one of the following forms:

URL.URLName

Or a string URL, such as:

http://www.peoplesoft.com/

Description

Use AddElementNS to add a namespace element to an XmlNode. The new element is appendced to the list of child nodes.

To insert a Namespace element at a particular place in the list of nodes, use the InsertElementNS method instead. A reference to the newly created element is returned. If you specify an element name that already exists, the new value you use replaces the existing value, and a reference to the element is returned.

Parameters

 NamespaceURI Specify the URI that contains the Namespaces for the XmlDoc, as a string. TagName Specify the name of the Element that you want to create, as a string.

Returns

A reference to the newly created element if successful. If not successful, the IsNull property is set to True.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");
"child");


Syntax

AddEntityReference(Name)

Description

Use the AddEntityReference method to add an entity reference. An entity reference refers to the content of the named entity. The new entity reference is appended to the list of child nodes. In the generated XML, the entity reference is automatically prefaced with the '&' character and suffixed with a semi-colon.

The named entity must exist in the document type declaration (DTD).

To insert an entity reference at a particular place in the list of nodes, use the InsertEntityReference method instead.

Parameters

 Name Specify the name of the entity to which this reference refers to.

Returns

A reference to the newly created entity reference.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;
Local XmlNode &entityRef;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");


The preceding PeopleCode program produces the following XML:

<?xml version="1.0"?>
<myroot>
<child>
&MyURL;  </child>
</myroot>


XmlNode class: InsertEntityReference method.

Syntax

AddNode(&XmlNode)

Description

Use the AddNode method to add an XmlNode to the XmlDoc. The new node is appended to the list of child nodes.

To insert a node at a particular place in the list of nodes, use the InsertNode method instead.

A reference to the newly created node is returned.

Parameters

Returns

None.

Example

Local XmlDoc &inXMLDoc, &firstDoc;
Local XmlNode &childNode;

&firstDoc = CreateXmlDoc("<?xml version='1.0'?><myroot><child><subchild/></child><⇒
/myroot>");
&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&childNode = &firstDoc.DocumentElement.FindNode("/child");


XmlNode class: InsertNode method.

Syntax

AddProcessInstruction(Target, Data)

Description

Use the AddProcessInstruction method to add a processing instruction to an XmlNode. The new process instruction is appended to the end of the child list.

To insert a processing instruction at a particular place, use the InsertProcessInstruction method instead.

A reference to the newly created processing instruction is returned.

Note. You cannot use this method with a SoapDoc object.

Parameters

 Target Specify the application to which the instruction is directed, as a string. Data Specify the data used with the processing instruction.

Returns

A reference to the newly created processing instruction.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &procInst;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");
"href=""book.css"" type=""text/css""");


The preceding PeopleCode program produces the followingXML :

<?xml version="1.0"?>
<myroot>
<?xml-stylesheet href="book.css" type="text/css"?>
</myroot>


XmlNode class: InsertProcessInstruction method.

Syntax

AddText(Data)

Description

Use the AddText method to add a text node to an XmlNode.

Note. A text node is not the same as a text declaration. The text declaration is added automatically with the CreateXmlDoc function. A text node just contains text within an XmlDoc.

To insert a text node at a particular place, use the InsertText method instead.

A reference to the newly created text node is returned.

Parameters

 Data Specify the data to be used as the text node, as a string.

Returns

A reference to the newly created text node.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;
Local XmlNode &textNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");


The preceding PeopleCode program produces the following XML:

<?xml version="1.0"?>
<myroot>
<child>This is text</child>
</myroot>


XmlNode class: InsertText method.

#### CopyNode

Syntax

CopyNode(&Node)

Description

Use the CopyNode method to copy a node specified by &Node and all of its child nodes into the current node, as a child node. The new node is appended to the end of the list of child nodes. The specified node can belong to a different XmlDoc.

If you just want to copy a top-level node, without copying its children, you can just create a new node with the name of the node you want.

Parameters

 &Node Specify an already instantiated node that you want to copy.

Returns

None.

Example

Suppose that your XmlDoc has the following structure:

<?xml version="1.0"?>
<myroot>
<child>
<subchild/>
</child>
</myroot>


The following PeopleCode copies the node child and copies it into another doc.

Local XmlDoc &inXMLDoc, &firstDoc;
Local XmlNode &childNode;

&firstDoc = CreateXmlDoc("<?xml version='1.0'?><myroot><child><subchild/></child><⇒
/myroot>");
&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&childNode = &firstDoc.DocumentElement.FindNode("/child");
&inXMLDoc.DocumentElement.CopyNode(&childNode);


The following is the new structure:

<?xml version="1.0"?>
<root>
<child>
<subchild/>
</child>
</root>


XmlNode class: AddNode method, InsertNode method, GetChildNode method, FindNode method, FindNodes method.

#### FindNode

Syntax

FindNode(Path)

Description

Use the FindNode method to return a reference to an XmlNode.

The path is specified as the list of tag names, to the node that you want to find, each separated by a slash (/).

Parameters

 Path Specify the tag names up to and including the name of the node that you want returned, starting with a slash and each separated by a slash (/). This is known as the XPath query language.

Returns

An XmlNode matching the path if successful. If not successful, the IsNull property on the XmlNode is set to True.

Example

Suppose your XmlDoc has the following structure:

<?xml version="1.0"?>
<myroot>
<postreqresponse>
<candidate>
<user>
​<location scenery="great" density="low" blank="eh?"/>
</user>
</candidate>
</postreqresponse>
</myroot>

You want to return a reference to the location attribute. Use the following Path to do it:

&XmlNode = &MyDoc.FindNode("/myroot/postreqresponse/candidate/user/location");

XmlNode class: GetChildNode method, FindNodes method.

#### FindNodes

Syntax

FindNodes(Path)

Description

Use the FindNodes method to return a reference to an array containing all the XmlNodes that match the path.

The path is specified as the list of tag names, to the node that you want to find, each separated by a slash (/).

Parameters

 Path Specify the tag names up to and including the name of the node that you want returned, each separated by a slash (/). This is known as the XPath query language.

Returns

An array of XmlNode objects. If there is no match for the specified path, an array with 0 elements is returned.

Example

Using the following input:

<?xml version="1.0"?>
<PSmessage>
<MsgData>
<Transaction>
<Record1 class="R">
<Field1>one</Field1>
<Field1>two</Field1>
<Field1>three</Field1>
</Record1>
</Transaction>
</MsgData>
</PSmessage>


The following PeopleCode program finds all of the Field1 nodes:

Local array of XmlNode &field1List;

&field1List = &inXMLDoc.DocumentElement.FindNodes("MsgData/Transaction/Record1⇒
/Field1");

If &field1List.Len = 0 Then
/* do error processing, no nodes returned */
Else
/* do regular processing */
End-If;


XmlNode class: GetChildNode method, FindNode method, Array Class .

#### GenXmlString

Syntax

GenXmlString()

Description

Use the GenXmlString method to generate an XML string of the XmlNode.

Parameters

None.

Returns

An XML String.

Example

&MyXML = &MyNode.GenXmlString();

GenXmlString XmlDoc method

#### GetAttributeName

Syntax

GetAttributeName(Index)

Description

Use the GetAttributeName method to return the specified attribute.

Parameters

 Index Specify an integer representing the attribute you want to access.

Returns

A string.

Example

Local XmlDoc &inXMLDoc;
Local string &attName;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");

&attName = &inXMLDoc.DocumentElement.GetAttributeName(2);


#### GetAttributeValue

Syntax

GetAttributeValue({Name | Index})

Description

Use the GetAttributeValue method to return the specific attribute value, given an attribute name. The attribute name is case-sensitive, so you must specify the exact name.

Parameters

 Name | Index Specify the name or index of the attribute whose value you want to access.

Returns

A string containing the value of the specified attribute.

Example

Local XmlDoc &inXMLDoc;
Local string &attName;
Local string &attValue;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");

&attName = &inXMLDoc.DocumentElement.GetAttributeName(2);
&attValue = &inXMLDoc.DocumentElement.GetAttributeValue(&attName);


#### GetCDataValue

Syntax

GetCDataValue()

Description

Use the GetCDataValue method to return the value of the first CDATA section in an XmlNode.

Parameters

None.

Returns

A reference to the value of the first CDATA section as a string.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local XmlNode &cdataNode;
Local string &theData;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&cdataNode = &dataNode.AddCDataSection("this is a bunch of text");

&theData = &dataNode.GetCDataValue();


XmlNode class: AddCDataSection method, InsertCDataSection method, GetCDataValues method.

#### GetCDataValues

Syntax

GetCDataValues()

Description

Use the GetCDataValues method to return an array of string containing the values of the CDATA section in an XmlNode.

Parameters

None.

Returns

An array of string.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local XmlNode &cdataNode;
Local array of string &theData;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&cdataNode = &dataNode.AddCDataSection("this is a bunch of text");

&theData = &dataNode.GetCDataValues();


XmlNode class: AddCDataSection method, InsertCDataSection method, GetCDataValue method, Array Class .

#### GetChildNode

Syntax

GetChildNode(index)

Description

Use the GetChildNode method to return the specified child node of an XmlNode.

Parameters

 Index Specify an integer representing the child node that you want to access.

Returns

A reference to an XmlNode. If the specified XmlNode isn't found, the IsNull property for the XmlNode is set to True.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");

&dataNode = &inXMLDoc.DocumentElement.GetChildNode(2);


XmlNode class: FindNode method, FindNodes method.

#### GetElement

Syntax

GetElement()

Description

Use the GetElement method to return the first child element node in the list of child nodes.

Parameters

None.

Returns

A reference to an element.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");

&dataNode = &inXMLDoc.DocumentElement.GetElement();


XmlNode class: AddElement method, InsertElement method, GetElements method, GetElementsByTagName method.

#### GetElements

Syntax

GetElements()

Description

Use the GetElements method to return an array of all the XmlNode objects that are elements.

Parameters

None.

Returns

An array of XmlNode of all the element nodes. If there are no element nodes, an array with 0 elements is returned.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local array of XmlNode &dataList;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");

&dataList = &inXMLDoc.DocumentElement.GetElements();

If &dataList.Len = 0 Then
/* do error processing, no nodes returned */
Else
/* do regular processing */
End-If;


XmlNode class: AddElement method, InsertElement method, GetElement method, GetElementsByTagName method, Array Class .

#### GetElementsByTagName

Syntax

GetElementsByTagName(TagName)

Description

Use the GetElementsByTagName method to return an array of XmlNode objects that match the specified tag name.

Parameters

 TagName Specify the tag name that you want to look for.

Returns

An array of XmlNode. If you specify an invalid tag name, the returned array has 0 elements.

Example

Using the following input:

<?xml version="1.0"?>
<PSmessage>
<MsgData>
<Transaction>
<Record1 class="R">
<Field1>one</Field1>
<Field1>two</Field1>
<Field1>three</Field1>
</Record1>
</Transaction>
</MsgData>
</PSmessage>


The following PeopleCode program finds all Field1 nodes:

Local array of XmlNode &field1List;

&field1List = &inXMLDoc.DocumentElement.GetElementsByTagName("Field1");

If &field1List.Len = 0 Then
/* do error processing, no nodes returned */
Else
/* do regular processing */
End-If;


XmlNode class: AddElement method, InsertElement method, GetElements method, GetElement method, Array Class .

#### GetElementsByTagNameNS

Syntax

GetElementsByTagNameNS(NamespaceURI, TagName)

Where NamespaceURI can have one of the following forms:

URL.URLName

Or a string URL, such as:

http://www.peoplesoft.com/

Description

Use the GetElementsByTagNameNS method to return an array of XmlNode objects that match the specified namespace and qualified name.

Parameters

 NamespaceURI Specify the URI that contains the Namespace for the XmlDoc, as a string. TagName Specify the name of the element that you want to retrieve.

Returns

An array of XmlNode. If you specify an invalid NamespaceURI, the returned array has 0 elements.

Example

Using the following input:

<?xml version="1.0"?>
<Psmessage xmlns="http://www.peoplesoft.com">
<MsgData>
<Transaction>
<Record1 class="R">
<Field1>one</Field1>
<Field1>two</Field1>
<Field1>three</Field1>
</Record1>
</Transaction>
</MsgData>
</PSmessage>


The following PeopleCode program finds all Field1 nodes:

Local array of XmlNode &field1List;

&field1List = &inXMLDoc.DocumentElement.GetElementsByTagNameNS("http:⇒
//www.peoplesoft.com", "Field1");

If &field1List.Len = 0 Then
/* do error processing, no nodes returned */
Else
/* do regular processing */
End-If;


#### InsertCDataSection

Syntax

InsertCDataSection(Data, Position)

Description

Use the InsertCDataSection method to insert a CDATA section in an XmlNode, at the location specified by Position.

Note. You cannot use this method with a SoapDoc object.

Parameters

 Data Specify the data for the CDATA section as a string. Position Specify where you want to insert the CDATA Section, as a number.

Returns

A reference to the newly created CDATA section.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local XmlNode &cdataNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&cdataNode = &dataNode.AddCDataSection("this is a bunch of text");

&cdataNode = &dataNode.InsertCDataSection("more text", 2);


This is the XML document before the insert:

<?xml version="1.0"?>
<root>
<data>
<![CDATA[this is a bunch of text]]>
<![CDATA[still more text]]>
</data>
</root>


This is the XML document after the insert:

<?xml version="1.0"?>
<root>
<data>
<![CDATA[this is a bunch of text]]>
<![CDATA[more text]]>
<![CDATA[still more text]]>
</data>
</root>


XmlNode class: AddCDataSection method, GetCDataValue method, GetCDataValues method.

#### InsertComment

Syntax

InsertComment(Data, Position)

Description

Use the InsertComment method to insert a comment in an XmlNode at the location specified by Position.

Parameters

 Data Specify the data for the comment as a string. Position Specify where you want to insert the comment, as a number.

Returns

A reference to the newly created comment.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local XmlNode &commentNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&commentNode = &dataNode.AddComment("this is a comment");



This is the XML document before the insert:

<?xml version="1.0"?>
<root>
<data>
<!--this is a comment-->
<!--still another comment-->
</data>
</root>


This is the XML document after the insert:

<?xml version="1.0"?>
<root>
<data>
<!--this is a comment-->
<!--still another comment-->
</data>
</root>


#### InsertElement

Syntax

InsertElement(TagName, Position)

Description

Use the InsertElement method to insert an element in an XmlNode at the location specified by Position.

Parameters

 TagName Specify the tagname for the element as a string. Position Specify where you want to insert the element, as a number.

Returns

A reference to the newly created element.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local XmlNode &elementNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");

&commentNode = &dataNode.InsertElement("third", 2);


This is the XML document before the insert:

<?xml version="1.0"?>
<root>
<data>
<first/>
<second/>
</data>
</root>


This is the XML document after the insert:

<?xml version="1.0"?>
<root>
<data>
<first/>
<third/>
<second/>
</data>
</root>


#### InsertElementNS

Syntax

InsertElementNS(NamespaceURI, TagName, Position)

where NamespaceURI can have one of the following forms:

URL.URLname

OR a string URL, such as

http://www.peoplesoft.com/

Description

Use InsertElementNS to insert a new element in an XmlNode, at the location specified by Position.

Parameters

 NamespaceURI Specify the URI that contains the Namespaces for the XmlDoc. TagName Specify the name of the element that you want to create, as a string. Position Specify where you want to insert the element, as a number.

Returns

A reference to the newly created element.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local XmlNode &elementNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root xmlns='http:⇒
//www.peoplesoft.com'/>");

&elementNode = &dataNode.InsertElementNS("http://www.peoplesoft.com", "third", 2);


This is the XML document before the insert:

<?xml version="1.0"?>
<root xmlns="http://www.peoplesoft.com">
<data>
<first/>
<second/>
</data>
</root>


This is the XML document after the insert:

<?xml version="1.0"?>
<root xmlns="http://www.peoplesoft.com">
<data>
<first/>
<third/>
<second/>
</data>
</root>


#### InsertEntityReference

Syntax

InsertEntityReference(Name, Position)

Description

Use the InsertEntityReference method to add an entity reference. An entity reference refers to the content of the named entity.

Parameters

 Name Specify the name of the entity to which this reference refers to. Position Specify where you want to insert the entity reference, as a number.

Returns

A reference to the newly created entity reference.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local XmlNode &entityRef;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");

&entityRef = &dataNode.InsertEntityReference("third", 2);


This is the XML document before the insert:

<?xml version="1.0"?>
<root>
<data>
&first;&second;  </data>
</root>


This is the XML document after the insert:

<?xml version="1.0"?>
<root>
<data>
&first;&third;&second;  </data>
</root>


#### InsertNode

Syntax

InsertNode(&NewNode, {&RefNode | Position})

Description

Use the InsertNode method to insert a new node. The node is inserted either before the node specified by &RefNode, or at the location specified by Position.

&NewNode refers to an already instantiated XmlNode object. You must create the node before you can insert it.

&RefNode refers to an already instantiated XmlNode object.

Parameters

 &NewNode Specify the name of an already instantiated XmlNode that you want to insert. &RefNode | Position Specify either the name of an existing node or the location where you want the node to be inserted.

Returns

A reference to the newly inserted node.

Example

The following PeopleCode program inserts a node using a position:

Local XmlDoc &inXMLDoc, &firstDoc;
Local XmlNode &childNode;

&firstDoc = CreateXmlDoc("<?xml version='1.0'?><myroot><third><child/></third><⇒
/myroot>");
&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root><first/><second/></root>");
&childNode = &firstDoc.DocumentElement.FindNode("/third");

&inXMLDoc.DocumentElement.InsertNode(&childNode, 2);


The following PeopleCode program inserts a node using a reference node:

Local XmlDoc &inXMLDoc, &firstDoc;
Local XmlNode &childNode, &secondNode;

&firstDoc = CreateXmlDoc("<?xml version='1.0'?><myroot><third><child/></third><⇒
/myroot>");
&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root><first/><second/></root>");
&childNode = &firstDoc.DocumentElement.FindNode("/third");
&secondNode = &inXMLDoc.DocumentElement.FindNode("/second");

&inXMLDoc.DocumentElement.InsertNode(&childNode, &secondNode);


The following is the XML document before the insert:

<?xml version="1.0"?>
<root>
<first/>
<second/>
</root>


The following is the XML document after the insert:

<?xml version="1.0"?>
<root>
<first/>
<third>
<child/>
</third>
<second/>
</root>


#### InsertProcessInstruction

Syntax

InsertProcessInstruction(Target, Data, Position)

Description

Use the InsertProcessInstruction method to insert a processing instruction to an XmlNode at the location specified by Position.

Note. Youcannot use this method with a SoapDoc object.

Parameters

 Target Specify the application to which the instruction is directed, as a string. Data Specify the data to be used with the instruction. Position Specify where you want to insert the process instruction, as a number.

Returns

A reference to the newly created processing instruction.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &procInst;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
"secondvalue");

&procInst = &inXMLDoc.DocumentElement.InsertProcessInstruction("third",⇒
"thirdvalue", 2);


This is the XML document before the insert:

<?xml version="1.0"?>
<root>
<?first firstvalue?>
<?second secondvalue?>
</root>


This is the XML document after the inser:

<?xml version="1.0"?>
<root>
<?first firstvalue?>
<?third thirdvalue?>
<?second secondvalue?>
</root>


#### InsertText

Syntax

InsertText(Data, Position)

Description

Use the InsertText method to insert a text node. The node is inserted at the location indicated by Position.

Note. A text node is not the same as a text declaration. The text declaration is added automatically with the CreateXmlDoc function. A text node just contains text within an XmlDoc.

Parameters

 Data Specify the data to be used for the text node, as a string. Position Specify where you want to insert the text ndoe, as a number.

Returns

A reference to the newly created text node.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &textNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");

&textNode = &inXMLDoc.DocumentElement.InsertText("third text", 2);


This is the XML document before the insert:

<?xml version="1.0"?>
<root>
first textsecond text</root>


This is the XML document after the insert:

<?xml version="1.0"?>
<root>
first textthird textsecond text</root>


#### RemoveAllChildNode

Syntax

RemoveAllChildNode()

Description

Use the RemoveAllChildNode method to remove all child nodes for an XmlNode.

Parameters

None.

Returns

None.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &elementNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");

&inXMLDoc.DocumentElement.RemoveAllChildNode();


This is the XML document before the removal:

<?xml version="1.0"?>
<root>
<first/>
<second/>
<third/>
</root>


This is the XML document after the removal:

<?xml version="1.0"?>
<root/>


XmlNode class: AddNode method, InsertNode method, GetChildNode method, FindNode method, FindNodes method, RemoveChildNode method.

#### RemoveChildNode

Syntax

RemoveChildNode({Position | Node})

Description

Use the RemoveChildNode method to remove the child node in an XmlNode specified by Node, or located at Position.

Parameters

 Position | Node Specify the child node that you want to delete, either using its position number or its name.

Returns

A reference to the removed XmlNode.

Example

The following PeopleCode program uses a position:

Local XmlDoc &inXMLDoc;
Local XmlNode &elementNode, &removedNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");

&removedNode = &inXMLDoc.DocumentElement.RemoveChildNode(2);


The following PeopleCode program uses a reference node:

Local XmlDoc &inXMLDoc;
Local XmlNode &elementNode, &removedNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");

&elementNode = &inXMLDoc.DocumentElement.FindNode("/second");
&removedNode = &inXMLDoc.DocumentElement.RemoveChildNode(&elementNode);


This is the XML document before the removal:

<?xml version="1.0"?>
<root>
<first/>
<second/>
<third/>
</root>


This is XML document after the removal:

<?xml version="1.0"?>
<root>
<first/>
<third/>
</root>


XmlNode class: AddNode method, InsertNode method, GetChildNode method, FindNode method, FindNodes method, RemoveAllChildNode method.

### XmlNode Class Properties

The following are the XmlNode properties.

#### AttributesCount

Description

This property returns the number of attributes for an XmlNode, as a number.

Example

Local XmlDoc &inXMLDoc;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");

For &i = 1 To &inXMLDoc.DocumentElement.AttributesCount
/* do some processing of the attributes here */
End-For;


#### ChildNodeCount

Description

This property returns the number of child nodes for an XmlNode, as a number.

#### Index

Description

This property returns the location (or position) of a node in the parent's child list, as a number. The root node always returns a 1.

#### IsNull

Description

This property returns a Boolean value, indicating whether the node is a valid node. Use this property to verify the value of the add or insert XmlNode methods.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &elementNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");

&elementNode = &inXMLDoc.DocumentElement.FindNode("/second");

If &elementNode.IsNull Then
/* do some error processing here, will not find "second" */
End-If;


#### LocalName

Description

This property returns the local part of a namespace as a string. The local part is the second part of the namespace entry. If you want access to the first part of a namespace, use the Prefix property.

XmlNode class: Prefix property.

#### NamespaceURI

Description

This property returns a reference to the namespace URI as a string.

#### NextSibling

Description

This property returns the next child node in an XmlNode, as an XmlNode.

Use the IsNull property to verify that the XmlNode that is returned is valid.

XmlNode class: IsNull property.

#### NodeName

Description

This property returns the name of the XmlNode as a string. You can use this property to rename an XmlNode.

#### NodePath

Description

This property returns the path of the XmlNode, from the root.

#### NodeType

Description

This property returns the type of the XmlNode. You can use either a numeric value or a constant. The values are:

 Numeric Value Constant Value Description 1 %ElementNode Element node 2 %AttributeNode Attribute node 3 %TextNode Text node 4 %CDataSectionNode CData section node 5 %EntityReferenceNode Entity reference node 6 %EntityNode Entity node 7 %ProcessingInstructionNode Processing instruction node 8 %CommentNode Comment node 9 %DocumentNode Document node 10 %DocumentTypeNode Document type node 11 %NotationNode Notation node 12 %XmlDeclNode XML DECL node

#### NodeValue

Description

This property returns the value of the XmlNode, as a string.

#### ParentNode

Description

This property returns a reference to the parent node for the XmlNode, as an XmlNode object.

Use the IsNull property to verify that the XmlNode that is returned is valid.

XmlNode class: IsNull property.

#### Prefix

Description

This property returns the prefix part of a namespace as a string. The prefix is the first part of the namespace entry. If you want access to the second part of a namespace, use the LocalName property.

XmlNode class: LocalName property.

#### PreviousSibling

Description

This property returns a reference to the previous node in the XmlNode, as an XmlNode object.

Use the IsNull property to verify that the XmlNode that is returned is valid.