Proprietary Functions

This section describes the following DataDirect XQuery proprietary functions:

In addition, DataDirect XQuery supports the DB2 V9.1 for Linux/UNIX/Windows, Microsoft SQL Server 2005, and
Oracle 10g R2 XQuery extensions through a set of proprietary (predeclared) XQuery functions that map one-to-one to the database features. See "Microsoft SQL Server 2005 Examples" and "Oracle 10g R2 Examples" for examples.

ddtek:convert-to-xml()

ddtek:convert-to-xml() allows you to convert EDI documents available as xs:string items into XML using DataDirect XML Converters. The behavior is similar to converting an EDI file referenced through the fn:doc() function (see "XML Data Sources"), but ddtek:convert-to-xml() applies the conversion to an xs:string item that may have been extracted from a database, XML document, or other sources, as follows: 

ddtek:convert-to-xml($input as xs:string, $options as xs:string) as  
document-node(element(*,xs:untyped))

where:

$input is a character string representing an EDI message

$options are colon-separated options applied to the conversion.

For example: 

let $edimessage := "ISA+00+ +00+ +01+1515151515  
+01+5151515151 +041201+1217+^+00403+000032123+0+P+*' 
GS+CT+9988776655+1122334455+20041201+1217+128+X+004030' 
ST+831+00128001' 
BGN+00+88200001+20041201' 
N9+BT+88200001' 
TRN+1+88200001' 
AMT+2+100000' 
QTY+46+1' 
SE+7+00128001' 
GE+1+128' 
IEA+1+000032123'" 
return 
  ddtek:convert-to-xml($edimessage, "EDI:long=yes")

ddtek:convert-to-xml() requires that XML Converters are reachable in the current classpath and that a valid XML Converters license is available.

ddtek:decimal()

ddtek:decimal() allows you to specify precision and scale of a decimal value. For example: 

ddtek:decimal($v as xs:anyAtomicType?,$p as xs:integer,$s as xs:integer)  
  as xs:decimal?

ddtek:isValid()

This function is similar to "ddtek:validate()" but instead of returning $arg1 unchanged, it returns a boolean indicating whether it is valid for the specified XML Schema. Unlike ddtek:validate(), ddtek:isValid() does not cause the XQuery execution to throw an exception when the validation fails. An exception is thrown, however, if $schema does not resolve to a valid XML Schema resource. 

declare function ddtek:isValid($arg1 as node(), $schema as xs:string) as 
xs:boolean external;

NOTE: Using this function can degrade performance, depending on the size of the node to be validated and the complexity of the XML schema used to do the validation.

ddtek:javaCast()

When possible, DataDirect XQuery keeps track of the exact Java class that is associated with a given ddtek:javaObject-typed expression. This is needed to map a given function call to a Java method. When DataDirect XQuery is unable to resolve the exact Java class statically, for example when passing ddtek:javaObject as a parameter to or a result from recursive XQuery functions, you can help DataDirect XQuery resolve the Java class by specifying the exact class through ddtek:javaCast(). See "Notes About Using Java Instance Methods" for information about tracking Java classes.

When you use ddtek:javaCast(), DataDirect XQuery assumes statically that the Java class of the expression that is cast is the class specified in the second argument of the call to the function. At runtime, the object is cast to the specified class. For example: 

declare namespace A = "ddtekjava:com.ddtek.ejf.A"; 
declare namespace B = "ddtekjava:com.ddtek.ejf.B"; 
declare function A:A() as ddtek:javaObject external; 
declare function A:f($this as ddtek:javaObject) as 
xs:string external; 
declare function local:f($arg1 as ddtek:javaObject, $count
  as xs:integer)  
  as ddtek:javaObject { 
if ( $count eq 0 )  
then 
  $arg1 
else 
  local:f($arg1, $count - 1) 
}; 
let $a := local:f(A:A(), 1) 
return A:f(ddtek:javaCast($a, "com.ddtek.qa.ejf.A"))

In this example, DataDirect XQuery cannot determine the class of the object that is returned by the local:f (recursive) function. By using ddtek:javaCast(), any possible ambiguity is resolved. If, at runtime, the ddtek:javaCast() operation fails, DataDirect XQuery raises an error.

ddtek:parse()

ddtek:parse() creates an XQuery Data Model instance from a string value, assuming the string contains well-formed XML. You can use this function to query XML information stored in character columns in database tables. When a database does not support an XML data type, sometimes XML information is stored in character columns. In such cases, ddtek:parse() allows you to query the XML character data and use it as an XML data source.

The function’s declaration is: 

ddtek:parse($arg as xs:string) as document-node(element(*,xs:untyped))

where $arg is a well-formed XML document. If $arg is not a well-formed XML document, the query execution is aborted and an exception can be handled at the XQJ level.

Assume a database table is created as: 

create table xmltab (key int primary key, xmlval varchar(2000)) 
insert into xmltab values(1,'<a><b>1</b><b>11</b></a>') 
insert into xmltab values(2,'<a><b>2</b><b>22</b></a>')

The following query returns the key value and b elements from the xmlval column for every b element that contains a value greater than 10: 

for $x  in collection('xmltab')/xmltab 
let $y := ddtek:parse($x/xmlval)//b[xs:integer(.) > 10] 
return (data($x/key),$y)

ddtek:serialize()

This proprietary function controls the process of serializing the query results into XML, XHTML, or HTML notation as specified by XQuery 1.0: An XML Query Language, W3C Recommendation 23 January 2007 located at: http://www.w3.org/TR/2007/REC-xquery-20070123/

The function’s declaration is: 

ddtek:serialize($items as item()*, $options as xs:string) as xs:string

where:

$items specifies the sequence that is to be serialized.

$options specifies the serialization options. See "Serialization Support" for the serialization parameters that you can set using this function.

For example: 

ddtek:serialize(<books><book/></books>, "indent=yes, omit-xml-declaration=no")

returns the xs:string instance: 

<?xml version="1.0"?> 
<books> 
  <book/> 
</books>

ddtek:serialize-to-url()

ddtek:serialize-to-url() is equivalent to ddtek:serialize() except that instead of returning a string of characters, it writes the result to I/O, allowing you to serialize XML nodes to a specified URL, as follows: 

ddtek:serialize-to-url(($items as item()*, $url as 
xs:string, $options as xs:string))

where:

$items specifies the sequence that is to be serialized.

$url specifies the URL where the result needs to be written. $url must be one of the standard URL schemes supported by Java. If no URL scheme is used, "file:" is implied. If the specified URL references an existing file, the file is overwritten; otherwise it is created.

To specify a ZIP as the target for ddtek:serialize-to-url(), prefix the file URL with zip:. You can use the auto-create="yes" option to specify the creation of a new ZIP file. See "Working with ZIP Files" for more information.

$options specifies the serialization options. See "Serialization Support" for the serialization parameters that you can set using this function.

For example: 

ddtek:serialize-to-url(<books><book/></books>, file:///c:/result.xml, 
"indent=yes, omit-xml-declaration=no")

creates a file c:/result.xml on the file system with content: 

<?xml version="1.0"?>  
<books>  
  <book/>  
</books>

Working with ZIP Files

In addition to creating new XML documents, you can use ddtek:serialize-to-url() to create ZIP files, and to create new entries in existing ZIP files.

This example shows how to add a new entry to an existing ZIP file. Note the use of the zip: prefix for the file URL: 

ddtek:serialize-to-url(<e/>, "zip:file:///C:/tmp/test.zip!/dir/file.xml", "")

This example shows how to add a new entry to a new ZIP file, which results from specifying the auto-create="yes" option: 

ddtek:serialize-to-url(<e/>, 
"zip:file:///C:/tmp/test.zip!/dir/file.xml?auto-create=yes", "")

ddtek:trim(), ddtek:rtrim(), and ddtek:ltrim()

These three proprietary functions trim whitespaces to:

The declarations of the function are: 

ddtek:trim($string as xs:string?) as xs:string? 
ddtek:rtrim($string as xs:string?) as xs:string? 
ddtek:ltrim($string as xs:string?) as xs:string?

where $string is the character string that is to be trimmed.

For example: 

ddtek:rtrim("   Gustavo     ")

returns: 

"   Gustavo"

and 

ddtek:trim("   Gustavo     ")

returns: 

"Gustavo"

ddtek:validate()

ddtek:validate() allows you to validate an XML element or document node against an element declaration in an XML Schema. Use this function if it is important to validate that:

NOTE: Using this function can degrade performance, depending on the size of the node to be validated and the complexity of the XML Schema used to do the validation.

See the section "ddtek:isValid()" to learn about alternatives to the ddtek:validate() function

The ddtek:validate() function’s declaration is: 

ddtek:validate($arg1 as node(), $arg2 as xs:string)as node() external;

where:

$arg1 is either an XML element or a document node.

$arg2 is a valid URI. If $arg2 is a relative URI, it is resolved using the base URI of the XQuery expression.

The function attempts to validate $arg1 against the XML Schema referred to by $arg2. If the validation succeeds, the function returns $arg1 unchanged. If the validation fails, DataDirect XQuery raises an error.

The following example first validates the input (req.xml) against the input XML Schema, req.xsd. Then, before returning the results, validates the results against the output XML Schema, reply.xsd.

Assume an XML document, req.xml, containing the following data: 

<request-user-holdings> 
      <user id="Minollo"/> 
      <user id="Jonathan"/> 
      <user id="Bill"/> 
</request-user-holdings>

Also, assume an associated input XML Schema, req.xsd: 

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
 elementFormDefault="qualified"> 
  <xs:element name="request-user-holdings"> 
    <xs:complexType> 
      <xs:sequence> 
        <xs:element maxOccurs="unbounded" ref="user"/> 
      </xs:sequence> 
    </xs:complexType> 
  </xs:element> 
  <xs:element name="user"> 
    <xs:complexType> 
      <xs:attribute name="id" use="required" type="xs:NCName"/> 
    </xs:complexType> 
  </xs:element> 
</xs:schema>

Lastly, assume a second schema, reply.xsd, which is an output XML Schema: 

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"  
  elementFormDefault="qualified"> 
  <xs:element name="reply"> 
    <xs:complexType> 
      <xs:sequence> 
        <xs:element maxOccurs="unbounded" ref="user"/> 
      </xs:sequence> 
    </xs:complexType> 
  </xs:element> 
  <xs:element name="user"> 
    <xs:complexType> 
      <xs:sequence minOccurs="0"> 
        <xs:element ref="name"/> 
        <xs:element maxOccurs="unbounded" ref="holding"/> 
      </xs:sequence> 
      <xs:attribute name="id" use="required" type="xs:NCName"/> 
    </xs:complexType> 
  </xs:element> 
  <xs:element name="name" type="xs:string"/> 
  <xs:element name="holding"> 
    <xs:complexType> 
      <xs:attribute name="shares" use="required" type="xs:double"/> 
      <xs:attribute name="ticker" use="required" type="xs:NCName"/> 
    </xs:complexType> 
  </xs:element> 
</xs:schema>

The following query returns holding information for each of the users in the input document, req.xml. The query first validates the input against the input XML Schema, req.xsd. Then, before returning the results, the query validates the results against the output XML Schema, reply.xsd. 

declare base-uri "file:///c:/requests/"; 
let $validInput := ddtek:validate(doc('req.xml'),'req.xsd') 
let $output := 
  <reply>{ 
    for $req-user in $validInput//user 
    let $userid := xs:string($req-user/@id) 
    return 
      <user id='{$userid}'>{ 
        for $db-user in collection('users')/users[userid = $userid] 
        return ( 
          <name>{concat($db-user/firstname,' ',$db-user/lastname)}</name>, 
          for $holding in collection('holdings')/holdings  
          where $holding/userid = $userid 
          return 
            <holding ticker='{$holding/stockticker}' 
                     shares='{$holding/shares}'/> 
          ) 
      }</user> 
  }</reply> 
let $validatedOutput := ddtek:validate($output,'reply.xsd') 
return $validatedOutput

ddtek:wscall()

This proprietary function allows you to invoke a Web service operation synchronously using the SOAP protocol over HTTP (see http://www.w3.org/TR/soap11 for details about the SOAP protocol).

The function’s declarations are: 

ddtek:wscall($location as element(), $payload as element())  
  as document-node( element(*, xs:untyped) ) 
ddtek:wscall($location as element(), $header as element(), 
  $payload as element())  
  as document-node( element(*, xs:untyped) )

where:

$location is an element named location as defined in the following XML Schema: 

<?xml version="1.0"?> 
<xsd:schema  
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"  
 targetNamespace="http://www.datadirect.com/xquery"> 
  <xsd:element name="location"> 
    <xsd:complexType> 
       <xsd:attribute name="address" type="xsd:anyURI"/> 
       <xsd:attribute name="soapaction" type="xsd:string" 
         use="optional"/> 
       <xsd:attribute name="timeout" type="xsd:unsignedInt" 
         use="optional" default="30000"/> 
       <xsd:attribute name="user" type="xsd:string"  
         use="optional"/> 
       <xsd:attribute name="password" type="xsd:string" 
         use="optional"/> 
       <xsd:attribute name="http.proxyHost"  
         type="xsd:anyURI" use="optional"/> 
       <xsd:attribute name="http.proxyPort"  
         type="xsd:unsignedInt" use="optional"/> 
       <xsd:attribute name="http.proxyUser"  
         type="xsd:string" use="optional"/> 
       <xsd:attribute name="http.proxyPassword"  
         type="xsd:string" use="optional"/> 
       <xsd:attribute name="http.version" 
         type="xsd:string" use="optional" default="1.1"/ 
       <xsd:attribute name="compression" 
         type="xsd:string" use="optional" default=""/ 
       <xsd:attribute name="wrapAnyErrorsAsSOAPFault"  
         type="xsd:boolean" use="optional" default="true"/> 
    </xsd:complexType> 
  </xsd:element> 
</xsd:schema>

For example: 

<ddtek:location  
  address="http://www.ejse.com/WeatherService/Service.asmx" 
  soapaction="http://ejse.com/WeatherService/GetWeatherInfo"/>

The following table defines the attributes in the XML schema.

Attribute Name
Description
address
Web service end point
soapaction
The SOAPAction HTTP header field
timeout
The connection timeout in milliseconds
user
User name for the HTTP connection, if required
password
Password for the HTTP connection if required
http:proxyHost
Proxy host address
http:proxyPort
Proxy port number
http:proxyUser
Proxy user name
http:proxyPassword
Proxy password
http:version
Version of the HTTP protocol to use when communicating with the server
compression
The type of file compression used to transmit the message. The default is off; you can specify "gzip".
wrapAnyErrorsAsSOAPFault
Determines if exceptions are returned

$header is the SOAP Header payload. See the SOAP Header specification at http://www.w3.org/TR/soap11/#_Toc478383497 for details. For example: 

<tns:UserCreds xmlns:tns="http://ejse.com/WeatherService/"> 
    <tns:UserName>marypelle@acme.org</tns:UserName> 
    <tns:Password>30Mp75Y8p49s</tns:Password> 
</tns:UserCreds>

$payload is an element that defines the payload expected by the web service, which is usually in a format defined by the Web Services Description Language (WSDL). See http://www.w3.org/TR/wsdl for details about WSDL. For example: 

<tns:GetWeatherInfo xmlns:tns="http://ejse.com/WeatherService/"> 
    <tns:zipCode>01803</tns:zipCode> 
</tns:GetWeatherInfo>

The return value is a document node that contains the web service response.

The following example invokes a web service that requires registration and uses the SOAP header to specify the user’s credentials: 

ddtek:wscall( 
<ddtek:location  
  address="http://www.ejse.com/WeatherService/Service.asmx" 
  soapaction="http://ejse.com/WeatherService/GetWeatherInfo"/>, 
<tns:UserCreds xmlns:tns="http://ejse.com/WeatherService/"> 
    <tns:UserName>marypelle@acme.org</tns:UserName> 
    <tns:Password>30Mp75Y8p49s</tns:Password> 
</tns:UserCreds>, 
<tns:GetWeatherInfo xmlns:tns="http://ejse.com/WeatherService/"> 
    <tns:zipCode>01803</tns:zipCode> 
</tns:GetWeatherInfo>  
)