Section - 2 : Using XML Built-in Functions

---

The DAL XML API function are registered in keywords, called built-in functions. A DAL XML built-in function performs an operation on a set of parameters and returns a DAL variable in one of the three types: list, integer, or string.

Note: A list type DAL variable always begins with a percent sign (%) and an integer type DAL variable always begins with an octothorpe (#). Floating decimal numbers begin with a dollar sign ($). A string type DAL variable does not begin with a leading symbol.

Here are brief descriptions of the DAL XML built-in functions:

LoadXMLList

%xListH=LoadXMLList(filename);

This function loads a XML document and extracts a XML tree. The only required input parameter is the XML document file name. This function returns the XML tree in the list type DAL variable.

For an example, see the DAL script in scenario 2.

DestroyList

#rc=DestroyList(%xListH);

This function destroys the XML tree created by LoadXMLList. The input parameter is a list type DAL variable that passes the XML tree handle. This function returns one (1) for success or zero (0) for failure. The return DAL variable is of integer type.

For an example, see the DAL script in scenario 2.

GetListElem

aStr=GetListElem(%xListH, SrchCriteria);

This function has two input parameters. The first is a list type DAL variable that passes the XML tree handle. The second is a string type DAL variable that passes the search criteria.

The search criteria can be a node name, followed by up to five pairs of attribute names and values. If success, it returns a text string which contains the first element that matches the search criteria.

This example returns the text of the first matched element node Form with the attribute name ID and value Agent.

IsXMLError

IsXMLError;

This function checks the list for error status. The input parameter is a list type DAL variable that passes the XML tree handle. This function returns one (1) if there no errors occur or zero (0) if errors do occur.

XMLFind

Result=XMLFind(%xListH, srchnode, xpath);

This function locates the XML path from the extracted XML tree and returns a list of matched elements to a list type DAL variable or a matched text to a string type DAL variable, depending on the search request.

This function has three input parameters. The first is a list type DAL variable passed from either the XMLFileExtract rule or the LoadXMLList built-in function. The second is a string type DAL variable that passes a node name from which the search starts. The third is also a string type DAL variable that passes the XML location. If you omit the second parameter, the search starts from the root of the XML tree.

Result can be a list type or a string type DAL variable.

For an example, see the next section.

XMLFirst

#rc=XMLFirst(%listH);

This function takes one input parameter, a list type DAL variable. The variable can be either a XML tree or a list of extracted elements. In any cases, it sets the current pointer to the first element in the specified list. This function returns one (1) for success or zero (0) for failure.

This example returns text from the last element in the list.

XMLNext

#rc=XMLNext(%listH);

This function is similar to XMLFirst. It sets the current pointer to the next node or element in the specified list and returns one (1) for success or zero (0) for failure.

For an example, see XMLFirst.

XMLGetCurName

aStr=XMLGetCurName(%listH);

This function takes one input parameter of the list type. It can be either an XML tree or a list of elements. It returns the element name from the current element. The return value is the string type.

For an example see XMLFirst.

XMLGetCurText

aStr=XMLGetCurText(%listH);

This function is similar to XMLGetCurName. It returns the text from the current element. The return value is the string type. The message is similar to that from the XMLGetCurName function.

For an example see XMLFirst.

XMLFirstAttrib

rc=XMLFirstAttrib(%listH);

This function has one input parameter of a list type variable. It can be an element or attribute list. This function sets the attribute pointer to the first attribute for the current element in the element list or to the first attribute element in the attribute list.

If the input is an element list, use these functions to retrieve the attribute name and value:

• XMLAttrName
• XMLAttrValue

If the input is an attribute list, use these functions to retrieve attribute name and value:

• XMLNthAttrName
• XMLNthAttrValue

For examples, see XMLAttrName and XMLNthAttrName.

XMLNextAttrib

rc=XMLNextAttrib(%listH);

This function is similar to XMLFirstAttrib. It sets the current attribute pointer to the next attribute for the current element in the list or to the next attribute element in the attribute list.

For an example, see XMLAttrName and XMLNthAttrName.

XMLAttrName

aStr=XMLAttrName(%listH);

This function takes a list type DAL variable of input parameter. It returns the name of the current attribute pointed to by the XMLFirstAttrib and XMLNextAttrib functions.

The example returns the second attribute name of the first Form is the list.

XMLAttrValue

aStr=XMLAttrValue(%listH);

This function is similar to XMLAttrName. It returns the value of the current attribute pointed to by the XMLFirstAttrib and XMLNextAttrib functions.

For an example, see XMLAttrName. Use XMLAttrValue to replace XMLAttrName.

XMLNthText

aStr=XMLNthText(%listH,#index);

This function has two input parameters. One is a list type DAL variable that passes a text list. The other is an integer type DAL variable that passes an index number. It returns the nth text value indicated by the index number.

In this example, LoadXMLList returns a text list and XMLNthText gets the first text.

XMLNthAttrName

aStr=XMLNthAttrValue(%listH,#index);

This function has two input parameters. One is a list type DAL variable that passes an attribute list. The other is a integer type DAL variable that passes an index number. It returns the nth attribute name indicated by the index number.

In this example, XMLFind returns a list of attributes and XMLNthAttrName returns the name of the first attribute in the list.

XMLNthAttrValue

aStr=XMLNthAttrValue(%list,#index);

This function is similar to XMLNthAttrName. It returns the nth attribute value indicated by the index number.

For an example, see XMLNthAttrName. Use XMLNthAttrValue to replace XMLNthAttrName.