Progress XML Tools Users' Guide

Sonic ESBProgress XML Tools Users' Guide

PROGRESS® SONIC® 8.0

Sonic ESB

Progress XML Tools Users' GuideMarch 2010

BUSINESS MAKING PROGRESS™

Progress XML Tools Users' GuideProgress Sonic 8.0

Publication date 23 Mar 2010Copyright © 2001-2010 Progress Software Corporation and/or its subsidiaries or affiliates.

Legal Notices

These materials and all Progress(R) software products are copyrighted and all rights are reserved by Progress Software Corporation. The information inthese materials is subject to change without notice, and Progress Software Corporation assumes no responsibility for any errors that may appear therein.The references in these materials to specific platforms supported are subject to change.

Actional, Apama, Apama (and Design), Artix, Business Empowerment, DataDirect (and design), DataDirect Connect, DataDirect Connect64, DataDirectTechnologies, DataDirect XML Converters, DataDirect XQuery, DataXtend, Dynamic Routing Architecture, EdgeXtend, Empowerment Center, Fathom,FUSE Mediation Router, FUSE Message Broker, FUSE Services Framework, IntelliStream, IONA, IONA (and design), Making Software Work Together,Mindreef, ObjectStore, OpenEdge, Orbix, PeerDirect, POSSENET, Powered by Progress, PowerTier, Progress, Progress DataXtend, Progress Dynamics,Progress Business Empowerment, Progress Empowerment Center, Progress Empowerment Program, Progress OpenEdge, Progress Profiles, ProgressResults, Progress Software Developers Network, Progress Sonic, ProVision, PS Select, SequeLink, Shadow, SOAPscope, SOAPStation, Sonic, Sonic ESB,SonicMQ, Sonic Orchestration Server, SonicSynergy, SpeedScript, Stylus Studio, Technical Empowerment, WebSpeed, Xcalia (and design), and YourSoftware, Our Technology Experience the Connection are registered trademarks of Progress Software Corporation or one of its affiliates or subsidiariesin the U.S. and/or other countries. AccelEvent, Apama Dashboard Studio, Apama Event Manager, Apama Event Modeler, Apama Event Store, ApamaRisk Firewall, AppsAlive, AppServer, ASPen, ASP-in-a-Box, BusinessEdge, Business Making Progress, Cache-Forward, DataDirect Spy, DataDirectSupportLink, FUSE, Future Proof, GVAC, High Performance Integration, ObjectStore Inspector, ObjectStore Performance Expert, OpenAccess, Orbacus,Pantero, POSSE, ProDataSet, Progress ESP Event Manager, Progress ESP Event Modeler, Progress Event Engine, Progress RFID, Progress SoftwareBusiness Making Progress, PSE Pro, Savvion, SectorAlliance, SeeThinkAct, Shadow z/Services, Shadow z/Direct, Shadow z/Events, Shadow z/Presentation,Shadow Studio, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame,SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, Sonic Business Integration Suite, Sonic Process Manager, Sonic CollaborationServer, Sonic Continuous Availability Architecture, Sonic Database Service, Sonic Workbench, Sonic XML Server, The Brains Behind BAM, WebClient,and Who Makes Progress are trademarks or service marks of Progress Software Corporation and/or its subsidiaries or affiliates in the U.S. and othercountries. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Any othertrademarks contained herein are the property of their respective owners.

Third Party Acknowledgements:

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate Xalan-J v2.4.1 from the Apache Foundation. Such technology is subjectto the following terms and conditions: The Apache Software License, Version 1.1 - Copyright (C) 1999-2003 The Apache Software Foundation. All rightsreserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binaryform must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials providedwith the distribution. 3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This productincludes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the softwareitself, if and wherever such third-party acknowledgments normally appear. 4. The names "Xalan" and "Apache Software Foundation" must not be usedto endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected]. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the ApacheSoftware Foundation. THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITEDTO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THEAPACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, ORCONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THEPOSSIBILITY OF SUCH DAMAGE. This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundationand was originally based on software copyright 1999, Lotus Development Corporation., http://www.lotus.com. For more information on the ApacheSoftware Foundation, please see http://www.apache.org/.

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate DSTC Xs3P version 1.1 from DSTC Pty Ltd. PSC will, at Licensee's request,provide copies of the source code for this third party technology, including modifications, if any, made by PSC. PSC may charge reasonable shipping andhandling charges for such distribution. Licensee may also obtain the source code through http://communities.progress.com/pcom/docs/DOC-16051 byfollowing the instructions set forth therein. - DSTC Public License. The contents of this file are subject to the DSTC Public License Version 1.1 (the'License') (provided herein); you may not use this file except in compliance with the License. Software distributed under the License is distributed on an'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitationsunder the License. The Original Code is xs3p. The Initial Developer of the Original Code is DSTC. Portions created by DSTC are Copyright (C) 2001,2002 DSTC Pty Ltd. All Rights Reserved.

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate version 8.9 of the Saxon XSLT and XQuery Processor from Saxonica Limited(http://www.saxonica.com/) which is available from SourceForge (http://sourceforge.net/projects/saxon/). PSC will, at Licensee's request, provide copiesof the source code for this third party technology, including modifications, if any, made by PSC. PSC may charge reasonable shipping and handlingcharges for such distribution. Licensee may also obtain the source code through http://communities.progress.com/pcom/docs/DOC-16051 by followingthe instructions set forth therein. - Mozilla Public License Version 1.0 (the "License"); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.mozilla.org/MPL. Software distributed under the License is distributed on an "AS IS" basis, WITHOUTWARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. TheOriginal Code of Saxon comprises all those components which are not explicitly attributed to other parties. The Initial Developer of the Original Code isMichael Kay. Until February 2001 Michael Kay was an employee of International Computers Limited (now part of Fujitsu Limited), and original codedeveloped during that time was released under this license by permission from International Computers Limited. From February 2001 until February2004 Michael Kay was an employee of Software AG, and code developed during that time was released under this license by permission from SoftwareAG, acting as a "Contributor". Subsequent code has been developed by Saxonica Limited, of which Michael Kay is a Director, again acting as a "Contributor".A small number of modules, or enhancements to modules, have been developed by other individuals (either written specially for Saxon, or incorporatedinto Saxon having initially been released as part of another open source product). Such contributions are acknowledged individually in comments attachedto the relevant code modules. All Rights Reserved.

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate Model Object Framework v2. Such technology is subject to the followingterms and conditions: The ModelObjects Group Software License, Version 1.0 - Redistribution and use in source and binary forms, with or withoutmodification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, thislist of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and thefollowing disclaimer in the documentation and/or other materials provided with the distribution. 3. The end-user documentation included with theredistribution, if any, must include the following acknowledgement: "This product includes software developed by the ModelObjects Group(http://www.modelobjects.com)." Alternatively, this acknowledgement may appear in the software itself, if and wherever such third-party acknowledgementsnormally appear. 4. The name "ModelObjects" must not be used to endorse or promote products derived from this software without prior written permission.For written permission, please contact [email protected]. 5. Products derived from this software may not be called "ModelObjects", nor mayModelObjects" appear in thier name, without prior written permission of the ModelObjects Group. THIS SOFTWARE IS PROVIDED "AS IS" AND ANYEXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESSFOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE MODEL OBJECTS GROUP OR ITS CONTRIBUTORS BE LIABLE FORANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENTOF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANYTHEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAYOUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate OpenSAML Java Distribution v1.0.1. Such technology is subject to thefollowing terms and conditions: The OpenSAML License, Version 1. Copyright (C) 2002 - University Corporation for Advanced Internet Development, Inc.All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditionsare met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions inbinary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materialsprovided with the distribution, if any, must include the following acknowledgment: "This product includes software developed by the University Corporationfor Advanced Internet Development <http://www.ucaid.edu>Internet2 Project. Alternately, this acknowledegement may appear in the software itself, ifand wherever such third-party acknowledgments normally appear. Neither the name of OpenSAML nor the names of its contributors, nor Internet2, northe University Corporation for Advanced Internet Development, Inc., nor UCAID may be used to endorse or promote products derived from this softwarewithout specific prior written permission. For written permission, please contact [email protected]. Products derived from this software may notbe called OpenSAML, Internet2, UCAID, or the University Corporation for Advanced Internet Development, nor may OpenSAML appear in their name,without prior written permission of the University Corporation for Advanced Internet Development. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHTHOLDERS AND CONTRIBUTORS "AS IS" AND WITH ALL FAULTS. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT ARE DISCLAIMED ANDTHE ENTIRE RISK OF SATISFACTORY QUALITY, PERFORMANCE, ACCURACY, AND EFFORT IS WITH LICENSEE. IN NO EVENT SHALL THE COPYRIGHTOWNER, CONTRIBUTORS OR THE UNIVERSITY CORPORATION FOR ADVANCED INTERNET DEVELOPMENT, INC. BE LIABLE FOR ANY DIRECT,INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTEGOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OFTHIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate Colt cern.colt* packages v1.0.3 (ca1420-20040626). Such technologyis subject to the following terms and conditions: Packages cern.colt* , cern.jet*, cern.clhep - Copyright (c) 1999 CERN - European Organization forNuclear Research. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted withoutfee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supportingdocumentation. CERN makes no representations about the suitability of this software for any purpose. It is provided "as is" without expressed or impliedwarranty.

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate Mozilla Rhino v1.5R3. The contents of this file are subject to the NetscapePublic License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License athttp://www.mozilla.org/NPL/. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, eitherexpress or implied. See the License for the specific language governing rights and limitations under the License. The Original Code is Mozilla Communicator

client code, released March 31, 1998. The Initial Developer of the Original Code is Netscape Communications Corporation. Portions created by Netscapeare Copyright (C) 1998-1999 Netscape Communications Corporation. All Rights Reserved. PSC will, at Licensee's request, provide copies of the sourcecode for this third party technology, including modifications, if any, made by PSC. PSC may charge reasonable shipping and handling charges for suchdistribution. Licensee may also obtain the source code through http://communities.progress.com/pcom/docs/DOC-16051 by following the instructionsset forth therein.

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate NET Security Library v1.0. Such technologies are subject to the followingterms and conditions: Copyright (C) 2002-2003, The KPD-Team All rights reserved. http://www.mentalis.org/ Redistribution and use in source and binaryforms, with or without modification, are permitted provided that the following conditions are met: - Redistributions of source code must retain the abovecopyright notice, this list of conditions and the following disclaimer. - Neither the name of the KPD-Team, nor the names of its contributors may be usedto endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHTHOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHTOWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESSINTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDINGNEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCHDAMAGE. Copyright (C) 2002-2003, The KPD-Team.

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate Another Tool for Language Recognition v2.7.4. Such technologies aresubject to the following terms and conditions: ANTLR Software License http://www.antlr.org/rights.html We reserve no legal rights to the ANTLR--it isfully in the public domain. An individual or company may do whatever they wish with source code distributed with ANTLR or the code generated byANTLR, including the incorporation of ANTLR, or its output, into commercial software. We encourage users to develop software with ANTLR. However,we do ask that credit is given to us for developing ANTLR. By "credit", we mean that if you use ANTLR or incorporate any source code into one of yourprograms (commercial product, research project, or otherwise) that you acknowledge this fact somewhere in the documentation, research report, etc...If you like ANTLR and have developed a nice tool with the output, please mention that you developed it using ANTLR. In addition, we ask that the headersremain intact in our source code. As long as these guidelines are kept, we expect to continue enhancing this system and expect to make other toolsavailable as they are completed.

Table of ContentsI. XML Editor ................................................................................................................................................... 11

1. Concepts ............................................................................................................................................. 13XML editor: Source page .................................................................................................................... 14XML editor: Tree page ....................................................................................................................... 15XML editor: Outline view .................................................................................................................... 16

2. Tasks ................................................................................................................................................. 17Working with the Source page ............................................................................................................. 18

Navigating in the Source page of the XML editor .............................................................................. 19Editing XML in the Source page .................................................................................................... 20Indenting XML in the Source page ................................................................................................ 21Commenting XML in the Source page of the XML editor ..................................................................... 22Cutting, copying, and pasting XML in the Source page of the XML editor ................................................ 23Highlighting XML in the Source page of the XML editor ...................................................................... 24

Working with the Tree page ................................................................................................................ 25Navigating in the Tree page of the XML editor .................................................................................. 26Viewing an XML document in the Tree page .................................................................................... 27Editing XML in the Tree page ....................................................................................................... 29Adding nodes in the Tree page of the XML editor .............................................................................. 30Cutting, copying, and pasting nodes in the Tree page of the XML editor .................................................. 31Deleting nodes from the Tree page of the XML editor ......................................................................... 32Reordering nodes in the Tree page of the XML editor ......................................................................... 33

Using XML code completion ................................................................................................................ 34Using Undo and Redo in the XML editor ................................................................................................ 37Saving an XML document ................................................................................................................... 38Searching in an XML document ........................................................................................................... 39Finding all occurrences of an XML element in a file ................................................................................... 40Browsing XML source code ................................................................................................................. 41Using code folding in the XML editor ..................................................................................................... 42Creating a new XML file ..................................................................................................................... 43

Creating an XML document from an XML schema, WSDL, or another XML file ......................................... 44Customizing the generation of XML ............................................................................................... 45

Creating an XML schema from an XML instance ....................................................................................... 46Associating an XML schema with an XML document .................................................................................. 47Validating XML ................................................................................................................................ 48Running XPath expressions .................................................................................................................. 49Working with the Outline page ............................................................................................................. 50

Navigating in the Outline view ..................................................................................................... 51Filtering content in the Outline view .............................................................................................. 52Synchronizing the Outline view with the editor ................................................................................. 53

Specifying preferences for the XML editor ............................................................................................... 54Specifying Colors for the XML editor .............................................................................................. 55Specifying formatting preferences ................................................................................................. 56

II. XML Schema Editor ...................................................................................................................................... 573. Concepts ............................................................................................................................................. 59

XML Schema editor: Source page ......................................................................................................... 60XML Schema editor: Tree page ............................................................................................................ 61XML Schema editor: Diagram page ........................................................................................................ 62XML Schema editor: Outline view ......................................................................................................... 63XML Schema editor: Palette ................................................................................................................ 64

4. Tasks ................................................................................................................................................. 65Working with XML schemas in the Tree page ........................................................................................... 66

Navigating in the Tree page of the XML Schema editor ....................................................................... 67Adding XML schema components in the Tree page ............................................................................ 68Dragging nodes from the Tree page to another editor ......................................................................... 69

7Sonic ESB Progress XML Tools Users' Guide Progress Sonic 8.0

Using Undo and Redo ............................................................................................................... 70Reordering nodes in the Tree page ................................................................................................ 71Cutting, copying, and pasting nodes in the Tree page ........................................................................ 72Editing nodes in the Tree page ..................................................................................................... 73Deleting nodes in the Tree page ................................................................................................... 74

Working with XML schemas in the Diagram page ..................................................................................... 75Navigating in the Diagram page of the XML Schema editor ................................................................. 76Adding and deleting XML schema components in the Diagram page ...................................................... 77Moving schema elements in the Diagram page of the XML Schema editor .............................................. 78

Defining an XML Schema .................................................................................................................... 79Defining elements and element references in XML Schemas ................................................................ 81Defining attributes and attribute references in XML schemas ............................................................... 83Defining groups and group references in XML Schemas ...................................................................... 84Defining simple types in XML schemas .......................................................................................... 86Defining complex types in XML Schemas ....................................................................................... 87Defining restriction and extension type nodes in XML Schemas ............................................................ 88Defining content types in XML Schemas ......................................................................................... 89Defining aggregator types in XML Schemas ..................................................................................... 90Defining facet types in XML Schemas ............................................................................................. 91Defining notations .................................................................................................................... 93Defining Include, Import, and Redefine nodes ................................................................................. 94Including and importing external XML schemas ............................................................................... 95

Adding an Identity Constraint to an Element ............................................................................ 96Adding annotation, documentation, text, and comments to XML Schemas ....................................... 98

Editing XML schemas .............................................................................................................. 100Saving an XML schema ............................................................................................................. 101Specifying colors for the XML Schema editor .................................................................................. 102

5. Reference .......................................................................................................................................... 103What Is an XML Schema? ................................................................................................................ 104xsd:schema properties ..................................................................................................................... 106Simple types in XML Schemas ............................................................................................................ 107Complex types in XML Schemas ......................................................................................................... 109

III. XPath Helper ............................................................................................................................................ 1116. About XPath Helper ............................................................................................................................ 1157. Tasks ................................................................................................................................................ 117

Launching the XPath Helper .............................................................................................................. 118Viewing the source document for an XPath expression ............................................................................. 119Generating XPath expressions ............................................................................................................. 120Building XPath expressions ............................................................................................................... 121Evaluating an XPath expression ........................................................................................................... 122Clearing an XPath expression .............................................................................................................. 123About XML document structure .......................................................................................................... 124XPath Helper target node .................................................................................................................. 125Selecting a target node .................................................................................................................... 126Removing a target node .................................................................................................................... 127Selecting a key node ........................................................................................................................ 128Removing a key node ....................................................................................................................... 129Running sample queries with XPath Helper ............................................................................................ 130Internationalizing XPath ................................................................................................................... 131

8. References ........................................................................................................................................ 133Getting started with queries .............................................................................................................. 135

Querying multiple documents .................................................................................................... 136Restrictions on queries with XPath Helper ..................................................................................... 137Obtaining all marked-up text ...................................................................................................... 138Obtaining part of an XML document ............................................................................................. 139Obtaining all elements of a particular name ................................................................................... 140Obtaining all elements of a particular name from a particular branch .................................................... 141

Sonic ESB Progress XML Tools Users' Guide Progress Sonic 8.08

Different results from similar queries ........................................................................................... 142Queries that return more than you want ........................................................................................ 143Specifying attributes in queries ................................................................................................... 144Filtering the results of XPath queries ............................................................................................ 145

How XPath Helper evaluates a filter ..................................................................................... 146Filter examples .............................................................................................................. 147Quotation marks in filters .................................................................................................. 148Multiple filters ................................................................................................................ 149Filters and attributes ....................................................................................................... 150

Using wildcards in queries ......................................................................................................... 151Calling functions in queries ........................................................................................................ 152Case sensitivity and blank spaces in queries ................................................................................... 153Precedence of query operators .................................................................................................... 154

Specifying nodes to evaluate ............................................................................................................. 155Using context operators ............................................................................................................ 156Starting at the context node ....................................................................................................... 157Starting at the root node ........................................................................................................... 158Descending along branches ....................................................................................................... 159Explicitly specifying the current context ......................................................................................... 160Specifying children or descendants of parent nodes .......................................................................... 161Examples of XPath expression results ........................................................................................... 162Specifying an axis in a query ...................................................................................................... 163Supported XPath axes .............................................................................................................. 164Axes that represent the whole XML document ................................................................................ 168

Handling strings and text .................................................................................................................. 169Finding identical strings ............................................................................................................ 170Finding elements containing specified strings ................................................................................. 171Finding substrings that occur before specified strings ........................................................................ 172Finding substrings that occur after specified strings .......................................................................... 173Finding substrings by position .................................................................................................... 174Concatenating strings ............................................................................................................... 175Determining the number of characters in a string ............................................................................ 176Handling white space in strings .................................................................................................. 177Replacing characters in strings ................................................................................................... 178Converting objects to strings ...................................................................................................... 179Finding strings that start with a particular string ............................................................................. 180Obtaining the text contained in a node ......................................................................................... 181

Specifying Boolean expressions and functions ......................................................................................... 182Converting an object to Boolean .................................................................................................. 183Obtaining Boolean values .......................................................................................................... 184Determining the context node language ......................................................................................... 185

Specifying number operations and functions .......................................................................................... 186Performing arithmetic operations ................................................................................................ 187Converting an object to a number ................................................................................................ 188Obtaining the sum of the values in a node set ................................................................................ 189Obtaining the largest, smallest, or closest number .......................................................................... 190

Comparing values ........................................................................................................................... 191About comparison operators ...................................................................................................... 192How XPath Helper evaluates comparisons .................................................................................... 193Priority of object types in comparisons .......................................................................................... 194Comparing node sets ............................................................................................................... 195Comparing Boolean values with = and != ..................................................................................... 196Comparing single values with = and != ....................................................................................... 197Comparing single values with <=, <, >, and >= ......................................................................... 198Examples of comparisons ......................................................................................................... 199

Finding a particular node .................................................................................................................. 200About node positions ............................................................................................................... 201


Determining the position number of a node .................................................................................... 202Positions in relation to parent nodes ............................................................................................ 203Finding nodes relative to the last node in a set ................................................................................ 204Finding multiple nodes ............................................................................................................ 205Finding the first node that meets a condition ................................................................................. 206Finding an element with a particular ID ....................................................................................... 207The id() function ..................................................................................................................... 208Unique IDs ............................................................................................................................ 209Generating temporary IDs for nodes ............................................................................................ 210

Obtaining particular node types with node tests ..................................................................................... 211Node tests ............................................................................................................................ 212About the document object ....................................................................................................... 213Finding an element with a particular key ...................................................................................... 214

Obtaining a union ........................................................................................................................... 215Obtaining information about a node or a node set ................................................................................... 216

Obtaining the name of a node .................................................................................................... 217Obtaining the namespace URI ................................................................................................... 218Obtaining the local name .......................................................................................................... 219Obtaining the expanded name ................................................................................................... 220Specifying wildcards with namespaces ........................................................................................ 221Examples of namespaces in queries ............................................................................................ 222Obtaining the URI for an unparsed entity ...................................................................................... 223Determining the number of nodes in a collection ............................................................................ 224Determining the context size ..................................................................................................... 225

Using XPath expressions in stylesheets ................................................................................................ 226Defining variables in stylesheets ................................................................................................. 228Obtaining system properties when using XPath in stylesheets ............................................................ 229Available functions when using XPath in stylesheets ......................................................................... 230Current node for the current XSLT template ................................................................................... 231

Using the document() function to access other documents ......................................................................... 232Example of calling the document() function ................................................................................... 233

XPath functions quick reference .......................................................................................................... 234XPath syntax quick reference .............................................................................................................. 236Abbreviations in XPath expressions ..................................................................................................... 238


Part I. XML Editor1. Concepts ..................................................................................................................................................... 13

XML editor: Source page ............................................................................................................................ 14XML editor: Tree page ............................................................................................................................... 15XML editor: Outline view ............................................................................................................................ 16

2. Tasks ......................................................................................................................................................... 17Working with the Source page ..................................................................................................................... 18

Navigating in the Source page of the XML editor ...................................................................................... 19Editing XML in the Source page ............................................................................................................ 20Indenting XML in the Source page ........................................................................................................ 21Commenting XML in the Source page of the XML editor ............................................................................. 22Cutting, copying, and pasting XML in the Source page of the XML editor ........................................................ 23Highlighting XML in the Source page of the XML editor .............................................................................. 24

Working with the Tree page ........................................................................................................................ 25Navigating in the Tree page of the XML editor .......................................................................................... 26Viewing an XML document in the Tree page ............................................................................................ 27Editing XML in the Tree page ............................................................................................................... 29Adding nodes in the Tree page of the XML editor ...................................................................................... 30Cutting, copying, and pasting nodes in the Tree page of the XML editor .......................................................... 31Deleting nodes from the Tree page of the XML editor ................................................................................. 32Reordering nodes in the Tree page of the XML editor ................................................................................. 33

Using XML code completion ........................................................................................................................ 34Using Undo and Redo in the XML editor ........................................................................................................ 37Saving an XML document ........................................................................................................................... 38Searching in an XML document ................................................................................................................... 39Finding all occurrences of an XML element in a file ........................................................................................... 40Browsing XML source code ......................................................................................................................... 41Using code folding in the XML editor ............................................................................................................. 42Creating a new XML file ............................................................................................................................. 43

Creating an XML document from an XML schema, WSDL, or another XML file ................................................. 44Customizing the generation of XML ....................................................................................................... 45

Creating an XML schema from an XML instance ............................................................................................... 46Associating an XML schema with an XML document .......................................................................................... 47Validating XML ........................................................................................................................................ 48Running XPath expressions .......................................................................................................................... 49Working with the Outline page ..................................................................................................................... 50

Navigating in the Outline view ............................................................................................................. 51Filtering content in the Outline view ...................................................................................................... 52Synchronizing the Outline view with the editor ......................................................................................... 53

Specifying preferences for the XML editor ....................................................................................................... 54Specifying Colors for the XML editor ...................................................................................................... 55Specifying formatting preferences ......................................................................................................... 56

Chapter 1. ConceptsXML editor: Source page .................................................................................................................................... 14XML editor: Tree page ....................................................................................................................................... 15XML editor: Outline view .................................................................................................................................... 16


XML editor: Source pageUse the Source page to create, edit, save and run XPath queries on XML documents.

The Source page includes the following text formatting features:

• Code folding

• Code completion

• Code color specification

The Source page provides XML validation. When the document is not well-formed, errors are flagged in red on the rightscrollbar and in the left margin. Explanations of errors appear in the Problems view and in Tool Tips.

Related tasks

"Navigating in the Source page of the XML editor " on page 19

"Editing XML in the Source page" on page 20

"Searching in an XML document " on page 39

"Browsing XML source code " on page 41

"Using code folding in the XML editor " on page 42

"Using XML code completion " on page 34


Chapter 1. Concepts

XML editor: Tree pageThe tree page displays any XML document (conforming to the XML 1.1 specification) in the form of a (left aligned) treestarting from the document root. The tree has two columns:

• Node displays the tree nodes with each node in a different row

• Content displays any description for the node

You can move, edit, add and delete nodes in the Tree page using the buttons on the toolbar, right clicking or accessingitems in the Main menu. No XML validation errors appear in the Tree Page.

Related tasks

"Viewing an XML document in the Tree page " on page 27

"Navigating in the Tree page of the XML editor " on page 26

"Editing XML in the Tree page" on page 29


XML editor: Tree page

XML editor: Outline viewThe Outline view displays the elements of the document that is currently open in the editor area in the form of a hierarchicaltree.

When you click an element in the Outline view, the document in the editor scrolls to the corresponding element. Also,selecting an element in the document highlights the corresponding element in the Outline view.

The Outline View is dynamic in nature, immediately reflecting any edits to the document in the editor. The text that iscurrently being modified is highlighted in the middle of the Outline view.

The Outline view is a read-only view.

Use the toolbar buttons:

• Attribute: to show/hide attribute values

• Element: to show/hide element values

• Expand/Collapse All: select/deselect to display/not display all elements in the document

• Link with Editor:select/deselect to link/unlink the Outline view with the document.

Related tasks

"Navigating in the Outline view " on page 51

"Filtering content in the Outline view " on page 52

" Synchronizing the Outline view with the editor " on page 53


Chapter 1. Concepts

Chapter 2. TasksWorking with the Source page ............................................................................................................................. 18

Navigating in the Source page of the XML editor .............................................................................................. 19Editing XML in the Source page .................................................................................................................... 20Indenting XML in the Source page ................................................................................................................ 21Commenting XML in the Source page of the XML editor ..................................................................................... 22Cutting, copying, and pasting XML in the Source page of the XML editor ................................................................ 23Highlighting XML in the Source page of the XML editor ...................................................................................... 24

Working with the Tree page ................................................................................................................................ 25Navigating in the Tree page of the XML editor .................................................................................................. 26Viewing an XML document in the Tree page .................................................................................................... 27Editing XML in the Tree page ....................................................................................................................... 29Adding nodes in the Tree page of the XML editor .............................................................................................. 30Cutting, copying, and pasting nodes in the Tree page of the XML editor .................................................................. 31Deleting nodes from the Tree page of the XML editor ......................................................................................... 32Reordering nodes in the Tree page of the XML editor ......................................................................................... 33

Using XML code completion ................................................................................................................................ 34Using Undo and Redo in the XML editor ................................................................................................................ 37Saving an XML document ................................................................................................................................... 38Searching in an XML document ........................................................................................................................... 39Finding all occurrences of an XML element in a file ................................................................................................... 40Browsing XML source code ................................................................................................................................. 41Using code folding in the XML editor ..................................................................................................................... 42Creating a new XML file ..................................................................................................................................... 43

Creating an XML document from an XML schema, WSDL, or another XML file ......................................................... 44Customizing the generation of XML ............................................................................................................... 45

Creating an XML schema from an XML instance ....................................................................................................... 46Associating an XML schema with an XML document .................................................................................................. 47Validating XML ................................................................................................................................................ 48Running XPath expressions .................................................................................................................................. 49Working with the Outline page ............................................................................................................................. 50

Navigating in the Outline view ..................................................................................................................... 51Filtering content in the Outline view .............................................................................................................. 52Synchronizing the Outline view with the editor ................................................................................................. 53

Specifying preferences for the XML editor ............................................................................................................... 54Specifying Colors for the XML editor .............................................................................................................. 55Specifying formatting preferences ................................................................................................................. 56


Working with the Source page"Navigating in the Source page of the XML editor " on page 19


"Indenting XML in the Source page " on page 21

" Commenting XML in the Source page of the XML editor " on page 22

"Cutting, copying, and pasting XML in the Source page of the XML editor " on page 23

"Highlighting XML in the Source page of the XML editor " on page 24


Chapter 2. Tasks

Navigating in the Source page of the XML editorTo shift the cursor, use:

• CTRL+E to go to the end

• CTRL+shift+S to go to the start

• CTRL+, to go to the previous element

• CTRL+. to go to the next element

To shift the cursor to the matching bracket, when the cursor is on one bracket:

• Ctrl+Shift+> to go to the end tag

• Ctrl+Shift+<to go to the start tag

To go to a specific line number, select CTRL+L and enter the line number in the Go To Line dialog box.

Related concepts

"XML editor: Source page " on page 14


Navigating in the Source page of the XML editor

Editing XML in the Source pageThe source page displays an XML document in a text area. To edit the XML document, see the following:

• "Indenting XML in the Source page " on page 21

• " Commenting XML in the Source page of the XML editor " on page 22

• "Cutting, copying, and pasting XML in the Source page of the XML editor " on page 23

• "Highlighting XML in the Source page of the XML editor " on page 24

• "Using XML code completion " on page 34

• "Using Undo and Redo in the XML editor " on page 37

• "Saving an XML document " on page 38

Related concepts


Related tasks

" Specifying Colors for the XML editor " on page 55"Using code folding in the XML editor " on page 42


Chapter 2. Tasks

Indenting XML in the Source pageYou can automatically indent using the Enter key. The text is indented on the new line where the current cursor is.

Smart indentation provides intelligent generation of closing tags at appropriate positions while editing an XML document.

For example:

• When you type the opening tag, the closing tag is generated immediately following.

• For comments, when you type the commenting opening tag, the corresponding closing tag is inserted at the appropriateposition.

• For single and double quotes, when you type ' or ", the corresponding ' or " is inserted at the appropriate position.

Related tasks



Indenting XML in the Source page

Commenting XML in the Source page of the XML editorYou can insert and remove the XML comment tags by using Ctrl+ Shift + / or the XML menu option Add Comment tocomment and uncomment. You can comment and uncomment by block selection and caret position (if not selected).

To comment or uncomment, click Ctrl+Shift+/.

To comment/uncomment on block selection:

• If the block selection contains a complete element, the whole element is commented/uncommented

• If the block selection contains part of element, the whole element is commented/uncommented

• If the block selection contains more than one element (can be partly selected), all the partly selected elements arecommented/uncommented.

• If the block is already commented, it is uncommented. If the block is not already commented, it is commented.

To comment/uncomment based on cursor position:

• If the cursor position is on an element, the whole element is selected.

• If the cursor position is on empty space (the carat is between two elements), no commenting/uncommenting occurs.

Related tasks



Chapter 2. Tasks

Cutting, copying, and pasting XML in the Source page of the XML editorTo cut, copy, and/or paste, select the text and:

• Right-click and select Cut, Copy, or Paste

• Select Edit > Cut, Edit > Copy, or Edit > Paste

• Click Ctrl+X, Ctrl+C, or Ctrl+V

Related tasks



Cutting, copying, and pasting XML in the Source page of the XMLeditor

Highlighting XML in the Source page of the XML editorYou can highlight all occurrences in a document of:

• Element

• Attribute

• Namespace prefix based on its currently assigned URI (when the prefix is overridden with another URI or set to emptyURI (null))

• Namespace URI, to highlight all occurrences of the namespace prefixes which point to this URI

To highlight, place the cursor on the element, attribute, or namespace prefix, and click Ctrl+Shift+U. The occurrences arehighlighted with the default background color.

Related tasks



Chapter 2. Tasks

Working with the Tree page"Navigating in the Tree page of the XML editor " on page 26

"Viewing an XML document in the Tree page " on page 27


"Adding nodes in the Tree page of the XML editor " on page 30

"Cutting, copying, and pasting nodes in the Tree page of the XML editor" on page 31

"Deleting nodes from the Tree page of the XML editor " on page 32

"Reordering nodes in the Tree page of the XML editor " on page 33


Working with the Tree page

Navigating in the Tree page of the XML editorTo navigate in the XML editor's Tree page, you can:

• Expand and collapse the document's tree structure.

• Expand or collapse to view or hide all the inner elements and attributes under element nodes.

• Expand and collapse using the left and right arrow keys

Related concepts

"XML editor: Tree page " on page 15


Chapter 2. Tasks

Viewing an XML document in the Tree pageAll the XML components are shown in the tree as tree nodes except attributes and text.

The attribute name is shown as a child node and the attribute value corresponding to it is shown in the second column ofthe row.

If a node has children, a button is on the left side of the node. (Attributes are also considered child nodes.) Click the buttonto expand or collapse the node showing or hiding its child nodes:

• A + is shown on the button if it is in the collapsed state

• A - is shown if it is in the expanded state.

If the content in the second column is greater than the available space, ... signifies that there is more content that you canview in a fly-over tooltip.

If you double-click on a node, an editable combo box with code completion suggestions opens.

The following XML components are displayed in the tree:

• Elements

• Attribute names

• Attribute values

• Text

• CDATA

• Comment

• Character reference

• Entity reference

Click on a node to select that node. This highlights the currently selected element:

• The highlight changes when the current selection changes.

• The selection changes as you navigate the nodes of the tree.

• Only one node can be selected at a time.

To show or hide the whitespace between different nodes, click the Show/Hide Whitespace node toolbar button to show thewhitespace as a child node under the containing element (or hide it).

You can specify filters on nodes by clicking the Hide> toolbar button and selecting:

• Attributes

• Comments

• CData Sections

• Namespace Prefixes for the XML elements and attributes

You can optionally hide all the text nodes except those corresponding to attribute nodes.

For nodes that have only text inside them, the text is displayed in the second column for that row:


Viewing an XML document in the Tree page

• If an element has child elements and text, the text is shown as a child node. The first column of such a node is denotedby #text and the actual text is displayed in the second column.

• When in Hide text nodes mode, all text nodes (other than those corresponding to attribute values) are hidden.

Related concepts



Chapter 2. Tasks

Editing XML in the Tree pageThe tree page displays any XML document (conforming to the XML 1.1 specification) in the form of a (left aligned) treestarting from the document root.

To edit the XML, see the following:

• "Adding nodes in the Tree page of the XML editor " on page 30

• "Cutting, copying, and pasting nodes in the Tree page of the XML editor" on page 31

• "Reordering nodes in the Tree page of the XML editor " on page 33

• "Deleting nodes from the Tree page of the XML editor " on page 32

• "Using XML code completion " on page 34

• "Using Undo and Redo in the XML editor " on page 37

• "Saving an XML document " on page 38

Related concepts


Related tasks

"Running XPath expressions" on page 49


Editing XML in the Tree page

Adding nodes in the Tree page of the XML editorWhen you add new nodes to the Tree page, the XML document in the Source page changes at the same time.

To add a node, move the cursor to the position in the tree where you want to add the node. Right-click, select an XMLcomponent and the position of the component relative to the current node:

If you select Text, the Edit Text dialog box opens where you can type the text. It also automatically encodes special characters,such as &, <, and >.

Related tasks



Chapter 2. Tasks

Cutting, copying, and pasting nodes in the Tree page of the XML editorYou can cut or copy a complete node in the tree and paste it anywhere in the document. Validation is performed after theoperation.

To cut, copy, and/or paste nodes:

• Right-click and select Cut, Copy, or Paste.

• Click the Cut, Copy, or Paste toolbar button.

• Use Ctrl+X, Ctrl+C, or Ctrl+V.

Related tasks



Cutting, copying, and pasting nodes in the Tree page of the XMLeditor

Deleting nodes from the Tree page of the XML editorYou can delete any of the nodes from the tree. The selected node is deleted from the tree and also the corresponding datais removed from the underlying XML document..

To delete an node:

• Right-click and select Delete

• Click the Delete toolbar button

• Use the Del key

Related tasks



Chapter 2. Tasks

Reordering nodes in the Tree page of the XML editorYou can change the ordering of the child nodes within a parent:

• Move the selected node before the sibling preceding it.

• Move the selected node after the sibling succeeding it.

To move a node up:

• Select the node, right-click, and select Move Up

• Click the Move Up button in the Toolbar

• Use Ctrl + Up Arrow key

To move a node down:

• Select the node, right-click, and select Move Down

• Click the Move Down button in the toolbar

• Use Ctrl+Down Arrow key

Note• You cannot move a node up or down if it is the only child.

• You cannot move a node up if it is the first sibling.

• You cannot move a node down if it is the last sibling.

Related tasks



Reordering nodes in the Tree page of the XML editor

Using XML code completionUse XML code completion to add new nodes to an XML document in the Source page and Tree page. The XML editor listsall the possible elements or attributes based on the associated schema or structured XML (when no schema is associatedor the schema cannot be located or loaded).

Code completion rules are the same for the Source and Tree pages, except for start and end tag completion.

Code completion is provided in the following ways:

• When a schema association exists, the elements and attributes are listed from the schema.

• When no schema association exists, the elements and attributes listed are based on the previous element structure inthe document.

Code completion is provided for adding the following nodes:

• Elements

• Attributes

• Lists the namespace prefix based on entries from the Namespace preference page.

• Lists the namespace URI based on entries from the Namespace preference page.

• Lists the possible schema locations from the Namespace preference page.

You can trigger code completion explicitly or automatically. The same set of completion rules apply in both cases:

• Trigger code completion explicitly by selecting Ctrl+Space.

Code completion occurs as follows:

1. When you type '<', the editor lists valid a combination of: 'namespace_prefix:element' list when the schema defines the'namespace_prefix:element' list.

2. When you type '<namespace_prefix:', the editor lists all valid elements.

3. When you type '<namespace_prefix:element space' (space means the keyboard space key), the editor lists the possibleattributes.

4. When you type '<namespace_prefix:element attributename="value" space' (space means the keyboard space key), theeditor lists the possible attributes, filtering out the already added attributes.

5. When the cursor comes between the double codes of attribute value '<namespace_prefix:element attributename="", theeditor lists the possible attribute values when the value is the Boolean or enumeration type.

6. The editor's attribute popup lists 'xmlns' in all cases

7. When you type '<namespace_prefix:element xmlns:', the editor lists all the namespaces known to the editor as definedin the Namespace preference page. The list is shown in the dropdown as a set of 'namespace_prefix=URI'. Once any ofthese are chosen, the code generated is:

<namespace_prefix:element xmlns:prefix="URI"

8. When you type '<namespace_prefix:element xmlns: namespace_prefix=', the editor lists all the namespaces URIs. Asan example of a special case:


Chapter 2. Tasks

1. <ns:parent>2. <ns:child1> <ns:child1>3. <invalidchild></invalidchild>4. <5. </ns:parent>

In the example, there is an invalid child in line 3. When typing '<' in the next line, the editor lists all the possible elementsfrom the defined namespaces.

9. When no schema is associated, the behavior is as in the following example:

1. <customers>2. <customer>3. <name></name>4. <id></id>5. </customer>6. <7. </customers>

When the XML is not associated with a schema, it should list all the possible elements based on the previous content inthe document. In this example, when you type '<' in line 6, it lists 'customer' as a possible element.

You can use the insert or overwrite completion mode:

• To insert a node form the popup, select the option and press Enter. The editor inserts the element in the page.

• To replace existing text with the selected option, select the option and press Tab. If no prior text exists in the page, theeditor inserts the selected option.

Code completion filters include:

• Element list, for example:

1. <customers2. <customer>3. <id>1</id>4. <5. </customer>6. </customers>

In this example, element '<id>' can occur once. In line 4, when you try to add an element using code completion, thepopup lists all the remaining valid elements by filtering the '<id>' element from the list.

• Attribute list, for example:

1. <customers2. <customer id='1'

In this example, the attribute "id" was already added to the page. If you press Space after the first attribute, the popuplists the remaining valid attributes by filtering "id" from the list.

• Filtering as you type. The popup lists the 'namespace_prefix:elements that start with the typed characters:

• For example, when '<x' is typed, the popup lists the 'namespace_prefix:elements that start with x.

• For example, when '<namespace_prefix:element xmlns: x' is typed, the popup lists all the namespaces with'namespace_prefix=URI' that start with x.


Using XML code completion

Related concepts

"XML editor: Source page " on page 14"XML editor: Tree page " on page 15


Chapter 2. Tasks

Using Undo and Redo in the XML editorAfter editing, you can go back to the previous state of the document by undoing the last change. You can use Undo/Redoto back as far as the last time the document was saved:

• Right-click and select Undo or Redo

• Select Edit > Undo or Edit > Redo.

• Use Ctrl+Z for undo or Ctrl+Y for redo

Related concepts

"Editing XML in the Source page" on page 20"Editing XML in the Tree page" on page 29


Using Undo and Redo in the XML editor

Saving an XML documentAn asterisk next to the file name on the tab indicates that the file has unsaved changes.

To save an XML file, either:

• Select File > Save.

• Use Ctrl+S.

To perform Save As on an XML file:

1. Select File > Save As. The SaveAs dialog box opens.

2. Enter the location and file name.

Related tasks




Chapter 2. Tasks

Searching in an XML documentTo search in an XML document, either:

• Click Ctrl+F for find, Ctrl+Up for find next, Ctrl+Down for find previous, or Ctrl+R for replace.

• Select Edit > Find/Replace. The Find/Replace dialog box opens:

• Enter the appropriate search information for Direction, Scope, and Options.1.

2. Select Find, Replace/Find, Replace, or Replace All and click Close.

You can click Advanced in the Find/Replace dialog box to open the Advanced Options dialog box and specify:

• XML element and attribute names

• XML element and attribute values

After running a search:

• To find next, click Ctrl+Up

• To find previous, click Ctrl+Down

Related tasks

" Finding all occurrences of an XML element in a file " on page 40


Searching in an XML document

Finding all occurrences of an XML element in a fileTo find all occurrences of an XML element in a file:

1. Open the file in the XML editor on page 11.

2. Select the element in the Source page on page 14.

3. Select XML > Find Occurrences in File. The Search view shows the occurrences.

The Search view is a standard Eclipse view. For more information, see the help for the Eclipse Search view.


Chapter 2. Tasks

Browsing XML source codeUse F3 or Ctrl + Left mouse click in the Source page to browse to:

• Schema element's declaration from an element in the XML document. The associated schema file is opened in the Schemaeditor and scrolled to make the schema element declaration visible. The cursor is also set to this location.

• Schema location when the cursor is over a schema location or the namespace URI.

• Corresponding schema file is opened when invoked on a namespace URI.

• Declaration of the namespace prefix when invoked on a namespace prefix and the cursor goes to the namespace URI.

Related concepts



Browsing XML source code

Using code folding in the XML editorUse code folding to reduce the amount of text visible in the Source page. Sections of the document that are not currentlythe focus of editing can be hidden (collapsed or folded). Since XML documents are tree structured, the simplest way to usecode folding is to do it for every element.

The following parts of XML documents can be folded:

• Elements

• Comments

• XML Declaration and processing instructions

• Internal DTDs

• CDATA sections

• Search criteria-based:

• XPath based

• Canned

• Regular expression-based

You can use hot keys to bring deep nodes to the top levels of the document (in the view):

• To expand, use Ctrl + Numpad Add

• To collapse, use Ctrl + Numpad Subtract

• To expand all, use Ctrl + Numpad Divide

• To collapse all, use Ctrl +Numpad Multiply

When the document is folded, you can hover your mouse over it, and see a projection of the master document.

Related concepts



Chapter 2. Tasks

Creating a new XML fileTo create a new XML file:

1. Select File > New > XML. The New XML File wizard opens.

2. Enter or select the parent folder.

3. Enter the File name.

4. You can click Advanced to link to the file system.

5. Click:

• Finish to generate the new XML file. The file opens in the XML editor on page 11.

• Next to create the XML document from an XML schema on page 44


Creating a new XML file

Creating an XML document from an XML schema, WSDL, or another XML fileTo create an XML document from an XML schema, WSDL, or another XML file:

1. Follow the steps in Creating a new XML file on page 43 and click Next. The Create XML from XML schema, WSDL andXML file wizard page opens.

2. Select the XML schema, WSDL, or XML file.

3. Select the Types and/or Elements.

4. Specify the Root element name.

5. Click:

• Finish to generate the new XML file. The file opens in the XML editor on page 11.

• Next to customize the generation of XML on page 45.

Related tasks

"Creating an XML schema from an XML instance " on page 46


Chapter 2. Tasks

Customizing the generation of XMLTo customize the generation of XML:

1. Follow the steps in Creating an XML document from an XML schema, WSDL, or another XML file on page 44 and clickNext. The Customize the generation of XML wizard page opens.

2. Specify whether to generate optional elements and/or attributes.

3. Specify repeat counts for repeating elements.

4. Click Finish to generate the new XML file. The file opens in the XML editor on page 11.


Customizing the generation of XML

Creating an XML schema from an XML instanceTo create an XML schema from an XML instance:

1. Open an XML instance in the XML Source Page.

2. Click the Generate Schema button (or right-click and select Create Schema). The Generate Schema from XML dialogbox opens.

3. Modify or confirm the Input XML and Output XSD file names and paths.

Related tasks

"Creating an XML document from an XML schema, WSDL, or another XML file " on page 44


Chapter 2. Tasks

Associating an XML schema with an XML documentYou can associate a schema with the currently open XML document. Once the location of the XML schema is specified, theXML document refers to that schema.

To associate an XML schema with the currently opened XML document:

1. In the Source or Tree page of an XML document, select XML > Associate Schema to XML.

2. Specify the location of the schema file in the Open dialog box.

Related concepts

"XML editor: Source page " on page 14"XML editor: Tree page " on page 15

Related tasks

"Creating an XML schema from an XML instance " on page 46


Associating an XML schema with an XML document

Validating XMLThe XML Editor provides validation (based on Xerces) on the open document:

• Well formedness

• Schema-based

The XML Editor automatically marks invalid xml with red in the top right corner. Validation errors are highlighted on theoverview ruler, vertical ruler and in the Problems view.

Use Ctrl+Shift+V or the toolbar menu to explicitly trigger validation of the document.


Chapter 2. Tasks

Running XPath expressionsYou can enter the XPath expression and press the Run button to execute the expression and select the node in the treewhich matches the expression. If there is more than one match, the editor repeatedly iterates through the result set.

Related concepts

"XPath Helper" on page 111


Running XPath expressions

Working with the Outline page"Navigating in the Outline view " on page 51

"Filtering content in the Outline view " on page 52

" Synchronizing the Outline view with the editor " on page 53


Chapter 2. Tasks

Navigating in the Outline viewUse the toolbar button in the Outline view to collapse all or expand all the elements.

You can only select a single element. Use the arrow keys to change the selection and navigate between element or attributesiblings and children:

To navigate between parent and child, left mouse click or use the arrow keys:

• Left arrow: If the element is a leaf, the selection moves to its parent. If the element has children, the element is collapsed.If the element is already collapsed, go to the element's parent, if a parent exists.

• Right arrow: If the element is in a collapsed state, it expands to show its children. If the element is already expanded,the selection moves to the element's first child. If the element is a leaf, there is no change in the selection.

• Up arrow: If the element is the first child, the selection moves to its parent, if a parent exists.

• Down arrow: If the element is the last child, the selection moves to the element's parent's next sibling.

To navigate between siblings, left mouse click or use the arrow keys:

• Up arrow: If the element has a previous sibling and is a leaf or a collapsed element, the selection moves to the previoussibling. If the element has a previous sibling and is not a leaf or an expanded element, the selection moves to the lastexpanded element of the previous sibling.

• Down arrow: If the current element is the last expanded element of its parent, the selection moves to the parent's nextsibling. If the there is no next sibling to its parent, it searches for the parent's parent's next sibling recursively. If theelement has a next sibling and the current element is a collapsed element or a leaf, the selection moves to the next sibling.

Related concepts

"XML editor: Outline view " on page 16


Navigating in the Outline view

Filtering content in the Outline viewYou can filter the content in the Outline view.

To filter attributes:

• Select Show Attribute Value to display attribute content beside the attribute name

• Select Hide Attribute Value to display only the attribute name

To filter elements:

• Select Show Element Value to display the element name and its content

• Select Hide Element Value to display only the element name

Related concepts



Chapter 2. Tasks

Synchronizing the Outline view with the editorWhen you select an element in the Outline view, the selection moves to the corresponding element in the editor page.

Similarly, as you move through a document in the editor page, the selection moves to the corresponding element in theOutline view except when the Outline View is not synchronized for editor selection changes.

Use the Link with Editor toolbar button to synchronize scrolling.

Related concepts



Synchronizing the Outline view with the editor

Specifying preferences for the XML editor" Specifying Colors for the XML editor " on page 55

" Specifying formatting preferences " on page 56


Chapter 2. Tasks

Specifying Colors for the XML editorTo specify colors in the XML editor, select Window > Preferences > Progress > Sonic > XML Editors > XML > ColorSettings, then select the element and Bold, Italic, and Color.

You can specify the color and format for the following XML elements:

• Attribute name

• Attribute value

• Comment

• Tag name

• Tag value

• Opening tag

• Processing instruction

• Others


Specifying Colors for the XML editor

Specifying formatting preferencesTo specify formatting preferences, selectWindow > Preferences > Progress > Sonic > XML Editors > XML > Formatterto open the Formatter preferences page.

Formatting preferences include:

• Format and indent on document open

• Use single quote for attributes

• Space around attribute "="

• Namespace attributes on new line (default)

• Attributes on new line

• Attribute indent width

• Element child indent width


Chapter 2. Tasks

Part II. XML Schema Editor3. Concepts ..................................................................................................................................................... 59

XML Schema editor: Source page ................................................................................................................. 60XML Schema editor: Tree page .................................................................................................................... 61XML Schema editor: Diagram page ................................................................................................................ 62XML Schema editor: Outline view ................................................................................................................. 63XML Schema editor: Palette ........................................................................................................................ 64

4. Tasks ......................................................................................................................................................... 65Working with XML schemas in the Tree page ................................................................................................... 66

Navigating in the Tree page of the XML Schema editor ............................................................................... 67Adding XML schema components in the Tree page .................................................................................... 68Dragging nodes from the Tree page to another editor ................................................................................. 69Using Undo and Redo ....................................................................................................................... 70Reordering nodes in the Tree page ........................................................................................................ 71Cutting, copying, and pasting nodes in the Tree page ................................................................................ 72Editing nodes in the Tree page ............................................................................................................. 73Deleting nodes in the Tree page ........................................................................................................... 74

Working with XML schemas in the Diagram page ............................................................................................. 75Navigating in the Diagram page of the XML Schema editor ......................................................................... 76Adding and deleting XML schema components in the Diagram page .............................................................. 77Moving schema elements in the Diagram page of the XML Schema editor ...................................................... 78

Defining an XML Schema ............................................................................................................................ 79Defining elements and element references in XML Schemas ........................................................................ 81Defining attributes and attribute references in XML schemas ....................................................................... 83Defining groups and group references in XML Schemas .............................................................................. 84Defining simple types in XML schemas .................................................................................................. 86Defining complex types in XML Schemas ............................................................................................... 87Defining restriction and extension type nodes in XML Schemas .................................................................... 88Defining content types in XML Schemas ................................................................................................. 89Defining aggregator types in XML Schemas ............................................................................................. 90Defining facet types in XML Schemas ..................................................................................................... 91Defining notations ............................................................................................................................ 93Defining Include, Import, and Redefine nodes ......................................................................................... 94Including and importing external XML schemas ....................................................................................... 95

Adding an Identity Constraint to an Element .................................................................................... 96Adding annotation, documentation, text, and comments to XML Schemas ............................................... 98

Editing XML schemas ...................................................................................................................... 100Saving an XML schema ..................................................................................................................... 101Specifying colors for the XML Schema editor .......................................................................................... 102

5. Reference .................................................................................................................................................. 103What Is an XML Schema? ........................................................................................................................ 104xsd:schema properties ............................................................................................................................. 106Simple types in XML Schemas .................................................................................................................... 107Complex types in XML Schemas ................................................................................................................. 109

Use the XML Schema editor to generate an XML schema from an XML document. You can rapidly generate XML schemas when sampleXML documents are available.

You can use the XML Schema editor to analyze your XML schema document (.xsd) to determine if it is valid. Sonic Workbench canassociate an XML schema with an XML document, and it can validate an XML document against its associated schema.

If you update a schema in Sonic Workbench and that schema is associated with an XML document that is open in Sonic Workbench,Sonic Workbench refreshes the XML schema information for the XML document.

Use the XML Schema editor to define or update an XML schema. You can edit either the text of an XML schema or a DOM tree thatrepresents the XML schema. Use the Tree page to view a DOM tree representation of your schema. In the Tree page, Sonic Workbenchallows you to add particular nodes to the schema with the click of a button. Any changes you make in one view are automatically reflectedin the other view.

The Source page displays the XML markup that defines the XML schema. You can edit this document as you would any other XMLdocument. As soon as you type a left angle bracket, Sonic Workbench prompts you with a list of the possible tag names. As you continueto type, Sonic Workbench highlights the first selection that matches what you enter. Double-click a selection in the shortcut menu toinsert it in your schema.

After you enter the tag name and insert a space, Sonic Workbench prompts you with the attributes that can appear at that point.Double-click an attribute to insert it automatically. At any time, select XML > Schema Validation in the tool bar to confirm that yourschema is valid.

The XML Schema editor provides three ways to view an XML schema document:

• The Source page on page 60 displays the raw XML text.

• The Tree page on page 61 displays a DOM tree representation of the schema.

• The Diagram page on page 62 (available only when Progress Sonic Workbench is installed) displays the document in a graphicalmanner in the upper pane. The lower pane displays the element or type selected in the top pane schema as text.

You can make changes in one page, and they are immediately reflected in the other pages.

The XML Schema editor supports semantic navigation using F3 and Ctrl+Click for various items such as refs, binding, port Types, etc.that go across files and follow the right namespace, imports, and visibility rules.

Chapter 3. ConceptsXML Schema editor: Source page ......................................................................................................................... 60XML Schema editor: Tree page ............................................................................................................................ 61XML Schema editor: Diagram page ........................................................................................................................ 62XML Schema editor: Outline view ......................................................................................................................... 63XML Schema editor: Palette ................................................................................................................................ 64


XML Schema editor: Source pageAn XML schema file is composed of XSD text and XML text. Use the XML schema Source page to create, edit and save XMLschema documents.

The Source page includes the following text formatting features:

• Code folding

• Code completion

• Code color specification

The XML elements are color-coded as in the XML editor. Preferences for color-coding XML also apply to XML fragments inan XSD document.

The Source page provides XML validation. When the document is not well-formed, errors are flagged in red on the rightscrollbar and in the left margin. Explanations of errors appear in the Problems view and in Tool Tips.

Related concepts

"XML Schema Editor" on page 57

Related tasks

"Specifying colors for the XML Schema editor" on page 102


Chapter 3. Concepts

XML Schema editor: Tree pageThe Tree page displays a Document Object Model (DOM) tree or hierarchical representation of the XML schema beingcreated or viewed.

You can add nodes, sub nodes and attributes and all the artifacts that make up a XML schema using the toolbar buttonsor menu items.

You can navigate the schema using the Move up and Move down buttons to traverse through the entire tree representationof the XML schema.

The Properties view shows the properties for the selected DOM tree node. Click a node in the DOM tree to view its properties.The properties that appear vary according to the type of node you select.

Related concepts


Related tasks

"Navigating in the Tree page of the XML Schema editor " on page 67"Adding XML schema components in the Tree page " on page 68


XML Schema editor: Tree page

XML Schema editor: Diagram pageNoteThis page is available only when Progress Sonic Workbench is installed.

The Diagram page provides a high-level representation of an XML schema in a graphical, hierarchical view in the upperpane. The lower pane shows the XML schema as text. Use the arrow keys to navigate in the Diagram page. Pan the diagramwith the Overview view in Progress Sonic 8.0 Progress Sonic ESB Developers' Tools.

You can define some, but not all, of a schema in the Diagram page. You can add nodes, sub nodes and attributes at anylevel of the document by right clicking on any node in the diagram page. At any time, you can use the Tree or Source pagesto add artifacts that you cannot add from the Diagram page. You can then go back to the Diagram page to see the result.

Use the Tree or Source page for the following operations that the Diagram page does not support:

• Adding an attribute group to a complex type

• Adding comments, annotations, and white space

• Defining an identity constraint

• Defining notations

• Including or importing an external XML Schema

Related concepts

"XML Schema Editor" on page 57"XML Schema editor: Source page " on page 60"XML Schema editor: Tree page " on page 61


Chapter 3. Concepts

http://documentation.progress.com/output/Sonic/8.0.0/Docs8.0/online_help/dev_tools.pdf#overview_view

XML Schema editor: Outline viewOpen the Outline view by selecting Window > Show View > Outline View.

The Outline view displays the elements of the document that is currently open in the editor area in the form of a hierarchicaltree.

When you click an element in the Outline view, the document in the editor scrolls to the corresponding element. Also,selecting an element in the document highlights the corresponding element in the Outline view.

The Outline View is dynamic in nature, immediately reflecting any edits to the document in the editor. The text that iscurrently being modified is highlighted in the middle of the Outline view.

The Outline view is a read-only view.

Use the toolbar buttons to display the following elements:

• Show Attribute Value or Hide Attribute Value

• Show Element Value or Hide Element Value

• Select or deselect Expand All

• Select or deselect Link with Editor

Related tasks

"Filtering content in the Outline view " on page 52"Navigating in the Outline view " on page 51" Synchronizing the Outline view with the editor " on page 53


XML Schema editor: Outline view

XML Schema editor: PaletteUse the options in the Palette in the Tree and Diagram pages of the XML Schema editor to define an XML Schema.

Related concepts

"XML Schema editor: Tree page " on page 61"XML Schema editor: Diagram page" on page 62

Related tasks

"Defining an XML Schema" on page 79

"Defining elements and element references in XML Schemas " on page 81

"Defining attributes and attribute references in XML schemas " on page 83

"Defining groups and group references in XML Schemas " on page 84

"Defining simple types in XML schemas " on page 86

"Defining complex types in XML Schemas " on page 87

"Defining restriction and extension type nodes in XML Schemas " on page 88

"Defining content types in XML Schemas " on page 89

"Defining aggregator types in XML Schemas " on page 90

"Defining facet types in XML Schemas" on page 91

"Defining notations " on page 93

"Defining Include, Import, and Redefine nodes " on page 94

"Adding an Identity Constraint to an Element " on page 96

"Adding annotation, documentation, text, and comments to XML Schemas" on page 98

"Editing XML schemas " on page 100

Related reference

"xsd:schema properties " on page 106


Chapter 3. Concepts

Chapter 4. TasksWorking with XML schemas in the Tree page ........................................................................................................... 66

Navigating in the Tree page of the XML Schema editor ....................................................................................... 67Adding XML schema components in the Tree page ............................................................................................ 68Dragging nodes from the Tree page to another editor ......................................................................................... 69Using Undo and Redo ............................................................................................................................... 70Reordering nodes in the Tree page ................................................................................................................ 71Cutting, copying, and pasting nodes in the Tree page ........................................................................................ 72Editing nodes in the Tree page ..................................................................................................................... 73Deleting nodes in the Tree page ................................................................................................................... 74

Working with XML schemas in the Diagram page ..................................................................................................... 75Navigating in the Diagram page of the XML Schema editor ................................................................................. 76Adding and deleting XML schema components in the Diagram page ...................................................................... 77Moving schema elements in the Diagram page of the XML Schema editor .............................................................. 78

Defining an XML Schema .................................................................................................................................... 79Defining elements and element references in XML Schemas ................................................................................ 81Defining attributes and attribute references in XML schemas ............................................................................... 83Defining groups and group references in XML Schemas ...................................................................................... 84Defining simple types in XML schemas .......................................................................................................... 86Defining complex types in XML Schemas ....................................................................................................... 87Defining restriction and extension type nodes in XML Schemas ............................................................................ 88Defining content types in XML Schemas ......................................................................................................... 89Defining aggregator types in XML Schemas ..................................................................................................... 90Defining facet types in XML Schemas ............................................................................................................. 91Defining notations .................................................................................................................................... 93Defining Include, Import, and Redefine nodes ................................................................................................. 94Including and importing external XML schemas ............................................................................................... 95

Adding an Identity Constraint to an Element ............................................................................................ 96Adding annotation, documentation, text, and comments to XML Schemas ....................................................... 98

Editing XML schemas .............................................................................................................................. 100Saving an XML schema ............................................................................................................................. 101Specifying colors for the XML Schema editor .................................................................................................. 102


Working with XML schemas in the Tree page"Navigating in the Tree page of the XML Schema editor " on page 67

"Adding XML schema components in the Tree page " on page 68

"Dragging nodes from the Tree page to another editor " on page 69

"Using Undo and Redo " on page 70

"Reordering nodes in the Tree page " on page 71

"Cutting, copying, and pasting nodes in the Tree page " on page 72

"Editing nodes in the Tree page " on page 73

"Deleting nodes in the Tree page " on page 74


Chapter 4. Tasks

Navigating in the Tree page of the XML Schema editorTo navigate in the XML Schema editor's Tree page, you can:

• Expand and collapse the document's tree structure.

• Expand or collapse to view or hide all the inner elements and attributes under element nodes.

• Expand and collapse using the left and right arrow keys

Related concepts

"XML Schema editor: Tree page " on page 61


Navigating in the Tree page of the XML Schema editor

Adding XML schema components in the Tree pageYou can select from a comprehensive list of schema components in the Palette.

To add a component, select the node where you want to define a new element as a child of the selected node. Then, either:

• Click Add and select the component from the list.

• Right-click, select Add, and select the component from the list.

• Drag and drop the component from the Palette.

The insertion point can be at the top of the list of children, at the bottom, or between two children. When you drop on theparent, the insertion point is the bottom of the children’s list.

You are prompted for the name (where required) and a drop-down list shows the available options.

Once inserted, auto-validation is triggered to detect any errors.

NoteFor all components created from Palette, you are prompted to rename the created node, except for anonymoustypes, and the Include, Import, Redefine, and Content nodes.

Related concepts

"XML Schema editor: Palette " on page 64

Related tasks



Chapter 4. Tasks

Dragging nodes from the Tree page to another editorYou can select a node in the Tree page and drag it onto another editor. This pastes the text content corresponding to thatnode into the editor.

Related concepts



Dragging nodes from the Tree page to another editor

Using Undo and RedoAfter editing, you can go back to the previous state of the XML schema document by undoing/redoing the last edit action.You can use Undo and Redo to go back as far as the last time the document was saved:

• Click the toolbar button for Undo or Redo.

• Select Edit > Undo or Edit > Redo.

• Use Ctrl+Z for Undo or Ctrl+Y for Redo.

Related tasks



Chapter 4. Tasks

Reordering nodes in the Tree pageYou can change the order of the child nodes within a parent:

• Move the selected node before its sibling

• Move the selected node after its sibling

To move a node up:

• Select the node, right-click, and select Move Up.

• Select the node and select the Move Up toolbar button.

• Select the node and click Alt+Shift+Up Arrow.

To move a node down:

• Select the node, right-click, and select Move Down.

• Select the node and select the Move Down toolbar button.

• Select the node and click Alt+Shift+Down Arrow.

Note• You cannot move a node up or down if it is the only child.

• You cannot move a node that is the first sibling.

• You cannot move a node that is the last sibling.

Related concepts



Reordering nodes in the Tree page

Cutting, copying, and pasting nodes in the Tree pageTo cut or copy a complete node in the tree and paste it anywhere in the document, select the node and:

• Select Edit > Cut, Edit > Copy, or Edit > Paste.

• Select the Cut, Copy, or Paste toolbar button.

• Click Ctrl+X, Ctrl+C, or Ctrl+V.

Validation is performed after the operation.

Related concepts



Chapter 4. Tasks

Editing nodes in the Tree pageYou can edit the names of components (element names, attribute names, attribute content, CDATA, and Text) that havecorresponding nodes in the tree:

• Double-click on the relevant node to enter edit mode.

• Select the node, right-click, and select Rename.

• Select the node and click F2.

You can edit the values displayed in the Content column (for example, attributes values).

To edit the values of attributes and text of a component that has a corresponding node in the tree:

• Select the component, right-click, and select Change Value.

• Select the node and click Shift+F2.

Related concepts



Editing nodes in the Tree page

Deleting nodes in the Tree pageYou can delete any of the nodes in the Tree page of the XML Schema editor. Deleting nodes from the tree removes thecorresponding text from the underlying XML schema document.

To delete a node, select the node, and click the Delete toolbar button, click the Del key, or right-click and select Delete.

Related concepts



Chapter 4. Tasks

Working with XML schemas in the Diagram page"Navigating in the Diagram page of the XML Schema editor " on page 76

"Adding and deleting XML schema components in the Diagram page " on page 77

"Moving schema elements in the Diagram page of the XML Schema editor " on page 78


Working with XML schemas in the Diagram page

Navigating in the Diagram page of the XML Schema editor

NoteThis functionality is available only when Progress Sonic Workbench is installed.

The tree in the Diagram page is initially expanded to three levels.

To navigate to:

• The parent node from a child node, use the Up arrow key.

• The next sibling, use the Right arrow key.

• The previous sibling, use the Left arrow key.

• The next visible node vertically below the current node (child, sibling or other node), use the Down arrow key.

• The next visible node vertically above the current node (child, sibling or other node), use the Up arrow key.

Related concepts

"XML Schema editor: Diagram page" on page 62


Chapter 4. Tasks

Adding and deleting XML schema components in the Diagram page


You can select from a comprehensive list of schema components in the Palette.

To add a component, select the node and either:

• Click Add and select the component from the list.

• Right-click, select Add, and select the component from the list.

• Drag and drop the component from the Palette.

You can choose from:

• Annotation

• key

• keyRef

• Unique

You can select Insert Before:

• Attribute

• Attribute Group

• Complex Type

• Element

• Group

• Notation

• Simple Type

You can delete a particular attribute or an element from the selected element in an element group.

Related concepts


Related tasks




Adding and deleting XML schema components in the Diagrampage

Moving schema elements in the Diagram page of the XML Schema editor


You can move schema elements to a new position in the Diagram page:

• Use Move Up and Move down to move in a vertical direction

• Right click, select zoom, and select a magnifcation amount.

• Use the Change Alignment button.

Related concepts

"XML Schema editor: Diagram page" on page 62


Chapter 4. Tasks

Defining an XML SchemaThe recommended way to use the XML Schema editor is to start with the Diagram page. When you use the Diagram page,Sonic Workbench assists with XML schema syntax. For example, regardless of the order in which you define nodes, SonicWorkbench ensures that the nodes you define are in the required order in the XML document that contains the XML schemadefinition.

However, you cannot use the Diagram page to define some advanced structures. You must switch to the Tree or Sourcepage to define these structures. You can then switch back to the Diagram page to see the new structure.

Although some information about XML schema tags is provided, familiarity with the W3C XML Schema Recommendationis assumed.

To create a new XML schema:

1. Select File > New > XSD. The Create New XSD File wizard opens.

2. Enter the name and location for the new XML schema (using a .xsd extension). The XML Schema editor creates a

skeleton of an XML schema.

3. Use the Palette to add elements to the XML schema.

See the Related tasks links for more details.

Related concepts

"What Is an XML Schema? " on page 104


Related tasks
















Defining an XML Schema

Related reference



Chapter 4. Tasks

Defining elements and element references in XML SchemasYou can define an element as part of a complex type or as a top-level item. In the XML document that defines the XMLSchema, the element is a child of the xsd:schema element.

An element that is an immediate child of the xsd:schema element is a global element. A global element cannot:

• Contain a reference to another element

• Specify values for minOccurs, maxOccurs or use properties

An element that contains subelements is a complex type. You can define an element that contains subelements in either ofthe following ways:

• Define a top-level complex type. That is, it is a child of the xsd:schema node. In the complex type definition, define thesubelements. Elsewhere in the XML schema, define an element that uses the complex type you defined.

• Define an element that is a child of the xsd:schema node or a Model Group node. In the element definition, define acomplex type that contains your subelements.

Use the Tree page or the Source page to define an element that carries attributes and contains data, but does not containsubelements.

To define:

• An element, click the schema node or a model group node (all, any, choice, or sequence) and then select an element todefine a new element as a child of the selected node.

• An Element Ref, select a model group node (all, any, choice or sequence) and select this component to specify an elementthat the parent element of the model group node can contain.

Both global and local elements have the following properties. References to elements have the same properties except wherenoted.

• Data Type is element for elements or Ref. to Element for references to elements.

• MaxOccurs specifies the maximum number of instances of this element that can be present. If there is no limit to thenumber of instances, specify unbounded. You cannot specify this property for a global element. If you do, Sonic Workbenchignores it.

• Name is the tag name you use in an instance document. Specify the name you want the element to have.

• MinOccurs specifies the minimum number of instances of this element that can be present. If an element is not requiredto be present, specify 0. You cannot specify this property for a global element. If you do, Sonic Workbench ignores it.

• Data Type is the type of the data that the element contains. Select from all simple types defined in an XML Schema, andall types (simple or complex) that you define in the same schema. Nodes that are references to elements do not have thisproperty.

• Default specifies the default value for this element. Specification of this property makes sense only for optional elements.If you specify 0 for the Min Occur. property, you can specify a default value. When this element is in an instance document,the element has whatever value you specify. If you do not specify this element, the schema processor behaves as thoughyou had specified it with the default value. When you specify a default value for an element, that element must be optionalin an instance document. An element can have a value for the Default property or a value for the Fixed Value property.The two properties are mutually exclusive.

• Fixed Value: when you specify a value for Fixed Value, it is optional for the element to appear in an instance document.However, if the element does appear, it must have the value specified by Fixed Value. Whether or not you specify thiselement in an instance document, the schema processor behaves as though you had specified this element with the fixed


Defining elements and element references in XML Schemas

value. An element can have a value for the Fixed Value property or a value for the Default property. The two propertiesare mutually exclusive.

• Abstract is a Boolean value that indicates whether substitution for this element is required. When Abstract is true, theelement cannot be used in an instance document. Instead, a member of the element's substitution group must appear inthe instance document.

• Nillable is a Boolean value that indicates whether the contents of the element can be set to nil. A value of true indicatesthat the element can be empty; that is, it is permissible for the element to not contain any subelements, attributes, ordata.

• Form: an element's form is either qualified or unqualified. A form of qualified means that each time the element isreferenced in the XML schema document, you must specify the prefix of its namespace. Every element has a form attribute.If it is not explicitly defined, the schema processor checks the default attribute form specified for the Schema node.

• Blocked Substitutions: defines that this element cannot be derived in some forms. That is, it specifies that one or moreextensions, restrictions or substitutions cannot be permitted. For example, an enumeration for all the states in the UnitedStates can block extensions and substitutions, thus allowing derived data types only so as to restrict the number of validstates.

• Final Substitutions: specifies that this element is not allowed to be substituted in a substitution group if these are extensionsor restrictions of the same base type. For example, suppose an Invoice contains a reference to a PO document. The POdocument is derived from AccountingDocument. If PO document has the final="extensions" attribute, and PartialPO isdefined as an extension from AccountingDocument, the Invoice cannot substitute PO with PartialPO.

• Substitution Groups: if an element defines an element name definition in a substitution group, it means that it can beused in all the places where there is a reference to that element. For example, suppose the PO document definitionindicates that it can refer to an RFQ element. You can specify that a foo element is in the substitution group for an RFQelement. If you do, a PO document is valid if it refers to a foo element.

Related concepts


Related tasks




Chapter 4. Tasks

Defining attributes and attribute references in XML schemasYou can define an attribute as part of a complex type. You can also define an attribute as a top-level item. In the XMLdocument that defines the XML Schema, the attribute is a child of the xsd:schema element.

An attribute that is an immediate child of the xsd:schema element is a global attribute. A global attribute cannot:

• Contain a reference to another attribute

• Specify values for minOccurs, maxOccurs or use properties

To define an attribute, select the schema node, a complex type node, or an attribute group node, and select an attribute todefine an attribute name. This attribute is associated with the node that was selected.

Both global and local attributes have the following properties. References to attributes have the same properties, exceptwhere noted.

• Type: For attributes, the type is always Attribute. For attribute references, the type is always Ref. to Attribute.

• Name: the attribute name you use in an instance document. Specify the name you want the attribute to have.

• Data Type: the type of the data that is the value of the attribute. Select from all simple types defined in an XML Schema,and all simple types that you already defined in the same schema. References to attributes do not have this property.

• Default: specifies the default value for this attribute. Specification of this property makes sense only for optional attributes.If you specified optional for the Restrictions property, you can specify a default value. If this attribute is in an instancedocument, the attribute has whatever value you specify. If you do not specify this attribute, the schema processor behavesas though you had specified it with the default value. When you specify a default value for an attribute, that attributemust be optional in an instance document. An attribute can have a value for the Default property or for the Fixed Valueproperty. The two properties are mutually exclusive.

• Fixed Value: when you specify a value for Fixed Value, it is optional for the attribute to appear in an instance document.However, if the attribute does appear, it must have the value specified by Fixed Value. Whether or not you specify thisattribute in an instance document, the schema processor behaves as though you had specified this attribute with thefixed value. An attribute can have a value for the Fixed Value property or for the Default property. The two properties aremutually exclusive.

• Restrictions: specify prohibited, optional, or required.

• Form: An attribute’s form is either qualified or unqualified. A form of qualified means that each time the attribute isreferenced in a XML schema document, you must specify the prefix of its namespace. Every attribute has a form attribute.If it is not explicitly defined, the schema processor checks the default attribute form specified for the Schema node.

Related concepts


Related tasks



Defining attributes and attribute references in XML schemas

Defining groups and group references in XML SchemasThe XML Schema Recommendation allows you to specify groups of elements and groups of attributes. When you specify agroup updating the XML schema becomes easier. You only need to update the group definition. There is no need to changethe references to the group.

The XML Schema Recommendation refers to a group of elements as a model group definition. A model group definition cancontain references to elements and definitions of nested model group definitions.

In the Diagram or Tree page, define a group of elements. In any location where you can add a model group, you can alsoadd a reference to a model group definition.

To define a group, select the schema node, a complex type node, or a model group node, and select the group componentto define a new group, which can contain:

• New definitions of elements

• References to previously-defined elements

• Nested definitions of groups of elements

• References to groups of elements.

After you create a group node or a complex type node, you can add a model group node as a child. A model group specifiesrules for the occurrence of elements. These are the elements that are the children of the group or complex type in an instancedocument. A model group references and defines elements.

To define:

• An attribute group, click the schema node or a complex type node, and then select the attribute group component todefine a new attribute group. The group can contain new definitions of attributes, references to previously defined attributes,definitions of new attribute groups, or references to attribute groups.

• A Model Group, select a complex type node or a group node, and select the Model Group component to specify a modelgroup.

• A Group Ref, select a complex type node or a model group node (all, any, choice, sequence), and select this componentto add a reference to a group.

• An AttGroup Ref, select a complex type node or an attribute group node and select this component to add a reference toan attribute group.

Group properties

Groups have the following properties:

• Type is always Group.

• Name is the name you specified for the group.

• Min Occur. specifies the minimum number of instances of this group that can appear in a complex type that referencesthis group. If a group is not required to be present, specify 0.

• Max Occur. specifies the maximum number of instances of this group that can appear in a complex type that referencesthis group. If there is no limit to the number of instances, specify unbounded.

Model Group properties

Model groups have the following properties:


Chapter 4. Tasks

• Type is always Model.

• Modifier specifies the occurrence rules for the elements that you add as children of the model group node. Specify oneof the following values:

• all specifies that each element must appear exactly zero or one time in any order. In an instance document, the childrenof the group or complex type can include zero or one instance of each element.

• choice specifies that exactly one element can be present, and there must be only one instance of that element. In aninstance document, exactly one element can be a child of the group or complex type.

• sequence specifies that the elements must appear in the order in which they are specified in the schema. For eachelement, you can specify whether it is optional and whether it can appear more than once. The default is that exactlyone must be present in an instance document. In an instance document, each element that appears must be in thesame order as in the XML schema.

• any specifies that an element can appear any number of times. When you specify any, you do not add any elementdefinitions or references to elements.

• Min Occur. specifies the minimum number of instances of this model group that can appear in this group or complextype. If a model group is not required to be present, specify 0.

• Max Occur. specifies the maximum number of instances of this model group that can appear in this group or complextype. If there is no limit to the number of instances, specify unbounded.

Related concepts


Related tasks



Defining groups and group references in XML Schemas

Defining simple types in XML schemasIn an XML schema, an element that contains only data is a simple type. (Attributes are always simple types.)

Many simple types, such as string and integer, are built in to an XML Schema. You can define your own simple type byrestricting the range of values provided by a built-in simple type. After you define one or more simple types, you can alsodefine simple types that are derived from the simple types you defined.

You can define an atomic simple type in the Diagram page and Tree page. To define list, union, and anonymous simpletypes, use the Tree page.

Use the Tree page to define a simple type for a sequence of atomic types. In a:

• list simple type, all instances in the sequence must be of the same type.

• union simple type, the instances in the sequence can be of different types.

To define a simple type, select the schema node, an element node, an attribute node, a list node, or a union node.

Simple types have the following properties:

• Data Type is always simpleType.

• name is the type name you use elsewhere in the XML schema. Specify the name you want the type to have.

Related concepts


Related tasks



Related reference

"Simple types in XML Schemas" on page 107


Chapter 4. Tasks

Defining complex types in XML SchemasTo define a complex type, select the schema node or an element node and select this component. Then specify the followingproperties:

• Type is always Complex Type or Simple Type.

• Name is the type name you use elsewhere in the XML Schema. Specify the name you want the type to have.

• Abstract is a Boolean value that indicates whether substitution for this complex type is required. When Abstract is true,the complex type cannot be used in an instance document. Instead, a member of the complex type’s substitution groupmust appear in the instance document.

• Mixed is a Boolean value that indicates whether or not this complex type can contain raw data as well as elements andattributes. A value of true indicates that it can contain raw data.

• Blocked Substitutions defines that this type cannot be derived in some forms. That is, it specifies that one or moreextensions, restrictions or substitutions cannot be permitted. For example, an enumeration for all the states in the UnitedStates can block extensions and substitutions, thus allowing derived data types only so as to restrict the number of validstates.

• Final Substitutions specifies that the type is not allowed to be substituted in a substitution group if these are extensionsor restrictions of the same base type. For example, an Invoice contains a reference to a PO document and the PO documentis derived from AccountingDocument. If the PO document has the final="extensions" attribute, and PartialPO is definedas an extension from AccountingDocument, the Invoice cannot substitute PO with PartialPO.

Related concepts


Related tasks


Related reference

"Complex types in XML Schemas " on page 109


Defining complex types in XML Schemas

Defining restriction and extension type nodes in XML SchemasWhen you define a simple type, you always derive it from a built-in XML schema simple type, or a simple type you previouslydefined. To specify the simple type that your simple type is based on, add a restriction node or an extension node to yoursimple type node:

• A restriction node specifies that your simple type is a subset of some other simple type.

• An extension node specifies that your simple type extends the range of values provided by an existing simple type.

To define a restriction, select a simple type node and specify the base type for the simple type. A list displays all the globaltypes.

To define an extension, select a content node and specify the base type that this complex type extends. A list displays allthe global types.

Restriction type nodes and extension type nodes have the following properties:

• Type is always Restriction or Extension.

• Base Type specifies the data type that this simple type is based on.

Related concepts


Related tasks




Chapter 4. Tasks

Defining content types in XML SchemasTo define a content type, select a complex type node and specify the following properties:

• Type is always Content.

• Mixed is a Boolean value that specifies whether this node can contain text as well as elements.

• Content Type:

• simpleContent specifies that the node can contain only character data and no elements or attributes.

• complexContent specifies that the node can contain character data, elements, and attributes.

Related concepts


Related tasks



Defining content types in XML Schemas

Defining aggregator types in XML SchemasAfter you create a simple type node, you can add an aggregator node as its child. An aggregator node indicates that a singleinstance of an element of your new simple type contains a sequence of atomic types.

To define an aggregator type, select a simple type node and specify the following properties:

• Type must be list or union:

• list specifies that all instances in the sequence must be of the same type.

• union specifies that the instances in the sequence can be of different types.

• Aggregator Type is the type of the instances included in your new simple type. If the value of Type is union, you canspecify a space-separated list.

Related concepts


Related tasks



Chapter 4. Tasks

Defining facet types in XML SchemasSelect a restriction node then select facet from the palette to e allowable set of values for the simple type.

The following list provides a brief description of what to specify as the value of a facet for a new simple type. You shouldconsult the XML Schema Recommendation for a complete definition of each facet and its allowable values.

• Facet Type: must be one of the following:

• enumeration: one allowable value. Add an enumeration facet for each allowable value. For example:

<xsd:simpleType name="USState"><xsd:restriction base="xsd:string"><xsd:enumeration value="AK"/><xsd:enumeration value="AL"/><xsd:enumeration value="AR"/></xsd:restriction>

</xsd:simpleType>

• fractionDigits: the maximum number of digits that are allowed in the fractional portion of values of simple types thatare derived from xsd:decimal.

• length: the number of units of length. Units vary according to the base type. The simple type must be this number ofunits of length. For example, if xsd:string is the base type, you might specify 5 as the length if you know that eachvalue will be a code that always has five characters.

• maxExclusive: the exclusive upper bound of the range of values allowed for this simple type. The value of the simpletype must be less than the value of maxExclusive.

• maxInclusive: the inclusive upper bound of the range of values allowed for this simple type. The value of the simpletype must be less than or equal to the value of maxInclusive.

• maxLength: the maximum number of units of length. Units vary according to the base type. The length of the instancesof this simple type must be less than or equal to this number of lengths.

• minExclusive: the exclusive lower bound of the range of values allowed for this simple type. The value of the simpletype must be more than the value of minExclusive.

• minInclusive: the inclusive lower bound of the range of values allowed for this simple type. The value of the simpletype must be equal to or more than the value of minInclusive.

• minLength: the minimum number of units of length. Units vary according to the base type. The length of the instancesof this simple type must be equal to or more than this number of lengths.

• pattern: a regular expression. The values of the simple type must be literals that match this regular expression.

• totalDigits: the maximum number of digits that are allowed in values of simple types that are derived from xsd:decimal.

• whiteSpace: specify one of the following values:

• preserve specifies that no normalization is performed. The value is not changed.

• replace specifies that each tab, line feed, and return is replaced with a space.

• collapse specifies that the processing specified by replace is performed, and then contiguous sequences of spacesare collapsed into one space.


Defining facet types in XML Schemas

• Fixed is a Boolean value that indicates whether you can further restrict the simple type with this same facet and a differentvalue. The default is false, specifying that you can apply the same facet more than once. The following definition is anexample:

<xsd:simpleType name="zip"><xsd:restriction base="xsd:string"><xsd:length value="5" fixed="true"/></xsd:restriction>

</xsd:simpleType>

This defines a postal code whose length is 5 characters. You can further restrict this simple type with, for example, thepattern facet so that the first three characters must always be "100", but you cannot further restrict the length facet whenthe Fixed property is set to true .

Facet types of pattern and enumeration do not have the Fixed property.

• Value varies according to the facet type.

Related concepts


Related tasks




Chapter 4. Tasks

Defining notationsA notation is an unparsed entity. It is a name for something that you cannot express in terms of XML. For example, if youhave an XML file that represents a press release. You can define a notation named logo that points to a JPEG image. Youcan place the notation in the XML file in the location where you want the logo.

You can define a notation node in the Tree or Source page (not in the Diagram page). Select the node that you want toannotate, right-click and select Add > Notation.

Notation types have the following properties:

• Type is always Notation.

• Name is the name you specify for the notation.

• Public IDis the unique string that refers to the physical location of the external data, for example, MyCompany//LOGO//JPEG.

• System ID is the URL used to physically locate the external data, for example, http://www.mycompany.com/mylogo.jpg.

Related concepts


Related tasks



Defining notations

Defining Include, Import, and Redefine nodesThe included schema augments the including schema. Both schemas must have the same target namespace.

To define an Include, Import, or Redefine node in a schema:

1. Click the schema node and select Include, Import, or Redefine.

2. Enter the URL that identifies the location of the file that contains the XML schema.

3. If you defined an Import node, enter the target namespace in the Properties view. The target namespace must be differentfrom the target namespace of the importing file.

Include type properties

Include types have the following properties:

• Type is always Include.

• Location is the URL that identifies the location of the XML schema.

Import type properties

Import types have the following properties:

• Type is always Import.

• Location is the URL that identifies the location of the XML schema.

• Target Namespace is the namespace that elements and attributes defined in an instance document belong to.

Redefine type properties

Redefine types have the following properties:

• Type is always Redefine.

• Location the URL that identifies the location of the XML schema.

Related concepts


Related tasks


"Including and importing external XML schemas " on page 95


Chapter 4. Tasks

Including and importing external XML schemasYou can split the definition of an XML schema into multiple files. To do this, you specify Include, Import, or Redefine nodesin a master XML schema document.

When an XML Schema includes, rather than imports, another XML Schema:

• The included XML schema augments the XML schema that includes it; they define the same XML Schema.

• The included XML schema and the XML schema that includes it must both have the same target namespace.

When an XML Schema imports rather than includes another XML Schema:

• The XML Schema that imports another XML Schema can reference parts of the imported XML schema. For example, itcan specify a prefix whose namespace is defined in the imported XML Schema.

• The imported XML Schema and the XML Schema that imports it must have different target namespaces.

A Redefine node is a variation of an Include node. The difference is that a Redefine node can redefine some of the definitionsin the included schema. For example, if you release version 1 of an XML Schema for RFQs and then find that you need torelease version 2 of the XML Schema. You can specify a Redefine node so that in version 2 the definition of a particularelement has a new attribute.

You can include or import external XML Schemas in the Tree and Source pages. Sonic Workbench displays the include orimport node in the Source and Tree pages; it does not display the contents of the included or imported schema. For example,in the Tree page, you cannot expand an include node.

You cannot add include or import nodes in the Diagram page. In the Diagram page, Sonic Workbench displays completeinformation for any definitions that are in the included or imported schema and that are referenced in the including orimporting XML schema. You can expand such definitions to examine their entire structure. However, you cannot modifythese definitions.

To modify these definitions, you must open the included or imported schema, right-click the included or imported node andclick Go To Include/Import. Sonic Workbench opens the XML Schema that contains the definition you want to modify. TheDiagram page displays the diagram of the selected definition.

Related tasks



Including and importing external XML schemas

Adding an Identity Constraint to an Element

In XML Schemas, you associate an identity constraint with an element. You can specify an identity constraint in the Treeor Source page of an XML Schema. You cannot specify an identity constraint in the Diagram page.

To define an identity constraint, select an element node. The type of an identity constraint can be:

• Unique identity constraint forces the result of evaluation of an XPath expression to be unique. Sonic Workbench evaluatesthe XPath expression against the element for which you define the identity constraint. If the element is present, the resultmust be unique among the children of that element.

• Key identity constraint specifies that the fields that form the expression must be present in all instance documents. Forexample, if a key is based on date and number attributes, the date and number attributes must always be specified.

• Keyref identity constraint is equivalent to the IDREF attribute in DTDs. It specifies that the contents of a field in theinstance document is the value of a key that is defined in another document. For example, a Quote document would havea reference to the RFQ that originated it.

To define a selector or key, select an identity constraint node and define the selector or key for the identity constraint:

• selector

• field

Identity Constraint types have the following properties:

• Type is always Identity Constraint.

• Name is the name you specify for the identity constraint.

Constraint Element types have the following properties:

• Type is always Constraint Element.

• XPath Expression is an XPath expression that returns the element for which you are defining a constraint.

Example of an Identity Constraint

If you defined the following element in an XML Schema:

<element name="purchaseReport"><complexType><sequence>

<element name="parts"><complexType><sequence><element name="part" maxOccurs="unbounded"><attribute name="number" type="SKU"/><attribute name="vendor" type="xs:string"/><attribute name="quantity" type="integer"/></element>

</sequence></complexType>

</element></sequence></complexType></element>

You can then define the following elements in an XML document that uses this XML schema:


Chapter 4. Tasks

<purchaseReport><parts><part number="00-01-02" vendor="IBM" quantity="10"/><part number="01-01-02" vendor="BEAS" quantity="1"/>...

</parts></purchaseReport>

To enforce that there is just one part element for each product that is purchased, add the following to the previous XMLSchema example:

... [previous definition]</sequence></complexType><unique name="pNumKey"><selector xpath="parts/part"/><field xpath="@number"/><field xpath="@vendor"/></unique>

</element>

The XML schema validator starts with an initial context set that contains purchaseReport elements. It runs the XPathexpression parts/part to obtain the data set to be checked. In this example, the data set contains the two part elements.The XML schema validator then gathers the values from the number and vendor attributes, and builds a key from thesevalues. It then uses the key to check that no part elements have the same tuple.

Related concepts


Related tasks




Adding annotation, documentation, text, and comments to XML Schemas

The XML Schema recommendation provides comment and annotation nodes for you to provide information that documentsan XML Schema. You can add these nodes to any node in an XML Schema.

The difference between comments and annotations is that a human must read a comment node for it to have meaning. Anannotation element allows you to specify nodes that a stylesheet can operate on.

You can add comments, annotations, and white space in the Tree or Source page. You cannot do this in the Diagram page.

In an XML Schema, you might have a comment node such as the following:

<xsd:schema ...><xsd:element name="..."/>

The contents of a comment node have meaning only when a person reads them. However, the contents of annotation nodescan be operated on. For example:

<xsd:element name="foo"><xsd:annotation>

<xsd:documentation language="en">This is a <b>foo</b> element. Use it for ...

</xsd:documentation><xsd:documentation language="jp">xksnjgfyre fvhfdbvhjds

</xsd:documentation></xsd:annotation></xsd:element>

You can apply an XSLT stylesheet to this XML Schema document. The stylesheet could generate an HTML manual byextracting the Documentation nodes in the desired language:

<xsl:stylesheet ... ><xsl:template match="xsd:element"><xsl:apply-templates select="xsd:annotation/xsd:documentation[@language='en']"/>

</xsl:template>...

</xsl:stlyesheet>

If the parent of the new comment or annotation node has more than one child, you can move the comment or annotationwith the up or down arrow. However, you cannot move the comment or annotation out of the scope of its parent.

An annotation node indicates the start of some documentation. To define an annotation node, select any node to add anannotation node.

Click an annotation node to add documentation. You can include text, a URL, a file path.

Click a documentation node to add a text node.

Click any node to add a comment node.

Documentation types have the following properties:

• Type is always Documentation.

• Source is the path or URL for an external file that contains the documentation.

• Language is the language of the contents of the documentation.


Chapter 4. Tasks

Related concepts


Related tasks




Editing XML schemasThe recommended method for defining or updating an XML Schema is to edit the schema in the Diagram page. The Diagrampage provides tools for defining an XML Schema. In general, you right-click the item you want to operate on, and then selectthe operation from a shortcut menu.

In the Tree page, to add a node to an XML Schema, click a node that is already in the schema. Sonic Workbench activatesthe buttons for only those nodes that can be children of the node you selected. If you hold down the Shift key, SonicWorkbench activates only those buttons that allow you to add nodes that can be siblings of the selected node.

The steps for editing the Source page of an XML Schema are the same as for any other XML document.

Each type of node has its own set of properties. Click the node whose properties you want to view, and the properties appearin the Properties view. If the Properties view is not visible, selectWindow > Show View > Properties. To change the valueof a property, click the property field and enter the new value.

Related concepts

"XML Schema Editor" on page 57"XML Schema editor: Diagram page" on page 62 (Available only when Progress Sonic Workbench is installed)"XML Schema editor: Tree page " on page 61"XML Schema editor: Palette " on page 64"XML Editor" on page 11

Related tasks

"Adding and deleting XML schema components in the Diagram page " on page 77(Available only when Progress SonicWorkbench is installed)"Moving schema elements in the Diagram page of the XML Schema editor " on page 78(Available only when Progress SonicWorkbench is installed)"Adding XML schema components in the Tree page " on page 68"Using Undo and Redo " on page 70"Editing nodes in the Tree page " on page 73"Cutting, copying, and pasting nodes in the Tree page " on page 72"Reordering nodes in the Tree page " on page 71"Deleting nodes in the Tree page " on page 74"Dragging nodes from the Tree page to another editor " on page 69"Saving an XML schema" on page 101


Chapter 4. Tasks

Saving an XML schemaTo save changes in an XML schema document do one of the following:

• Select File > Save.

• Click Ctrl+S.

To save your changes as a new XML schema document, select File > Save As.

Related tasks



Saving an XML schema

Specifying colors for the XML Schema editorTo modify the colors for the XML Schema editor, select Window > Preferences > Sonic > XML Editors > XSD > ColorSettings, then select the element and Bold, Italic, and Color.

Related concepts



Chapter 4. Tasks

Chapter 5. ReferenceWhat Is an XML Schema? ................................................................................................................................ 104xsd:schema properties ..................................................................................................................................... 106Simple types in XML Schemas ............................................................................................................................ 107Complex types in XML Schemas ......................................................................................................................... 109


What Is an XML Schema?An XML schema conforms with the W3C XML Schema Recommendation which defines an XML markup vocabulary forspecifying the structure of an XML document. An XML Schema serves the same purpose as a Document Type Definition(DTD). The most visible difference is that an XML schema is in XML, while a DTD is not.

An XML schema defines the elements in a document. In an XML schema, elements that contain subelements or attributesare complex types. Elements that contain data but do not contain subelements or attributes are simple types.

Attributes are always simple types. In your XML schema, along with elements and attributes, you define complex types andsome simple types. In addition, many simple types are part of the XML schema grammar.

Suppose you want to define an XML schema that defines book, magazine, and newsletter elements. The type of each ofthese elements is PublicationType. The XML schema defines the PublicationType complex type. An element that is aPublicationType contains the following:

• The genre attribute specifies the style of the publication. That is, whether it is a book, magazine, or newsletter.

• There is always exactly one title element.

• The subtitle element is optional.

• There must be at least one author element and there can be more. Each author element contains one first-name elementand one last-name element.

• Of the following three elements, exactly one must always be present and must be in the order specified in this list:

• ISBNnumber

• PUBnumber

• LOCnumber

Related tasks















Chapter 5. Reference


Related reference



What Is an XML Schema?

xsd:schema propertiesThe root element of every XML schema document is the xsd:schema element. The xsd:schema element has the followingproperties:

• Type is always schema.

• Namespace: the namespace for the schema node is usually xsd, but you can change it.

• Target Namespace: this is the namespace that elements and attributes defined in an instance document belong to. Forexample, if you define the following:

•<xsd:schema ... targetNamespace="http://myNS"><xsd:element name="myelement"/>

In an instance document, the following declarations conform with the target namespace:

<myelement xmlns="http://myNS”/><myns:myelement xmlns:myns="http://myNS"/>

However, the following declaration does not conform:

<myns:myelement xmlns:myns="http://anotherNS"/>

• Version: you can use this property to track revisions of your XML Schema document.

• Default Element Form and Default Attribute Form: an element or attribute’s form is either qualified or unqualified. Whenthe form is qualified, each time an element or attribute is referenced in the schema you must specify the prefix of itsnamespace. Every element and attribute has a form attribute. If it is not explicitly defined, the schema processor checksthe default attribute form specified for the Schema node. For example:

• <xs:schema elementFormDefault="qualified"targetNamespace="http://myNs"xmlns:myns="http://myNS"><xs:element name="topElem">...

</xs:element><xs:element name="anElem"><xs:complexType><xs:sequence><xs:element ref="myns:topElem">...

If the form for the element topElem (or, the default form for elements) is defined as unqualified, the reference can useref="topElem".

• Default Blocked Definitions and Default Final Definitions: if an element does not have its own blocked or final definition,the schema processor uses the default blocked or final definition you specify here.

Related tasks




Simple types in XML SchemasDescriptions of the XML schema built-in types are in the W3C XML Schema Part 2: Datatypes1. XML Schema defines severalkinds of simple types:

• Atomic describes most of the simple types built in to XML schema, such as integer, string, and decimal. They are calledatomic because no part of an element or attribute of an atomic type has meaning on its own in the context of XML schema.It is only the whole instance that has meaning.

• List simple types are sequences of atomic types. All elements of a particular list simple type are instances of the sameatomic type.

• Union simple types are sequences of atomic and list types. However, the elements of a particular union simple type canbe instances of more than one atomic or list type.

• Anonymous simple types are simple type definitions that are not explicitly named. An anonymous simple type can be anatomic, list, or union simple type. You define an anonymous simple type in the element or attribute definition that usesit.

• Anonymous simple types are useful when you want to define a type that is used in only one element or attribute. Byspecifying an anonymous simple type, you save the overhead of explicitly defining the type and specifying a reference toit.

Examples of simple types

The W3C XML Schema Part 0: Primer2 specifies the following simple type in its sample purchase order schema:

<xsd:simpleType name="SKU"><xsd:restriction base="xsd:string"><xsd:pattern value="\d{3}-[A-Z]{2}"/>

</xsd:restriction></xsd:simpleType>

This specifies that SKU is a simple type. It is restricted to the values of the base type, which is xsd:string. This means thatfor a node that is of type SKU, the possible values are a subset of the values allowed for the xsd:string type.

The xsd:pattern element specifies that the pattern facet is being applied to the set of values allowed by the xsd:stringtype. The value of the xsd:pattern element is an XML Schema regular expression that specifies the allowable values fornodes of type SKU . In this example, the regular expression specifies that the value must be three digits, followed by ahyphen, followed by two uppercase ASCII letters. For information about XML Schema expressions, see the W3C XML SchemaPart 0: Primer3.

Elsewhere in the purchase order schema, an attribute definition specifies that SKU is the type of its value:

<xsd:attribute name="partNum" type="SKU" use="required"/>

An XML document that uses a schema that contains this simple type definition can specify the partNum attribute. Theparser ensures that the value of the partNum attribute is in the range specified by the xsd:pattern element. The SKU typeitself is not mentioned in the instance document.

The following is another example of a simple type definition from the W3C XML Schema Part 0: Primer4. This simple typeis based on the xsd:integer type. It specifies two facets (minInclusive and maxInclusive), which specify the lower and upperinclusive bounds of the range of valid values.

1 http://www.w3.org/TR/xmlschema-2/2 http://www.w3.org/TR/xmlschema-0/3 http://www.w3.org/TR/xmlschema-0/4 http://www.w3.org/TR/xmlschema-0/


Simple types in XML Schemas

http://www.w3.org/TR/xmlschema-2/









<xsd:simpleType name="myInteger"><xsd:restriction base="xsd:integer"><xsd:minInclusive value="10000"/><xsd:maxInclusive value="99999"/>

</xsd:restriction></xsd:simpleType>

Related tasks




Complex types in XML SchemasAn element that contains anything more than raw data is a complex type. The XML Schema Recommendation does notinclude any built-in complex types. You must define each complex type you need.

In the Diagram page, when you define a complex type as a top-level definition, it is a global declaration. You can specifythat any element in the schema is of this complex type. Similarly, in the Tree page, it is a global declaration when you definea complex type as a child of the Schema node.

Define the complex type first. Then when you define an element, Sonic Workbench includes your complex type’s name inthe menu that lists the available types for your new element. You can select the name of the complex type from the menu.

You can also define a complex type in the definition of an element. As you define a complex type, it is helpful to keep inmind that a complexType node can have only one child node that is a model group modifier. However, this modifer nodecan have any number of child nodes that are modifiers. In this way, you can specify any number of modifiers in a complextype. Each modifier controls the occurrence of its child nodes. You can specify the same modifier more than once. Forexample, you might want to specify the sequence modifier, with some child nodes, then the choice modifier with somechild nodes, and then the o>sequence modifier again with other child nodes.

An XML schema allows you to create groups of attributes. This makes it easy to create a complex type that contains onlyattributes. The first step is to create an attribute group. You can then create a complex type and add a reference to theattribute group to the complex type.

You can define a complex type that mixes elements and data, for example in the following:

<letter><salutation>Dear Mr.<name>Robert Smith</name>,

</salutation>Your order of

<quantity>1 </quantity><productName>Baby Monitor </productName>

shipped from our warehouse on<shipDate>2001-04-21</shipDate>

.</letter>

The letter element has element and data children, and the salutation element has element and data children. You mustdefine complex types for both the letter and the salutation elements. For both these elements, the value of the Mixed propertymust be true . This allows an element to contain both elements and raw data as children.

You can define a complex type that contains elements in a particular order, with some of them optional, and you can ensurethat only one element from a particular group of elements is present. To define this, you must define a sequence modifierfirst. You can then define sequence and choice modifiers that are children of the initial sequence modifier.

Related tasks



Complex types in XML Schemas


Part III. XPath Helper6. About XPath Helper .................................................................................................................................... 1157. Tasks ........................................................................................................................................................ 117

Launching the XPath Helper ...................................................................................................................... 118Viewing the source document for an XPath expression ..................................................................................... 119Generating XPath expressions ..................................................................................................................... 120Building XPath expressions ....................................................................................................................... 121Evaluating an XPath expression ................................................................................................................... 122Clearing an XPath expression ...................................................................................................................... 123About XML document structure .................................................................................................................. 124XPath Helper target node .......................................................................................................................... 125Selecting a target node ............................................................................................................................ 126Removing a target node ............................................................................................................................ 127Selecting a key node ................................................................................................................................ 128Removing a key node ............................................................................................................................... 129Running sample queries with XPath Helper .................................................................................................... 130Internationalizing XPath ........................................................................................................................... 131

8. References ................................................................................................................................................ 133Getting started with queries ...................................................................................................................... 135

Querying multiple documents ............................................................................................................ 136Restrictions on queries with XPath Helper ............................................................................................. 137Obtaining all marked-up text .............................................................................................................. 138Obtaining part of an XML document ..................................................................................................... 139Obtaining all elements of a particular name ........................................................................................... 140Obtaining all elements of a particular name from a particular branch ............................................................ 141Different results from similar queries ................................................................................................... 142Queries that return more than you want ................................................................................................ 143Specifying attributes in queries ........................................................................................................... 144Filtering the results of XPath queries .................................................................................................... 145

How XPath Helper evaluates a filter ............................................................................................. 146Filter examples ...................................................................................................................... 147Quotation marks in filters .......................................................................................................... 148Multiple filters ........................................................................................................................ 149Filters and attributes ............................................................................................................... 150

Using wildcards in queries ................................................................................................................. 151Calling functions in queries ................................................................................................................ 152Case sensitivity and blank spaces in queries ........................................................................................... 153Precedence of query operators ............................................................................................................ 154

Specifying nodes to evaluate ..................................................................................................................... 155Using context operators .................................................................................................................... 156Starting at the context node ............................................................................................................... 157Starting at the root node ................................................................................................................... 158Descending along branches ............................................................................................................... 159Explicitly specifying the current context ................................................................................................. 160Specifying children or descendants of parent nodes .................................................................................. 161Examples of XPath expression results ................................................................................................... 162Specifying an axis in a query .............................................................................................................. 163Supported XPath axes ...................................................................................................................... 164Axes that represent the whole XML document ........................................................................................ 168

Handling strings and text .......................................................................................................................... 169Finding identical strings .................................................................................................................... 170Finding elements containing specified strings ......................................................................................... 171Finding substrings that occur before specified strings ................................................................................ 172Finding substrings that occur after specified strings .................................................................................. 173

Finding substrings by position ............................................................................................................ 174Concatenating strings ....................................................................................................................... 175Determining the number of characters in a string .................................................................................... 176Handling white space in strings .......................................................................................................... 177Replacing characters in strings ........................................................................................................... 178Converting objects to strings .............................................................................................................. 179Finding strings that start with a particular string ..................................................................................... 180Obtaining the text contained in a node ................................................................................................. 181

Specifying Boolean expressions and functions ................................................................................................. 182Converting an object to Boolean .......................................................................................................... 183Obtaining Boolean values .................................................................................................................. 184Determining the context node language ................................................................................................. 185

Specifying number operations and functions .................................................................................................. 186Performing arithmetic operations ........................................................................................................ 187Converting an object to a number ........................................................................................................ 188Obtaining the sum of the values in a node set ........................................................................................ 189Obtaining the largest, smallest, or closest number .................................................................................. 190

Comparing values ................................................................................................................................... 191About comparison operators .............................................................................................................. 192How XPath Helper evaluates comparisons ............................................................................................ 193Priority of object types in comparisons .................................................................................................. 194Comparing node sets ....................................................................................................................... 195Comparing Boolean values with = and != ............................................................................................. 196Comparing single values with = and != ............................................................................................... 197Comparing single values with <=, <, >, and >= ................................................................................. 198Examples of comparisons ................................................................................................................. 199

Finding a particular node .......................................................................................................................... 200About node positions ....................................................................................................................... 201Determining the position number of a node ............................................................................................ 202Positions in relation to parent nodes .................................................................................................... 203Finding nodes relative to the last node in a set ........................................................................................ 204Finding multiple nodes .................................................................................................................... 205Finding the first node that meets a condition ......................................................................................... 206Finding an element with a particular ID ............................................................................................... 207The id() function ............................................................................................................................. 208Unique IDs .................................................................................................................................... 209Generating temporary IDs for nodes .................................................................................................... 210

Obtaining particular node types with node tests ............................................................................................. 211Node tests .................................................................................................................................... 212About the document object ............................................................................................................... 213Finding an element with a particular key .............................................................................................. 214

Obtaining a union ................................................................................................................................... 215Obtaining information about a node or a node set ........................................................................................... 216

Obtaining the name of a node ............................................................................................................ 217Obtaining the namespace URI ........................................................................................................... 218Obtaining the local name .................................................................................................................. 219Obtaining the expanded name ........................................................................................................... 220Specifying wildcards with namespaces ................................................................................................ 221Examples of namespaces in queries .................................................................................................... 222Obtaining the URI for an unparsed entity .............................................................................................. 223Determining the number of nodes in a collection .................................................................................... 224Determining the context size ............................................................................................................. 225

Using XPath expressions in stylesheets ........................................................................................................ 226Defining variables in stylesheets ......................................................................................................... 228Obtaining system properties when using XPath in stylesheets .................................................................... 229Available functions when using XPath in stylesheets ................................................................................. 230Current node for the current XSLT template ........................................................................................... 231

Using the document() function to access other documents ................................................................................. 232Example of calling the document() function ........................................................................................... 233

XPath functions quick reference .................................................................................................................. 234XPath syntax quick reference ...................................................................................................................... 236Abbreviations in XPath expressions ............................................................................................................. 238

Use the XPath Helper to generate an XPath expression and view its results. The Xpath Helper supports both XPath 1.0 and 2.0. Itdefaults to the version in use by the file that invoked the Helper.

The XPath Helper shows the source XML document in a tree view (in the left-hand pane). In the tree view, you can see the elements,attributes, values, and namespaces for the source document.

Depending on how you launch the XPath Helper, you might also see an Input Document field, which enables you to select different XMLdocuments. See Viewing the source document for an XPath expression on page 119.

When you double-click a node in the tree view, the XPath Helper generates an XPath expression on page 120 and displays the expressionin the XPath tab of the Input panel. How the expression is generated depends on which generation options you specify in the drop-down.

Use the following toolbar buttons to generate XPath expressions:

• Use Index: Inserts an index in the XPath expression to identify the position of the element.

• get element text(): Generates an XPath expression that invokes the text() function in the last location step.

• Node Depth: Limits the number of location steps in an XPath expression, and determines whether the expression is relative or absolute.

You can evaluate the expression on page 122 and view the results of the expression, or you can clear the expression on page 123.

Use the following toolbar buttons to evaluate XPath expressions:

• Auto Evaluate: XPath Helper continuously shows results as you manually enter XPath expressions.

• XPath Version 1.0: Generates expressions and evaluates expressions that are compliant with XPath version 1.0.

• XPath Version 2.0: Generates expressions and evaluates expressions that are compliant with XPath version 2.0.

Choose from the following expression options:

• Localname

• Namespace

• Prefix

The Input panel also has a Namespaces tab that shows all the namespaces that apply to the selected node.

Use the toolbar buttons to edit namespace information:

• Add namespace

• Remove namespace

If you click the Add namespace button, a dialog box opens that lists all the namespaces found in the Namespace preferences page. Youcan add your own namespaces using this dialog box.

Chapter 6. About XPath HelperXPath is a notation for retrieving information from a document. A query, which is always an XPath expression, returnswell-formed XML or an XPath value object. The value returned could be a set of nodes, information about node relationships,or derived values.

You can use XPath in many contexts including providing links to nodes, for searching repositories, and for many otherapplications.

XPath allows you to identify parts of an XML document. In addition, a subset of XPath allows you to test whether or not anode matches a particular pattern. XPath provides Boolean logic, filters, indexing into collections of nodes, and more.

XPath is declarative rather than procedural. Queries say what should be found, not how it should be found. This is importantbecause a query optimizer must be free to use indexes or other structures to find results efficiently. For example, book/authormeans find all author elements that are contained in book elements.

XPath provides a common syntax for features shared by Extensible Stylesheet Language Transformations (XSLT) and XPointer.XSLT is a language for transforming XML documents into other XML documents. XPointer builds on XPath and is a languagefor addressing the internal structure of XML documents, such as particular elements.

The basic syntax for XPath mimics the Uniform Resource Identifier (URI) directory navigation syntax. However, the syntaxdoes not specify navigation through a physical file structure. The navigation is through elements in the XML tree.

When you use XPath helper, you specify queries as values of match and select attributes in stylesheets. In this way, youuse queries to select the nodes you want to transform and to select the operations you want to perform on those nodes.

You can also specify a query at the top of an XML document window in the Run XPath option on the toolbar. In the Resultspane, XPath Helper displays a DOM tree that represents the result of the query.

When you define a query, keep in mind that XML data can be represented as a tree. A tree is a hierarchical representationof XML data. The root node is the top of the tree. Each element, attribute, text string, comment, and processing instructioncorresponds to one node in the tree. A tree also shows the relationships among the nodes.

The XPath Helper implements all features defined in the W3C XPath Recommendation. For additional information aboutXPath see http://www.w3.org/TR/xpath.

Related reference

" About XML document structure " on page 124"Running sample queries with XPath Helper" on page 130


http://www.w3.org/TR/xpath


Chapter 7. TasksLaunching the XPath Helper .............................................................................................................................. 118Viewing the source document for an XPath expression ............................................................................................. 119Generating XPath expressions ............................................................................................................................. 120Building XPath expressions ............................................................................................................................... 121Evaluating an XPath expression ........................................................................................................................... 122Clearing an XPath expression .............................................................................................................................. 123About XML document structure .......................................................................................................................... 124XPath Helper target node .................................................................................................................................. 125Selecting a target node .................................................................................................................................... 126Removing a target node .................................................................................................................................... 127Selecting a key node ........................................................................................................................................ 128Removing a key node ....................................................................................................................................... 129Running sample queries with XPath Helper ............................................................................................................ 130Internationalizing XPath ................................................................................................................................... 131


Launching the XPath HelperYou can launch the XPath helper from several different locations. For example, you can launch it from the Source page ofthe XML editor. You can also launch it from other editors, at locations where you specify XPath expressions.

How you launch the XPath helper affects its behavior. For example, if you edit an XML document with the XML editor,launching the XPath helper from the Source page enables you to create and test XPath expressions against the XML document.

To launch the XPath helper from the Source page of the XML editor, click the XPath Helper button in the toolbar.

Related concepts



Chapter 7. Tasks

Viewing the source document for an XPath expressionThe source document is the document on which the XPath will be composed and evaluated for testing. The source file canbe specified as an input parameter when the Xpath Helper is opened.

After selecting an XML document, it is parsed and displayed in the left side of the Helper in a tree consisting of XML elementsand their values.

NoteSome of the following functionality is available only when Progress Sonic Workbench is installed.

You can invoke the Xpath Helper from some Sonic editors by using an XML document as an argument. If you launch theXPath Helper from another Sonic editor at a location where you want to specify an XPath expression — for example, fromthe Routing Rules page of the XPath Routing Rules editor (in the XPath Expression field) in Progress Sonic Workbench —the XPath Helper displays the pathname of the XML document in the Input Document field. This field provides a ... buttonthat opens the SonicFS Chooser, which lets you select a different input document. The Input Document field also providesa drop-down that lists documents you previously opened (if any). The Input Document field does not show up every timeyou launch the XPath Helper; it shows up only if the context allows you to select different input documents. For example,if you are editing a specific XML document in the XML Editor on page 11, you can launch the XPath Helper from the XMLEditor's Source page on page 14. However, since you have already opened the input document in the XML Editor, theXPath Helper does not display the Input Document field.

Related concepts



Viewing the source document for an XPath expression

Generating XPath expressionsYou generate an XPath expression by double-clicking a node in the document tree (shown in the left-hand pane of the XPathHelper). How an expression is generated depends on which generation options you select.

When you select an element, the appropriate XPath expression is displayed in the XPath evaluation text area (based on theoption you select). You can modify the default generated XPath expression.

When you click the Evaluate button, the results for that expression are displayed in the Results windows in tree format.You can expand and collapse the tree if it has sub nodes. You can view the result count.

You can set a target node and test whether the XPath expression hits that node uniquely (found in the selected node or inthe whole tree), or a part of a result sequence. The number of hits found for the selected node is also displayed.

Related concepts


Related tasks

"Evaluating an XPath expression" on page 122


Chapter 7. Tasks

Building XPath expressionsYou can build an XPath expression in two ways using the XPath helper:

• Double-click a node in the tree in the left-hand pane of the XPath Helper.

• Select an element in the tree, right-click, and select an option:

• Remove Target— Removes the current target.

• Set Key— The appropriative XPath expression is displayed in the XPath component text area. A text box also appearsin the tree for the selected node. In the text box, you enter the condition or constraint. This can also be done in theXPath component text area. It is simultaneously updated.

• Remove Key— Removes the current key.

• Set Root— Sets this node as root. If this node is a sub-node or child, all of its parents and the root are collapsed.

Example XML document:

0 <x>1 <A>2 <B>27</B>3 <C>12</C>4 </A>6 <A>7 <B>27</B>8 <C>12</C>9 </A>10 </x>

Example targets:

• Setting the target on line 3, with no key generates /x/A/C

• Setting the target on line 3, with the key on 2 generates /x/A[B='27']/C

This example also shows how to use depth and index=true.

Related concepts


Related tasks

"Selecting a key node" on page 128"Removing a key node" on page 129" Selecting a target node " on page 126"Removing a target node" on page 127

Related reference

" Abbreviations in XPath expressions " on page 238


Building XPath expressions

Evaluating an XPath expressionTo evaluate an XPath expression:

1. Select the evaluation option on the toolbar.

2. Select an XPath generation option in the drop-down in the toolbar.

3. Select the node depth.

4. In the left pane, click the node you want to evaluate.

5. In the right pane, click Evaluate.

XPath evaluates the expression according to the criteria you select and the results appear in the Results pane.

Related concepts


Related tasks

"Generating XPath expressions" on page 120"Clearing an XPath expression" on page 123" Selecting a target node " on page 126"Removing a target node" on page 127"Clearing an XPath expression" on page 123


Chapter 7. Tasks

Clearing an XPath expressionAfter you generate (or manually enter) an XPath expression, if you do not want to evaluate the expression on page 122, youcan clear the expression.

To clear an expression you click the Clear button.

When you clear the expression, the Input panel erases the current XPath expression.

Related concepts


Related tasks

"Generating XPath expressions" on page 120" Selecting a target node " on page 126"Removing a target node" on page 127


Clearing an XPath expression

About XML document structureThe XPath Helper operates on a tree representation of XML data that looks like the following figure:

The root node has no actual text associated with it. You can think of the file name as the root node. A document can includezero or more comments and zero or more processing instructions.

A document element is required, and there can be only one. The document element contains all elements in the document.For example:

In the preceding figure, bookstore.xml is the name of a file that contains XML data. There is a comment near the beginningof the document that starts with "This file represents a ..." The document element is bookstore. The immediatechildren of bookstore include an attribute, a namespace declaration, three book elements (one is in the my namespace),and a magazine element.


Chapter 7. Tasks

XPath Helper target nodeWhen you evaluate an XPath expression, the result set might be large, depending on the size of the XML document and onhow you construct the expression. If you want to be sure that a specific node is in the result set, you can either manuallysearch through the result set one node at a time, or you can specify a target node. A target node is a node you want to besure is present in the result set of an XPath expression.

When you select a target node, a target indicator (red circle) appears in the gutter of the left-hand pane, indicating whichnode is the target.

After you select a target node, you can enter and evaluate (or generate and evaluate) an XPath expression. If the target nodeis in the result set, the message Target Reached is displayed in the Results pane. The target indicator changes to acheckmark.

Related tasks

" Building XPath expressions " on page 121

" Selecting a target node " on page 126

"Removing a target node" on page 127


XPath Helper target node

Selecting a target nodeTo specify a target node:

1. In the left-hand pane of the XPath Helper, right-click a node.

2. Select Set As Target.

When you select a target node, a target indicator (red circle) appears in the gutter of the left-hand pane, indicating whichnode is the target.

Related concepts


Related tasks

"Removing a target node" on page 127


Chapter 7. Tasks

Removing a target nodeTo remove a target node:

1. In the document tree, right-click a node previously set as the target node.

2. Select Remove Target.

When you select a target node, a target indicator (red circle) is displayed in the gutter of the left-hand pane, indicating whichnode is the target. After you remove the target node, the target indicator is hidden.

Related tasks

" Selecting a target node " on page 126


Removing a target node

Selecting a key nodeTo select a key node:

1. In the left-hand pane of the XPath Helper, right-click a node.

2. Select Set As Key.

When you set a key node, a key indicator is displayed in the gutter of the left-hand pane, indicating which node is the key.

Related concepts


Related tasks

"Removing a key node" on page 129

Related reference

" Finding an element with a particular key " on page 214


Chapter 7. Tasks

Removing a key nodeTo remove a key node:

1. In the left pane of the XPath Helper, right-click a key node (indicated by the key indicator).

2. Select Remove Key.

When you remove a key node, the corresponding key indicator is removed from the gutter in the left pane.

Related concepts



Removing a key node

Running sample queries with XPath HelperTo run queries:

1. Open the XML document.

2. In the Source page toolbar, in the Run XPath Helper, type a query.

For example:

/bookstore/book/author

3. Press Enter.

Xpath Helper displays the results in the Results pane of the XPath helper.

Related reference

" Restrictions on queries with XPath Helper " on page 137

" Querying multiple documents " on page 136


Chapter 7. Tasks

Internationalizing XPathQueries can contain non-Latin characters.


Internationalizing XPath


Chapter 8. ReferencesGetting started with queries .............................................................................................................................. 135

Querying multiple documents .................................................................................................................... 136Restrictions on queries with XPath Helper ..................................................................................................... 137Obtaining all marked-up text ...................................................................................................................... 138Obtaining part of an XML document ............................................................................................................. 139Obtaining all elements of a particular name ................................................................................................... 140Obtaining all elements of a particular name from a particular branch .................................................................... 141Different results from similar queries ........................................................................................................... 142Queries that return more than you want ........................................................................................................ 143Specifying attributes in queries ................................................................................................................... 144Filtering the results of XPath queries ............................................................................................................ 145

How XPath Helper evaluates a filter ..................................................................................................... 146Filter examples .............................................................................................................................. 147Quotation marks in filters .................................................................................................................. 148Multiple filters ................................................................................................................................ 149Filters and attributes ....................................................................................................................... 150

Using wildcards in queries ......................................................................................................................... 151Calling functions in queries ........................................................................................................................ 152Case sensitivity and blank spaces in queries ................................................................................................... 153Precedence of query operators .................................................................................................................... 154

Specifying nodes to evaluate ............................................................................................................................. 155Using context operators ............................................................................................................................ 156Starting at the context node ....................................................................................................................... 157Starting at the root node ........................................................................................................................... 158Descending along branches ....................................................................................................................... 159Explicitly specifying the current context ......................................................................................................... 160Specifying children or descendants of parent nodes .......................................................................................... 161Examples of XPath expression results ........................................................................................................... 162Specifying an axis in a query ...................................................................................................................... 163Supported XPath axes .............................................................................................................................. 164Axes that represent the whole XML document ................................................................................................ 168

Handling strings and text .................................................................................................................................. 169Finding identical strings ............................................................................................................................ 170Finding elements containing specified strings ................................................................................................. 171Finding substrings that occur before specified strings ........................................................................................ 172Finding substrings that occur after specified strings .......................................................................................... 173Finding substrings by position .................................................................................................................... 174Concatenating strings ............................................................................................................................... 175Determining the number of characters in a string ............................................................................................ 176Handling white space in strings .................................................................................................................. 177Replacing characters in strings ................................................................................................................... 178Converting objects to strings ...................................................................................................................... 179Finding strings that start with a particular string ............................................................................................. 180Obtaining the text contained in a node ......................................................................................................... 181

Specifying Boolean expressions and functions ......................................................................................................... 182Converting an object to Boolean .................................................................................................................. 183Obtaining Boolean values .......................................................................................................................... 184Determining the context node language ......................................................................................................... 185

Specifying number operations and functions .......................................................................................................... 186Performing arithmetic operations ................................................................................................................ 187Converting an object to a number ................................................................................................................ 188Obtaining the sum of the values in a node set ................................................................................................ 189Obtaining the largest, smallest, or closest number .......................................................................................... 190


Comparing values ........................................................................................................................................... 191About comparison operators ...................................................................................................................... 192How XPath Helper evaluates comparisons .................................................................................................... 193Priority of object types in comparisons .......................................................................................................... 194Comparing node sets ............................................................................................................................... 195Comparing Boolean values with = and != ..................................................................................................... 196Comparing single values with = and != ....................................................................................................... 197Comparing single values with <=, <, >, and >= ......................................................................................... 198Examples of comparisons ......................................................................................................................... 199

Finding a particular node .................................................................................................................................. 200About node positions ............................................................................................................................... 201Determining the position number of a node .................................................................................................... 202Positions in relation to parent nodes ............................................................................................................ 203Finding nodes relative to the last node in a set ................................................................................................ 204Finding multiple nodes ............................................................................................................................ 205Finding the first node that meets a condition ................................................................................................. 206Finding an element with a particular ID ....................................................................................................... 207The id() function ..................................................................................................................................... 208Unique IDs ............................................................................................................................................ 209Generating temporary IDs for nodes ............................................................................................................ 210

Obtaining particular node types with node tests ..................................................................................................... 211Node tests ............................................................................................................................................ 212About the document object ....................................................................................................................... 213Finding an element with a particular key ...................................................................................................... 214

Obtaining a union ........................................................................................................................................... 215Obtaining information about a node or a node set ................................................................................................... 216

Obtaining the name of a node .................................................................................................................... 217Obtaining the namespace URI ................................................................................................................... 218Obtaining the local name .......................................................................................................................... 219Obtaining the expanded name ................................................................................................................... 220Specifying wildcards with namespaces ........................................................................................................ 221Examples of namespaces in queries ............................................................................................................ 222Obtaining the URI for an unparsed entity ...................................................................................................... 223Determining the number of nodes in a collection ............................................................................................ 224Determining the context size ..................................................................................................................... 225

Using XPath expressions in stylesheets ................................................................................................................ 226Defining variables in stylesheets ................................................................................................................. 228Obtaining system properties when using XPath in stylesheets ............................................................................ 229Available functions when using XPath in stylesheets ......................................................................................... 230Current node for the current XSLT template ................................................................................................... 231

Using the document() function to access other documents ......................................................................................... 232Example of calling the document() function ................................................................................................... 233

XPath functions quick reference .......................................................................................................................... 234XPath syntax quick reference .............................................................................................................................. 236Abbreviations in XPath expressions ..................................................................................................................... 238


Chapter 8. References

Getting started with queriesThe following topics contain examples of typical queries used with XPath.

• Obtaining all marked-up text on page 138

• Obtaining part of an XML document on page 139

• Obtaining all elements of a particular name on page 140

• Obtaining all elements of a particular name from a particular branch on page 141

• Different results from similar queries on page 142

• Queries that return more than you want on page 143

Related reference

"Case sensitivity and blank spaces in queries" on page 153

"Precedence of query operators" on page 154

"Calling functions in queries" on page 152

"Filtering the results of XPath queries " on page 145

"Using wildcards in queries" on page 151

"Specifying attributes in queries" on page 144


Getting started with queries

Querying multiple documentsTo query multiple documents with a single query, call the document() function in a query. During execution of a query ona particular document, this function allows you to access another XML document.



Restrictions on queries with XPath HelperAlthough XQuery permits it, you cannot perform SQL-style joins using XPath. That is, you cannot use XPath to merge thecontents of two XML documents into a single result. You also cannot sort or order attributes. However, you can perform anyof these functions with XQuery, and XPath does permit you to apply a stylesheet to query results and specify the instruction.

You cannot query non-XML data. If you query a document that does not contain XML-formatted data, you receive an errormessage that informs you that the queried text is not XML.


Restrictions on queries with XPath Helper

Obtaining all marked-up textThe following figure shows a complete query (/bookstore ) and the way the XPath helper interprets it:

This query returns the bookstore element. Because the bookstore element is the document element, which contains allelements and attributes in the document, this query returns all marked-up text.

In the query, the initial forward slash (/) instructs the XPath Helper to start its search at the root node.

Suppose you run the following query on bookstore.xml:

/book

This query returns an empty set. It searches the immediate children of the root node for an element named book . Becausethere is no such element, this query does not return any marked-up text. Note that this query does not return an error. Thequery runs successfully, but the XPath Helper does not find any elements that match the query. All book elements aregrandchildren of the root node, and the XPath Helper only checks the children of the root node.



Obtaining part of an XML documentUsually, you use a query to obtain a portion of an XML document. To obtain the particular elements that you want, youmust obtain an element that is a child of the document element. With this information, you can obtain any elements in thedocument.

The following figure shows how the XPath Helper interprets the /bookstore/book query:

When the XPath Helper starts its search at the root node, there is only one element among the immediate children of theroot node. This is the document element. In this example, bookstore is the document element.

The query in this figure returns the book elements that are children of bookstore . This query does not return the my:bookelement, which is also a child of bookstore .

Now you can define queries that obtain any elements you want. For example:

/bookstore/book/title

This query returns title elements contained in book elements that are contained in bookstore.


Obtaining part of an XML document

Obtaining all elements of a particular nameSometimes you want all like-named elements regardless of where they are in a document. In this case, you do not need tostart at the root node and navigate to the elements you want.

For example, the following query returns all last-name elements in any XML document:

//last-name

The double forward slash (//) at the beginning of a query instructs the XPath processor to start at the root node and searchthe entire document. In other words, the XPath processor searches all descendants of the root node.

If you perform this query on bookstore.xml , it returns the last-name elements that are children of author elements,and it also returns the last-name element that is a child of a publication element.



Obtaining all elements of a particular name from a particular branchAlthough sometimes you might want all like-named elements wherever they are in a document, other times you might wantonly those like-named elements from a particular part of the document (branch of the tree).

For example, you might want all price elements contained in book elements, but not price elements contained in magazineelements. The query is to return such a result is:

/bookstore/book//price

This query returns all price elements that are contained in book elements. Some of these price elements are immediatechildren of book elements. One returned price element is a great-grandchild of the second book element. The followingfigure shows how the XPath processor interprets this query:


Obtaining all elements of a particular name from a particularbranch

Different results from similar queriesSome queries can look very similar but return very different results. The following figure shows this.



Queries that return more than you wantSuppose you want the titles of all the books. You might decide to define your query like this:

//title

This query does return all titles of books, but it also returns the title of a magazine. This query instructs the XPath processorto start at the root node, search all descendants, and return all title elements. In bookstore.xml, this means that thequery returns the title of the magazine in addition to the titles of books. In some other document, if all titles are containedin book elements, this query returns exactly what you want.

To query and obtain only the titles of books, you can use either of the following queries. They obtain identical results.However, the first query runs faster.

/bookstore/book/title//book/title code

The first query runs faster because it uses the child axis, while the second query uses the descendent axis. In general,the simpler axes, such as child, self , parent , and ancestor, are faster than the more complicated axes, such asdescendent, preceding, following , preceding-sibling , and following-sibling . This is especially true for largedocuments. Whenever possible, use a simpler axis.


Queries that return more than you want

Specifying attributes in queriesTo specify an attribute name in a query, precede the attribute name with an at sign (@). The XPath processor treats elementsand attributes in the same way wherever possible. For example:

//@style

This query returns the style attributes associated with the magazine, the three books, and the my:book element. That is,it returns all the style attributes in the document. It does not return the elements that contain the attributes.

The following is another query that includes an attribute:

/bookstore/book/@style

This query returns the three style attributes for the three book elements.

The following query returns the style attribute of the context node:

@style

If the context node does not have a style attribute, the result set is empty.

The next query returns the exchange attribute on price elements in the current context:

price/@exchange

Following is an example that is not valid because attributes cannot have subelements:

price/@exchange/total

Following is a query that finds the style attribute for all book elements in the document:

//book/@style

You can use an at sign (@) and asterisk (*) together to retrieve a collection of attributes. This can be useful for applicationsthat treat attributes as fields in a record. For example, the following query finds all attributes in the current context:

@*

Restrictions on querying attributes include:

• Attributes cannot contain subelements. Consequently, you cannot apply a path operator to an attribute. If you try to, youreceive a syntax error.

• Attributes are inherently unordered. Consequently, you cannot apply a position number to an attribute. If you try to, youreceive a syntax error.



Filtering the results of XPath queriesSometimes you want to retrieve only those elements that meet a certain condition. For example, you might want informationabout a particular book. In this case, you can include a filter in your query. You enclose filters in brackets ( [] ).

The following figure shows how the XPath Helper interprets a query with a filter:

This query checks each book element to determine whether it has a title child element whose value is History ofTrenton. If it does, the query returns the book element. Using the sample data, this query returns the second book element.

Related reference

"How XPath Helper evaluates a filter" on page 146

"Multiple filters" on page 149

" Filters and attributes " on page 150

"Quotation marks in filters" on page 148

" Filter examples " on page 147


Filtering the results of XPath queries

How XPath Helper evaluates a filter

You can apply constraints and branching to a query by specifying a filter clause. The filter contains a query, which is calledthe subquery. The subquery evaluates to a Boolean value. The XPath Helper tests each element in the current context tosee if it satisfies the subquery. The result includes only those elements that test true for the subquery.

The XPath Helper always evaluates filters with respect to a context. For example, the expression book[author] means forevery book element that is found in the current context, determine whether the book element contains an author element.For example, the following query returns all books in the current context that contain at least one excerpt:

book[excerpt]

The following query returns all titles of books in the current context that have at least one excerpt:

book[excerpt]/title

An important point to remember is that the query returns the rightmost element that is not in the filter. The following queryreturns book elements:

/bookstore/book[title="History of Trenton"]

The next query returns title elements:

/bookstore/book[title=/bookstore/book/title[. ="History of Trenton"] "History of Trenton"]

This query finds all title elements that are in book elements. It tests each title element to determine if its value is "Historyof Trenton". The query returns any title elements for which the result of the test is true. The result looks like this:

<xlnxql:result xlnxql:count="1"xlnxql:query="/bookstore/xmlns:my="http://www.placeholder-name-here.com/schema/">xmlns:xlnxql="http://www.sonicsoftware.com/DXE/namespaces/query"

<title>History of Trenton</title></xlnxql:result>



Filter examples

Following is another example of a query with a filter clause. This query returns book elements if the price of the book isgreater than 25 dollars:

/bookstore/book[price > 25]

The next query returns author elements if the author has a degree:

//author[degree]

The next query returns the date attributes that match "3/1/00" :

//@date[.="3/1/00"]

The next query returns manufacturer elements in the current context for which the rwdrive attribute of the model is thesame as the vendor attribute of the manufacturer :

manufacturer[model/@rwdrive = @vendor]



Quotation marks in filters

Suppose you define the following filter:

[title="History of Trenton"]

If you need to specify this filter as part of an attribute value, use single quotation marks instead of double quotation marks.This is because the attribute value itself is (usually) inside double quotation marks. For example:

<xsl:value-of select="/bookstore/book[title='History of Trenton']"

Strings within an expression may contain special characters such as [, {, &, `, /, and others, as long as the entire stringis enclosed in double quotes ("). When the string itself contains double quotes, you may enclose it in single quotes (').When a string contains both single and double quotes, you must handle these segments of the string as if they were individualphrases, and concatenate them.



Multiple filters

You can specify any number of filters in any level of a query expression. Empty filters ([ ]) are not allowed.

A query that contains one or more filters returns the rightmost element that is not in a filter clause. For example:

book[excerpt]/author[degree]

The previous query returns author elements. It does not return degree elements. To be exact, this query returns all authorswho have at least one degree if the author is of a book for which the document contains at least one excerpt. In other words,for all books in the current context that have excerpts, this query finds all authors with degrees.

The following query finds each book child of the current context that has an author with at least one degree:

book[author/degree]

The following query returns all book children in the current context that have an excerpt and a title:

book[excerpt][title]



Filters and attributes

The following query finds all child elements of the current context with specialty attributes:

*[@specialty]

The following query returns all book children in the current context with style attributes:

book[@style]

The following query finds all book child elements in the current context in which the value of the style attribute of thebook is equal to the value of the specialty attribute of the bookstore element:

book[/bookstore/@specialty = @style]



Using wildcards in queriesIn a query, you can include an asterisk (*) to represent all elements. For example:

/bookstore/book/*

This query searches for all book elements in bookstore. For each book element, this query returns all child elements thatthe book element contains.

The * collection returns all elements that are children of the context node, regardless of their tag names.

The next query finds all last-name elements that are grandchildren of book elements in the current context:

book/*/last-name

The following query returns the grandchild elements of the current context:

*/*

Usually, the asterisk (*) returns only elements. It does not return processing instructions, attributes, or comments, nor doesit include attributes or comments when it maintains a count of nodes. For example, the following query returns titleelements. It does not return style attributes.

/bookstore/book/*[1]

Wildcards in strings are not allowed. For example, you cannot define a query such as the following:

/bookstore/book[author=" A* "]

To use a wildcard for attributes, you can specify @*. For example:

/bookstore/book/@*

For each book element, this query returns all attributes. It does not return any elements.


Using wildcards in queries

Calling functions in queriesThe XPath Helper provides many functions that you can call in a query. The following examples give you a sense of howfunctions in queries work. For a complete list of the functions you can call in a query, see XPath functions quickreference on page 234.

Following is a query that returns a number that indicates how many book elements are in the document:

count(//book)

In format descriptions, a question mark (?) that follows an argument indicates that the argument is optional. For example:

string substring(string, number, number ?)

This function returns a string. The name of the function is substring. This function takes two required arguments (a stringfollowed by a number) and one optional argument (a number).



Case sensitivity and blank spaces in queriesQueries are case sensitive. This applies to every part of the query, including operators, strings, element and attribute names,and function names.

For example, if you enter this query:

/Bookstore

it returns an empty set because the name of the document element is bookstore and not Bookstore.

Blank spaces in queries are not significant unless they appear within quotation marks.


Case sensitivity and blank spaces in queries

Precedence of query operatorsThe following table lists operators in order of precedence, highest to lowest; multiple operators on the same row have thesame precedence.

XPath Operators in Decreasing PrecedenceProduction

( )Grouping

[ ]Filter

-Unary minus

*, div, modMultiplication

+, -Addition

&= != < <= > >=Relational (comparison)

|Union

notNegation

andConjunction

orDisjunction



Specifying nodes to evaluateThe following topics contain information about evaluating nodes with XPath:

Related reference

"Using context operators" on page 156

"Supported XPath axes " on page 164

"Specifying an axis in a query" on page 163

"Examples of XPath expression results" on page 162

"Starting at the context node" on page 157

"Starting at the root node" on page 158

"Descending along branches" on page 159

"Specifying children or descendants of parent nodes" on page 161

"Explicitly specifying the current context" on page 160


Specifying nodes to evaluate

Using context operatorsTo use the context operators, it is important to understand the following terms.

The axis is a list of nodes in relation to the context node.

For example, the ancestor axis contains the ancestor nodes of the context node. The child axis contains the immediatechildren of the context node. See Specifying an axis in a query on page 163.

The context nNode is the node the XPath helper is currently looking at.

The context node changes as the XPath Helper evaluates a query. If you pass a document to the XPath helper, the root nodeis the initial context node. If you pass a node to the XPath helper, the node that you pass is the initial context node. Duringevaluation of a query, the initial context node is also the current node.

The following query looks for all child author elements in the current context:

author

This query is the name of the element you want to search for. If the context node is one of the book elements, this queryreturns one author.

The current node the first context node that the XPath Helper uses when it starts to execute the query. The current noderemains the same through the query evaluation.

If you pass a document to the XPath helper, the root node is the current node. If you pass a node to the XPath helper, thatnode is the current node.

A document element contains all other elements. The document element is an immediate child of the root node. When youobtain the document element of a document, you obtain all marked-up text in that document.

A filter is a restriction on the set of nodes to be returned.

For example, the filter in the following query restricts the result set to book elements that contain at least one excerptelement.

book[excerpt]

A Location path expression has the following format:

[/]LocationStep[/LocationStep]...

XPath location expressions consist of one or more location steps.

A location step has the following format:

axis ::]node_test [[filter ] [filter ]...]

A node test returns nodes of a particular type or nodes with a particular name. For example, a node test might return allcomment nodes, or all book elements.

The root node is the root of the document tree. The document element node for a document is a child of the root node. Theroot node also has as children processing instructions and comment nodes for processing instructions and comments thatoccur in the prolog and after the end of the document element.

Related reference


"Specifying nodes to evaluate " on page 155



Starting at the context nodeThe following query looks for all child author elements in the current context:

author

This query is simply the name of the element you want to search for. If the context node is any one of the book elements,this query returns one author element. If the context node is any other node, this query returns the empty set.

Related reference



Starting at the context node

Starting at the root nodeA root node is the topmost node in the tree that represents the contents of an XML document. The root node can containcomments, a declaration, and processing instructions, as well as the document element. The document element is theelement that contains all other elements; that is, the document element contains elements that are in the document butthat are not immediate children of the root node.

To specify that the XPath Helper should start at the root node when it evaluates nodes for a query, insert a forward slash(/) at the beginning of the query.

In an XML document, there is no text that corresponds to the root node. Externally, a root node is really a concept. Internally,there are data structures that represent this concept, but there is no text that you can point to and call a root node.

The following query instructs the XPath Helper to start at the root node, as indicated by the forward slash at the beginningof the query.

/bookstore

This query searches the children of the root node for a bookstore element. Because the name of the document elementis bookstore, the query returns it. If the name of the document element is not bookstore, this query returns an emptyset.

The following query returns the entire document, starting with the root node. As you can see, the entire query is just aforward slash:

/

This query returns everything - comments, declarations, processing instructions, the document element, and any elements,attributes, comments, and processing instructions that the document element contains.

Related reference




Descending along branchesSometimes you want the XPath Helper to evaluate all nodes that are descendants of a node and not just the immediatechildren of that node. This amounts to operating on a branch of the tree that forms the document.

To specify the evaluation of descendants that starts at the root node, insert two forward slashes (//) at the beginning of aquery.

To specify the evaluation of descendants that starts at the context node, insert a dot and two forward slashes (.//) at thebeginning of the query.

Following is a query that finds all last-name elements anywhere in the current document:

//last-name

Suppose the context node is the first book element in the document. The following query returns a single last-name elementbecause it starts its search in the current context:

.//last-name

At the beginning of a query, / or // instructs the XPath Helper to begin to evaluate nodes at the root node. However, betweentag names, / is a separator, and // is an abbreviation for the descendant-or-self axis.

The // selects from all descendants of the context node set. For example:

book//award

This query searches the current context for book child elements that contain award elements. If the bookstore elementis the context node, this query returns the two award elements that are in the document.

For the sample bookstore data, the following two queries are equivalent. Both return all last-name elements in thedocument.

//last-name //author//last-name

The first query returns all last-name elements in the sample document or in any XML document. The second query returnsall last-name elements that are descendants of author elements. In the sample data, last-name elements are alwaysdescendants of author elements, so this query returns all last-name elements in the document. But in another XMLdocument, there might be last-name elements that are not descendants of author elements. In that case, the query wouldnot return those last-name elements.

Note// is useful when the exact structure is unknown. If you know the structure of your document, avoid the use of //.A query that contains // is slower than a query with an explicit path.

Related reference



Descending along branches

Explicitly specifying the current contextIf you want to explicitly specify the current context node, place a dot and a forward slash (./) in front of the query. Thisconstruct typically appears in queries that contain filters. The following two queries are equivalent:

./author

author

Remember, if you specify the name of an element as a complete query (for example, foo), you obtain only the foo elementsthat are children of the current context node. You do not necessarily obtain all foo elements in the document.

You can also specify the dot notation (.) to indicate that you want the XPath processor to process each node in the currentcontext. For example:

//title [. = "History of Trenton"]

In this example, the XPath processor finds all title elements. The dot indicates the context node. This causes the XPathprocessor to check each title in turn to determine whether its string value is History of Trenton.

Related reference




Specifying children or descendants of parent nodesSometimes you want a query to return information about a sibling of the context node. One way to obtain a sibling is todefine a query that navigates up to the parent and then down to the sibling.

For example, suppose the context node is the first author element. You want to find out the title associated with thisauthor. The following query returns the associated title element:

../title

The double dot (..) at the beginning of the query instructs the XPath processor to select the parent of the context node.This query returns the title elements that are children of the first book element, which is the parent of the first authorelement. In the bookstore.xml document, there is only one such title element.

Now suppose that the context node is still the first author element and you want to obtain the style attribute for the bookthat contains this author. The following query does this:

../@style

The double dot notation need not appear at the beginning of a query. It can appear anywhere in a query string, just like thedot notation.

Related reference



Specifying children or descendants of parent nodes

Examples of XPath expression resultsThe following table contains examples of XPath Expression results:

ResultExpression

Returns the document element of the document if it is an a element/a

Returns all b elements that are immediate children of the document element, which is the a element/a/b

Returns all a elements in the document//a

Returns all b elements that are immediate children of a elements that are anywhere in the document//a/b

Returns all a elements that are immediate children of the context nodea or ./a

Returns all b elements that are immediate children of a elements that are immediate children of the context

node

a/b

Returns all b elements that descend from a elements that are immediate children of the context nodea//b

Returns all a elements in the document tree branch that starts with the context node.//a

Returns all a elements in the document tree branch that are children of the parent node of the context node.../a

Related reference




Specifying an axis in a queryFor a list of XPath abbreviations, see Abbreviations in XPath expressions on page 238.

You can use axis syntax to specify a location path in a query. An axis specifies the tree relationship between the nodesselected by an expression and the context node. Axis names are defined in Supported XPath axes on page 164. The syntaxfor specifying an axis in a query is as follows:

axis_name::node_test

A node test is a simpleExpression that tests for a specified node type or node name. For example:

• node() matches any type of node.

• text() matches text or CDATA nodes.

• comment() matches comment nodes.

• processing-instruction() matches any processing instruction.

• processing-instruction(name ) matches processing instructions whose target is name.

• name matches elements or attributes whose name is name.

• * matches any elements or any attributes.

In addition, you can follow the node test with any number of filters.

Related reference


"Supported XPath axes " on page 164


"Running sample queries with XPath Helper" on page 130


Specifying an axis in a query

Supported XPath axesThe XPath Helper supports all XPath axes:

Child axis

The child axis contains the children of the context node. The following examples select the book children of the contextnode:

child::book

book

If the context node is the bookstore element, each of these queries return the book elements in bookstore.xml. Whenyou do not specify an axis, the child axis is assumed.

Descendant axis

The descendant axis contains the descendants of the context node. A descendant is a child or a child of a child, and soon. The descendant axis never contains attribute nodes. The following example selects the first-name element descendantsof the context node:

descendant::first-name

If the context node is the bookstore element, this query returns all first-name elements in the document. If the contextnode is the first publication element, this query returns the first-name element that is in the publication element.

Parent axis

The parent axis contains the parent of the context node, if there is one. The following example selects the parent of thecontext node if it is a title element:

parent::title

If the first title element in bookstore.xml is the context node, this query returns the first book element.

Note that dot dot (code>.. ) is equivalent to parent::node() .

Ancestor axis

The ancestor axis contains the ancestors of the context node. The ancestors of the context node consist of the parent ofthe context node and the parent's parent, and so on. The ancestor axis always includes the root node, unless the contextnode is the root node. The following example selects the book ancestors of the context node:

ancestor::book

If the context node is the first title element in bookstore.xml , this query returns the first book element.

Following-sibling axis

The following-sibling axis contains all the siblings of the context node that come after the context node in documentorder. If the context node is an attribute node or namespace node, the following-sibling axis is empty. The followingexample selects the next book sibling of the context node:

following-sibling::book[position()=1]

If the context node is the first book element in bookstore.xml, this query returns the second book element.

Preceding-sibling axis



The preceding-sibling axis contains all the siblings of the context node that precede the context node in documentorder. If the context node is an attribute node or namespace node, the preceding-sibling axis is empty. The followingexample selects the closest previous book sibling of the context node:

preceding-sibling::book[position()=1]

If the context node is the third book element in bookstore.xml , this query returns the second book element. If the contextnode is the first book element, this query returns the empty set.

Following Axis

The following axis contains the nodes that follow the context node in document order. This can include

• Following siblings of the context node

• Descendants of following siblings of the context node

• Following siblings of ancestor nodes

• Descendants of following siblings of ancestor nodes

The following axis never includes

• Ancestors or descendants of the context node

• Attribute nodes

• Namespace nodes

The following example selects the book elements that are following siblings of the context node and that follow the contextnode in document order:

following::book

If the context node is the first book element, this query returns the last three book elements. If the context node is thesecond book element, this query returns only the third and fourth book elements.

Preceding axis

The preceding axis contains the nodes that precede the context node in document order. This can include:

• Preceding siblings of the context node

• Descendants of preceding siblings of the context node

• Preceding siblings of ancestor nodes

• Descendants of preceding siblings of ancestor nodes

The preceding axis never includes

• Ancestors or descendants of the context node

• Attribute nodes

• Namespace nodes

The following example selects the book elements that are preceding siblings of the context node and that precede the contextnode in document order:

preceding::book


Supported XPath axes

If the third book element is the context node, this query returns the first two book elements. If the first book element is thecontext node, this query returns the empty set.

Attribute axis

The attribute axis contains the attributes of the context node. The attribute axis is empty unless the context node isan element. The following examples are equivalent. They both select the style attributes of the context node. The at sign(@) is an abbreviation for the attribute axis.

attribute::style @style

If the context node is the second book element, this query returns a style attribute whose value is textbook .

Namespace axis

The namespace axis contains the namespace nodes that are in scope for the context node. This includes namespacedeclaration attributes for the

• Context node

• Ancestors of the context node

If more than one declaration defines the same prefix, the resulting node set includes only the definition that is closest tothe context node.

If the context node is not an element, the namespace axis is empty.

For example, if an element is in the scope of three namespace declarations, its namespace axis contains three namespacedeclaration attributes.

Note that the XIS XPath Helper deviates slightly from the W3C XPath Recommendation. In the XPath Recommendation,the namespace axis contains special namespace nodes. An element contains a namespace node for each namespacedeclaration.

Self axis

The self axis contains just the context node itself. The following example selects the context node if it is a title element:

self::title

Note that dot (. ) is equivalent to self::node() .

Descendant-or-self Axis

The descendant-or-self axis contains the context node and the descendants of the context node. The following exampleselects the first-name element descendants of the context node and the context node itself if it is a first-name element:

descendant-or-self::first-name

If the context node is the first-name element that is in the author element in the second book element, this query returnsjust the context node. If the context node is the second book element, this query returns the two first-name elementscontained in the second book element.

Note that // is equivalent to descendant-or-self::node() , while //name is equivalent todescendant-or-self::node()/child::name .

Ancestor-or-self axis

The ancestor-or-self axis contains the context node and the ancestors of the context node. The ancestor-or-selfaxis always includes the root node. The following example selects the author element ancestors of the context node andthe context node itself if it is an author element:



ancestor-or-self::author

If the context node is the award element in the first book element, this query returns the first author element.

Related reference





Supported XPath axes

Axes that represent the whole XML documentThe following group of axes represent an entire XML document:

• ancestor

• preceding

• self

• following

• descendant

There is no overlap among these axes, as shown in the following figure:



Handling strings and textThe following topics contain information about searching documents with XPath:

• Finding identical strings on page 170

• Finding elements containing specified strings on page 171

• Finding substrings that occur before specified strings on page 172

• Finding substrings that occur after specified strings on page 173

• Finding substrings by position on page 174

The following topics contain information about manipulating strings:

• Concatenating strings on page 175

• Determining the number of characters in a string on page 176

• Handling white space in strings on page 177

• Replacing characters in strings on page 178

• Converting objects to strings on page 179

Related reference

"Running sample queries with XPath Helper" on page 130


Handling strings and text

Finding identical stringsIn a document, you can search for text that is an exact match with what you specify in your query. For example, considerthe following query:

//name [ . ="Lu" ]

This query finds all name elements that contain only the text Lu. It would return elements like these:

<name>Lu</name><name><firstname>Lu</firstname></name>

The same query does not return elements like these:

<name>Lu Chen</name><name><firstname>Lu</firstname><lastname>Chen</lastname></name>

The XPath Helper does not return the first name element because the comparison is between "Lu" and "Lu Chen". Thequery does not return he second name element because the XPath helper concatenates the two strings "Lu" and "Chen"before it makes the evaluation. Consequently, the comparison is between "Lu" and "LuChen". Note that the XPath Helperdoes not insert a space between text nodes that it concatenates. Searches are case sensitive. A search for "Lu" does notreturn "lu".

Related reference

" Handling strings and text " on page 169



Finding elements containing specified stringsTo obtain elements that contain a particular string, call the contains() function. The format is:

boolean contains(string, string)

The contains() function returns true if the first argument string contains the second argument string, and otherwisereturns false. For example, the following query returns all books that have a title that contains the string "Trenton":

/bookstore/book[contains(title, "Trenton")]

When the first argument is a node list, the XPath helper tests only the string value of the node in the node list that is firstin document order. Any subsequent nodes are ignored.

Related reference



Finding elements containing specified strings

Finding substrings that occur before specified stringsTo obtain a substring that appears before a string you specify, call the substring-before() function. The format is:

string substring-before(string, string)

The substring-before() function returns the substring of the first argument string that precedes the first occurrence ofthe second argument string in the first argument string. This function returns the empty string if the first argument stringdoes not contain the second argument string. For example, the following call returns "1999":

substring-before("1999/04/01","/")

Related reference




Finding substrings that occur after specified stringsTo obtain a substring that appears after a string you specify, call the substring-after() function. The format is:

string string-after(string, string)

The substring-after() function returns the substring of the first argument string that follows the first occurrence of thesecond argument string in the first argument string. This function returns the empty string if the first argument string doesnot contain the second argument string. For example, the following call returns "04/01":

substring-after("1999/04/01","/")

Related reference



Finding substrings that occur after specified strings

Finding substrings by positionTo obtain a substring that is in a particular position within its string, call the substring() function. The format is:

string substring(string, number, number?)

The substring() function returns the substring of the first argument, starting at the position specified in the secondargument, with length specified in the third argument. For example, the following returns "234":

substring("12345", 2, 3)

If you do not specify the third argument, the substring() function returns the substring starting at the position specifiedin the second argument and continuing to the end of the string. For example, the following call returns "2345":

substring("12345", 2)

Each character in the string has a numeric position. The position of the first character is 1. The position of the secondcharacter is 2, and so on. The returned substring contains those characters for which the position of the character is greaterthan or equal to the rounded second argument and, if the third argument is specified, less than the sum of the value of thesecond and third arguments. The comparisons and addition used for the preceding follow the standard IEEE 754 rules. TheXPath Helper rounds the second and third arguments as if by a call to the round() function. For example:

• substring("12345", 1.5, 2.6) returns "234"

• substring("12345", 0, 3) returns "12"

• substring("12345", 0 div 0, 3) returns ""

• substring("12345", 1, 0 div 0) returns ""

• substring("12345", -42, 1 div 0) returns "12345"

• substring("12345", -1 div 0, 1 div 0) returns ""

Related reference




Concatenating stringsTo concatenate two or more strings, call the concat() function. The format is

string concat(string, string,(string...)

The concat() function returns the concatenation of its arguments.

Related reference



Concatenating strings

Determining the number of characters in a stringTo obtain the number of characters in a string, call the string-length()function. The format is:

number string-length(string?)

The string-length()function returns the number of characters in the string. If you omit the argument, it defaults to thestring value of the context node.

Related reference




Handling white space in stringsTo strip leading and trailing white space from a string, call the normalize-space() function. The format is:

string normalize-space(string?)

The normalize-space() function removes leading and trailing white space. White space consists of spaces, tabs, newlines, and returns.

If there are consecutive internal spaces, the normalize-space() function collapses the internal spaces into one space.The normalize-space() function returns the string with the extraneous white space removed. If you omit the argument,it defaults to the string value of the context node.

Related reference



Handling white space in strings

Replacing characters in stringsTo replace characters in a string with other characters, call the translate() function. The format is:

string translate(string, string, string)

The translate() function looks for characters in the first string that are also in the second string. For each such character,the translate() function replaces the character in the first string with a character from the third string. The replacementcharacter is the character in the third string that is in the same position as the character in the second string that correspondsto the character being replaced. For example:

translate("bar", "abc","ABC")

Execution of this function returns "BAr". Following is another example:

translate("---aaa---", "abc","ABC")

Execution of this function returns "AAA". Sometimes there is a character in the second argument string with no characterat a corresponding position in the third argument string. This happens when the second argument string is longer than thethird argument string. In this case, the XPath processor removes occurrences of that character.

If a character occurs more than once in the second argument string, the first occurrence determines the replacementcharacter. If the third argument string is longer than the second argument string, the XPath processor ignores the excesscharacters.

Related reference




Converting objects to stringsIn some situations, you might want to force a string comparison. The XPath processor performs a string comparison onlywhen the operands are neither Boolean nor numeric values. If an operand is numeric or Boolean, call the string() functionon it to convert it to a string. The format of the string() function is:

string<</code> string(object<</code>?)

The string() function can convert any object to a string. If you omit the argument, it defaults to a node set with the contextnode as the only member. The string value of an element node is the concatenation of the string values of all text nodedescendants of the element node in document order.

Node sets

When the string() function converts a node set to a string, it returns the string value of the node in the node set that isfirst in document order. If the node set is empty, the string() function returns an empty string.

Numbers

The string() function converts numbers to strings as follows:

• NaN (not a number) becomes "NaN"

• Positive zero becomes "0"

• Negative zero becomes "0"

• Positive infinity becomes "Infinity"

• Negative infinity becomes "-Infinity"

• An integer becomes a sequence of digits with no leading zeros, for example, "1234". A negative integer is preceded by

a minus sign, for example, "-1234".

• A noninteger number becomes a sequence of digits with at least one digit before a decimal point and at least one digitafter a decimal point, for example, "12.34". A negative noninteger number is preceded by a minus sign, for example,

"-12.34". Leading zeros are not allowed unless there is only one to satisfy the requirement of a zero before the decimal

point. Beyond the one required digit after the decimal point, there must be as many, but only as many, more digits asare needed to uniquely distinguish the number from all other IEEE 754 numeric values.

Boolean values

The string() function converts the Boolean false value to the string "false", and the Boolean true value to the string"true".

Related reference



Converting objects to strings

Finding strings that start with a particular stringTo determine if a string starts with a particular string, specify the starts-with() function. The format is

boolean starts-with(string, string)

This function returns true if the first argument string starts with the second argument string, and otherwise returns false.



Obtaining the text contained in a nodeYou can use the string() function to obtain the text in a node. The string value of an element node is the concatenationof the string values of all text node descendants of the element node in document order. Use one of the following formats:

string string(pathExpression)pathExpression

Replace pathExpression with the path of the node or nodes that contain the text you want. This can be a rooted path or arelative path. It need not be a single node. If you do not explicitly specify the string() function, you must specifypathExpression in a context where the XPath processor must treat it as a string, for example:

/bookstore/book[title = "Trenton Revisited"]

The XPath processor obtains the text contained in each title element and compares it with "Trenton Revisited". TheXPath processor returns books with the title Trenton Revisited.


Obtaining the text contained in a node

Specifying Boolean expressions and functionsYou can specify Boolean expressions in the subqueries in filters. You specify the Boolean NOT operators like this:

• and

• or

• not

You can use parentheses to group collection specifications and operators for clarity or where the normal precedence isinadequate to express an operation.

Operators are case sensitive. Spaces are not significant. You can omit them or include them for clarity. For example, thefollowing query returns all authors who have at least one degree and one award:

author[degree and award]

The next query finds all authors who have at least one degree or award and at least one publication:

author[(degree or award) and publication]

Following is a query that finds all authors who have at least one degree and no publications:

author[degree and not(publication)]

Related reference

"Converting an object to Boolean" on page 183

"Obtaining Boolean values" on page 184

"Determining the context node language" on page 185



Converting an object to BooleanIn some situations, you might want to force a Boolean comparison. The XPath Helper performs a Boolean comparison ifeither operand is a Boolean value. Consequently, if neither operand is a Boolean value, call the boolean() function on oneoperand to convert it to a Boolean value. The XPath Helper automatically converts the other operand to a Boolean value.The format of the boolean() function is:

boolean boolean( object )

The boolean() function converts its argument to Boolean as follows:

• A number is false if and only if it is one of the following:

• Positive zero

• Negative zero

• NaN (not a number)

• A node set is false if and only if it is empty.

• A string is false if and only if its length is 0 .

The boolean() function is useful in comparisons. For example, the following query returns b elements that either containboth c and d elements as children or contain neither c nor d elements as children:

/a/b[boolean(c) = d]

This query is equivalent to the following:

/a/b [(c and d) or (not(c) and not(d))]

Related reference

"Specifying Boolean expressions and functions" on page 182


Converting an object to Boolean

Obtaining Boolean valuesTo obtain the opposite Boolean value, call the not() function. The format is:

boolean not(boolean)

The not() function returns true if its argument is false, and returns false if its argument is true. For example, thefollowing query finds all authors who have publications but no degrees or awards:

author[not(degree or award) and publication]

To obtain the value true, call the true() function. The format is:

boolean true()

The true() function returns true. To obtain the value, false, call the false() function. The format is:

boolean false()

The false() function returnsfalse.

Related reference




Determining the context node languageTo determine whether the language of the context node is the language you expect it to be, call the lang() function. Theformat is:

boolean lang(string)

The lang() function returns true or false depending on whether the language of the context node as specified by thexml:lang attribute is the same as, or is a sublanguage of, the language specified by the argument string. The language ofthe context node is determined by the value of the xml:lang attribute on the context node or, if the context node has noxml:lang attribute, by the value of the xml:lang attribute on the nearest ancestor of the context node that has an xml:langattribute.

If there is no such attribute, then lang() returns false. If there is such an attribute, lang() returns true in the followingsituations:

• The attribute value is equal to the argument string.

• The attribute value has a suffix starting with a dash (-) so that the attribute value is equal to the argument string if youignore the suffix.

In both situations, case is ignored. For example:

lang("en")

This returns true if the context node is any of these elements:

• <para xml:lang="en"/>

• <div xml:lang="en"><para/></div>

• <para xml:lang="EN"/>

• <para xml:lang="en-us"/>

Related reference



Determining the context node language

Specifying number operations and functionsThe following topics provide information about arithmetic operations and number functions in queries:

• Performing arithmetic operations on page 187

• Converting an object to a number on page 188

• Obtaining the sum of the values in a node set on page 189

• Obtaining the largest, smallest, or closest number on page 190



Performing arithmetic operationsIn queries, a number represents a floating-point number. A number can have any double-precision 64-bit format IEEE 754value. This includes:

• A special not-a-number (NaN) value

• Positive and negative infinity

• Positive and negative zero

The numeric operators convert their operands to numbers as if by calling the number() function. See Converting an Objectto a Number.

You can use the following arithmetic operators in queries:

• + performs addition

• - performs subtraction

• XML allows hyphens (-) in names. Consequently, the subtraction operator (-) typically needs to be preceded by white

space. For example, foo-bar evaluates to a node set that contains the child elements named foo-bar. However, foo

- bar evaluates to the difference between the result of converting the string value of the first foo child element to a

number and the result of converting the string value of the first bar child to a number.

• * performs multiplication

• mod returns the remainder from a truncating division. For example:

• 5 mod 2 returns 1.

• 5 mod -2 returns 1.

• -5 mod 2 returns -1.

• -5 mod -2 returns -1.

The mod operator is the same as the % operator in Java and ECMAScript. But it does not perform the same operationas the IEEE remainder operation, which returns the remainder from a rounding division.

• div performs floating-point division according to IEEE 754.

Related reference

" Specifying number operations and functions " on page 186


Performing arithmetic operations

Converting an object to a numberIn some situations, you might want to force a numeric comparison. The XPath processor performs a numeric comparisonif either operand is numeric and neither is Boolean. (If one operand is Boolean, the XPath processor converts the other toBoolean and performs a Boolean comparison.) However, if neither operand is a numeric or Boolean value, you can call thenumber() function on one operand to convert it to a numeric value. The XPath processor automatically converts the otheroperand to a numeric value.

To perform a numeric comparison, you must call the number() function to convert a Boolean operand, if there is one, to anumeric value. The format of the number() function is:

number number(object?)

If you omit the argument, the value of the argument defaults to a node set with the context node as its only member. Thefollowing table shows how the number() function converts its argument to a number:

Converted valueArgument

IEEE 754 number that is nearest to the mathematical value representedby the string.

String that consists of optional white space followedby an optional minus sign followed by a numberfollowed by white space

NaN (not a number)Any other string

1Boolean true

0Boolean false

First the XPath processor converts the node set to a concatenated stringas if by a call to the string() function for the first node in the node

Node set

set, in document order. The XPath processor then converts this stringthe same way as it would a string argument.

Related reference




Obtaining the sum of the values in a node setTo obtain the sum of the values of the nodes in a set, call the sum() function. The format is:

number sum(node-set)

For each node in the argument node-set, the XPath processor converts the string value of the node to a number. Thesum() function returns the sum of these numbers.

Related reference



Obtaining the sum of the values in a node set

Obtaining the largest, smallest, or closest numberTo obtain the largest integer that is not greater than a particular number, call the floor() function. The format is:

number floor(number)

The floor() function returns the largest (closest to positive infinity) number that is not greater than the argument and thatis an integer. For example:

• floor(5.3) returns 5

• floor(-5.3) returns -6

To obtain the smallest integer that is not less than a particular number, call the ceiling() function. The format is:

number ceiling(number)

Related reference




Comparing valuesThe following topics contain information about comparing values in queries:

• About comparison operators on page 192

• How XPath Helper evaluates comparisons on page 193

• Comparing node sets on page 195

• Comparing single values with <=, <, >, and >= on page 198

• Comparing single values with = and != on page 197

• Priority of object types in comparisons on page 194

• Examples of comparisons on page 199

• Comparing Boolean values with = and != on page 196


Comparing values

About comparison operatorsThe following table lists the comparison operators you can specify:

DescriptionOperator

Equality=

Inequality!=

Less than<

Less than or equal<=

Greater than>

Greater than or equal>=

You can specify single or double quotation marks (' or ") as string delimiters in expressions. This makes it easier to constructand pass queries from within scripting languages.

Related reference

" Comparing values " on page 191



How XPath Helper evaluates comparisonsA query can compare values of elements. For example:

last-name [. = "foo"]

The XPath Helper compares the value of each last-name element in the current context with the value "foo". The resultof each comparison is a Boolean value. The XPath Helper returns the last-name elements for which the comparison yieldstrue.

The XPath Helper evaluates filters with respect to a context. For example, the expression book[author] means for everybook element that is found, determine whether it has an author child element. Likewise, book[author = "Bob"] meansfor every book element that is found, determine whether it contains an author child element whose value is "Bob".

Comparisons are case sensitive. For example, "Bob" and "bob" are not considered to be equal.

Remember that comparisons return Boolean values. For example:

/bookstore/book/author/last-name="Bob"

You might think that this query returns authors whose last name is "Bob". But this is not the case. This query returns asingle Boolean value. It tests each last-name element to determine if its value is "Bob". As soon as the XPath Helper findsa last-name element that tests true, it returns true. If no nodes test true, this query returns false.

To obtain author elements whose last name is "Bob", enclose the comparison in a filter as follows:

/bookstore/book/author[last-name="Bob"]

Related reference



How XPath Helper evaluates comparisons

Priority of object types in comparisonsWhen the XPath Helper performs a comparison, if either operand is a Boolean value, the XPath Helper automatically convertsthe other operand to a Boolean value, if necessary, and makes a Boolean comparison.

If either operand is numeric and neither operand is Boolean, the XPath Helper automatically converts the other operand toa numeric value, if necessary, and performs a numeric comparison.

If neither operand is numeric or Boolean, the XPath helper performs a string comparison.

Related tasks




Comparing node setsYou can compare:

• Two node sets— Suppose the objects you want to compare are both node sets. The result is true only in the followingcase. There is a node in the first node set and a node in the second node set such that the result of performing a comparisonon the values of the two nodes is true. For string values, the comparison can be = or !=. For numeric values, the

comparison can also be <, >, <=, or >=.

• Node set and a number— Now suppose one object to be compared is a node set and the other is a number. The XPathHelper searches for a node in the node set that yields a true result when its number value is compared with the numberthat is not in the node set. If necessary, the XPath Helper uses the number() function to convert values to numeric values.

If and only if the XPath Helper finds such a node, the result is true.

• Node set and a string— Sometimes you want to compare a node set with a string. The XPath Helper searches for a nodein the node set that yields a true result when its string value is compared with the string that is not in the node set. Ifnecessary, the XPath Helper uses the string() function to convert values to string values. If and only if the XPath Helper

finds such a node, the result is true.

• Node set and a Boolean value— Finally, suppose you want to compare a node set with a Boolean value. This tests trueif and only if the result of performing the comparison on the Boolean value and on the result of converting the node setto a Boolean value using the boolean() function is true.

Related reference



Comparing node sets

Comparing Boolean values with = and !=You can use the = or != operator to compare Boolean values. If you try to use any other operator to compare Boolean values,you receive an error.

Related reference




Comparing single values with = and !=When neither object to be compared is a node set and the operator is = or !=, the XPath Helper compares the objects byconverting them to a common type and then comparing them. The XPath Helper converts the objects to a common type asfollows:

• If at least one object to be compared is Boolean, the XPath Helper converts the other object to Boolean as if by applyingthe boolean() function.

• If at least one object to be compared is a number, and neither is Boolean, the XPath Helper converts the nonnumberobject to a number as if by applying the number() function.

If the objects to be compared are neither Boolean nor numeric, the XPath Helper compares the string values of the objectsas if by applying the string() function to each object.

The = comparison returns true if and only if the objects are equal. The != comparison returns true if and only if the objectsare not equal. Numbers are compared for equality according to IEEE 754. Two Boolean values are equal if either both aretrue or both are false. Two strings are equal if and only if they both consist of the same sequence of Universal CharacterSet (UCS) characters.

Related reference



Comparing single values with = and !=

Comparing single values with <=, <, >, and >=When neither object to be compared is a node set and the operator is <=, <, >=, or >, the XPath helper performs thecomparison by converting both objects to numbers and comparing the numbers according to IEEE 754.

True if and only ifComparison

The first number is less than the second number.<

The first number is less than or equal to the second number.<=

The first number is greater than the second number.>

The first number is greater than or equal to the second number.>=

The XPath Helper always evaluates these comparisons in terms of numbers. You cannot use the less than and greater thanoperators to order strings. This is especially important to remember when you compare a number with a string. For example,suppose you want to evaluate the expression

a < "foo"

The return value is always false. This is because number("foo") returns NaN, and the resulting comparison, shown below,is always false.

a < NaN

Related reference

Comparing values on page 191



Examples of comparisonsThe following query finds all authors whose last name is Bob:

author[last-name = "Bob"]

The next query finds authors whose degrees are not from Harvard. Again, the queries are equivalent:

author/degree[@from != "Harvard"]

The following query returns prices that are greater than 20 dollars. This assumes that the current context contains one ormore price elements.

price [. > 20]

Related reference



Examples of comparisons

Finding a particular nodeTo find a specific node within a set of nodes, enclose an integer within brackets([]).The integer indicates the position of thenode relative to its parent.

The following topics contain information about finding nodes:

• About node positions on page 201

• Determining the position number of a node on page 202

• Positions in relation to parent nodes on page 203

• Finding nodes relative to the last node in a set on page 204

• Finding multiple nodes on page 205

• Examples specifying positions on page 205

• Finding the first node that meets a condition on page 206

• Finding an element with a particular ID on page 207

• Finding types of nodes with node tests on page 212

• Finding an element with a particular key on page 214

Related reference

" About the document object " on page 213



About node positionsTo find a specific node within a set of nodes, enclose an integer within brackets ( [ ] ). The integer indicates the positionof the node relative to its parent.

The node positions for a node set start with 1. Evaluation of the position number is always based on document order. Forexample, the following query returns the first author element in the current context:

author[1]

The next query finds the author elements (in the current context) that contain a first-name element. The query returnsthe third such author element.

(author[first-name])[position()=3]

When you specify an integer in brackets, it is equivalent to calling the position() function. For example, the followingqueries both return the third y child element of each x child element in the current context:

x/y[3]x/y[position()=3]

NoteIf you do not know the position of the node you want, a call to the position() function might help you. (SeeDetermining the position number of a node on page 202.)

The return value of the position() function depends on the specified axis. For example, suppose the axis is one of thereverse axes, such as preceding, ancestor, or preceding-sibling. The position() function returns the nth one inreverse document order that falls in the specified axis.

Related reference

" Finding a particular node " on page 200


About node positions

Determining the position number of a nodeThe position() function returns an integer that indicates the position of the node within the parent. Positions start with1; a node with a position of 1 is always the first node in the collection.

For example, the following query returns the first three degree elements in the document:

(//degree)[position() < 4]

The next query finds the first two book children in the current context:

book[position() <= 2]

The XPath processor executes the position() function with respect to the parent node. Consider the following data:

<x><y/><y/>

</x><x><y/><y/>

</x>

The following expression returns the first y element contained in each x element:

x/y[position() = 1]

Related tasks




Positions in relation to parent nodesPositions are relative to the parent. Consider the following data, which has line numbers on the left for explanation only.

1 <x>2 <z>3 <z/>4 </x>5 <x>6 <y>7 <y/>8 </x>9 <x>10 <y>11 <y/>12 </x>

The following query returns the first y element contained in each x element. It returns the elements on lines 6 and 10. TheXPath processor finds all x elements. For each x element, the XPath processor then returns the first y element it finds.

x/y[1]

The next query returns the first y element that is contained in an x element that is in the context node set. It returns theelement on line 6. The XPath processor finds all x elements that contain y elements. The XPath processor then returns thefirst y element in that set.

(x/y)[1]

The next query returns the empty set. The XPath processor finds the first x element. It then searches that first x elementfor the first y . Because the first x element does not contain a y element, this query returns the empty set.

x[1]/y[1]

Related reference



Positions in relation to parent nodes

Finding nodes relative to the last node in a setTo obtain nodes relative to the last node in the set, use the position() and last() functions with arithmetic. For example,the following queries both obtain the last author element in the current context:

author [position() = last()]author [last()]

The following queries both return the next-to-last author element:

author [position() = last() - 1]author [last() - 1]

For information about position(), see Determining the position number of a node on page 202. For information aboutlast(), see Determining the context size on page 225.

Related reference




Finding multiple nodesTo obtain several nodes in one operation, use the and or the or operator with the position() and last() functions. Forexample, the following query returns the first and the last author nodes in the current context:

author [(position() = 1) or (position() = last())]

You can also specify a range of nodes. For example, the following query returns the second, third, and fourth authorelements:

author [(position() >= 2) and ( position() <= 4)]

To obtain a range of nodes, m to n, relative to the last node, use the following format:

(m <= position()) and (position() <= n)

For example, the following query obtains the last five nodes in the current context:

author [(last() - 4) <= position()) and (position() <= last())]

The following query finds the first and fourth author elements:

author [(position() = 4) or (position() = 1)]

The following query finds the first, the third through the fifth, and the last author elements:

author [(position() = 1) or (position() >= 3 and position() <= 5) or (position() = last())]

The XPath processor removes duplicate values. For the previous query, if there are only five elements in the collection, thequery returns only one copy of the fifth element.

The following example finds all author elements in which the first degree is a Ph.D.:

author[degree[1] = "Ph.D."]

Related reference



Finding multiple nodes

Finding the first node that meets a conditionSuppose you want to obtain from a collection the first node that meets a certain condition. For example, you want the firstbook whose author's last name is Bob. You can specify the following query:

(//book[author/last-name="Bob"])[position()=1]

When the XPath Helper evaluates this expression, it creates a collection of book elements where the author's last name isBob. The XPath Helper then returns the first node in this collection.

The following two expressions appear to also return the first book whose author's last name is Bob, but they do not. Instead,these queries both return a book whose author's last name is Bob only if that book is the first book in the document.

//book[author/first-name="Bob"][position()=1]//book[author/first-name="Bob" and position() = 1]

Related reference




Finding an element with a particular IDTo obtain the element that has a particular identifier (ID), the DTD must specify an attribute for that element. The type ofthis attribute must be ID. The name of the attribute is not significant, though it is typically id. If there is such an attribute,you can call the id() function to obtain the element with a particular ID. The format is:

node-set id(object)

The id() function evaluates to a set. It ignores the context node set except to evaluate the function's argument. The resultset contains an element node that has an attribute of type ID whose value is identical to the string the object argumentevaluates to. The element node can appear anywhere in the document that is being queried.

id("special")

This query searches for an element that has an attribute whose

• Type is ID

• Value is special

Related reference



Finding an element with a particular ID

The id() functionWhen the id() function's argument is of type node-set, the result is the union of the results of applying id() to the stringvalue of each of the nodes in the argument node set.

When the argument of id() is any other type, the XPath helper converts the argument to a string as if by a call to thestring() function. The XPath Helper splits the string into a white-space-separated list of tokens. The result is a node setthat contains the elements in the same document as the context node that have a unique ID equal to any of the tokens inthe list.

Related reference




Unique IDsAn element node can have a unique ID. This is the value of the attribute that is declared in the DTD as type ID. No twoelements in a document can have the same unique ID. If an XML processor reports two elements in a document as havingthe same unique ID (which is possible only if the document is invalid), the second element is treated as not having a uniqueID.

If a document does not have a DTD, the id() function always returns an empty node list.

Related reference



Unique IDs

Generating temporary IDs for nodesYou can generate temporary IDs for nodes with the generate-id() function.

Caution: The ID generated by the generate-id() function is not an object ID. The value generated by the generate-id()function is guaranteed to be the same only during an XSL transformation. If the source document changes, the value forthis ID can change.

The format for the generate-id() function is as follows:

string generate-id(node-set?)

The generate-id() function returns a string that uniquely identifies the node in node-setthat is first in document order.This string starts with xln and ends with eight hexadecimal digits. Syntactically, the string is an XML name.

If the node-set argument is empty, the generate-id() function returns an empty string. If you omit the node-set argument,the generate-id() function generates a temporary ID for the context node.

Related reference




Obtaining particular node types with node testsThe following topics contain information about node tests:

• Node tests on page 212

• About the document object on page 213

• Finding an element with a particular key on page 214


Obtaining particular node types with node tests

Node testsNode tests enable you to obtain nodes according to their type. Node test is an XPath term. Although a node test looks likea function, it is not a function.

You can use these node tests with filters and position specifiers. They resolve to the set of children of the context node thatmeets the restrictions you specify. The following table lists the node tests and the type of node each returns.

Node type returnedNode test

Comment nodes.comment()

All nonattribute nodes.node()

Processing instruction nodes. The processing-instruction() node test selects

all processing instructions. When this node test specifies a literal argument, it

processing-instruction("name")

selects any processing instruction that has a name equal to the value of theargument. If there is no argument, this node test selects all processing instructions.

Text nodes and CDATA nodes.text()

For each p element in the current context, the following query returns its second text child node:

p/text()[2]

Following is a query that finds the third comment child in each foo element anywhere in the document:

//foo/comment()[3]

Related reference

" Obtaining particular node types with node tests " on page 211



About the document objectIn the Document Object Model (DOM), a document contains comments, processing instructions, and declarations, as wellas the document element. As in XPath, the root node is the root of the DOM tree, and the root node is not the same as thedocument element. This allows comments, declarations, and processing instructions at the document entity level.

For example, the following query finds all comments at the document entity level. In other words, it finds all comments thatare immediate children of the root node.

/comment()

This query returns the comment at the beginning of the bookstore.xml file:

"This file represents a fragment of a book store inventory database."

A query like the following returns all the comments in a document:

//comment()

The following query returns the third comment in the document:

(//comment()) [3]

Related reference



About the document object

Finding an element with a particular keyThe key() function, defined in the XSLT Recommendation, obtains the node whose key value matches the specified key.The format is:

node-set key(string, object)

The first argument specifies the name of the key. The value of this argument must be a qualified name. The second argumentspecifies the node or nodes to examine. When the second argument is a node set, the result is the union of the results ofapplying the key() function to the string value of each of the nodes in the set. When the second argument is any othertype, the XPath Helper converts the argument to a string, as if by a call to the string() function. The key() functionreturns a node set that contains the nodes in the same document as the context node that have a value for the named keythat is equal to this string.

For example, the videos.xml document contains the following elements:

<result><actors><actor id="00000003">Jones, Tommy Lee</actor>

</actors><videos>

<video id="id1235AA0"><title>The Fugitive</title>...<actorRef>00000003</actorRef><actorRef>00000006</actorRef>...

</video>...

</videos></result>

When you display information about a video in a Web browser, you want to display the names of the actors. Because theactors are referenced only by an ID number, you create a key table in your stylesheet:

<xsl:keyname="actors"match="/result/actors/actor"use="@id"/>

This indexes all actors by their ID. To process a video, your stylesheet specifies the following:

<xsl:for-each select="actorRef"><xsl:value-of select="key('actors', .)"/></xsl:for-each>

This instructs the XPath Helper to look up the actor element in the actors key table by using the actorRef element asa key.

Related reference




Obtaining a unionSpecify the | operator to combine collection sets. For example, the following query returns all last-name elements and allfirst-name elements in the current context:

first-name | last-name

The result set can contain zero or more of each element that the | operator applies to. For example, using the previousquery, it is possible for the query to contain only first-name elements if no last-name elements are found. The followingquery finds all book elements and magazine elements in the bookstore element:

/bookstore/book | /bookstore/magazine

The next query finds all books and all authors in the current context:

book | book/author

The next query returns the first names, last names, and degrees of authors of books or magazines in the current context:

((book | magazine)/author/first-name) | (book | magazine)/author/last-name | (book |magazine)/author/degree) )

A union can appear only as the first step in a location path expression. Consequently, the following is incorrect becausethere is a union specification that is not in the first step of a location path expression.

(book | magazine)/author/(first-name | last-name | degree)

The following query finds all books for which the author's first name is Bob and all magazines with prices less than 10dollars:

/bookstore/book[author/first-name = "Bob"] | magazine[price < 10]


Obtaining a union

Obtaining information about a node or a node setThe following topics information about operations that provide details about namespaces, URI, and nodes:

• Obtaining the name of a node on page 217

• Obtaining the namespace URI on page 218

• Obtaining the local name on page 219

• Obtaining the expanded name on page 220

• Specifying wildcards with namespaces on page 221

• Examples of namespaces in queries on page 222

• Obtaining the URI for an unparsed entity on page 223

• Determining the number of nodes in a collection on page 224

• Determining the context size on page 225



Obtaining the name of a nodeThe name() function returns a string that contains the tag name of the node, including the namespace prefix, if any.

The following query returns the name of the third element in bookstore, which is "magazine".

name(/bookstore/*[3])

An asterisk ( * ) specifies a wildcard name for element names. If there are comments before the third element in the precedingexample, this query does not include them in the count.

NoteAn asterisk that is not preceded by an at sign (@ ) never returns attributes. The XPath processor does not includeattributes in node counts.

Related reference

" Obtaining information about a node or a node set " on page 216


Obtaining the name of a node

Obtaining the namespace URITo obtain the URI for a namespace, call the namespace-uri() function. The format is:

string namespace-uri(>node-set ?)

The namespace-uri() function returns the namespace URI of the expanded name of the node in the node-set argumentthat is first in document order. If the node-set argument is empty, the first node has no expanded name, or the namespaceURI of the expanded name is null , the XPath processor returns an empty string. If you omit the argument, it defaults toa node set with the context node as its only member.

Call the namespace-uri() function on element or attribute nodes. For example, the query:

/bookstore/my:book/namespace-uri()

returns the string "http://www.placeholder-name-here.com/schema/".

For any other type of node, the XPath processor always returns an empty string.

Related reference




Obtaining the local nameTo obtain the local portion of a node name, excluding the prefix, call the local-name() function. The format is:

string local-name(node-set ?)

The local-name() function returns the local part of the expanded name of the node in the node-set argument that isfirst in document order. If the node-set argument is empty or the first node has no expanded name, the function returnsan empty string. If you omit the argument, it defaults to a node set with the context node as its only member. For example,the following query returns my:book nodes:

/bookstore/my:*[local-name()="book"]

Related reference



Obtaining the local name

Obtaining the expanded nameTo obtain the expanded name of a node, call the name() function. The expanded name is the namespace prefix, if any,plus the local name. The format is

string name(node-set ?)

The name() function returns a string that represents the expanded name of the node in the node-set argument that is firstin document order. The returned string represents the expanded name with respect to the namespace declarations in effecton the node whose expanded name is being represented.

Typically, this is the name in the XML source. This need not be the case if there are namespace declarations in effect onthe node that associate multiple prefixes with the same namespace.

If the node-set argument is empty or the first node has no expanded name, the XPath processor returns an empty string.If you omit the argument, it defaults to a node set with the context node as its only member.

Except for element and attribute nodes, the string that the name() function returns is the same as the string the local-name()function returns.

Related reference




Specifying wildcards with namespacesElement and attribute names that include colons (: ) can include wildcards; that is, asterisks (* ). For example, queriescan include *:* , *:a , or a:* .

Related reference



Specifying wildcards with namespaces

Examples of namespaces in queriesThe following example finds all book elements in the current context. This query does not return any book elements thatare not in the default namespace. For example, it does not return my:book elements.

book </<code>

The next query finds all book elements with the prefix my . This query does not return unqualified book elements; that is,book elements in the default namespace.

my:book code

The following query finds all book elements with a my prefix that have an author subelement:

my:book[author]

The following query finds all elements with a my prefix that have an author subelement with a my prefix:

my:book[my:author]

The following query returns the style attribute with a my prefix for book elements in the current context:

book/@my:style

Related reference




Obtaining the URI for an unparsed entityTo obtain the URI for an unparsed entity, call the unparsed-entity-uri() function. The format is:

string unparsed-entity-uri(string)

This function returns the URI of the unparsed entity with the specified name that is in the same document as the contextnode. If there is no such entity, this function returns an empty string.

Related reference



Obtaining the URI for an unparsed entity

Determining the number of nodes in a collectionTo obtain the number of nodes in a node set, call the count() function. The format is:

number count( node-set )

The count() function returns the number of nodes in the specified set. For example, the following query finds all authorswho have more than ten publications:

//author[count(publications) > 10]

To obtain the number of nodes in the current context, call the last() function.

Related reference




Determining the context sizeTo obtain the number of nodes in the current context, call the last() function. The format is:

number last()

The last() function returns a number equal to the context size of the expression evaluation context. Essentially, the last()function returns the position number of the last node in document order for the current context. For example, the followingquery returns all books if there are three or more of them. There are three book elements in the current context. Consequently,this query returns three book elements.

bookstore/book[last() >= 3]

Related reference



Determining the context size

Using XPath expressions in stylesheetsVariables

In a query that you specify in a stylesheet, you can refer to variables that you defined elsewhere in the stylesheet. Use thefollowing format to refer to a variable:

$variable_name

In a stylesheet, you can define variables with either of the following instructions:

• xsl:param

• xsl:variable

Obtaining system properties

In a query in a stylesheet, there are three system properties for which you can obtain information:

• xsl:version returns 1.0 as the version of XSLT that the XSLT processor implements.

• xsl:vendor returns Sonic Software as the vendor of the XSLT processor.

• xsl:vendor-url returns http://www.sonicsoftware.com as the vendor URL.

To obtain this information, call the system-property() function. The format is:

object system-property(string)

The string you specify must identify one of the three properties and must be a qualified name. This function returns anobject that represents the value of the system property you specify.

Determining whether functions are available

In a query in a stylesheet, to determine whether the XPath processor supports a particular function, call thefunction-available() function. The format is

boolean function-available(string)

Specify a string that identifies the name of the function. The XPath processor returns true if it implements that function.

Obtaining the current node for the current XSLT template

In a stylesheet, the current node is the node for which the XSLT processor instantiates a template. When the XPath processorevaluates an expression during stylesheet processing, the initial context node for the expression is set to the current nodefor the stylesheet instruction that contains the expression. Because the context node can change during evaluation ofsubexpressions, it is useful to be able to retrieve, from within a subexpression, the original context node for which theexpression is being evaluated. You can use the current() function for this purpose. The format is

node-set current()

The current() function returns a node set that contains only the current node for the current template. The current()function is specified in the W3C XSLT Recommendation.

For example, the following stylesheet causes the XSLT processor to pass the bookstore node to the outer xsl:for-eachinstruction:

<xsl:stylesheetxmlns:xsl="http://www.w3.org/XSL/Transform"



version="1.0" ><xsl:template match="/"><xsl:for-each select="bookstore">

<xsl:for-each select="book[@style=current()/@specialty]"> ...

</xsl:for-each></xsl:for-each></xsl:template></xsl:stylesheet>

The bookstore node is the current node within the outer xsl:for-each instruction. Within the inner xsl:for-eachinstruction, a book node is the current node.

The current() function in the inner expression returns the bookstore element because the bookstore element is thecurrent node for the inner xsl:for-each instruction. The result of the query contains book elements if the value of theirstyle attribute is the same as the value of the specialty attribute of the bookstore element (novel).

Suppose the select attribute in the inner xsl:for-each instruction specified the dot (.) instead of the current() function:

<xsl:for-each select="book[@style=./@specialty]">

In a query, the dot specifies the context node. This query would return a book if the value of its style attribute was thesame as the value of its specialty attribute.

You can nest xsl:for-each instructions more than one level deep. In any given nested xsl:for-each instruction, thecurrent() function returns the current node for the closest enclosing xsl:for-each instruction.

Related reference

" Defining variables in stylesheets " on page 228

" Obtaining system properties when using XPath in stylesheets " on page 229

"Available functions when using XPath in stylesheets" on page 230

" Current node for the current XSLT template " on page 231


Using XPath expressions in stylesheets

Defining variables in stylesheetsIn a query that you specify in a stylesheet, you can refer to variables that you defined elsewhere in the stylesheet. Use thefollowing format to refer to a variable:

$variable_name

In a stylesheet, you can define variables with either of the following instructions:

• xsl:param

• xsl:variable

Related reference

"Using XPath expressions in stylesheets " on page 226



Obtaining system properties when using XPath in stylesheetsIn a query in a stylesheet, there are three system properties for which you can obtain information:

• xsl:version returns 1.0 as the version of XSLT that the XSLT processor implements.

• xsl:vendor returns Sonic Software as the vendor the XSLT processor.

• xsl:vendor-url returns http://www.sonicsoftware.com as the vendor URL.

To obtain this information, call the system-property() function. The format is:

object system-property(string)

The string you specify must identify one of the three properties and must be a qualified name. This function returns anobject that represents the value of the system property you specify.

Related reference



Obtaining system properties when using XPath in stylesheets

Available functions when using XPath in stylesheetsIn a query in a stylesheet, to determine whether the XPath processor supports a particular function, call thefunction-available() function. The format is

boolean function-available(string)

Specify a string that identifies the name of the function. The XPath processor returns true if it implements that function.

Related reference




Current node for the current XSLT templateIn a stylesheet, the current node is the node for which the XSLT processor instantiates a template. When the XPath processorevaluates an expression during stylesheet processing, the initial context node for the expression is set to the current nodefor the stylesheet instruction that contains the expression. Because the context node can change during evaluation ofsubexpressions, it is useful to be able to retrieve, from within a subexpression, the original context node for which theexpression is being evaluated. You can use the current() function for this purpose. The format is

node-set current()

The current() function returns a node set that contains only the current node for the current template. The current()function is specified in the W3C XSLT Recommendation.

For example, the following stylesheet causes the XSLT processor to pass the bookstore node to the outer xsl:for-eachinstruction:

<xsl:stylesheetxmlns:xsl="http://www.w3.org/XSL/Transform" version="1.0" ><xsl:template match="/"><xsl:for-each select="bookstore">

<xsl:for-each select="book[@style=current()/@specialty]"> ...</xsl:for-each>

</xsl:for-each></xsl:template></xsl:stylesheet>

The bookstore node is the current node within the outer xsl:for-each instruction. Within the inner xsl:for-eachinstruction, a book node is the current node.

The current() function in the inner expression returns the bookstore element because the bookstore element is thecurrent node for the inner xsl:for-each instruction. The result of the query contains book elements if the value of theirstyle attribute is the same as the value of the specialty attribute of the bookstore element (novel).

Suppose the select attribute in the inner xsl:for-each instruction specified the dot (.) instead of the current() function:

<xsl:for-each select="book[@style=./@specialty]">

In a query, the dot specifies the context node. This query would return a book if the value of its style attribute was thesame as the value of its specialty attribute.

You can nest xsl:for-each instructions more than one level deep. In any given nested xsl:for-each instruction, thecurrent() function returns the current node for the closest enclosing xsl:for-each instruction.

Related reference



Current node for the current XSLT template

Using the document() function to access other documentsWhen you want to access data in another document during execution of a query, call the document()function.

Format of the document() function

The format for the document() function is:

node-set document(object , node-set ?)

The XPath processor examines the first argument. If it is a single value (that is, it is not a node set) the XPath processorconverts it to a string, if it is not already a string. Separate directory names and the file name with a forward slash (/).

This string must be an absolute path. The XPath processor retrieves the specified document. The new context node is theroot node of this document. Suppose you invoke the document() function and the requested document does not exist. Ifthe invocation is in a stylesheet, the XPath processor returns an empty node set. If the invocation is anywhere else, theXPath processor returns an error message.

When the first argument is a node set

It is possible for the first argument of the document() function to be a node set. In this case, the result is as if you hadcalled the document() function on each node in this node set. That is, the first argument of the document() function iseach node in the node set in turn. The second argument, if there is one, is the same for each iteration of the document()function. This allows you to obtain the contents of multiple documents.

Specifying a second argument

If you specify a second argument, it must be a node set. The XPath processor examines the first node (in the context ofdocument order) in the node set to determine the document that this node belongs to. The XPath processor retrieves thename of the directory that contains this document and appends the relative path from the first argument to the name of thedirectory. This creates an absolute path, and the XPath processor retrieves the specified document.

If there is no second argument, the query must be an expression in an XSLT stylesheet. The XPath processor appends therelative path to the name of the directory that contains the XSLT stylesheet. This allows the query to examine the stylesheetitself.

Related reference

"Example of calling the document() function " on page 233



Example of calling the document() functionSuppose you have the following XML document:

<?xml version="1.0" encoding="UTF-8"?><books>

<bookstore>bookstore1:bookstore1.xml</bookstore><bookstore>bookstore2:bookstore2.xml</bookstore><bookstore>bookstore3:bookstore3.xml</bookstore>

</books>

The following query returns the bookstore elements:

/books/bookstore

Now suppose you pass this query to the document() function as follows:

document(/books/bookstore)

This query returns the root nodes of bookstore1.xml, bookstore2.xml, and bookstore3.xml.

Related reference

"Using the document() function to access other documents" on page 232


Example of calling the document() function

XPath functions quick referenceThe following table lists functions you can call in an XPath query.

ReturnsSourceFunction

Boolean value that is the result of converting an object to a Booleanvalue.

XPathboolean() on page 182

Number that is the smallest integer that is not less than a number youspecify.

XPathceiling() on page 190

Comment nodes.XPathcomment() on page 213

String that concatenates two or more strings you specify.XPathconcat() on page 175

Nodes that contain the specified string.XPathcontains()

Number of nodes in the node-set argument.XPathcount() on page 224

Node for which the current template started its operation.XPathcurrent() on page 226

Root node of the specified document.XSLTdocument()

Boolean value that indicates whether the specified element is supportedby the XSLT processor.

XSLTelement-available()

falseXPathfalse() on page 184

Number that is the largest integer that is not greater than a numberyou specify.

XPathfloor() on page 190

Boolean value that indicates whether the specified function is supportedby the XPath processor.

XSLTfunction-available() on page 226

String that uniquely, temporarily, identifies a node.XSLTgenerate-id() on page 210

Element whose id attribute value matches the specified value.XPathid() on page 208

Node whose key value matches the specified key.XSLTkey() on page 214

Boolean value that indicates whether the language of the node is thelanguage you expect.

XPathlang() on page 185

Number of nodes in the context list.XPathlast() on page 225

Local portion of the node name, excluding the prefix.XPathlocal-name() on page 219

String that contains the tag name of the node, including namespaceinformation, if any.

XPathname() on page 220

URI for the namespace of the node.XPathnamespace-uri() on page 218

All nonattribute nodes.XPathnode() on page 212

String without leading or trailing white space.XPathnormalize-space() on page 177

Boolean value that indicates the opposite of the specified Boolean value.XPathnot() on page 184

Number that is the result of converting the specified argument to anumber.

XPathnumber() on page 187

Position number of the node relative to the context node set.XPathposition() on page 201



Processing instruction nodes. If you specify a literal argument, thisfunction returns a processing instruction if its name matches the literalyou specify.

XPathprocessing- instruction()

Number that is the closest to the argument and is an integer.XPathround()

Boolean value that indicates if a string starts with a particular string.XPathstarts-with() on page 180

String that is the result of converting some object to a string.XPathstring() on page 179

Number of characters in a string you specify.XPathstring-length() on page 176

Substring that is in a particular position within its string.XPathsubstring() on page 174

Substring that appears before a string you specify.XPathsubstring-before() on page 172

Substring that appears after a string you specify.XPathsubstring-after() on page 173

Number that is the sum of the values of the nodes in the specified set.XPathsum() on page 189

Object that represents the specified property.XSLTsystem-property() on page 226

String with some characters replaced by other characters.XPathtranslate() on page 178

true.XPathtrue() on page 184

URI of an unparsed entity with the specified name.XSLTunparsed-entity-uri() on page 223


XPath functions quick reference

XPath syntax quick referenceThis topic provides a quick reference for XPath expression syntax.

Axes

XPath provides the following axes on page 164:

• ancestor

• ancestor-or-self

• attribute

• child

• descendant

• descendant-or-self

• following

• following-sibling

• namespace

• parent

• preceding

• preceding-sibling

• self

Node Tests

XPath provides the following node tests:

• * selects all nodes of the specified name. For the attribute axis, attributes are selected. For the namespace axis,

namespace nodes are selected. For all other axes, element nodes are selected.

• comment() selects all comment nodes.

• element_name selects all element_name nodes.

• node() selects all nodes.

• processing-instruction([" some_literal"]) selects all processing instructions. If some_literal is specified,

processing-instruction() selects all processing instructions with some_literal as their name.

• text() selects all text nodes.



Filters

A filter on page 146 specifies a constraint on a node set with respect to an axis to produce a new node set.

Location Steps

A location step has the following format:

AxisSpecifier::NodeTest[Filter][Filter]...

XPath Expressions

An XPath expression has one of the following formats:

LocationStep[/LocationStep]...FunctionCall()[Filter]/LocationStep[/LocationStep]...(Expression)[Filter]/LocationStep[/LocationStep]...

A function call or an XPath expression in parentheses can appear only at the very beginning of an XPath expression. Anexpression in parentheses always returns a node set. Any function that appears at the beginning of an XPath location stepexpression must return a node set.


XPath syntax quick reference

Abbreviations in XPath expressionsThe following table contains abbreviations used in XPath queries.

DescriptionExample

Selects the para children of the context nodepara

Selects all element children of the context node*

Evaluates all children of the context node and returns those that test true for the

particular node_test

node_test

Selects all para grandchildren of the context node*/para

Selects the first para child of the context nodepara[1]

Selects the last para child of the context nodepara[last()]

Selects the second section of the fifth chapter of the doc child of the context node/doc/chapter[5]/section[2]

Selects para children of the context node that have type attributes with a value of

warning

para[@type="warning"]

Selects the fifth para child of the context node that has a type attribute with a value

of warning

para[@type="warning"][5]

Selects the fifth para child of the context node if that child has a type attribute with

a value of warning

para[5][@type="warning"]

Selects the chapter children of the context node that have one or more title childrenchapter[title]

Selects all para descendants of the document root//para

Selects all para descendants of chapter children of the context nodechapter//para

Selects all item elements that have olist parents//olist/item

Selects the context node.

Selects the para descendants of the context node.//para

Selects the parent of the context node..

Selects all attributes of the context node@*

Selects the name attribute of the context node@name

Selects the name attribute of the parent of the context node../@name

Progress XML Tools Users' Guide

Documents