SOAPDoc Object Creation

Because the SOAP header is optional, the header is not validated when you use the ValidateSOAPDoc method.

A SOAP header must be added before any other parts of the SOAPdoc.

Use the AddHeader method to add a header to a SOAPDoc.

Use the HeaderNode property to access an existing SOAPDoc header.

After you have a reference to the header, you can use XmlDoc methods to read the contents of the header (like any node.)

A SOAP envelope is a required portion of the XML Message and is generated automatically using the SOAP schema as specified by SOAP W3C.

A SOAP envelope must be added before you add a SOAP body or a SOAP method. This is an optional method. You need to use this method only if you need to set any additional attributes for the Envelope section. The default SOAP schemas are added automatically.

To set additional custom attributes or schemas on the Envelope element, use the AddEnvelope method. This method adds the envelope element tags and the default schemas for either SOAP or UDDI depending on the value of the parameter passed in. The default encoding styles are also set here. Only one envelope section can be set within one PeopleSoft SOAP XmlDoc.

The SOAPDoc adds only a default URL to the envelope. For some UDDI sites, you may need to add a specific schema yourself. To do this, generate the envelope with no schema, then access the envelope section and add the specific schema URL using the AddAttribute method.

The body is the XmlDoc where the method is defined. The method AddBody starts the body section of the XML SOAPDoc and must be in the XmlDoc before adding in method sections of the message. Only one body section can be set within one SOAPDoc. This is an optional method and must called only if you need to set any additional attributes for the body section. Otherwise the body section is automatically generated in the XmlDoc.

The SOAP body must be added after you add the SOAP envelope, and before you add any methods.

The AddMethod method adds the name of the method element being processed. Additional attributes for this method can be set using the AddAttribute and InsertAttribute XmlNode methods.

You don't have to specifically add a SOAP body section. The body is automatically added when you call the AddMethod method.

The AddParm method sets the parameters for the parameter element of the method as a name, value pair. Multiple parameters can be set and are used in the order that this method is called. If an XML Schema is defined, types can be used using the AddAttribute XmlNode method. Any number of parameter name-value pairs can be added for a method and are added to the XmlDoc in the order that the AddParm methods are called.

You can add parameters to a method only after you add the method. The parameters are added in the order you add them in the PeopleCode program.

Use the following properties to access the different parts of a SOAPDoc object. All of these properties return an XmlNode object.

• BodyNode

• EnvelopeNode

• MethodNode

After you have access to the portion of the SOAPDoc that you want, use the XmlNode properties and methods to manipulate the SOAPDoc.

Use the XmlDoc property to convert a SOAPDoc object to an XmlDoc object, and vice-versa.

The MethodName property returns the name of the method in the SOAPDoc object.

Use the GetParmName and GetParmValue methods to get the name and the values in a SOAPDoc object for each output parameter. You must use the index number of the parameter you want with these methods. You can determine the total number of parameters with the ParmCount property.

The following is the order in which the Soap methods must be called in order to create a valid SOAPDoc.

&SOAPDoc = CreateSOAPDoc(); /* required */
&SOAPDoc.AddEnvelope(0); /* optional */
&SOAPDoc.AddBody(); /* optional */
&SOAPDoc.AddMethod("GetQuote", 1); /* required */
&SOAPDoc.AddParm("symbols", "PSFT");
&SOAPDoc.AddParm("format", "l1c1d1t1");
&OK = &SOAPDoc.ValidateSOAPDoc(); /* optional */

In the body of a SOAP XML response document, you can define a fault section. Generally this is used if in an inbound message has been processed and some sort of error occurred. The text of the message gives further information about the error.

Use the AddFault method to add a fault code and a fault string to the body of a SOAPDoc. Only one fault section can be set within one SOAP XML document.

If you receive a response message that contains a fault, use the FaultCode and FaultString methods to return these values.