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

See Also

http://www.w3.org

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.

Do not use the XmlDoc object if your message contains cookies.

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.

See Also

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_ADDRESS>F18 HORNET WAY</QE_ADDRESS> 
               <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_ADDRESS>THE ADDRESS</QE_ADDRESS> 
               <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:

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;
Local string &userName;

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

If Not (&MyNode.IsNull) Then
   &userName = &usernode.NodeValue;
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

• An optional SOAP header

• 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.

• AddCDataSection

• AddProcessInstruction

• CopyToPSFTMessage

• CreateDocumentType

• InsertCDataSection

• InsertProcessInstruction

• LoadIBContent

See Also

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

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");

See Also

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

Returns

A number. The values are:

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);

See Also

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.

For example, suppose your XmlDoc had the following structure:

<?xml version="1.0"?>
<QE_SALES_ORDER>
    <QE_ACCT_ID/>
    <QE_ACCOUNT_NAME/>
    <QE_ADDRESS/>
    <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

Returns

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

See Also

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

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/>

See Also

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

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/>

See Also

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();

See Also

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

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");

See Also

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();

See Also

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

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; 

See Also

Array Class.

LoadIBContent

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

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("");
&ret = &inXMLDoc.LoadIBContent(&inStr, "Root");

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("");
&ret = &inXMLDoc.LoadIBContent(&inStr);

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("");
&ret = &inXMLDoc.LoadIBContent(&inStr);

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

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");

See Also

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

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;

See Also

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.

This property is read-only.

See Also

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.

This property is read-only.

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.

AddAttribute

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

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/>");

&postReqNode = &inXMLDoc.DocumentElement.AddElement("postreqresponse");
&candidatesNode = &postReqNode.AddElement("candidates");
&userNode = &candidatesNode.AddElement("user");
&locationNode = &userNode.AddElement("location");

&locationNode.AddAttribute("scenery", "great");
&locationNode.AddAttribute("density", "low");
&locationNode.AddAttribute("blank", "eh?");

See Also

XmlNode class: IsNull property.

AddAttributeNS

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

Returns

None.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");
&childNode = &inXMLDoc.DocumentElement.AddElement("child");
&childNode.AddAttributeNS("http://www.peoplesoft.com", "scenery", "great");

See Also

XmlNode class: IsNull property.

AddCDataSection

Syntax

AddCDataSection(Data)

Description

Use the AddCDataSection to add a CDATA section to an XmlNode.

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

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/>");
&childNode = &inXMLDoc.DocumentElement.AddElement("child");
&cdataNode = &childNode.AddCDataSection("testing...");

The preceding PeopleCode program produces the following:

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

See Also

XmlNode class: InsertCDataSection method.

AddComment

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

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/>");
&childNode = &inXMLDoc.DocumentElement.AddElement("child");
&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>

See Also

XmlNode class: InsertComment method.

AddElement

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

Returns

A reference to the newly created element.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;

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

The preceding PeopleCode program produces the following XML:

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

See Also

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

AddElementNS

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

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/>");
&childNode = &inXMLDoc.DocumentElement.AddElementNS("http://www.peoplesoft.com",⇒
 "child");

AddEntityReference

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

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/>");
&childNode = &inXMLDoc.DocumentElement.AddElement("child");
&entityRef = &childNode.AddEntityReference("MyURL");

The preceding PeopleCode program produces the following XML:

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

See Also

XmlNode class: InsertEntityReference method.

AddNode

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");
&inXMLDoc.DocumentElement.AddNode(&childNode);

See Also

XmlNode class: InsertNode method.

AddProcessInstruction

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

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/>");
&procInst = &inXMLDoc.DocumentElement.AddProcessInstruction("xml-stylesheet",⇒
 "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>

See Also

XmlNode class: InsertProcessInstruction method.

AddText

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

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/>");
&childNode = &inXMLDoc.DocumentElement.AddElement("child");
&textNode = &childNode.AddText("This is text");

The preceding PeopleCode program produces the following XML:

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

See Also

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

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>

See Also

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

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");

See Also

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

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;

See Also

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();

See Also

GenXmlString XmlDoc method

GetAttributeName

Syntax

GetAttributeName(Index)

Description

Use the GetAttributeName method to return the specified attribute.

Parameters

Returns

A string.

Example

Local XmlDoc &inXMLDoc;
Local string &attName;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&inXMLDoc.DocumentElement.AddAttribute("name", "Joe");
&inXMLDoc.DocumentElement.AddAttribute("address", "1234 West Eastland");

&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

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/>");
&inXMLDoc.DocumentElement.AddAttribute("name", "Joe");
&inXMLDoc.DocumentElement.AddAttribute("address", "1234 West Eastland");

&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/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&cdataNode = &dataNode.AddCDataSection("this is a bunch of text");

&theData = &dataNode.GetCDataValue();

See Also

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/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&cdataNode = &dataNode.AddCDataSection("this is a bunch of text");
&cdataNode = &dataNode.AddCDataSection("more text");
&cdataNode = &dataNode.AddCDataSection("still more text");

&theData = &dataNode.GetCDataValues();

See Also

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

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.AddElement("data");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data2");

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

See Also

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.AddElement("data");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data2");

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

See Also

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/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data2");

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

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

See Also

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

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;

See Also

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

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

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/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&cdataNode = &dataNode.AddCDataSection("this is a bunch of text");
&cdataNode = &dataNode.AddCDataSection("still more 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>

See Also

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

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/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&commentNode = &dataNode.AddComment("this is a comment");
&commentNode = &dataNode.AddComment("still another comment");

&commentNode = &dataNode.InsertComment("more comments", 2);

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-->
    <!--more comments-->
    <!--still another comment-->
  </data>
</root>

See Also

XmlNode class: AddComment method.

InsertElement

Syntax

InsertElement(TagName, Position)

Description

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

Parameters

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/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&elementNode = &dataNode.AddElement("first");
&elementNode = &dataNode.AddElement("second");

&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>

See Also

XmlNode class: AddElement method.

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

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'/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&elementNode = &dataNode.AddElement("first");
&elementNode = &dataNode.AddElement("second");

&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

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/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&entityRef = &dataNode.AddEntityReference("first");
&entityRef = &dataNode.AddEntityReference("second");

&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>

See Also

XmlNode class: AddEntityReference method.

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

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>

See Also

XmlNode class: AddNode method.

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

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/>");
&procInst = &inXMLDoc.DocumentElement.AddProcessInstruction("first", "firstvalue");
&procInst = &inXMLDoc.DocumentElement.AddProcessInstruction("second",⇒
 "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>

See Also

XmlNode class: AddProcessInstruction method.

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

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.AddText("first text");
&textNode = &inXMLDoc.DocumentElement.AddText("second text");

&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>

See Also

XmlNode class: AddText method.

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/>");
&elementNode = &inXMLDoc.DocumentElement.AddElement("first");
&elementNode = &inXMLDoc.DocumentElement.AddElement("second");
&elementNode = &inXMLDoc.DocumentElement.AddElement("third");

&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/>

See Also

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

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/>");
&elementNode = &inXMLDoc.DocumentElement.AddElement("first");
&elementNode = &inXMLDoc.DocumentElement.AddElement("second");
&elementNode = &inXMLDoc.DocumentElement.AddElement("third");

&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.AddElement("first");
&elementNode = &inXMLDoc.DocumentElement.AddElement("second");
&elementNode = &inXMLDoc.DocumentElement.AddElement("third");

&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>

See Also

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.

This property is read-only.

Example

Local XmlDoc &inXMLDoc;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&inXMLDoc.DocumentElement.AddAttribute("first", "John");
&inXMLDoc.DocumentElement.AddAttribute("last", "Public");
&inXMLDoc.DocumentElement.AddAttribute("address", "1234 West Eastland");

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.

This property is read-only.

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.

This property is read-only.

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.

This property is read-only.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &elementNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&elementNode = &inXMLDoc.DocumentElement.AddElement("first");

&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.

This property is read-only.

See Also

XmlNode class: Prefix property.

NamespaceURI

Description

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

This property is read-only.

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.

This property is read-only.

See Also

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.

This property is read-write.

NodePath

Description

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

This property is read-only.

NodeType

Description

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

NodeValue

Description

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

This property is read-write.

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.

This property is read-only.

See Also

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.

This property is read-only.

See Also

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.

This property is read-only.

See Also

XmlNode class: IsNull property.