XmlDoc Class Methods

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

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

Field or Control	Definition
`&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");

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

Field or Control	Definition
`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);

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

Field or Control	Definition
`&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.

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

Field or Control	Definition
`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/>

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

Field or Control	Definition
`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/>

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

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

Field or Control	Definition
`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");

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

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

Field or Control	Definition
`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;

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

Field or Control	Definition
`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("");
&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/>

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

Field or Control	Definition
`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.

Field or Control

Definition

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

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

Field or Control	Definition
`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;