Incoming Business Interlink Methods

This section describes the PeopleCode methods you use with Incoming Business Interlinks.

Syntax

AddAttribute(attributename, attributevalue)

Description

The AddAttribute method adds an attribute name and its value to an XML element referenced by a BiDocs object.

Parameters

Parameter	Description
`attributename`	String. The name of the attribute.
`attributevalue`	String. The value of the attribute.

Returns

Number. The return status. NoError, or 0, means the method succeeded.

Example

Here is a set of XML response code.

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

Here is the PeopleCode that builds it.

Local BIDocs &rootDoc, &postreqresponse; 
Local BIDocs &candidates, &location, &user; 
Local number &ret; 
 
&rootDoc = GetBiDoc(""); 
&ret = &rootDoc.AddProcessInstruction("<?xml version=""1.0""?>"); 
&postreqresponse = &rootDoc.CreateElement("postreqresponse"); 
&candidates = &postreqresponse.CreateElement("candidates"); 
&user = &candidates.CreateElement("user"); 
&location = &user.CreateElement("location"); 
&ret = &location.AddAttribute("scenery", "great"); 
&ret = &location.AddAttribute("density", "low"); 
&ret = &location.AddAttribute("blank", "eh?");

Syntax

AddComment(comment)

Description

The AddComment method adds an XML comment after the beginning tag of an XML element referenced by a BiDoc object.

Parameters

Parameter	Description
`comment`	String. The comment.

Returns

Number. The return status. NoError, or 0, means the method succeeded.

Example

Here is a set of XML response code.

<?xml version="1.0"?> 
   <postreqresponse>    
      <error> 
         <!--this is a comment line--> 
         <errorcode>1</errorcode> 
         <errortext></errortext> 
      </error> 
   </postreqresponse>

Here is the PeopleCode that builds it.

Local BIDocs &rootDoc, &postreqresponse, &error, &errorcode, &errortext; 
Local string &blob; 
Local number &ret; 
&rootDoc = GetBiDoc(""); 
 
/* add a processing instruction*/ 
&ret = &rootDoc.AddProcessInstruction("<?xml version=""1.0""?>"); 
/* create an element and add text*/ 
&postreqresponse = &rootDoc.CreateElement("postreqresponse"); 
&error = &postreqresponse.CreateElement("error"); 
&ret = &error.AddComment("this is a comment line"); 
&errorcode = &error.CreateElement("errorcode"); 
&ret = &errorcode.AddText("1"); 
&errortext = &error.CreateElement("errortext");

Syntax

AddProcessInstruction(instruction)

Description

The AddProcessInstruction method adds an XML processing instruction to a BiDocs object. Use this method at the root level of the BiDocs object for Incoming Business Interlinks before you add anything else to the BiDocs object.

Parameters

Parameter	Description
`instruction`	String. The processing instruction.

Returns

Number. The return status. NoError, or 0, means the method succeeded.

Example

Here is a set of XML response code.

<?xml version="1.0"?> 
   <postreqresponse>    
      <error> 
         <!--this is a comment line--> 
         <errorcode>1</errorcode> 
         <errortext></errortext> 
      </error> 
   </postreqresponse>

Here is the PeopleCode that builds it.

Local BIDocs &rootDoc, &postreqresponse; 
Local BIDocs &error, &errorcode, &errortext; 
Local number &ret; 
&rootDoc = GetBiDoc(""); 
 
/* add a processing instruction*/ 
&ret = &rootDoc.AddProcessInstruction("<?xml version=""1.0""?>"); 
/* create an element and add text*/ 
&postreqresponse = &rootDoc.CreateElement("postreqresponse"); 
&error = &postreqresponse.CreateElement("error"); 
&ret = &error.AddComment("this is a comment line"); 
&errorcode = &error.CreateElement("errorcode"); 
&ret = &errorcode.AddText("1"); 
&errortext = &error.CreateElement("errortext");

Syntax

AddText(text)

Description

The AddText method adds text to an XML element referenced by a BiDocs object.

Parameters

Parameter	Description
`text`	String. The text.

Returns

Number. The return status. NoError, or 0, means the method succeeded.

Example

Here is a set of XML response code.

<?xml version="1.0"?> 
   <postreqresponse> 
      <error> 
         <!--this is a comment line--> 
         <errorcode>1</errorcode> 
         <errortext></errortext> 
      </error> 
   </postreqresponse>

Here is the PeopleCode that builds it.

Local BIDocs &rootDoc, &postreqresponse; 
Local BIDocs &error, &errorcode, &errortext; 
Local number &ret; 
&rootDoc = GetBiDoc(""); 
 
/* add a processing instruction*/ 
&ret = &rootDoc.AddProcessInstruction("<?xml version=""1.0""?>"); 
/* create an element and add text*/ 
&postreqresponse = &rootDoc.CreateElement("postreqresponse"); 
&error = &postreqresponse.CreateElement("error"); 
&ret = &error.AddComment("this is a comment line"); 
&errorcode = &error.CreateElement("errorcode"); 
&ret = &errorcode.AddText("1"); 
&errortext = &error.CreateElement("errortext");

Syntax

CreateElement(elementname)

Description

The CreateElement method creates an XML element with the given name within a BiDoc object.

Parameters

Parameter	Description
`elementname`	String. The XML element name.

Returns

BiDocs. The reference to the created element.

Example

Here is a set of XML response code.

<?xml version="1.0"?> 
   <postreqresponse> 
      <error> 
         <errorcode>1</errorcode> 
         <errortext></errortext> 
      </error> 
   </postreqresponse>

Here is the PeopleCode that builds it.

Local BIDocs &rootDoc, &postreqresponse; 
Local BIDocs &error, &errorcode, &errortext; 
Local number &ret; 
 
&rootDoc = GetBiDoc(""); 
 
/* add a processing instruction*/ 
&ret = &rootDoc.AddProcessInstruction("<?xml version=""1.0""?>"); 
/* create an element and add text*/ 
&postreqresponse = &rootDoc.CreateElement("postreqresponse"); 
&error = &postreqresponse.CreateElement("error"); 
&errorcode = &error.CreateElement("errorcode"); 
&ret = &errorcode.AddText("1"); 
&errortext = &error.CreateElement("errortext");

Syntax

GenXMLString()

Description

The GenXMLString method creates an XML string from a BiDocs object. The BiDocs object must contain the shape and data needed for an XML string. This is part of the Incoming Business Interlink functionality, which enables PeopleCode to receive an XML request and return an XML response.

Parameters

None.

Returns

String. The XML string containing the shape and data of the BiDocs object. For example, you can use this method to create an XML string containing an XML response.

Example

The following example takes a BiDocs structure that contains an XML response and puts that into a text string. After this is done, the %Response.Write function can send this as an XML response.

Local BIDocs &rootDoc; 
Local string &xmlString; 
 
/* Create a BiDoc structure containing the data and shape of your XML response (code not shown) */ 
 
/* Generate the XML string containing the data and shape of your XML response from the BiDoc structure */ 
&xmlString = &rootDoc.GenXMLString(); 
%Response.Write(&xmlString);

Syntax

GetAttributeName(attributenumber)

Description

The GetAttributeName method gets the name of an attribute within an XML element referenced by a BiDocs object.

Parameters

Parameter	Description
`attributenumber`	Number. The index number of the attribute.

Returns

String. The name of the attribute.

Example

Here is a set of XML request code.

<?xml version="1.0"?> 
   <postreq> 
      <email>[email protected]</email> 
      <location scenery="great" density="low" blank="eh?"> 
         <city>San Rafael</city> 
         <state>CA</state> 
         <zip>94522</zip> 
         <country>US</country> 
      </location> 
   </postreq>

Here is the PeopleCode that gets the name of the second attribute in the location node. &attrName is density.

Local BIDocs &rootInDoc, postreqDoc, &locationDoc; 
Local string &blob, &attrName; 
&blob = %Request.GetContentBody(); 
    
&rootInDoc = GetBiDoc(&blob); 
&postreqDoc = &rootInDoc.GetNode("postreq"); 
&locationDoc = &postreqDoc.GetNode("location"); 
&attrName = &locationDoc.GetAttributeName(2);

Syntax

GetAttributeValue({attributename | attributenumber})

Description

The GetAttributeValue method gets the value of an attribute within an XML element referenced by a BiDocs object.

Parameters

Parameter	Description
`attributenumber` \| `attributename`	Specify the attribute that you want to get the value for. You can specify either the attribute number (1 for the first attribute, 2 for the second, and so on) or the attribute name (an XML tag.)

Returns

String. The value of the attribute.

Example

Here is a set of XML request code.

<?xml version="1.0"?> 
   <postreq> 
      <email>[email protected]</email> 
      <location scenery="great" density="low" blank="eh?"> 
         <city>San Rafael</city> 
         <state>CA</state> 
         <zip>94522</zip> 
         <country>US</country> 
      </location> 
   </postreq>

Here is the PeopleCode that gets the value of the second attribute in the location node. &attrValue is low.

Local BIDocs &rootInDoc, &postreqDoc, &locationDoc; 
Local string &blob, &attrValue; 
&blob = %Request.GetContentBody(); 
    
&rootInDoc = GetBiDoc(&blob); 
&postreqDoc = &rootInDoc.GetNode("postreq"); 
&locationDoc = &postreqDoc.GetNode("location"); 
&attrValue = &locationDoc.GetAttributeValue(2);

Syntax

GetNode({nodename | nodenumber})

Description

The GetNode method returns a BiDocs reference to a child XML node (element or comment). Use the GetNode method upon a BiDocs reference to an XML element to access the child nodes for that element.

Parameters

Parameter	Description
`nodenumber` \| `nodename`	Specify the node that you want to reference. You can specify either a node number (the first node is 1, the second 2, and so on) or a node name (that is, the XML tag.)

Returns

BiDocs. The returned XML element within a BiDocs object.

Example

Here is a set of XML request code.

<?xml version="1.0"?> 
   <postreq> 
      <email>[email protected]</email> <projtitle> 
         <projsubtitle>first_subtitle</projsubtitle> 
         <projsubtitle>second_subtitle</projsubtitle> <projsubtitle>third_subtitle</projsubtitle> 
      </projtitle> 
   </postreq>

Here is the PeopleCode that gets the postreqDoc element and the projtitle element.

Local BIDocs &rootInDoc, &postreqDoc, &projtitleDoc; 
Local string &name, &blob; 
&blob = %Request.GetContentBody(); 
    
&rootInDoc = GetBiDoc(&blob); 
&postreqDoc = &rootInDoc.GetNode("postreq"); 
&projtitleDoc = &postreqDoc.GetNode("projtitle");

Here is the PeopleCode that gets the postreqDoc element, the projtitle element, and the third projsubtitle element.

Local BIDocs &rootInDoc, &postreqDoc, &projtitleDoc, &projsubtitleDoc; 
Local string &name, &blob; 
&blob = %Request.GetContentBody(); 
    
&rootInDoc = GetBiDoc(&blob); 
&postreqDoc = &rootInDoc.GetNode(1); 
&projtitleDoc = &postreqDoc.GetNode(2); 
&projsubtitleDoc = &projtitleDoc.GetNode(3);

To parse a list of elements like <projsubtitle>, where elements have the same name, you must call GetNode using an index number rather than the element name.

Syntax

ParseXMLString(XMLstring [, DTDValidation])

Description

The ParseXMLString methods fills an existing BiDocs object with the data and shape from an XML string. This is part of the Incoming Business Interlink functionality, which enables PeopleCode to receive an XML request and return an XML response.

Parameters

Parameter	Description
`XMLstring`	A string containing an XML document.
`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.

Parameter

Description

XMLstring

A string containing an XML document.

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

Number. The return status. NoError, or 0, means the method succeeded.

Example

The following example gets an XML request, creates an empty BiDoc, and then fills the BiDoc with the data and shape contained in the XML string. After this is done, the GetDoc method and the GetValue method can get the value of the skills XML element, which is contained within the postreq element in the XML request.

Local BIDocs &rootInDoc, &postreqDoc; 
Local string &blob; 
Local number &ret; 
 
&blob = %Request.GetContentBody(); 
/* process the incoming xml(request)- Create a BiDoc and fill with the request*/ 
&rootInDoc = GetBiDoc(""); 
&ret = &rootInDoc.ParseXMLString(&blob); 
&postreqDoc = &rootInDoc.GetDoc("postreq"); 
&ret = &postreqDoc.GetValue("skills", &skills);