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